**版本：V6.2.0**

# token token合约
`cli token -h`  
```
Available Commands:
  burn               Create a burn token transaction
  finish             Create a finish created token transaction
  get_finish_created Get finish created tokens
  get_precreated     Get precreated tokens
  get_token_logs     Get logs of token
  mint               Create a mint token transaction
  precreate          Create a precreated token transaction
  revoke             Create a token revoke transaction
  send_exec          Create a token send to executor transaction
  token_assets       Get token assets
  token_balance      Get token balance of one or more addresses
  transfer           Create a token transfer transaction
  withdraw           Create a token withdraw transaction
```
token合约包括以下功能：  
- token发行  
- token资产操作  
- token相关查询  
- token增发及燃烧

***
## token预创建  
`cli token precreate -h`  
```
Flags:
  -c, --category int32        token category
  -f, --fee float             token transaction fee
  -h, --help                  help for precreate
  -i, --introduction string   token introduction
  -n, --name string           token name
  -a, --owner_addr string     address of token owner
  -p, --price float           token price(mini: 0.0001)
  -s, --symbol string         token symbol
  -t, --total int             total amount of the token
```
创建前，需向创建者地址的token合约打入发行token的费用。  
`cli coins send_exec -e token -a 100`  
以创建者地址签名。  

`cli token precreate -c 1 -i justtest -n cityonchain -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -p 1 -s COC -t 10000 `  
由创建者签名。   
-c为是否支持增发及燃烧的标志位，0为不支持，1为支持；  
-i为token介绍；  
-a为拥有者地址，可与创建者不相同；  
-n为token名称，可重复；  
-p为发行消耗的费用，需存于token合约中；  
-s为token标志，不可重复；  
-t为发行总量，不超过900亿。  
***
## 查询所有预创建的token  
`cli token get_precreated `  
```
{
    "name": "cityonchain",
    "symbol": "COC",
    "introduction": "justtest",
    "total": 10000,
    "price": 1,
    "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
    "creator": "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx",
    "prepareCreateHeight": 2789514,
    "prepareCreateTime": 1564557416,
    "precision": 8,
    "category": 1
}
{
    "name": "共享",
    "symbol": "GX",
    "total": 1000000,
    "owner": "17E7LnoyxGWbiE72vp5HyeiKkBfY83WnBF",
    "creator": "1JzEPPB4j9Z2cBHeHR62JkkGDdy3HmMgse",
    "prepareCreateHeight": 314288,
    "prepareCreateTime": 1525926739,
    "precision": 8
}
```
***
## 撤销预创建的token  
`cli token revoke  -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -s COC `  
由创建者签名。  

***
## 完成已预创建的token  
`cli token finish -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -s COC `   
完成token的创建需要由该链token管理员权限签名。  
***
## 查询所有完成创建的token
`cli token get_finish_created`  
```
{
    "name": "coe",
    "symbol": "COE",
    "total": 30000000,
    "owner": "1PdYcRjesxMCToZwMyvka9DExPQUxkQAUD",
    "creator": "1JzEPPB4j9Z2cBHeHR62JkkGDdy3HmMgse",
    "status": 1,
    "createdHeight": 390842,
    "createdTime": 1527231515,
    "prepareCreateHeight": 390841,
    "prepareCreateTime": 1527231511,
    "precision": 8
}
{
    "name": "cityonchain",
    "symbol": "COC",
    "introduction": "justtest",
    "total": 10000,
    "price": 1,
    "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
    "creator": "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx",
    "status": 1,
    "createdHeight": 2789646,
    "createdTime": 1564558109,
    "prepareCreateHeight": 2789626,
    "prepareCreateTime": 1564558016,
    "precision": 8,
    "category": 1
}
```
*** 
## token转账  
`cli token transfer -a 10 -s COC -t "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs"`  
格式基本同coins币相同，由发送者签名。  

***
## token向指定合约转账  
`cli token send_exec -a 10 -s COC -e trade `  
格式基本同coins币相同，由发送者签名。
***
## 从指定合约取回token  
`cli token withdraw -s COC -e trade -a 5`  
格式基本同coins币相同，由发送者签名。
***
## 查询指定地址在指定合约中的所有token  
`cli token token_assets -a "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs" -e token`  
```
[
    {
        "Token": "YQM",
        "balance": "8.0000",
        "frozen": "0.0000",
        "addr": "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs"
    },
    {
        "Token": "JTT",
        "balance": "7000.0000",
        "frozen": "0.0000",
        "addr": "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs"
    },
    {
        "Token": "LXY",
        "balance": "0.5000",
        "frozen": "0.0000",
        "addr": "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs"
    },
    {
        "Token": "COC",
        "balance": "10.0000",
        "frozen": "0.0000",
        "addr": "18jUpfSuYCk2iQu8ZqB3d6hNWNWA4ty3Xs"
    }
]
```
***
## 查询指定地址在指定合约中某指定token的余额  
`cli token token_balance  -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -e token -s COC`  
```
[
    {
        "Token": "COC",
        "balance": "9985.0000",
        "frozen": "0.0000",
        "addr": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG"
    }
]
```
***
## 查询token完成创建的logs
`cli token get_token_logs -s COC`  
```
{
    "logs": [
        {
            "symbol": "COC",
            "txIndex": "000000278964600001",
            "actionType": 8,
            "txHash": "0xfb7355878a6110199e2184e9c507ea35ac7e589abae806808910a605b2e85283"
        }
    ]
}
```
***
## token燃烧  
`cli token burn -a 1000 -s COC `  
由创建者签名并发送。  

## token增发  
`cli token mint -a 10000 -s COC`  
由创建者签名并发送。

单次增发或燃烧不能超过100亿；增发后的总量也不能超过900亿。  
***
目前版本有两个接口只有rpc，未实现cli命令，包括：  
查询指定创建成功的token；  
查询token相关的交易。   

***
# trade trade合约  
`cli trade -h`  

```
Available Commands:
  buy                     Create a buying token transaction
  buy_limit               Create a buy limit transaction
  buy_order               Show one's buying orders
  revoke                  Create a revoke token transaction
  revoke_buy              Create a revoke buy limit transaction
  sell                    Create a selling token transaction
  sell_market             Create a sell market transaction
  sell_order              Show one's token selling orders
  status_buy_order        Show one's buying orders of tokens
  status_order            Show one's orders with status
  status_sell_order       Show selling orders of the status
  status_token_buy_order  Show token buying orders of a status
  status_token_sell_order Show token selling orders of a status
```
在下面查询相关接口中， 返回的卖单都一个一种格式， 买单也是一种格式， 只在第一个卖单或买单查询中列出其格式， 不重复
卖单买单状态  
状态 1： TradeOrderStatusOnSale, 在售  
状态 2： TradeOrderStatusSoldOut，售完   
状态 3： TradeOrderStatusRevoked， 卖单被撤回  
状态 4： TradeOrderStatusExpired， 订单超时(目前不支持订单超时)  
状态 5： TradeOrderStatusOnBuy， 求购  
状态 6： TradeOrderStatusBoughtOut， 购买完成  
状态 7： TradeOrderStatusBuyRevoked， 买单被撤回  

Buy/Sell ID 在创建交易时不需要带上前缀 “mavl-trade-sell-“ 或 ”mavl-trade-buy-“  

要执行在trade中的交易，首先需要由token合约向trade合约转币：  

`cli token send_exec -e trade -a 1000 -s COC `  
签名并发送。  

## 交易操作
***

## sell 挂卖
`cli trade sell -m 100 -p 0.1 -s COC -t 100 `  
签名并发送  
默认每手为0.01个token；  
-m为最小购买手数；  
-p为每手价格；  
-t为出售的token总量。  

## buy 购买指定卖单的token  
购买前需要在trade合约中有足额的BTY  
`cli coins send_exec -a 700 -e trade`  
签名并发送。  

购买指定卖单的token  
`cli trade buy -c 200 -s aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381 `  
签名并发送。  


## buy_limit 挂买    
因为历史原因，挂买和挂卖的cli命令不对称。  
`cli trade buy_limit -m 1 -p 0.1 -s COC -t 2 `  
签名并发送。  
参数定义与挂卖一致。  

## sell_market 出售token给指定id的挂买单  
`cli trade sell_market -b bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634 -c 200 `  
签名并发送。  

## revoke 撤销挂卖

`cli trade revoke -s aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381 `  
挂单地址签名并发送。  

## revoke_buy 撤销挂买  
`cli trade revoke_buy -b bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634 `   
挂单地址签名并发送。 

***

## 查询操作  
***
## sell_order 根据地址及token标志查询挂卖单  
`cli trade sell_order -s "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -t COC`  
```
{
    "sellOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 10000,
            "tradedBoardlot": 0,
            "buyID": "",
            "status": 1,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0xaa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "height": 2892103,
            "key": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "blockTime": 1565077079,
            "isSellOrder": true
        }
    ]
}
```
默认为0.01个每手，共100个token，故为10000手

## status_sell_order 根据地址及订单状态查询挂买单  
`cli trade status_sell_order -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -s onsale`  
```
{
    "sellOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 10000,
            "tradedBoardlot": 0,
            "buyID": "",
            "status": 1,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0xaa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "height": 2892103,
            "key": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "blockTime": 1565077079,
            "isSellOrder": true
        }
    ]
}
```
-s的状态有onsale, soldout ，revoked三种  



## status_token_sell_order 根据token标志及卖单状态查询指定卖单  
`cli trade status_token_sell_order`  
```
Flags:
  -c, --count int32       order count (default 10)
  -d, --direction int32   direction must be 0 (previous-page) or 1(next-page) (default 1)
  -f, --from string       start from sell id (not required)
  -h, --help              help for status_token_sell_order
  -s, --status string     sell order status (onsale, soldout or revoked)
  -t, --token string      token name
```
`cli trade status_token_sell_order -c 2 -d 1 -s onsale -t COC`  
```
{
    "sellOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 10000,
            "tradedBoardlot": 200,
            "buyID": "",
            "status": 1,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0xaa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "height": 2892103,
            "key": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "blockTime": 1565077079,
            "isSellOrder": true
        }
    ]
}
```
-c为查询数量，默认为10；  
-d为查询方向，默认为1，正向；  
-f为查询起始id，非必需；  
-s为卖单状态，包括onsale，soldout，revoked；  
-t为token标志。  




### buy_order 查询买单  
`cli trade buy_order -t COC -b 1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG`  
```
{
    "buyOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 1,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 200,
            "tradedBoardlot": 0,
            "buyID": "mavl-trade-buy-bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "status": 5,
            "sellID": "",
            "txHash": "0xbba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "height": 2892613,
            "key": "mavl-trade-buy-bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "blockTime": 1565079711,
            "isSellOrder": false
        }
    ]
}
```

## status_buy_order 查询指定地址的指定状态的买单  
`cli trade status_buy_order -b "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx" -s boughtout`  
```
{
    "buyOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 200,
            "tradedBoardlot": 200,
            "buyID": "",
            "status": 6,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0x779f3f9351243a69e865604c77fdd4316eac98e9e559b0e7aeb3b2d9a034fcb7",
            "height": 2892103,
            "key": "0x779f3f9351243a69e865604c77fdd4316eac98e9e559b0e7aeb3b2d9a034fcb7",
            "blockTime": 1565078298,
            "isSellOrder": false
        }
    ]
}
```
※ -s支持onbuy, boughtout or buyrevoked  



## status_token_buy_order 根据token标志及卖单状态查询指定卖单   
`cli trade status_token_buy_order -c 2 -d 1 -s boughtout -t COC`  
```
{
    "buyOrders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 200,
            "tradedBoardlot": 200,
            "buyID": "",
            "status": 6,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0x779f3f9351243a69e865604c77fdd4316eac98e9e559b0e7aeb3b2d9a034fcb7",
            "height": 2892103,
            "key": "0x779f3f9351243a69e865604c77fdd4316eac98e9e559b0e7aeb3b2d9a034fcb7",
            "blockTime": 1565078298,
            "isSellOrder": false
        },
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 1,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 200,
            "tradedBoardlot": 200,
            "buyID": "mavl-trade-buy-bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "status": 6,
            "sellID": "",
            "txHash": "0xbba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "height": 2892613,
            "key": "mavl-trade-buy-bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "blockTime": 1565079711,
            "isSellOrder": false
        }
    ]
}
```
参数定义与查询挂买一致，-s状态包括onbuy, boughtout or buyrevoked。  


## status_order 查询指定地址的指定状态的所有买卖单，可指定配置查询  
`cli trade status_order -h`  
```
Flags:
  -a, --address string    user address
  -c, --count int32       order count (default 10)
  -d, --direction int32   direction must be 0 (previous-page) or 1(next-page) (default 1)
  -f, --from string       start from sell id (not required)
  -h, --help              help for status_order
  -s, --status int32      order status (1: on, 2: done, 3: revoke)
```
`cli trade status_order -a "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -s 1`  
```
{
    "orders": [
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 100,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 10000,
            "tradedBoardlot": 200,
            "buyID": "",
            "status": 1,
            "sellID": "mavl-trade-sell-aa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "txHash": "0xaa376e2b30cc07c4629460d9b520f8f39f003fb12cd87404574f3f9faddc7381",
            "height": 2892103,
            "key": "000000289210300005",
            "blockTime": 1565077079,
            "isSellOrder": true
        },
        {
            "tokenSymbol": "COC",
            "owner": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
            "amountPerBoardlot": "0.0100",
            "minBoardlot": 1,
            "pricePerBoardlot": "0.1000",
            "totalBoardlot": 200,
            "tradedBoardlot": 0,
            "buyID": "mavl-trade-buy-bba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "status": 5,
            "sellID": "",
            "txHash": "0xbba09b6aece714bcbdc66142414a8050d576d4b0c9b7e78b56c93637ae582634",
            "height": 2892613,
            "key": "000000289261300001",
            "blockTime": 1565079711,
            "isSellOrder": false
        }
    ]
}
```
※ -s后1: on, 2: done, 3: revoke  
※ -c可选择输入，为显示的买卖单上限，默认为10；  
-d可选择输入，显示查询的方向，默认为1，即正向，0代表反向。  

# unfreeze 冻结解冻  
`cli unfreeze -h`  
```
Available Commands:
  create        create unfreeze construct
  list          list unfreeze
  show          show construct
  show_withdraw show available withdraw amount of one unfreeze construct
  terminate     terminate construct
  withdraw      withdraw asset from construct
```
## 合约功能说明  
定期解冻合约帮助用户锁定一定量的币，按在指定的规制解冻给受益人，适用于分期付款，分期支付形式的员工激励等情景。    

合约提供了3类操作：  

创建定期解冻合约：创建时需要指定支付的资产和总量，以及定期解冻的形式。  
受益人提币：受益人提走解冻了的资产。  
发起人终止合约： 发起人可以终止合约的履行。  

解冻的形式目前支持两种：  

固定数额解冻：指定时间间隔，解冻固定的资产。  
按剩余量的固定比例解冻：指定时间间隔，按剩余量的固定比例解冻。 这种方式，越到后面解冻的越少。  
## 合约操作  

## create 创建解冻合约  
创建合约前需向unfreeze合约转入操作的代币  
`cli coins send_exec -e unfreeze -a 1000`  
签名并发送。  

创建的解冻合约分为固定数额解冻和按剩余量的固定比例解冻。  
### fix_amount 固定数额解冻：  
`cli unfreeze create  fix_amount -a 0.1 -e coins -s bty -b "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG" -p 60 -t 10 `  
-a为每次解冻的数额；  
-e为资产的归属执行器，支持coins，token，paracross等；  
-s为资产symbol，实测此处bty需小写；  
-b为受益人地址；  
-p为解冻周期，单位为秒；  
--start_ts为选填项，为解冻合约开始时间，以UTC时间戳记录，默认不填为交易打包时间；  
-t为该合约解锁总量。  


### left_proportion 按剩余量的固定比例解冻：  
`cli unfreeze create left_proportion -e coins -s bty -b "17mFjHjMHdtTU31QhFsLGcjNWxvGaVZcPH" -p 60 --ten_thousandth 200 -t 10`   
--ten_thousandth为每次解冻的比例，单位万分之一。  
其余参数与固定数额解冻一致。  

## withdraw 受益人取回解冻部分  
`cli unfreeze withdraw  --id b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8`   
由受益人签名并发送。id为解冻合约的id值。  

## terminate 创建者终止解冻合约  
`cli unfreeze terminate  --id b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8 `  
由创建者签名并发送。  

*** 
## 合约查询  

## show 根据id查询合约信息  
`cli unfreeze show --id b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8`  
```
{
    "unfreezeID": "mavl-unfreeze-b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8",
    "startTime": "1565162228",
    "assetExec": "coins",
    "assetSymbol": "bty",
    "totalCount": "1000000000",
    "initiator": "1KoiQmaFg3DoZr84JehxrEWiR7SorSgbUx",
    "beneficiary": "1KbM8ewfmNzsp1j3GHKz5tGn28ouaAGZAG",
    "remaining": "1000000000",
    "means": "FixAmount",
    "fixAmount": {
        "period": "60",
        "amount": "10000000"
    },
    "terminated": false
}
```

## show_withdraw 根据id查询可取回冻结份额  
`cli unfreeze show_withdraw --id b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8`  
```
{
    "unfreezeID": "mavl-unfreeze-b8cc193e362d889caf1c52be4c9865fc8a9330620e3686794b6e24c6376c78f8",
    "availableAmount": "130000000"
}
```

目前本合约缺少部分查询接口，包括根据创建者地址查询合约id、根据受益人地址查询合约id。需补充。










