3. 权限管理

3.1. 合约访问控制列表ACL

ACL（Access Control List）是XuperChain提供的重要的权限管理方法，其主要对于合约方法的读写做控制，包括系统合约和用户合约。

如果把合约账号当作一家股份制公司，那么ACL便是公司股东投票的机制，ACL可以规定合约账号背后各“股东”账号的权重，只有当“股东”签名的权重之和大于设定阈值时操作才会有效地进行。

XuperChain 中ACL配置格式如下：

  1. {
  2.     “pm”: {
  3.         “rule”: 1,              # rule=1表示签名阈值策略，rule=2表示AKSet签名策略
  4.         “acceptValue”: 0.6      # acceptValue为签名需达到的阈值
  5.     },
  6.     “aksWeight”: {              # aksWeight里规定了每个地址对应账号签名的权重
  7.         “AK1”: 0.3,
  8.         “AK2”: 0.3
  9.     }
  10. }

了解了访问控制列表的概念，下面我们会进一步详细介绍ACL的细节。

3.1.1. 合约账号创建

XuperChain的客户端工具提供了新建账号的功能，基本用法如下：

  1. xchain-cli account new —desc account.des

这里的 account.des 就是创建账号所需要的配置了，内容如下：

  1. {
  2.     “module_name”: “xkernel”,
  3.     “method_name”: “NewAccount”,
  4.     “contract_name”: “$acl”,
  5.     “args” : {
  6.         “account_name”: “1111111111111111”,  # 说明：账号名称是16位数字组成的字符串
  7.         # acl 中的内容注意转义
  8.         “acl”: “{\”pm\”: {\”rule\”: 1,\”acceptValue\”: 0.6},\”aksWeight\”: {\”AK1\”: 0.3,\”AK2\”: 0.3}}”
  9.     }
  10. }

命令运行后就会调用xchain的系统合约功能 NewAccount 创建一个名为 XC1111111111111111@xuper （如果链名字为xuper）的账号

除了上述方法，我们还提供了一个比较简易的方式来创建合约账号，命令如下：

  1. xchain-cli account new —account 1111111111111111 # 16位数字组成的字符串

上述命令也会创建一个名为 XC1111111111111111@xuper 的账号，由于我们没有制定ACL的具体内容，其ACL被赋值为默认状态，即背后有权限的账号只有当前节点上默认账号一个（地址默认位于 data/keys/address）。

重要

创建合约账号的操作需要提供手续费，需要按照命令行运行结果给出的数值，添加一个不小于它的费用（使用 –fee 参数）。

3.1.2. 合约账号基本操作

1. 查询账号ACL

XuperChain的客户端工具提供了ACL查询功能，只需如下命令。

  1. ./bin/xchain-cli acl query —account XC1111111111111111@xuper # account参数为合约账号名称

查询合约账号ACL

查询合约账号ACL

2. 查询账号余额

合约账号查询余额和普通账号类似，只是命令行的参数有些许变化。

  1. ./bin/xchain-cli account balance XC1111111111111111@xuper -H 127.0.0.1:37101

使用此命令即可查询 XC1111111111111111@xuper 的余额。

查询合约账号

查询合约账号余额

3. 修改账号ACL

修改ACL的配置和创建账号的配置类似。

  1. {
  2.     “module_name”: “xkernel”,
  3.     “method_name”: “SetAccountAcl”,  # 这里的方法有了变更
  4.     “contract_name”: “$acl”,
  5.     “args” : {
  6.         “account_name”: “XC1111111111111111@xuper”, #account_name在此处一定要写成XC…..@xuper的形式
  7.         # acl字段为要修改成的新ACL
  8.         “acl”: “{\”pm\”: {\”rule\”: 1,\”acceptValue\”: 0.6},\”aksWeight\”: {\”AK3\”: 0.3,\”AK4\”: 0.3}}”
  9.     }
  10. }

修改ACL的操作，需要符合当前ACL中设置的规则，即需要具有足够权重的账号签名。

需要新建文件添加需要签名的地址，默认acl文件路径是：./data/acl/addrs 。 ./data/acl/addrs 示例(这里为原ACL地址，即AK1,AK2)： XC9999999999999999@xuper/9LArZSMrrRorV7T6h5T32PVUrmdcYLbug XC9999999999999999@xuper/gLAdZSMtkforV7T6h5TA14VUrfdcYLbuy

我们首先生成一个多重签名的交易。

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

生成多重签名交易

成多重签名交易

这样就会生成一个默认为 tx.out 的文件，之后使用原ACL中的账号对其进行签名。

  1. ./bin/xchain-cli multisig sign —keys data/account/AK1 —output AK1.sign
  2. ./bin/xchain-cli multisig sign —keys data/account/AK2 —output AK2.sign

签名交易

签名交易

最后把生成的 tx.out 发出去。

  1. ./bin/xchain-cli multisig send —tx tx.out AK1.sign,AK2.sign AK1.sign,AK2.sign

发送交易

发送交易

至此便完成了ACL的修改。

重要

生成交易等操作中，会出现需要手续费的情况，需要按要求添加 –fee 参数。

重要

使用“简易”方式创建的合约账号，修改ACL生成交易时，需要添加节点账号的地址路径 –multiAddrs data/keys/address。

3.2. 合约方法 ACL

合约方法 ACL 允许某个合约方法只能被满足特定条件的账号调用。

合约方法 ACL 的设置也是通过多签来完成。

  1. 准备desc文件setMethodACL.desc

    1. {
    2.     "module_name": "xkernel",
    3.     "method_name": "SetMethodAcl",
    4.     "args" : {
    5.         "contract_name": "counter",
    6.         "method_name": "increase",
    7.         "acl": "{\"pm\": {\"rule\": 1,\"acceptValue\": 1.0},\"aksWeight\": {\"TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY\": 1}}"
    8.         }
    9. }

    参数说明：

    • module_name： 模块名称，用固定值xkernel

    • method_name ：方法名称，用固定值SetMethodAcl

    • contract_name：合约名称

    • method_name：合约方法名称

    • acl：合约方法的acl

  2. 准备 ACL 描述文件

    以使用 XC1111111111111111@xuper 部署的 counter 合约为例，合约账号 ACL 里 只有 1 个 AK，所以在data/acl/addrs中添加1行

    1. $ echo "XC1111111111111111@xuper/TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY" > data/acl/addrs

    如果合约账号 ACL 有多个 AK，按序添加即可。

  3. 生成交易并发送

    1. # 生成交易
    2. xchain-cli multisig gen --desc ./setMethodACL.desc --fee 1
    3. # 对交易签名
    4. xchain-cli multisig sign --output sign.out
    5. # 发送交易
    6. xchain-cli multisig send sign.out sign.out

  4. 查看合约方法ACL

    1. $ xchain-cli acl query --contract counter --method increase
    2. {
    3.     "pm": {
    4.         "rule": 1,
    5.         "acceptValue": 1
    6.     },
    7.     "aksWeight": {
    8.         "TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY": 1
    9.     }
    10. }
    11. confirmed

3.3. 平行链群组

平行链群组提供的是对某一条平行链的读权限和操作该权限的写权限的控制。平行链和群组是彼此相辅相成的概念，在创建平行链时，会根据输入创建该平行链的群组合约，用户后续可通过系统合约对群组进行修改。

重要

XuperChain需要与Xuper-Front联合使用才可以控制平行链的权限，该方案面向的是联盟链场景。单独的XuperChain进程，通过调用系统合约只能对主链群组相关Key进行修改，并不影响XuperChain节点的使用。具体可见 平行链、群组和CA中心 。

3.3.1. 平行链群组的创建

平行链群组的创建只能在平行链创建时发生。若在平行链参数中指定 group 参数，则平行链群组根据该参数创建，否则走默认模式，即平行链群组默认归合约发起节点拥有。

  1. // 平行链参数形式
  2. {
  3.     “name”:$Blockchain_Name, // 平行链名称
  4.     “data”:$Genesis_Configuration，// 平行链创世块配置
  5.     “group”:$Group_Configuration // 平行链群组配置，若缺省则为默认配置
  6. }

群组合约的参数如下。

  1. // 平行链群组参数形式
  2. {
  3.     “name”: $Blockchain_Name, // 平行链群组名称必须与平行链名称相同
  4.     “admin”: [$Admin_Addresses], // 管理者列表，管理者拥有写该群组合约的权限
  5.     “identities”: [$Identities_Address] // 查询者列表，查询者仅拥有读该群组合约的权限，若同时也为管理者，则也有写权限
  6. }

3.3.2. 平行链群组的修改

有平行链群组管理员身份的XuperChain节点和账户才可以对该平行链群组做修改。

  1. // group参数在-a后面键入，下面是更改hello链的例子
  2. ./bin/xchain-cli xkernel invoke ‘$parachain’ —method editGroup -a ‘{ “name”:”hello”,”admin”:”TeyyPLpp9L7QAcxHangtcHTu7HUZ6iydY;SmJG3rH2ZzYQ9ojxhbRCPwFiE9y6pD1Co;iYjtLcW6SVCiousAb5DFKWtWroahhEj4u”}’ —fee 1000

3.3.3. 平行链群组的查看

仅有平行链管理员身份或者平行链查询者身份的节点和账户才可以对该平行链群组做查询。

  1. // 下面是查看hello链群组信息的例子
  2. ./bin/xchain-cli xkernel query ‘$parachain’ —method getGroup -a ‘{“name”:”hello”}’