公众号：元壤

元壤yr.xyz：一分钟搭建您专属的NFT数字藏品服务平台。

命令行工具

1.1. 简介

cmc(ChainMaker Client)是ChainMaker提供的命令行工具，用于和ChainMaker链进行交互以及生成证书或者密钥等功能。cmc基于go语言编写，通过使用ChainMaker的go语言sdk（使用grpc协议）达到和ChainMaker链进行交互的目的。
cmc的详细日志请查看./sdk.log

1.2. 身份模式

长安链在2.1版本以后支持不同身份模式，详情见身份权限管理的身份模式部分。本篇文章中主要是介绍Public模式，其它两种模式的cmc使用文档如下：

• Public
• PermissionedWithCert
• PermissionedWithKey

1.3. 编译&配置

cmc工具的编译&运行方式如下：

创建工作目录 $WORKDIR 比如 ~/chainmaker 启动测试链 在工作目录下 使用脚本搭建

  # 编译cmc
  $ cd $WORKDIR/chainmaker-go/tools/cmc
  $ go build
  # 配置测试数据
  $ cp -rf $WORKDIR/chainmaker-go/build/crypto-config $WORKDIR/chainmaker-go/tools/cmc/testdata/ # 使用chainmaker-cryptogen生成的测试链的密钥
  # 查看help
  $ cd $WORKDIR/chainmaker-go/tools/cmc
  $ ./cmc --help

编译 cmc：

命令解释：

• 命令执行成功后，会在当前目录生成可执行文件 cmc。

配置测试数据：

命令解释：

• cmc 将读取配置文件 ./testdata/sdk_config.yml 中证书相关的配置项。
• 配置文件 ./testdata/sdk_config.yml 默认将证书放在 ./testdata/crypto-config 目录下。
• 上面执行的 cp 命令将由 $WORKDIR/chainmaker-go/scripts/prepare.sh 脚本生成的证书文件复制到默认的目录。

1.4. 自定义配置

cmc 依赖 sdk-go 配置文件。 编译&配置 步骤使用的是 SDK配置模版 可通过修改 ~/chainmaker/chainmaker-go/tools/cmc/testdata/sdk_config_pk.yml 实现自定义配置。 比如 user-signkey-file-path 参数可设置为普通用户或admin用户的私钥路径。设置后cmc将会以对应用户身份与链建立连接。 其他详细配置项请参看 ~/chainmaker/chainmaker-go/tools/cmc/testdata/sdk_config_pk.yml 中的注解。

sdk_config_pk.yml：

chain_client:
  # 链ID
  chain_id: "chain1"

  # 客户端用户交易签名私钥路径
  user_sign_key_file_path: "./testdata/crypto-config/node1/admin/admin1/admin1.key"

  # 签名使用的哈希算法，和节点保持一直
  crypto:
    hash: SHA256
  auth_type: public
  # 默认支持TimestampKey，如果开启enableNormalKey则是有NormalKey
  enable_normal_key: false

  nodes:
    - # 节点地址，格式为：IP:端口:连接数
      node_addr: "127.0.0.1:12301"
      # 节点连接数
      conn_cnt: 10
    - # 节点地址，格式为：IP:端口:连接数
      node_addr: "127.0.0.1:12302"
      # 节点连接数
      conn_cnt: 10

  archive:
    # 数据归档链外存储相关配置
    type: "mysql"
    dest: "root:123456:localhost:3306"
    secret_key: xxx

  rpc_client:
    max_receive_message_size: 16 # grpc客户端接收消息时，允许单条message大小的最大值(MB)
    max_send_message_size: 16 # grpc客户端发送消息时，允许单条message大小的最大值(MB)

1.5. 功能

TBFT共识场景下的cmc提供功能如下:

• 私钥管理：私钥生成功能
• 交易功能：主要包括链管理、用户合约发布、升级、吊销、冻结、调用、查询等功能
• 查询链上数据：查询链上block和transaction
• 链配置：查询及更新链配置
• 归档&恢复功能：将链上数据转移到独立存储上，归档后的数据具备可查询、可恢复到链上的特性
• gas管理：gas管理类命令，包括设置 gas admin、充值 gas 等功能
• 地址转换：转换成指定类型的地址。支持转换成至信链等类型的地址

DPOS共识场景下的cmc命令

1.5.1. 示例（TBFT共识）

1.5.1.1. 私钥管理

生成私钥， 目前支持的算法有SM2、ECC_P256，未来将支持更多算法。 参数说明：

$ ./cmc key gen -h 
Private key generate
Usage:
  cmc key gen [flags]

Flags:
  -a, --algo string specify key generate algorithm
  -h, --help        help for gen
  -n, --name string specify storage name
  -p, --path string specify storage path

示例： $ ./cmc key gen -a ECC_P256 -n ca.key -p ./

1.5.1.2. 交易功能

1.5.1.2.1. 用户合约

cmc的交易功能用来发送交易和链进行交互，主要参数说明如下：

  sdk配置文件flag
  --sdk-conf-path：指定cmc使用sdk的配置文件路径

  如果想覆盖sdk配置文件中的配置，则使用以下两个flag且都必填；如不传，则默认使用sdk配置文件中的配置参数
  --chain-id: 指定链Id, 会覆盖sdk配置文件读取的配置
  --user-signkey-file-path: 指定发送交易的用户sign私钥路径, 会覆盖sdk配置文件读取的配置

  其他flags
  --byte-code-path：指定合约的wasm文件路径
  --contract-name：指定合约名称
  --method：指定调用的合约方法名称
  --runtime-type：指定合约执行虚拟机环境，包含：GASM、EVM、WASMER、WXVM、NATIVE、DOCKER VM
  --version：指定合约的版本号，在发布和升级合约时使用
  --sync-result：指定是否同步等待交易执行结果，默认为false，如果设置为true，在发送完交易后会主动查询交易执行结果
  --params：指定发布合约或调用合约时的参数信息
  --concurrency：指定调用合约并发的go routine，用于压力测试
  --total-count-per-goroutine：指定单个go routine发送的交易数量，用于压力测试，和--concurrency配合使用
  --block-height：指定区块高度
  --tx-id：指定交易Id
  --with-rw-set：指定获取区块时是否附带读写集，默认是false
  --abi-file-path：调用evm合约时需要指定被调用合约的abi文件路径，如：--abi-file-path=./testdata/balance-evm-demo/ledger_balance.abi

• 创建wasm合约

  $ ./cmc client contract user create \
  --contract-name=fact \
  --runtime-type=WASMER \
  --byte-code-path=./testdata/claim-wasm-demo/rust-fact-2.0.0.wasm \
  --version=1.0 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --sync-result=true \
  --params="{}"

如下返回表示成功： response: message:”OK” contract_result:<result:”\n\004fact\022\0031.0\030\002<\n\026wx-org1.chainmaker.org\020\001\032 F]\334,\005O\200\272\353\213\274\375nT\026%K\r\314\362\361\253X\3562\377\216\250kh\031” message:”OK” > tx_id:”991a1c00369e4b76853dadf410182bcdfc86062f8cf1478f93482ba9000191d7” 注：智能合约编写参见：智能合约开发

• 调用wasm合约

  $ ./cmc client contract user invoke \
  --contract-name=fact \
  --method=save \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --params="{\"file_name\":\"name007\",\"file_hash\":\"ab3456df5799b87c77e7f88\",\"time\":\"6543234\"}" \
  --sync-result=true

如下返回表示成功： INVOKE contract resp, [code:0]/[msg:OK]/[contractResult:gas_used:12964572 contract_event:<topic:”topic_vx” tx_id:”7c9e98befbb64cec916765d760d4def5aa26f8bac78d419c9018b8d220e7f041” contract_name:”fact” contract_version:”1.0” event_data:”ab3456df5799b87c77e7f88” event_data:”” event_data:”6543234” > ]/[txId:7c9e98befbb64cec916765d760d4def5aa26f8bac78d419c9018b8d220e7f041]

• 查询合约

  $ ./cmc client contract user get \
  --contract-name=fact \
  --method=find_by_file_hash \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --params="{\"file_hash\":\"ab3456df5799b87c77e7f88\"}"

如下返回表示成功： QUERY contract resp: message:”SUCCESS” contract_result:<result:”{“file_hash”:”ab3456df5799b87c77e7f88”,”file_name”:””,”time”:”6543234”}” gas_used:24354672 > tx_id:”25716b955ebd4a258c4bd6b6f682f1341dfe97e4bd18495c864992f1618a2003”

• 升级合约

  $ ./cmc client contract user upgrade \
  --contract-name=fact \
  --runtime-type=WASMER \
  --byte-code-path=./testdata/claim-wasm-demo/rust-fact-2.0.0.wasm \
  --version=2.0 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --sync-result=true \
  --params="{}"

如下返回表示成功：其中result结果为用户自定义，每个合约可能不一样，也可能没有。 upgrade user contract params:[] upgrade contract resp: message:”OK” contract_result:<result:”\n\004fact\022\0032.0\030\002<\n\026wx-org1.chainmaker.org\020\001\032 F]\334,\005O\200\272\353\213\274\375nT\026%K\r\314\362\361\253X\3562\377\216\250kh\031” message:”OK” > tx_id:”d89df9fcd87f4071972fdabdf3003a349250a94893fb43899eac4d68e7855d52”

• 冻结合约

  $ ./cmc client contract user freeze \
  --contract-name=fact \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --sync-result=true

如下返回表示成功：冻结后的合约再去执行查询、调用合约则会失败 freeze contract resp: message:”OK” contract_result:<result:”{“name”:”fact”,”version”:”3.0”,”runtime_type”:2,”status”:1,”creator”:{“org_id”:”wx-org1.chainmaker.org”,”member_type”:1,”member_info”:”Rl3cLAVPgLrri7z9blQWJUsNzPLxq1juKjL/jqhraBk=”}}” message:”OK” > tx_id:”09841775173548ad9a8a39e2987a4f5115d59d50dd3448e8b09a83624dee5367”

• 解冻合约

  $ ./cmc client contract user unfreeze \
  --contract-name=fact \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --sync-result=true

如下返回表示成功：解冻后的合约可正常使用 unfreeze contract resp: message:”OK” contract_result:<result:”{“name”:”fact”,”version”:”3.0”,”runtime_type”:2,”creator”:{“org_id”:”wx-org1.chainmaker.org”,”member_type”:1,”member_info”:”Rl3cLAVPgLrri7z9blQWJUsNzPLxq1juKjL/jqhraBk=”}}” message:”OK” > tx_id:”fccf024450c140dea999cc46ad24d381a679ce2142bd48b2a829abcd4f099866”

• 吊销合约

  $ ./cmc client contract user revoke \
  --contract-name=fact \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --sync-result=true

如下返回表示成功：吊销合约后，不可恢复，且不能对该合约执行任何操作，包括查询。 revoke contract resp: message:”OK” contract_result:<result:”{“name”:”fact”,”version”:”3.0”,”runtime_type”:2,”status”:2,”creator”:{“org_id”:”wx-org1.chainmaker.org”,”member_type”:1,”member_info”:”Rl3cLAVPgLrri7z9blQWJUsNzPLxq1juKjL/jqhraBk=”}}” message:”OK” > tx_id:”d971b57cf12c46ff8fe0d4f5897634c644fb802998f44360bb130f27ff54a10a”

1.5.1.3. 查询链上数据

查询链上block和transaction 主要参数说明如下：

  --sdk-conf-path：指定cmc使用sdk的配置文件路径
  --chain-id：指定链Id

• 根据区块高度查询链上未归档区块

  ./cmc query block-by-height [blockheight] \
  --chain-id=chain1 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml

• 根据区块hash查询链上未归档区块

  ./cmc query block-by-hash [blockhash] \
  --chain-id=chain1 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml

• 根据txid查询链上未归档区块

  ./cmc query block-by-txid [txid] \
  --chain-id=chain1 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml

• 根据txid查询链上未归档tx

  ./cmc query tx [txid] \
  --chain-id=chain1 \
  --sdk-conf-path=./testdata/sdk_config_pk.yml

1.5.1.4. 链配置

查询及更新链配置 主要参数说明如下：

  sdk配置文件flag
  --sdk-conf-path：指定cmc使用sdk的配置文件路径

  admin签名者flags，此类flag的顺序及个数必须保持一致，且至少传入一个admin（当前只有管理员的添加删除需要用到管理员多签）
  --admin-key-file-paths: admin签名者的tls key文件的路径列表. 单签模式下只需要填写一个即可, 离线多签模式下多个需要用逗号分割

  如果想覆盖sdk配置文件中的配置，则使用以下两个flag且都必填；如不传，则默认使用sdk配置文件中的配置参数
  --chain-id: 指定链Id, 会覆盖sdk配置文件读取的配置
  --user-signkey-file-path: 指定发送交易的用户sign私钥路径, 会覆盖sdk配置文件读取的配置

  --block-interval: 出块时间 单位ms
  --tx-parameter-size: 交易参数最大限制 单位:MB
  --trust-root-org-id: 增加/删除/更新组织管理员公钥时指定的组织Id
  --trust-root-path: 增加/删除/更新组织管理员公钥时指定的管理员公钥文件目录
  --node-id: 增加/删除/更新共识节点Id时指定的节点Id
  --node-ids: 增加/更新共识节点Org时指定的节点Id列表
  --node-org-id: 增加/删除/更新共识节点Id,Org时指定节点的组织Id 
  --address-type: 地址类型 ChainMaker:0, 至信链:1

• 查询链配置

  ./cmc client chainconfig query \
  --sdk-conf-path=./testdata/sdk_config_pk.yml

• 更新出块时间

  ./cmc client chainconfig block updateblockinterval \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --block-interval 1000

• 更新交易参数最大值限制

  ./cmc client chainconfig block updatetxparametersize \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --tx-parameter-size 10 

• 添加共识节点

  ./cmc client chainconfig consensusnodeid add \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --user-signkey-file-path=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --node-id=QmcQHCuAXaFkbcsPUj7e37hXXfZ9DdN7bozseo5oX4qiC4 \
  --node-org-id=public

• 删除共识节点

  ./cmc client chainconfig consensusnodeid remove \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --user-signkey-file-path=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --node-id=QmXxeLkNTcvySPKMkv3FUqQgpVZ3t85KMo5E4cmcmrexrC \
  --node-org-id=public

• 更新共识节点

  ./cmc client chainconfig consensusnodeid update \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --user-signkey-file-path=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --node-id=QmXxeLkNTcvySPKMkv3FUqQgpVZ3t85KMo5E4cmcmrexrC \
  --node-id-old=QmcQHCuAXaFkbcsPUj7e37hXXfZ9DdN7bozseo5oX4qiC4 \
  --node-org-id=public

• 更新共识节点Org

  ./cmc client chainconfig consensusnodeorg update \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --user-signkey-file-path=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --node-ids=QmbUjZPooufuTbRBxzVx546xyLpwibwsQXRPD6SwWfZMgx,QmP2GcRYFh2xQ2rh4CXsCN1d9CMxk9SktygXiwFKG487mo,QmSJGZxUSq5xXGZ68myuHcAqHsExioS8Bt87WZ3LsqRauC,QmcVEe4uVS2b6zNVKMzL57CdDhJtXey4wcktPdDv3JgyDg \
  --node-org-id=public

• 更新管理员公钥

  ./cmc client chainconfig trustroot update \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --user-signkey-file-path=./testdata/crypto-config/node1/admin/admin1/admin1.key \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --trust-root-org-id=public \
  --trust-root-path=./testdata/crypto-config/node1/admin/admin1/admin1.pem,./testdata/crypto-config/node1/admin/admin2/admin2.pem,./testdata/crypto-config/node1/admin/admin3/admin3.pem

• 开启/关闭链的 gas 功能

  ./cmc client gas \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --gas-enable=true

• 更新链的账户地址类型

  ./cmc client chainconfig alter-addr-type \
  --sdk-conf-path=./testdata/sdk_config_pk.yml \
  --admin-key-file-paths=./testdata/crypto-config/node1/admin/admin1/admin1.key,./testdata/crypto-config/node1/admin/admin2/admin2.key,./testdata/crypto-config/node1/admin/admin3/admin3.key \
  --address-type=1 \
  --sync-result=true

。。。。。。