## 区块链接口

### 1 获取版本 Version

**请求报文：**

```
{    "jsonrpc":"2.0",    "id":int32    "method":"Chain33.Version",    "params":[],}
```

**参数说明：**
nil

**响应报文：**

```
{
    "id":int32,
    "result":{
        "title":"string",
        "app":"string",
        "chain33":"string",
        "localDb":"string"
    },
    "error":null
}
```

**参数说明：**

| 参数           | 类型   | 说明                                        |
| :------------- | :----- | :------------------------------------------ |
| result.title   | string | 区块链名，该节点chain33.toml中配置的title值 |
| result.app     | string | 应用app的版本                               |
| result.chain33 | string | 版本信息，版本号-GitCommit(前八个字符)      |
| result.localDb | string | localdb版本号                               |

**示例：**

Request:

```
{
    "method": "Chain33.Version",
    "params": [],
    "id": 0,
}
```

Response:

```
{
    "id":0,
    "result":{
        "title":"chain33",
        "app":"1.0.0",
        "chain33":"6.0.2-46bd6ab9",
        "localDb":"1.0.0"
    },
    "error":null
}
```

### 2 获取区间区块 GetBlocks

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32
    "method": "Chain33.GetBlocks",
    "params": [
        {
            "start": int32,
            "end": int32,
            "isDetail": bool
        }
    ],
}
```

**参数说明：**

| 参数     | 类型  | 说明                 |
| :------- | :---- | :------------------- |
| start    | int64 | 开始区块高度         |
| end      | int64 | 结束区块高度         |
| isDetail | bool  | 是否打印区块详细信息 |

**响应报文：**

```
{
    "id": 0,
    "result": {
        "items": [
            {
                "block": {
                    "version": int64,
                    "parentHash": "string",
                    "txHash": "string",
                    "stateHash": "string",
                    "height": int64,
                    "blockTime": int64,
                    "txs": [
                        {
                            "execer": "string",
                            "payload": {
                                "genesis": {
                                    "amount": "string",
                                    "returnAddress": "string"
                                },
                                "ty": int32
                            },
                            "rawPayload": "string",
                            "signature": {
                                "ty": int32,
                                "pubkey": "string",
                                "signature": "string"
                            },
                            "fee": int64,
                            "feefmt": "string",
                            "expire": int64,
                            "nonce": int64,
                            "from": "string",
                            "to": "string"
                        }
                    ]
                },
                "recipts": {
                    "ty":int32,
                    "tyName":"string",
                    "logs":{
                        "ty":int32,
                        "tyName":"string",
                        "log":"string",
                        "rawLog":"string"
                    }
                }
            },
            {
                "block": {
                    "version": int64,
                    "parentHash": "string",
                    "txHash": "string",
                    "stateHash": "string",
                    "height": int64,
                    "blockTime": int64,
                    "txs": [
                        {
                            "execer": "string",
                            "payload": {
                                "topic": "",
                                "content": "string"
                            },
                            "rawPayload": "string",
                            "signature": {
                                "ty": int32,
                                "pubkey": "string",
                                "signature": "string"
                            },
                            "fee": int64,
                            "feefmt": "string",
                            "expire": int64,
                            "nonce": int64,
                            "from": "string",
                            "to": "string"
                        }
                    ]
                },
                "recipts": null
            }
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数                   | 类型   | 说明                                                         |
| :--------------------- | :----- | :----------------------------------------------------------- |
| items                  | json   | 区块数组；包含区块信息；                                     |
| items.block            | json   | 区块的信息                                                   |
| items.block.version    | int64  | 区块版本                                                     |
| items.block.parentHash | string | 上一区块的部分header信息序列化后的哈希值                     |
| items.block.txHash     | string | 所有交易序列化后的哈希值                                     |
| items.block.stateHash  | string | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| items.block.txs        | json   | 交易信息                                                     |
| items.recipts          | json   | 交易执行结果信息                                             |

**示例：**

Request:

```
{
    "id": 0,
    "method": "Chain33.GetBlocks",
    "params": [
        {
            "start": 0,
            "end": 10,
            "isDetail": false
        }
    ]
}
```

Response:

```
{
    "id": 0,
    "result": {
        "items": [
            {
                "block": {
                    "version": 0,
                    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
                    "txHash": "0xe34a933c5abf350db4db5122abbf43f6a54da2dbd67d214f67362c36bd70d23e",
                    "stateHash": "0x2863c8dbc7fe3146c8d4e7acf2b8bbe4666264d658356e299e240f462a382a51",
                    "height": 0,
                    "blockTime": 1514533394,
                    "txs": [
                        {
                            "execer": "coins",
                            "payload": {
                                "genesis":{
                                    "amount": "10000000000000000",
                                    "returnAddress": ""
                                },
                                "ty": 2
                            },
                            "rawPayload": "0x1802120910808084fea6dee111",
                            "signature": {
                                "ty": 0,
                                "pubkey": "",
                                "signature": ""
                            },
                            "fee": 0,
                            "feefmt": "0.0000",
                            "expire": 0,
                            "nonce": 0,
                            "from": "1HT7xU2Ngenf7D4yocz2SAcnNLW7rK8d4E",
                            "to": "14KEKbYtKKQm4wMthSK9J4La4nAiidGozt"
                        }
                    ]
                },
                "recipts": null
            },
            {
                "block": {
                    "version": 0,
                    "parentHash": "0xfd39dbdbd2cdeb9f34bcec3612735671b35e2e2dbf9a4e6e3ed0c34804a757bb",
                    "txHash": "0x2af1d0131f37ded31eee9bd16630af761b7299ee53a16ebe8f15dfdf1b9d2b0f",
                    "stateHash": "0x2863c8dbc7fe3146c8d4e7acf2b8bbe4666264d658356e299e240f462a382a51",
                    "height": 1,
                    "blockTime": 1543920166,
                    "txs": [
                        {
                            "execer": "user.write",
                            "payload": {
                                "topic": "",
                                "content": "NDtZZxe"
                            },
                            "rawPayload": "0x4e44745a5a7865",
                            "signature": {
                                "ty": 1,
                                "pubkey": "0x030f9e532cd668a0b32dd96cac3325ed8eddc46901535c20fb2253acea34213eaf",
                                "signature": "0x3045022100b8364f68d8bd35b66b3a346239ec7fddbec3b6c37aeee6694153d724f693e6bd02200e0c5c824c088bd24b180fc9da4f7c569929d20141e66fdab820f731f5db00d0"
                            },
                            "fee": 1000000,
                            "feefmt": "0.0100",
                            "expire": 4611686018427388000,
                            "nonce": 0,
                            "from": "1MoMByk8Jp9qB97VJQ1mjPk23EqheSpKgg",
                            "to": "1DNaSDRG9RD19s59meAoeN4a2F6RH97fSo"
                        }
                    ]
                },
                "recipts": null
            }
        ]
    },
    "error": null
}
```

### 3 获取最新的区块头 GetLastHeader

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GetLastHeader",
    "params":[]
}
```

**参数说明：**

| 参数 | 类型 | 是否必填 | 说明 |
| :--- | :--- | :------- | :--- |
|      |      |          |      |

**响应报文：**

```
{
    "id": int32,
    "result": {
        "version": int64,
        "parentHash": "string",
        "txHash": "string",
        "stateHash": "string",
        "height": int64,
        "blockTime": int64,
        "txCount": int64,
        "hash": "string",
        "difficulty": uint32
    },
    "error": null
}
```

**参数说明：**

| 参数       | 类型   | 说明                                                         |
| :--------- | :----- | :----------------------------------------------------------- |
| version    | int64  | 区块版本                                                     |
| parentHash | string | 上一区块的部分header信息序列化后的哈希值                     |
| txHash     | string | 所有交易序列化后的哈希值                                     |
| stateHash  | string | 所有交易在对应的执行器执行后写入KVDB中重新计算得到的新state的哈希值 |
| difficulty | uint32 | 困难值                                                       |

**示例：**

Request:

```
{
    "method": "Chain33.GetLastHeader",
    "params": [],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "version": 0,
        "parentHash": "0xfd39dbdbd2cdeb9f34bcec3612735671b35e2e2dbf9a4e6e3ed0c34804a757bb",
        "txHash": "0x2af1d0131f37ded31eee9bd16630af761b7299ee53a16ebe8f15dfdf1b9d2b0f",
        "stateHash": "0x2863c8dbc7fe3146c8d4e7acf2b8bbe4666264d658356e299e240f462a382a51",
        "height": 1,
        "blockTime": 1543920166,
        "txCount": 1,
        "hash": "0x8a7cf829cd993a23933c8b6914e6d1e560c17c50ce224aa6639ecee950699dff",
        "difficulty": 523239423
    },
    "error": null
}
```

### 4 获取区间区块头 GetHeaders

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.GetHeaders",
    "params": [
        {
            "start": int64,
            "end": int64,
            "isDetail": bool
        }
    ]
}
```

**参数说明：**

| 参数     | 类型     | 说明                 |
| :------- | :------- | :------------------- |
| start    | int64    | 开始区块高度         |
| end      | int64    | 结束区块高度         |
| isDetail | bool     | 是否打印区块详细信息 |
| pid      | []string | peer列表             |

**响应报文：**

```
{
    "id": 0,
    "result": {
        "items": [
            {
                "version": int64,
                "parentHash": "string",
                "txHash": "string",
                "stateHash": "string",
                "height": int64,
                "blockTime": int64,
                "txCount": int64,
                "hash": "string",
                "difficulty": uint32
            }
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数  | 类型 | 说明           |
| :---- | :--- | :------------- |
| items | json | 区块头信息数组 |

### 5 获取区块哈希值 GetBlockHash

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.GetBlockHash",
    "params": [
        {
            "height": int64
        }
    ]
}
```

**参数说明：**

| 参数   | 类型  | 说明                     |
| :----- | :---- | :----------------------- |
| height | int64 | 需要获取哈希的区块的高度 |

**响应报文：**

```
{
    "id": int32,
    "result": {
        "hash": "string"
    },
    "error": null
}
```

**参数说明：**

| 参数 | 类型   | 说明       |
| :--- | :----- | :--------- |
| hash | string | 区块哈希值 |

**示例：**

Request:

```
{
    "method": "Chain33.GetBlockHash",
    "params": [
        {
            "height": 1
        }
    ],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "hash": "0x8a7cf829cd993a23933c8b6914e6d1e560c17c50ce224aa6639ecee950699dff"
    },
    "error": null
}
```

### 6 获取区块的详细信息 GetBlockOverview

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method": "Chain33.GetBlockOverview",
    "params": [
        {
            "hash":"string"
        }
    ]
}
```

**参数说明：**

| 参数 | 类型   | 说明       |
| :--- | :----- | :--------- |
| hash | string | 区块哈希值 |

**响应报文：**

```
{
    "id": 0,
    "result": {
        "head": {
            "version": int64,
            "parentHash": "string",
            "txHash": "string",
            "stateHash": "string",
            "height": int64,
            "blockTime": int64,
            "txCount": int64,
            "hash": "string",
            "difficulty": uint32
        },
        "txCount": int64,
        "txHashes": [
            "string"
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数     | 类型 | 说明                               |
| :------- | :--- | :--------------------------------- |
| head     | json | 区块头信息                         |
| txHashes | json | 交易哈希数组，包含每个交易的哈希值 |

### 7 通过区块哈希获取区块信息 GetBlockByHashes

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.GetBlockByHashes",
    "params": [
        {
            "hashes": [
                "string"
            ],
            "disableDetail": bool
        }
    ]
}
```

**参数说明：**

| 参数          | 类型     | 说明                 |
| :------------ | :------- | :------------------- |
| hashes        | []string | 区块哈希列表         |
| disableDetail | bool     | 是否打印区块详细信息 |

**响应报文：**

```
{
    "id": 0,
    "result": {
        "items": [
            {
                "block": {
                    "version": 0,
                    "parentHash": "string",
                    "txHash": "string",
                    "stateHash": "string",
                    "height": int64,
                    "blockTime": int64,
                    "txs": [
                        {
                            "execer": "string",
                            "payload": {
                                "genesis": {
                                    "amount": "string",
                                    "returnAddress": "string"
                                },
                                "ty": int32
                            },
                            "rawPayload": "string",
                            "signature": {
                                "ty": int32,
                                "pubkey": "string",
                                "signature": "string"
                            },
                            "fee": int64,
                            "feefmt": "string",
                            "expire": int64,
                            "nonce": int64,
                            "from": "string",
                            "to": "string",
                            "hash": "string"
                        }
                    ]
                },
                "recipts": [
                    {
                        "ty": int32,
                        "tyName": "string",
                        "logs": [
                            {
                                "ty": int32,
                                "tyName": "string",
                                "log": {
                                    "prev": {
                                        "currency": int32,
                                        "balance": "string",
                                        "frozen": "string",
                                        "addr": "string"
                                    },
                                    "current": {
                                        "currency": int32,
                                        "balance": "string",
                                        "frozen": "string",
                                        "addr": "string"
                                    }
                                },
                                "rawLog": "string"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数          | 类型 | 说明                   |
| :------------ | :--- | :--------------------- |
| items         | json | 区块数组；包含区块信息 |
| items.block   | json | 区块的信息             |
| items.recipts | json | 交易执行结果信息       |

### 8 获取区块的序列信息 GetBlockSequences

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.GetBlockSequences",
    "params": [
        {
            "start": int64,
            "end": int64,
            "isDetail": bool
        }
    ]
}
```

**参数说明：**

| 参数     | 类型  | 说明                 |
| :------- | :---- | :------------------- |
| start    | int64 | 开始区块高度         |
| end      | int64 | 结束区块高度         |
| isDetail | bool  | 是否打印区块详细信息 |

**响应报文：**

```
{
    "id": 0,
    "result": {
        "blkseqInfos": [
            {
                "hash": "string",
                "type": int64
            }
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数 | 类型   | 说明                               |
| :--- | :----- | :--------------------------------- |
| hash | string | 区块哈希值                         |
| type | int64  | 区块类型，1：增加区块，2：删除区块 |

**示例：**

Request:

```
{
    "method": "Chain33.GetBlockSequences",
    "params": [
        {
            "start": 0,
            "end": 0,
            "isDetail": false
        }
    ],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "blkseqInfos": [
            {
                "hash": "0xfd39dbdbd2cdeb9f34bcec3612735671b35e2e2dbf9a4e6e3ed0c34804a757bb",
                "type": 1
            }
        ]
    },
    "error": null
}
```

### 9 获取最新区块的序列号 GetLastBlockSequence

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.GetLastBlockSequence",
    "params": []
}
```

**参数说明：**

| 参数 | 类型 | 是否必填 | 说明 |
| :--- | :--- | :------- | :--- |
|      |      |          |      |

**响应报文：**

```
{
    "id":int32,
    "result":int64,
    "error":null
}
```

**参数说明：**

| 参数   | 类型  | 说明       |
| :----- | :---- | :--------- |
| result | int64 | 区块序列号 |

**示例：**

Request:

```
{
    "method": "Chain33.GetLastBlockSequence",
    "params": [],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": 0,
    "error": null
}
```

### 10 注册区块（区块头）推送服务或者合约回执推送服务 AddPushSubscribe

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id": int32,
    "method": "Chain33.AddPushSubscribe",
    "params": [
        {
            "name": "string",
            "URL": "string",
            "encode": "string",
            "lastSequence": int64,
            "lastHeight": int64,
            "lastBlockHash": "string",
            "type": int32,
            "contract": map[string]bool
        }
    ]
}
```

**参数说明：**

| 参数          | 类型            | 说明                                                         |
| :------------ | :-------------- | :----------------------------------------------------------- |
| name          | string          | 注册名称，长度不能超过 128；一旦通过 name 完成注册，其他订阅用户就不能使用相同的名字进行注册。 |
| URL           | string          | 接受推送的 URL，长度不能超过 1024； 当 name 相同，URL 不同，提示该 name 已经被注册，注册失败； 当 name 相同，URL 相同 如果推送已经停止，则重新开始推送，如果推送正常，则继续推送。 |
| encode        | string          | 数据编码方式；json 或者 proto                                |
| lastSequence  | int64           | 推送开始序列号                                               |
| lastHeight    | int64           | 推送开始高度                                                 |
| lastBlockHash | string          | 推送开始块哈希                                               |
| last三个参数  |                 | 必须保持一致，不然会出错； 都不填，或者 lastSequence=0，lastHeight=0，lastBlockHash=“”，从零开始推送。 |
| type          | int32           | 推送的数据类型；0:代表区块；1:代表区块头信息；2：代表交易回执 |
| contract      | map[string]bool | 订阅的合约名称，当type=2的时候起效，比如“coins=true”         |

**响应报文：**

```
{
    "id":int32,
    "result": {
        "isOK": bool,
        "msg": "string"
    },
    "error": null
}
```

**参数说明：**

| 参数 | 类型   | 说明         |
| :--- | :----- | :----------- |
| isOK | bool   | 是否设置成功 |
| msg  | string | 错误信息     |

**示例：**

Request:

```
{
    "method": "Chain33.AddPushSubscribe",
    "params": [
        {
            "name": "test",
            "URL": "http://127.0.0.1:9999/",
            "encode": "json",
            "type": 0
        }
    ],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "isOK": true,
        "msg": ""
    },
    "error": null
}
```

### 11 列举推送服务 ListPushes

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.ListPushes",
    "params":[]
}

```

**参数说明：**

| 参数 | 类型 | 是否必填 | 说明 |
| :--- | :--- | :------- | :--- |
|      |      |          |      |

**响应报文：**

```
{
    "id":int32,
    "result": {
        "items": [
            {
                "name":"string",
                "URL":"string",
                "encode":"string"
                "lastSequence": int64,
                "lastHeight": int64,
                "lastBlockHash": "string",
                "type": int32,
                "contract": map[string]bool
            }
        ]
    },
    "error": null
}
```

**参数说明：**

| 参数  | 类型 | 说明         |
| :---- | :--- | :----------- |
| items | json | 推送服务列表 |

**示例：**

Request:

```
{
    "method": "Chain33.ListPushes",
    "params": [],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "items": [
            {
                "name": "test",
                "URL": "http://127.0.0.1:9999/",
                "encode": "json",
                "lastSequence": 100,
                "lastHeight": 100,
                "lastBlockHash": "0xe15fb9d8ee52be4654d7250266cdf8c86e84f6d0518ad81699b3d81e71fc3828",
                "type": 1,
                "contract": {}
            }
        ]
    },
    "error": null
}
```

### 12 获取某推送服务最新序列号的值 GetPushSeqLastNum

**请求报文：**

```
{
    "jsonrpc":"2.0",
    "id":int32,
    "method":"Chain33.GetPushSeqLastNum",
    "params": [
        {
            "data":"string"
        }
    ]
}
```

**参数说明：**

| 参数 | 类型   | 说明       |
| :--- | :----- | :--------- |
| data | string | 推送服务名 |

**响应报文：**

```
{
    "id":int32,
    "result": {
        "data": int64
    },
    "error": null
}
```

**参数说明：**

| 参数 | 类型   | 说明   |
| :--- | :----- | :----- |
| data | string | 序列号 |

**示例：**

Request:

```
{
    "method": "Chain33.GetPushSeqLastNum",
    "params": [
        {
            "data": "test"
        }
    ],
    "id": 0
}
```

Response:

```
{
    "id": 0,
    "result": {
        "data": -1
    },
    "error": null
}
```

