3.1 XuperUnion的编译

3.1.1 准备环境

  • 安装go语言编译环境，版本为1.12以上
  • 安装git
    • 下载地址：@git
  • 安装g++
    • 版本要求g++4.8.2以上

3.1.2 编译步骤

  • 使用git下载源码到本地
    • git clone xchain地址
  • 执行命令
    1. cd github.com/xuperchain/xuperunion
    2. make
    • 得到产出xchain和xchain-cli

3.2 单节点网络

3.2.1 启动单节点模拟的测试网络

3.2.1.1 获取编译产出

在当前目录下：主要获取目录为data, logs, conf, plugins, 二进制文件为xchain，xchain-cli，wasm2c

3.2.1.2 建立目录

目录名 功能 备注
node/ 根节点目录
——-/conf xchain.yaml:xchain服务的配置信息,plugins.conf: 插件的配置信息 防止冲突，部署时根据需要修改端口号
——-/data 数据的存放目录,创世块信息，以及共识和合约的样例
——-/——-/blockchain 账本目录
——-/——-/keys 此节点的地址，唯一性
——-/——-/netkeys 此节点的网络标识ID，唯一性
——-/——-/config 创始的共识采用tdpos模式，指定单一地址有权利出块
——-/logs 程序日志目录
——-/plugins so的存放目录
——-/xchain 服务的二进制文件
——-/xchain-cli 客户端工具
——-/wasm2c wasm工具

3.2.1.3 创建链

  1. # 创建xuper链
  2. ./xchain-cli createChain

3.2.1.3 启动服务

  1. # 启动服务节点
  2. nohup ./xchain &

3.2.2 观察区块

  1. # check服务运行状况
  2. ./xchain-cli status -H 127.0.0.1:37101

3.2.3 测试基本功能

3.2.3.1 创建新账户

  1. # 创建普通用户, 包含地址，公钥，私钥
  2. ./xchain-cli account newkeys --output data/accounts/bob
  3. # 在bob目录下会看到文件address，publickey，privatekey生成
  5. # 创建合约账户
  6. ## 通用方式
  7. ./xchain-cli account new --desc account.des
  8. 其中，account.des内容如下
  9. {
  10.     "module_name": "xkernel",
  11.     "method_name": "NewAccount",
  12.     "args" : {
  13.         "account_name": "1111111111111111",  //说明：16位数字组成的字符串
  14.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"AK1\": 0.3,\"AK2\": 0.3}}"
  15.     }
  16. }
  17. ## 简易方式
  18. ./xchain-cli account new --account 1111111111111111  // 说明：16位数字组成的字符串

3.2.3.2 查余额

  1. ./xchain-cli account balance --keys data/accounts/bob -H 127.0.0.1:37101

3.2.3.3 转账

  1. # --keys 从此地址 转给 --to地址 --amount 钱
  2. ./xchain-cli transfer --to czojZcZ6cHSiDVJ4jFoZMB1PjKnfUiuFQ --amount 10 --keys data/keys/ -H 127.0.0.1:37101

3.2.3.4 查询交易信息

  1. # 查询上一步生成的txid的交易信息
  2. ./xchain-cli tx query cbbda2606837c950160e99480049e2aec3e60689a280b68a2d253fdd8a6ce931 -H 127.0.0.1:37101

3.2.3.5 查询block信息

  1. # 可查询上一步交易所在的block id信息
  2. ./xchain-cli block 0354240c8335e10d8b48d76c0584e29ab604cfdb7b421d973f01a2a49bb67fee -H 127.0.0.1:37101

3.2.3.6 发起多重签名交易

  1. # generate raw tx
  2. ### data/acl/addrs维护好涉及到操作权限的所有的address信息，默认从此地址文件读取，可用参数指定自己文件。此操作会默认产生一个tx.out文件，供后续命令使用。这里所有地址为需要多方的所有参与者的地址以及一些需要授权的地址
  3. addrs文件中，格式为每行一个address，例如
  4. YDYBchKWXpG7HSkHy4YoyzTJnd3hTFBgG
  5. ZAmWoJViiNn5pKz32m2MVgmPnSpgLia7z
  6. ## 某个address发起
  7. ./xchain-cli multisig gen --to YDYBchKWXpG7HSkHy4YoyzTJnd3hTFBgG --amount 100 --desc contract.desc -H 127.0.0.1:37101
  8. ## 从账户发起
  9. ./xchain-cli multisig gen --to YDYBchKWXpG7HSkHy4YoyzTJnd3hTFBgG --amount 100 --desc contract.desc -H 127.0.0.1:37101 --from XC11111111111111@xuper
  10. # 各方在签名之前可以check 原始交易是否ok，查看visual.out
  11. ./xchain-cli multisig check --input tx.out --output visual.out
  12. # 各方签名生成签名文件
  13. ./xchain-cli multisig sign --keys data/account/bob --output bob.sign
  14. # 组装成带有签名的完整tx，并更新账本，同时发送到周边节点 eg. 第一个参数是发起者的签名文件，第二个参数是需要所有方的签名文件，均为逗号分割
  15. ./xchain-cli multisig send --tx tx.out a.sign,b.sign c.sign,d.sign

3.2.4 常见问题

  • tdpos默认共识，xuper.json文件如下：
    1. {
    2.   "version" : "1"
    3.   , "predistribution":[
    4.       {
    5.           "address" : "dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN"
    6.           , "quota" : "100000000000000000000"
    7.       }
    8.   ]
    9.   , "maxblocksize" : "128"
    10.   , "award" : "1000000"
    11.   , "decimals" : "8"
    12.   , "award_decay": {
    13.       "height_gap": 31536000,
    14.       "ratio": 1
    15.   }, "genesis_consensus":{
    16.   "name": "tdpos",
    17.   "config": {
    18.       "timestamp": "1556444792000000000",
    19.       "proposer_num":"1",
    20.           "period":"3000",
    21.               "alternate_interval":"3000",
    22.               "term_interval":"6000",
    23.           "block_num":"20",
    24.           "vote_unit_price":"1",
    25.           "init_proposer": {
    26.           "1":["dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN"]
    27.           }
    28.       }
    29.   }
    30. }
    详情内容介绍请见3.5.2
  • single共识介绍
  1. {
  2.     "version" : "1"
  3.     , "predistribution":[
  4.         {
  5.             "address" : "dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN"       // 创世块生产者地址
  6.             , "quota" : "100000000000000000000"                   // 初始货币量
  7.         }
  8.     ]
  9.     , "maxblocksize" : "128"
  10.     , "award" : "428100000000"  // 挖块奖励
  11.     , "decimals" : "8"
  12.     , "award_decay": {      // 挖块奖励衰减
  13.         "height_gap": 31536000,
  14.         "ratio": 1
  15.     },"genesis_consensus":{
  16.         "name": "single",    // 共识机制
  17.         "config": {
  18.                         "miner":"dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN",  // 矿工地址
  19.                         "period": "3000"     // 块生产间隔
  20.                 }
  21.         }
  22. }

3.3 账号与权限管理

3.3.1 创建合约账号

3.3.1.1 快速创建一个合约账号

./xchain-cli account new —account 1111111111111111

3.3.1.2 按照json文件创建一个合约账号

./xchain-cli account new —desc account.jsonaccount.json模版如下:

  1. {
  2.     "module_name": "xkernel",
  3.     "method_name": "NewAccount",
  4.     "args" : {
  5.         "account_name": "1111111111111111",
  6.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"AK1\": 0.5,\"AK2\": 0.5}}"
  7.     }
  8. }

3.3.2 管理合约账号/合约方法ACL

3.3.2.1 重新设置一个账号/合约方法的ACL

走multisig命令

step1:准备好ACL的json文件，该json文件中有新的ACL配置，文件名记为acl_new.json

step2:针对acl_new.json生成原始交易

先查看合约账号余额是否充足： ./xchain-cli account balance XC1111111111111111@xuper

如果不足，可以把当前个人账户（data/keys/address)的资产转移一些给合约账户

  1. ./xchain-cli multisig gen --desc acl_new.json --from XC1111111111111111@xuper

step3:使用旧有的acl权限模型对新生成的原始交易做签名(假设旧有的权限模型的成员包括bob和alice)

  1. ./xchain-cli multisig sign --keys data/account/bob --output bob.sign
  2. ./xchain-cli multisig sign --keys data/account/alice --output alice.sign

step4:将签名后的交易post出去

  1. ./xchain-cli multisig send --tx tx.out bob.sign,alice.sign bob.sign,alice.sign

3.3.2.2 查询一个账号的Acl

./xchain-cli acl query —account XC1111111111111111@xuper

3.3.2.3 查询一个合约方法的Acl

./xchain-cli acl query —contract contractName —method methodName

3.3.3 常见问题

3.3.3.1 创建合约账户，重置合约账户／合约方法的ACL时，配置文件的案例：

  1. a.创建合约账号,配置文件案例如下：
  2. {
  3.     "module_name": "xkernel",
  4.     "method_name": "NewAccount",
  5.     "args" : {
  6.         "account_name": "1111111111111111",
  7.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"AK1\": 0.5,\"AK2\": 0.5}}"
  8.     }
  9. }
  10. b.重置合约账户的ACL,配置文件案例如下：
  11. {
  12.     "module_name": "xkernel",
  13.     "method_name": "SetAccountAcl",
  14.     "args" : {
  15.         "account_name": "XC1111111111111111@xuper",
  16.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"AK1\": 0.5,\"AK2\": 0.5}}"
  17.     }
  18. }
  19. c.重置合约方法的ACL,配置文件案例如下：
  20. {
  21.     "module_name": "xkernel",
  22.     "method_name": "SetMethodAcl",
  23.     "args" : {
  24.         "contract_name": "math",
  25.         "method_name": "transfer",
  26.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 0.6},\"aksWeight\": {\"AK1\": 0.5,\"AK2\": 0.5}}"
  27.     }
  28. }

3.4 智能合约开发

3.4.1 编写合约

参考源码样例contractsdk/cpp/example/counter.cc contractsdk/go/example/counter/counter.go主要实现一个struct的任意方法，来实现自己的逻辑

3.4.2 wasm合约

3.4.2.1 部署合约

3.4.2.1.1 编译

注意合约编译环境与源码编译环境一致

  1. #c++语言的智能合约
  2. # 依赖docker环境
  3. cd contractsdk/cpp
  4. sh build.sh

到当前目录build里，将编译好的合约二进制counter.wasm，重新命名为counter，放到某个目录node/data/下，这是随意的。

涉及到合约操作会消耗资源，需要通过--fee参数指定为该transaction付出的资源量，在一开始不确定需要花费多少资源时，可以先不加参数—fee, 预执行会提示需要消耗的资源数值，第二次再指定>=要消耗的资源数值的数量即可。

3.4.2.1.2 部署

合约在使用前，所使用的账号一定要提前储备资金

  1. # 便捷方式
  2. ## 账户下权限AK是自己，提前创建好账号，并保证账号下有足够资源余额
  3. 查看合约账号资源余额是否充足：  ./xchain-cli account balance  XC1111111111111111@xuper 
  4. 如果不足，可以把当前个人账户（data/keys/address)的资产转移一些给合约账户：
  5. ./xchain-cli transfer --to XC1111111111111111@xuper --amount 100000 
  7. # c语言合约
  8. ./xchain-cli wasm deploy --account XC1111111111111111@xuper --cname counter -H localhost:37101 data/counter -a '{"creator":"xchain"}'
  9. # 多重签名场景
  10. ## 提前维护好data/acl/addrs 需要的合作的地址
  11. # c语言合约
  12. ./xchain-cli wasm deploy --account XC1111111111111111@xuper --cname counter -H localhost:37101 -m data/counter -a '{"creator":"xchain"}'
  13. ## 后续参看3.2.3.6多重签名交易的后续check，sign，send场景

3.4.2.2 调用合约

  1. # --method 是指合约样例里方法
  2. # c++合约
  3. ./xchain-cli wasm query -a '{"key":"counter"}' --method get -H localhost:37101 counter
  4. # 便捷方式
  5. # c++合约
  6. ./xchain-cli wasm invoke -a '{"key":"counter"}' --method increase -H localhost:37101 counter
  7. # 多重签名场景
  8. # 参考部署多重签名场景
  9. ./xchain-cli wasm invoke -a '{"key":"counter"}' --method increase -H localhost:37101 counter -m
  1. ### go语言部分
  2. # 编译
  3. #go语言的智能合约，在当前写的智能合约目录下
  4. GOOS=js GOARCH=wasm go build
  5. # 便捷方式
  6. ./xchain-cli wasm deploy --account XC1111111111111111@xuper --cname counter -H localhost:37101 -a '{"creator":"xchain"}' data/counter --runtime go
  7. # 多重签名
  8. ./xchain-cli wasm deploy --account XC1111111111111111@xuper --cname counter -H localhost:37801 -m -a '{"creator":"xchain"}' data/counter
  9. ./xchain-cli wasm query -a '{"key":"counter"}' --method get -H localhost:37101 counter
  10. ./xchain-cli wasm invoke -a '{"key":"counter"}' --method increase -H localhost:37101 counter

3.4.3 访问权限管理

合约方法的ACL控制参看3.3.3设置合约方法权限样例

3.5 多节点网络搭建

在阅读本节前，请先阅读3.2节“单节点网络”。3.2 节中介绍了创建单节点网络的创建，在该基础上，搭建一个SINGLE共识的多节点网络，其他节点只要新增p2p网络 bootNodes 配置即可。如果你想搭建一个TDPoS共识的链，仅需要修改创世块参数中 “genesis_consensus” 配置参数即可。下面将详细介绍相关操作步骤。

3.5.1 p2p网络配置

  1. 假设搭建3个节点的网络，在单节点的基础上再新增两个节点node2和node3；

  2. 创建node2和node3的部署路径，并按照3.2.1.2 建立每个节点自己的部署目录；

    1. 注意：由于每个节点在网络中有自己唯一的身份，所以node2 和node3 需要重置自己的身份信息，
    2. 主要包括2个步骤:
    4. 1 创建节点私钥
    5.  ./xchain-cli account newkeys -f
    6. 2 创建节点netUrl
    7.  ./xchain-cli netURL gen

  3. 查询node节点的netUrl，会得到节点netUrl

    1. ./xchain-cli netUrl get -H 127.0.0.1:37101
  4. 在node2和node3的p2pv2配置中的bootNodes增加node的netUrl，如下所示：
    1. p2pV2:
    2.   // port是节点p2p网络监听的端口，如果在一台机器上部署注意端口配置不要冲突，node配置的是47101，node2和node3可以分别设置为47102和47103
    3.   port: 47102
    4.   // 节点加入网络所连接的种子节点的链接信息，
    5.   bootNodes:
    6.     - "/ip4/127.0.0.1/tcp/47101/p2p/QmVxeNubpg1ZQjQT8W5yZC9fD7ZB1ViArwvyGUB53sqf8e"
  5. 设置node2和node3节点RPC服务暴露的端口
    1. // port是节点启动时RPC服务监听的端口，如果在一台机器上部署注意端口配置不要冲突，node配置的是 :37101，node2和node3可以分别设置为 :37102和 :37103
    2. tcpServer:
    3.   port: :37102
  6. 启动node2和node3，check服务是否正常：
    1. ./xchain-cli status -H 127.0.0.1:37102
    2. ./xchain-cli status -H 127.0.0.1:37103
    若节点高度一致，则网络启动成功。

3.5.2 搭建TDPoS共识网络

3.5.1 是搭建一个SINGLE共识的多节点网络。网络中的矿工节点是node。XuperUnion系统支持可插拔共识，通过修改创世块的参数，可以创建一个TDPoS链。下面创世块配置和单节点创世块配置的区别在于创世共识参数genesis_consensus的config配置，各个配置参数详解配置说明如下所示：

  2. {
  3.     "version" : "1"
  4.     , "predistribution":[
  5.         {
  6.             "address" : "mahtKhdV5SZP4FveEBzX7j6FgUGfBS9om"
  7.             , "quota" : "100000000000000000000"
  8.         }
  9.     ]
  10.     , "maxblocksize" : "128"
  11.     , "award" : "1000000"
  12.     , "decimals" : "8"
  13.     , "award_decay": {
  14.         "height_gap": 31536000,
  15.         "ratio": 1
  16.     }, "genesis_consensus":{
  17.         "name": "tdpos",
  18.         "config": {
  19.                 "timestamp": "1548123921000000000", // tdpos共识初始时间，声明tdpos共识的起始时间戳，建议设置为一个刚过去不旧的时间戳
  20.                 "proposer_num":"3",// 每一轮选举出的矿工数，如果某一轮的投票不足以选出足够的矿工数则默认复用前一轮的矿工
  21.                 "period":"3000",// 每个矿工连续出块的出块间隔
  22.                 "alternate_interval":"6000",// 每一轮内切换矿工时的时间间隔，需要为period的整数倍
  23.                 "term_interval":"9000", // 切换轮时的出块间隔，即下一轮第一个矿工出第一个块距离上一轮矿工出最后一个块的时间间隔，需要为period的整数配
  24.                 "block_num":"200",// 每一轮内每个矿工轮值任期内连续出块的个数
  25.                 "vote_unit_price":"1",// 为被提名的候选人投票时，每一票单价，即一票等于多少Xuper
  26.         // 指定第一轮初始矿工，矿工个数需要符合proposer_num指定的个数，所指定的初始矿工需要在网络中存在，不然系统轮到该节点出块时会没有节点出块
  27.                 "init_proposer": {
  28.                         "1":["RU7Qv3CrecW5waKc1ZWYnEuTdJNjHc43u","XpQXiBNo1eHRQpD9UbzBisTPXojpyzkxn","SDCBba3GVYU7s2VYQVrhMGLet6bobNzbM"]
  29.                         }
  30.                 }
  31.         }
  32. }

修改完创世块参数后，删除./data/blockchain下的内容，3个节点全部重新创建链：

  1.    ./xchain-cli createChain

先启动node，再启动node2和node3，至此TDPoS共识的集群启动成功。

3.5.3 提名候选人

  1. ./xchain-cli transfer --to=dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN --name=$chain --desc=./nominate.json --amount=11000002266 --frozen=-1 -H=$host

nominate.json

  1. {
  2.   "module": "tdpos",
  3.   "method": "nominate_candidate",
  4.   "args": {
  5.     "candidate": "提名address"
  6.     }
  7. }

3.5.4 投票

  1. ./xchain-cli transfer --to=dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN --desc=./vote.json --amount=$ballots --frozen=-1 --name=$chain -H=$host

vote.json

  1. {
  2.   "module": "tdpos",
  3.   "method": "vote",
  4.   "args" : {
  5.     "candidates":["提名过的address"]
  6.     }
  7. }

3.5.5 撤销提名 && 撤销投票

  1. ./xchain-cli transfer --to Y4TmpfV4pvhYT5W17J7TqHSLo6cqq23x3 --desc=./revoke_demo.json --amount=1

revoke_demo.json

  1. {
  2.     "module":"proposal",
  3.     "method": "Thaw",
  4.     "args" : {
  5.         "txid":"02cd75a721f2589a3ff6768b49650b46fa0b042f970df935b4d28a15aa19e49a" // 提名或者投票时的txid,发起的交易的input需只有一个，且address与提名或者投票时需要相同
  6.      }
  7. }

3.5.6 TDPOS结果查询

  1. ./xchain-cli tdpos -h

提示如下所示：

tdpos命令行

1.查询候选人信息

  1. ./xchain-cli tdpos query-candidates --name=$chain -H=$host

2.查看某一轮的出块顺序

  1. ./xchain-cli tdpos query-checkResult -t=30 --name=$chain -H=$host

3.查询提名信息：某地址发起提名的记录

  1. ./xchain-cli tdpos query-nominate-records --name=$chain -H=$host -a=dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN

4.被提名查询：某个候选人被提名的记录

  1. ./xchain-cli tdpos query-nominee-record --name=$chain -H=$host -a=TyYCWDJ1pyV8fA3VyPenCdFdcPmHnwMhx

5.某选民的有效投票记录

  1. ./xchain-cli tdpos query-vote-records --name=$chain -H=$host -a=dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN

6.某候选人被投票记录

  1. ./xchain-cli tdpos query-voted-records --name=$chain -H=$host -a=TyYCWDJ1pyV8fA3VyPenCdFdcPmHnwMhx

3.5.7 常见问题

  1. 端口冲突：注意如果在一台机器上部署3个节点，各个节点的RPC监听端口以及p2p监听端口都需要设置地不相同，避免冲突；
  2. 节点公私钥和节点netUrl冲突：注意网络中不同节点 ./data/keys下的文件和./data/netkeys下的内容都不一样，这两个文件夹是节点在网络中的唯一标识，每个节点需要独自生成，否则网络启动异常。
  3. 启动时链接bootNodes节点失败：注意要先将bootNodes节点启动，再起动其他节点，否则会加入网络失败而启动失败。
  4. The gas you cousume is: XXXX, You need add fee. 通过加--fee XXXX 参数附加资源