版本历史 ( 每次更新填写一个表单 ) 版本编号 编写人 马晓敏 修改日期 2017 年 6 月 06 日 变更内容 1. 添加接口 : 5.4 断开与 VP 节点的连接

Transcription

1 JSON-RPC 接口文档 (v1.2 版 )

2 版本历史 ( 每次更新填写一个表单 ) 版本编号 编写人 马晓敏 修改日期 2017 年 6 月 06 日 变更内容 1. 添加接口 : 5.4 断开与 VP 节点的连接

3 目录 第一章说明 JSON-RPC 概述 总结... 2 第二章交易接口 查询指定区块区间的交易 查询所有非法交易 查询交易 (by transaction hash) 查询交易 (by block hash) 查询交易 (by block number) 查询链上所有交易量 查询指定区块中交易平均处理时间 查询指定交易回执信息 查询区块交易数量 (by block hash) 查询区块交易数量 (by block number) 获取交易签名哈希 查询指定时间区间内的交易 第三章智能合约 编译合约 部署合约 调用合约 获取合约字节编码 获取合约数量 获取同态加密之后的账户余额以及转账金额 获取收款方对所有未验证同态交易的验证结果 升级合约 冻结合约 解冻合约 查询合约状态 查询合约部署者 查询合约部署时间... 40

4 3.14 查询已部署合约列表 归档数据 第四章区块链 获取最新区块 查询指定区块区间的区块 查询指定区块区间的区块 (no transactions) 查询区块 (by block hash) 查询区块 (by block number) 查询区块平均生成时间 查询指定时间区间内的区块数量 第五章节点接口 获取节点信息 获取当前节点哈希值 删除节点 断开与 VP 节点的连接 第六章证书接口 获取 tcert... 62

5 第一章说明 1.1 JSON-RPC 概述 JSON-RPC 是一个无状态且轻量级的远程过程调用 (RPC) 协议 它允许运行在基于 socket http 等诸多不同消息传输环境的同一进程中, 其使用 JSON 作为数据格式 发送一个请求对象至服务端代表一个 RPC 调用, 一个请求对象包含下列成员 : jsonrpc: 指定 JSON-RPC 协议版本的字符串, 如果是 2.0 版本, 则必须准确写为 2.0 method: 表示所要调用方法名称的字符串 以 RPC 开头的方法名, 用英文句号 (U+002E or ASCII 46) 连接的为预留给 RPC 内部的方法名及扩展名, 且不能在其他地方使用 params: 调用方法所需要的结构化参数值, 该成员参数可以被省略 id: 已建立客户端的唯一标识 id, 该值必须包含一个字符串 数值或 NULL 值 如果不包含该成员则被认定为是一次通知调用 该值一般不为 NULL, 若为数值则应为整数 当发起一次 rpc 调用时, 服务端都必须回复一个 JSON 对象作为响应, 响应对象包含下列成员 : jsonrpc: 指定 JSON-RPC 协议版本的字符串, 如果是 2.0 版本, 则必须准确写为 2.0 result: 该成员在成功时必须包含, 当调用方法失败时必须不包含该成员 服务端中的被调用方法决定了该成员的值 error: 该成员在失败时必须包含, 当没有错误引起时, 不包含该成员 若引起错误, 则该成员对象将包含 code 和 message 两个属性 id: 该成员必须包含 该成员值必须与请求对象中的 id 成员值一致 若在检查请求对象 id 时错误 ( 例如参数错误或无效请求 ), 则该值必须为空值 (NULL) 第 1 页

6 1.2 总结 在 Hyperchain 中, 为了提高可用性,JSON-RPC 返回的结果格式不完全按照 JSON-RPC 2.0 的规范 比如, 接口调用成功的话, 返回的字段有 :jsonrpc id code message result, 且 code 值为 0,message 值为 SUCCESS, 用户可通过这两个字段的值来判断接口调用是否成功, 若调用失败, 则 code 为非 0 值, message 为错误信息 code 值的定义如下 : code 含义 0 请求成功 服务端接收到无效的 json 该错误发送于服务器尝试解析 json 文本 无效的请求 ( 比如非法的 JSON 格式 ) 方法不存在或者无效 无效的方法参数 JSON-RPC 内部错误 Hyperchain 内部错误或者空指针或者节点未安装 solidity 环境 请求的数据不存在 余额不足 签名非法 合约部署出错 合约调用出错 系统繁忙 交易重复 请求 tcert 失败 下面列出几个例子 : Example1: 请求无效 curl -X GET localhost:8081 "code": , "message": "EOF", "result": null 第 2 页

7 Example2: 交易重复 curl localhost: data '"jsonrpc":"2.0","method":"contract_deploycontract","params":[ "from":"0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "nonce": , "payload":"0x ffffffff e e f e060020a ad14af c5f6d d09de08a14607c575b b ffffffff ffffffff b005b ffffffff ffffffff f35b ffffffff ffffffff ", "signature":"97501a6f16b f93fb865d296074e2bcbbee87d276c3d968e bf5b4bdab5ed01b679d24dc d27fbfe3c21fc5f3534b866024f6995c330 e0b00", "timestamp": ],"id":"1"' "code": , "message": "repeated tx", "result": null Example3: 方法不存在 curl localhost: data '"jsonrpc":"2.0","method":"tx_test","params":["0x0e cde33c53f8c2b852e7 5bc9b670c14c547dd785d93cb48f661a2b36a "],"id":1' 第 3 页

8 "code": , "message": "The method tx_test does not exist/is not available", "result": null JSON-RPC 接口文档 (v1.2 版 ) 第 4 页

9 第二章交易接口 表 2.1 交易服务接口概览表 RPC 方法 tx_gettransactions tx_getdiscardtransactions tx_gettransactionbyhash tx_gettransactionbyblockhashandindex tx_gettransactionbyblocknumberandindex tx_gettransactionscount tx_gettxavgtimebyblocknumber tx_gettransactionreceipt tx_getblocktransactioncountbyhash tx_getblocktransactioncountbynumber tx_getsighhash tx_gettransactionsbytime 功能获取交易获取所有非法交易根据交易哈希值查询交易详情根据区块哈希值查询交易详情根据区块号查询交易详情查询链上所有交易量查询指定区块中交易平均处理时间查询指定交易回执信息根据区块哈希查询区块交易数量根据区块号查询区块交易数量获取用于签名算法的哈希值查询指定时间区间内的交易 2.1 查询指定区块区间的交易 表 2.2 查询指定区块区间交易接口 RPC 方法 参数 返回值 [<TransactionResult>] - from: <blocknumber> 起始区块 TransactionResult 数组 tx_gettransactions 号 to: <blocknumber> 终止区块 号 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表 示最新的区块 from 必须小于等于 to, 否则会返回 error TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 第 5 页

10 txindex: <number> 交易在区块中的交易列表的位置 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 curl -X POST --data ' "method": "tx_gettransactions", "params": ["from": 1, "to": 2], "id": 71' "result": [ "version": "1.0", "hash": "0x88d5b325dc9042ff92a9fa26ed8c943719bb049ac7022abd09bb85da36f531e4", "blocknumber": "0x2", "blockhash": "0xc c28ad6d744cb4bbe ba65ad010ce24056b6f8def9fc5cdd5", "txindex": "0x0", "from": "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , 第 6 页

11 "executetime": "0x2", "payload": "0x ffffffff e e f e060020a ad14af c5f6d d09d e08a14607c575b b ffffffff f fffffff b005b ffffffff ffffffff f35b ffffffff fffffff f ", "invalid": false, "invalidmsg": "", "version": "1.0", "hash": "0xf7149a8349f1853d8d713a15935e5059e6f55c2827f0c88f8414dd0402d6760b", "blocknumber": "0x1", "blockhash": "0x4bab3f9297e737eb197d666a2f08219f94460ace08a8e1ecad87e6e52183bcd5", "txindex": "0x0", "from": "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x7", "payload": "0x ffffffff e e f e060020a ad14af c5f6d d09d e08a14607c575b b ffffffff f fffffff b005b ffffffff ffffffff f35b ffffffff fffffff f ", "invalid": false, "invalidmsg": "" ] 2.2 查询所有非法交易 表 2.3 获取所有非法交易接口 RPC 方法 参数 返回值 tx_getdiscardtransactions 无 [<TransactionResult>] 第 7 页

12 TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 txindex: <number> 交易在区块中的交易列表的位置 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 不合法的交易指的是签名非法 合约部署出错或者合约调用出错的交易, 此时 invalid 值为 true, invalidmsg 为 SIGFAILED DEPLOY_CONTRACT_FAILED 或者 INVOKE_CONTRACT_FAILED Example1: 正常的请求 curl -X POST --data ' "method": "tx_getdiscardtransactions", "params": [], "id": 71' 第 8 页

13 "message": "SUCCESS", "result": [ "version": "", "hash": "0x100ff931204d149f88c0778f6e7b8d4b11ba3c8c720f0cc3e204b ed4", "blocknumber": null, "blockhash": null, "txindex": null, "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "executetime": null, "payload": "0x ", "invalid": true, "invalidmsg": "DEPLOY_CONTRACT_FAILED" ] Example2: 若没有非法交易 curl -X POST --data ' "method": "tx_getdiscardtransactions", "params": [], "id": 71' "message": "SUCCESS", "result": null 2.3 查询交易 (by transaction hash) 表 2.4 根据哈希查询交易接口 第 9 页

14 RPC 方法参数返回值 tx_gettransactionbyhash transactionhash <string> 交易的哈希值,32 字节的 十六进制字符串 <TransactionResult> - TransactionResult 对象 TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 txindex: <number> 交易在区块中的交易列表的位置 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 curl -X POST --data ' "method":"tx_gettransactionbyhash", "params":["0xe652e25e617c5f193b240c0d8ff1941a8cfb1d15434eb b7a aa"], "id": 1' 第 10 页

15 "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe652e25e617c5f193b240c0d8ff1941a8cfb1d15434eb b7a aa", "blocknumber": "0x4", "blockhash": "0x6ea0c80c1532c273c124511e364fc0a9225e0d129e53249f8e26752ee7d7d989", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x d f e060020a be1c766b c575b b ", "invalid": false, "invalidmsg": "" 2.4 查询交易 (by block hash) 表 2.5 根据区块哈希查询交易接口 RPC 方法 参数 返回值 blockhash: <string> 区 块的哈希值,32 字节的 tx_gettransactionbyblockhashandindex 十六进制字符串 [<TransactionResult>] index: <number> 区块 中的位置 索引 number 可以是十进制整数或者进制字符串 TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 第 11 页

16 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 txindex: <number> 交易在区块中的交易列表的位置 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 curl -X POST --data ' "method": "tx_gettransactionsbyblockhashandindex","params": ["0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", 0], "id": 71' "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe81d39df11779c7f83e6073cc659c7ee85708c135b6557d318e765b9f938c02f", "blocknumber": "0x2", "blockhash": "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", "txindex": "0x0", 第 12 页

17 "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x6fd7cc b ", "invalid": false, "invalidmsg": "" 2.5 查询交易 (by block number) 表 2.6 根据区块号查询交易接口 RPC 方法 参数 返回值 blocknumber: <blocknumber> 区块 tx_gettransactionbyblocknumberandindex 的高度 [<TransactionResult>] index: <number> 区 块中的位置 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表 示最新的区块 索引 number 可以是十进制整数或者进制将字符串 TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 txindex: <number> 交易在区块中的交易列表的位置 第 13 页

18 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 curl -X POST --data ' "method": "tx_gettransactionsbyblocknumberandindex", "params": [2,0], "id": 71' "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe81d39df11779c7f83e6073cc659c7ee85708c135b6557d318e765b9f938c02f", "blocknumber": "0x2", "blockhash": "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": 第 14 页

19 JSON-RPC 接口文档 (v1.2 版 ) "0x6fd7cc b ", "invalid": false, "invalidmsg": "" 2.6 查询链上所有交易量 表 2.7 查询链上所有交易量接口 RPC 方法 参数 返回值 无 count: <number> 交易数量 tx_gettransactionscount timestamp: <number> 响应时间戳 ( 单位 ns) curl -X POST --data ' "method": "tx_gettransactionscount", "params": [], "id": 71' "id": 71, "message": "SUCCESS":, "result": "count": "0x9", "timestamp": 第 15 页

20 2.7 查询指定区块中交易平均处理时间 表 2.8 根据指定的区块区间计算出每笔交易的平均处理时间接口 RPC 方法参数返回值 time: <number> 交易 from: <blocknumber> 起始的平均处理时间 ( 单位区块号 ms) tx_gettxavgtimebyblocknumber to: <blocknumber> 终止区块号 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表示最新的区块 from 必须小于等于 to, 否则会返回 error 注意 : 如果 from 和 to 的值一样, 则表示计算的是当前指定区块交易的平均处理时间 curl -X POST --data ' "method": "tx_gettxavgtimebyblocknumber", "params": ["from":10, "to":19], "id": 71' "id":71, "message": "SUCCESS", "result": "0xa9" 2.8 查询指定交易回执信息 表 2.9 根据交易 hash 返回交易回执信息接口 RPC 方法 参数 返回值 tx_gettransactionreceipt transactionhash: <string> 交 <Receipt> 易 hash <Receipt> 对象 第 16 页

21 txhash:<string> 交易哈希 contractaddress:<string> 合约地址 ret: <string> 执行的结果 若调用这个方法得到的 <Receipt> 对象为 null, 则表明这笔交易还没被确认, 若返回了 error, 则可能是合约部署失败 DEPLOY_CONTRACT_FAILED 合约方法调用失败 INVOKE_CONTRACT_FAILED 或者是签名非法 SIGFAILED, 下面将对这里说到的几种情况都一一举例 : Example1: 交易未被确认 curl localhost: data '"jsonrpc":"2.0","method":"tx_gettransactionreceipt","params":["0x0e cd e33c53f8c2b852e75bc9b670c14c547dd785d93cb48f661a2b36a "],"id":1' "code": , "message": "Not found receipt by 0x0e cde33c53f8c2b852e75bc9b670c14c547dd785d93cb48f661a2b36a", "result": null Example2: 合约部署出错 在这个例子中我们使用以下合约来重现这个情况 : contract TestContractor int length = 0; 第 17 页

22 modifier justfortest() length = 2; throw; _; function TestContractor()justForTest function getlength() returns(int) return length; 我们将该合约编译后返回的 bin 作为 contract_deploycontract() 方法中参数 payload 的值, 那么部署合约请求如下 : curl localhost: data '"jsonrpc":"2.0", "method":"contract_deploycontract", "params":[ "from":"17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload":"0x b b5b5b60 3f f e060020a be1c766b c 575b b b f35 b b9056", "timestamp": , "signature":"0xfc1cb1986dd4ee4a5f8d8238e2f7bac1866aad235d587eb641d7627 0bf ab7d42dc0f2575aa858a88ae7732cd617281eedb38636e843ff3b49b8f 8ab01"],"id":1' "message": "SUCCESS", "result": "0x33aef7e6bad2ae27c23a8ab44f56aef87042f1f0b02e1b0ee5e8a a6" 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了合约部署失 第 18 页

23 败的 error: curl localhost: data '"jsonrpc":"2.0","method":"tx_gettransactionreceipt","params":["0x33aef7e6bad 2ae27c23a8ab44f56aef87042f1f0b02e1b0ee5e8a a6"],"id":1' "jsonrpc":"2.0", "id":1, "code":-32004, "message":"deploy_contract_failed", "result":null Example3: 合约方法调用出错 在这个例子中我们使用以下合约来重现这个情况 : contract TestContractor int length = 0; modifier justfortest() length = 2; throw; _; function TestContractor() function getlength()justfortest returns(int) return length; 调用合约方法的请求如下 : curl localhost: data '"jsonrpc":"2.0", "method": "contract_invokecontract", "params": [ 第 19 页

24 "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0xaeccd2fd c5de1cb014a9c192c498df", "timestamp": , "nonce": , "payload":"0xbe1c766b", "signature":"0x8c56f025610dd9cb3f4ac346d a b7593d87f3b 45c ed32f6a da915740b363c1b357cf31a7eb83e05dde0afc "],"id": 1' "message": "SUCCESS", "result":"0x5233d18f46e9c1ed49dbdeb4273c1c1e0eb176efcedf6edb6d9fa59d33 d02fee " 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了方法调用失 败的 error: curl localhost: data '"jsonrpc":"2.0","method":"tx_gettransactionreceipt","params":["0x5233d18f46e 9c1ed49dbdeb4273c1c1e0eb176efcedf6edb6d9fa59d33d02fee"],"id":1' "jsonrpc":"2.0", "id":1, "code":-32005, "message":"invoke_contract_failed", "result":null Example4: 签名非法 我们将 Example3 合约方法调用失败例子的参数稍微修改一下, 把 from 的最后一 第 20 页

25 个字母 c 改为 0, 那么调用合约请求如下 : curl localhost: data '"jsonrpc":"2.0", "method": "contract_invokecontract", "params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bff0", "to":"0xaeccd2fd c5de1cb014a9c192c498df", "timestamp": , "nonce": , "payload":"0xbe1c766b", "signature":"0x57dfa7f2c2d8c762c9c0e5ef7b1c4dda84b584f36799ab751891c 8dc f64d c af4e4231db393744ad3cfd37c8cce74c aa401"],"id": 1' "id": "SUCCESS", "result": " 0x621d09cd9d5e9027d9b82c5e1fd911ac dbb0c4dab6c6fcd64310fe23" error: 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了签名非法的 curl localhost: data '"jsonrpc":"2.0","method":"tx_gettransactionreceipt","params":["0x621d09cd9d5 e9027d9b82c5e1fd911ac dbb0c4dab6c6fcd64310fe23"],"id":1' "code": , "message": " SIGFAILED ", "result": null Example5: 第 21 页

26 curl -X POST --data ' "method": "tx_gettransactionreceipt", "params":["0x406f89cb205e136411fd7f5befbf8383bbfdec5f6e8bcfe50b16dcff037d 1d8a"], "id": 71' "id":71, "message": "SUCCESS", "result": " txhash ": " 0x406f89cb205e136411fd7f5befbf8383bbfdec5f6e8bcfe50b16dcff037d1d8a", " contractaddress ": "0x313bbf563991dc4c1be9d98a058a26108adfcf81", " ret ": "0x e060020a ad14af c5f6d14605e d09de08a b b e060020a ffffffff ffffffff b005b ffffffff ffffffff f35b c e060020a63ffffffff ffffffff " 2.9 查询区块交易数量 (by block hash) 表 2.10 根据区块 hash 返回区块交易数量接口 RPC 方法参数返回值 blockhash: <string> 区块 count: <number> 交 tx_getblocktransactioncountbyhash hash 易数量 curl -X POST --data ' "method":"tx_getblocktransactioncountbyhash", "params": ["0xb60e8dd61c5d32be8058bb8eb970870f "], "id": 71' 第 22 页

27 "id":71, "message": "SUCCESS", "result": "0xaf5" 2.10 查询区块交易数量 (by block number) 表 2.11 根据区块 number 返回区块交易数量接口 RPC 方法参数返回值 blocknumber: <string> count: <number> 交 tx_getblocktransactioncountbynumber 区块号 易数量 curl -X POST --data ' "method":" tx_getblocktransactioncountbynumber", "params": ["0x2"], "id": 71' "id":71, "message": "SUCCESS", "result": "0xaf5" 2.11 获取交易签名哈希 表 2.12 获取用于签名算法的哈希接口 RPC 方法 参数 返回值 tx_getsignhash from: <string> 发起者地址 to: <string> 接收者地址或合约地址, 若是部署合约, 则不需要这个参数 nonce: <number> 16 位的随机数, 该值必须为十进制整数 hash: <string> 签名哈希 第 23 页

28 value/payload: <number> 交易量值 / 字节编码 timestamp: <number> 交易时间戳 说明 : 如果是部署合约的交易, 则不要传 to 若为普通交易, 则传 value, 表示交 易金额, 若是部署合约或调用合约的交易, 则传 payload, 含义详见部署合约或 调用合约的接口 curl localhost: data '"jsonrpc":"2.0", "method":"tx_getsignhash", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload":"0x ffffffff ae e f e060020a ad14af c5f6d14 605e578063d09de08a b b e060020a ffffffff ffffffff b005b ffffffff ffffffff f35b c e060020a63ffffffff ffffffff ", "timestamp": ],"id":"1"' "message": "SUCCESS", "result": "0x2e6a644a4ca6a9daba dc0dda039208e642df11db35438d18e7c3b13c3 " 2.12 查询指定时间区间内的交易 表 2.13 查询指定时间区间内的所有交易接口 第 24 页

29 RPC 方法参数返回值 tx_gettransactionsbytime starttime: <number> 起始时间戳 ( 单位 ns) endtime: <number> 结束时间戳 ( 单位 ns) [<TransactionResult>] - TransactionResult 数组 TransactionResult 对象 : version: <string> 平台版本号 hash: <string> 交易的哈希值,32 字节的十六进制字符串 blocknumber: <number> 交易所在的区块高度 blockhash: <string> 交易所在区块哈希值 txindex: <number> 交易在区块中的交易列表的位置 from: <string> 交易发送方的地址,20 字节的十六进制字符串 to: <string> 交易接收方的地址,20 字节的十六进制字符 amount: <number> 交易量 timestamp: <number> 交易发生时间 ( 单位 ns) nonce: <number> 16 位随机数 executetime: <string> 交易的处理时间 ( 单位 ms) payload: <string> 部署合约与调用合约的时候才有这个值, 可以通过这个值追朔到合约调用的方法以及调用传入的参数 invalid: <boolean> 交易是否不合法 invalidmsg: <string> 交易的不合法信息 curl -X POST --data '"jsonrpc":"2.0", "method":"tx_gettransactionsbytime","params":["starttime":1, "endtime": ],"id":1' 第 25 页

30 "message": "SUCCESS", "result": [ "version": "1.0", "hash": "0xbd441c7234e3b83a05c89ed5d548c3d e271a08e7354d74e45431bc", "blocknumber": "0x1", "blockhash": "0xa6a4b2df16c7bdeb578aa7de7b05f9b54d96202bdc ebd", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x b6101e f e a fd7cc a b b f b f f35b a a bc b f f01f f f 01f f35b b f b b b ", "invalid": false, "invalidmsg": "" ] 第 26 页

31 第三章智能合约 表 3.1 智能合约服务接口概览表 RPC 方法 功能 contract_compilecontract 编译合约 contract_deploycontract 部署合约 contract_invokecontract 调用合约 归档数据 contract_getcode 获取合约编码 contract_ getcontractcountbyaddr 获取合约数量 contract_encryptomessage 获取同态余额以及转账金额 contract_checkhmvalue 获取同态交易的 s 验证结果 contarct_maintaincontract 升级合约 冻结合约 解冻合约 contract_getstatus 查询合约状态 contract_getcreator 查询合约部署者 contract_getcreatetime 查询合约部署时间 contract_getdeployedlist 查询指定账户已部署合约的列表 使用智能合约一般需要经过以下几个步骤 : 调用 3.1 编译合约 接口, 得到该合约的 abi 和 bin 调用 3.2 部署合约 接口, 这一步需要用到上一步得到的 bin 值作为部署合约的 payload 参数 ( 详见 3.2 部署合约接口 ) 调用 2.8 获取回执信息 接口, 得到上一步部署合约完成后合约的地址 调用 3.3 调用合约 接口, 参数 to 即为第三步得到的合约地址 ( 详见 3.3 调用合约接口 ) 继续调用 2.8 获取回执信息 接口, 得到合约方法返回值的字节编码 3.1 编译合约 表 3.2 编译合约源码 RPC 方法 参数 返回值 contract_compilecontract <string> 合约源码 <compilecode> 说明 : 合约实际上是在本地编译, 务必保证本地已经安装 solidity 环境, 否则无 法编译 <compilecode> 对象 : 第 27 页

32 abi: <Array> 合约源码对应的 abi 数组 bin: <Array> 合约编译而成的字节码 types: <Array> 对应合约的名称 若源码中有多个合约, 则 bin 为顶层合约的字节码 curl -X POST --data '"jsonrpc":"2.0","method":"contract_compilecontract","params":["contract Accumulator uint32 sum = 0; function increment() sum = sum + 1; function getsum() returns(uint32) return sum; function add(uint32 num1,uint32 num2) sum = sum+num1+num2; "],"id":1' "message": "SUCCESS", "result": "abi": [ "[\"constant\":false,\"inputs\":[\"name\":\"num1\",\"type\":\"uint32\",\"name\":\ "num2\",\"type\":\"uint32\"],\"name\":\"add\",\"outputs\":[],\"payable\":false,\"type \":\"function\",\"constant\":false,\"inputs\":[],\"name\":\"getsum\",\"outputs\":[\" name\":\"\",\"type\":\"uint32\"],\"payable\":false,\"type\":\"function\",\"constant\ ":false,\"inputs\":[],\"name\":\"increment\",\"outputs\":[],\"payable\":false,\"type\":\ "function\"]" ], "bin": [ "0x ffffffff ae e f e060020a ad14af c5f6d14605e578063d09d e08a b b e060020a ffffffff ffffffff b005b ffffffff ffffffff f35b c e 第 28 页

33 060020a63ffffffff ffffffff " ], "types": [ "Accumulator" ] 3.2 部署合约 表 3.3 部署合约 RPC 方法参数返回值 from: <string> 合约调用者地址 nonce: <number>16 位的随机数, 该值必须为十进制整数 transactionhash:<string> timestamp: <number> 交易时间交易的哈希值,32 字节 contract_deploycontract 戳 ( 单位 ns) 的十六进制字符串 payload: <string> 合约编码, contract_compliecontract 方法返回的 bin signature: <string> 交易签名 说明 : 若合约构造函数需要传参, 则 payload 为编译合约返回的 bin 与构造函数 参数编码的字符串拼接 curl localhost: data '"jsonrpc":"2.0", "method":"contract_deploycontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc ", "nonce": , "payload":"0x ffffffff ae e f e060020a ad14af c5f6d1460 5e578063d09de08a b b e060020a ffffffff ffffffff b005b ffffffff ffffffff f35b c e060020a63ffffffff ffffffff ", "signature":"0x388ad7cb71b1281eb5a0746fa8fe6fda006bd28571cbe69947ff01 第 29 页

34 15ff8f3cd00bdf2f45748e0068e dc69a71cc95a2305bd2abf813574b cea900", "timestamp": ],"id":"1"' "message": "SUCCESS", "result": "0x406f89cb205e136411fd7f5befbf8383bbfdec5f6e8bcfe50b16dcff037d1d8a" 3.3 调用合约 表 3.4 调用合约 RPC 方法参数返回值 from: <string> 合约调用者地址 to: <string> 合约地址 nonce: <number> 16 位的随机数, 该值必须为十进制整数 transactionhash:<string> timestamp: <number> 交易时间戳 交易的哈希值,32 字节 contract_invokecontract payload: <string> 方法名和方法的十六进制字符串 参数经过编码后的 input 字节码 signature: <string> 交易签名 simulate: <bool> true 表示交易不走共识,false 表示走共识, 默认为 false 说明 :to 合约地址需要在部署完合约以后, 调用 tx_gettransactionreceipt 方法来获取 curl localhost: data '"jsonrpc":"2.0", "method": "contract_invokecontract", "params":[ 第 30 页

35 "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload":"0x3ad14af ", "signature":"0xde467ec4c0bd9033bdc3b6faa43a8d3c5dcf393ed9f34ec1c1310b 0859a0ecba15c5be4480a9ad2aaaea cb54e dd5407f9fd64f c9301", "simulate":false, "timestamp": , "to":"0x313bbf563991dc4c1be9d98a058a26108adfcf81" ],"id":"1"' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed c08fde" 3.4 获取合约字节编码 表 3.5 获取合约的字节编码 RPC 方法参数返回值 contract_getcode address: <string> 合约地址 <string> 十六进制字节码 curl -X POST --data '"jsonrpc":"2.0","method":"contract_getcode","params": ["0xaeccd2fd c5de1cb014a9c192c498df"],"id": 1' "message": "SUCCESS", 第 31 页

36 "result": "0x e060020a dd b e e f24d ae9f75e b30cd67c e578063e01da11e b b e e0565b f f01f f d a b f35b f f1565b f35b e b f f01f f d a b f35b e b7565b f f01f f d a b f35b e cf b f35b b f f01f f35b e f c ea565b b c b b5b b f6e b b b b a f e6f af565b f c616e b b e b b f e6f c5565b f616d6f756e e6f e6f c5565b f e 第 32 页

37 b b fb10e2d b26eecdfd717e6a320cf44b4afac2b0732d9fcbe2b7fa0cf b b5b b c b b f b b d b c5575b b9056" 3.5 获取合约数量 表 3.6 获取指定账户部署的合约量 RPC 方法参数返回值 contract_getcontractcountbyaddr address: <string> 账户地址 <number> 合约数量 curl -X POST --data ' "method": "contract_getcontractcountbyaddr", "params": ["0xa94f5374fce5edbc8e2a8697c e6ebf0b"], "id": 1' "message": "SUCCESS", "result": "0x3" 3.6 获取同态加密之后的账户余额以及转账金额 表 3.7 获取账户的同态余额以及转账金额 第 33 页

38 RPC 方法参数返回值 contract_encryptomessage balance: <number> 账户未转账之前所有的余额, 长整形, 不超过 8 个字节数据大小 amount: <number> 要转的金额, 长整形数据, 不超过 8 个字节数据大小 hmbalance: <string> 非法同态值, 由一个 16 个字节的大整数转化为 10 进制得到 newbalance:<string> 同态加密之后的账户余额, 十进制数表示. amount: <string> 同态加密之后的转账金额, 十进制数表示. 若无非法交易,hmBalance 为空 若有非法交易,hmBalance 的值为 3.7 获取收 款方对所有未验证同台交易的验证结果 接口返回值中的 illegalhmamount 的值 curl localhost: data '"jsonrpc":"2.0","method": "contract_encryptomessage","params": ["balance":100, "amount":10, "hmbalance":"123456"],"id": 1' "message": "SUCCESS", "result": "newbalance":" ", "amount":" " 3.7 获取收款方对所有未验证同态交易的验证结果 表 3.8 获取收款方对所有未验证同台交易的验证结果 RPC 方法参数返回值 第 34 页

39 contract_checkhmvalue rawvalue: <number[]> 经过收款方椭圆曲线私钥解密之后的所有未验证转账金额 encryvalue: <string[]> 所有未验证交易中的同态加密过的转账金额, 由 16 个字节大小的大整形转化为 10 进制所得 illegalhm: <string> 收款方当前所有非法转账金额同态值之和 checkresult: <bool[]> 返回一个 bool 类型数组,true 表示验证成功,false 表示验证失败 illegalhmamount: <string> 返回更新之后的所有非法转账金额同态值之和 当返回的值中有 false, 则 false 对应的数组下标对应的 encryvalue[] 中的同态值是 一个非法同态值, 需要收款方进行存储 curl localhost: data '"jsonrpc":"2.0","method": "contract_checkhmvalue","params": ["rawvalue": [1,2], "encryvalue": ["123", "456"],"illegalhm":"" ],"id": 1' "message": "SUCCESS", "result": "checkresult":[false,false], "illegalhmamount":"0" 3.8 升级合约 表 3.9 升级合约 RPC 方法 参数 返回值 contract_maintaincontract transactionhash:<string> from: <string> 合约调用者地址 交易的哈希值,32 字节的 to: <string> 合约地址 十六进制字符串 nonce: <number> 16 位的随机数, 第 35 页

40 该值必须为十进制整数 timestamp: <number> 交易时间戳 payload: <string> 编译后的新合 约字节码 signature: <string> 交易签名 opcode: 1 只有合约的部署者才拥有升级合约的权限 curl localhost: data '"jsonrpc":"2.0","method": "contract_maintaincontract","params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "payload": "0x6fd7cc b ", "signature":"0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c4689 4b9f12a02af471031ba11f155e41adf42fca639b67fb7148ddec90e7628ec8af60c872c 00", "opcode": 1], "id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed c08fde" 第 36 页

41 3.9 冻结合约 表 3.10 冻结合约 RPC 方法参数返回值 from: <string> 合约调用者地址 to: <string> 合约地址 nonce: <number> 16 位的随机数, 该值必须为十进制整数 contract_maintaincontract timestamp: <number> 交易时间戳 signature: <string> 交易签名 opcode: 2 只有合约的部署者才拥有冻结合约的权限 transactionhash:<string> 交易的哈希值,32 字节的 十六进制字符串 curl localhost: data '"jsonrpc":"2.0","method": "contract_maintaincontract","params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "signature":"0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c4689 4b9f12a02af471031ba11f155e41adf42fca639b67fb7148ddec90e7628ec8af60c872c 00", "opcode": 2], "id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed c08fde" 第 37 页

42 3.10 解冻合约 表 3.11 解冻合约 RPC 方法参数返回值 from: <string> 合约调用者地址 to: <string> 合约地址 nonce: <number> 16 位的随机数, 该值必须为十进制整数 contract_maintaincontract timestamp: <number> 交易时间戳 signature: <string> 交易签名 opcode: 3 只有合约的部署者才拥有解冻合约的权限 transactionhash:<string> 交易的哈希值,32 字节的 十六进制字符串 curl localhost: data '"jsonrpc":"2.0","method": "contract_maintaincontract","params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "signature":"0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c4689 4b9f12a02af471031ba11f155e41adf42fca639b67fb7148ddec90e7628ec8af60c872c 00", "opcode": 3], "id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed c08fde" 第 38 页

43 3.11 查询合约状态 表 3.12 查询合约状态 RPC 方法 参数 返回值 contract_getstatus address: <string> 合约地址 contractstatus:<string> 合约状态 normal 表示正常状态, frozen 表示冻结状态, non-contract 表示非合约, 即为普通转账的交易 curl localhost: data '"jsonrpc":"2.0","method": "contract_getstatus","params": ["0xbbe2b6412ccf de8958f2acc76cda9c9"],"id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":" normal" 3.12 查询合约部署者 表 3.13 查询合约部署者 RPC 方法 参数 返回值 contract_getcreator address: <string> 合约地址 address:<string> 合约部署者的地址 curl localhost: data '"jsonrpc":"2.0","method": "contract_getcreator","params": 第 39 页

44 ["0xbbe2b6412ccf de8958f2acc76cda9c9"],"id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":" 0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd " 3.13 查询合约部署时间 表 3.14 查询合约部署时间 RPC 方法 参数 返回值 contract_getcreatetime address: <string> 合约地址 datetime: <string> 合约部署的日期时间 curl localhost: data '"jsonrpc":"2.0","method": "contract_getcreatetime","params": ["0xbbe2b6412ccf de8958f2acc76cda9c9"],"id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":" :37: CST" 3.14 查询已部署合约列表 表 3.15 查询已部署的合约地址列表 RPC 方法 参数 返回值 contract_getdeployedlist address: <string> 部署者地址 address: <string[]> 已部署的所有合约地址 第 40 页

45 curl localhost: data '"jsonrpc":"2.0","method": "contract_getdeployedlist","params": ["0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd"],"id": 1' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":[ 0xbbe2b6412ccf de8958f2acc76cda9c9 ], 3.15 归档数据 表 3.16 归档数据 RPC 方法参数返回值 from: <string> 合约调用者地址 to: <string> 合约地址 nonce: <number> 16 位的随机数, 该值必须为十进制整数 timestamp: <number> 交易时间戳 transactionhash:<string> payload: <string> 方法名和方法交易的哈希值,32 字节 contract_invokecontract 参数经过编码后的 input 字节码 的十六进制字符串 signature: <string> 交易签名 simulate: <bool> true 表示交易不走共识,false 表示走共识, 默认为 false opcode: 100 合约中通过 delete 关键字删除的变量均会被归档到历史数据库中 curl localhost: data '"jsonrpc":"2.0", "method": "contract_invokecontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , 第 41 页

46 "payload":"0x3ad14af ", "signature":"0xde467ec4c0bd9033bdc3b6faa43a8d3c5dcf393ed9f34ec1c1310b 0859a0ecba15c5be4480a9ad2aaaea cb54e dd5407f9fd64f c9301", "simulate":false, "timestamp": , "to":"0x313bbf563991dc4c1be9d98a058a26108adfcf81", opcode : 100, ],"id":"1"' "jsonrpc":"2.0", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed c08fde" 第 42 页

47 第四章区块链 表 4.1 区块服务接口概览表 RPC 方法 功能 block_latestblock 获取最新区块 block_getblocks 查询指定区块区间的所有区块 Block_getPlainBlocks 查询指定区块区间的所有区块, 但不包含 区块中交易的信息 block_getblockbyhash 根据区块的哈希值返回区块信息 block_getblockbynumber 根据区块号返回区块信息 block_getavggeneratetimebyblocknumber 根据区块区间计算出区块的平均生成时间 block_getblocksbytime 查询指定时间区间内的区块数量 4.1 获取最新区块 表 4.2 获取最新区块接口 RPC 方法参数返回值 block_latestblock 无 <blockresult> <blockresult> 该对象成员有以下 : version: <string> 平台版本号 number: <string> 区块的高度 hash: <string> 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> 父区块哈希值,32 字节的十六进制字符串 writetime: <number> 区块的生成时间 ( 单位 ns) avgtime: <number> 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <number> 当前区块中打包的交易数量 merkleroot: <string> Merkle 树的根哈希 transactions: [<TransactionResult>] 区块中的交易列表 Example1: 正常的请求 第 43 页

48 curl -X POST --data '"jsonrpc":"2.0","method":"block_latestblock","params":[],"id":71' "message": "SUCCESS", "result": "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ "version": "1.0", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x81053a c 第 44 页

49 c8", "invalid": false, "invalidmsg": "" ] Example1: 如果链上一个区块都没有 curl -X POST --data '"jsonrpc":"2.0","method":"block_latestblock","params":[],"id":71' "message": "SUCCESS", "result": null 4.2 查询指定区块区间的区块 表 4.3 查询指定区块区间的所有区块接口 RPC 方法 参数 返回值 block_getblocks from: <blocknumber> 起始区块号 to: <blocknumber> 终止区块号 [<blockresult>] blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表 示最新的区块 from 必须小于等于 to, 否则会返回 error <blockresult> 该对象成员有以下 : 第 45 页

50 version: <string> 平台版本号 number: <string> 区块的高度 hash: <string> 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> 父区块哈希值,32 字节的十六进制字符串 writetime: <number> 区块的生成时间 ( 单位 ns) avgtime: <number> 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <number> 当前区块中打包的交易数量 merkleroot: <string> Merkle 树的根哈希 transactions: [<TransactionResult>] 区块中的交易列表 curl -X POST --data ' "method": "block_getblocks", "params": ["from":2,"to":3], "id": 1' "message": "SUCCESS", "result": [ "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ 第 46 页

51 "version": "1.0", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x81053a c c8", "invalid": false, "invalidmsg": "" ], "version": "1.0", "number": "0x2", "hash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "parenthash": "0xe287c62aae77462aa772bd68da9f1a1ba21a0d044e2cc47f742409c20643e50c", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ "version": "1.0", "hash": "0x07d606a25d1eab009f e9c e6c b969ba ", 第 47 页

52 "blocknumber": "0x2", "blockhash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x6fd7cc a ", "invalid": false, "invalidmsg": "" ] ] 4.3 查询指定区块区间的区块 (no transactions) 表 4.4 查询指定区块区间的所有区块接口 RPC 方法 参数 返回值 block_getplainblocks from: <blocknumber> 起始区块号 to: <blocknumber> 终止区块号 [<plainblockresult>] blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表 示最新的区块 from 必须小于等于 to, 否则会返回 error <plainblockresult> 该对象成员有以下 : version: <string> 平台版本号 number: <string> 区块的高度 第 48 页

53 hash: <string> 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> 父区块哈希值,32 字节的十六进制字符串 writetime: <number> 区块的生成时间 ( 单位 ns) avgtime: <number> 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <number> 当前区块中打包的交易数量 merkleroot: <string> Merkle 树的根哈希 curl -X POST --data ' "method": "block_getplainblocks", "params": ["from":2,"to":3], "id": 1' "message": "SUCCESS", "result": [ "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "version": "1.0", "number": "0x2", "hash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", 第 49 页

54 "parenthash": "0xe287c62aae77462aa772bd68da9f1a1ba21a0d044e2cc47f742409c20643e50c", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c" ] 4.4 查询区块 (by block hash) 表 4.5 根据区块的哈希值查询区块详细信息 RPC 方法 参数 返回值 block_getblockbyhash blockhash: <string> 区块的哈希值,32 字节的十六进制字符串 <blockresult> <blockresult> 该对象成员有以下 : version: <string> 平台版本号 number: <string> 区块的高度 hash: <string> 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> 父区块哈希值,32 字节的十六进制字符串 writetime: <number> 区块的生成时间 ( 单位 ns) avgtime: <number> 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <number> 当前区块中打包的交易数量 merkleroot: <string> Merkle 树的根哈希 transactions: [<TransactionResult>] 区块中的交易列表 curl -X POST --data '"jsonrpc":"2.0","method":"block_getblockbyhash","params":["0x00acc3e13d81 第 50 页

55 24fe799d55d7d2af dc7bbc723718bb1a88fead34c914"],"id":1' "message": "SUCCESS", "result": "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ "version": "1.0", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x81053a c c8", 第 51 页

56 ] "invalid": false, "invalidmsg": "" 4.5 查询区块 (by block number) 表 4.6 根据区块高度查询区块详细信息 RPC 方法 参数 返回值 block_getblockbynumber blocknumber: <blocknumber> 区块号 <blockresult> blocknmber 可以是十进制整数或者进制字符串, 也可以是 latest 字符串表示最新的区块 <blockresult> 该对象成员有以下 : version: <string> 平台版本号 number: <string> 区块的高度 hash: <string> 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> 父区块哈希值,32 字节的十六进制字符串 writetime: <number> 区块的生成时间 ( 单位 ns) avgtime: <number> 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <number> 当前区块中打包的交易数量 merkleroot: <string> Merkle 树的根哈希 transactions: [<TransactionResult>] 区块中的交易列表 curl -X POST --data ' "method": "block_getblockbynumber", "params": ["0x3"], "id": 1' 第 52 页

57 "message": "SUCCESS", "result": "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ "version": "1.0", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "executetime": "0x2", "payload": "0x81053a c c8", "invalid": false, 第 53 页

58 ] "invalidmsg": "" 4.6 查询区块平均生成时间 表 4.7 查询区块平均生成时间 RPC 方法参数返回值 block_getavggeneratetimebyblocknumber from: <blocknumber> 起始区块号 to: <blocknumber> 终 止区块号 time: <number> 区块的平均生成时间 ( 单位 ms) blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表 示最新的区块 from 必须小于等于 to, 否则会返回 error curl -X POST --data '"jsonrpc":"2.0","method":"block_getavggeneratetimebyblocknumber","params ": ["from": 10, "to": 19],"id":71' "id":71, "message": "SUCCESS", "result": "0x32" 第 54 页

59 4.7 查询指定时间区间内的区块数量 表 4.8 查询指定时间区间内的区块数量 RPC 方法 参数 返回值 starttime: <number> 起始时间戳 ( 单位 ns) sumofblocks: <number> 区块总数 block_getblocksbytime endtime: <number> 结束 startblock: <number> 起始区块时间戳 ( 单位 ns) 号 endblock: <number> 结束区块 号 Example1: 正常的请求 curl -X POST --data '"jsonrpc":"2.0","method":"block_getblocksbytime","params":["starttime": , "endtime": ],"id":1' "message": "SUCCESS", "result": "sumofblocks": "0x3", "startblock": "0x1", "endblock": "0x3" Example2: 如果起始时间和终止时间均大于链上最新区块的写入时间 curl -X POST --data '"jsonrpc":"2.0","method":"block_getblocksbytime","params":["starttime": , "endtime": ],"id":1' 第 55 页