控制台

控制台是WeCross重要的交互式客户端工具，它通过WeCross-Java-SDK与WeCross 跨链代理建立连接，实现对跨链资源的读写访问请求。控制台拥有丰富的命令，包括获取跨链资源列表，查询资源状态，以及所有的JSON-RPC接口命令。

控制台命令

控制台命令可分为两类，普通命令和交互式命令。

普通命令

普通命令由两部分组成，即指令和指令相关的参数：

  • 指令: 指令是执行的操作命令，包括获取跨链资源列表，查询资源状态指令等，其中部分指令调用JSON-RPC接口，因此与JSON-RPC接口同名。 使用提示： 指令可以使用tab键补全，并且支持按上下键显示历史输入指令。
  • 指令相关的参数: 指令调用接口需要的参数，指令与参数以及参数与参数之间均用空格分隔。与JSON-RPC接口同名命令的输入参数和获取信息字段的详细解释参考JSON-RPC API。

交互式命令

WeCross控制台为了方便用户使用，还提供了交互式的使用方式，比如将跨链资源标识赋值给变量，初始化一个类，并用.command的方式访问方法。 详见：交互式命令

常用命令链接

普通命令

交互式命令

快捷键

  • Ctrl+A：光标移动到行首
  • Ctrl+E：光标移动到行尾
  • Ctrl+R：搜索输入的历史命令
  • ↑： 向前浏览历史命令
  • ↓： 向后浏览历史命令
  • tab： 自动补全，支持命令、变量名、资源名、账户名以及其它固定参数的补全

控制台响应

当发起一个控制台命令时，控制台会获取命令执行的结果，并且在终端展示执行结果，执行结果分为2类：

  • 正确结果: 命令返回正确的执行结果，以字符串或是json的形式返回。
  • 错误结果: 命令返回错误的执行结果，以字符串或是json的形式返回。
  • 状态码: 控制台的命令调用JSON-RPC接口时，状态码参考这里。

控制台配置与运行

重要

前置条件：部署WeCross请参考 快速部署。

获取控制台

可通过脚本download_console.sh获取控制台。

  1. cd ~ && mkdir -p wecross && cd wecross
  2. # 获取控制台
  3. bash <(curl -sL https://github.com/WeBankFinTech/WeCross-Console/releases/download/resources/download_console.sh)

执行成功后，会生成WeCross-Console目录，结构如下：

  1. ├── apps
  2. │   └── wecross-console-xxx.jar  # 控制台jar包
  3. ├── conf
  4. │   ├── application-sample.toml   # 配置示例文件
  5. │   └── log4j2.xml           # 日志配置文件
  6. ├── lib                      # 相关依赖的jar包目录
  7. ├── logs                     # 日志文件
  8. └── start.sh                 # 启动脚本

配置控制台

控制台配置文件为 conf/application-toml，启动控制台前需配置

  1. cd ~/wecross/WeCross-Console
  2. # 拷贝配置sample
  3. cp conf/application-sample.toml conf/application.toml
  5. # 拷贝连接router所需的TLS证书，从生成的routers-payment/cert/sdk目录下拷贝
  6. cp ~/wecross/routers-payment/cert/sdk/* conf/ # 包含：ca.crt、node.nodeid、ssl.crt、ssl.key
  8. # 配置
  9. vim conf/application.toml

配置控制台与某个router的连接

  1. [connection]
  2.     server =  '127.0.0.1:8250' # 对应router的ip和rpc端口
  3.     sslKey = 'classpath:ssl.key'
  4.     sslCert = 'classpath:ssl.crt'
  5.     caCert = 'classpath:ca.crt'

启动控制台

在WeCross已经开启的情况下，启动控制台

  1. cd ~/wecross/WeCross-Console
  2. bash start.sh
  3. # 输出下述信息表明启动成功
  4. =============================================================================================
  5. Welcome to WeCross console(1.0.0-rc4)!
  6. Type 'help' or 'h' for help. Type 'quit' or 'q' to quit console.
  8. =============================================================================================

普通命令

以下所有跨链资源相关命令的执行结果以实际配置为准，此处只是示例。

help

输入help或者h，查看控制台所有的命令。

  1. [WeCross]> help
  2. ---------------------------------------------------------------------------------------------
  3. quit                               Quit console.
  4. supportedStubs                     List supported stubs of WeCross router.
  5. listAccounts                       List all accounts stored in WeCross router.
  6. listLocalResources                 List local resources configured by WeCross server.
  7. listResources                      List all resources including remote resources.
  8. status                             Check if the resource exists.
  9. detail                             Get resource information.
  10. call                               Call constant method of smart contract.
  11. sendTransaction                    Call non-constant method of smart contract.
  12. callTransaction                    Call constant method of smart contract during transaction.
  13. execTransaction                    Call non-constant method of smart contract during transaction.
  14. startTransaction                   Start a 2pc transaction.
  15. commitTransaction                  Commit a 2pc transaction.
  16. rollbackTransaction                Rollback a 2pc transaction.
  17. getTransactionInfo                 Get info of specified transaction.
  18. getTransactionIDs                  Get transaction ids of 2pc.
  19. bcosDeploy                         Deploy contract in BCOS chain.
  20. bcosRegister                       Register contract abi in BCOS chain.
  21. fabricInstall                      Install chaincode in fabric chain.
  22. fabricInstantiate                  Instantiate chaincode in fabric chain.
  23. fabricUpgrade                      Upgrade chaincode in fabric chain.
  24. genTimelock                        Generate two valid timelocks.
  25. genSecretAndHash                   Generate a secret and its hash.
  26. newHTLCProposal                    Create a htlc transfer proposal .
  27. checkTransferStatus                Check htlc transfer status by hash.
  28. WeCross.getResource                Init resource by path and account name, and assign it to a custom variable.
  29. [resource].[command]               Equal to: command [path] [account name].
  31. ---------------------------------------------------------------------------------------------

注：

  • help显示每条命令的含义是：命令 命令功能描述
  • 查看具体命令的使用介绍说明，输入命令 -h或—help查看。例如：
  1. [WeCross]> detail -h
  2. ---------------------------------------------------------------------------------------------
  3. Get the resource information
  4. Usage: detail [path]
  5. ---------------------------------------------------------------------------------------------

supportedStubs

显示router当前支持的插件列表。

  1. [WeCross]> supportedStubs
  2. [BCOS2.0, GM_BCOS2.0, Fabric1.4]

listAccounts

显示所有已配置的账户列表。

  1. name: fabric_user1, type: Fabric1.4
  2. name: fabric_default_account, type: Fabric1.4
  3. name: bcos_user1, type: BCOS2.0
  4. name: bcos_sender, type: BCOS2.0
  5. name: bcos_default_account, type: BCOS2.0
  6. total: 5

listLocalResources

显示router配置的跨链资源。

  1. [WeCross]> listLocalResources
  2. path: payment.bcos.htlc, type: BCOS2.0, distance: 0
  3. path: payment.bcos.HelloWeCross, type: BCOS2.0, distance: 0
  4. total: 2

listResources

查看WeCross跨链代理本地配置的跨链资源和所有的远程资源。

  1. [WeCross]> listResources
  2. path: payment.bcos.htlc, type: BCOS2.0, distance: 0
  3. path: payment.bcos.HelloWeCross, type: BCOS2.0, distance: 0
  4. path: payment.fabric.htlc, type: Fabric1.4, distance: 1
  5. path: payment.fabric.abac, type: Fabric1.4, distance: 1
  6. total: 4

status

判断跨链资源是否存在。

参数：

  • path：跨链资源标识。
  1. [WeCross]> status payment.bcos.HelloWeCross
  2. exists

detail

查看跨链资源的详细信息。

参数：

  • path：跨链资源标识。
  1. [WeCross]> detail   payment.bcos.HelloWorld
  2. ResourceDetail{
  3.  path='payment.bcos.HelloWorld',
  4.  distance=0',
  5.  stubType='BCOS2.0',
  6.  properties={
  7.   BCOS_PROPERTY_CHAIN_ID=1,
  8.   BCOS_PROPERTY_GROUP_ID=1
  9.  },
  10.  checksum='c77f0ac3ead48d106d357ffe0725b9761bd55d3e27edd8ce669ad8b470a27bc8'
  11. }
  13. [WeCross]> detail  payment.fabric.sacc
  14. ResourceDetail{
  15.  path='payment.fabric.sacc',
  16.  distance=1',
  17.  stubType='Fabric1.4',
  18.  properties={
  19.   ORG_NAMES=[
  20.    Org1,
  21.    Org2
  22.   ],
  23.   PROPOSAL_WAIT_TIME=300000,
  24.   CHAINCODE_VERSION=1.0,
  25.   CHANNEL_NAME=mychannel,
  26.   CHAINCODE_NAME=sacc
  27.  },
  28.  checksum='058b239a9f10dc2b1154e28910861053c376be61cbbfd539b71f354b85ed309b'
  29. }

call

调用智能合约的方法，不涉及状态的更改，不发交易。

参数：

  • path：跨链资源标识。
  • accountName：交易签名账户，router上配置的账户名（listAccounts命令可查询）。
  • method：合约方法名。
  • args：参数列表。
  1. [WeCross]> call payment.bcos.HelloWeCross bcos_user1 get
  2. Result: [Talk is cheap, Show me the code]

sendTransaction

调用智能合约的方法，会更改链上状态，需要发交易。

参数：

  • path：跨链资源标识。
  • accountName：交易签名账户，router上配置的账户名。
  • method：合约方法名。
  • args：参数列表。
  1. [WeCross]> sendTransaction payment.bcos.HelloWeCross bcos_user1 set hello wecross
  2. Txhash  : 0x66f94d387df2b16bea26e6bcf037c23f0f13db28dc4734588de2d57a97051c54
  3. BlockNum: 2219
  4. Result  : [hello, wecross]

bcosDepoly

FISCO BCOS 合约部署命令，成功返回部署的合约地址，失败返回错误描述

参数：

  • Path: 跨链资源标示，用于标记部署的合约资源
  • Account: 部署合约发送交易的账户
  • Source file path: 部署的合约路径，支持绝对路径/相对路径
  • Class Name: 部署的合约名
  • Verseion: 部署合约版本号，注意: 同一合约版本号唯一，再次部署相同的版本号会失败

示例：

  1. [WeCross]> bcosDeploy payment.my_bcos_chain.HelloWorld my_bcos_account contracts/solidity/HelloWorld.sol HelloWorld 1.0
  2. Result: 0x79a178e71dc77fbccd31d464c114c95403a31e00

bcosRegister

FISCO BCOS 注册已有合约为跨链资源，成功返回Success，失败返回错误描述

参数：

  • Path: 跨链资源标示，用于标记注册的合约资源
  • Account: 注册合约发送交易的账户
  • Source file path: 合约的ABI文件路径或者合约源码路径
  • Contract address: 注册的合约地址
  • Version: 合约版本号，注意: 同一部署合约版本号唯一，再次部署相同版本号的合约会失败

示例：

  1. [WeCross]> bcosRegister payment.my_bcos_chain.HelloWorld my_bcos_account contracts/solidity/HelloWorld.sol 0x2c8595f82dc930208314030abc6f5c4ddbc8864f v1.0
  2. Result: Success

fabricInstall

Fabric 安装链码命令，安装后需fabricInstantiate来启动链码

参数：

  • path：跨链资源标识。
  • account：被安装链码的endorser所属机构的admin账户
  • orgName：被安装链码的endorser所属的机构
  • sourcePath：链码工程所在目录，支持绝对路径和WeCross-Console的conf目录内的相对路径
  • version：指定一个版本，fabricInstantiate时与此版本对应
  • language：指定一个链码语言，支持GO_LANG和JAVA
  1. [WeCross]> fabricInstall payment.fabric.sacc fabric_admin_org1 Org1 contracts/chaincode/sacc 1.0 GO_LANG
  2. Result: Success
  3. [WeCross]> fabricInstall payment.fabric.sacc fabric_admin_org2 Org2 contracts/chaincode/sacc 1.0 GO_LANG
  4. Result: Success

fabricInstantiate

Fabric 启动（实例化）已安装的链码。此步骤前需先用fabricInstall向指定机构安装链码。

参数：

  • path：跨链资源标识。
  • account：指定一个发交易的账户
  • orgNames：链码被安装的的机构列表
  • sourcePath：链码工程所在目录，支持绝对路径和WeCross-Console的conf目录内的相对路径
  • version：指定一个版本，与fabricInstall时的版本对应
  • language：指定一个链码语言，支持GO_LANG和JAVA
  • policy：指定背书策略文件，设置default为OR所有endorser
  • initArgs：链码初始化参数
  1. [WeCross]> fabricInstantiate payment.fabric.sacc fabric_admin ["Org1","Org2"] contracts/chaincode/sacc 1.0 GO_LANG default ["a","10"]
  2. Result: Instantiating... Please wait and use 'listResources' to check. See router's log for more information.

启动时间较长（1min左右），可用listResources查看是否已启动，若长时间未启动，可查看router的日志进行排查。

fabricUpgrade

Fabric 升级已启动的链码逻辑，不改变已上链的数据。此步骤前需先用fabricInstall向指定机构安装另一个版本的链码。

参数：

  • path：跨链资源标识。
  • account：指定一个发交易的账户
  • orgNames：链码被安装的的机构列表
  • sourcePath：链码工程所在目录，支持绝对路径和WeCross-Console的conf目录内的相对路径
  • version：指定一个版本，与fabricInstall时的版本对应
  • language：指定一个链码语言，支持GO_LANG和JAVA
  • policy：指定背书策略文件，设置default为OR所有endorser
  • initArgs：链码初始化参数
  1. [WeCross]> fabricUpgrade payment.fabric.sacc fabric_admin ["Org1","Org2"] contracts/chaincode/sacc 2.0 GO_LANG default ["a","10"]
  2. Result: Upgrading... Please wait and use 'detail' to check the version. See router's log for more information.

升级时间较长（1min左右），可用detail payment.fabric.sacc查看版本号，若长时间升级完成，可查看router的日志进行排查。

genTimelock

跨链转账辅助命令，根据时间差生成两个合法的时间戳。

参数：

  • interval：时间间隔
  1. [WeCross]> genTimelock  300
  2. timelock0: 1586917289
  3. timelock1: 1586916989

genSecretAndHash

跨链转账辅助命令，生成一个秘密和它的哈希。

  1. [WeCross]> genSecretAndHash
  2. hash  : 66ebd11ec6cc289aebe8c0e24555b1e58a5191410043519960d26027f749c54f
  3. secret: afd1c0f9c2f8acc2c1ed839ef506e8e0d0b4636644a889f5aa8e65360420d2a9

newHTLCProposal

新建一个基于哈希时间锁合约的跨链转账提案，该命令由两条链的资金转出方分别执行。

参数：

  • path：跨链转账资源标识。
  • accountName：资产转出者在router上配置的账户名。
  • args：提案信息，包括两条链的转账信息。
    • hash： 唯一标识，提案号，
    • secret： 提案号的哈希原像
    • role： 身份，发起方-true，参与方-false。发起方需要传入secret，参与方secret传null。
    • sender0：发起方的资金转出者在对应链上的地址
    • receiver0：发起方的资金接收者在对应链上的地址
    • amount0：发起方的转出金额
    • timelock0：发起方的超时时间
    • sender1：参与方的资金转出者在对应链上的地址
    • receiver1：参与方的资金接收者在对应链上的地址
    • amount1：参与方的转出金额
    • timelock1：参与方的超时时间，小于发起方的超时时间
  1. [WeCross]> newHTLCProposal payment.bcos.htlc bcos_sender 88b6cea9b5ece573c6c35cb3f1a2237bf380dfbbf9155b82d5816344cdac0185 null false Admin@org1.example.com User1@org1.example.com 200 2000010000 0x55f934bcbe1e9aef8337f5551142a442fdde781c 0x2b5ad5c4795c026514f8317c7a215e218dccd6cf 100 2000000000
  3. Txhash: 0x244d302382d03985eebcc1f7d95d0d4eef7ff2b3d528fdf7c93effa94175e921
  4. BlockNum: 2222
  5. Result: [create a htlc transfer proposal successfully]

checkTransferStatus

根据提案号（Hash）查询htlc转账状态。

参数：

  • path：跨链资源标识。
  • accountName：交易签名账户，router上配置的账户名。
  • method：合约方法名。
  • hash：转账提案号。
  1. [WeCross]> checkTransferStatus payment.bcos.htlc bcos_sender dcbdf73ee6fdbe6672142c7776c2d21ff7acc6f0d61975e83c3b396a364bee93
  2. status: succeeded!

startTransaction

写接口，开始两阶段事务

参数：

  • transactionID：事务ID，类型为字符串，由用户指定，作为事务的唯一标识，后续所有的事务资源操作都必须指定该事务ID
  • account_1 … account_n：用于开始事务的账号列表，由于两阶段事务可能跨越多种区块链，多种区块链会使用不同类型的账号，因此开始事务时，需要为每种区块链指定至少一个账号，WeCross会使用相应类型的账号向链上发送开始事务交易，该账号列表仅用于开始事务，事务开始后，可以使用该账号列表以外的账号来发送事务交易
  • path_1 … path_n：参与事务的资源路径列表，路径列表中的资源会被本次事务锁定，锁定后仅限本事务相关的交易才能对这些资源发起写操作，非本次事务的所有写操作都会被拒绝
  1. [WeCross]> startTransaction 0001 bcos_user1 fabric_user1 payment.bcos.2pc payment.fabric.2pc
  2. Result: success!

execTransaction

写接口，发起事务交易

参数：

  • path：资源路径
  • account：交易账号
  • transactionID：事务ID，该资源正在参与事务的ID
  • seq：事务编号，本次操作的编号，每次事务交易唯一，要求递增
  • method：接口名，同sendTransaction。需要注意的是，该接口需要在合约中配套以_revert结尾的回滚接口。
  • args：参数，同sendTransaction
  1. [WeCross]> execTransaction payment.bcos.2pc bcos_user1 0001 1 newEvidence key1 evidence1
  2. Result: [true]
  4. [WeCross]> execTransaction payment.fabric.2pc fabric_user1 0001 1 newEvidence key1 evidence1
  5. Result: [newEvidence success]

callTransaction

读接口，查询事务中的数据

参数：

  • path：资源路径
  • account：交易账号
  • transactionID：事务ID，该资源正在参与事务的ID
  • method：接口名，同sendTransaction。
  • args：参数，同sendTransaction
  1. [WeCross]> callTransaction payment.bcos.2pc bcos_user1 0002 queryEvidence key1
  2. Result: [evidence1]

commitTransaction

写接口，提交事务，确认事务执行过程中所有的变动

参数：

  • transactionID：事务ID，待提交事务的ID
  • account_1 … account_n：用于提交事务的账号列表，由于两阶段事务可能跨越多种区块链，多种区块链会使用不同类型的账号，需要为每种区块链指定至少一个账号，WeCross会使用相应类型的账号向链上发送提交事务交易
  • path_1 … path_n：用于提交事务的路径列表
  1. [WeCross]> commitTransaction 0001 bcos_user1 fabric_user1 payment.bcos.2pc payment.fabric.2pc

rollbackTransaction

写接口，撤销本次事务的所有变更时

参数：

  • transactionID：事务ID，待回滚事务的ID
  • account_1 … account_n：用于回滚事务的账号列表，由于两阶段事务可能跨越多种区块链，多种区块链会使用不同类型的账号，需要为每种区块链指定至少一个账号，WeCross会使用相应类型的账号向链上发送回滚事务交易
  • path_1 … path_n：用于回滚事务的路径列表
  1. # 查看开始前的状态
  2. [WeCross]> call payment.bcos.2pc bcos_user1 queryEvidence key2
  3. Result: []
  5. # 开始事务
  6. [WeCross]> startTransaction 0002 bcos_user1 fabric_user1 payment.bcos.2pc payment.fabric.2pc
  7. Result: success!
  9. # 执行事务
  10. [WeCross]> execTransaction payment.bcos.2pc bcos_user1 0002 1 newEvidence key2 evidence2
  11. Result: [true]
  13. # 读事务数据
  14. [WeCross]> callTransaction payment.bcos.2pc bcos_user1 0002 queryEvidence key2
  15. Result: [evidence2]
  17. # 回滚事务
  18. [WeCross]> rollbackTransaction 0002 bcos_user1 fabric_user1 payment.bcos.2pc payment.fabric.2pc
  19. Result: success!
  21. # 查看事务回滚后的状态，和开始前保持一致
  22. [WeCross]> call payment.bcos.2pc bcos_user1 queryEvidence key2
  23. Result: []

getTransactionInfo

读接口，查询事务信息

参数：

  • transactionID：事务ID，待提交事务的ID
  • account_1 … account_n：如果涉及多条链需要多个账户
  • path_1 … path_n：参与事务的资源路径列表
  1. [WeCross]> getTransactionInfo 0001 bcos_user1 fabric_user1 payment.bcos.2pc payment.fabric.2pc
  2. XATransactionInfo{
  3.  transactionID='0001',
  4.  status=1,
  5.  startTimestamp=1596962127015,
  6.  commitTimestamp=1596962353724,
  7.  rollbackTimestamp=0,
  8.  paths=[
  9.   payment.fabric.2pc,
  10.   payment.bcos.2pc
  11.  ],
  12.  transactionSteps=[
  13.   XATransactionStep{
  14.    seq=1,
  15.    contract='0xd6cd8179b796f0fc04718364c232723833b8ca59',
  16.    path='payment.bcos.2pc',
  17.    timestamp='1596962287683',
  18.    func='newEvidence(string,
  19.    string)',
  20.    args='0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000046b65793100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000965766964656e6365310000000000000000000000000000000000000000000000'
  21.   },
  22.   XATransactionStep{
  23.    seq=2,
  24.    contract='null',
  25.    path='payment.fabric.2pc',
  26.    timestamp='1596962314',
  27.    func='newEvidence',
  28.    args='{
  29.     "args":[
  30.      "key1",
  31.      "evidence1"
  32.     ]
  33.    }'
  34.   }
  35.  ]
  36. }

getTransactionIDs

读接口，查询链上的事务ID

参数：

  • account：交易账户
  • path：指定需要查询的链
  • option：选项。0全部事务，1已完成的事务，2未完成的事务
  1. [WeCross]> getTransactionIDs payment.bcos.2pc bcos_user1 0
  2. Result: [0001, 0002]
  4. [WeCross]> getTransactionIDs payment.bcos.2pc bcos_user1 1
  5. Result: [0001]
  7. [WeCross]> getTransactionIDs payment.bcos.2pc bcos_user1 2
  8. Result: [0002]

交互式命令

WeCross.getResource

WeCross控制台提供了一个资源类，通过方法getResource来初始化一个跨链资源实例，并且赋值给一个变量。 这样调用同一个跨链资源的不同UBI接口时，不再需要每次都输入跨链资源标识。

  1. # myResource 是自定义的变量名
  2. [WeCross]> myResource = WeCross.getResource payment.bcos.HelloWeCross bcos_user1
  4. # 还可以将跨链资源标识赋值给变量，通过变量名来初始化一个跨链资源实例
  5. [WeCross]> path = payment.bcos.HelloWeCross
  7. [WeCross]> myResource = WeCross.getResource path bcos_user1

[resource].[command]

当初始化一个跨链资源实例后，就可以通过.command的方式，调用跨链资源的UBI接口。

  1. # 输入变量名，通过tab键可以看到能够访问的所有命令
  2. [WeCross]> myResource.
  3. myResource.call              myResource.status
  4. myResource.detail            myResource.sendTransaction

status

  1. [WeCross]> myResource.status
  2. exists

detail

  1. [WeCross]> myResource.detail
  2. ResourceDetail{
  3.  path='payment.bcos.HelloWeCross',
  4.  distance=0',
  5.  stubType='BCOS2.0',
  6.  properties={
  7.   BCOS_PROPERTY_CHAIN_ID=1,
  8.   BCOS_PROPERTY_GROUP_ID=1,
  9.   HelloWeCross=0x9bb68f32a63e70a4951d109f9566170f26d4bd46
  10.  },
  11.  checksum='0x888d067b77cbb04e299e675ee4b925fdfd60405241ec241e845b7e41692d53b1'
  12. }

call

  1. [WeCross]> myResource.call get
  2. Result: [hello, wecross]

sendTransaction

  1. [WeCross]> myResource.sendTransaction set hello world
  2. Txhash  : 0x616a55a7817f843d81f8c7b65449963fc2b7a07398b853829bf85b2e1261516f
  3. BlockNum: 2224
  4. Result  : [hello, world]