# Token 接口


## 1 发行token

### 1.1 生成预创建token 的交易（未签名） CreateRawTokenPreCreateTx

程序员小哥哥正在努力研发中…

### 1.2 生成完成创建token 的交易（未签名） CreateRawTokenFinishTx

程序员小哥哥正在努力研发中…

### 1.3 生成撤销创建token 的交易（未签名） CreateRawTokenRevokeTx

程序员小哥哥正在努力研发中…

### 1.4 查询所有预创建的token GetTokens

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqTokens {
    bool     queryAll          = 1;
    int32    status            = 2;
    repeated string tokens     = 3;
    bool            symbolOnly = 4;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 执行器名称, 主链上查询：token 平行链上查询:user.p.xxxx.token |
| funcName  | string | 是       | 操作名称, 这里固定为 GetTokens                               |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqTokens), status: 0, queryAll: true/false, symbolOnly:选填（true/false） |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message ReplyTokens {
    repeated LocalToken tokens = 1;
}
message LocalToken {
    string name                = 1;
    string symbol              = 2;
    string introduction        = 3;
    int64  total               = 4;
    int64  price               = 5;
    string owner               = 6;
    string creator             = 7;
    int32  status              = 8;
    int64  createdHeight       = 9;
    int64  createdTime         = 10;
    int64  prepareCreateHeight = 11;
    int64  prepareCreateTime   = 12;
    int32  precision           = 13;
    // 如果需要这个项可以单独做一个域存储
    int64 totalTransferTimes = 14;
    int64 revokedHeight      = 15;
    int64 revokedTime        = 16;
    int32 category           = 17;
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int64  | 发行总量                                          |
| price               | int64  | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | int32  | 0表示 TokenStatusPreCreated 状态                  |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

### 1.5 查询所有创建成功的token GetTokens

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqTokens {
    bool     queryAll          = 1;
    int32    status            = 2;
    repeated string tokens     = 3;
    bool            symbolOnly = 4;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName  | string | 是       | 操作名称, 这里固定为 GetTokens                               |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqTokens) status: 1, queryAll 是否查询所有: true/false, symbolOnly:是否只返回symbol值 选填（true/false） |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message ReplyTokens {
    repeated LocalToken tokens = 1;
}
message LocalToken {
    string name                = 1;
    string symbol              = 2;
    string introduction        = 3;
    int64  total               = 4;
    int64  price               = 5;
    string owner               = 6;
    string creator             = 7;
    int32  status              = 8;
    int64  createdHeight       = 9;
    int64  createdTime         = 10;
    int64  prepareCreateHeight = 11;
    int64  prepareCreateTime   = 12;
    int32  precision           = 13;
    // 如果需要这个项可以单独做一个域存储
    int64 totalTransferTimes = 14;
    int64 revokedHeight      = 15;
    int64 revokedTime        = 16;
    int32 category           = 17;
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int    | 发行总量                                          |
| price               | int    | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | int    | 1表示 Token已经完成创建状态                       |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

### 1.6 查询指定创建成功的token GetTokenInfo

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqString {
    string data = 1;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName  | string | 是       | 操作名称, 这里固定为 GetTokenInfo                            |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqString), token的Symbol                      |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message LocalToken {
    string name                = 1;
    string symbol              = 2;
    string introduction        = 3;
    int64  total               = 4;
    int64  price               = 5;
    string owner               = 6;
    string creator             = 7;
    int32  status              = 8;
    int64  createdHeight       = 9;
    int64  createdTime         = 10;
    int64  prepareCreateHeight = 11;
    int64  prepareCreateTime   = 12;
    int32  precision           = 13;
    // 如果需要这个项可以单独做一个域存储
    int64 totalTransferTimes = 14;
    int64 revokedHeight      = 15;
    int64 revokedTime        = 16;
    int32 category           = 17;
}
```

**参数说明：**

| 参数                | 类型   | 说明                                              |
| :------------------ | :----- | :------------------------------------------------ |
| name                | string | token的全名，最大长度是128个字符                  |
| symbol              | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| introduction        | string | token介绍，最大长度为1024个字节                   |
| total               | int    | 发行总量                                          |
| price               | string | 发行该token愿意承担的费用                         |
| ownerAddr           | string | token拥有者地址                                   |
| creator             | string | 预创建人地址                                      |
| status              | string | 1. 0表示 TokenStatusCreated 状态                  |
| createdHeight       | int64  |                                                   |
| createdTime         | int64  |                                                   |
| prepareCreateHeight | int64  |                                                   |
| prepareCreateTime   | int64  |                                                   |
| precision           | int32  |                                                   |
| totalTransferTimes  | int64  |                                                   |
| revokedHeight       | int64  |                                                   |
| revokedTime         | int64  |                                                   |
| category            | int32  | -                                                 |

## 2 token操作

### 2.1 token转账 SendToAddress

**调用接口**

```
rpc SendToAddress(ReqWalletSendToAddress) returns (ReplyHash) {}
```

**参数：**

```
message ReqWalletSendToAddress {
    string from        = 1;
    string to          = 2;
    int64  amount      = 3;
    string note        = 4;
    bool   isToken     = 5;
    string tokenSymbol = 6;
}
```

**参数说明：**

| 参数        | 类型   | 说明                                              |
| :---------- | :----- | :------------------------------------------------ |
| from        | string | 来源地址                                          |
| to          | string | 发送到地址                                        |
| amount      | int64  | 发送金额                                          |
| note        | string | 备注                                              |
| isToken     | bool   | 发送的是否是token，false 的情况下发送的bty        |
| tokenSymbol | string | token标记符，最大长度是16个字符，且必须为大写字符 |

**返回数据：**

```
message ReplyHash {
    bytes hash = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明         |
| :--- | :---- | :----------- |
| hash | bytes | 返回结果哈希 |

### 2.2 token提币 SendToAddress

**调用接口**

```
rpc SendToAddress(ReqWalletSendToAddress) returns (ReplyHash) {}
```

**参数：**

```
message ReqWalletSendToAddress {
    string from        = 1;
    string to          = 2;
    int64  amount      = 3;
    string note        = 4;
    bool   isToken     = 5;
    string tokenSymbol = 6;
}
```

**参数说明：**

| 参数        | 类型   | 说明                                              |
| :---------- | :----- | :------------------------------------------------ |
| from        | string | token提币地址                                     |
| to          | string | token保存的合约地址                               |
| amount      | int64  | 发送金额，填写负数                                |
| note        | string | 备注                                              |
| isToken     | bool   | 发送的是否是token，false 的情况下发送的bty        |
| tokenSymbol | string | token标记符，最大长度是16个字符，且必须为大写字符 |

**返回数据：**

```
message ReplyHash {
    bytes hash = 1;
}
```

**参数说明：**

| 参数 | 类型  | 说明         |
| :--- | :---- | :----------- |
| hash | bytes | 返回结果哈希 |

## 3 token查询

### 3.3 查询地址下的token合约下的token资产 GetAccountTokenAssets

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqAccountTokenAssets {
    string address = 1;
    string execer  = 2;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName  | string | 是       | 操作名称, 这里固定为 GetAccountTokenAssets                   |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqAccountTokenAssets) address:查询的地址, execer: token |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message ReplyAccountTokenAssets {
    repeated TokenAsset tokenAssets = 1;
}
message TokenAsset {
    string  symbol  = 1;
    Account account = 2;
}
message Account {
    string addr    = 1;
    string frozen  = 2;
    string balance = 3;
}
```

**参数说明：**

| 参数    | 类型   | 说明                                              |
| :------ | :----- | :------------------------------------------------ |
| symbol  | string | token标记符，最大长度是16个字符，且必须为大写字符 |
| account | string | token 对应地址的帐号信息                          |
| balance | int    | 帐号的可用余额                                    |
| frozen  | int    | 帐号中冻结余额                                    |
| addr    | string | 帐号的地址                                        |

### 3.4 查询token相关的交易 GetTxByToken

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqTokenTx {
    string symbol = 1;
    //表示取所有/from/to/其他的hash列表
    int32  flag      = 2;
    int32  count     = 3;
    int32  direction = 4;
    int64  height    = 5;
    int64  index     = 6;
    string addr      = 7;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName  | string | 是       | 操作名称, 这里固定为 GetTxByToken                            |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqTokenTx) symbol: token标记符，count: 交易的数量，flag /height / index / direction : 分页相关参数，addr: 地址 |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message ReplyTxInfos {
    repeated ReplyTxInfo txInfos = 1;
}
message ReplyTxInfo {
    bytes    hash         = 1;
    int64    height       = 2;
    int64    index        = 3;
    repeated Asset assets = 4;
}
message Asset {
    string exec   = 1;
    string symbol = 2;
    int64  amount = 3;
}
```

**参数说明：**

| 参数    | 类型          | 说明                               |
| :------ | :------------ | :--------------------------------- |
| txInfos | []ReplyTxInfo | 交易列表，包括交易hash，资产信息等 |

## 4 token的增发和燃烧

### 4.1 token的增发 CreateRawTokenMintTx

程序员小哥哥正在努力研发中…

### 4.2 token的燃烧 CreateRawTokenBurnTx

程序员小哥哥正在努力研发中…

### 4.3 查询token 的变化记录 GetTokenHistory

**调用接口**

```
rpc QueryChain(ChainExecutor) returns (Reply) {}
```

**参数：**

```
message ChainExecutor {
    string driver    = 1;
    string funcName  = 2;
    bytes  stateHash = 3;
    bytes  param     = 4;
    bytes  extra     = 5;
}
message ReqString {
    string data = 1;
}
```

**参数说明：**

| 参数      | 类型   | 是否必须 | 说明                                                         |
| :-------- | :----- | :------- | :----------------------------------------------------------- |
| driver    | bytes  | 是       | 主链上查询：token 平行链上查询:user.p.xxxx.token             |
| funcName  | string | 是       | 操作名称, 这里固定为 GetTokenHistory                         |
| stateHash | bytes  | 否       | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| param     | bytes  | 是       | types.Encode(&ReqString) data : token标记符                  |
| extra     | bytes  | 否       | 扩展字段，用于额外的用途                                     |

**返回数据：**

```
message ReplyTokenLogs {
    repeated LocalLogs logs = 1;
}
message LocalLogs {
    string symbol     = 1;
    string txIndex    = 2;
    int32  actionType = 3;
    string txHash     = 4;
}
```

**参数说明：**

| 参数 | 类型        | 说明                                                         |
| :--- | :---------- | :----------------------------------------------------------- |
| logs | []LocalLogs | txHash 交易hash，symbol token标记符, 具体信息可以通过交易hash查询, actionType: 8 是token创建， 12 是增发， 13 是燃烧 |

## 5 token 的转币 提币等

1. [参考链接](../jsonRPCInterface/transactionAPI.md#111-构造资产交易-createrawtransaction)