增加区块链接口文档

0af31f0b · Hugo · 72255a2b · 0af31f0b
Commit 0af31f0b authored Dec 07, 2018 by Hugo
Hide whitespace changes
Inline Side-by-side

Showing with 1003 additions and 0 deletions

区块链接口.md 区块链接口.md +1003 -0

No files found.
--- a/区块链接口.md
+++ b/区块链接口.md
+# 1 区块链接口
+# 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
+}
+```
\ No newline at end of file