# 1 区块链接口
[TOC]
## 1.1  获取版本

**请求报文：**

```json
{
	"method": "Chain33.Version",
	"params": [
		null
	],
	"id": int32,
}
```

**参数说明：**

无参数

**响应报文：**

```json
{
    "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:
```json
{
	"method": "Chain33.Version",
	"params": [
		null
	],
	"id": 0,
}
```
Response:
```json
{
    "id":0,
    "result":{
        "title":"chain33",
        "app":"1.0.0",
        "chain33":"6.0.2-46bd6ab9",
        "localDb":"1.0.0"
        },
    "error":null
}
```

## 1.2 获取区间区块

**请求报文：**

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

**参数说明：**

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

**响应报文：**

```json
{
  "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:
```json
{
	"method": "Chain33.GetBlocks",
	"params": [
		{
			"start": 0,
			"end": 10,
			"isDetail": false
		}
	],
	"id": 0
}
```
Response:
```json
{
  "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
}
```

## 1.3 获取最新的区块头

**请求报文：**

```json
{
	"method": "Chain33.GetLastHeader",
	"params": [
		null
	],
	"id": int32
}
```

**参数说明：**

无

**响应报文：**

```json
{
  "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:
```json
{
	"method": "Chain33.GetLastHeader",
	"params": [
		null
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "version": 0,
    "parentHash": "0xfd39dbdbd2cdeb9f34bcec3612735671b35e2e2dbf9a4e6e3ed0c34804a757bb",
    "txHash": "0x2af1d0131f37ded31eee9bd16630af761b7299ee53a16ebe8f15dfdf1b9d2b0f",
    "stateHash": "0x2863c8dbc7fe3146c8d4e7acf2b8bbe4666264d658356e299e240f462a382a51",
    "height": 1,
    "blockTime": 1543920166,
    "txCount": 1,
    "hash": "0x8a7cf829cd993a23933c8b6914e6d1e560c17c50ce224aa6639ecee950699dff",
    "difficulty": 523239423
  },
  "error": null
}
```

## 1.4 获取区间区块头

**请求报文：**

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

**参数说明：**

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

**响应报文：**
```json
{
  "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|区块头信息数组|

## 1.5 获取区块哈希值

**请求报文：**

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

**参数说明：**

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

**响应报文：**

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

**参数说明：**

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

**示例：**

Request:
```json
{
	"method": "Chain33.GetBlockHash",
	"params": [
		{
			"height": 1
		}
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "hash": "0x8a7cf829cd993a23933c8b6914e6d1e560c17c50ce224aa6639ecee950699dff"
  },
  "error": null
}
```

## 1.6 获取区块的详细信息

**请求报文：**

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

**参数说明：**

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

**响应报文：**

```json
{
  "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|交易哈希数组，包含每个交易的哈希值|

## 1.7 通过区块哈希获取区块信息

**请求报文：**

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

**参数说明：**

|参数|类型|说明|
|----|----|----|
|hashs|json|区块哈希列表|
|disableDetail|bool|是否打印区块详细信息|

**响应报文：**

```json
{
  "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|交易执行结果信息|

## 1.8 获取区块的序列信息

**请求报文：**

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

**参数说明：**

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

**响应报文：**

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

**参数说明：**

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

**示例：**

Request:
```json
{
	"method": "Chain33.GetBlockSequences",
	"params": [
		{
			"start": 0,
			"end": 0,
			"isDetail": false
		}
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "blkseqInfos": [
      {
        "hash": "0xfd39dbdbd2cdeb9f34bcec3612735671b35e2e2dbf9a4e6e3ed0c34804a757bb",
        "type": 1
      }
    ]
  },
  "error": null
}
```

## 1.9 获取最新区块的序列号

**请求报文：**

```json
{
	"method": "Chain33.GetLastBlockSequence",
	"params": [
		null
	],
	"id": int32
}
```

**参数说明：**

无

**响应报文：**

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

**参数说明：**

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

**示例：**

Request:
```json
{
	"method": "Chain33.GetLastBlockSequence",
	"params": [
		null
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": 0,
  "error": null
}
```

## 1.10 增加区块序列号变更回调

**请求报文：**

```json
{
	"method": "Chain33.AddSeqCallBack",
	"params": [
		{
			"name": "string",
			"URL": "string",
			"encode": "string"
		}
	],
	"id": int32
}
```

**参数说明：**

|参数|类型|说明|
|----|----|----|
|name|string|回调名称，长度不能超过128,|
|URL|string|序列号变化通知的URL，长度不能超过1024；当name相同，URL为空时取消通知|
|encode|string|数据编码方式；json 或者 proto|

**响应报文：**

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

**参数说明：**

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

**示例：**

Request:
```json
{
	"method": "Chain33.AddSeqCallBack",
	"params": [
		{
			"name": "test",
			"URL": "http://127.0.0.1:9999/",
			"encode": "json"
		}
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "isOK": true,
    "msg": ""
  },
  "error": null
}
```

## 1.11 列举区块序列号回调

**请求报文：**
```json
{
	"method": "Chain33.ListSeqCallBack",
	"params": [
		null
	],
	"id": 0
}
```

**参数说明：**

无

**响应报文：**

```json
{
  "id": 0,
  "result": {
    "items": [
      {
        "name": "string",
        "URL": "string",
        "encode": "string"
      }
    ]
  },
  "error": null
}
```

**参数说明：**

|参数|类型|说明|
|----|----|----|
|items|json|回调信息列表|

**示例：**

Request:
```json
{
	"method": "Chain33.ListSeqCallBack",
	"params": [
		null
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "items": [
      {
        "name": "test",
        "URL": "http://127.0.0.1:9999/",
        "encode": "json"
      }
    ]
  },
  "error": null
}
```

## 1.12 获取某回调最新序列号的值

**请求报文：**

```json
{
	"method": "Chain33.GetSeqCallBackLastNum",
	"params": [
		{
			"data": "string"
		}
	],
	"id": 0
}
```

**参数说明：**

|参数|类型|说明|
|----|----|----|
|data|string|回调名|

**响应报文：**

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

**参数说明：**

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

**示例：**

Request:
```json
{
	"method": "Chain33.GetSeqCallBackLastNum",
	"params": [
		{
			"data": "test"
		}
	],
	"id": 0
}
```
Response:
```json
{
  "id": 0,
  "result": {
    "data": -1
  },
  "error": null
}
```