Microsoft Word - 趣链科技Hyperchain运维手册V1.2.docx

Transcription

1 趣链科技 Hyperchain 运维手册 (V1.2) 2017 趣链科技版权所有

2 版本历史 ( 每次更新填写一个表单 ) 版本编号 1.0 编写人 戎佳磊 修改日期 2017 年 4 月 25 日 变更内容 1. 创建初始版本 版本编号 1.1 编写人 黄方蕾 修改日期 2017 年 6 月 20 日 变更内容 1. 修改部署步骤 版本编号 1.2 编写人 黄方蕾 修改日期 2017 年 7 月 6 日 变更内容 1. 增加单机部署四个节点脚本 2. 增加 peerconfig 配置示例 3. 增加日志归档详解 2017 趣链科技版权所有

3 目录 第 1 章前言 版本申明 服务申明... 1 第 2 章平台部署 上传 创建使用用户及文件权限 上传部署安装包 服务器单节点部署 一键部署 设置服务器出口流量限制 设置 Hyperchain 平台及其重启或宕机恢复后自动启动 启动 重新启动 停止 单服务器单节点简化部署 ( 测试推荐 ) 国密依赖库配置 启动 停止 单服务器四节点部署 ( 测试推荐 ) 国密依赖库配置 部署四节点 启动 停止... 8 第 3 章 Hyperchain 配置文件维护 修改配置 peerconfig.json pbft.yaml caconfig.yaml 趣链科技版权所有

4 3.1.4 global.yaml 节点出口流控配置 ( 投产推荐 ) 网络中心统一调控 TC(Traffic Control) 服务器端限流配置 Nginx 转发限流配置 版本升级 基本功能使用 启动 重新启动 停止 版本升级 第 4 章日志分级及归档方案 日志文件限制 日志文件分级 日志文件归档 第 5 章 CA 证书管理及使用方案 CA 证书体系 概念 CA 证书权限体系层次图 各 CA 证书用途 certgen 使用说明 certgen 安装 生成证书 检查证书 CA 证书签发管理方案 CA 生成及保管 节点 cert 签发 VP 节点 cert 文件配置 NVP 节点 cert 文件配置 第 6 章 VP 和 NVP 节点管理及使用方案 VP 节点管理 新增 VP 节点 趣链科技版权所有

5 6.1.2 删除 VP 节点 NVP 节点管理 新增 NVP 节点 删除 NVP 节点 VP 与 NVP 节点的相互转换 NVP 转 VP NVP 转 VP 第 7 章合约升级规范 变量定义 新增变量定义 删除变量定义 修改变量定义 更改变量定义顺序 变量声明 新增变量声明 删除变量声明 修改变量声明 更改变量声明顺序 函数定义 新增函数定义 删除函数定义 修改函数定义 更改函数定义顺序 编译合约 调用 SDK 编译 使用 Solc 编译器编译 合约升级 第 8 章 SDK 功能使用 初始化 初始化 Hyperchain 对象 HyperchainAPI 初始化 Hyperchain 对象 ( 带路径 ) 初始化 Hyperchain 对象 ( 带 APIProperties) 趣链科技版权所有

6 8.1.4 自动切换节点 Transaction 相关接口 实例化交易 交易签名 通过交易 hash 查询交易 查询指定交易中的收据信息 查询区块交易数量 Contract 相关接口 部署合约 System.out.println(handler.result); 调用合约 合约管理 Block 相关接口 取得最新区块信息 取得指定区块列表 取得指定区块 by hash 取得指定区块 by number 节点相关接口 取得节点信息 获取当前节点的哈希值 根据哈希值删除节点 NVP 根据 ID 值断开与 VP 节点的连接 返回值解析 通用返回值解析 ( 推荐 ) 复杂返回值解析 ( 不推荐 ) 账户相关接口 创建账户 ( 加密 ) 创建账户 ( 未加密 ) 创建账户 ( 返回值为 ECPriv) 加密明文私钥 解密私钥文件返回明文 Json 字符串 趣链科技版权所有

7 第 9 章异常处理 网络异常 单节点网络异常 数据异常 重新启动报错 invalid root 共识异常 重启后相同区块高度的节点数不超过规定数目 Viewchange 异常 Ignore duplicatoe 异常 第 10 章产品激活 续期 激活 续期 第 11 章联系与反馈 联系方式 注意事项 第 12 章附录 配置文件 caconfig.toml db.yaml genesis.json global.yaml pbft.yaml peerconfig.json static_peer.json 常见部署需求 peerconfig 配置示例 单机部署四个节点 同一网域内的四台服务器各部署一个节点 两个网域内的四台服务器各部署一个节点 趣链科技版权所有

8 第 1 章前言 1.1 版本申明 本文档著作权归趣链科技单独所有, 未经趣链科技事先书面许可, 任何主体不得以任何形式复制 修改 抄袭 传播全部或部分本文档内容 1.2 服务申明 本文档意在向客户介绍趣链科技区块链底层平台 ( 国密版 ) 的功能使用说明 您所购买的趣链科技的产品 服务的种类 服务标准等应由您与趣链科技之间的商业合同约定, 除非双方另有约定, 否则, 趣链科技对本文档内容不做任何明示或模式的承诺或保证 2017 趣链科技版权所有第 1 页

9 第 2 章平台部署 2.1 上传 创建使用用户及文件权限 创建平台部署所需的用户, 例如创建如下用户 : 用户名 :hyperchain 密码 :hyperchain 可用如下命令创建新用户 : sudo useradd -m -d /home/hyperchain -s /bin/bash -k /etc/skel hyperchain sudo passwd hyperchain 修改部署路径及数据存放路径的目录权限, 例如 /opt/hyperchain 及 /data/hyperchain sudo chown -R hyperchain: /opt/hyperchain sudo chown -R hyperchain: /data/hyperchain 上传部署安装包将我们向您提供的 Hyperchain 文件包上传至服务器并解压至相应的用户目录下 : scp hyperchain.tar hyperchain@hyperchain 服务器地址 :~ ssh hyperchain@hyperchain 服务器地址 cd ~ tar xvf hyperchain.tar cd hyperchain 一个完整的 hyperchain 文件包包含以下文件 : 2017 趣链科技版权所有第 2 页

10 2.2 服务器单节点部署 一键部署 部署前请先确定各配置参数已经配置正确, 然后进行如下操作 : cd ~/hyperchain./deploy-local.sh source ~/.bashrc Hyperchain 平台默认会安装到 /opt/hyperchain 目录下 如需更改目录, 请使用 '-d 目录名 ' 选项, 如 : cd ~/hyperchain./deploy-local.sh -d /opt/hyperchain source ~/.bashrc 部署完成可看到如下信息 : 2017 趣链科技版权所有第 3 页

11 2.2.2 设置服务器出口流量限制 root 用户运行如下命令可对服务器出口流量进行限制 : cd ~/hyperchain./tools/scripts/tc.sh 设置 Hyperchain 平台及其重启或宕机恢复后自动启动可通过如下步骤设置 Hyperchain 平台自动启动 : Suse11 系列的服务器 sudo vim /etc/init.d/after.local Suse12 系列 Centos 系列 Redhat 系列的服务器 sudo vim /etc/rc.local 在文件最后添加如下内容即可开机自动启动 Hyperchain 服务 : su hyperchain -c "/opt/hyperchain/scripts/start.sh" 如需开机自动加载流控可以在上面的基础上增加如下命令 : su - -c /opt/hyperchain/scripts/tc.sh 启动 启动某个节点的 hyperchain, 执行步骤如下 : hyperchain start 查看 hyperchain 的日志, 日志路径默认为 : ~/hyperchain/build/logs 2017 趣链科技版权所有第 4 页

12 若日志显示如下信息, 即表示节点都连上,hyperchain 平台部署启动完成 重新启动 重启某个节点的 hyperchain, 执行步骤如下 : hyperchain restart 停止 停止某个节点的 hyperchain, 执行步骤如下 : hyperchain stop 2.3 单服务器单节点简化部署 ( 测试推荐 ) 某个节点如果不想通过用户系统服务的方式启动 hyperchain, 而是想手动启 动 hyperchain 进程, 可以进入 hyperchain 目录, 按照以下描述执行启动 国密依赖库配置 hyperchain 的国密特性需要系统体统如下两个依赖库 : 我们将之放到 hyperchain/config/lib 目录下 2017 趣链科技版权所有第 5 页

13 目前我们可以通过运行以下脚本保证 hyperchain 正常运行 :./local-simple/env.sh -d /home/hyperchain/hyperchain/config/lib source ~/.bashrc 启动启动可用文件里提供的脚本, 也可直接输入命令行 : cd ~ cd hyperchain./local-simple/start.sh 或者./hyperchain >& /dev/null & 停止 如果想停止该 hyperchain 进程, 可以执行以下命令 :./local-simple/stop.sh 或者 pkill -9 hyperchain 2.4 单服务器四节点部署 ( 测试推荐 ) 当利用 Hyperchain 平台做一些简单测试时, 如果服务器资源不足可以选择 在一台机器上部署四个节点, 用户可以按照以下描述执行启动 国密依赖库配置 hyperchain 的国密特性需要系统体统如下两个依赖库 : 我们将之放到 hyperchain/config/lib 目录下目前我们可以通过运行以下脚本保证 hyperchain 正常运行 :./local-4-nodes/env.sh -d /home/hyperchain/hyperchain/config/lib source ~/.bashrc 2017 趣链科技版权所有第 6 页

14 2.4.2 部署四节点部署四个节点可以执行以下命令,-d 选项为设置部署目录, 示例如下 : cd ~ cd hyperchain./local-4-nodes/deploy.sh -d /home/hyperchain/app 部署完成之后可看到如下则表示部署成功 : 而指定部署目录则生成如下目录结构 : 启动启动可用文件里提供的脚本 : cd ~ cd app./start.sh 及使用 : 如看到类似如下日志则表示四个节点都启动成功, 用户可以对平台开始测试 2017 趣链科技版权所有第 7 页

15 2.4.4 停止 如果想停止该 hyperchain 进程, 可以执行以下命令 :./stop.sh 或者 pkill -9 hyperchain 2017 趣链科技版权所有第 8 页

16 第 3 章 Hyperchain 配置文件维护 Hyperchain 安装包的 config 目录如下所示 : 3.1 修改配置 Hyperchain 共有 7 个配置文件, 您需要在使用 hyperchain 服务之前根据您的需求及环境修改部分配置文件 在本节中将着重向您介绍较为重要的几个可修改的配置项, 剩余配置项的含义及配置方法详情可见附录 peerconfig.json peerconfig.json 是 Hyperchain 节点的网络配置文件 其中记录了当前节点的 2017 趣链科技版权所有第 9 页

17 启动方式 启动身份 区块链网络节点数目以及每个节点的网络配置信息 您在使用之前必须确保所有的网络配置正确, 且每个配置的端口是对外开放的 以机构 A 和机构 B 的部署各部署两个节点为例, 机构 A 局域网 (hyperchain- 1) 内的两个节点通过内网相连, 机构 B 局域网 (hyperchain-2) 内的两个节点通过内网相连, 它们的内外网 ip 如下 : 机构 A(hyperchain-1): node1: ( 内 ), ( 外 ) node2: ( 内 ), ( 外 ) 机构 B(hyperchain-2): node3: ( 内 ), ( 外 ) node4: ( 内 ), ( 外 ) 则机构 A 的 node1 的网络配置示例如下所示 : { "self":{ "is_reconnect":false, "is_origin":true, "is_vp":true, "node_id":1, "grpc_port":8001, "jsonrpc_port":8081, "restful_port":9001, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "introducer":{ "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, "maxpeernode":4, "nodes":[ 2017 趣链科技版权所有第 10 页

18 { "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":2, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":3, "domain":"hyperchain-2", "address":[ {"ip":" :8001","domain":"hyperchain-2", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":4, "domain":"hyperchain-2", "address":[ {"ip":" :8001","domain":"hyperchain-2", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081 ] 创世节点节点初次启动时, 前三项一次为 false,true,true;introduce 可不用 2017 趣链科技版权所有第 11 页

19 改动, 是新增节点的配置项 ;nodes 配置的是全网的连接项,domain 为节点在跟不同域的节点的连接时使用的不同 ip(default 为必配域, 一般填写所有节点都可链接的 ip),domain 指明选取 address 中那个 ip 进行链接 ;port 为节点间的 grpc 连接端口,rpc_port 为节点对外提供的 jsonrpc 端口 更详细的信息可以查询附录进行更多的配置修改 pbft.yaml pbft.yaml 中记录了所有 PBFT 算法涉及的配置项, 包括参与共识的节点个数 异常情况超时时长设置 区块容量 区块产生时间等等 默认的 pbft 配置信息如下所示 : pbft: # Number of replicas nodes: 4 # How many transactions should the primary pack before sending pre-prepare batchsize: 100 # How many times of same vc from self before a replica start recovery vcresendlimit: 10 # Timeouts timeout: # How long to wait for N-f responses after send negotiate view negoview: 6s # How long to wait before recovery finished(this is for release1.2) recovery: 15s # How long to wait before first request should come firstrequest: 30s yet, # Primary send a pre-prepare if there are pending requests, although batchsize isn't reached batch: 500ms # How long may a request(transaction batch) take between reception and execution, must be greater than the batch timeout 2017 趣链科技版权所有第 12 页

20 request: 3s # How long may a validate (transaction batch) process will take by local Validation validate: 2s # Primary send it to inform aliveness, must be greater than request timeout nullrequest: 4s # How long may a view change take viewchange: 4s # How long to wait for a view change quorum before resending (the same) view change resendviewchange: 8s # How long to clean out-of-data view change message cleanviewchange: 30s # How long may a update-n take update: 4s 我们推荐您将 batchsize 设置为 100,batchtime 设置为 500ms 使得系统拥有较高的交易处理能力 较低的交易处理时延 当然您也可以根据本身的需求修改 系统区块链节点数最小的合理值为 4, 您可以根据自身的需求进行修改, 只有创世节点需要对之进行准确配置, 新增节点只需要填写 4 即可 ( 新增节点会通过共识得到系统的节点数量 ) 由于一些异常情况超时时长 (timeout) 与共识算法的正确性密切相关, 因此我们不建议您对这部分内容进行修改 caconfig.yaml caconfig.yaml 中记录了 CA 权限验证相关的配置信息 一份默认的配置信息如下所示 : # CA & CERT configs # # this config prepare for ca & cert module # *.toml config file is batter than *.yaml # this config will never change by hyperchain # please ensure the file not end with the `/` (slash) # 2017 趣链科技版权所有第 13 页

21 [ecert] ca = "config/cert/eca.ca" cert = "config/cert/ecert.cert" priv = "config/cert/ecert.priv" [rcert] # if you do not have rcert, leave this item blank ca = "config/cert/rca.ca" cert = "config/cert/rcert.cert" priv = "config/cert/rcert.priv" # the tls cert supply the transport layer security [tlscert] ca = "config/cert/tlscert/tlsca.ca" cert = "config/cert/tlscert/tls_peer1.cert" priv = "config/cert/tlscert/tls_peer1.priv" serverhostoverride = "hyperchain.cn" [check] # check the ecert and rcert signature during the connect progress certsign = true # check the tcert during the request process tcert = true # check the ercert and rcert ercert = true [gm] # use sm4 or not sm4 = true 可以根据系统的所需的安全性, 建议选择开启或关闭 CA 权限控制, 开启方 式为将 certsign tcert ercert 值全部设置为 true global.yaml 在该配置文件中记录了剩余的一些配置项, 包括输出日志等级 输出日志文件的路径 是否开启流量控制等 ## Data storage path config # Note: please DONOT add a slash `/` in the end of directory path. # this relative path is relative to the hyperchain binary execute file path global: 2017 趣链科技版权所有第 14 页

22 ########################## # data storage config # ########################## account: keystoredir: "./build/keystore" keynodesdir: "./build/keynodes" dbconfig: "./config/db.yaml" structure: state: "hyperstate" # two available options: rawstate or hyperstate version: blockversion: "1.2" transactionversion: "1.2" ########################### # configs ############################ configs: caconfig: "config/caconfig.toml" peers: "config/local_peerconfig.json" genesis: "config/genesis.json" static_peers: "config/static_peers.json" pbft: "config/pbft.yaml" license: "config/license" replicainfo: interval : 500s enable : false ratelimit: enable : true txratepeak : 100 txfillrate: 0.5ms contractratepeak : 100 contractfillrate: 0.5ms buckettree: global: globaldatanodecachesize: globaldatanodecachelength: 20 state: size: levelgroup: 5 bucketcachesize: datanodecachesize: 趣链科技版权所有第 15 页

23 storage: size: levelgroup: 5 bucketcachesize: datanodecachesize: hmpublickey: "N": " " Nsquare: " " G: " " sync_chain: batch: 50 interval: 1m exitflag: false security: enabletls: false enablesymmetrical: false connection: retrytimelimit: 6 retrytimeout: 10s recoverytimelimit: 5 recoverytimeout: 5s keepalivetimelimit: 3 keepaliveinterval: 3s "h". ###################################################### # config log's level by module # # # # CRITICAL ERROR WARNING NOTICE INFO DEBUG # # high < log level > low # # # ###################################################### logs: # dump the log file or not dumpfile: true newlogfileinterval: 24h # Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", # such as "300ms", "2h45m". max_log_size: 200mb # "mb", "kb" split_start_stop_log: false # debug and normal mode, now true only for CEB logsdir: "./build/logs" # default loglevel for all modules which can be override by module level log setting 2017 趣链科技版权所有第 16 页

24 loglevel: "NOTICE" file_format: "[%{level:.5s] %{time:15:04: %{shortfile %{message" console_format: "%{color[%{level:.5s] %{time:15:04: %{shortfile %{message %{color:reset" module: #set log level by module p2p: "INFO" consensus: "NOTICE" core: "NOTICE" hyperdb: "NOTICE" 其中 logs 表示日志相关的配置选项 您可以通过修改 logs.dumpfile 来控制是否将输出日志重定向至日志文件中, 我们推荐您开启日志重定向 ; 在 logs.module 中您可以按照模块分别配置各个模块的日志等级, 我们推荐您所有模块的日志等级设置为 NOTICE 您可以修改 global.configs.ratelimit.enable 的值来控制是否开启流量控制, 建议根据测试的 tps 进行流控设置, 控制参数详见附录 3.2 节点出口流控配置 ( 投产推荐 ) 一般来说, 由于 hyperchain 平台的 tps 比较稳定, 流量根据 tps 也处于稳定状态, 但是例如节点宕机落后和增节点等特殊情况下的 recovery 行为会向其他节点区块, 为了避免公网共享带宽环境下不影响其他应用程序的带宽占用情况, 可根据需要对限制节点带宽 推荐以下三种流控方法 : 网络中心统一调控 可由各机构的网络中心进行调控配置, 由于各家机构策略不一, 不做详述, 可咨询各家机构的网络运维工作人员 TC(Traffic Control) 服务器端限流配置对于应用服务器来说, 报文分组从输入网卡 ( 入口 ) 接收进来, 经过路由的查找, 以确定是发给本机的, 还是需要转发的, 如果是转发的, 则会从输出网卡 ( 出口 ) 发出, 网络流量的控制通常发生在输出网卡处 一般说来, 由于我们无 2017 趣链科技版权所有第 17 页

25 法控制自己网络之外的设备, 入口处的流量控制相对较难, 因此我们这里处理的流量控制一般指出口处的流量控制 tc.sh 配置文件详解 : tc qdisc del dev eth0 root 2> /dev/null > /dev/null # 删除原有的 tc 规则 tc qdisc add dev eth0 root handle 1: htb # 为网卡 eth0 创建 htb 根队列 tc class add dev eth0 parent 1: classid 1:1 htb rate 100mbit ceil 100mbit # 为根队列创建子队列 1:1 分配带宽 100M tc class add dev eth0 parent 1:1 classid 1:10 htb rate 10mbit ceil 10mbit # 为 1:1 队列创建子队列 1:10 分配带宽 10M tc qdisc add dev eth0 parent 1:10 sfq perturb 10 # 防止一个段内的 ip 占用整个宽带 tc filter add dev eth0 protocol ip parent 1: prio 1 u32 match ip dst /16 flowid 1:1 # 为跟队列添加优先级为 1 的过滤器使得发往 xxx.xxx 的包转到 1:1 队列 tc filter add dev eth0 protocol ip parent 1: prio 2 u32 match ip dst /0 flowid 1:10 # 为跟队列添加优先级为 2 过滤器使得发往所有 ip 的包都转到 1:10 队列 tc.sh 的具体使用步骤和配置服务器重启自动生效等内容请参见本文档的 及 小节, 需要注意的是,tc.sh 的相关命令都需要 root 权限 Nginx 转发限流配置由于各家机构对节点服务器带宽要求不尽相同, 可能需要 nginx 做统一的转发限流 我们目前提供 nginx 安装包及三个脚本 :start.sh stop.sh reload.sh, 可通过这三个脚本满足基本 nginx 配置需求 我们继续以在 提到的两家机构为例, 假设 A 机构需要使用 nginx 做限流转发的话则为如下情况 : 机构 A(hyperchain-1): node1: ( 内 ),port:6665 node2: ( 内 ),port:6666 nginx: ( 内 ), ( 外 ) 机构 B(hyperchain-2): node3: ( 内 ), ( 外 ),port:8001 node4: ( 内 ), ( 外 ),port: 趣链科技版权所有第 18 页

26 则可编辑 nginx/conf/nginx.conf 如下 : stream { server { #node1 listen 6665; proxy_pass :6665; server { #node1-node3 listen 8003; proxy_pass :8001; proxy_upload_rate 500k; server { #node1-node2 listen 8004; proxy_pass :8001; proxy_upload_rate 500k; server { #node2 listen 6666; proxy_pass :6665; server { #node2-node3 listen 8013; proxy_pass :8001; proxy_upload_rate 500k; server { #node2-node4 listen 8014; proxy_pass :8001; proxy_upload_rate 500k; 需要注意的是, 如果通过 nginx 节点间已经建立好长连接, 这时如果修改 poxy_upload_rate 将不能通过 reload.sh 生效 所以, 务必配置好 nginx 启动后, 再启动 hyperchain 平台 2017 趣链科技版权所有第 19 页

27 3.3 版本升级 若您需要进行 hyperchain 的版本升级, 只需要通过以下步骤即可 : 停止 hyperchain 服务 hyperchain stop 替换可执行文件及需要修改的配置文件 重新启动 hyperchain 服务 hyperchain start 3.4 基本功能使用 启动 启动某个节点的 hyperchain, 执行步骤如下 : hyperchain start 查看 hyperchain 的日志, 日志路径默认为 : ~/hyperchain/build/logs 若日志显示如下信息, 即表示节点都连上,hyperchain 平台部署启动完成 重新启动 重启某个节点的 hyperchain, 执行步骤如下 : hyperchain restart 2017 趣链科技版权所有第 20 页

28 3.4.3 停止 停止某个节点的 hyperchain, 执行步骤如下 : hyperchain stop 3.5 版本升级 若您需要进行 hyperchain 的版本升级, 只需要通过以下步骤即可 : 停止 hyperchain 服务 hyperchain stop 替换可执行文件及需要修改的配置文件 重新启动 hyperchain 服务 hyperchain start 2017 趣链科技版权所有第 21 页

29 第 4 章日志分级及归档方案 global.yaml 的最后一部分为关于日志的配置 : ###################################################### # config log's level by module # # # # CRITICAL ERROR WARNING NOTICE INFO DEBUG # # high < log level > low # # # ###################################################### logs: # dump the log file or not dumpfile: true newlogfileinterval: 24h # Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". # such as "300ms", "2h45m". max_log_size: 200mb # "mb", "kb" split_start_stop_log: false # debug and normal mode, now true only for CEB logsdir: "./build/logs" # default loglevel for all modules which can be override by module level log setting loglevel: "NOTICE" file_format: "[%{level:.5s] %{time:15:04: %{shortfile %{message" console_format: "%{color[%{level:.5s] %{time:15:04: %{shortfile %{message %{color:reset" module: #set log level by module p2p: "INFO" consensus: "NOTICE" core: "NOTICE" hyperdb: "NOTICE" 4.1 日志文件限制 # dump the log file or not dumpfile: true newlogfileinterval: 24h # Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". # such as "300ms", "2h45m". max_log_size: 200mb # "mb", "kb" split_start_stop_log: false # debug and normal mode, now true only for CEB 2017 趣链科技版权所有第 22 页

30 dumpfile 参数选择是否要生成日志文件 ; newlogfileinterval 可配置日志生成间隔, 一般选择 24h, 可根据具体需求更改 ; max_log_size 可配置日志文件大小上限, 和 newlogfileinterval 配合任意目标达成即会切分日志 ; split_start_stop_log 则可选择是否将每次启动的日志文件进行启动日志和运行日志的区分 4.2 日志文件分级 # default loglevel for all modules which can be override by module level log setting loglevel: "NOTICE" file_format: "[%{level:.5s] %{time:15:04: %{shortfile %{message" console_format: "%{color[%{level:.5s] %{time:15:04: %{shortfile %{message %{color:reset" module: #set log level by module p2p: "INFO" consensus: "NOTICE" core: "NOTICE" hyperdb: "NOTICE" loglevel 设定了 hyperchain 运行的默认日志级别 ; file_format 可配置日志文件的输出格式 ; console_format 可配置屏幕输出的日志格式 ; module 则可配置任意模块的日志级别, 可以根据具体情况进行修改 4.3 日志文件归档 logsdir: "./build/logs" logdir 可以配置日志文件的生成位置, 一般推荐 /data/hyperchain 目录 我们另外提供了对日志文件进行归档整理的脚本, 如下所示 : cd ~/hyperchain 2017 趣链科技版权所有第 23 页

31 ./tools/scripts/clean-log.sh -t 设置需要清理的时间线 -s 设置清理路径 -d 设置归档路径 -c 设置是否日志归档脚本的日志生成位置运行该脚本可以将日志目录下在设定时间线之前的日志统一转移到归档目录中 2017 趣链科技版权所有第 24 页

32 第 5 章 CA 证书管理及使用方案 5.1 CA 证书体系 在 Hyperchain 系统中共有一下四种不同类型的证书, 首先先简要地介绍一下各种证书 概念 l ECert & ECA ECert (Enrollment Certcate) 准入证书 ECA (Enrollment Certiticate Authority) 准入证书认证机构 l RCert & CA RCert (Role Certcate) 角色证书 RCA (Role Certiticate Authority) 角色证书认证机构 l TCert & CA TCert (Transaction Cert) 交易证书 TCA (Transaction Certiticate Authority) 交易证书认证机构 l TlsCert & CA TlsCert(Transport Layer Security) 安全传输层协议证书 TlsCA (Transaction Certiticate Authority) 安全传输层协议证书认证机构 2017 趣链科技版权所有第 25 页

33 5.1.2 CA 证书权限体系层次图 各 CA 证书用途 l ECert 用于控制区块链节点 ( 包括 VP,NVP) 进入 Hyperchain, 持有 Ecert 的节点以及 SDK 才能够访问区块链网络 l RCert 用于区分 VP 和 NVP 节点, 持有 RCert 的节点才能被承认为 VP 节点, 反之均被视为 NVP l TCert 用于实现伪匿名交易, 在发起 SendTransaction 的时候需要使用 TCert 相匹配的私钥对 Transaction 进行加密,TCert 可以实现线上申请, 由各个节点签发, 每一条 Transaction 可以用一个新的 TCert 进行签名, 可以实现每条交易的相对匿名, 但是可以由签发方审查 l TlsCert 用于传输层安全协议证书, 即在传输网络传输过程中需要验证传输层安全协议证书的安全性, 验证通过即可以进行正常网络通信, 反之则无法进行网络通信 2017 趣链科技版权所有第 26 页

34 5.2 certgen 使用说明 certgen 安装 将相应的 certgen 发行版本解压到操作系统 Path 目录下即可 : 以 centos 6.5 为例 : 管理员 : tar zxf certgen-centos-6.5.tar.gz C /usr/local/bin 普通用户 : tar zxf certgen-centos-6.5.tar.gz C ~ 注意, 普通用户使用的时候如果无法放到 path 搜索目录, 则下面的命令用./certgen 运行 生成证书 Certgen 启动界面如下 : 签发根证书 ( 自签证书 ), 命令如下 : certgen selfgen./root.ca./root.priv 2017 趣链科技版权所有第 27 页

35 运行上述命令, 会在指定路径生成 root.ca root.priv 两个文件, 即根证书文 件 签发子证书 : certgen gc./root.ca./root.priv./subcert.cert./subcert.priv 另外需要注意的是 : 在签发子证书时, 默认生成的子证书, 不可以签发子证书 若需要具有子证书签发功能, 则需要在签发该证书时加入 -c 参数 在 hyperchain 平台中,ECert 以及 RCert 均为根证书 root.ca 的字证书 签发命令如下 : 签发 RCA:certgen gc./root.ca./root.priv./rca.ca./rca.priv -c 签发 RCert: certgen gc./rca.ca./rca.priv./rcert.cert./rcert.priv 签发 ECA:certgen gc./root.ca./root.priv./eca.ca./eca.priv -c 签发 ECert: certgen gc./eca.ca./eca.priv./ecert.cert./ecert.priv -c 特别说明 : 为 SDK 签发的 ECERT 应该不允许其签发子证书, 故应当用如下命令签发证书 : 签发 SDK ECert: certgen gc./eca.ca./eca.priv./ecert.cert./ecert.priv 用于 grpc 网络传输安全的 TlsCert 签发命令如下 : 签发 TlsCA:certgen selfgen./tlsca.ca./tlsca.priv 签发 TlsCert:certgen gc./tlsca.ca./tlsca.priv./tls_peer.cert./ tls_peer.priv 检查证书检查子证书是否由该 CA 证书签发 : certgen cc root.ca subcert.cert 2017 趣链科技版权所有第 28 页

36 检查证书签名是否有效 : certgen ccs./root.ca 5.3 CA 证书签发管理方案 CA 生成及保管举例来说, 机构 A 和机构 B 各有两个节点作为联盟链的初创成员同时管理 RootCA,RCA,ECA,TlsCA, 可由其中一个机构通过 certgen 工具使用如下命令生成, 双方同时保管 : 签发 RootCA:certgen selfgen./root.ca./root.priv 签发 RCA:certgen gc./root.ca./root.priv./rca.ca./rca.priv -c 签发 ECert: certgen gc./eca.ca./eca.priv./ecert.cert./ecert.priv -c 签发 TlsCA:certgen selfgen./tlsca.ca./tlsca.priv 节点 cert 签发创世的四个 VP 节点需要使用以上 CA 通过 certgen 的如下命令生成各自节点的一套证书 : 签发 RCert: certgen gc./rca.ca./rca.priv./rcert.cert./rcert.priv 签发 ECert: certgen gc./eca.ca./eca.priv./ecert.cert./ecert.priv c 签发 TlsCert:certgen gc./tlsca.ca./tlsca.priv./tls_peer.cert./ tls_peer.priv VP 节点 cert 文件配置 一个同时拥有共识投票和记账功能, 并且开启了 tls 的 VP 节点, 它的 config 目录下的 cert 文件配置如下 : 2017 趣链科技版权所有第 29 页

37 5.3.4 NVP 节点 cert 文件配置 一个只拥有记账功能, 并且开启了 tls 的 NVP 节点, 它的 config 目录下的 cert 文件配置如下 : 2017 趣链科技版权所有第 30 页

38 第 6 章 VP 和 NVP 节点管理及使用方案 VP 节点指在联盟链中参与共识投票和记账的节点 ;NVP 节点指在联盟链中只参与记账的节点, 可供外部查询或为 VP 节点做热备份 本章所描述的节点管理及使用方案皆基于以下案例 仍以在上一章中已经提到的机构 A 和机构 B 为例, 两家机构同时保管 RootCA,ECA,RCA,TlsCA 两家机构各有两个节点作为创世节点启动, 它们的 ip 配置如下 : 机构 A(hyperchain-1): node1: ( 内 ), ( 外 ) node2: ( 内 ), ( 外 ) 机构 B(hyperchain-2): node3: ( 内 ), ( 外 ) node4: ( 内 ), ( 外 ) 6.1 VP 节点管理 新增 VP 节点在上述提到的案例中, 在已有两家机构共四个节点的基础上, 若您需要新增一家机构 C( 网域 hyperchain-3 ) 的 VP 节点如下 : 机构 C(hyperchain-3): node5: ( 内 ), ( 外 ) 新增 VP 节点方案目前我们仅支持一次动态增加一个 VP 节点, 新增方案如下 : 申请端口和 IP 的白名单访问 : 机构 C 需要向机构 A 和机构 B 申请节点间通讯的 IP 和 GRPC 端口的访问, 并且自己也开放反向访问 ; 同时机构 C 内部开通 JSONRPC 和 RESTFUL 服务端口用于内部调用 申请证书 : 机构 C 需要向 CA 托管方申请 CA 证书, 在本案例中机构 C 需要同时获得 A,B 两家机构认证后得到由其中一家机构生成的 RCert 和 ECert( 具 2017 趣链科技版权所有第 31 页

39 签发功能 ) 保证 VP 节点权限,TlsCert 保证节点间通信安全所需,ECert( 不具签发功能 ) 保证机构内 SDK 调用节点接口 部署启动 VP 节点 : 将所需节点 cert 按照上一章描述的结构配置后置于 config 目录下,VP 节点即可启动, 部署安装流程同创世节点一致, 具体可参考部署手册 需要注意的是, 目前新增节点操作需要全网 VP 节点都在线才可进行 VP 节点的配置保持 config 配置与其他节点一致, 修改网络配置文件 peerconfig.json 和 pbft.yaml 文件即可, 机构 C 的 node5 的 peerconfig.json 文件需要的修改如下图所示 : { "self":{ "is_reconnect":false, "is_origin":false, "is_vp":true, "node_id":5, "grpc_port":8001, "jsonrpc_port":8081, "restful_port":9001, "domain":"hyperchain-3", "address":[ {"ip":" :8001","domain":"hyperchain-3", {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"hyperchain-2", {"ip":" :8001","domain":"default" ], "introducer":{ "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, "maxpeernode":4, 2017 趣链科技版权所有第 32 页

40 "nodes":[ { "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":2, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":3, "domain":"hyperchain-2", "address":[ {"ip":" :8001","domain":"hyperchain-2", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":4, "domain":"hyperchain-2", "address":[ {"ip":" :8001","domain":"hyperchain-2", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081 ] 2017 趣链科技版权所有第 33 页

41 需要注意的是 : l 节点 id 序列号依次增加 ; l introducer 为介绍人节点的相关信息, 一般选择创世节点为介绍人 ; l maxpeernodes 填新节点未加入前区块链网络的节点数 ; l nodes 只需要填创世节点的信息即可 pbft.yaml 需要的修改如下图所示 : pbft: # Number of replicas nodes: 4 # How many transactions should the primary pack before sending pre-prepare batchsize: 100 # How many times of same vc from self before a replica start recovery vcresendlimit: 10 # Timeouts 需要注意的是 :nodes 为新节点加入前的联盟节点数量 VP 节点成功加入 VP 节点成功加入的日志显示如下 : VP 节点加入共识其实需要两个步骤 : 确认所有 VP 反连后进入 recovery; 2017 趣链科技版权所有第 34 页

42 recovery 结束后全网更新共识参数 这样做的目的就是为了新的 VP 节点时以一个 recovery 完成 ( 即与其他节点区块高度同步 ) 的 好节点 身份加入时, 才能更新系统参数而不影响整个系统共识负荷 删除 VP 节点 VP 节点的删除需要全网节点在线, 并且平台目前仅支持在 VP 节点总数大于等于 5 的情况下一次删除一个 VP 节点 本节将在上一节描述的增加了机构 C 的 node5 的情况下, 现在要删除机构 B 的 node 删除 VP 节点方案节点提出申请 : 为了保障 VP 节点的权益, 删除一个 VP 节点需要由该节点自己提出申请, 该节点管理员通过调用 SDK 的得到节点哈希 <NodeHash>, 还需要将 <NodeHash> 发送给所有其他 VP 节点的管理员 所有 VP 节点同意删除 : 所有 VP 节点 ( 包括该节点自己 ) 管理员需要在拿到该节点的 <NodeHash> 后调用 SDK 的删除节点命令删除该节点 成功删除 : 其他 VP 节点将会断开与该节点的连接, 同时更新共识参数 ; 而该节点则会自动退出程序, 但还需要管理员终止服务运行 (hyperchain stop, 参考部署手册 ) VP 节点成功删除 VP 节点成功删除后,5 号节点的日志如下 : 需要注意的是,5 号节点已经更新为 4 号节点,VP 节点的序号会从 1 递增, 不存在空缺 6.2 NVP 节点管理 NVP 节点作为不参与共识的节点, 可以选择一到多个 VP 节点连接, 一般来 2017 趣链科技版权所有第 35 页

43 说一家机构内会选择机构内部的 VP 节点作为 NVP 节点的连接对象 新增 NVP 节点继续本章的案例, 现在机构 A 想要在机构内部增加一个 NVP 节点, 该 NVP 节点与原有的 node1 和 node2 相连, 该节点信息如下 : 机构 A(hyperchain-1): NVP: ( 内 ) 新增 NVP 节点方案申请 IP 和端口 : 机构 A 需要为 NVP 节点申请内网的 IP 和各类端口的访问权限, 由于该节点仅选择与 node1 和 node2 相连, 不需要做外网申请 申请证书 :NVP 节点需要申请联盟链准入的 ECert 和用于节点间安全通信的 TlsCert, 可由机构 A 内部签发, 部署启动 NVP 节点 : 将所需节点 cert 按照上一章描述的结构配置后置于 config 目录下,VP 节点即可启动, 部署安装流程同创世节点一致, 具体可参考部署手册 NVP 节点的配置保持 config 配置与其他节点一致, 修改网络配置文件 peerconfig.json 即可, 该 NVP 节点需要的修改如下图所示 : { "self":{ "is_reconnect":false, "is_origin":false, "is_vp":false, "node_id":0, "grpc_port":8001, "jsonrpc_port":8081, "restful_port":9001, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":" hyperchain-1", {"ip":" :8001","domain":"default" ], "introducer":{ 2017 趣链科技版权所有第 36 页

44 "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, "maxpeernode":4, "nodes":[ { "id":1, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, { "id":2, "domain":"hyperchain-1", "address":[ {"ip":" :8001","domain":"hyperchain-1", {"ip":" :8001","domain":"default" ], "port":8001, "rpc_port":8081, ] 需要将 "is_origin" 字段设置为 false,"is_vp" 字段设置为 false,"node_id" 字段 设置为 0,"maxpeernode" 字段设置为与该节点相连接的 VP 节点数量, 在 "nodes" 字段中配置连接的 VP 详情 其余字段与 VP 配置类似 NVP 节点成功加入 NVP 成功加入后的日志如下图所示 : 2017 趣链科技版权所有第 37 页

45 即表示该 NVP 节点已经和所有配置的 VP 节点建立连接, 可作为查询节点热备份 删除 NVP 节点 NVP 节点的删除需要所连的 VP 节点都在线, 本节将在上一节描述的机构 A 新增了一个 NVP 节 N 点的基础上删除它 NVP 节点删除方案如下 : 节点提出申请 : 为了保障被连接的 VP 节点的权益, 删除一个 NVP 节点需要经其连接的所有 VP 节点同意 ; 与之相连的 VP 节点管理员通过调用 SDK 的得到节点哈希 <NodeHash> 返回给该 NVP 节点, 表示同意删除 NVP 节点与所有 VP 节点断开连接 :NVP 节点拿到所有 VP 节点的 <NodeHash> 后调用 SDK 断开与所连 VP 节点的连接 成功删除 :NVP 节点将会断开所有相连的 VP 节点的连接后退出程序, 但还需要管理员终止服务运行 (hyperchain stop, 参考部署手册 );VP 节点也会反向断开与该 NVP 节点的连接 6.3 VP 与 NVP 节点的相互转换 NVP 转 VP NVP 节点转为 VP 节点, 首先遵循 节的方案删除该 NVP 节点, 删除成功后, 根据 的方案增加 VP 节点 NVP 转 VP VP 节点转为 NVP 节点, 需要先按照 的方案删除 VP 节点, 删除成功后再按照 的方案增加 NVP 节点 2017 趣链科技版权所有第 38 页

46 第 7 章合约升级规范 对于已部署到区块链上的智能合约做版本升级需要用到合约升级的功能 合约编码者要注意一个正确的新版合约需要满足以下所有的升级规范, 若不符合以下规范而进行合约代码升级的话, 在之后的合约调用过程中, 会出现变量内容读取失败 变量内容读取异常 虚拟机执行失败等情况, 造成合约中存储的数据与变量名无法对应的情况 出现这种情况, 可能会造成合约中某些数据永久无法恢复 因此合约编码者若需要做合约升级, 请务必阅读以下升级规范 注意, 不规范的新版合约在升级过程中是不会报错的, 即使在造成了数据混乱的情况下, 在之后的调用过程中, 虚拟机也有可能是不会报错的, 即调用者感知错误比较困难 7.1 变量定义 新增变量定义新版合约若需要新增变量定义, 注意一定要在旧版合约变量定义的基础上, 在尾部追加新定义 示例 : // 旧版合约 pragma solidity ^0.4.4; contract Demo { uint var1; string var2; 若旧版合约源码如上所示, 在合约中定义了两个类型为 uint 和 string 的变 量, 若新版合约想要新增类型为 bytes32 类型的变量 var3, 正确的定义方式为 : // 正确的新版合约 pragma solidity ^0.4.4; contract Demo { uint var1; string var2; byte32 var3; // 将新增的变量定义追加在旧合约变量定义的尾部 2017 趣链科技版权所有第 39 页

47 而以下这种新增变量定义的行为均是错误的 : // 错误的新版合约 pragma solidity ^0.4.4; contract Demo { uint var1; byte32 var3; // 将新增的变量定义插入在旧合约变量定义的中间 string var2; 删除变量定义新版合约若需要删除部分在旧合约中定义的变量, 需要注意的是只能删除在尾部定义的变量 示例 : // 旧版合约 pragma solidity ^0.4.4; contract Demo { uint var1; string var2; 若旧版合约源码如上所示, 在合约中定义了两个类型为 uint 和 string 的变量, 若新版合版合约试图删除变量 var2 的定义, 这种行为是容许的 正确示例 : // 正确的新版合约 pragma solidity ^0.4.4; contract Demo { uint var1; // string var2; // 删除了定义在 尾部 的变量 若新版合约试图删除变量 var1 的定义, 这种行为是错误的 错误示例 : // 错误的新版合约 pragma solidity ^0.4.4; contract Demo { // uint var1; // 删除了定义在 非尾部 的变量 string var2; 2017 趣链科技版权所有第 40 页

48 即合约编码者想要在新版合约中删除部分旧变量的定义, 当且仅当删除的这 些旧变量全部是定义在尾部的才是合法的 修改变量定义更改变量定义的变量名是允许的, 更改变量的类型是不被允许的 // 旧版合约 pragma solidity ^0.4.4; contract Demo { uint var1; string var2; 修改变量名的示例如下, 这种行为是合法的 : // 正确的新版合约 pragma solidity ^0.4.4; contract Demo { uint var3; // 将变量名由 var1 改为了 var3, 合法 string var4; // 将变量名由 var2 改为了 var4, 合法 修改变量的类型的示例如下, 这种行为是错误的 : // 错误的新版合约 pragma solidity ^0.4.4; contract Demo { uint8 var1; // 将变量 var1 的类型改为 uint8, 不合法 bytes32 var2; // 将变量 var2 的类型改为 bytes32, 不合法 更改变量定义顺序修改变量定义的顺序是不被允许的 以下有个错误示例, 合约编码者在新版合约中将旧版合约定义的 var1,var2 调换了定义顺序 : // 旧版合约 pragma solidity ^0.4.4; contract Demo { uint var1; 2017 趣链科技版权所有第 41 页

49 string var2; // 错误的新版合约 pragma solidity ^0.4.4; contract Demo { string var2; uint var1; 7.2 变量声明 新增变量声明变量声明包括例如结构体的声明, 枚举类型的声明等 新增变量声明是允许的, 且允许声明在合约的任意位置 示例如下 : // 旧版合约 pragma solidity ^0.4.4; contract Demo { uint var1; string var2; 以下几种新增定义方式都是合法的 // 正确的新版合约 pragma solidity ^0.4.4; contract Demo { // 将结构体 User 声明在合约首部, 合法 struct User { bytes32 ID; uint balance; uint var1; string var2; // 将枚举类型 UserType 声明在合约尾部, 合法 enum UserType{ STUDENT, TEACHER, STUFF 2017 趣链科技版权所有第 42 页

50 7.2.2 删除变量声明若在新版合约中删除旧版合约中未使用的变量声明, 这种行为是合法的 ; 若在新版合约中删除旧版合约正在使用的变量声明, 这种行为是错误的 // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; 若在新版合约中删除未使用的变量声明 ClassType, 这种行为是合法的 : // 正确的新版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF // enum ClassType {MATH, ENGLISH, CHINESE // 删除未使用的 enum 类型声明, 合法 struct User { string id; UserType t; User[] users; 若在新版合约中删除正在使用的变量声明 UserType, 这种行为是错误的 : // 错误的新版合约 contract Demo { // enum UserType {STUDENT, TEACHER, STUFF // 删除正在使用的 enum 类型声明 // 非法 enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; 2017 趣链科技版权所有第 43 页

51 UserType t; User[] users; 修改变量声明修改已有的变量声明是错误的 // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; 错误示例 // 错误的新版合约 contract Demo { enum UserType {STUDENT, TEACHER // 删除了 UserType 中的 STUFF 枚举项, 非法 enum ClassType {MATH, ENGLISH, CHINESE struct User { // string id; // 删除了 User 结构体中的 id 字段, 非法 UserType t; ClassType c; // 新增了类型为 ClassType 的 c 字段, 非法 User[] users; 更改变量声明顺序 更改变量声明的顺序是合法的 示例如下 : 2017 趣链科技版权所有第 44 页

52 // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; // 正确的新版合约 contract Demo { // 调换了 User 结构体,ClassType,UserTyep 枚举类型的声明位置, 合法 struct User { string id; UserType t; enum ClassType {MATH, ENGLISH, CHINESE enum UserType {STUDENT, TEACHER, STUFF User[] users; 7.3 函数定义 新增函数定义所有新增函数定义的行为都是合法的 示例 : // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; 2017 趣链科技版权所有第 45 页

53 function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); // 正确的新版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); // 新增 AddTeacher 函数定义, 合法 function AddTeacher (string id) { users.push(user(id, UserType.TEACHER)); 删除函数定义所有删除函数定义的行为都是合法的 示例 : // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); 2017 趣链科技版权所有第 46 页

54 在新版合约中删除了 AddStudent 函数, 合法 // 正确的新版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; // 删除了函数 AddStudent, 合法 // function AddStudent(string id) { // users.push(user(id, UserType.STUDENT)); // 修改函数定义所有修改函数定义的行为都是合法的示例 : // 旧版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); 修改了 AddStudent 函数的定义, 合法 2017 趣链科技版权所有第 47 页

55 // 正确的新版合约 contract Demo { enum UserType {STUDENT, TEACHER, STUFF enum ClassType {MATH, ENGLISH, CHINESE struct User { string id; UserType t; User[] users; uint usercnt; // 在变量定义尾巴追加定义 uint 类型的变量 usercnt, 合法 function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); usercnt += 1; // 更改函数逻辑, 合法 更改函数定义顺序所有更改函数定义顺序的行为都是合法的示例 : // 旧版合约 contract Demo { struct User { string id; UserType t; enum ClassType {MATH, ENGLISH, CHINESE enum UserType {STUDENT, TEACHER, STUFF User[] users; function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); function AddTeacher(string id) { users.push(user(id, UserType.TEACHER)); 2017 趣链科技版权所有第 48 页

56 // 新版合约 contract Demo { struct User { string id; UserType t; enum ClassType {MATH, ENGLISH, CHINESE enum UserType {STUDENT, TEACHER, STUFF User[] users; // 更改 AddTeacher 与 AddStudent 两个函数的定义顺序, 合法 function AddTeacher(string id) { users.push(user(id, UserType.TEACHER)); function AddStudent(string id) { users.push(user(id, UserType.STUDENT)); 7.4 编译合约 调用 SDK 编译 使用 SDK 的编译合约接口进行新版合约的编译, 获取编译后的二进制字节 码 ( 详细使用说明见用户 SDK 手册 ) 使用 Solc 编译器编译使用官方的 solidity 编译器对新版合约进行编译, 获取新版合约编译后的二进制字节码 注意 :solidity 编译器有很多版本, 不同版本的 solc 对同一份源码编译出来的二进制会有差异, 因此最好使用与编译旧合约统一版本的 solc 编译器 合约升级 调用 SDK 的合约升级接口进行合约升级的动作 注意升级合约交易的发起 者必须是合约的部署者 2017 趣链科技版权所有第 49 页

57 第 8 章 SDK 功能使用 更多 SDK 接口使用请参考 Hyperchain Java SDK 文档 v 初始化 初始化 Hyperchain 对象 HyperchainAPI 配置文件 :hpc.properties # 初始化 HyperchainAPI 的 #Hyperchain Nodes IP Ports node={"nodes":[" :8081"," :8082"," :8083"," :8084"] # 重发次数 resendtime = 10 # 第一次轮训时间间隔 unit /ms firstpollinginterval = 1000 # 发送一次, 第一次轮训的次数 firstpollingtimes = 10 # 第二次轮训时间间隔 unit /ms secondpollinginterval = 1000 # 发送一次, 第二次轮训的次数 secondpollingtimes = 10 #Send Tcert during the request or not SendTcert = false #if sendtcert is true, you should add follow path. ecertpath = src/test/resources/certs/ecert.cert ecertpripath = src/test/resources/certs/ecert.priv uniqueprivpath = src/test/resources/certs/unique.priv uniquepubpath = src/test/resources/certs/unique.pub/ HyperchainAPI hyperchain = new HyperchainAPI(); 该对象用于提供各类接口方法 说明 :node 表示平台各节点的 IP 以及端口,resendTime 参数表示重发次数 ; firstpollinginterval 表示第一阶段轮训去获取交易的时间间隔, 单位为毫秒 ; firstpollingtimes 表示发送一次交易的轮训次数 ;secondpollinginterval 表示第一阶段轮训去获取交易的时间间隔, 单位为毫秒 ;secondpollingtimes 表示发送一 2017 趣链科技版权所有第 50 页

58 次交易的轮训次数 ;SendTcert 表示是否打开 TCA 认证开关,ecertPath 表示 Ecert 的路劲,EcertPriPath 表示 Ecert 私钥的路径,uniquePrivPath 表示 SDK 私钥路径, uniquepubpath 表示 SDK 公钥路径, 用于向平台申请 TCert 证书 初始化 Hyperchain 对象 ( 带路径 ) new HyperchainAPI(path); 注意 : 传入的路径即为 hpc.properties 文件的路径 hpc.properties 的文件格式如 所示相同 HyperchainAPI hyperchain = new HyperchainAPI(./hpc.properties ); 初始化 Hyperchain 对象 ( 带 APIProperties) new HyperchainAPI(apiProperities); apiproperities 初始化方法 1. apiproperities() // 带部分默认值, 默认值与 所示的 hpcproperties 一致 2. apiproperities(string properitiespath) // 路径为 hpc.properties 路径 另外对于 apiproperties, 可以利用 set 方法进行赋值, 可赋值变量有 : String node; int resendtimes; int firstpollinginterval; int firstpollingtimes; int secondpollinginterval; int secondpollingtimes; boolean sendtcert; String ecertpath; String ecertpripath; String uniqueprivpath; String uniqurpubpath; 说明 :node 表示平台各节点的 IP 以及端口,resendTime 参数表示重发次数 ; firstpollinginterval 表示第一阶段轮训去获取交易的时间间隔, 单位为毫秒 ; firstpollingtimes 表示发送一次交易的轮训次数 ;secondpollinginterval 表示第一阶段轮训去获取交易的时间间隔, 单位为毫秒 ;secondpollingtimes 表示发送一 2017 趣链科技版权所有第 51 页

59 次交易的轮训次数 ;SendTcert 表示是否打开 TCA 认证开关,ecertPath 表示 Ecert 的路劲,EcertPriPath 表示 Ecert 私钥的路径,uniquePrivPath 表示 SDK 私钥路径, uniquepubpath 表示 SDK 公钥路径, 用于向平台申请 TCert 证书 apiproperities apiproperities = new apiproperities(); Hyperchain hyperchain = new HyperchainAPI(apiProperities) 自动切换节点在实例化 HyperchainAPI 对象的时候, 将会先读取配置文件所有节点的信息, 如果向 Hyperchain 某个节点请求失败,SDK 可以自动切换链上相应节点, 请配合最新版本的 hyperchain 使用 8.2 Transaction 相关接口 实例化交易 实例化普通交易普通交易主要是用于普通转账 : /** * from from 账户地址 to to 账户地址 value 转账金额 simulate 是否共识 */ public Transaction(String from,string to,long value,boolean simulate) // 以 address1: 向 address2 转账 53 单位值为例 : Transaction mytransaction = new Transaction(address1,address2,53L,true); 实例化合约部署交易 ( 无构造参数 ) 2017 趣链科技版权所有第 52 页

60 /** * 部署智能合约 ( 构造函数无参 ) from from 账户地址 payload 智能合约 bin simulate 是否共识 */ public Transaction(String from,string payload,boolean simulate) // 例子 : // 若已经编译得到智能合约的二进制代码 bin Transaction mytransaction = new Transaction(address1,bin,true); 实例化合部署约交易 ( 有构造参数 ) /** * 部署智能合约, 构造函数无参 from from 账户地址 payload 智能合约 bin simulate 是否共识 params 智能合约构造函数参数 FunctionParamException 参数非法异常 */ public Transaction(String from, String payload, boolean simulate, FuncParamReal... params) throws FunctionParamException // 例子 : // 以构造函数参数为 int32 类型, 值为 8 为例 // 构造参数对象 FuncParamReal funcparam = new FuncParamReal( int32,8); Transaction mytransaction = new Transaction(fromAddress,bin,true, funcparam); 交易签名构造完成之后的交易需要进行签名, 可以用如下方法进行签名 利用加密之后私钥字符串和加密密钥进行签名 /** *@param accountjson 加密后的密钥对 JSON 字符串 *@param passwd 加密密钥对密码 */ // 初始化一笔普通交易 Transaction transaction = new Transaction(TEST_FROM, TEST_TO, 53L, false); transaction. sign (TEST_PRIJSON, TEST_PASSWD); 利用未加密私钥进行签名 2017 趣链科技版权所有第 53 页

61 /** accountjson 密钥对字符串 */ Transaction transaction = new Transaction(address,bin,false); transaction. sign (privstring); 通过交易 hash 查询交易 SingleValueReturn gettxbyhash(string txhash, int id) /** * 查询交易 by TxHash * txhash 交易 Hash id 查询批次 单值返回值返回交易信息 json 字符串 */ hyperchain.gettxbyhash(txhash,id); result.getresult(); // 取得交易 hash 查询指定交易中的收据信息 ReceiptReturn gettransactionreceipt(string TxHash) /** * 查询指定交易中的收据信息 TxHash 交易 hash ReceiptReturn Receipt 返回 */ String txhash ="0x25cc67f7cb5c5393f419c2ea2be8ac a64fcda5b1afef2694f e" ReceiptReturn result = hyperchain.gettransactionreceipt(txhash); result.getcontractaddress(); // 合约地址 result.getret(); // 调用合约返回值 // 如果是合约部署交易的回执, 将会有合约地址, 否则合约地址字段为全零值 查询区块交易数量 SingleValueReturn getblktxcountbyhash(string blkhash) /** * 查询区块交易数量 blkhash 区块 hash id 查询批次 交易数目 16 进制表示 */ 2017 趣链科技版权所有第 54 页

62 hyperchain. getblktxcountbyhash(blkhash); result.getresult(); 8.3 Contract 相关接口 部署合约 同步说明 : 无参数的构造函数将会自动调用, 部署该类合约请用本方法 SingleValueReturn deploycontract(transaction transaction) throws Exception /** * 部署合约 from 部署账户地址 部署交易 Hash SingleValueReturn Exception */ StdReturn result = hyperchain.deploycontract(transaction); result.getresult(); // 合约部署交易返回 hash 异步 deployaysnccontract(transaction transaction,final AsyncHandler callback) /** * 3.2 部署合约 ( 构造函数 ) Transaction 交易结构体 AsyncHandler 异步回调, 需要实现此接口 Exception */ // 首先实现 AsyncHandler 接口 public class AsyncHandlerTest implements AsyncHandler{ public String result = public void onsuccess(stdreturn ret) { result = ret.getresult(); public void onfailed(stdreturn ret) { result = "failed"; // 再进行异步调用 2017 趣链科技版权所有第 55 页

63 AsyncHandlerTest handler = new AsyncHandlerTest(); // 构造交易 Transaction transaction = new Transaction(yourfrom,targetBin,false); // 签名交易 transaction.signwithsm2(accountjson,secretkey); // 异步部署 hyperchain.deployaysnccontract(transaction,handler); while(handler.result==""){ Thread.sleep(100); System.out.println(handler.result); 调用合约 同步 SingleValueReturn invokecontract(transaction transaction) throws InterruptedException /** * 调用智能合约 transaction 智能合约交易 返回单个 string 返回值交易 hash */ SingleValueReturn result = hyperchain.invokecontract(transaction); // 取得交易 hash result.getresult(); // 需要利用该 hash 去查询交易回执 异步 invokecontractaysnc(transaction transaction,final AsyncHandler callback) throws Exception /** * 调用智能合约 transaction 智能合约交易 callback 回调函数, 实现接口 AsyncHandler */ // 需要实现 AsyncHandler 接口 public class AsyncHandlerTest implements AsyncHandler{ public String result = public void onsuccess(stdreturn ret) { result = ret.getresult(); System.out.println(result); JSONObject jsonobject = JSONObject.fromObject(handler.result); 2017 趣链科技版权所有第 56 页

64 @Override public void onfailed(stdreturn ret) { result = "failed"; Transaction transaction = new Transaction(yourfrom,bin,false); AsyncHandlerTest handler = new AsyncHandlerTest(); hyperchain.invokecontractaysnc(transaction,handler); 合约管理 SingleValueReturn maintaincontract(transaction transaction) throws InterruptedException /** * 智能合约管理 * transaction 智能合约交易 返回单个 string 返回值 */ //upgrade contract, opcode 1 升级合约 Transaction transaction = new Transaction(yourfrom, contractaddress, UpgradeBin, 1); transaction.signwithsm2(account_json,passwd); StdReturn invokeresult = hyperchain.maintaincontract(transaction); System.out.println(invokeResult.getResult()); // 取得交易 hash // 利用交易 hash 取得回执, 如果交易回执执行能够取得, 则升级成功 //upgrade contract, opcode 2 冻结合约 Transaction transaction = new Transaction(yourfrom, contractaddress,2); transaction.signwithsm2(account_json,passwd); SinglevalueReturn invokeresult = hyperchain.maintaincontract(transaction); System.out.println(invokeResult.getResult());// 冻结交易 hash 如果冻结成功则能够查询到回执 //upgrade contract, opcode 3 解冻合约 Transaction unfreezetransaction = new Transaction(account.getAddress(), contractaddress, 3); unfreezetransaction.signwithsm2(account_json,passwd); SinglevalueReturn unfreezeinvokeresult = hyperchain.maintaincontract(unfreezetransaction); System.out.println(unfreezeInvokeResult.getResult());// 取得解冻 hash, 如果成功则能查询到回执 8.4 Block 相关接口 取得最新区块信息 BlockReturn getlatestblock() 2017 趣链科技版权所有第 57 页

65 /** * 取得最新的区块信息 区块信息 */ BlockReturn blockreturn = hyperchain.getlatestblock(); System.out.println(blockReturn.getResult());// 返回的是一个 json 字符串 取得指定区块列表 ArrayList<BlockReturn> getblocks(biginteger from, BigInteger to) /** * 取得指定开始与结束的区块 from 开始区块号 to 结束区块号 返回区块信息 */ ArrayList<BlockReturn> blockreturns = hyperchain.getblocks( new BigInteger( "13"),new BigInteger( "14")); 取得指定区块 by hash BlockReturn getblkbyhash(string blockhash) /** * 查询区块信息 by blk Hash * block_getblocksbyhash blockhash blk hash 区块信息 */ BlockReturn blockreturn = hyperchain. getblkbyhash ( "0xec86d97fb08dd10c4a238c7ba2993ee62d3f33df70b7b a8f36da08ab" ); 取得指定区块 by number BlockReturn getblkbynumber(biginteger blknumber) /** * 查询区块信息 by blk Number blknumber 区块 Number 区块信息 */ BlockReturn blockreturn = hyperchain.getblkbynumber( new BigInteger("1e",16)); System.out.println(blockReturn.getResult()); System.out.println(blockReturn.getAvgTime().toString()); 2017 趣链科技版权所有第 58 页

66 System.out.println(blockReturn.getMerkleRoot()); 8.5 节点相关接口 取得节点信息 ArrayList<NodeInfoReturn> getnodes() /** * 取得所有的节点信息 返回节点信息列表 */ ArrayList<NodeInfoReturn> nodeinforeturns= hyperchain.getnodes(); for (NodeInfoReturn nodeinforeturn : nodeinforeturns){ System.out.println(nodeInfoReturn.getIp()); System.out.println(nodeInfoReturn.getId()); System.out.println(nodeInfoReturn.getPrimary()); System.out.println(nodeInfoReturn.getDelay()); 获取当前节点的哈希值 String getnodehash() /** * 获取当前节点哈希值 返回节点信息 */ String nodehash = hyperchain.getnodeshash(); 根据哈希值删除节点说明 : 删除节点需要在所有的节点上调用该接口, 参数 nodehash 为需要删除的节点的 hash boolean deletenode(string nodehash) /** * 根据节点哈希值删除节点 nodehash 节点哈希值 删除操作结果 */ String nodehash = hyperchain.getnodeshash(); boolean issuccess = hyperchain.deletenode(nodehash); 2017 趣链科技版权所有第 59 页

67 8.5.4 NVP 根据 ID 值断开与 VP 节点的连接说明 : 如果同所有 VP 节点断开连接, 则该 NVP 节点会自动关闭, 该 API 请求应当发往 NVP 节点 boolean disconnectvp(string vpnodehash) /** * 根据节点 id 值同 VP 节点断开连接 nodeid 节点 id 值 删除操作结果 */ boolean issuccess = hyperchain.disconnectvp(nodehash); 8.6 返回值解析 通用返回值解析 ( 推荐 ) String resultdecode(string methodname,string abi, String encoded ) throws UnsupportedEncodingException 本方法将会利用 abi 将返回值直接解析为 json 字符串, 拥有 value( 返回值 ), mayvalue( 推测返回值 ) 字段, 更加便捷 ReceiptReturn result4 = // 取得交易回执 hyperchain.gettransactionreceipt(result3.getresult()); System.out.println(result4.getResult()); System.out.println(FunctionDecode.resultDecode("add",TEST_ABI,result4.getRet())); // 样例输出 //{"result":[{"type":"java.lang.boolean","value":"true","mayvalue":"true"],"status":"succes S","txhash":"0x533a013a82c831fb7986d240bfca3b c0658f12a e9f77f4c4","c ode":0,"info":"invoke Success!" 复杂返回值解析 ( 不推荐 ) ArrayList<Object> complexdecode(string methodname, String abi, String data) String ret = "0x "; 2017 趣链科技版权所有第 60 页

68 String abi = "[{\"constant\":false,\"inputs\":[{\"name\":\"a\",\"type\":\"uint256\"],\"name\":\"multiply\",\"ou tputs\":[{\"name\":\"d\",\"type \":\"uint256\"],\"payable\":false,\"type\":\"function\"]" ; FunctionDecode.complexDecode( "multiply", abi, ret); 8.7 账户相关接口 主要是提供了明文私钥相关接口, 所有涵盖 accountjson 相关的接口都有相 应的明文私钥重载实现 创建账户 ( 加密 ) String newaccount(string passphrase) throws GeneralSecurityException /** * 生成账户 keystore 文件, json 字符串形式返回 * passphrase 设置账户密码 json 格式私钥存储文件 GeneralSecurityException */ String account = hyperchain.newaccount( "123"); System.out.println(account); 创建账户 ( 未加密 ) String newaccountraw() throws GeneralSecurityException /** * 生成私钥存储 ( 未加密 ) 文件,json 字符串返回 json 格式私钥存储 ( 未加密 ) 文件 GeneralSecurityException 加密算法异常 */ String account = hyperchain.newaccountraw(); System.out.println(account); 创建账户 ( 返回值为 ECPriv) ECPriv newaccount() throws GeneralSecurityException 2017 趣链科技版权所有第 61 页

69 /** * 返回 ECPriv 类包括 ECKey ECPriv 包括用户私钥以及账户地址 GeneralSecurityException 加密算法异常 */ ECPriv ecpriv = new newaccount(); 加密明文私钥 String encryptaccount(string plainaccountjson, String password) throws GeneralSecurityException 加密明文私钥并返回一个 AccountJson 解密私钥文件返回明文 Json 字符串 StringdecryptAccount(String encrypetedaccountjson, String pwd) throws Exception 解密私钥文件, 并返回明文私钥文件 2017 趣链科技版权所有第 62 页

70 第 9 章异常处理 9.1 网络异常 单节点网络异常 当系统中出现如下报错, 即 IP 为 ,Port 为 8002 的节点连接失败, 表明本节点与该节点之间的网络连接断裂, 有较大概率是该节点发生了异常导致宕机 处理方式 : 重启该节点 注意 : 出现该情况有可能是该节点未开放相应端口, 请务必确认四个节点之间通讯顺利, 防止因为防火墙等问题导致节点间不能通讯 9.2 数据异常 重新启动报错 invalid root 该节点的账本数据已损坏 处理方式 : 1) 删除该节点的数据 (build 文件夹 ), 重新启动, 通过区块同步恢复 2) 删除该节点的数据 (build 文件夹 ), 将正常节点的数据拷贝至本节点 (build 文件夹拷贝 ), 重新启动 当数据规模不大时, 推荐采用第一种处理方式 当数据规模较大时, 推荐采用第二种处理方式 9.3 共识异常 重启后相同区块高度的节点数不超过规定数目 所有节点重新启动后, 拥有相同区块高度的节点数不超过算法规定的数值 2017 趣链科技版权所有第 63 页

71 当 N 为 4,F 为 1 时, 该值为 3 int(math.ceil(float64(s.config.n+s.config.f+1) / float64(2))) 出现这种情况, 即区块链网络中拜占庭节点的数量已经超过了算法容错的数目 处理方式 : 以区块高度最高的节点数据为准, 将该节点的数据 (build 文件夹 ) 拷贝给其他节点, 数据拷贝完成之后重启区块链网络 Viewchange 异常报错信息 : Replica 1 already has a view change message for view 3 from replica 2 当在所有节点上看到这条消息, 且消息都是来自相同的节点例如 2 时, 说明节点 2 发生了异常情况触发了 ViewChange, 无需理会节点 2 的错误行为, 当节点 2 发送 10 次 ViewChange 都不成功时会自动触发 recovery, 最终达成一致 处理方式 : 自动恢复当在所有节点都看到类似消息而且不断出现时处理方式 : 重启所有节点 Ignore duplicatoe 异常报错信息 : Replica 2 ignoring prepare for view=2/seqno=10: not in-wv, in view 1, low water mark 20 如果偶尔出现以上信息, 是正常情况, 可能是某一个节点的 cpu 负荷过高或网络通讯不畅造成该节点处理速度落后于区块链网络的处理速度 该条消息对于其他节点来说已经失效了 如果一直出现, 可能是一个节点 out-of-date 落后了, 可以等节点自动发现后恢复 ( 需要等待一段时间, 落后 50 个块会触发恢复 ), 也可以将落后的节点重启 处理方式 : 自动恢复 2017 趣链科技版权所有第 64 页

72 第 10 章产品激活 续期 10.1 激活 使用 Hyperchain 需要拥有本产品的激活码 本产品的激活码为名为 LICENSE 的文件 激活本产品只需将 LICENSE 文件放置在产品根目录下的 config 文件夹下即可 10.2 续期 当您购买的 Hyperchain 产品即将到期时, 您可以重新向本公司购买新的激活码, 在不停止 hyperchain 服务的情况下动态替换旧 LICENSE 文件即可 2017 趣链科技版权所有第 65 页

73 第 11 章联系与反馈 11.1 联系方式 您可以通过以下联系方式联系我们 : 联系电话 : , support@hyperchain.cn 我们的工作时间是 :9:00 AM to 5:00 PM PST (Monday-Friday, except Holidays) 11.2 注意事项 请您在联系我们之前, 将以下信息附上 : 您的姓名, 问题的主要内容, 您的公司, 电话以及电子邮箱操作系统以及版本号产品版本号问题描述 2017 趣链科技版权所有第 66 页

74 第 12 章附录 12.1 配置文件 caconfig.toml 文件描述 :CA 权限控制相关配置文件, 根据实际情况填写配置 字段 [ecert].ca [ecert].cert [ecert].priv [rcert].ca [rcert].cert [rcert].priv [tlscert].ca [tlscert].cert [tlscert].priv [tlscert].serverhostoverride [check].certsign [check]. tcert [check]. ercert [gm].sm4 含义 Enrollment Certiticate Authority, 准入认证机构证书 Enrollment Certcate, 准入证书, 用于控制 VP 和 NVP 节点进入 Hyperchain 中 准入证书的私钥 Role Certiticate Authority, 角色认证机构证书 Role Certcate, 角色证书, 用于区分 VP 和 NVP 节点, 持有 RCert 的节点才能被承认为 VP 节点 角色证书的私钥 tls 认证机构证书 tls 证书, 用于 grpc 连接 tls 证书的私钥 签发 tls 证书的组织 用于在连接过程中, 是否开启 ecert 和 rcert 的签名验证, 建议设置为 true 用于在请求过程中, 是否开启 tcert 验证, 建议设置为 true 用于在连接过程中, 是否开启 ecert 和 rcert 的验证, 建议设置为 true 用于对称加密的算法是否选用 sm4;false 为 AES 算法 ;true 为 sm4 ; 建议选择 false db.yaml 文件描述 : 数据库相关配置文件, 后两项建议修改 字段 dbconfig.dbtype dbconfig.sldb.dbpath 含义用于指定使用哪一个数据库 LEVEL_DB 为 0001,SUPER_LEVEL_DB 为 0010, 一般推荐使用 0001 SUPER_LEVEL_DB 的数据存储路径 2017 趣链科技版权所有第 67 页

75 dbconfig.sldb.index.dir dbconfig.sldb.index.bloombit dbconfig.sldb.index.hashnum dbconfig.sldb.index.dumpinterval dbconfig.leveldbpath SUPER_LEVEL_DB 的索引存储路径 SUPER_LEVEL_DB 的布隆过滤器的位数 SUPER_LEVEL_DB 的布隆过滤器所使用的哈希函数个数 SUPER_LEVEL_DB 的索引持久化间隔时间, 根据需求配置 leveldb 的数据存储路径, 根据需求配置 genesis.json 文件描述 : 本文件包含了启动 hyperchain 区块链的创世块的信息, 里面的信息包括创世账户地址和账户余额, 您可以随意修改里面的地址和值信息, 但是要求地址长度为 40 个 16 进制字符长度 账户余额为 10 进制值 注意!!! 务必保证所有节点的本文件的一致性 字段 genesis.alloc 含义用于新建创世区块, 其中 key 为用户帐号地址, 要求地址长度为 20 个 16 进制字符长度,value 为用户所拥有的余额, 要求为 10 进制值 global.yaml 文件描述 : 节点的整体配置选项, 一般全部保值默认值 字段 含义 global.account.keystoredir 加密私钥存储路径 global.account.keynodesdir 临时解密密钥存储路径 global.dbconfig 数据库的配置文件路径 global.structure.state 账本类型, 包括 rawstate 和 hyperstate global.version.blockversion 区块的版本号 global.version.transactionversion 交易的版本号 global.configs.caconfig 证书的配置文件路径 global.configs.peers 节点的配置文件路径 global.configs.genesis 创世区块的配置文件路径 global.configs.static_peers StateUpdate 相关配置文件路径 global.configs.pbft 共识算法的配置文件路径 global.configs.license Hyperchain 对客户的授权文件路径 global.configs.replicainfo.interval 节点间状态同步间隔 global.configs.replicainfo.enable 节点相互开启状态同步 global.configs.ratelimit.enable 流量控制是否开启, 一般开启 2017 趣链科技版权所有第 68 页

76 global.configs.ratelimit.txratepeak 普通交易流量控制 global.configs.ratelimit.txfillrate 普通交易流量阈值恢复间隔 global.configs.ratelimit.contractratepeak 合约交易流量控制 global.configs.ratelimit.contractfillrate 合约交易流量阈值恢复间隔 global.configs.buckettree.global.globaldata 用于 buckettree, 一般默认值 NodeCacheSize global.configs.buckettree.global.globaldata 用于 buckettree, 一般默认值 NodeCacheLength global.configs.buckettree.state.size 用于 buckettree, 一般默认值 global.configs.buckettree.state.levelgroup 用于 buckettree, 一般默认值 global.configs.buckettree.state.cachesize 用于 buckettree, 一般默认值 global.configs.buckettree.state.datanode 用于 buckettree, 一般默认值 CacheSize global.configs.buckettree.storage.size 用于 buckettree, 一般默认值 global.configs.buckettree.storage.levelgroup 用于 buckettree, 一般默认值 global.configs.buckettree.storage.cachesize 用于 buckettree, 一般默认值 global.configs.buckettree.storage.datanode 用于 buckettree, 一般默认值 CacheSize global.configs.hmpublickey."n" 用于同态加密, 一般默认值 global.configs.hmpublickey.nsquare 用于同态加密, 一般默认值 global.configs.hmpublickey.g 用于同态加密, 一般默认值 global.configs.sync_chain.batch 节点恢复数据时一次请求最大的块数 global.configs.sync_chain.interval 节点恢复数据时重复请求的时间间隔 global.configs.sync_chain.exitflag 当发生本地账本与收到的区块不一致情况 时,NVP 节点是否宕机 global.security.enabletls 是否使用 tls, 一般默认值 global.security.enablesymmetrical 是否使用对称加密, 一般默认值 global.connection.retrytimelimit 测试连接是否可用最大次数 global.connection.retrytimeout 单次测试连接是否可用最长时间 global.connection.recoverytimelimit 尝试重新连接最大次数 global.connection.recoverytimeout 单次尝试重新连接最长时间 global.connection.keepalivetimelimit 保活消息发送最大次数 global.connection.keepaliveinterval 保活消息发送间隔 global.logs.dumpfile 是否输出日志文件 global.logs.newlogfileinterval 产生新的日志文件的时间间隔 global.logs.logsdir 输出日志文件路径 global.logs.loglevel 全局的日志级别, 可被 module 下的模块设 置覆盖 global.logs.file_format 日志输出到文件的格式 global.logs.console_format 日志输出到控制台的格式 global.logs.module.p2p p2p 模块的日志级别 字段 含义 global.account.keystoredir 加密私钥存储路径 2017 趣链科技版权所有第 69 页

77 global.account.keynodesdir 临时解密密钥存储路径 global.dbconfig 数据库的配置文件路径 global.structure.state 账本类型, 包括 rawstate 和 hyperstate global.version.blockversion 区块的版本号 global.version.transactionversion 交易的版本号 global.configs.caconfig 证书的配置文件路径 global.configs.peers 节点的配置文件路径 global.configs.genesis 创世区块的配置文件路径 global.configs.static_peers StateUpdate 相关配置文件路径 global.configs.pbft 共识算法的配置文件路径 global.configs.license Hyperchain 对客户的授权文件路径 global.configs.replicainfo.interval 节点间状态同步间隔 global.configs.replicainfo.enable 节点相互开启状态同步 global.configs.ratelimit.enable 流量控制是否开启, 一般开启 global.configs.ratelimit.txratepeak 普通交易流量控制 global.configs.ratelimit.txfillrate 普通交易流量阈值恢复间隔 global.configs.ratelimit.contractratepeak 合约交易流量控制 global.configs.ratelimit.contractfillrate 合约交易流量阈值恢复间隔 global.configs.buckettree.global.globaldata 用于 buckettree, 一般默认值 NodeCacheSize global.configs.buckettree.global.globaldata 用于 buckettree, 一般默认值 NodeCacheLength global.configs.buckettree.state.size 用于 buckettree, 一般默认值 global.configs.buckettree.state.levelgroup 用于 buckettree, 一般默认值 global.configs.buckettree.state.cachesize 用于 buckettree, 一般默认值 global.configs.buckettree.state.datanode 用于 buckettree, 一般默认值 CacheSize global.configs.buckettree.storage.size 用于 buckettree, 一般默认值 global.configs.buckettree.storage.levelgroup 用于 buckettree, 一般默认值 global.configs.buckettree.storage.cachesize 用于 buckettree, 一般默认值 global.configs.buckettree.storage.datanode 用于 buckettree, 一般默认值 CacheSize global.configs.hmpublickey."n" 用于同态加密, 一般默认值 global.configs.hmpublickey.nsquare 用于同态加密, 一般默认值 global.configs.hmpublickey.g 用于同态加密, 一般默认值 global.configs.sync_chain.batch 节点恢复数据时一次请求最大的块数 global.configs.sync_chain.interval 节点恢复数据时重复请求的时间间隔 global.configs.sync_chain.exitflag 当发生本地账本与收到的区块不一致情况 时,NVP 节点是否宕机 global.security.enabletls 是否使用 tls, 一般默认值 global.security.enablesymmetrical 是否使用对称加密, 一般默认值 global.connection.retrytimelimit 测试连接是否可用最大次数 global.connection.retrytimeout 单次测试连接是否可用最长时间 2017 趣链科技版权所有第 70 页

78 global.connection.recoverytimelimit global.connection.recoverytimeout global.connection.keepalivetimelimit global.connection.keepaliveinterval global.logs.dumpfile global.logs.newlogfileinterval global.logs.max_log_size global.logs.split_start_stop_log global.logs.logsdir global.logs.loglevel global.logs.file_format global.logs.console_format global.logs.module.p2p 尝试重新连接最大次数 单次尝试重新连接最长时间 保活消息发送最大次数 保活消息发送间隔 是否输出日志文件 产生新的日志文件的时间间隔 配置日志文件的大小上限选择是否对平台启动及平台运行的日志进行区分生成输出日志文件路径 全局的日志级别, 可被 module 下的模块设置覆盖 日志输出到文件的格式 日志输出到控制台的格式 p2p 模块的日志级别 pbft.yaml 文件描述 :pbft 算法相关配置, 一般全部保值默认值 字段 pbft.nodes pbft.batchsize pbft.vcresendlimit timeout.negoview timeout.recovery timeout.firstrequest timeout.batch timeout.request timeout.validate timeout.nullrequest timeout.viewchange timeout.resendviewchange timeout.cleanviewchange timeout.update 含义节点个数 在 pre-prepare 前, 可以被主节点打包成一个区块的最大交易数量 在节点进行 recovery 前, 进行同一个 view change 的最大次数 在发送协商请求后, 等待 N-f 个响应的最长时间 等待 recovery 过程结束的最长等待时间 节点启动后的最长准备时间 主节点发送 pre-prapare 请求的时间间隔, 即使区块所拥有的交易数量未达到 pbft.batchsize 大小 节点接收 执行区块的最长时间, 其值必须大于 timeout.batch 节点进行 validate 最长的时间 主节点发送给其它节点的心跳消息 进行 viewchange 的最长时间 重新发送 view change 的间隔 view change 消息的过期时间并清除 增删节点时, 更新共识参数的最长时间 2017 趣链科技版权所有第 71 页

79 peerconfig.json 文件描述 : 节点网络配置, 全部按照实际情况填写 字段 含义 self.is_reconnect 用于标识本节点是否启动过 self.is_origin 本节点是否是创世节点 self.is_vp 本节点是否是 VP 节点 self.node_id 本节点的 id self.grpc_port 本节点使用的 grpc 端口 self.local_ip 本节点的本地 ip 地址 self.jsonrpc_port 本节点使用的 jsonrpc 端口 self.restful_port 本节点使用的 restful 端口 self.domain 本节点所在的域名 self.address 本节点在不同域中用于连接的 ip 地址 self.introducer_ip 用于新增节点时充当介绍人的节点 ip 地址 self.introducer_port 用于新增节点时充当介绍人的节点通讯端 口 self.introducer_id 用于新增节点时充当介绍人的节点 id maxpeernode 本节点所连接的节点数量 nodes.id 本节点连接的其它节点 id nodes.domain 本节点连接的其他节点所在域 nodes.address 本节点连接的其它节点在各域的 ip 地址 nodes.port 本节点连接的其它节点通讯端口 nodes.rpc_port 本节点连接的其它节点 rpc 端口 static_peer.json 文件描述 : 静态节点配置, 发生区块同步时, 优先向配置的静态节点发起区块请求 该配置文件可以不存在, 也可以为空, 视为没有静态节点 字段 含义 port 区块同步时优先请求的节点通讯端口 local_address 区块同步时优先请求的节点内网 ip id 区块同步时优先请求的节点 id remote_address 区块同步时优先请求的节点外网 ip 2017 趣链科技版权所有第 72 页

80 12.2 常见部署需求 peerconfig 配置示例 单机部署四个节点 示意图如下, 具体四节点的配置可参考 peerconfig-examples/local-4-nodes 的具体配置 同一网域内的四台服务器各部署一个节点 示意图如下, 具体四节点的配置可参考 peerconfig-examples/ 4-nodes-in-1- domain 的具体配置 2017 趣链科技版权所有第 73 页

81 两个网域内的四台服务器各部署一个节点局域网内内网连接, 否则外网连接 示意图如下, 具体四节点的配置可参考 peerconfig-examples/ 4-nodes-in-1- domain 的具体配置 2017 趣链科技版权所有第 74 页