控制台配置

标签:console 控制台配置 命令行交互工具


重要

  • 控制台 只支持FISCO BCOS 3.0+版本,基于 Java SDK 实现。
  • 可通过命令 ./start.sh --version 查看当前控制台版本

控制台是FISCO BCOS 3.0重要的交互式客户端工具,它通过Java SDK与区块链节点建立连接,实现对区块链节点数据的读写访问请求。控制台拥有丰富的命令,包括查询区块链状态、管理区块链节点、部署并调用合约等。此外,控制台提供一个合约编译工具,用户可以方便快捷的将Solidity和webankblockchain-liquid合约文件(以下简称wbc-liquid)编译后的WASM文件转换为Java合约文件。

wbc-liquid编译环境搭建请参考:wbc-liquid的环境配置

控制台配置与运行

重要

前置条件:搭建FISCO BCOS区块链,请参考 搭建第一个区块链网络 建链工具参考:

1. 获取控制台

cd ~ && mkdir -p fisco && cd fisco
# 获取控制台
curl -#LO https://github.com/FISCO-BCOS/console/releases/download/v3.0.0-rc3/download_console.sh && bash download_console.sh

注解

  • 如果因为网络问题导致长时间无法下载,请尝试 curl -#LO https://gitee.com/FISCO-BCOS/console/raw/master/tools/download_console.sh && bash download_console.sh

目录结构如下:

│── apps # 控制台jar包目录
│   └── console.jar
├── lib # 相关依赖的jar包目录
├── conf
│   ├── clog.ini    # c sdk日志配置文件
│   ├── config-example.toml # 配置文件
│   └── log4j.properties # 日志配置文件
├── contracts # 合约所在目录
│   ├── console # 控制台部署合约时编译的合约abi, bin,java文件目录
│   ├── sdk     # sol2java.sh脚本编译的合约abi, bin,java文件目录
│   ├── liquid  # WBC-Liquid 合约存放目录
│   └── solidity    # solidity合约存放目录
│       └── HelloWorld.sol # 普通合约:HelloWorld合约,可部署和调用
│       └── KVTableTest.sol # 使用KV存储接口的合约:KVTableTest合约,可部署和调用
│       └── KVTable.sol # 提供KV存储操作的接口合约    
│-- start.sh # 控制台启动脚本
│-- get_account.sh # 账户生成脚本
│-- get_gm_account.sh # 账户生成脚本,国密版
│-- contract2java.sh # Solidity/WBC-Liquid合约文件编译为java合约文件的开发工具脚本

2. 配置控制台

  • 区块链节点和证书的配置:
    • 将节点sdk目录下的所有文件拷贝到conf目录下。
    • conf目录下的config-example.toml文件重命名为config.toml文件。配置config.toml文件,其中添加注释的内容根据区块链节点配置做相应修改。

配置示例文件如下:

[cryptoMaterial]

certPath = "conf"                           # The certification path  
useSMCrypto = "false"                       # RPC SM crypto type

# The following configurations take the certPath by default if commented
# caCert = "conf/ca.crt"                    # CA cert file path
# sslCert = "conf/sdk.crt"                  # SSL cert file path
# sslKey = "conf/sdk.key"                   # SSL key file path

# The following configurations take the sm certPath by default if commented
# caCert = "conf/sm_ca.crt"                    # SM CA cert file path
# sslCert = "conf/sm_sdk.crt"                  # SM SSL cert file path
# sslKey = "conf/sm_sdk.key"                    # SM SSL key file path
# enSslCert = "conf/sm_ensdk.crt"               # SM encryption cert file path
# enSslKey = "conf/sm_ensdk.key"                # SM ssl cert file path

[network]
messageTimeout = "10000"
defaultGroup="group0"                            # Console default group to connect
peers=["127.0.0.1:20200", "127.0.0.1:20201"]    # The peer list to connect

[account]
authCheck = "false"
keyStoreDir = "account"         # The directory to load/store the account file, default is "account"
# accountFilePath = ""          # The account file path (default load from the path specified by the keyStoreDir)
accountFileFormat = "pem"       # The storage format of account file (Default is "pem", "p12" as an option)

# accountAddress = ""           # The transactions sending account address
                                # Default is a randomly generated account
                                # The randomly generated account is stored in the path specified by the keyStoreDir

# password = ""                 # The password used to load the account file

[threadPool]
# threadPoolSize = "16"         # The size of the thread pool to process message callback
                                            # Default is the number of cpu cores

配置项详细说明参考这里

重要

控制台说明

  • 当控制台配置文件在一个群组内配置多个节点连接时,由于群组内的某些节点在操作过程中可能退出群组,因此控制台轮询节点查询时,其返回信息可能不一致,属于正常现象。建议使用控制台时,配置一个节点或者保证配置的节点始终在群组中,这样在同步时间内查询的群组内信息保持一致。

3. 启动控制台

在节点正在运行的情况下,启动控制台:

$ ./start.sh
# 输出下述信息表明启动成功
=====================================================================================
Welcome to FISCO BCOS console(3.0.0-rc3)!
Type 'help' or 'h' for help. Type 'quit' or 'q' to quit console.
 ________ ______  ______   ______   ______       _______   ______   ______   ______
|        |      \/      \ /      \ /      \     |       \ /      \ /      \ /      \
| $$$$$$$$\$$$$$|  $$$$$$|  $$$$$$|  $$$$$$\    | $$$$$$$|  $$$$$$|  $$$$$$|  $$$$$$\
| $$__     | $$ | $$___\$| $$   \$| $$  | $$    | $$__/ $| $$   \$| $$  | $| $$___\$$
| $$  \    | $$  \$$    \| $$     | $$  | $$    | $$    $| $$     | $$  | $$\$$    \
| $$$$$    | $$  _\$$$$$$| $$   __| $$  | $$    | $$$$$$$| $$   __| $$  | $$_\$$$$$$\
| $$      _| $$_|  \__| $| $$__/  | $$__/ $$    | $$__/ $| $$__/  | $$__/ $|  \__| $$
| $$     |   $$ \\$$    $$\$$    $$\$$    $$    | $$    $$\$$    $$\$$    $$\$$    $$
 \$$      \$$$$$$ \$$$$$$  \$$$$$$  \$$$$$$      \$$$$$$$  \$$$$$$  \$$$$$$  \$$$$$$

=====================================================================================

4. 启动脚本说明

4.1 查看当前控制台版本

./start.sh --version
console version: 3.0.0-rc3

4.2 账户使用方式

4.2.1 控制台加载私钥

控制台提供账户生成脚本get_account.sh(脚本用法请参考账户管理文档,生成的的账户文件在accounts目录下,控制台加载的账户文件必须放置在该目录下。 控制台启动方式有如下几种:

./start.sh
./start.sh group0
./start.sh group0 -pem pemName
./start.sh group0 -p12 p12Name
4.2.2 默认启动

使用控制台配置文件指定的默认群组号启动。

./start.sh

注意: 控制台启动未指定私钥账户时,会尝试从account目录下加载一个可用的私钥账户用于发送交易,加载失败则会创建一个新的PEM格式的账户文件,将其保存在account目录下。

4.2.3 指定群组名启动

使用命令行指定的群组名启动。

./start.sh group0
4.2.4 使用PEM格式私钥文件启动
  • 使用指定的pem文件的账户启动,输入参数:群组号、-pem、pem文件路径
./start.sh group0 -pem accounts/0xebb824a1122e587b17701ed2e512d8638dfb9c88.pem
4.2.5 使用PKCS12格式私钥文件启动
  • 使用指定的p12文件的账户,需要输入密码,输入参数:群组号、-p12、p12文件路径
./start.sh group0 -p12 accounts/0x5ef4df1b156bc9f077ee992a283c2dbb0bf045c0.p12
Enter Export Password:

注意: 控制台启动时加载p12文件出现下面报错:

exception unwrapping private key - java.security.InvalidKeyException: Illegal key size

可能是Java版本的原因,参考解决方案:https://stackoverflow.com/questions/3862800/invalidkeyexception-illegal-key-size

Java合约生成工具

控制台提供一个专门的生成Java合约工具,方便开发者将Solidity和wbc-liquid合约文件编译为Java合约文件。

当前合约生成工具支持Solidity的自动编译并生成Java文件、支持指定wbc-liquid编译后的WASM文件以及ABI文件生成Java文件。

Solidity合约使用

$ bash contract2java.sh solidity -h 
usage: contract2java.sh <solidity|liquid> [OPTIONS...]
 -h,--help
 -l,--libraries <arg>   [Optional] Set library address information built
                        into the solidity contract
                        eg:
                        --libraries lib1:lib1_address lib2:lib2_address
 -o,--output <arg>      [Optional] The file path of the generated java
                        code, default is contracts/sdk/java/
 -p,--package <arg>     [Optional] The package name of the generated java
                        code, default is com
 -s,--sol <arg>         [Optional] The solidity file path or the solidity
                        directory path, default is contracts/solidity/

参数详细:

  • package: 生成Java文件的包名。
  • sol: (可选)solidity文件的路径,支持文件路径和目录路径两种方式,参数为目录时将目录下所有的solidity文件进行编译转换。默认目录为contracts/solidity
  • output: (可选)生成Java文件的目录,默认生成在contracts/sdk/java目录。

wbc-liquid合约使用

$ bash contract2java.sh liquid -h
usage: contract2java.sh <solidity|liquid> [OPTIONS...]
 -a,--abi <arg>       [Required] The ABI file path of WBC-Liquid contract.
 -b,--bin <arg>       [Required] The binary file path of WBC-Liquid contract.
 -h,--help
 -o,--output <arg>    [Optional] The file path of the generated java code,
                      default is contracts/sdk/java/
 -p,--package <arg>   [Optional] The package name of the generated java
                      code, default is com
 -s,--sm-bin <arg>    [Required] The SM binary file path of WBC-Liquid
                      contract.

参数详细:

  • abi:(必选)WBC-Liquid合约ABI文件的路径,在使用cargo liquid build命令之后生成在target文件夹中。
  • bin:(必选)WBC-Liquid合约wasm bin文件的路径,在使用cargo liquid build命令之后生成在target文件夹中。
  • package:(可选)生成Java文件的包名,默认为org
  • sm-bin:(必选)WBC-Liquid合约wasm sm bin文件的路径,在使用cargo liquid build -g命令之后生成在target文件夹中。

使用

$ cd ~/fisco/console

# 生成Solidity合约的Java代码
$ bash contract2java.sh solidity -p org.com.fisco

# 生成WBC-Liquid合约的Java代码
$ bash contract2java.sh liquid -p org.com.fisco -b ./contracts/liquid/asset/asset.wasm -a ./contracts/liquid/asset/asset.abi -s ./contracts/liquid/asset/asset_gm.wasm 

运行成功之后,将会在console/contracts/sdk目录生成java、abi和bin目录,如下所示。

|-- abi # 编译生成的abi目录,存放solidity合约编译的abi文件
|   |-- HelloWorld.abi
|   |-- KVTable.abi
|   |-- KVTableTest.abi
|-- bin # 编译生成的bin目录,存放solidity合约编译的bin文件
|   |-- HelloWorld.bin
|   |-- KVTable.bin
|   |-- KVTableTest.bin
|-- java  # 存放编译的包路径及Java合约文件
|   |-- org
|       |-- com
|           |-- fisco
|               |-- HelloWorld.java # Solidity编译的HelloWorld Java文件
|               |-- KVTable.java    # Solidity编译的KV存储接口合约 Java文件
|               |-- KVTableTest.java  # Solidity编译的KVTableTest Java文件
|               |-- Asset.java  # wbc-liquid生成的Asset文件

Java目录下生成了org/com/fisco/包路径目录。包路径目录下将会生成Java合约文件HelloWorld.javaKVTableTest.javaKVTable.javaAsset.java。其中HelloWorld.javaKVTableTest.javaAsset.java是Java应用所需要的Java合约文件。