1. Experience Changan Chain through the command line

Official document
https://docs.chainmaker.org.cn/v2.3.1/html/quickstart/%E9%80%9A%E8%BF%87%E5%91%BD%E4%BB%A4%E8%A1 %8C%E4%BD%93%E9%AA%8C%E9%93%BE.html#

This article is based on the official documentation and is a demonstration record.

1 Overview

Through this article, you can build a Changan Chain multi-node cluster and deploy smart contracts through the command line and cmc tool, and complete the initial experience of Changan Chain.

The following steps are required to build Changan Chain through source code and check data on the chain. This article will demonstrate them one by one.

• Download Changan chain and certificate management tool source code

• Compile source code

• Generate node certificate

• Compilation and installation package production

• Start node cluster

• View node status

• Use CMC tools to install, call and query a contract

2. Environmental dependence

2.1. Hardware dependency

This is just a reference for everyone. If the configuration is not enough, it will be stuck. It is not a big problem. Come on~

Configuration	Minimum configuration	Recommended configuration
CPU	1.5GHz	2.4GHz
Memory	8GB	16GB
core	4 Nuclear	8 cores
bandwidth	2Mb	10Mb

2.2. Software dependencies

The current document is completed under centos7 operation. The following is a list of dependent software required for this demonstration:

name	Version	describe	Is it necessary
git	/	Source code management	yes
golang	1.16-1.19	Compilation environment (domestic agent needs to be modified)	yes
gcc	7.3+	Compilation environment dependencies	yes
glibc	2.18	Smart contract execution environment dependencies	yes
tmux	/	Default quick start command dependencies	no
wasmer runtime library libwasmer_runtime_c_api.so	/	In the https://git.chainmaker.org.cn/chainmaker/vm-wasmer/-/tree/master/wasmer-go/packaged/lib directory, find the library corresponding to the chain branch and add the library path to the system PATH environment The startup script under the variable is included by default. For separate startup, the following configuration must be added: cd deployPath/lib cp xxx/main/libwasmer_runtime_c_api.so libwasmer.so export LD_LIBRARY_PATH=deployPath/lib:$LD_LIBRARY_PATH	yes

2.3. git installation

# 使用yum命令安装
yum install -y git

# 验证查看版本号
git --version

2.4. golang installation

Recommended: Version 1.16-1.19

Please move to the tutorial: Installing Golang under Linux

2.5、gcc

• Check gcc version

  gcc --version
  

  

• If the displayed result is < 7.3, perform the following steps to upgrade.

  sudo yum install centos-release-scl
  sudo yum install devtoolset-7-gcc*
  scl enable devtoolset-7 bash
  

  Note: The third command scl enable devtoolset-7 bash only upgrades gcc in the current session. If you want to automatically upgrade gcc every time you log in, you can put scl enable devtoolset-7 bash in the ~/.bash_profile file.

  vim ~/.bash_profile
  

  

• If it is not installed, just execute the command to install it.

  yum install -y gcc
  

3. Environment construction

The following will introduce the use of scripts to build the environment.

Available on Linux, MacOS

3.1. Source code download

Download the source code from the Changan Chain official website: https://git.chainmaker.org.cn/chainmaker/chainmaker-go

It is currently a private warehouse and requires account registration first.

The source code here is placed in the /data directory.

Download chainmaker-go source code to local

$ git clone -b v2.3.1 --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git

Download the certificate generation tool source code to your local computer

$ git clone -b v2.3.0  --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-cryptogen.git

3.2. Source code compilation

• Compile certificate generation tool

  $ cd chainmaker-cryptogen
  $ make
  

  As a result, bin and release directories will be generated.
  

• Configuration file generation:
  soft-link the compiled chainmaker-cryptogen to the chainmaker-go/tools directory

  # 进入工具目录
  $ cd chainmaker-go/tools
  
  # 软连接chainmaker-cryptogen到tools目录下
  $ ln -s ../../chainmaker-cryptogen/ .
  

  
  After version 2.1, ChainMaker supports multiple identity modes. Since the directory structure and content of configuration files vary greatly under different identity modes, here we choose the identity mode PermissionedWithCert (see Identity Permission Management for details) as an example .

• 
  The original identity mode of PermissionedWithCert , that is, the certificate mode
  . Enter the chainmaker-go/scripts directory and execute the prepare.sh script to generate a single-chain 4-node cluster configuration, which is stored in the path chainmaker-go/build

  The prepare.sh script supports generating solo mode node certificates and configurations, as well as the certificates and configurations of 4/7/10/13/16 nodes

  # 进入脚本目录
  $ cd ../scripts
  
  # 查看脚本帮助
  $ ./prepare.sh -h
  Usage:  
    prepare.sh node_cnt(1/4/7/10/13/16) chain_cnt(1-4) p2p_port(default:11301) rpc_port(default:12301)
      eg1: prepare.sh 4 1
      eg2: prepare.sh 4 1 11301 12301
  
  # 生成单链4节点集群的证书和配置
  $ ./prepare.sh 4 1
  begin check params...
  begin generate certs, cnt: 4
  input consensus type (0-SOLO,1-TBFT(default),3-HOTSTUFF,4-RAFT,5-DPOS):
  input log level (DEBUG|INFO(default)|WARN|ERROR):
  enable docker vm (YES|NO(default))
  begin generate node1 config...
  begin generate node2 config...
  begin generate node3 config...
  begin generate node4 config...
  
  # 查看生成好的节点证书和配置
  $ tree -L 3 ../build/
  ../build/
  ├── config
  │   ├── node1
  │   │   ├── certs
  │   │   ├── chainconfig
  │   │   ├── chainmaker.yml
  │   │   └── log.yml
  │   ├── node2
  │   │   ├── certs
  │   │   ├── chainconfig
  │   │   ├── chainmaker.yml
  │   │   └── log.yml
  │   ├── node3
  │   │   ├── certs
  │   │   ├── chainconfig
  │   │   ├── chainmaker.yml
  │   │   └── log.yml
  │   └── node4
  │       ├── certs
  │       ├── chainconfig
  │       ├── chainmaker.yml
  │       └── log.yml
  ├── crypto-config
  │   ├── wx-org1.chainmaker.org
  │   │   ├── ca
  │   │   ├── node
  │   │   └── user
  │   ├── wx-org2.chainmaker.org
  │   │   ├── ca
  │   │   ├── node
  │   │   └── user
  │   ├── wx-org3.chainmaker.org
  │   │   ├── ca
  │   │   ├── node
  │   │   └── user
  │   └── wx-org4.chainmaker.org
  │       ├── ca
  │       ├── node
  │       └── user
  └── crypto_config.yml
  

  About automatically generated port descriptions

  The configuration generated by the prepare.sh script is deployed on a single server by default, so the automatically generated port number starts from a starting port number and increases in sequence. The starting port number can be modified through command line parameters.

  There are mainly 2 ports, p2p port (used for node interconnection) and rpc port (used for client-node communication). The p2p starting port is 11301, and the rpc starting port is 12301.

  If a configuration of 4 nodes is generated, the p2p ports are: 11301, 11302, 11303, and 11304, and the rpc ports are: 12301, 12302, 12303, and 12304.

  If you are deploying on multiple machines and want to generate a fixed port number, please refer to: [Multi-machine deployment]

3.3. Compilation and installation package production

After generating the certificate (prepare.sh script) and executing the build_release.sh script, the chainmaker-go module will be compiled, packaged and installed, and stored in the path chainmaker-go/build/release

$ ./build_release.sh
$ tree ../build/release/
../build/release/
├── chainmaker-v2.0.0-wx-org1.chainmaker.org-20210406194833-x86_64.tar.gz
├── chainmaker-v2.0.0-wx-org2.chainmaker.org-20210406194833-x86_64.tar.gz
├── chainmaker-v2.0.0-wx-org3.chainmaker.org-20210406194833-x86_64.tar.gz
├── chainmaker-v2.0.0-wx-org4.chainmaker.org-20210406194833-x86_64.tar.gz
└── crypto-config-20210406194833.tar.gz

3.4. Start the node cluster

• Executing the cluster_quick_start.sh script will decompress each installation package, call the start.sh script in the bin directory, and start the chainmaker node.

  $ ./cluster_quick_start.sh normal
  

  

• After successful startup, back up *.tar.gz to prevent the file from being overwritten when you decompress it again next time.

  $ mkdir -p ../build/bak
  $ mv ../build/release/*.tar.gz ../build/bak
  

  If you need to shut down the cluster, use the script:
  $ ./cluster_quick_stop.sh

3.5. Check whether the node is started and used normally.

• Check if the process exists

  $ ps -ef|grep chainmaker | grep -v grep
  

  

• Check whether the port is listening

  $ netstat -lptn | grep 1230
  

  

• Check whether the node has ERROR logs

  $ cat ../build/release/*/bin/panic.log
  $ cat ../build/release/*/log/system.log
  $ cat ../build/release/*/log/system.log |grep "ERROR\|put block\|all necessary"
  //若看到all necessary peers connected则表示节点已经准备就绪。
  

  

4. Use CMC command line tools to deploy and call contracts

In order to verify whether the built chain functions normally, you can use the cmc command line tool to verify.

4.1. Compilation & Configuration

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

4.2. Deploy sample contract

• Create wasm contract

  ./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.yml \
  --admin-key-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.key,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.key \
  --admin-crt-file-paths=./testdata/crypto-config/wx-org1.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org2.chainmaker.org/user/admin1/admin1.sign.crt,./testdata/crypto-config/wx-org3.chainmaker.org/user/admin1/admin1.sign.crt \
  --sync-result=true \
  --params="{}"
  

  Note: For smart contract writing, see: Smart Contract Development

  

• Call the wasm contract

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

  

• Query contract

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

  

4.3 Query data on the chain

The main parameters of block and transaction on the query chain are explained as follows:

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

• Query unarchived blocks on the chain based on block height

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

• Query unarchived blocks on the chain based on block hash

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

• Query unarchived blocks on the chain based on txid

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

• Query unarchived tx on the chain based on txid

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

Query chain configuration

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

5. Changan Chain deployment directory description

This directory is the directory structure description after starting using: chainmaker-go/scripts/cluster_quick_start.sh.

[root@sw build]# tree
.
├── backup # 下次重新prepare.sh时，此次的备份。
├── config # 使用 prepare.sh 生成的节点配置信息
│   ├── node1 # 节点1-4
│   ├── node2
│   ├── node3
│   └── node4
├── crypto-config # 使用 prepare.sh 生成的组织证书信息
│   ├── wx-org1.chainmaker.org # 组织名称1-4
│   │   ├── ca # 该组织的根证书 ca
│   │   ├── node # 由该组织的根证书签发的节点证书 common/consensus
│   │   └── user # 由该组织的根证书签发的用户证书 admin/client/light
│   ├── wx-org2.chainmaker.org
│   │   ├── ca
│   │   ├── node
│   │   └── user
│   ├── wx-org3.chainmaker.org
│   │   ├── ca
│   │   ├── node
│   │   └── user
│   └── wx-org4.chainmaker.org
│       ├── ca
│       ├── node
│       └── user
├── crypto_config.yml # 使用 prepare.sh 生成以上证书的配置文件（扩展组织、证书可使用到）
├── pkcs11_keys.yml # 使用 prepare.sh 生成的硬件加密机相关配置
└── release # 使用 build_release.sh 生成的打包好的部署文件夹
    ├── crypto-config-20220720141039.tar.gz # 证书集 即上面的crypto-config文件夹的压缩包
    ├── chainmaker-v2.3.0-wx-org2.chainmaker.org # 使用 cluster_quick_start.sh 启动链后，解压缩后的部署文件
    │   ├── bin  # 操作管理脚本目录
    │   ├── config # 配置文件目录
    │   ├── data # 数据目录
    │   ├── lib # 依赖目录
    │   └── log # 日志目录
    ├── chainmaker-v2.3.0-wx-org2.chainmaker.org-20220720141039-x86_64.tar.gz # 使用 build_release.sh 生成的打包好的部署文件
    ├── chainmaker-v2.3.0-wx-org3.chainmaker.org
    │   ├── bin
    │   ├── config
    │   ├── data
    │   ├── lib
    │   └── log
    ├── chainmaker-v2.3.0-wx-org3.chainmaker.org-20220720141039-x86_64.tar.gz
    ├── chainmaker-v2.3.0-wx-org4.chainmaker.org
    │   ├── bin
    │   ├── config
    │   ├── data
    │   ├── lib
    │   └── log
    │── chainmaker-v2.3.0-wx-org4.chainmaker.org-20220720141039-x86_64.tar.gz
    |
    |
    | # 以下为部署节点文件详情
    ├── chainmaker-v2.3.0-wx-org1.chainmaker.org # 解压缩后的部署文件
    │   ├── bin  # 操作管理脚本目录
    │   │   ├── chainmaker # 二进制文件
    │   │   ├── chainmaker.service # 基于 linux 系统的 systemd 自拉起服务
    │   │   ├── docker-vm-standalone-start.sh # 独立启动 docker 虚拟机引擎脚本
    │   │   ├── docker-vm-standalone-stop.sh # 独立停止 docker 虚拟机引擎脚本
    │   │   ├── init.sh # 基于 linux 系统的 systemd 自拉起服务部署脚本
    │   │   ├── panic.log # 异常日志输出及控制台输出日志文件
    │   │   ├── restart.sh # 重启节点脚本
    │   │   ├── run.sh # 基于 linux 系统的 systemd 自拉起服务管理脚本
    │   │   ├── start.sh # 启动节点脚本
    │   │   └── stop.sh # 停止节点脚本
    │   ├── config # 配置文件目录
    │   │   └── wx-org1.chainmaker.org
    │   │       ├── certs # 证书
    │   │       │   ├── ca
    │   │       │   │   ├── wx-org1.chainmaker.org
    │   │       │   │   │   └── ca.crt
    │   │       │   ├── node 
    │   │       │   │   |── common1 # 同步节点证书（通过chainmaker.yml配置为节点证书，表示只可同步）
    │   │       │   │   └── consensus1 # 共识节点证书（通过chainmaker.yml配置为节点证书不代表就可以参与共识，共识管理是在链配置bc.yml中）
    │   │       │   │       ├── consensus1.nodeid # xxx.sign.crt生成的节点id
    │   │       │   │       ├── consensus1.sign.crt # 签名证书
    │   │       │   │       ├── consensus1.sign.key # 签名key
    │   │       │   │       ├── consensus1.tls.crt # tls连接证书
    │   │       │   │       └── consensus1.tls.key # tls连接key
    │   │       │   └── user # 用户证书
    │   │       │       ├── admin1 # 管理员
    │   │       │       │   ├── admin1.sign.crt
    │   │       │       │   ├── admin1.sign.key
    │   │       │       │   ├── admin1.tls.crt
    │   │       │       │   └── admin1.tls.key
    │   │       │       ├── client1 # 普通客户端
    │   │       │       │   ├── client1.addr
    │   │       │       │   ├── client1.sign.crt
    │   │       │       │   ├── client1.sign.key
    │   │       │       │   ├── client1.tls.crt
    │   │       │       │   └── client1.tls.key
    │   │       │       └── light1 # 轻节点，只可同步当前组织的数据（区块、交易）
    │   │       │           ├── light1.sign.crt
    │   │       │           ├── light1.sign.key
    │   │       │           ├── light1.tls.crt
    │   │       │           └── light1.tls.key
    │   │       ├── chainconfig # 链配置
    │   │       │   │── bc1.yml # 第一条链配置
    │   │       │   └── bc2.yml # 第二条链配置
    │   │       ├── chainmaker.yml # 节点配置
    │   │       └── log.yml # 日志配置
    │   ├── data # 数据目录
    │   │   └── wx-org1.chainmaker.org
    │   │       ├── block # 区块数据/索引（必须）
    │   │       │   └── chain1
    │   │       │       └── store_block
    │   │       │           ├── 000001.log
    │   │       │           ├── CURRENT
    │   │       │           ├── LOCK
    │   │       │           ├── LOG
    │   │       │           └── MANIFEST-000000
    │   │       ├── history # 历史数据
    │   │       │   └── chain1
    │   │       │       └── store_history
    │   │       │           ├── 000001.log
    │   │       │           ├── CURRENT
    │   │       │           ├── LOCK
    │   │       │           ├── LOG
    │   │       │           └── MANIFEST-000000
    │   │       ├── ledgerData1 # 中间数据（必须）
    │   │       │   └── chain1 # 链ID
    │   │       │       ├── bfdb # 区块实际存储数据（文件存储方式）
    │   │       │       │   └── 00000000000000000001.fdb.END
    │   │       │       ├── localdb # 中间状态数据
    │   │       │       │   ├── 000001.log
    │   │       │       │   ├── CURRENT
    │   │       │       │   ├── LOCK
    │   │       │       │   ├── LOG
    │   │       │       │   └── MANIFEST-000000
    │   │       │       └── wal_QmSQeH1SV65YkafQG6y7uqabF4Xwzn5VoXniFBXrzy4Eqn # 异常恢复临时数据
    │   │       │           └── 00001_1.wal
    │   │       ├── result # 结果集数据
    │   │       │   └── chain1
    │   │       │       └── store_result
    │   │       │           ├── 000001.log
    │   │       │           ├── CURRENT
    │   │       │           ├── LOCK
    │   │       │           ├── LOG
    │   │       │           └── MANIFEST-000000
    │   │       └── state # 状态数据（必须）
    │   │           └── chain1
    │   │               └── store_state
    │   │                   ├── 000001.log
    │   │                   ├── CURRENT
    │   │                   ├── LOCK
    │   │                   ├── LOG
    │   │                   └── MANIFEST-000000
    │   ├── lib # 依赖目录
    │   │   ├── libwasmer.so # wasmer（rust）运行引擎
    │   │   └── wxdec # wxvm（c++）运行引擎
    │   └── log # 日志目录
    │       ├── system.log # 当前1小时的日志
    │       └── system.log.2022072014 # 历史日志
    └── chainmaker-v2.3.0-wx-org1.chainmaker.org-20220720141039-x86_64.tar.gz # 使用 build_release.sh 生成的打包好的部署文件