hyperchain Documentation

Transcription

1 hyperchain Documentation 发布 Hyperchain Corp 年 01 月 11 日

2

3 快速入门 : 1 准备工作 操作系统版本要求 安装 Go 语言开发环境 安装 Go vendor 安装合约编译器 ( 可选 ) 快速入门 编译 Hyperchain 启动 Hyperchain Hyperchain 使用示例 HyperCli 合约样例 1 - Set/Get Hash 合约样例 2 - Simulate Bank 交易处理 交易执行流程 19 5 共识 概述 RBFT 相关变量 RBFT 常规流程 RBFT 视图变更 RBFT 自主恢复 RBFT 节点增删 账本 概述 区块链数据 账户数据 Bucket tree 概述 结构解析 核心操作 智能合约 智能合约简介 智能合约引擎 HyperVM 智能合约使用 P2P 51 i

4 概述 Hypernet P2PManager 数字证书 概述 证书简述 CA 相关配置 证书获取以及校验流程 分区共识 概述 集群架构 节点架构 系统数据流 密码学算法 概述 椭圆曲线数字签名 对称加密算法 密钥交换算法 密码杂凑算法 JSON-RPC API JSON-RPC 概述 接口设计 接口概览 接口描述 节点操作 添加节点 删除节点 Hyperchain 开发路线图 First community version Better smart contract Controllable data capacity Autonomous Protect your pricacy Run fast What is your favourite ii

5 CHAPTER 1 准备工作 1.1 操作系统版本要求 以下图表说明了 Hyperchain 对于不同操作系统的版本要求 不同平台版本要求 操作系统 系统版本 系统架构 RHEL 6 或更新 amd64, 386 CentOS 6 或更新 amd64, 386 SLES 11SP3 或更新 amd64, 386 Ubuntu 或更新 amd64, 386 macos 10.8 或更新 amd64, 安装 Go 语言开发环境 因为 Hyperchain 使用 Go 语言来实现它的各个组件, 所以需要安装 Go 语言开发环境 下载 Go Go 为 Mac OS X Linux 和 Windows 提供二进制发行版 如果您使用的是不同的操作系统, 您可以下载 Go 源代码并从源代码安装 在这里下载适用于您的平台的最新版本 Go: 下载 - 请下载 1.7.x 或更新 安装 Go 请按照对应于您的平台的步骤来安装 Go 环境 : 安装 Go, 推荐使用默认配置安装 对于 Mac OS X 和 Linux 操作系统, 默认情况下 Go 会被安装到 /usr/local/go/, 并且将环境变量 GOROOT 设置为该路径 /usr/local/go. 1

6 export GOROOT=/usr/local/go 同时, 请添加路径 GOROOT/bin 到环境变量 PATH 中, 可以使 Go 工具正常执行 export PATH=$PATH:$GOROOT/bin 设置 GOPATH 您的 Go 工作目录 (GOPATH) 是用来存储您的 Go 代码的地方, 您必须要将他跟您的 Go 安装目录区分开 (GOROOT) 以下命令是用了设置您的 GOPATH 环境变量的, 您也可以参考 Go 官方文档, 来获得更详细的内容 : 对于 Mac OS X 和 Linux 操作系统将 GOPATH 环境变量设置为您的工作路径 : export GOPATH=$HOME/go 同时添加路径 GOPATH/bin 到环境变量 PATH 中, 可以使编译后的 Go 程序正常执行 export PATH=$PATH:$GOPATH/bin 由于我们将在 Go 中进行一系列编码, 您可以将以下内容添加到您的 ~/.bashrc 文件中 : export GOROOT=/usr/local/go export GOPATH=$HOME/go export PATH=$PATH:$GOPATH/bin:$GOROOT/bin 检查 Go 安装结果 创建和运行这里描述的 hello.go 应用 : 如果您正确设置了 Go 运行环境, 您应该能够从任何目录运行 hello 程序, 并看到程序成功执行 1.3 安装 Go vendor Go vendor 是管理包及其依赖项的工具 此工具将依赖的包复制到项目的 vendor 目录中, 并将其版本记录在名为 vendor.json 的文件中 安装命令 go get -u github.com/kardianos/govendor 检查 Go vendor 安装结果 为了要验证您的 govendor 安装正确, 可以通过查看 govendor 版本信息来检验 在命令提示符下, 键入以下命令并确保您看到了 govendor 版本信息 : $ govendor --version v Chapter 1. 准备工作

7 1.3.3 更多信息 您可以转到项目的主页了解更多细节 - Go vendor 1.4 安装合约编译器 ( 可选 ) Hyperchain 支持用 Solidity 编写的智能合约, 然后将它编译为字节码并部署到区块链中 鉴于我们是用 Solidity 语言编写的合约, 所以需要确保我们已经安装名为 solc 的合约编译器 我们已经在源码中提供了一些平台的通用安装包, 您可以直接使用他们来快速安装 solc, 您也可以参考官方文档来完成安装 - 安装 Solidity 安装合约编译器 ( 可选 ) 3

8 4 Chapter 1. 准备工作

9 CHAPTER 2 快速入门 如果您还没有完成上一篇中提到的所有准备工作, 请先完成它们, 再继续下一步的操作 本快速入门告诉您如何从源代码构建 Hyperchain, 如何启动一个 Hyperchain 集群 2.1 编译 Hyperchain 拉取代码 克隆代码到您的 GOPATH 工作目录下 : mkdir -p $GOPATH/src/github.com/hyperchain cd $GOPATH/src/github.com/hyperchain git clone 编译代码 请确保您已经安装了正确的 Go 工具, 如有问题, 请参见准备工作. 编译 Hyperchain: cd $GOPATH/src/github.com/hyperchain/hyperchain govendor build 您也可以执行 go build 来编译 2.2 启动 Hyperchain 由于 Hyperchain 集群需要至少 4 个节点建立一个 BFT 系统, 我们建议用以下几种模式启动 Hyperchain 节点 : 单服务器模式 - 本地运行 4 个节点 多服务器模式 - 多服务器运行 4 个节点 5

10 2.2.1 单服务器模式 - 本地运行 4 个节点 我们提供了一个工具脚本名为 local.sh, 可以用来快速部署运行本地 4 个 Hyperchain 节点 cd $GOPATH/src/github.com/hyperchain/hyperchain/scripts./local.sh 如果脚本输出以下信息, 说明 Hyperchian 节点已经正常运行了 $./local.sh start up node 1... done start up node 2... done start up node 3... done start up node 4... done 多服务器模式 - 多服务器运行 4 个节点 SSH 免密通路 因为我们使用的 server.sh 工具脚本在执行 ssh 操作时, 会提示输入远程服务器的密码, 所以我们建议您打通与远程服务器之间的 SSH 免密通路 1. 本地节点生成 SSH 秘钥对, 密码请设置为空 : ssh-keygen Generating public/private key pair. Enter file in which to save the key (/home/hyperchain/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/hyperchain/.ssh/id_rsa. Your public key has been saved in /home/hyperchain/.ssh/id_rsa.pub. 2. 将 SSH 公钥拷贝到 Hyperchain 节点, 请用您远程服务器上的用户名代替以下命令中的 username ssh-copy-id username@node1 ssh-copy-id username@node2 ssh-copy-id username@node3 ssh-copy-id username@node4 分发部署 Hyperchain 我们提供了一个工具脚本名为 server.sh, 可以用来快速分发到 4 个节点部署运 Hyperchain 1. 首先请您将 4 台服务器的 IP 地址填入到 hyperchain/scripts 目录下的 serverlist.txt 文件中 格式如下所示 : $ cat $GOPATH/src/github.com/hyperchain/hyperchain/scripts/serverlist.txt 使用 server.sh 启动远程多个 Hyperchain 节点 cd $GOPATH/src/github.com/hyperchain/hyperchain/scripts./server.sh 6 Chapter 2. 快速入门

11 如果脚本输出以下信息, 说明 Hyperchian 节点已经正常运行了 $./server.sh start up node 1... done start up node 2... done start up node 3... done start up node 4... done 2.2. 启动 Hyperchain 7

12 8 Chapter 2. 快速入门

13 CHAPTER 3 Hyperchain 使用示例 在这一节中, 我们将会用一些例子, 来介绍一下 Hyperchain 平台的简单使用方法 3.1 HyperCli 我们推荐使用 HyperCli 作为您的管理工具 HyperCli 是一个基于 Hyperchain 平台开发的命令行工具, 方便管理员操作 Hyperchain 平台 HyperCli 提供了丰富的命令行接口, 下面我们会介绍它的智能合约 交易处理等相关功能 编译 HyperCli: cd $GOPATH/src/github.com/hyperchain/hyperchain/hypercli govendor build 您也可以执行 go build 来编译 注解 : 默认情况下,HyperCli 是给 localhost:8081 发送消息的, 所以我们建议您在 Hyperchain 节点服务器上运行 HyperCli 如果您希望在本地执行 HyperCli, 那么就需要指定 --host 和 --port 选项来设置远程 Hyperchain 节点的地址和 JSON-RPC 端口 3.2 合约样例 1 - Set/Get Hash 这里是一个实现 sethash 和 gethash 功能的智能合约 contract Anchor mapping(bytes32 => bytes32) hashmap; function sethash(bytes32 key,bytes32 value) returns(bool,bytes32) if(hashmap[key]!= 0x0) return (false,"the key exist"); hashmap[key] = value; return (true,"success"); 9

14 function gethash(bytes32 key) returns(bool,bytes32,bytes32) if(hashmap[key] == 0x0) return (false,"the key is not exist",0x0); return (true,"success",hashmap[key]); 编译合约 如果您已经安装了 solc, 您只需通过一个简单的命令就能得到合约的字节码 如果您没有安装编译器, 也可以直接使用以下的字节码, 该字节码是本合约的编译结果 字节码 0x c f e060020a cf5040a d7fa10 假设您的智能合约文件名为 sample1.sol, 您可以通过以下命令获得合约字节码 : solc --bin sample1.sol 部署合约 HyperCli 提供了一个合约部署的功能, 以下是该功能的参数 : $./hypercli contract deploy --help NAME: hypercli contract deploy - Deploy a contract USAGE: hypercli contract deploy [command options] [arguments...] OPTIONS: --namespace value, -n value specify the namespace, default to global (default: "global") --from value, -f value specify the account (default: "000f1a7a08ccc48e5d30f80850cf1cf283aa3abd") --payload value, -p value specify the contract payload --extra value, -e value specify the extra information --simulate, -s simulate execute or not, default to false --directory value, -d value specify the contract file directory 您可以将合约的字节码作为 --payload 选项的值, 使用以下的命令来部署合约 :./hypercli contract deploy --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x c f e060020a cf5040a d7fa 该命令的意思是 HyperCli 使用地址为 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd 的账户来部署合约 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xb1b7d4f083ac65679ddd31a9b864fc8ca1ec75eee2f7a46cca1b223eae94527c","vmType": "EVM","contractAddress":"0xbbe2b6412ccf de8958f2acc76cda9c9","gasUsed ":69660,"ret": "0x e060020a cf5040a d7fa b575b b ","log":[] 10 Chapter 3. Hyperchain 使用示例

15 从结果中可以得到部署后的合约地址, 在这个例子中, 合约地址为 : 0xbbe2b6412ccf de8958f2acc76cda9c9 之后它将会被用于合约调用的操作中 调用合约 HyperCli 提供了一个合约调用的功能, 以下是该功能的参数 : $./hypercli contract invoke --help NAME: hypercli contract invoke - Invoke a contract USAGE: hypercli contract invoke [command options] [arguments...] OPTIONS: --namespace value, -n value specify the namespace, default to global (default: "global") --from value, -f value specify the account (default: "000f1a7a08ccc48e5d30f80850cf1cf283aa3abd") --payload value, -p value specify the contract payload --to value, -t value specify the contract address --extra value, -e value specify the extra information --simulate, -s simulate execute or not, default to false --args value, -a value specify the args of invoke contract 在本例中, 您至少需要指定两个参数的值, 才能调用合约中的函数 : payload 选项 : 函数调用的字节码 to 选项 : 合约地址 我们提供了一些函数调用的字节码, 您可以直接使用它们 sethash 调用 sethash 函数, 设置 key1 = value1, 以下是该调用的字节码 : 0xd7fa10076b c 以下是该合约的地址 : 0xbbe2b6412ccf de8958f2acc76cda9c9 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0xd7fa10076b c to 0xbbe2b6412ccf de8958f2acc76cda9c9 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xa a964f5ab6f4ef355131c0c241388ac6e8548c191aa5b3b94af95571","vmType": "EVM","contractAddress":"0x ","gasUsed ":20477,"ret": "0x ","log":[] 3.2. 合约样例 1 - Set/Get Hash 11

16 gethash 调用 gethash 函数, 获得 key1 对应的 value 值, 以下是该调用的字节码 : 0x3cf5040a6b 以下是该合约的地址 : 0xbbe2b6412ccf de8958f2acc76cda9c9 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x3cf5040a6b to 0xbbe2b6412ccf de8958f2acc76cda9c9 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0x185dba5451ace5ffcf4c11d10968e1e4ed299eb78ca6ddda65539dfca2fc56df","vmType": "EVM","contractAddress":"0x ","gasUsed ":523,"ret": "0x ","log":[] 3.3 合约样例 2 - Simulate Bank 这里是另一个实现了资产管理的合约示例 contract SimulateBank address owner; bytes32 bankname; uint banknum; bool isinvalid; mapping(address => uint) public accounts; function SimulateBank( bytes32 _bankname,uint _banknum,bool _isinvalid) bankname = _bankname; banknum = _banknum; isinvalid = _isinvalid; owner = msg.sender; function issue(address addr,uint number) returns (bool) if(msg.sender==owner) accounts[addr] = accounts[addr] + number; return true; return false; function transfer(address addr1,address addr2,uint amount) returns (bool) if(accounts[addr1] >= amount) accounts[addr1] = accounts[addr1] - amount; accounts[addr2] = accounts[addr2] + amount; return true; return false; 12 Chapter 3. Hyperchain 使用示例

17 function getaccountbalance(address addr) returns(uint) return accounts[addr]; 编译合约 如果您已经安装了 solc, 您只需通过一个简单的命令就能得到合约的字节码 如果您没有安装编译器, 也可以直接使用以下的字节码, 该字节码是本合约的编译结果 字节码 0x c a f 假设您的智能合约文件名为 sample2.sol, 您可以通过以下命令获得合约字节码 : solc --bin sample2.sol 部署合约 HyperCli 提供了一个合约部署的功能, 以下是该功能的参数 : $./hypercli contract deploy --help NAME: hypercli contract deploy - Deploy a contract USAGE: hypercli contract deploy [command options] [arguments...] OPTIONS: --namespace value, -n value specify the namespace, default to global (default: "global") --from value, -f value specify the account (default: "000f1a7a08ccc48e5d30f80850cf1cf283aa3abd") --payload value, -p value specify the contract payload --extra value, -e value specify the extra information --simulate, -s simulate execute or not, default to false --directory value, -d value specify the contract file directory 您可以将合约的字节码作为 --payload 选项的值, 使用以下的命令来部署合约 :./hypercli contract deploy --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x c a f 该命令的意思是 HyperCli 使用地址为 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd 的账户来部署合约 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0x ca4c072f53d1684dff9e080098db931358d8eca04c833373ae580ed9e","vmType": "EVM","contractAddress":"0xbbe2b6412ccf de8958f2acc76cda9c9","gasUsed ":109363,"ret": "0x e060020a e5c06e f b c e9c146100a85 ","log":[] 3.3. 合约样例 2 - Simulate Bank 13

18 从结果中可以得到部署后的合约地址, 在这个例子中, 合约地址为 : 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 之后它将会被用于合约调用的操作中 调用合约 HyperCli 提供了一个合约调用的功能, 以下是该功能的参数 : $./hypercli contract invoke --help NAME: hypercli contract invoke - Invoke a contract USAGE: hypercli contract invoke [command options] [arguments...] OPTIONS: --namespace value, -n value specify the namespace, default to global (default: "global") --from value, -f value specify the account (default: "000f1a7a08ccc48e5d30f80850cf1cf283aa3abd") --payload value, -p value specify the contract payload --to value, -t value specify the contract address --extra value, -e value specify the extra information --simulate, -s simulate execute or not, default to false --args value, -a value specify the args of invoke contract 在本例中, 您至少需要指定两个参数的值, 才能调用合约中的函数 : payload 选项 : 函数调用的字节码 to 选项 : 合约地址 我们提供了一些函数调用的字节码, 您可以直接使用它们 发布资产 调用 issue 函数, 给账户 0x 发布资产 1,000,000,000, 以下是该调用的字节码 : 0x867904b 以下是该合约的地址 : 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x867904b to 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0x9f602fc0c4ac12d383cf765e a0e5daaec666888e242485bd6314e17f9","vmType": "EVM","contractAddress":"0x ","gasUsed ":20498,"ret":"0x ","log":[] 14 Chapter 3. Hyperchain 使用示例

19 交易资产 调用 transfer 函数, 从账户 0x 向账户 0x 转移 1 个资产, 以下是该调用的字节码 : 0xbeabacc 以下是该合约的地址 : 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0xbeabacc to 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0x2d779df9db e98ed db42da6c13a2a6ac5c7ba9c606acecba28","vmType": "EVM","contractAddress":"0x ","gasUsed ":25733,"ret":"0x ","log":[] 查询资产 调用 getaccountbalance 函数, 查询账户 0x 的资产, 以下是该调用的字节码 : 0x93423e9c 以下是该合约的地址 : 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x93423e9c to 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xcca7b19dde84bf de4107ee0b783b6e243176e162a2239bae1f475f7","vmType": "EVM","contractAddress":"0x ","gasUsed ":353,"ret":"0x b9ac9ff", "log":[] 调用 getaccountbalance 函数, 查询账户 0x 的资产, 以下是该调用的字节码 : 0x93423e9c 以下是该合约的地址 : 3.3. 合约样例 2 - Simulate Bank 15

20 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 您可以通过以下命令调用合约 :./hypercli contract invoke --from 000f1a7a08ccc48e5d30f80850cf1cf283aa3abd -- payload 0x93423e9c to 0x1e548137be17e1a11f0642c9e22dfda64e61fe6d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0x04b82a4fcdadcf102d559b4eb6a29030f7ef29195f40a5f9b986021b48b48552","vmType": "EVM","contractAddress":"0x ","gasUsed ":353,"ret":"0x ", "log":[] 3.4 交易处理 HyperCli 提供了交易处理相关的功能, 以下是该功能的参数 : $./hypercli tx --help NAME: hypercli tx - transaction related commands USAGE: hypercli tx command [command options] [arguments...] COMMANDS: send info receipt OPTIONS: --help, -h send normal transactions query the transaction info by hash query the transaction receipt by hash show help 可以看到 tx 命令有三个子命令, 下面我们将介绍这三个命令 发送交易 send 命令可以用来发送普通的交易, 以下是它的参数 : $./hypercli tx send --help NAME: hypercli tx send - send normal transactions USAGE: hypercli tx send [command options] [arguments...] OPTIONS: --count value, -c value send how many transactions (default: 1) --namespace value, -n value specify the namespace to send transactions to (default: "global") --from value, -f value specify the account (default: "000f1a7a08ccc48e5d30f80850cf1cf283aa3abd") --to value, -t value specify the contract address --password value, -p value specify the password used to generate signature (default: "123") 16 Chapter 3. Hyperchain 使用示例

21 --amount value, -a value specify the amount to transfer (default: 0) --extra value, -e value specify the extra information --snapshot value, -s value specify the snapshot ID --simulate simulate execute or not 您可以用以下命令发送交易, 它的意思是连续发送 10 笔交易 :./hypercli tx send -c 10 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xefbc9f9b fbaf64047ad5eff03c40c1c76991b ba3620e2c5ea3","vmType": "EVM","contractAddress":"0x ","gasUsed":0, "ret":"0x0","log":[] "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d","vmType": "EVM","contractAddress":"0x ","gasUsed":0, "ret":"0x0","log":[] 选取结果中的一条 txhash, 它之后将被用于查看交易的信息和回执 在这个例子中, 我们选取这一个 txhash: 0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d 交易信息 info 命令可以用来获取交易的信息, 以下是它的参数 :./hypercli tx info --help NAME: hypercli tx info - query the transaction info by hash USAGE: hypercli tx info [command options] [arguments...] OPTIONS: --hash value specify the tx hash used to query the detailed information --namespace value, -n value specify the namespace to query transaction information (default: "global") 您可以用以下命令获取交易信息, 它的意思是获取某一笔指定 txhash 的交易信息 :./hypercli tx info --hash 0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","hash": "0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d","blockNumber ":"0xf","blockHash": "0x2592e0f3e1f156effe93325a60b be2053aa102eb182bd64f95b28080a","txIndex": "0x0","from":"0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd","to": "0x6201cb ac597faf6fdf1f472edf2a22b89","amount":"0x8","timestamp ": ,"nonce": ,"extra":"","executeTime":"0x5", "payload":"0x0" 3.4. 交易处理 17

22 3.4.3 交易回执 receipt 命令可以用来获取交易的回执, 以下是它的参数 : $./hypercli tx receipt --help NAME: hypercli tx receipt - query the transaction receipt by hash USAGE: hypercli tx receipt [command options] [arguments...] OPTIONS: --hash value receipt --namespace value, -n value (default: "global") specify the tx hash used to query the transaction specify the namespace to query transaction receipt 您可以用以下命令获取交易回执, 它的意思是获取某一笔指定 txhash 的交易回执 :./hypercli tx receipt --hash 0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d 如果命令执行正确, 您将看到以下输出结果 : "jsonrpc":"2.0","namespace":"global","id":1,"code":0,"message":"success","result": "version":"1.3","txhash": "0xc47b64ddad2be542bfdc5164d447317f ac7961c88332b25f04b31783d","vmType": "EVM","contractAddress":"0x ","gasUsed":0, "ret":"0x0","log":[] 18 Chapter 3. Hyperchain 使用示例

23 CHAPTER 4 交易执行流程 本文意在描述一条交易从最初产生到最终上链的交易机制 场景包括发起交易的客户端和与之直连的共识节点 A, 客户端通过 SDK 与共识节点 A 以交易的形式与区块链账本进行交互 ; 共识节点 A 与其他共识节点 B C D... 全连接, 同时共识节点 A 有两个用于备份的记账节点 a1 和 a2 假设 我们假设客户端已经拿到证书管理中心 (CA) 颁发的准入证书 (SDKCert), 智能合约已经部署在同一命名空间的区块链节点上 客户端发起交易 现在要做的是发起一笔交易请求 ( 调用已部署合约中的一个方法 ) 客户端首先通过调用 SDK 的接口初始化一个 HyperchainAPI 对象, 初始化过程中,SDK 会以 SDKCert 和公钥向共识节点 A 请求获取发起交易所需的 TCert 然后通过调用 SDK 的 Transaction 接口生成一条交易,SDK 会用客户端指定的私钥对交易进行签名, 再对交易进行 JSONRPC 协议封装后 19

24 用 TCert 对应的私钥进行消息签名 SDK 与节点间支持 HTTP/HTTPS 短连接和 WebSocket 长连接 节点受理交易, 发送到全网共识节点 节点 A 收到交易后先进行 TCert 验证, 节点只会对通过 TCert 验证的请求进行处理 节点的 API 模块还会做如下交易验证 : (1) 根据流控配置确认是否接受交易请求 ; (2) 验证交易字段的合法性, 包括交易的格式, 是否为空值, 以及时间戳的合法性 ; (3) 是否已经提交过相同交易 ( 重放攻击 ); (4) 验证交易签名 当交易通过以上验证后, 会被提交到共识模块, 共识模块将收到的交易向全网的共识节点进行广播 交易的共识 : 排序, 验证, 写块 交易将会经历共识算法 (RBFT) 的三步走流程 1. 预准备 Pre-Prepare 共识主节点会将一定时间内 ( 或者一定数量 ) 的交易定序后打包成一个区块, 然后发送到全网进行共识 2. 准备 Prepare 所有共识节点对区块进行预处理, 并广播结果哈希 20 Chapter 4. 交易执行流程

25 3. 提交 Commit 所有共识节点写入区块, 并更新区块链账本 在执行过程中发现的非法交易会被存储到数据库的非法交易记录中, 并不会记录到区块链账本上 区块链账本上存储了所有合法交易 所有共识节点在区块成功生成后也会将区块推送到所连接的所有记账节点进行记账 交易回执 SDK 在 Transaction 接口中实现了定时向节点获取交易结果, 即查询交易回执 区块链网络设置的交易打包数量和打包时间会影响交易的延迟 21

26 22 Chapter 4. 交易执行流程

27 CHAPTER 5 共识 概述 共识机制是保证区块链中所有共识节点 ( 即验证节点 :validating peer, VP) 按照相同顺序执行交易 写入账本的基础, 而记账节点 ( 即非验证节点 :non-validating peer, NVP) 只需要从其所连接的共识节点中同步账本信息, 因此无需参与共识 Hyperchain 平台支持可插拔的共识机制, 可以针对区块链的不同应用场景提供不同的共识算法, 当前版本已经实现了 PBFT 算法的改良算法 : 高鲁棒拜占庭容错算法 RBFT(Robust Byzantine Fault Tolerance), 其算法构思来源于多篇论文 ( 尤其是 Aardvark), 后续将陆续支持 RAFT 等共识算法 客户端发送交易到 Hyperchain 平台,API 层解析出交易后转发给共识模块, 共识模块接收并缓存交易到本地的交易池 (TxPool) 中, 交易池承担着缓存交易与打包区块的作用, 因此是作为共识模块的子模块实现的 另外, 共识模块还需要维护一个共识的数据库, 用于存储算法所需的变量以便宕机后的自主恢复, 例如 RBFT 算法需要维护视图,PrePrepare,Prepare,Commit 等共识信息 23

28 RBFT 相关变量 在一个由 N 个节点 (N>=4) 组成的共识网络中,RBFT 最多能容忍 f 个节点的拜占庭错误, 其中 : 而能够保证达成共识的节点个数为 : f = N 1 3 quorum = N + f RBFT 常规流程 RBFT 的常规流程保证了区块链各共识节点以相同的顺序处理来自客户端的交易 RBFT 同 PBFT 的容错能力相同, 需要至少 3f+1 个节点才能容忍 f 个拜占庭错误 下图为最少集群节点数下的共识流程, 其 N=4,f=1 图中的 Primary1 为共识节点动态选举出来的主节点, 负责对客户端发来的交易进行排序打包,Replica2,3,4 为从节点 所有节点执行交易的逻辑相同并能够在主节点失效时参与新主节点的选举 常规流程 RBFT 共识保留了 PBFT 原有的三阶段处理流程 (PrePrepare Prepare Commit) 的同时增加了重要的交易验证 (validate) 环节, 在保证对交易执行顺序达成共识的同时也保证了对区块验证结果的共识 24 Chapter 5. 共识

29 RBFT 常规流程在原生的 PBFT 算法中穿插了交易验证环节, 主节点将交易打包成块后先行验证, 并将验证结果包含到 PrePrepare 消息中进行全网广播, 这样 PrePrepare 消息中既包含了排好序的交易信息也包含了区块验证结果 从节点在收到主节点的 PrePrepare 消息后先检查消息的合法性, 检查通过后广播 Prepare 消息表明本节点同意主节点的排序结果 ; 在收到 (quorum-1) 个 Prepare 消息后从节点才会开始验证区块, 并将验证结果与主节点的验证结果进行比对, 比对结果一致则广播 Commit 表明本节点同意主节点的验证结果, 否则直接发起 ViewChange 表明本节点认为主节点有异常行为 RBFT 常规流程具体分为如下几个步骤 : 1. 交易转发阶段 : 客户端将交易发送到区块链中的任意节点 ( 包括共识节点与记账节点 ), 其中记账节点在收到交易后会主动转发给与其相连的共识节点 ; 而共识节点在收到客户端的交易后将其广播给其他共识节点, 这样所有共识节点的交易池中都会维护一份完整的交易列表 ; 2. PrePrepare 阶段 : 主节点按照如下策略进行打包 : 用户可以根据需求自定义打包的超时时间 (batch timeout) 与打包的最大区块大小 (batch size), 主节点在超时时间内收集到了足够多 ( 超过最大区块大小个数 ) 的交易或者超时时间到达后仍未收集到足够多的交易都会触发主节点的打包事件 主节点将交易按照接收的时间顺序打包成块, 并进行验证, 计算执行结果, 最后将定序好的交易信息连同验证结果等写入 PrePrepare 消息中广播给所有共识节点, 开始三阶段处理流程 ; 3. Prepare 阶段 : 从节点在收到主节点的 PrePrepare 消息后, 首先进行消息合法性检查, 检查当前的视图与区块号等信息, 检查通过后向共识节点广播 Prepare 消息 ; 4. Commit 阶段 : 从节点在收到 (quorum-1) 个 Prepare 消息以及相应的 PrePrepare 消息后进行验证, 并将验证结果与主节点写入 PrePrepare 消息中的验证结果进行比对, 比对结果一致则广播 Commit 表明本节点同意主节点的验证结果, 否则直接发起 ViewChange 表明本节点认为主节点存在异常行为, 需要切换主节点 ; 5. 写入账本 : 所有共识节点在收到 quorum 个 Commit 消息后将执行结果写入本地账本 Hyperchain 通过在共识模块中加入验证机制, 可以保证从节点对主节点的每一次排序打包的结果进行校验, 尽早地发现主节点的拜占庭行为, 提升了系统的稳定性 检查点 为了防止运行过程中产生过多的消息缓存, 共识节点需要定时清理一些无用的消息缓存 RBFT 通过引入 PBFT 算法中的检查点 (checkpoint) 机制进行垃圾回收并将检查点的大小 K 固定设置为 10 节点在写入到 K 的整数倍个区块后达到一个检查点, 并广播该检查点的信息, 待收集到其他 (quorum-1) 个共识 RBFT 常规流程 25

30 节点相同的检查信息后就达到了一个稳定检查点 (stable checkpoint), 随后即可清理该检查点之前的一些消息缓存, 保证了运行过程中消息缓存不会无限制地增长 交易池 交易池是共识节点用于缓存交易的场所, 交易池的存在一方面限制了客户端发送交易的频率, 另一方面也减少了主节点的带宽压力 首先, 通过限制交易池的缓存大小,Hyperchain 平台可以在交易池达到限制大小后拒绝接收来自客户端的交易, 这样, 在合理评估机器性能的情况下, 通过合理设置交易缓存大小, 可以最大限度地利用机器性能而又不至于出现异常 其次, 共识节点在接收到来自客户端的交易后先将其存到自己的交易池中, 随后向全网其他共识节点广播该条交易, 保证了所有共识节点都维护了一份完整的交易列表 ; 主节点在打包后只需要将交易哈希列表放到 PrePrepare 消息中进行广播即可, 而不用将完整的交易列表打包进行广播, 大大减轻了主节点的出口带宽压力 如果从节点在验证之前发现缺少了某些交易, 也只需要向主节点索取缺少的那些交易而不用索取整个区块里面所有的交易 RBFT 视图变更 RBFT 视图变更能够解决主节点成为拜占庭节点的问题 在 RBFT 算法中, 参与共识的节点可根据角色分为主节点和从节点 主节点最重要的功能是将收到的交易按照一定策略打包成块, 为交易定序, 并让所有节点按照此顺序执行 然而, 如果主节点发生宕机 系统错误或者被攻占 ( 即成为拜占庭节点 ), 从节点需要及时发现主节点异常并选举产生新的主节点 这将是所有 BFT 类算法为满足稳定性必须要解决的问题 视图 在 RBFT 与 PBFT 中, 都引入了视图 (View) 概念, 即每次更换一个主节点的同时都会切换视图 目前 RBFT 采用轮换的方式切换主节点, 并且 view 从 0 开始只增不减 当前的 view 和总节点数量 N 决定了主节点 id: P rimaryid = (view + 1) mod N 可检测到的拜占庭行为 目前 RBFT 能够检测到的主节点的拜占庭行为主要有 2 种场景 : 1. 主节点停止工作, 不再发送任何消息 ; 2. 主节点发送错误的消息 对于场景一,RBFT 由 nullrequest 机制保证, 行为正确的主节点会在没有交易发生时, 向所有从节点定时发送 nullrequest 来维持正常连接 如果从节点在规定时间内没有收到 nullrequest, 则会触发 ViewChange 流程选举新的主节点 对于场景二, 从节点会对主节点发出的消息进行验证, 如上一节中提到的包含在 PrePrepare 消息中的验证结果, 如果从节点验证不通过的话, 会直接发起 ViewChange 流程选举新的主节点 此外,RBFT 还提供了可配置的 ViewChangePeriod 选项 用户可以根据需要设置此选项, 每写入一定数量区块后进行主动的 ViewChange 轮换主节点, 一来能够缓解主节点作为打包节点的额外压力, 二来也使所有参与共识的节点都能承担一定的打包工作, 保证了公平性 26 Chapter 5. 共识

31 5.4.3 视图变更流程 上图中,Primary 1 为拜占庭节点, 需要进行 ViewChange 在 RBFT 中的 ViewChange 流程如下 : 1. 从节点在检测到主节点有异常情况 ( 没有按时收到 nullrequest 消息 ) 或者接收到来自其他 f+1 个节点的 ViewChange 消息之后会向全网广播 ViewChange 消息, 自身 view 从 v 更改为 v+1; 2. 新视图中主节点收到 N-f 个 ViewChange 消息后, 根据收到的 ViewChange 消息计算出新视图中主节点开始执行的 checkpoint 和接下来要处理的交易包, 封装进 NewView 消息并广播, 发起 VcReset; 3. 从节点接收到 NewView 消息之后进行消息的验证和对比, 如果通过验证, 进行 VcReset, 如果不通过, 发送 ViewChange 消息, 进行又一轮 ViewChange; 4. 所有节点完成 VcReset 之后向全网广播 FinishVcReset; 5. 每个节点在收到 N-f 个 FinishVcReset 消息之后, 开始处理确定的 checkpoint 后的交易, 完成整个 ViewChange 流程 由于共识模块与执行模块之间是异步通信的, 而 ViewChange 之后执行模块可能存在一些无用的 validate 缓存, 因此共识模块需要在 ViewChange 完成之前通知执行模块清除无用的缓存,RBFT 通过 VcReset 事件主动通知执行模块清除缓存, 并在清理完成之后才能完成 ViewChange RBFT 自主恢复 区块链网络在运行过程中由于网络抖动 突然断电 磁盘故障等原因, 可能会导致部分节点的执行速度落后于大多数节点 在这种场景下, 节点需要能够做到自动恢复才能继续参与后续的共识流程 为了解决这类数据恢复的问题,RBFT 算法提供了一种动态数据自动恢复的机制 (recovery),recovery 通过主动索取现有共识网络中所有节点的视图 最新区块等信息来更新自身的存储状态, 最终同步至整个系统的最新状态 在节点启动 节点重启或者节点落后的时候, 节点将会自动进入 recovery, 同步至整个系统的最新状态 RBFT 自主恢复 27

32 5.5.1 自主恢复流程 上图中,Replica 4 为落后节点, 需要进行 recovery 此节点在 RBFT 中的自动恢复流程如下 : 1. Replica 4 首先广播 NegotiateView 消息, 获取当前其余节点的视图信息 ; 2. 其余三个节点向 Replica 4 发送 NegotiateViewResponse, 返回当前视图信息 3. Replica 4 收到 quorum 个 NegotiateViewResponse 消息后, 更新本节点的视图 ; 4. Replica 4 广播 RecoveryInit 消息到其余节点, 通知其他节点本节点需要进行自动恢复, 请求其余节点的检查点信息和最新区块信息 ; 5. 正常运行节点在收到 RecoveryInit 消息之后, 发送 RecoveryResponse, 将自身的检查点信息以及最新区块信息返回给 Replica 4 节点 ; 6. Replica 4 节点在收到 quorum 个 RecoveryResponse 消息后, 开始尝试从这些 response 中寻找一个全网共识的最高的检查点, 随后将自身的状态更新到该检查点 ; 7. Replica 4 节点向正常运行节点索要检查点之后的 PQC 数据, 最终同步至全网最新的状态 RBFT 节点增删 在联盟链场景下, 由于联盟的扩展或者某些成员的退出, 需要联盟链支持成员的动态进出服务, 而传统的 PBFT 算法不支持节点的动态增删 RBFT 为了能够更加方便地控制联盟成员的准入和准出, 添加了保持集群非停机的情况下动态增删节点的功能 28 Chapter 5. 共识

33 5.6.1 新增节点流程 上图中,Replica 5 为待新增的节点 RBFT 节点的动态新增节点流程如下 : 1. 新增节点 Replica 5 通过读取配置文件信息, 主动向现有节点发起连接, 确认所有节点连接成功后更新自身的路由表, 并发起 recovery; 2. 现有节点接收到 Replica 5 的连接请求后确认同意该节点加入, 然后向全网广播 AddNode 消息, 表明自己同意该新节点加入整个共识网络 ; 3. 当现有节点收到 N 条 (N 为现有区块链共识网络中节点总数 )AddNode 消息后, 更新自身的路由表, 随后开始回应新增节点的共识消息请求 ( 在此之前, 新增节点的所有共识消息是不予处理的 ); 4. Replica 5 完成 recovery 之后, 向全网现有节点广播 ReadyForN 请求 ; 5. 现有节点在收到 ReadyForN 请求后, 重新计算新增节点加入之后的 N,view 等信息, 随后将其与 PQC 消息封装到 AgreeUpdateN 消息中, 进行全网广播 ; 6. Replica 5 加入后的共识网络会产生一个新的主节点, 该主节点在收到 N-f 个 AgreeUpdateN 消息后, 以新的主节点的身份发送 UpdateN 消息 ; 7. 全网所有节点在收到 UpdateN 消息之后确认消息的正确性, 进行 VCReset; 8. 每个节点完成 VCReset 后, 全网广播 FinishUpdate 消息 ; 9. 节点在收到 N-f 个 FinishUpdate 消息后, 处理后续请求, 完成新增节点流程 RBFT 节点增删 29

34 30 Chapter 5. 共识

35 CHAPTER 6 账本 概述 账本是 hyperchain 平台中的重要模块, 负责区块链账本数据的维护与组织 账本数据可以分成两部分 : 区块链数据 账户数据 其中, 区块链数据包括 : 区块 交易 回执等数据 这部分也就是我们传统意义上所说的区块链 而后者指代的是区块链上所有账户状态的集合, 该状态集统称为世界状态 由于需要支持智能合约, 因此 hyperchain 与以太坊一样, 摒弃了比特币的 UTXO 模型而采用账户模型来组织数据, 因而这部分数据称为账户数据 区块链数据主要通过区块的形式进行串联 所有区块被从后向前有序地链接在一个链条里, 每一个区块都指向其父区块 区块中包含了一批交易, 由共识模块负责统一打包并定序 区块链节点在接收到一个区块之后, 在原有的账户状态基础上, 依次执行交易, 在此期间读 / 写相关账户的状态数据 一笔交易执行结束, 也就意味着区块链状态进行了一次变迁 每一笔交易, 在 hyperchain 中都会有一个对应的交易回执或者非法交易记录来表示最终的执行结果 倘若这笔交易是一笔合法的交易, 则执行结束后, 会将该交易执行的结果记录在交易回执中 反之, 会将错误原因记录在一条非法交易记录中 账本中各部分大体的逻辑关系可以如下图所示 区块链数据 在本章中, 将介绍以下几种数据结构之间的关系 : 区块 交易 回执 区块链 非法交易记录 31

36 32 Chapter 6. 账本

37 其中前两类数据结构在区块链网路中组成了 区块链数据, 是区块链网络中进行流转的 共识 数据 ; 后三类数据结构由各节点维护在本地 以上五种数据结构组成了一个节点中所有的区块链数据 区块 区块结构可以分成两部分 : 区块头信息 ; 区块体信息 ; 区块头中主要包含一些区块链的元数据, 包括 :(1) 区块高度 (2) 区块哈希 (3) 父区块哈希 (4) 账户状态哈希 (5) 交易集哈希 (6) 回执集哈希 (7) 时间戳 (8) 日志过滤数据 区块体内包含所有的交易数据 区块的主要作用是封装交易数据, 记录区块链状态数据 交易 交易是由外部用户发起的, 在交易体中记录了用户指定的调用信息 交易根据是否执行智能合约可以分为两类 : 普通交易 ; 合约交易 ; 合约部署 合约调用 前者表示交易执行过程中不触发智能合约的运行, 仅进行 hyperchain 提供的 token 的转账 ; 后者表示交易执行过程中会触发智能合约的运行 后者又可以分为 :(1) 合约部署交易 (2) 合约调用交易 交易体包含如下字段 : 版本号 : 指明该交易数据结构定义的版本信息, 便于向后兼容 ; 交易发起者 : 长度为 20 字节的交易发起者的标识信息 ; 交易接收者 : 长度为 20 字节的交易接收者的标识信息, 若本交易是合约调用交易, 该字段为被调合约的地址, 若该字段为空, 则表明本交易为部署合约交易 ; 调用信息 : 若本交易为普通交易, 在调用信息中指定需要转账的 token 数量 ; 若本交易为合约调用交易, 在调用信息中指定需要调用的函数以及调用参数 ; 若本交易为合约部署交易, 则需要在调用信息中指定合约的二进制代码 ; 随机值 :uint64 的随机值 ( 避免产生哈希相同的交易, 防止重放攻击 ); 交易签名 : 用户利用自己的私钥对 (1) 交易发起者 (2) 交易接收者 (3) 调用信息 (4) 时间戳 (5) 随机值五个字段的内容进行签名, 产生的签名内容填在该字段, 防止交易的内容被篡改 ; 交易哈希 : 将上述 (1)-(5) 字段加上交易签名一起进行哈希计算, 获得一个哈希标识用于表示本交易 区块链数据 33

38 6.2.3 回执每一笔合法的交易, 其执行结果都会被封装成一个交易回执存储在区块链上 交易回执包括 : 版本号 : 指明该回执数据结构定义的版本信息, 便于向后兼容 ; 交易哈希 : 与该回执相关的交易哈希 ; 合约地址 : 若该交易为部署合约交易, 则新部署的合约地址被放置在该字段, 否则该字段为空 ; 执行结果 : 若该交易为调用合约交易, 则执行结果被放置在该字段, 否则该字段为空 ; 虚拟机日志 : 智能合约运行过程中, 可能会产生一系列日志, 这些日志数据被放置在该字段中 ; 智能合约类型 : 用于表示智能合约的类型,EVM,JVM 或是其他类型 ; 非法交易记录 每一笔非法的交易, 其错误信息会被封装成一个非法交易记录, 存储在节点本地 除了与之相关的交易数据, 非法记录中还会记载具体的错误原因, 例如 :(1) 余额不足 (2) 合约调用参数错误 (3) 调用权限不够等 区块链 一个本地的节点会维护一些区块链元数据以便用户进行查询, 因此在 hyperchain 中, 有个名为 chain 的数据结构, 记录了这些数据, 包括 : 最新父区块哈希 最新区块哈希 最新区块高度 创世区块高度 ( 默认为 0, 数据归档 / 数据恢复等操作会影响该高度的值 ) 交易总数 额外数据 共识比较 区块链节点在执行完一个区块中所有的交易后, 需要将本次区块处理得到的 结果 在节点间进行比较, 只有大多数节点 ( 超过 quorum 个 ) 拥有与之相同的结果时, 才会将本次执行结果提交到数据库中 而表示本区块执行结果的标识是由以下几个内容组成 : 世界状态哈希 : 交易执行过程中会更改账户状态数据, 当一个区块中所有的交易执行结束后, 会利用 bucket tree 对账户集合状态进行哈希重计算, 计算结果便是世界状态哈希 ; 交易集哈希 : 利用区块中每一笔交易的 * 重要字段 * 作为 sha256 算法的输入, 计算得到一个用于表示整个交易集的哈希标识 重要字段为 :(1) 交易发起者 (2) 交易接收者 (3) 调用信息 (4) 时间戳 (5) 随机值 ; 回执集哈希 : 利用区块中每一个回执的 * 重要字段 * 作为 sha256 算法的输入, 计算得到一个用于表示整个回执集的哈希标识 重要字段为 :(1) 虚拟机执行计数器 (2) 执行结果 (3) 虚拟机执行日志 ; 34 Chapter 6. 账本

39 账户数据 之前提及的区块链数据, 其实可以总结为是合约调用信息的流水集合 而智能合约在运行过程中, 需要读 / 写合约状态数据 接下来就介绍这部分数据的组织结构 由于 hyperchain 需要兼容 EVM(Ethereum Virtual Machine), 而 EVM 与以太坊的账户体系有着较强的耦合性, 因此,hyperchain 的 state 是在以太坊的基础上, 做了一系列的改造及优化得到 账户类别 与以太坊一样,hyperchain 中的账户也可以分为两类 : 外部账户 : 外部账户的私钥由用户自己控制, 可以主动发起交易, 且这类账户不包含智能合约代码 合约账户 : 合约账户包含一段可执行的智能合约代码, 且有自己的存储空间用来存储自身的状态变量 该智能合约的运行可以由外部账户发起交易进行触发, 也可以由其他合约 主动调用 进行触发 虽然两类账户在逻辑上有所区别, 但是共享一套定义 : 一个账户的元数据包括以下字段 : 账户地址 (20 字节, 由哈希函数根据一定的输入产生, 不考虑哈希冲突的情况下, 不会有两个相同地址的账户 ); 余额 : 该余额表示该账户所拥有的 hyperchain 平台的 token 个数, 这类 token 可以通过智能合约进行操控, 也可以通过发起普通交易转账进行交易 ; 状态变量 ( 存储空间 ) 哈希标识 : 一个合约账户, 需要存储其所有的状态变量, 一个用于表示这些状态变量的哈希值被存储在该字段 ; 合约代码哈希 : 智能合约代码哈希标识 ; 状态 : 合约状态, 普通 冻结等 ; 部署时间 : 若该账户为合约账户, 则会记录该账户第一次被部署的时间点 ; 创建者地址 : 若该账户为合约账户, 则会记录该账户的创建者信息 ; 已部署的合约地址列表 : 若该账户为外部账户, 则会记录该账户部署的所有合约账户的地址 ; 账户数据 35

40 除了以上这些 简短 的数据被放置在账户元数据里, 还有 (1) 合约源码 (2) 状态变量这些需要大量存储空间的数据被直接存储, 在元数据中只存储这类数据的哈希值 合约的状态变量, 其实是一系列的 kv 键值对 在 hyperchain 中, 每个合约账户, 都会有一棵 bucket tree, 专门用来计算该合约的状态变量哈希 每次执行一笔交易, 修改一系列状态变量, 从底层来看, 其实就是更新了一批 kv 对, 而这些修改集刚好可以作为 bucket tree 的输入, 以便快速地计算 新 的状态变量哈希 账户集 hyperchain 将每一个账户的元数据进行序列化, 将序列化得到的二进制作为一个账户的内容 所有的账户数据, 最终可以转换成一系列的 kv 对,key 为该账户的地址,value 为元数据序列化的内容 对于账户集, 会有一棵全局级别的 bucket tree 进行账户数据的哈希计算, 示意图如上所示 每个账户数据仅作为 bucket tree 中的一条数据项, 不断进行哈希计算, 最终生成一个根节点, 该节点的哈希值 (merkle root) 便是整个账户集的哈希标识 该哈希值作为整个账户集的状态表示, 不仅是共识阶段比较的依据之一, 之后更是会被记录在区块头中 原子性 hyperchain 利用底层数据库 leveldb 提供的 batch 来保障账本的原子性 hyperchain 采用 rbft 作为共识算法, 因此整个处理流程会分成 3 阶段来完成 在执行阶段, 所有对账本的改动会预先保存在一个 leveldb 的 batch 中 ; 当本次执行的结果得到了足够多节点的认可, 会从缓存中取出该 batch, 将所有的修改落盘 36 Chapter 6. 账本

41 CHAPTER 7 Bucket tree 7.1 概述 在 hyperchain 中, 账本数据可以分成两部分 : 区块链数据 账户数据 其中, 区块链数据包括 : 区块 交易 回执等数据 这部分也就是我们传统意义上所说的区块链 所有区块被从后向前有序地链接在这个链条里, 每一个区块都指向其父区块 区块中包含了一批交易, 由共识模块负责将接收到的交易统一定序并打包成一个区块进行分发 区块链节点在接收到一个区块之后, 在原有的状态基础上, 依次执行交易, 在此期间读 / 写相关账户的状态数据 ; 执行结束, 将期间所有的账本改动统一写入 每一笔交易的执行, 都意味着区块链进行了一次状态变迁 在这里, 区块链状态指代的是区块链上所有账户状态的集合, 该状态集统称为世界状态 由于支持智能合约, 因此与以太坊一样,hyperchain 摒弃了比特币的 UTXO 模型而采用账户模型来组织数据, 因而这部分数据称为账户数据 所以,hyperchain 的账本体系可以大致分为上述两部分, 架构示意图如下所示 在本文中我们不展开对账本结构的讨论 而来讨论一种用来快速计算账户集状态的树结构 - bucket tree 在 hyperchain 中, 每执行完一个区块, 各个节点需要在共识的第三阶段比较执行的结果是否一致 也就是说, 每个节点在执行完一个区块后, 账户数据需要保持一致 因此,hyperchain 中使用了一种 bucket tree 的结构对账户数据进行哈希计算, 节点间只需要通过比较该哈希值就能判断账户数据的一致性 注解 : 值得注意的是,bucket tree 并不组织和维护账户数据, 而仅仅只是进行状态的哈希计算 bucket tree 有以下特点 : 提供了一种快速计算账户数据哈希标示的机制 ; 提供了账本回滚的机制 ; hyperchain 中的 bucket tree 思想最早从 fabric 项目中借鉴得到, 进行了一系列的重构和优化, 使得最终的性能表现符合生产需求 下文中, 将详细介绍这种树的结构 主要操作以及最终的性能表现 37

42 38 Chapter 7. Bucket tree

43 7.2 结构解析 bucket tree 其实是揉合了两种不同的数据结构组合而成, 这两种数据结构为 : merkle 树 哈希表因此在介绍 bucket tree 的结构之前, 我们首先简要地介绍一下上述两种数据结构 merkle 树 Merkle 树是由计算机科学家 Ralph Merkle 在很多年前提出的, 并以他本人的名字来命名, 在比特币网络中用到了这种数据结构来进行数据正确性的验证 在比特币网络中,merkle 树被用来归纳一个区块中的所有交易, 同时生成整个交易集合的数字指纹 此外, 由于 merkle 树的存在, 使得在比特币这种公链的场景下, 扩展一种 轻节点 实现简单支付验证变成可能 特点 原理 默克尔树是一种树, 大多数是二叉树, 也可以多叉树, 无论是几叉树, 它都具有树结构的所有特点 ; 默克尔树叶子节点的 value 是数据项的内容, 或者是数据项的哈希值 ; 非叶子节点的 value 根据其孩子节点的信息, 进行 Hash 计算得到的 ; 在比特币网络中,merkle 树是自底向上构建的 在下图的例子中, 首先将 ENTRY1-ENTRY4 四个单元数据哈希化, 然后将哈希值存储至相应的叶子节点 这些节点是 Hash0-0, Hash0-1, Hash1-0, Hash1-1 将相邻两个节点的哈希值合并成一个字符串, 然后计算这个字符串的哈希, 得到的就是这两个节点的父节点的哈希值 7.2. 结构解析 39

44 如果该层的树节点个数是单数, 那么对于最后剩下的树节点, 这种情况就直接对它进行哈希运算, 其父节点的哈希就是其哈希值的哈希值 ( 对于单数个叶子节点, 有着不同的处理方法, 也可以采用复制最后一个叶子节点凑齐偶数个叶子节点的方式 ) 循环重复上述计算过程, 最后计算得到最后一个节点的哈希值, 将该节点的哈希值作为整棵树的哈希 若两棵树的根哈希一致, 则这两棵树的结构 节点的内容必然相同 采用 merkle 树的优势是 : 当某一个节点的内容发生变化时, 仅需要重新计算从该节点到根节点路径上所有树节点的哈希, 即可重新得到一个可以代表整棵树状态的哈希值 也正是因为 merkle 树的这个特点, 使得 bucket tree 能够避免许多不必要的计算开销, 拥有快速计算账户状态哈希的能力 哈希表 哈希表, 也称散列表, 是大家非常熟悉的数据结构, 是根据键 (key) 而直接访问在内存存储位置的 也就是说, 它通过计算一个关于键值的函数, 将所需查询的数据映射到表中一个位置来访问记录, 这加快了查找速度 这个映射函数称做散列函数, 存放记录的数组称做散列表 有关于哈希表的描述, 在此就不再赘述了 在 bucket tree 中, 使用哈希表来维护原始的数据 bucket tree bucket tree 由两部分组成 : 底层的哈希表以及上层的默克尔树 也就是 bucket tree 其实是一棵建立在哈希表上的默克尔树 哈希表由一系列哈希桶 (bucket) 组成, 每个桶中存储着若干被散列到该桶中的数据项 (entry), 所有数据项按序排列 每一个桶有一个哈希值用来表示整个哈希桶的状态, 该哈希值是根据桶内所有数据项的内容进行哈希计算得到 除了底层的哈希表以外, 上层是一系列的 merkle 树节点 一个 merkle 树节点对应着下一层的 n 个哈希桶或者 merkle 树节点 这个 n 也称作 merkle 树的聚合度 该 merkle 树节点中维护着这 n 个孩子节点的哈希值, 且 merkle 树节点本身的哈希值是根据这 n 个孩子节点的哈希值计算得到 如此不断迭代, 最终最上层的树节点是整棵树的根节点, 该节点的哈希值就代表着整棵树的哈希 如此设计的目的是 : 利用 merkle 树的特点, 使得每次树状态改变, 重新哈希计算的计算代价最小 ; 利用哈希表进行底层数据的维护, 使得数据项均匀分布 ; 40 Chapter 7. Bucket tree

45 例如上图中, 一条新的数据项 entry5 插入, 该数据项被散列到 POS 为 2 的桶中 该桶, 即从该桶至根节点上所有的节点被标为粉红色, 即为脏节点 仅对这些脏节点进行哈希重计算, 便可得到一个新的哈希值用来代表新的树状态 由于 bucket tree 是一棵固定大小的树 ( 即底层的哈希表容量在树初始化之后, 就无法更改了 ), 随着数据量的增大, 采用散列函数将所有的数据项进行均匀散列可以避免数据聚集的情况发生 此外,bucket tree 有两个重要的可调参数 : capacity aggreation 前者表示哈希表的容量, 该值越大, 整棵树相对来说能够容纳的数据项的个数就越多, 在聚合度不变的前提下, 树高越高, 从叶子节点到根节点路径上的树节点个数也越多, 哈希计算次数增加 ; 后者表示一个父节点对应的孩子节点的个数, 该值越大, 表示树的收敛速度越快, 在哈希表容量不变的前提下, 树高更低, 从叶子节点到根节点路径上的树节点个数也越少, 哈希计算次数减少 ; 但是每个默克尔树节点的 size 就越大, 增加数据库 IO 开销 ; 哈希桶 哈希桶的定义如下, 由一系列的数据项组成, 注意这些数据项是按 key 的字典序排序的, 每一个数据项即代表了一条用户数据 ( 可以优化为仅存储用户数据的哈希值 ) type Bucket []*DataEntry merkle 节点 merkle 节点的定义如下, 主要的字段为与其相关的孩子节点列表, 该列表中的每一个元素都是一个孩子节点的哈希值 // MerkleNode merklenode represents a tree node except the lowest level's hash bucket. // Each node contains a list of children's hash. It's hash is derived from children 's content 结构解析 41

46 // If the aggreation is larger(children number is increased), the size of a merkle node will increase too. type MerkleNode struct pos *Position children [][]byte dirty []bool deleted bool lock sync.rwmutex log *logging.logger 7.3 核心操作 bucket tree 的计算过程可以分为以下四阶段 : 1. Initialize 2. Prepare 3. Process 4. Commit Initialize 在初始化阶段, 主要进行构建树形态的构建,cache 的初始化以及历史数据的恢复 ( 从 db 中读取最新的根节点的哈希 ) 所谓树形态的构建就是利用用户配置的 capacity 及 aggreation 两个参数构建树的结构 构建函数如下 : var ( curlevel int cursize int = cap levelinfo = make(map[int]int) ) levelinfo[curlevel] = cursize for cursize > 1 parsize := cursize / aggr // 根据收敛系数计算下一层的节点个数 if cursize%aggr!= 0 parsize++ cursize = parsize curlevel++ levelinfo[curlevel] = cursize conf.lowest = curlevel for k, v := range levelinfo conf.levelinfo[conf.lowest-k] = v // 将每一层的节点个数信息倒置, 使得根节点处于 0 层, 哈希桶处于最高层 42 Chapter 7. Bucket tree

47 此外,bucket tree 为了 (1) 增加读取的效率 (2) 防止写丢失, 增加了两个 cache 用于缓存哈希桶和 merkle 节点的数据 这两个 cache 都是利用 LRUCache 实现的, 每次更新时都会同步地更新 cache 中的内容 如此, 下一次 bucket tree 进行哈希计算时, 便可以从 cache 中命中热数据, 尽量避免磁盘的读取 至于防止写丢失是因为在 hyperchain 中,validation 和 commit 是两个独立异步的过程, 因此在进行完区块 100 的 validation 过程时, 可能会立刻基于 100 的状态直接进行区块 101 的 validation 而此时区块 100 执行过程中对账本的修改还没有被提交的数据库中, 因此为了 防止写丢失, 这些内容需要从缓存中命中 倘若此刻 cache 发生了容量过小未提交的内容被驱除的情况, 就会导致区块 101 的 validation 的结果与其他节点不一致 ( 通常为主节点 ), 此时会依赖于 RBFT 算法进行故障处理 其中 bucketcache 是用来存储哈希桶的数据, 每一个哈希桶为一个 cache 数据项 存在的问题是, 一个哈希桶本身由若干条数据项组成, 随着运行时间增长, 一个哈希桶的 size 会越来越大, 导致内存占用量不断上升 merklenodecache 是用来存储除最高层以外的所有 merkle 节点数据的,merkle 节点个数是固定的, 每个节点的 size 也是有上限的, 因此 merklenodecache 不存在内容占用量变大的问题 Prepare 在准备阶段,bucket tree 会接收由用户传入的修改集, 并利用修改集的内容构建脏的哈希桶集 注意, 返回的哈希桶中, 内部的数据项是按字典序升序排列的 func newbuckets(prefix string, entries Entries) *Buckets buckets := &Bucketsmake(map[Position]Bucket) for key, value := range entries buckets.add(prefix, key, value) for _, bucket := range buckets.data sort.sort(bucket) return buckets Process process 也就是哈希重计算阶段, 可以分为两部分 (1) 脏哈希桶的哈希重计算 (2) 脏 merkle 节点的哈希重计算 脏哈希桶计算 如上图所示, 在 bucket tree 中新插入两条数据项 entry5, entry6 entry5 得到的散列地址为 Pos2,entry6 得到的散列地址为 Pos5 哈希桶计算存在一个合并的操作, 即在 Pos2, 需要将新插入的数据, 与历史的数据进行一个合并, 且按照固定的排序算法进行重排序, 最终得到一个新的哈希桶, 包含了所有的新旧数据, 且按序排列 每个哈希桶的哈希值为当前桶中数据的进行哈希计算得到的结果 如图所示,Pos2 与 Pos5 为两个脏的哈希桶, 计算完成之后, 将父节点中对应的孩子哈希值置为新的桶哈希值, 即 Merkle1-1,Merkle1-2 为两个脏的 merkle 节点 脏 merkle 节点计算 当哈希桶计算完成之后, 便可以进行 merkle 节点的哈希计算 这步中仅对脏的 merkle 节点进行哈希重计算 注意,merkle 节点的哈希计算是分层进行的 每个 merkle 节点维护其孩子节点的哈希值, 若下一层的孩子节点哈希值发生变化, 会在之前的计算中, 就将最新的哈希值置到父节点中 ; 对于没有发生变化的孩子节点, 直接使用历史的哈希值即可 每个 merkle 节点的哈希值, 为其所有孩子节点哈希值的哈希计算得到 7.3. 核心操作 43

48 7.3.4 Commit 计算完成之后, 需要将最新的哈希桶数据 merkle 节点数据进行持久化 除此以外, 所有的哈希桶数据 merkle 节点数据都会被存储到缓存中, 对于热数据, 既可以提高数据的查找效率, 也可以避免数据的写丢失情况 44 Chapter 7. Bucket tree

49 CHAPTER 8 智能合约 智能合约简介 注解 : 智能合约是指部署在区块链上的一段可以自动执行条款的计算机程序 智能合约能够根据外界输入信息自动执行预先定义好的协议并完成区块链内部相关状态的转移 广泛意义上的智能合约还包括智能合约编程语言 编译器 虚拟机 事件 状态机 容错机制等 其中对智能合约影响较大的是智能合约编程语言以及其执行引擎 智能合约虚拟机一般为了安全起见是作为沙箱被封装起来, 整个执行环境完全被隔离 虚拟机内部执行的智能合约不允许接触网络 文件系统 进程线程等系统资源 不同智能合约的安全性等级 表达的丰富性有所不同,Hyperchain 系统自主研发智能合约的执行引擎 HyperVM 是一种通用智能合约引擎设计, 允许多种不同智能合约引擎接入 目前的实现了兼容 Ethereum 的 Solidity 语言的 HyperEVM 和支持 Java 语言的智能合约引擎 HyperJVM 智能合约引擎 HyperVM HyperVM 是 Hyperchain 自主研发的可插拔智能合约引擎通用框架, 允许不同智能合约执行引擎接入 如下图所示是 HyperVM 的架构示意图,HyperVM 的架构图提供了智能合约编译 执行等相关主要组件 其中,Compiler 提供了智能合约编译相关功能,Interpreter 和 Executor 则提供了智能合约解释以及执行相关功能,State 组件赋予智能合约操作区块链账本的相关功能 Guard 模块提供智能合约安全保障相关机制 45

50 HyperEVM 为了最大程度利用开源社区在智能合约技术方面的研究和积累, 提高智能合约的可重用性以及兼容性 HyperEVM 的实现采用了完全兼容 Ethereum 的智能合约规范, 使用 Solidity 作为智能合约开发语言, 底层使用了优化了的 Ethereum 虚拟机 EVM 如下图所示为 HyperEVM 智能合约执行流程图 : HyperEVM 执行一次交易之后会返回一个执行结果, 系统将其保存在被称为交易回执的变量中, 之后平台客户端可以根据本次的交易哈希进行交易结果的查询 HyperEVM 的执行流程如下 : 1. HyperEVM 接收到上层传递的 transaction, 并进行初步的验证 ; 2. 判断 transaction 类型, 如果是部署合约则执行 3, 否则执行 4; 3. HyperEVM 新建一个合约账户来存储合约地址以及合约编译之后的代码 ; 4. HyperEVM 解析 transaction 中的交易参数等信息, 并调用其执行引擎执行相应的智能合约字节码 ; 5. 指令执行完成之后,HyperEVM 会判断其是否停机, 否的话跳转步骤 2, 否则执行步骤 6; 6. 判断 HyperEVM 的停机状态是否正常, 正常则结束执行, 否则执行步骤 7; 7. 进行 Undo 操作, 状态回滚到本次交易执行之前 执行指令集模块是 HyperEVM 执行模块的核心, 指令的执行模块有两种实现, 分别是基于字节码的执行以及更加复杂高效的即时编译 (Just-in-time compilation) 字节码执行的方式比较简单,HyperEVM 实现的虚拟机会有指令执行单元 该指令执行单元会一直尝试执行指令集, 当指定时间未执行完成, 虚拟机会中断计算逻辑, 返回超时错误信息, 以此防止智能合约中的恶意代码执行 JIT 方式的执行相对复杂, 即时编译也称为及时编译 实时编译, 是动态编译的一种形式, 是一种提高程序运行效率的方法 通常, 程序有两种运行方式 : 静态编译与动态直译 静态编译的程序在执行前全部被翻译为机器码, 而直译执行的则是边翻译边执行 即时编译器则混合了这二者, 一句一句编译源代码, 但是会将翻译过的代码缓存起来以降低性能损耗 相对于静态编译代码, 即时编译的代码可以处理延迟绑定并增强安全性 JIT 模式执行智能合约主要包含以下步骤 : 1. 将所有同智能合约相关的信息封装在合约对象中, 然后会通过该代码的哈希值去查找该合约对象是否已经存储编译 合约对象有四个常见状态, 即 : 合约未知, 合约已编译, 合约准备好通过 JIT 执行, 合约错误 46 Chapter 8. 智能合约

51 图 8.1: hyperevm-flow 智能合约引擎 HyperVM 47

52 2. 如果合约状态是合约准备好通过 JIT 执行, 则 HyperEVM 会选择 JIT 执行器来执行该合约 执行过程中虚拟机将会对编译好的智能合约进一步编译成机器码并对 push jump 等指令进行深度优化 3. 如果合约状态是合约未知的情况下,HyperEVM 首先需要检查虚拟机是否强制 JIT 执行, 如果是则顺序编译并通过 JTI 的指令进行执行 否则, 开启单独线程进行编译, 当前程序仍然通过普通的字节码编译 下次虚拟机执行过程中再次遇到相同编码的合约时, 虚拟机会直接选择经过优化的合约 这样合约的指令集由于经过了优化, 该合约的执行和部署的效率能够获得较大的提高 智能合约使用 基于 Solidity 智能合约案例 编写合约 基于 Solidity 的智能合约同基于 JS 的程序类似, 由一系列变量和相关函数组成 如下所示为模拟简单累加器功能的智能合约 我们以此为例简单介绍基于 Solidity 智能合约的基本组成部分 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; Accumulator 合约说明 : 基于 solidity 的智能合约以关键字 contract 开头, 类似 Java 等语言中的 class 关键字 ; 合约内部可以有变量和函数, 上述 sum 为 uint32 类型的简单变量,Solidity 智能合约还支持 map 等集合类型 ; 合约允许定义执行函数以 function 关键字定义 ; 基于 Solidity 语言编写智能合约的详细规范参考 Solidiy 官方网站 编译合约 Hyperchain 的智能合约的编译既可以采用 Solidity 官方编译器编译, 也可以使用 Hyperchain 提供的智能合约部署 JSON-RPC 的接口进行编译 ( 这种场景需要在安装 Hyperchain 的宿主机安装 Solidity 编译器 sloc) 调用 Hyperchain 编译 Solidity 智能合约命令如下 : curl -X POST --data ' "jsonrpc":"2.0", "namespace":"global", "method":"contract_compilecontract", "params":["contract_code"], "id":1 ' 合约编译接口调用的返回如下 : 48 Chapter 8. 智能合约

53 "namespace":"global", "id": 1, "code": 0, "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 ad " ], "types": [ "Accumulator" ] 其中字段 bin 对应的内容为该合约的字节码表示, 该 bin 内容供后续部署使用 部署合约 Hyperchain 部署 Solidity 命令如下 : curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_deploycontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc ", "nonce": , "payload": "0x ffffffff ae e f e060020a ad ", "signature": "0x388ad7cb71b1281eb5a0746fa8fe6fda006bd28571cbe69947ff0115ff8f3cd00bdf2f45748e0068e ", "timestamp": ],"id":"1"' 部署合约返回如下, 其中 result 字段内容为该合约在区块链中的地址, 后期对该合约的调用需要指定该合约地址 "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x406f89cb205e136411fd7f5befbf8383bbfdec5f6e8bcfe50b16dcff037d1d8a" 智能合约使用 49

54 8.3.5 调用合约 Hyperchain 调用命令如下, 其中 payload 为调用合约中函数以及其参数值的编码结果,to 为所调用合约的地址 curl localhost: data ' "jsonrpc":"2.0", "namespace":"global", "method": "contract_invokecontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload": "0x3ad14af ", "signature": "0xde467ec4c0bd9033bdc3b6faa43a8d3c5dcf393ed9f34ec1c1310b0859a0ecba15c5be4480a9ad2aaaea cb ", "simulate":false, "timestamp": , "to":"0x313bbf563991dc4c1be9d98a058a26108adfcf81" ], "id":"1" ' 合约调用会立即给客户端返回该交易的哈希值, 后期可以根据该交易的哈希值查询具体交易的执行结果 "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed098995c08fde" 50 Chapter 8. 智能合约

55 CHAPTER 9 P2P 概述 P2P 模块是 Hyperchain 底层网络通信模块, 它保证了通信链路的数据传输安全, 用户可以通过配置文件来配置是否启用传输安全 TLS 是否启动数据传输加密 ( 或更换数据加密算法 ) 在该模块中, 物理连接 (Network 层 ) 与逻辑连接分离, 模块整体架构如下图所示 : 51

56 Hypernet Hypernet 作为 Hyperchain 的底层通信基础设施, 通过注册 slot 的形式向上层提供网络通信服务, 其主要的功能包括通信链路的建立, 数据传输, 链路安全, 链路活性控制等功能 其拥有 Server 和 Client 两个重要成员 整体架构图如下 : Server 在 Hypernet 中,Server 负责注册网络插口 (slot) 监听服务 分发来自 Client 的各类消息 网络插口 slot slot 作为 Hypernet 同上层进行通信的主要机制, 其实现其实是一个多维的线程安全的 map 映射, 将相关方法映射到不同的消息处理器中进行处理 slots 作为 Server 成员, 拥有一组对应到不同 namespace 中的 slot, 分别处理来自不同 namespace 消息 Client Client 与 Server 相对应, 主要用于处理不同的消息发送请求 通常一个 Client 对应于多个不同的远端 Server( 因为一个节点会与多个节点相连 ), 并且与不同 Server 通信, 交由 Sever 的信息将会分发到不同的 namespace 中的 slot 去处理 TLS 传输层安全是 Hyperchain 默认开启的功能, 采用 Hyperchain 内部的 TLSCA 签发的证书进行安全通信, 从传输层面保障信息通信的安全性 进一步地, 该选项是可选的 52 Chapter 9. P2P

57 TLS 能够在传输层保障信息传输的安全性, 是目前较为通用的网络传输实施标准, 在几乎所有的网络安全传输中都采用了该技术 P2PManager P2PManager 用于分配不同 namespace 中的 PeerManager, 它在全局中只有一个实例 PeerManager PeerManager 主要负责以下几个部分 : 对外提供不同的消息发送服务接口 ; 提供相应的消息向上推送服务 ; 使用 PeerManagerEventHub 这个消息中间件对 PeerManager 的控制消息进行分发管理, 进行整个逻辑网络的状态维护, 同时承担较为复杂的消息处理逻辑 在整个网络中, 节点可称为 Node 或 Peer, 下面来看这两者的区别 Peer 逻辑上的所有 remote 节点都称为 peer, 一个远端节点对应一个 peer,peer 主要用于处理逻辑上的消息发送请求 其主要工作就是对消息进行加密, 然后调用 Hypernet Client 的对应的消息发送方法, 并且消息中需要附着 namespace 信息 Node Node 即本地节点, 它也是逻辑上的 server, 主要负责逻辑上的节点消息处理, 对从网络中接收到的消息进行解密然后抛给 Hyperchain 消息中间件 eventhub, 由消息中间件识别这是哪一类消息应该交给哪一个模块去处理, 比如共识模块 执行模块 数据传输加密 数据传输加密是指对网络上传输的交易信息和通信消息的加密, 根据用户的需求可以对所有在 Hyperchain 上传输的信息进行加密, 其加密方案同 TLS 类似, 先通过 ECDH 算法协商对应的会话密钥, 然后利用该会话密钥对业务信息进行加密, 对端进行解密 所有的节点之间的通信都会利用不同的会话密钥进行加密 这是对传输层安全的一个补充 目前 hyperchain 的消息可以通过配置进行对称加密, 如果有更加复杂的消息加密需求可以使用该方式进行处理 P2PManager 53

58 54 Chapter 9. P2P

59 CHAPTER 10 数字证书 概述 Hyperchain 是一个联盟链级别的区块链服务平台, 拥有精确的权限控制粒度, 需要通过多级的 CA 证书来进行权限控制 权限控制主要分为两个方面 : 节点权限控制 交易权限控制 首先我们需要知道的是, 权限控制是 Namespace 级别的, 即每个 Namespace 就会拥有一个相应 CaManager 来进行 CA 证书的管理以及 Namespace 级别的权限控制 以下是我们的 PKI 体系 ( 证书体系 ) 图 : 55

60 root.ca( 根证书颁发机构 ): 它代表 PKI 体系中的信任锚 数字证书的验证遵循信任链 根 CA 是 PKI 层次结构中最上层的 CA, 用于签发证书认证机构以及角色证书准入认证机构 eca.ca( 准入证书颁发机构 ): 用于给节点颁发节点准入证书 (ecert) 和 sdk 证书 (sdkcert) rca.ca( 角色证书颁发机构 ): 用于给节点颁发角色证书 (rcert) ecert.cert( 准入证书 ): 准入证书是长期证书, 是颁发给节点的, 用于节点的准入, 若无准入证书, 则该节点无法加入此 Namespace, 同时准入证书也作为交易证书的颁发机构用于颁发交易证书 rcert.cert( 角色证书 ): 角色证书是长期证书, 是颁发给节点的, 用于节点的角色的认证, 若无角色证书, 则此节点为 NVP, 无法参与共识, 反之则为 VP 节点 sdkcert.cert(sdk 证书 ):SDK 证书时颁发给 SDK 的, 用于进行 SDK 的身份认证, 同时 SDK 证书时获取交易证书的 (Tcert) 的判别依据 tcert.cert( 交易证书 ):SDK 发送交易时需携带交易证书, 若无交易证书或证书验证失败, 则抛弃交易 证书简述 Hyperchian 区块链平台证书均符合 ITU-T X.509 国际标准, 它仅包含了公钥信息而没有私钥信息, 是可以公开进行发布的, 所以 X.509 证书对象一般都不需要加密 X.509 证书的格式通常如下 : ---BEGIN CERTIFICATE---...PEM 编码的 X.509 证书内容 ( 省略 ) END CERTIFICATE--- PEM 编码全称是 Privacy Enhanced Mail, 是一种保密邮件的编码标准 通常来说, 对信息的编码过程基本如下 : 信息转换为 ASCII 码或其他编码方式, 比如采用 DER 编码 使用对称加密算法加密经过编码的信息 使用 BASE64 对加密码后的信息进行编码 使用一些头定义对信息进行封装, 主要包含了进行正确解码需要的信息 除此以外 Hyperchain 区块链平台证书内具体包含以下信息 : 1 X.509 版本号 : 指出该证书使用了哪种版本的 X.509 标准, 版本号会影响证书中的一些特定信息 目前的版本是 3 2 证书持有人的公钥 : 包括证书持有人的公钥 算法 ( 指明密钥属于哪种密码系统 ) 的标识符和其他相关的密钥参数 3 证书的序列号 : 由 CA 给予每一个证书分配的唯一的数字型编号, 当证书被取消时, 实际上是将此证书序列号放入由 CA 签发的 CRL(Certificate Revocation List 证书作废表, 或证书黑名单表 ) 中 这也是序列号唯一的原因 4 主题信息 : 证书持有人唯一的标识符 ( 或称 DN-distinguished name) 这个名字在 Internet 上应该是唯一的 DN 由许多部分组成, 看起来象这样 : CN=Bob Allen, OU=Total Network Security Division O=Network Associates, Inc. C=US 这些信息指出该科目的通用名 组织单位 组织和国家或者证书持有人的姓名 服务处所等信息 5 证书的有效期 : 证书起始日期和时间以及终止日期和时间 ; 指明证书在这两个时间内有效 6 认证机构 : 证书发布者, 是签发该证书的实体唯一的 CA 的 X.509 名字 使用该证书意味着信任签发证书的实体 ( 注意 : 在某些情况下, 比如根或顶级 CA 证书, 发布者自己签发证书 ) 7 发布者的数字签名 : 这是使用发布者私钥生成的签名, 以确保这个证书在发放之后没有被撰改过 56 Chapter 10. 数字证书

61 8 签名算法标识符 : 用来指定 CA 签署证书时所使用的签名算法 算法标识符用来指定 CA 签发证书时所使用的公开密钥算法和 HASH 算法 CA 相关配置 CA 所需配置在 namespace.toml 配置文件内, 具体参数如下 : [encryption] [encryption.ecert] eca = "config/certs/eca.cert" ecert = "config/certs/ecert.cert" priv = "config/certs/ecert.priv" [encryption.rcert] #if you do not have rcert, leave this item blank rca = "config/certs/rca.cert" rcert = "config/certs/rcert.cert" priv = "config/certs/rcert.priv" [encryption.tcert] #Tcert whitelist configuration. whitelist = false listdir = "config/certs/tcerts" [encryption.check] enable = true #enable ERCert enablet = false #enable TCert 首先前六个参数, 分别是配置改 Namespace 的相关证书路径, 分别是 eca,ecert 和 ecert 对应的私钥,rcar,rcert 和 rcert 对应的私钥 其次是 TCert 相关配置, 平台支持 TCert 白名单策略, 即在 whitelist=true 时, 即开启 TCert 白名单策略, 在 listdir 参数配置下的 TCert 证书则是立即可用交易证书 反之, 当 whitelist 为 false 时, 则不开启白名单策略, 只有在该交易证书合法性验证通过, 且确定该交易证书确定为本节点且在 Namespace 下颁布的交易证书时才可完全验证通过 最后的两个参数则为配置开关参数,enable 为开启准入证书以及角色证书的校验开关, 反之则不进行验证,enableT 则为开启交易证书验证的开关配置, 只有当该参数置为 true 时才进行交易证书的验证 动态的开关配置也使区块链配台更加灵活 证书获取以及校验流程 ECert 和 RCert 获取准入证书以及角色证书主要是通过线下颁布进行控制, 有 Certgen 证书签发工具进行证书的生成 校验 若 ECert 以及 RCert 校验开关开启, 则具体验证流程如下图所示 : CA 相关配置 57

62 ECert 以及 RCert 在节点初次握手连接时进行了证书的互换以及验证, 由此来确定了节点是否允许入链以及相关连接节点的角色信息 TCert TCert 的获取以及验证的流程图如下图所示 : 58 Chapter 10. 数字证书

63 4.2.1 获取 首先,SDK 或者外部应用需要向连接节点发起 GetTcert 的消息, 该消息需要携带 SDKCert 对该 SDK 或外部应用进行身份认证, 在认证通过后进行 TCert 证书的生成以及颁布 校验 若 SDK 或者外部应用获取 TCert 成功后, 则接下来的交易需要携带相关交易证书给相关节点进行验证, 只有交易证书验证通过后才会进行接下来的交易执行 证书获取以及校验流程 59

64 60 Chapter 10. 数字证书

65 CHAPTER 11 分区共识 概述 Hyperchain 通过 Namespace( 名字空间 ) 机制实现区块链网络内部交易的分区共识 Hyperchain 平台的使用者可以按照名字空间进行业务交易划分, 同一个 Hyperchain 联盟链网络中的节点按照其所参与的业务组成以名字空间为粒度的子区块链网络 名字空间通过业务的交易共识 分发以及存储的物理级别隔离实现业务级别的隐私保护 集群架构 名字空间可以动态创建, 单个 Hyperchain 节点按照其业务需求可以选择参与一个或者多个名字空间 如下图所示是 Namespace 机制的整体集群架构图 六个节点参与两个命名空间的集群示意图,Node1 Node2 Node4 和 Node5 组成 namespace1, 而 Node2 Node3 Node5 和 Node6 组成 namespace2 其中 Node1 和 Node4 仅参与了 namespace1,node3 和 Node6 仅参与了 namespace2, 而 Node2 和 Node4 则同时参与了两个名字空间 名字空间中通过 CA 认证方式控制节点的动态加入和退出, 每个节点可以允许参与到一至多个 Namesapce 中 带特定 Namespace 信息的交易的验证 共识 存储以及传输仅在参与特定 Namespace 的节点之间进行, 不同 Namespace 之间的交易可实现并行执行 如下图所示 Node1 仅能参与 namespace1 中交易的验证以及相应账本的维护而 Node2 能够同时参与 namespace1 和 namespace2 的交易执行和账本维护, 但 Node2 中的 namespace1 和 namespace2 的账本互相隔离互不可见 61

66 节点架构 加入分区共识机制之后的 Hyperchain 单节点将包含一个 NamespaceManager 对象 NamespaceManager 是分区共识机制的关键管理组件, 负责 namespace 的注册 启动 停止 注销等一系列的生命周期状态操作 NamespaceManager 中包含多个 namespace, 此外还包含 JvmManager 和 BloomFilter 具体而言 : JvmManager 负责管理 jvm 执行器,JvmManager 是否开启需要在配置文件中进行配置 ; BloomFilter 为交易的布隆过滤器, 主要负责重复交易的检测, 防止重放攻击 ; 分区共识中的一个分区被称为一个 namespace, 每个 namespace 之间互相隔离, 包括执行空间以及数据存储空间均做到完全隔离 每个节点默认加入到名为 global 的 namespace 中 每个 namespace 包含 consenter,executor,eventhub,peermanager,camanager,requestprocessor 等关键组件, 这几个关键组件实现各自 namespace 的共识服务, 交易执行存储, 模块间异步交互, 节点间通讯 身份认证 交易处理等功能 62 Chapter 11. 分区共识

67 具体而言 : Consenter 提供共识服务, 目前支持 RBFT 算法, 负责对交易进行定序, 保证同一 namespace 内的 hyperchain 节点的账本一致性 ; Executor 为执行器, 执行器主要负责 namespace 中的智能合约的调用以及账本状态的维护 ; EventHub 为事件总线, 是 namespace 内各关键组件间事件进行异步交互的消息中转中心 ; PeerManager 提供节点通讯管理, 负责 namespace 成员之间网络通信 ; CaManager 为证书认证中心, 负责进行互联网上的身份认证 ; RequestProcessor 为请求处理组件 负责处理 JSON-RPC 消息, 最终通过反射调用相应 api Namespace 的生命周期如下图所示 首先在 namespacemanager 中进行注册, 创建并初始化此 namespace 之后 start 此 namespace, 启动 namespace 中所有组件的功能, 进行 Running 状态 Stop 将停止此 namespace 中所有组件, 最后在 namespacemanager 注销此 namespace 系统数据流 在引入 namespace 之后 hyperchain 节点的交易执行流程有所改变, 客户端能够发送交易到其期望的 namespace 交易传递到 hyperchain 平台之后 json rpc 会首先进行参数检查以及签名验证等前期工作, 之后 json rpc 服务会将请求转发到 NamespaceManager,NamespaceManager 在会根据请求中的 namespace 字段信息将交易请求发送到具体的 namespace 进行执行 不同 namespace 之间的交易能够并发执行 对应 系统数据流 63

68 的 namespace 将调用 RequestProcessor 进行交易的处理, 首先检查请求的参数, 如果没有问题, 通过反射调用相应处理函数并返回结果 64 Chapter 11. 分区共识

69 CHAPTER 12 密码学算法 概述 Hyperchain 区块链平台支持多级密码学加密来保证数据安全, 利用了以下密码学算法来保证了数据的安全性问题 : 椭圆曲线数字签名 :secp256k1,secp256r1 对称加密算法 :3DES,AES 密钥交换 :ECDH 密码杂凑算法 :Keccak 椭圆曲线数字签名 椭圆曲线数字签名算法 (ECDSA) 是使用 [ 椭圆曲线密码 (ECC) 对数字签名算法 (DSA) 的模拟 ECDSA 于 1999 年成为 ANSI 标准, 并于 2000 年成为 IEEE 和 NIST 标准 它在 1998 年既已为 ISO 所接受, 并且包含它的其他一些标准亦在 ISO 的考虑之中 与普通的离散对数问题 (discrete logarithm problem DLP) 和大数分解问题 (integer factorization problem IFP) 不同, 椭圆曲线离散对数问题 (elliptic curve discrete logarithm problem ECDLP) 没有亚指数时间的解决方法 因此椭圆曲线密码的单位比特强度要高于其他公钥体制 椭圆曲线的图形如下图所示 : Hyperchain 区块链使用了 secp256k1 曲线对平台交易进行签名验签, 保证交易的正确性以及完整性 同时平台支持利用 secp256r1 曲线对节点间消息进行签名验证, 保证节点间消息通信的完整性以及正确性 节点消息签名可插拔, 可以通过配置文件开启, 配置文件在 namespace.toml 下 : [encryption.check] sign = true #enable Signature 即当 sign=true 时, 需要进行节点间消息的签名验证, 反之则无需验证 对称加密算法 Hyperchain 区块链平台同时支持 AES,3DES 的对称加密算法, 保证节点间的密文传输 65

70 3DES 又称 Triple DES, 是 DES 加密算法的一种模式, 它使用 3 条 56 位的密钥对 3DES 数据进行三次加密 数据加密标准 (DES) 是美国的一种由来已久的加密标准, 它使用对称密钥加密法.DES 使用 56 位密钥和密码块的方法, 而在密码块的方法中, 文本被分成 64 位大小的文本块然后再进行加密 比起最初的 DES,3DES 更为安全 加密算法, 其具体实现如下 : 设 Ek() 和 Dk() 代表 DES 算法的加密和解密过程,K 代表 DES 算法使用的密钥,M 代表明文,C 代表密文, 这样 : 3DES 加密过程为 :C=Ek3(Dk2(Ek1(M))) 3DES 解密过程为 :M=Dk1(EK2(Dk3(C))) AES 又称为高级加密标准, 是美国联邦政府采用的一种区块加密标准 AES 算法基于排列和置换运算,AES 使用几种不同的方法来执行排列和置换运算 AES 是一个迭代的 对称密钥分组的密码, 它可以使用 和 256 位密钥, 并且用 128 位 (16 字节 ) 分组加密和解密数据 与公共密钥密码使用密钥对不同, 对称密钥密码使用相同的密钥加密和解密数据 通过分组密码返回的加密数据的位数与输入数据相同 迭代加密使用一个循环结构, 在该循环中重复置换和替换输入数据 同时 Hyperchain 区块链平台支持对称加密算法的配置选择来对节点消息进行加解密, 配置在 namespace.toml 下 : [encryption.security] algo = "3des" # Selective symmetric encryption algorithm (pure,3des or aes) 支持 pure,3des 以及 aes 三种参数 : pure: 不进行任何加密, 明文传输 3des: 进行 3des 加解密 aes: 进行 aes 加解密 密钥交换算法 ECDH 即 ECC 算法和 DH 结合使用, 用于密钥磋商 交换双方可以在不共享任何秘密的情况下协商出一个密钥 ECC 是建立在基于椭圆曲线的离散对数问题上的密码体制, 给定椭圆曲线上的一个点 P, 一个整数 k, 求解 Q=kP 很容易 ; 给定一个点 P Q, 知道 Q=kP, 求整数 k 却是一个难题 ECDH 即建立在此数学难题之上 同时 Hyperchain 在节点首次握手连接时便进行了密钥的交换, 生成了彼此的共享密钥, 此密钥即为之后节点间对称加密的密钥 密码杂凑算法 密码杂凑算法, 即 Hash 算法,Hyperchain 平台利用 Keccak256 算法, 来进行 Hash 计算, 结算结果用于签名的消息摘要入参, 同时 Hash 算法也可以用来地址 (Address) 的计算 66 Chapter 12. 密码学算法

71 CHAPTER 13 JSON-RPC API 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) 接口设计 Hyperchain 接口主要由六块接口组成 : 1. 交易服务, 方法名前缀为 "tx"; 2. 合约服务, 方法名前缀为 "contract"; 3. 区块服务, 方法名前缀为 "block"; 4. 消息订阅服务, 方法名前缀为 "sub"; 5. 节点服务, 方法名前缀为 "node"; 6. 证书服务, 方法名前缀为 "cert"; 接口设计基于 JSON-RPC 2.0 规范 所有 HTTP 请求均为 POST 请求, 请求的参数包括 : jsonrpc: 指定 JSON-RPC 协议版本的字符串, 如果是 2.0 版本, 则必须准确写为

72 namespace: 表示该条请求发送给哪个分区去处理 method: 表示所要调用方法名称的字符串, 格式为 :( 服务前缀 )_( 方法名 ) params: 调用方法所需要的结构化参数值, 该成员参数可以被省略 id: 已建立客户端的唯一标识 id, 该值必须包含一个字符串 数值 curl -X POST -d '"jsonrpc":"2.0","method":"block_latestblock","namespace":"global ","params":[],"id":1' localhost:8081 返回值格式为 : jsonrpc: 指定 JSON-RPC 协议版本的字符串, 如果是 2.0 版本, 则必须准确写为 2.0 namespace: 表示该条请求所属分区 code: 状态码 若成功, 则为 0, 其他状态码详见表 5-1 message: 错误信息 若成功, 则为 SUCCESS, 否则为错误详细信息 result: 被调用方法成功执行返回的结果 id: 该值应与请求对象中的 id 值保持一致 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.4", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ "version": "1.4", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae ", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x81053a " ] 68 Chapter 13. JSON-RPC API

73 比如, 接口调用成功的话, 返回的字段有 :jsonrpc namespace id code message result, 且 code 值为 0,message 值为 SUCCESS, 用户可通过这两个字段的值来判断接口调用是否成功, 若调用失败, 则 code 为非 0 值,message 为错误信息 code 值的定义如下 : code 含义 0 请求成功 服务端接收到无效的 json 该错误发送于服务器尝试解析 json 文本 无效的请求 ( 比如非法的 JSON 格式 ) 方法不存在或者无效 无效的方法参数 JSON-RPC 内部错误 Hyperchain 内部错误或者空指针或者节点未安装 solidity 环境 查询的数据不存在 余额不足 签名非法 合约部署出错 合约调用出错 系统繁忙 交易重复 合约操作权限不够 ( 合约 ) 账户不存在 namespace 不存在 账本上无区块产生, 查询最新区块的时候可能抛出该错误 订阅不存在 ( 预留状态码 ) 数据归档 快照相关错误 请求未带 cert 或者错误 cert 导致认证失败 请求 tcert 失败 接口概览 Transaction tx_gettransactions tx_getdiscardtransactions tx_gettransactionbyhash tx_gettransactionbyblockhashandindex tx_gettransactionbyblocknumberandindex tx_gettransactionscount tx_gettxavgtimebyblocknumber tx_gettransactionreceipt tx_getblocktransactioncountbyhash tx_getblocktransactioncountbynumber tx_getsignhash tx_gettransactionsbytime tx_getdiscardtransactionsbytime 接口概览 69

74 tx_getbatchtransactions tx_getbatchreceipt Contract contract_compilecontract contract_deploycontract contract_invokecontract contract_getcode contract_getcontractcountbyaddr contract_maintaincontract contract_getstatus contract_getcreator contract_getcreatetime contract_getdeployedlist Block block_latestblock block_getblocks block_getblockbyhash block_getblockbynumber block_getavggeneratetimebyblocknumber block_getblocksbytime block_getgenesisblock block_getchainheight block_getbatchblocksbyhash block_getbatchblocksbynumber Subscription sub_newblocksubscription sub_neweventsubscription sub_getlogs sub_newsystemstatussubscription sub_getsubscriptionchanges sub_unsubscription 70 Chapter 13. JSON-RPC API

75 Node node_getnodes node_getnodehash node_deletevp node_deletenvp Certificate cert_gettcert 接口描述 tx_gettransactions 查询指定区块区间的所有交易 Parameters 1. <Object> from: <blocknumber> - 起始区块号 to: <blocknumber> - 终止区块号 <blocknumber> 可以是十进制整数或者进制字符串, 可以是 latest 字符串表示最新的区块 from 必须小于等于 to, 否则会返回 error Returns 1. [<Transaction>] - Transaction 对象字段如下 : version: <string> - 平台版本号 hash: <string> - 32 字节的十六进制字符串, 交易哈希值 blocknumber: <string> - 十六进制, 交易所在区块的高度 blockhash: <string> - 32 字节的十六进制字符串, 交易所在区块的哈希 txindex: <string> - 十六进制, 交易在区块中的偏移量 from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - 20 字节的十六进制字符串, 交易接收方的地址 amount: <string> - 转账金额 timestamp: <number> - 交易发生的 unix 时间戳 ( 单位 ns) nonce: <number> - 16 位随机数 extra: <string> - 交易的额外信息 executetime: <string> - 交易的处理时间 ( 单位 ms) payload: <string> - 部署合约 调用合约 升级合约的时候才有这个值, 可以通过这个值追溯到合约调用的方法以及调用传入的参数 接口描述 71

76 Example1: 正常的请求 curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactions", "params": ["from": 1, "to": 2], "id": 71' "namespace":"global", "id": 1, "result": [ "version": "1.0", "hash": "0x88d5b325dc9042ff92a9fa26ed8c943719bb049ac7022abd09bb85da36f531e4", "blocknumber": "0x2", "blockhash": "0xc c28ad6d744cb4bbe ba65ad010ce24056b6f8def9fc5cdd5", "txindex": "0x0", "from": "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x ffffffff e e f e060020a ad ", "version": "1.0", "hash": "0xf7149a8349f1853d8d713a15935e5059e6f55c2827f0c88f8414dd0402d6760b", "blocknumber": "0x1", "blockhash": "0x4bab3f9297e737eb197d666a2f08219f94460ace08a8e1ecad87e6e52183bcd5", "txindex": "0x0", "from": "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x7", "payload": "0x ffffffff e e f e060020a ad " ] Example2: 区块不存在 curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactions", "params": ["from": 1, "to": 2], "id": 71' "namespace": "global", 72 Chapter 13. JSON-RPC API

77 "id": 71, "code": , "message": "block number 1 is out of range, and now latest block number is 0" tx_getdiscardtransactions 查询所有非法交易 Parameters 无 Returns 1. [<Transaction>] - Transaction 对象字段如下 : version: <string> - 平台版本号 hash: <string> - 32 字节的十六进制字符串, 交易哈希值 串, 交易所在区块的哈希 from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - 20 字节的十六进制字符串, 交易接收方的地址 amount: <string> - 转账金额 timestamp: <number> - 交易发生的 unix 时间戳 ( 单位 ns) nonce: <number> - 16 位随机数 extra: <string> - 交易的额外信息 payload: <string> - 部署合约 调用合约 升级合约的时候才有这个值, 可以通过这个值追溯到合约调用的方法以及调用传入的参数 invalid: <boolean> - 交易是否不合法 invalidmsg: <string> - 交易的不合法信息 不合法的交易 invalid 值为 true, invalidmsg 可能为 : DEPLOY_CONTRACT_FAILED - 合约部署失败 ; INVOKE_CONTRACT_FAILED - 合约方法调用失败 ; SIGFAILED - 签名非法 ; OUTOFBALANCE - 余额不足 ; INVALID_PERMISSION - 合约操作权限不够 ; Example1: 正常的请求 curl -X POST --data ' "namespace":"global", "method": "tx_ getdiscardtransactions", "params": [], "id": 71' "namespace":"global", "id": 1, 接口描述 73

78 "code": 0, "message": "SUCCESS", "result": [ "version": "", "hash": "0x100ff931204d149f88c0778f6e7b8d4b11ba3c8c720f0cc3e204b ed4", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "payload": "0x ", "invalid": true, "invalidmsg": "DEPLOY_CONTRACT_FAILED" ] Example2: 若没有非法交易 curl -X POST --data ' "namespace":"global", "method": "tx_ getdiscardtransactions", "params": [], "id": 71' "namespace": "global", "id": 1, "code": , "message": "Not found discard transactions " tx_gettransactionbyhash 根据交易哈希查询交易详情 Parameters 1. <string> - 32 字节的十六进制字符串, 交易的哈希值 Returns 1. <Transaction> - Transaction 对象字段如下 : version: <string> - 平台版本号 hash: <string> - 32 字节的十六进制字符串, 交易哈希值 blocknumber: <string> - 十六进制, 交易所在区块的高度 blockhash: <string> - 32 字节的十六进制字符串, 交易所在区块的哈希 txindex: <string> - 十六进制, 交易在区块中的偏移量 from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - 20 字节的十六进制字符串, 交易接收方的地址 74 Chapter 13. JSON-RPC API

79 amount: <string> - 转账金额 timestamp: <number> - 交易发生的 unix 时间戳 ( 单位 ns) nonce: <number> - 16 位随机数 extra: <string> - 交易的额外信息 executetime: <string> - 交易的处理时间 ( 单位 ms) payload: <string> - 部署合约 调用合约 升级合约的时候才有这个值, 可以通过这个值追溯到合约调用的方法以及调用传入的参数 invalid: <boolean> - 交易是否不合法 invalidmsg: <string> - 交易的不合法信息 不合法的交易 invalid 值为 true, invalidmsg 可能为 : OUTOFBALANCE - 余额不足, 对应 code 是 ; SIGFAILED - 签名非法, 对应 code 是 ; DEPLOY_CONTRACT_FAILED - 合约部署失败, 对应 code 是 ; INVOKE_CONTRACT_FAILED - 合约方法调用失败, 对应 code 是 ; INVALID_PERMISSION - 合约操作权限不够, 对应 code 是 ; Example1: 查询合法的交易 curl -X POST --data ' "namespace":"global", "method":"tx_ gettransactionbyhash", "params":[ "0xe652e25e617c5f193b240c0d8ff1941a8cfb1d15434eb b7a aa"], "id": 1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe652e25e617c5f193b240c0d8ff1941a8cfb1d15434eb b7a aa", "blocknumber": "0x4", "blockhash": "0x6ea0c80c1532c273c124511e364fc0a9225e0d129e53249f8e26752ee7d7d989", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x d f e060020a be1c766b c575b600 " 接口描述 75

80 Example2: 查询非法的交易 curl -X POST --data '"jsonrpc":"2.0","method":"tx_gettransactionbyhash","params":[ "0x1f6dc4c744ce5e8a39e6a19f19dc27c99d7efd8e38061e80550bf5e7ab1060e1"],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.3", "hash": "0x1f6dc4c744ce5e8a39e6a19f19dc27c99d7efd8e38061e80550bf5e7ab1060e1", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "payload": "0x fd5b5b fd5b5b5b d f ", "invalid": true, "invalidmsg": "DEPLOY_CONTRACT_FAILED" Example3: 查询的交易不存在 curl -X POST --data ' "namespace":"global", "method":"tx_ gettransactionbyhash", "params":[" 0x0e707231fd779779ce25a06f51aec60faed8bf6907e6d74fb11a3fd585831a7e"], "id": 1' "namespace": "global", "id": 1, "code": , "message": "Not found transaction 0x0e707231fd779779ce25a06f51aec60faed8bf6907e6d74fb11a3fd585831a7e" tx_gettransactionbyblockhashandindex 根据区块哈希和交易偏移量查询交易 Parameters 1. <string> - 32 字节的十六进制字符串, 区块的哈希值 2. <number> - 交易在区块中的偏移量, 可以是十进制整数或进制字符串 76 Chapter 13. JSON-RPC API

81 Returns 1. <Transaction> - Transaction 对象字段见合法交易. Example1: 正常的请求 curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactionsbyblockhashandindex","params": [ "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", 0], "id": 71' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe81d39df11779c7f83e6073cc659c7ee85708c135b6557d318e765b9f938c02f", "blocknumber": "0x2", "blockhash": "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x6fd7cc b " Example2: 查询的区块不存在 curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactionsbyblockhashandindex","params": [ "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", 0], "id": 71' "namespace": "global", "id": 71, "code": , "message": "Not found block 0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9" 接口描述 77

82 tx_gettransactionbyblocknumberandindex 根据区块号和交易偏移量查询交易 Parameters 1. <blocknumber> - 区块号, 可以是十进制整数 进制字符串或 latest 字符串表示最新的区块 2. <number> - 交易在区块中的偏移量, 可以是十进制整数或进制字符串 Returns 1. <Transaction> - Transaction 对象字段见合法交易. Example1: 正常的请求 curl -X POST --data ' "namespace":"global", "method": gettransactionbyblocknumberandindex", "params": [2,0], "id": 71' "tx_ "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.0", "hash": "0xe81d39df11779c7f83e6073cc659c7ee85708c135b6557d318e765b9f938c02f", "blocknumber": "0x2", "blockhash": "0xd198976fa8b4ca2de6b1b137552b84dc08b7cdcbebbf9388add88f4710fd2cf9", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x6fd7cc b " Example2: 请求的区块不存在 curl -X POST --data ' "namespace":"global", "method": gettransactionsbyblocknumberandindex", "params": [2,0], "id": 71' "tx_ "namespace": "global", 78 Chapter 13. JSON-RPC API

83 "id": 71, "code": , "message": "block number 2 is out of range, and now latest block number is 0" tx_gettransactionscount 查询当前链上交易量 Parameters 无 Returns 1. <Object> count: <string> - 交易数量, 十六进制字符串表示 timestamp: <number> - 响应时间戳 ( 单位 ns) Example curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactionscount", "params": [], "id": 71' "namespace":"global", "id": 71, "code": 0, "message": "SUCCESS":, "result": "count": "0x9", "timestamp": tx_gettxavgtimebyblocknumber 根据指定的区块区间计算出每笔交易的平均处理时间 Parameters 1. <Object> from: <blocknumber> - 起始区块号 to: <blocknumber> - 终止区块号 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表示最新的区块 from 必须小于等于 to, 否则会返回 error 如果 from 和 to 的值一样, 则表示计算的是当前指定区块交易的平均处理时间 接口描述 79

84 Returns 1. <string> - 十六进制字符串, 表示交易的平均处理时间 ( 单位 ms) Example curl -X POST --data ' "namespace":"global", "method": "tx_ gettxavgtimebyblocknumber", "params": ["from":10, "to":19], "id": 71' "id":71, "namespace":"global", "code": 0, "message": "SUCCESS", "result": "0xa9" tx_gettransactionreceipt 根据交易哈希返回交易回执信息 Parameters 1. <string> - 32 字节的十六进制字符串, 交易的哈希值 Returns 1. <Receipt> - Receipt 对象字段如下 : version: <string> - 平台版本号 txhash: <string> - 交易哈希 vmtype: <string> - 该笔交易执行引擎类型,EVM 或 JVM contractaddress: <string> - 合约地址 gasused: <number> - 该笔交易所耗费的 gas ret: <string> - 合约编译后的字节码或合约执行的结果 log: [<Log>] - Log 对象数组, 表示合约中的 event log 信息 Log 对象如下 : address: <string> - 产生事件日志的合约地址 topics: [<string>] - 一系列的 topic, 第一个 topic 是 event 的唯一标识 data: <string> - 日志信息 blocknumber: <number> - 所属区块的区块号 blockhash: <string> - 所属区块的区块哈希 txhash: <string> - 所属交易的交易哈希 txindex: <number> - 所属交易在当前区块交易列表中的偏移量 index: <number> - 该日志在本条交易产生的所有日志中的偏移量 80 Chapter 13. JSON-RPC API

85 如果该笔交易还没被确认, 则返回的错误码为 的 error, 如果该笔交易处理过程中发生错误, 则错误可能是 : OUTOFBALANCE - 余额不足, 对应 code 是 ; SIGFAILED - 签名非法, 对应 code 是 ; DEPLOY_CONTRACT_FAILED - 合约部署失败, 对应 code 是 ; INVOKE_CONTRACT_FAILED - 合约方法调用失败, 对应 code 是 ; INVALID_PERMISSION - 合约操作权限不够, 对应 code 是 ; Example1: 交易未被确认 curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ gettransactionreceipt","params":[ "0x0e cde33c53f8c2b852e75bc9b670c14c547dd785d93cb48f661a2b36a "],"id":1' "namespace":"global", "id": 1, "code": , "message": "Not found receipt by 0x0e cde33c53f8c2b852e75bc9b670c14c547dd785d93cb48f661a2b36a" Example2: 合约部署出错 在这个例子中我们使用以下合约来重现这个情况 : contract TestContractor int length = 0; modifier justfortest() length = 2; throw; _; function TestContractor()justForTest function getlength() returns(int) return length; 我们将该合约编译后返回的 bin 作为 contract_deploycontract 方法中参数 payload 的值, 那么部署合约请求如下 : curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_deploycontract", "params":[ "from":"17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload": "0x b b5b5b603f f e0600 ", "timestamp": , 接口描述 81

86 "signature": "0xfc1cb1986dd4ee4a5f8d8238e2f7bac1866aad235d587eb641d76270bf ab7d42dc0f2575aa858a88ae77 "],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x33aef7e6bad2ae27c23a8ab44f56aef87042f1f0b02e1b0ee5e8a a6" 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了合约部署失败的 error: curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ gettransactionreceipt","params":[ "0x33aef7e6bad2ae27c23a8ab44f56aef87042f1f0b02e1b0ee5e8a a6"],"id":1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":-32004, "message":"deploy_contract_failed" Example3: 合约方法调用出错 在这个例子中我们使用以下合约来重现这个情况 : contract TestContractor int length = 0; modifier justfortest() length = 2; throw; _; function TestContractor() function getlength()justfortest returns(int) return length; 调用合约 getlength() 方法的请求如下 : curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_invokecontract", "params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0xaeccd2fd c5de1cb014a9c192c498df", "timestamp": , "nonce": , "payload":"0xbe1c766b", "signature": "0x8c56f025610dd9cb3f4ac346d a b7593d87f3b45c ed32f6a da "],"id": 1' 82 Chapter 13. JSON-RPC API

87 "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":"0x5233d18f46e9c1ed49dbdeb4273c1c1e0eb176efcedf6edb6d9fa59d33d02fee " 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了方法调用失败的 error: curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ gettransactionreceipt","params":[ "0x5233d18f46e9c1ed49dbdeb4273c1c1e0eb176efcedf6edb6d9fa59d33d02fee"],"id":1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":-32005, "message":"invoke_contract_failed" Example4: 签名非法 我们将 Example3 合约方法调用失败例子的参数稍微修改一下, 把 from 的最后一个字母 c 改为 0, 那么调用合约请求如下 : curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_invokecontract", "params": [ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bff0", "to":"0xaeccd2fd c5de1cb014a9c192c498df", "timestamp": , "nonce": , "payload":"0xbe1c766b", "signature": "0x57dfa7f2c2d8c762c9c0e5ef7b1c4dda84b584f36799ab751891c8dc f64d c af4e4231d "],"id": 1' "namespace":"global", "id": 1, "code": 0, "id": "SUCCESS", "result":"0x621d09cd9d5e9027d9b82c5e1fd911ac dbb0c4dab6c6fcd64310fe23" 接着, 根据返回的 hash 查找这条记录的 receipt, 会发现返回了签名非法的 error: curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ gettransactionreceipt","params":[ "0x621d09cd9d5e9027d9b82c5e1fd911ac dbb0c4dab6c6fcd64310fe23"],"id":1' 接口描述 83

88 "namespace":"global", "id": 1, "code": , "message": " SIGFAILED " Example5 curl -X POST --data ' "namespace":"global", "method": "tx_ gettransactionreceipt", "params":[ "0x e11bc753b8cc778e2fbb e ba1110dd1118c059"], "id": 1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.3", "txhash": "0x e11bc753b8cc778e2fbb e ba1110dd1118c059 ", "vmtype": "EVM", "contractaddress": "0x ", "ret": "0x0", "log": [ "address": "0xaeccd2fd c5de1cb014a9c192c498df", "topics": [ "0x24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd da" ], "data": " ", "blocknumber": 2, "blockhash": "0x0c14a89b9611f7f268f26d4ce552de966bebba4aab6aaea988022f3b6817f61b", "txhash": "0x e11bc753b8cc778e2fbb e ba1110dd1118c059", "txindex": 0, "index": 0 ] tx_getblocktransactioncountbyhash 根据区块哈希查询区块交易数量 Parameters 1. <string> - 32 字节的十六进制字符串, 区块的哈希值 84 Chapter 13. JSON-RPC API

89 Returns 1. <string> - 十六进制字符串, 交易数量 Example1: 正常的请求 curl -X POST --data ' "namespace":"global", "method":"tx_ getblocktransactioncountbyhash", "params": [ "0x7a87bd1fb51a86763e9791eab1d5ecca7f004bea1cfcc426113b4625d267f699"], "id": 71' "id":71, "namespace":"global", "code": 0, "message": "SUCCESS", "result": "0xaf5" Example2: 查询区块不存在 curl -X POST --data ' "namespace":"global", "method":"tx_ getblocktransactioncountbyhash", "params": [ "0x7a87bd1fb51a86763e9791eab1d5ecca7f004bea1cfcc426113b4625d267f699"], "id": 71' "namespace": "global", "id": 71, "code": , "message":"not found block 0x7a87bd1fb51a86763e9791eab1d5ecca7f004bea1cfcc426113b4625d267f699" tx_getblocktransactioncountbynumber 根据区块号查询区块交易数量 Parameters 1. <blcoknumber> - 区块号, 可以是十进制整数 进制字符串或 latest 字符串来表示最新区块 Returns 1. <string> - 十六进制字符串, 交易数量 Example1: 正常的请求 接口描述 85

90 curl -X POST --data ' "namespace":"global", "method":" tx_ getblocktransactioncountbynumber", "params": ["0x2"], "id": 71' "id":71, "namespace":"global", "code": 0, "message": "SUCCESS", "result": "0xaf5" Example2: 查询的区块不存在 curl -X POST --data ' "namespace":"global", "method":" tx_ getblocktransactioncountbynumber", "params": ["0x2"], "id": 71' "namespace": "global", "id": 71, "code": , "message": "block number 0x2 is out of range, and now latest block number is 0" tx_getsignhash 获取用于签名算法的哈希 Parameters 1. <Object> from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - [ 可选 ] 20 字节的十六进制字符串, 交易接收方的地址 ( 普通账户或合约地址 ) 若是部署合约, 则不需要这个参数 nonce: <number> - 16 位随机数 extra: <string> - [ 可选 ] 交易的额外信息 value 或 payload: <string> - value 表示转账金额,payload 表示合约操作对应字节编码 timestamp: <number> - 交易发生时间戳 ( 单位 ns) 注解 : 如果是部署合约的交易, 则不要传 to 若为普通转账, 则传 value, 表示转账金额 若是部署合约 调用合约或升级合约的交易, 则传 payload, 含义详见部署合约 调用合约或升级合约的接口 Returns 1. <string> - 十六进制字符串, 签名哈希 86 Chapter 13. JSON-RPC API

91 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ getsignhash", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload": "0x ffffffff ae e f e060020a ad ", "timestamp": ],"id":"1"' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x2e6a644a4ca6a9daba dc0dda039208e642df11db35438d18e7c3b13c3" tx_gettransactionsbytime 查询指定时间区间内的所有合法交易 Parameters 1. <Object> starttime: <number> - 起始时间戳 ( 单位 ns) endtime: <number> - 结束时间戳 ( 单位 ns) Returns 1. [<Transaction>] - Transaction 对象字段见合法交易. Example1: 正常的请求 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"tx_ gettransactionsbytime","params":["starttime":1, "endtime": ], "id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.0", "hash": "0xbd441c7234e3b83a05c89ed5d548c3d e271a08e7354d74e45431bc", "blocknumber": "0x1", "blockhash": "0xa6a4b2df16c7bdeb578aa7de7b05f9b54d96202bdc ebd", 接口描述 87

92 "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x b6101e f e060020a fd7cc " ] Example2: 查询数据不存在 curl -X POST --data '"jsonrpc":"2.0","method":"tx_gettransactionsbytime","params ":["starttime": , "endtime": ],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [] tx_getdiscardtransactionsbytime 查询指定时间区间内的所有非法交易 Parameters 1. <Object> starttime: <number> - 起始时间戳 ( 单位 ns) endtime: <number> - 结束时间戳 ( 单位 ns) Returns 1. [<Transaction>] - Transaction 对象字段见非法交易. Example1: 正常的请求 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":" tx_ getdiscardtransactionsbytime","params":["starttime":1, "endtime ": ],"id":1' # Result 88 Chapter 13. JSON-RPC API

93 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "hash": "0x4e468969d94b92622e d05981ef43869b17c8afedc7e6b5b138ae807", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd", "amount": "0x1", "timestamp": , "nonce": , "extra": "", "payload": "0x0", "invalid": true, "invalidmsg": "OUTOFBALANCE" ] tx_getbatchtransactions 根据交易哈希批量查询交易 Parameters 1. <Object> hashs: [<string>] - 交易哈希数组, 哈希值为 32 字节的十六进制字符串 Returns 1. [<Transaction>] - Transaction 对象字段见合法交易. Example curl -X POST --data '"jsonrpc":"2.0","method":"tx_getbatchtransactions","params":[ "hashes":["0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4", "0x7aebde51531bb29d3ba620f91f6e1556a1e8b50913e590f31d4fe4a2436c0602"] ],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "hash": "0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4", 接口描述 89

94 "blocknumber": "0x2", "blockhash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x6", "payload": "0x0a9ae69d", "version": "1.3", "hash": "0x7aebde51531bb29d3ba620f91f6e1556a1e8b50913e590f31d4fe4a2436c0602", "blocknumber": "0x1", "blockhash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x11", "payload": "0x f fd5b b6 " ] tx_getbatchreceipt 根据交易哈希批量查询交易回执 Parameters 1. <Object> hashs: [<string>] - 交易哈希数组,, 哈希值为 32 字节的十六进制字符串 Returns 1. [<Receipt>] - Receipt 对象字段见 Receipt. Example curl -X POST --data ' "jsonrpc":"2.0","method":"tx_getbatchreceipt","params":[ "hashes":["0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4", "0x7aebde51531bb29d3ba620f91f6e1556a1e8b50913e590f31d4fe4a2436c0602"] ],"id":1' 90 Chapter 13. JSON-RPC API

95 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "txhash": "0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4 ", "vmtype": "EVM", "contractaddress": "0x ", "ret": "0x ", "log": [], "version": "1.3", "txhash": "0x7aebde51531bb29d3ba620f91f6e1556a1e8b50913e590f31d4fe4a2436c0602 ", "vmtype": "EVM", "contractaddress": "0xaeccd2fd c5de1cb014a9c192c498df", "ret": "0x ffffffff7c ", "log": [] ] contract_compilecontract 编译智能合约 Parameters 1. <string> - 合约源码 Returns 1. <Object> abi: [<string>] - 合约源码对应的 abi bin: [<string>] - 合约编译而成的字节码 types: [<string>] - 对应合约的名称 若源码中有多个合约, 则 bin 为顶层合约的字节码 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "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' 接口描述 91

96 "namespace":"global", "id": 1, "code": 0, "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 ad " ], "types": [ "Accumulator" ] contract_deploycontract 部署合约 Parameters 1. <Object> from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 nonce: <number> - 16 位随机数, 该值必须为十进制整数 extra: <string> -[ 可选 ] 交易的额外信息 timestamp: <number> - 交易发生时间戳 ( 单位 ns) payload: <string> - 合约编码 如果是 solidity 合约, 则该值为 contract_compliecontract 方法返回的 bin 以及构造函数参数的拼接 如果是 java 合约, 该值为 class 文件和配置文件压缩后的字节流 signature: <string> - 交易签名 type: <string> - [ 可选 ] 指定合约执行引擎, 默认为 evm 如果合约代码由 java 语言编写, 则需要设置该值为 jvm 注解 : 若合约构造函数需要传参, 则 payload 为编译合约返回的 bin 与构造函数参数编码的字符串拼接 Returns 1. <string> - 32 字节的十六进制字符串, 交易的哈希值 92 Chapter 13. JSON-RPC API

97 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_deploycontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload": "0x ffffffff ae e f e060020a ad ", "signature": "0x388ad7cb71b1281eb5a0746fa8fe6fda006bd28571cbe69947ff0115ff8f3cd00bdf2f45748e0068e ", "timestamp": ],"id":"1"' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x406f89cb205e136411fd7f5befbf8383bbfdec5f6e8bcfe50b16dcff037d1d8a" contract_invokecontract 调用合约 Parameters 1. <Object> from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - 20 字节的十六进制字符串, 合约地址 nonce: <number> - 16 位随机数, 该值必须为十进制整数 extra: <string> -[ 可选 ] 交易的额外信息 timestamp: <number> - 交易发生时间戳 ( 单位 ns) payload: <string> - 该值为方法名和方法参数经过编码后的 input 字节码 signature: <string> - 交易签名 simulate: <bool> - [ 可选 ] 默认为 false true 表示交易不走共识,false 表示走共识 type: <string> - [ 可选 ] 指定合约执行引擎, 默认为 evm 如果合约代码由 java 语言编写, 则需要设置该值为 jvm 注解 : 说明 :to 合约地址需要在部署完合约以后, 调用 tx_gettransactionreceipt 方法来获取 Returns 1. <string> - 32 字节的十六进制字符串, 交易的哈希值 接口描述 93

98 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_invokecontract", "params":[ "from":"0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "nonce": , "payload": "0x3ad14af ", "signature": "0xde467ec4c0bd9033bdc3b6faa43a8d3c5dcf393ed9f34ec1c1310b0859a0ecba15c5be4480a9ad2aaaea cb ", "simulate":false, "timestamp": , "to":"0x313bbf563991dc4c1be9d98a058a26108adfcf81" ],"id":"1"' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed098995c08fde" contract_getcode 获取合约的字节编码 Parameters 1. <string> - 合约地址 Returns 1. <string> - 十六进制字节码 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"contract_ getcode","params": ["0xaeccd2fd c5de1cb014a9c192c498df"],"id": 1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x e060020a dd b e e f24d " 94 Chapter 13. JSON-RPC API

99 contract_getcontractcountbyaddr 获取指定账户部署的合约量 Parameters 1. <string> - 20 字节的十六进制字符串, 账户地址 Returns 1. <string> - 合约数量 Example curl -X POST --data ' "namespace":"global", "method": "contract_ getcontractcountbyaddr", "params": ["0xa94f5374fce5edbc8e2a8697c e6ebf0b "], "id": 1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x3" contract_maintaincontract 升级合约 冻结合约 解冻合约 只有合约的部署者才拥有升级合约 冻结合约 解冻合约的权限 Parameters 1. <Object> from: <string> - 20 字节的十六进制字符串, 交易发送方的地址 to: <string> - 20 字节的十六进制字符串, 合约地址 nonce: <number> - 16 位随机数, 该值必须为十进制整数 extra: <string> -[ 可选 ] 交易的额外信息 timestamp: <number> - 交易发生时间戳 ( 单位 ns) payload: <string> - [ 可选 ] 编译后的新合约字节码 升级合约才需要这个字段 signature: <string> - 交易签名 type: <string> - 指定合约执行引擎, 默认为 evm 如果合约代码由 java 语言编写, 则需要设置该值为 jvm opcode: 值为 1 表示升级合约, 值为 2 表示冻结合约 值为 3 表示解冻合约 注解 : 说明 :to 合约地址需要在部署完合约以后, 调用 tx_gettransactionreceipt 方法来获取 接口描述 95

100 Returns 1. <string> - 32 字节的十六进制字符串, 交易的哈希值 Example1: 升级合约 curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_maintaincontract","params":[ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "payload": "0x6fd7cc b ", "signature": "0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c46894b9f12a02af471031ba11f155e41adf42fca ", "opcode": 1], "id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed098995c08fde" Example2: 冻结合约 curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_maintaincontract","params":[ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "signature": "0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c46894b9f12a02af471031ba11f155e41adf42fca ", "opcode": 2], "id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed098995c08fde" 96 Chapter 13. JSON-RPC API

101 Example3: 解冻合约 curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_maintaincontract","params":[ "from": "17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to":"0x3a3cae27d1b9fa931458b5b2a5247c5d67c75d61", "timestamp": , "nonce": , "signature": "0x19c0655d05b9c24f b81a25c48458a05f69f05cf8d6c46894b9f12a02af471031ba11f155e41adf42fca ", "opcode": 3], "id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":"0xd7a07fbc8ea43ace5c36c14b375ea1e1bc216366b09a6a3b08ed098995c08fde" contract_getstatus 查询合约状态 Parameters 1. <string> - 20 字节的十六进制字符串, 合约地址 Returns 1. <string> - 合约状态 normal 表示正常状态,frozen 表示冻结状态,non-contract 表示非合约, 即为普通转账的交易 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_getstatus","params": ["0xbbe2b6412ccf de8958f2acc76cda9c9"],"id ": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":" normal" 接口描述 97

102 contract_getcreator 查询合约部署者 Parameters 1. <string> - 20 字节的十六进制字符串, 合约地址 Returns 1. <string> - 20 字节的十六进制字符串, 合约部署者地址 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_getcreator","params": ["0xbbe2b6412ccf de8958f2acc76cda9c9"], "id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":" 0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd " contract_getcreatetime 查询合约部署时间 Parameters 1. <string> - 20 字节的十六进制字符串, 合约地址 Returns 1. <string> - 合约部署的日期时间 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_getcreatetime","params": ["0xbbe2b6412ccf de8958f2acc76cda9c9 "],"id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, 98 Chapter 13. JSON-RPC API

103 "code":0, "message":"success", "result":" :37: CST" contract_getdeployedlist 查询已部署的合约地址列表 Parameters 1. <string> - 20 字节的十六进制字符串, 账户地址 Returns 1. [<string>] - 已部署的所有合约地址 Example curl localhost: data '"jsonrpc":"2.0", "namespace":"global", "method": "contract_getdeployedlist","params": ["0x000f1a7a08ccc48e5d30f80850cf1cf283aa3abd "],"id": 1' "jsonrpc":"2.0", "namespace":"global", "id":1, "code":0, "message":"success", "result":["0xbbe2b6412ccf de8958f2acc76cda9c9"] block_latestblock 获取最新区块 Parameters 无 Returns 1. <Block> - Block 对象字段如下 : version: <string> - 平台版本号 number: <string> - 区块的高度 hash: <string> - 区块的哈希值,32 字节的十六进制字符串 parenthash: <string> - 父区块哈希值,32 字节的十六进制字符串 接口描述 99

104 writetime: <number> - 区块生成的 unix 时间戳 avgtime: <string> - 当前区块中, 交易的平均处理时间 ( 单位 ms) txcounts: <string> - 当前区块中打包的交易数量 merkleroot: <string> - Merkle 树的根哈希 transactions: [<Transaction>] - 区块中的交易列表 Example1: 正常的请求 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":" block_ latestblock","params":[],"id":71' "namespace":"global", "id": 1, "code": 0, "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": , "extra": "", "executetime": "0x2", "payload": "0x81053a " ] Example2: 如果链上一个区块都没有 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":" block_ latestblock","params":[],"id":71' 100 Chapter 13. JSON-RPC API

105 "namespace": "global", "id": 1, "code": , "message": "There is no block generated!" block_getblocks 查询指定区块区间的所有区块 Parameters 1. <Object> from: <blocknumber> - 起始区块号 to: <blocknumber> - 终止区块号 isplain: <boolean> - [ 可选 ] 默认值为 false, 表示返回的区块包括区块内的交易信息, 如果指定为 true, 表示返回的区块不包括区块内的交易 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表示最新的区块 from 必须小于等于 to, 否则会返回 error Returns 1. [<Block>] - Block 对象字段见 Block. Example1: 返回的区块包括交易信息 curl -X POST --data ' "namespace":"global", "method": "block_ getblocks", "params": ["from":2,"to":3], "id": 1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c", "transactions": [ 接口描述 101

106 "version": "1.0", "hash": "0xf57a6443d08cda4a3dfb b6334d17d7af51c94a5f98ed67179b59169ae", "blocknumber": "0x3", "blockhash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x81053a " ], "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 ", "blocknumber": "0x2", "blockhash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x6fd7cc a " ] ] Example2: 返回的区块不包括交易信息 curl -X POST --data ' "namespace":"global", "method": "block_ getblocks", "params": ["from":2,"to":3,"isplain":true], "id": 1' 102 Chapter 13. JSON-RPC API

107 "namespace":"global", "id": 1, "code": 0, "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", "parenthash": "0xe287c62aae77462aa772bd68da9f1a1ba21a0d044e2cc47f742409c20643e50c", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c" ] block_getblockbyhash 根据区块的哈希值查询区块详细信息 Parameters 1. <string> - 32 字节的十六进制字符串, 区块的哈希值 2. <boolean> - 值为 true, 表示返回的区块不包括区块内的交易 值为 false 表示返回的区块包括区块内的交易信息 Returns 1. <Block> - Block 对象字段见 Block. Example1: 返回的区块包括交易信息 curl -X POST -data '"jsonrpc":"2.0","namespace":"global","method":"block_ getblockbyhash","params":[ "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", false],"id ":1' 接口描述 103

108 "namespace":"global", "id": 1, "code": 0, "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": , "extra": "", "executetime": "0x2", "payload": "0x81053a " ] Example2: 返回的区块不包括交易信息 curl -X POST -data '"jsonrpc":"2.0","namespace":"global","method":"block_ getblockbyhash","params":[ "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", true],"id ":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", 104 Chapter 13. JSON-RPC API

109 "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c" block_getblockbynumber 根据区块高度查询区块详细信息 Parameters 1. <blocknumber> - 区块号, 可以是十进制整数 进制字符串或 latest 字符串来表示最新区块 2. <boolean> - 值为 true, 表示返回的区块不包括区块内的交易 值为 false 表示返回的区块包括区块内的交易信息 Returns 1. <Block> - Block 对象字段见 Block. Example1: 返回的区块包括交易信息 curl -X POST --data ' "namespace":"global", "method": "block_ getblockbynumber", "params": ["0x3", false], "id": 1' "namespace":"global", "id": 1, "code": 0, "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", 接口描述 105

110 "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x2", "payload": "0x81053a " ] Example2: 返回的区块不包括交易信息 curl -X POST --data ' "namespace":"global", "method": "block_ getblockbynumber", "params": ["0x3", true], "id": 1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "version": "1.0", "number": "0x3", "hash": "0x00acc3e13d8124fe799d55d7d2af dc7bbc723718bb1a88fead34c914", "parenthash": "0x2b de0dda68926f96cffbe48c980c4325d416dab62b4be27fd73cee9", "writetime": , "avgtime": "0x2", "txcounts": "0x1", "merkleroot": "0xc6fb0054aa90f3bfc78fe79cc459f7c7f268af7eef23bd4d8fc85204cb00ab6c" block_getavggeneratetimebyblocknumber 查询区块平均生成时间 Parameters 1. <Object> from: <blocknumber> - 起始区块号 to: <blocknumber> - 终止区块号 blocknumber 可以是十进制整数或者进制字符串, 可以是 latest 字符串表示最新的区块 from 必须小于等于 to, 否则会返回 error 106 Chapter 13. JSON-RPC API

111 Returns 1. <string> - 区块的平均生成时间 ( 单位 ms) Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":" block_ getavggeneratetimebyblocknumber","params": ["from": 10, "to": 19],"id":71' "id":71, "namespace":"global", "code": 0, "message": "SUCCESS", "result": "0x32" block_getblocksbytime 查询指定时间区间内的区块数量 Parameters 1. <Object> starttime: <number> - 起始 unix 时间戳 ( 单位 ns) endtime: <number> - 结束 unix 时间戳 ( 单位 ns) Returns 1. <Object> sumofblocks: <string> - 区块总数 startblock: <string> - 起始区块号 endblock: <string> - 结束区块号 Example1: 正常的请求 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"block_ getblocksbytime","params":["starttime": , "endtime ": ],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "sumofblocks": "0x3", 接口描述 107

112 "startblock": "0x1", "endblock": "0x3" Example2: 如果起始时间和终止时间均大于链上最新区块的写入时间 curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"block_ getblocksbytime","params":["starttime": , "endtime ": ],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "sumofblocks": "0x0", "startblock": null, "endblock": null block_getgenesisblock 查询创世区块号 Parameters 无 Returns 1. <string> - 区块号 Example curl -X POST --data ' "jsonrpc":"2.0","method":"block_getgenesisblock","params ":[],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x8" 108 Chapter 13. JSON-RPC API

113 block_getchainheight 查询最新区块号 Parameters 无 Returns 1. <string> - 区块号 Example curl -X POST --data ' "jsonrpc":"2.0","method":"block_getchainheight","params":[], "id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "0x11" block_getbatchblocksbyhash 根据区块哈希列表批量查询区块详细信息 Parameters 1. <Object> hashes: [<string>] - 要查询的区块哈希数组, 哈希值为 32 字节的十六进制字符串 isplain: <boolean> - 值为 true, 表示返回的区块不包括区块内的交易 值为 false 表示返回的区块包括区块内的交易信息 Returns 1. [<Block>] - Block 对象数组,Block 对象字段见 Block. Example1: 返回的区块包含交易信息 curl -X POST --data ' "jsonrpc":"2.0","method":"block_getbatchblocksbyhash", "params":[ "hashes":["0x810c92919fba632471b543905d8b4f8567c4fac27e5929d2eca8558c68cb7cf0", "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b"] ],"id":1' 接口描述 109

114 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "number": "0x3", "hash": "0x810c92919fba632471b543905d8b4f8567c4fac27e5929d2eca8558c68cb7cf0", "parenthash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "writetime": , "avgtime": "0x0", "txcounts": "0x0", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "version": "1.3", "number": "0x2", "hash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "parenthash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "writetime": , "avgtime": "0x6", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "transactions": [ "version": "1.3", "hash": "0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4", "blocknumber": "0x2", "blockhash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x6", "payload": "0x0a9ae69d" ] ] Example2: 返回的区块不包括交易信息 curl -X POST --data ' "jsonrpc":"2.0","method":"block_getbatchblocksbyhash", "params":[ "hashes":["0x810c92919fba632471b543905d8b4f8567c4fac27e5929d2eca8558c68cb7cf0", "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b"], "isplain": true 110 Chapter 13. JSON-RPC API

115 ],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "number": "0x3", "hash": "0x810c92919fba632471b543905d8b4f8567c4fac27e5929d2eca8558c68cb7cf0", "parenthash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "writetime": , "avgtime": "0x0", "txcounts": "0x0", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "version": "1.3", "number": "0x2", "hash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "parenthash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "writetime": , "avgtime": "0x6", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481" ] block_getbatchblocksbynumber 根据区块号列表批量查询区块详细信息 Parameters 1. <Object> numbers: [<blocknumber>] - 要查询的区块号数组, 区块号可以是十进制整数或者进制字符串, 也可以是 latest 字符串表示最新的区块 isplain: <boolean> - 值为 true, 表示返回的区块不包括区块内的交易 值为 false 表示返回的区块包括区块内的交易信息 Returns 1. [<Block>] - Block 对象数组,Block 对象字段见 Block 接口描述 111

116 Example1: 返回的区块包括交易信息 curl -X POST --data ' "jsonrpc":"2.0","method":"block_getbatchblocksbynumber", "params":[ "numbers": ["1","2"] ],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "number": "0x1", "hash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "parenthash": "0x ", "writetime": , "avgtime": "0x11", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "transactions": [ "version": "1.3", "hash": "0x7aebde51531bb29d3ba620f91f6e1556a1e8b50913e590f31d4fe4a2436c0602", "blocknumber": "0x1", "blockhash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0x ", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x11", "payload": "0x f fd5b b6 " ], "version": "1.3", "number": "0x2", "hash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "parenthash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "writetime": , "avgtime": "0x6", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "transactions": [ "version": "1.3", 112 Chapter 13. JSON-RPC API

117 "hash": "0x c577ceaa2088d dc6c1b6096a0b3f565d130f03ca75e4", "blocknumber": "0x2", "blockhash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "txindex": "0x0", "from": "0x17d806c92fa941b4b7a8ffffc58fa2f297a3bffc", "to": "0xaeccd2fd c5de1cb014a9c192c498df", "amount": "0x0", "timestamp": , "nonce": , "extra": "", "executetime": "0x6", "payload": "0x0a9ae69d" ] ] Example2: 返回的区块不包括交易信息 curl -X POST --data ' "jsonrpc":"2.0","method":"block_getbatchblocksbynumber", "params":[ "numbers": ["1","2"], "isplain": true ],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "version": "1.3", "number": "0x1", "hash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "parenthash": "0x ", "writetime": , "avgtime": "0x11", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481", "version": "1.3", "number": "0x2", "hash": "0x9c41efcc50ec6af6e3d14e1669f37bd1fc0cfe5836af6ab1e43ced98653c938b", "parenthash": "0x4cd9f393aabb2df51c09e66925c4513e23f0dbbb9e94d0351c1c3ec a0", "writetime": , "avgtime": "0x6", "txcounts": "0x1", "merkleroot": "0x97b0d f5b0aee123d5652b15d4ae3ab41cc487cda9d8885cb003481" 接口描述 113

118 ] sub_newblocksubscription 订阅新区块事件并且创建一个过滤器用于通知客户端, 当有一个新区块产生的时候, 该区块信息会缓存在过滤器中 Parameters 1. <boolean> - 是否返回完整数据 ; 值为 true 表示返回完整 Block 对象 ; 值为 false 表示只返回区块哈希 Returns 1. <string> - 订阅标号 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_ newblocksubscription","params":[false],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":"0x7e533eb0647ecbe473ae610ebdd1bba6" sub_neweventsubscription 订阅虚拟机事件并且创建一个过滤器用于通知客户端, 当虚拟机事件被触发的时候, 该事件日志会缓存在过滤器中 Parameters 1. <Object> fromblock: <number> - [ 可选 ] 十进制整数, 表示起始区块号 ; 若为空则默认没有限制 起始区块号大于或等于当前最新区块号 toblock: <number> - [ 可选 ] 十进制整数, 表示终止区块号 ; 若为空则默认没有限制 终止区块号是大于起始区块号的未来某一个区块号 addresses: [<string>] - [ 可选 ] 表示监听指定地址的合约产生的事件 ; 若为空则表示监听所有合约产生的事件 topics: [<string>][<string>] - [ 可选 ] 二维字符串数组, 表示事件的话题, 用于事件的内容过滤 若为空表示没有过滤条件 topics 可能有以下组合 : [A, B] = A && B 114 Chapter 13. JSON-RPC API

119 [A, [B, C]] = A && (B C) [null, A, B] = ANYTHING && A && B null 表示通配符 Returns 1. <string> - 订阅标号 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_ neweventsubscription","params":[ "fromblock":100, "addresses": ["000f1a7a08ccc48e5d30f80850cf1cf283aa3abd"] ], "id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":"0x7e533eb0647ecbe473ae610ebdd1bba6" sub_getlogs 获取符合条件的虚拟机事件 Parameters 1. <Object> fromblock: <number> - [ 可选 ] 十进制整数, 表示起始区块号 ; 若为空则默认为 0 起始区块号不能小于当前创世区块号 toblock: <number> - [ 可选 ] 十进制整数, 表示终止区块号 ; 若为空则默认没有限制 终止区块号不能大于当前最新区块号 addresses: [<string>] - [ 可选 ] 一维数组, 表示监听指定地址的合约产生的事件 ; 若为空则表示监听所有合约产生的事件 topics: [<string>][<string>] - [ 可选 ] 二维字符串数组, 表示事件的话题, 用于事件的内容过滤 topics 可能有以下组合 : [A, B] = A && B [A, [B, C]] = A && (B C) [null, A, B] = ANYTHING && A && B null 表示通配符 Returns 1. [<Log>] - 事件信息,Log 对象字段如下 : address: <string> - 20 字节的十六进制字符串, 产生事件的合约地址 接口描述 115

120 topics: [<string>] - 一系列的 topic data: <string> - 数据段 blocknumber: <number> - 十进制整数, 所属区块号 blockhash: <string> - 所属区块哈希 txhash: <string> - 所属交易哈希 txindex: <number> - 十进制整数, 所属交易在当前区块交易列表中的偏移量 index: <number> - 十进制整数, 该日志在本条交易产生的所有日志中的偏移量 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_getlogs ","params":[ "addresses": ["0x313bbf563991dc4c1be9d98a058a26108adfcf81"] ], "id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":[ "address":"0x313bbf563991dc4c1be9d98a058a26108adfcf81", "topics":[ "0x24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd da"], "data":" ", "blocknumber":4, "blockhash": "0xee93a66e170f2b20689cc05df27e290613da411c42a7bdfa951481c08fdefb16", "txhash": "0xa676673a23f33a95a1a ad780c5048dff76df961e9f78329b201670ae2", "txindex":0, "index":0 ] sub_newsystemstatussubscription 订阅系统状态事件 Parameters 1. <Object> modules: [<string>] - [ 可选 ] 一维数组, 表示要订阅哪些模块的状态信息, 若为空, 则表示订阅所有模块 比如 :p2p consensus executor 等 modules_exclude: [<string>] - [ 可选 ] 一维数组, 表示排除哪些模块的状态信息, 若为空, 则表示不排除 116 Chapter 13. JSON-RPC API

121 subtypes: [<string>] - [ 可选 ] 一维数组, 表示要订阅模块下面的哪一类状态信息, 若为空, 则表示订阅所有类型 比如 :viewchange 等 subtypes_exclude: [<string>] - [ 可选 ] 一维数组, 表示要排除模块下面的哪一类状态信息, 若为空, 则表示不排除 error_codes: [<number>] - [ 可选 ] 一维数组, 元素为十进制整数, 表示要订阅指定的具体哪一条状态信息, 若为空, 则表示订阅所有状态信息 error_codes_exclude: [<number>] - [ 可选 ] 一维数组, 元素为十进制整数, 表示要排除指定的具体哪一条状态信息, 若为空, 则表示不排除 Returns 1. <string> - 订阅标号 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_ newsystemstatussubscription","params":[ "modules":["executor", "consensus"], "subtypes": ["viewchange"], "error_codes_exclude": [-1, -2] ], "id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":"0x7e533eb0647ecbe473ae610ebdd1bba6" sub_getsubscriptionchanges 获取所订阅的事件 通过轮询这个方法, 可以实时获取订阅的事件 Parameters 1. <string> - 订阅标号 Returns 1. <Array> - 一维数组, 所订阅的事件返回的内容 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_ getsubscriptionchanges","params":[ 0x7e533eb0647ecbe473ae610ebdd1bba6 ], "id":1' 接口描述 117

122 "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": sub_unsubscription 取消订阅 Parameters 1. <string> - 订阅标号 Returns 1. <boolean> - 值为 true 表示取消订阅指定事件成功, 否则失败 Example curl -X POST --data '"jsonrpc":"2.0", "namespace":"global", "method":"sub_ unsubscription","params":[ 0x7e533eb0647ecbe473ae610ebdd1bba6 ], "id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result":true, node_getnodes 获取节点信息 Parameters 无 Returns 1. [<PeerInfo>] - PeerInfo 对象字段如下 id: <number> - 该节点 id ip: <string> - 该节点 IP 地址 118 Chapter 13. JSON-RPC API

123 port: <number> - 该节点的 grpc 端口号 namespace: <string> - 该节点所在分区 hash: <string> - 该节点哈希值 hostname: <string> - 节点主机名 isprimary: <bool> - 表示该节点是否为主节点 isvp: <bool> - 表示该节点是否为 VP 节点 status: <number> - 表示该节点的状态, 值为 0 表示节点处于 Alive 状态, 值为 1 表示节点处于 Pending 状态, 值为 2 表示节点处于 Stop 状态 delay: <number> - 表示该节点与本节点的延迟时间 ( 单位 ns), 若为 0, 则为本节点 Example curl -X POST --data ' "namespace":"global", "method": "node_ getnodes", "params": [],"id":1' "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": [ "id": 1, "ip": " ", "port": "50011", "namespace": "global", "hash": "fa34664ec14727c bcaba9ef05d2c48e06d294c15effc900a5b4b663a ", "hostname": "node1", "isprimary": true, "isvp": true, "status": 0, "delay": 0, "id": 2, "ip": " ", "port": "50012", "namespace": "global", "hash": "c82a71a88c58540c62fc119e78306e7fdbe114d9b840c47ab564767cb1c706e2 ", "hostname": "node2", "isprimary": false, "isvp": true, "status": 0, "delay": , "id": 3, "ip": " ", "port": "50013", "namespace": "global", "hash": "0c89dc7d8bdf45d1fed89fdbac27463d9f144875d3d73795f64f35dc204480fd ", 接口描述 119

124 ", ], "hostname": "node3", "isprimary": false, "isvp": true, "status": 0, "delay": "id": 4, "ip": " ", "port": "50014", "namespace": "global", "hash": "34d bab353995fe b5c27bde52489f61de093176e82088 "hostname": "node4", "isprimary": false, "isvp": true, "status": 0, "delay": node_getnodehash 获取当前节点哈希值 ( 向哪个节点发送请求即获取那个节点的哈希值 ) Parameters 无 Returns 1. <string> - 节点哈希值 Example curl -X POST --data ' "jsonrpc":"2.0", "namespace":"global", "method":"node_ getnodehash","params":[],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "c605d50c3ed56902ec31492ed43b238b36526df5d2fd6153c b6635f6e" node_deletevp 删除 VP 节点 说明 : 假设当前有 5 个 VP 节点, 如果要删除第 3 个节点, 则需要向其他 4 个节点都发送删除节点的请求,3 号节点才能成功删除 120 Chapter 13. JSON-RPC API

125 Parameters 1. <Object> nodehash: <string> - 要删除的 VP 节点的哈希值 Returns 1. <string> - 请求发送成功的 mesage Example curl -X POST --data ' "jsonrpc":"2.0", "namespace":"global", "method":"node_ deletevp","params":["nodehash": "c605d50c3ed56902ec31492ed43b238b36526df5d2fd6153c b6635f6e"],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", "result": "successful request to delete vp node" node_deletenvp VP 节点断开与 NVP 节点的连接 Parameters 1. <Object> nodehash: <string> - 要删除的 NVP 节点的哈希值 Returns 1. <string> - 请求发送成功的 mesage Example curl -X POST --data ' "jsonrpc":"2.0","namespace":"global", "method":"node_ deletenvp","params":["nodehash": "c605d50c3ed56902ec31492ed43b238b36526df5d2fd6153c b6635f6e"],"id":1' "namespace":"global", "id": 1, "code": 0, "message": "SUCCESS", 接口描述 121

126 "result": "successful request to delete nvp node" cert_gettcert 获取节点颁发给用户的 tcert 证书 Parameters 1. <Object> pubkey: <string> - 十六进制表示的 pem 格式公钥 Returns 1. <Object> tcert: <string> - tcert 证书 Example: 获取 tcert 失败 curl -X POST --data ' "jsonrpc":"2.0", "namespace":"global", "method":"cert_ gettcert","params":[ "pubkey": "2d2d2d2d2d e c b45592d2d2d2d2d0a424a4b d2b c7 "],"id":"1"' "namespace":"global", "id": "1", "code": , "message": "signed tcert failed" 122 Chapter 13. JSON-RPC API

127 CHAPTER 14 节点操作 添加节点 添加节点需要涉及以下三个文件的配置 : peerconfig.toml: 对端配置文件, 用于配置逻辑对端节点连接信息 hosts.toml: 主机配置文件, 用于配置物理对端节点连接信息, 包括节点主机与 IP 地址的映射 addr.toml: 地址配置文件, 用于配置物理互连地址信息, 包括域名与 IP 地址的映射 当对端节点反向连接的时候需要用到此文件的配置 Example1: 在已有 4 个 VP 节点的基础上, 添加第五个 VP 节点 新增的 VP 节点在启动前需配置好以下配置文件 : 1. peerconfig.toml [[nodes]] hostname = "node1" id = 1 static = true [[nodes]] hostname = "node2" id = 2 static = true [[nodes]] hostname = "node3" id = 3 static = true [[nodes]] hostname = "node4" id = 4 static = true [[nodes]] 123

128 hostname = "node5" id = 5 static = true [self] caconf = "config/namespace.toml" hostname = "node5" id = 5 # 节点 ID n = 5 # 需要连接的 vp 的个数 new = true # 是否为新加入节点 org = false # 是否为创世节点 rec = false # 是否重连 vp = true # 是否为 VP 节点 2. hosts.toml 本文件需要配置所有需要连接的节点的物理地址,hyperchain 节点之间通过 hostname 进行相互通信, 所以 hostname 可以配置为任意的节点通信地址 hosts = [ "node :50011", "node :50012", "node :50013", "node :50014", "node :50015" ] 3. addr.toml addr 采用域的形式进行声明, 例如 hostname 为 node1 和 node5 的两个节点同属 domain1 而其他节点都分别属于不同的 domain 下, 则配置文件应该按照如下配置 ( 本配置文件为 node5 的 addr.toml): addrs = [ "domain :50015", "domain :50015", "domain :50015", "domain :50015", ] domain = "domain1" 注解 : 重申一下,addr.toml 是为了让别的节点知道自己所在的域以及让不同的域的节点通过不同的网络地址进行互连的配置, 能够允许复杂网段之间的节点互连 Example2: 在已有 4 个 VP 节点的基础上, 添加一个 NVP 节点 新增的 NVP 节点在启动前需配置好以下配置文件 : 1. peerconfig.toml [[nodes]] hostname = "node1" id = 1 static = true [[nodes]] hostname = "node2" id = 2 static = true [[nodes]] 124 Chapter 14. 节点操作

129 hostname = "node3" id = 3 static = true [[nodes]] hostname = "node4" id = 4 static = true [self] caconf = "config/namespace.toml" hostname = "node5" id = 0 n = 4 # 需要连接的 vp 的个数 new = true # 是否为新加入节点 org = false # 是否为创世节点 rec = false # 是否重连 vp = false # 是否为 VP 节点 2. hosts.toml hosts = [ "node :50011", "node :50012", "node :50013", "node :50014", "node :50015" ] 3. addr.toml addrs = [ "domain :50015", "domain :50015", "domain :50015", "domain :50015", "domain :50015" ] domain = "domain5" 删除节点 我们将删除节点分为三种情况 : 1. VP 断开与某个 VP 的连接 ; 2. VP 主动断开与 NVP 的连接 ; 3. NVP 主动断开与 VP 的连接 ; 第二种和第三种的结果是一样的, 均能使 NVP 不再同步 VP 数据 NVP 不再转发交易给 VP 在下面的例子中, 我们均假设各个节点的 JSON-RPC API 服务端口映射如下 : 1 号节点 : 号节点 : 号节点 : 号节点 : 号节点 : 删除节点 125

130 Example1: VP 断开与其他 VP 的连接 例如, 当前有 5 个 VP 节点, 现在要删除 5 号 VP 节点 首先, 获取要删除的 5 号 VP 节点的哈希, curl -X POST -d '"jsonrpc":"2.0","method":"node_getnodehash","params":[],"id":1, "namespace":"global"' localhost:8085 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "55d3c05f2c24c232a47a1f1963ace172b21d3a2ec0ac83ea075da2d bc" 然后, 分别向 号 VP 节点发送删除节点请求, curl -X POST -d '"jsonrpc":"2.0","method":"node_deletevp","params":["nodehash": "55d3c05f2c24c232a47a1f1963ace172b21d3a2ec0ac83ea075da2d bc"],"id":1, "namespace":"global"' localhost:8081/8082/8083/8084/8085 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "successful request to delete vp node, hash 55d3c05f2c24c232a47a1f1963ace172b21d3a2ec0ac83ea075da2d bc" 当在终端看到以下日志时, 说明 VP 节点删除成功 global::p2p 12:33: DELETE NODE 55d3c05f2c24c232a47a1f1963ace172b21d3a2ec0ac83ea075da2d bc global::p2p 12:33: delete validate peer Example2: VP 断开与 NVP 的连接 例如, 当前有 4 个 VP 节点和 1 个 NVP 节点,NVP 节点与 1 号节点相连 首先, 获取 NVP 节点的哈希, curl -X POST -d '"jsonrpc":"2.0","method":"node_getnodehash","params":[],"id":1, "namespace":"global"' localhost:8085 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", 126 Chapter 14. 节点操作

131 "result": " d8191b62a1141dbc3250a0cc61a436ca28829f40cb5a690c ad" 然后, 向 1 号节点发送删除 NVP 的请求, curl -X POST -d '"jsonrpc":"2.0","method":"node_deletenvp","params":["nodehash": " d8191b62a1141dbc3250a0cc61a436ca28829f40cb5a690c ad"],"id":1, "namespace":"global"' localhost:8081 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "successful request to delete nvp node, hash d8191b62a1141dbc3250a0cc61a436ca28829f40cb5a690c ad" 在 1 号 VP 节点终端看到以下日志, global::p2p 13:28: delete NVP peer, hash d8191b62a1141dbc3250a0cc61a436ca28829f40cb5a690c ad, vp pool size(4) nvp pool size(0) 同时,NVP 节点也会打印以下日志说明与 1 号节点已经断开连接 global::p2p 13:28: peers_pool.go:244 delete validate peer 1 说明 NVP 节点删除成功 Example3: NVP 断开与 VP 的连接 这种情况与 Example2 差不多, 不同的是我们这次是向 NVP 节点发送删节点请求 例如, 当前有 4 个 VP 节点和 1 个 NVP 节点,NVP 节点与 1 号节点相连 首先, 获取 1 号 VP 节点的哈希, curl -X POST -d '"jsonrpc":"2.0","method":"node_getnodehash","params":[],"id":1, "namespace":"global"' localhost:8081 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "fa34664ec14727c bcaba9ef05d2c48e06d294c15effc900a5b4b663a" 然后, 向 NVP 节点发送删除 VP 的请求, curl -X POST -d '"jsonrpc":"2.0","method":"node_deletevp","params":["nodehash": "fa34664ec14727c bcaba9ef05d2c48e06d294c15effc900a5b4b663a"],"id":1, "namespace":"global"' localhost: 删除节点 127

132 "namespace": "global", "id": 1, "code": 0, "message": "SUCCESS", "result": "successful request to delete vp node, hash fa34664ec14727c bcaba9ef05d2c48e06d294c15effc900a5b4b663a" 在 NVP 节点终端看到以下日志, global::p2p 13:47: delete validate peer 1 同时, 在 1 号 VP 节点终端看到以下日志, global::p2p 13:47: delete NVP peer, hash d8191b62a1141dbc3250a0cc61a436ca28829f40cb5a690c ad, vp pool size(4) nvp pool size(0) 说明 VP 节点删除成功 128 Chapter 14. 节点操作

133 CHAPTER 15 Hyperchain 开发路线图 Hyperchain 目前在开源社区开放的是 1.4 稳定版本, 在今后还将不断推出新的特性 欢迎 Hyperchain 社区的爱好者一起参与到我们的开发到中! 15.1 First community version 这是 Hyperchain 的第一个社区版本, 包括了联盟链平台的完整组件 : 1. 基于 RBFT 算法的共识引擎 ; 2. 兼容以太坊的 EVM 智能合约虚拟机 ; 3. 数据分区, 从物理上实现业务隔离 ; 4. 丰富的事件订阅接口, 实时捕捉区块链平台动态 ; 129