权限合约接口 · CITAHub Docs

CITA 的权限系统对账户的操作进行控制，并支持基于角色的权限管理。

账户相关信息查看账户概述。

权限系统概述

在权限系统中由合约地址来标识权限，控制的范围可细粒度到合约的函数级别。一个权限的属性包含：

可阅读的权限名称
目标合约地址
对应目标合约的函数签名

由此可表示三种类别的权限：

发交易：由系统内置的的合约地址标识，权限属性为空
创建合约：由系统内置的的合约地址标识，权限属性为空
调用合约：
- 内置的权限：由系统内置的合约地址标识，权限属性包含系统合约的地址和函数签名
- 账户自定义的权限：由账户创建权限时生成的合约地址标识，权限属性包含参数所表示的地址和函数签名

权限系统操作

使用权限系统可进行的一些操作如下：

创建权限：生成权限的标识，属性包含参数所表示的合约地址、函数签名及名称
更新权限：修改权限的属性
删除权限：删除权限
授予权限：授予账户权限
取消授权：撤销对目标账户某种权限

具体接口定义可查看权限系统接口。

权限系统配置

CITA 在起链的时候可以对权限系统进行配置，默认是关闭的（即没有权限检查）。有三个配置项：

checkCallPermission：表示对合约调用的权限进行检查
checkSendTxPermission：表示对发送交易的权限进行检查
checkCreateContractPermission：表示对创建合约的权限进行检查

注意：

这里的 checkCallPermission 与 JSON-RPC 中的 Call 并不同， JSON-RPC 中的 Call 是指对链上数据的查询，是读数据而非写数据。而这里的checkCallPermission 是指通过发送交易的方式调用合约接口，是指写数据的操作。

更多信息查看链级配置。

系统内置权限

账户可自定义权限，其中系统内置了几种权限（禁止对其进行删除操作），如下所示：

name	permission
`sendTx`	表示发交易权限
`createContract`	表示创建合约权限
`newPermission`	表示创建一个新的权限权限
`deletePermission`	表示删除一个权限权限
`updatePermission`	表示更新一个权限权限
`setAuth`	表示对账户进行授权权限
`cancelAuth`	表示对账户取消授权权限
`newRole`	表示创建一个新的角色权限
`deleteRole`	表示删除一个角色权限
`updateRole`	表示更新一个角色权限
`setRole`	表示对账户授予角色权限
`cancelRole`	表示对账户取消授予角色权限
`newGroup`	表示创建一个新组权限
`deleteGroup`	表示删除一个组权限
`updateGroup`	表示更新一个组权限
`newNode`	表示增加普通节点权限
`deleteNode`	表示删除节点权限
`updateNode`	表示更新节点权限
`accountQuota`	表示账户配额设置权限
`blockQuota`	表示块配额设置权限
`batchTx`	表示批量交易权限
`ermergencyBrake`	表示紧急制动权限
`quotaPrice`	表示设置 quotaPrice 权限
`version`	表示设置版本权限

对应地址信息可查看已使用地址列表。

使用示例

接下来的测试，用 [cita-cli] 命令行模式进行演示，操作类接口调用需要有相应的权限。

修改系统配置

通过以下命令生成配置文件（打开所有权限系统配置）：

$ bin/cita create \
    --super_admin "0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523" \
    --nodes "127.0.0.1:4000,127.0.0.1:4001,127.0.0.1:4002,127.0.0.1:4003" \
    --contract_arguments SysConfig.checkCallPermission=true SysConfig.checkSendTxPermission=true SysConfig.checkCreateContractPermission=true

启动链的接下来的步骤见运行 CITA 部分。接下来的测试，用 cita-cli 命令行模式（与交互式模式的命令是一致的）进行演示。

生成普通账户

参考生成账户。

部署合约

授予发交易和部署合约权限

由于设置了权限的检查开关，所有账户默认是没有发交易及创建合约的权限的。首先需要通过 superAdmin 对其授 sendTx 发送交易及 createContract 创建合约权限。

发送交易权限地址为 0xffffffffffffffffffffffffffffffffff021000，创建合约权限地址为 0xffffffffffffffffffffffffffffffffff021001

由超级管理员进行操作。调用 setAuthorizations接口。

$ cita-cli scm PermissionManagement setAuthorizations \
    --permissions '[ffffffffffffffffffffffffffffffffff021000,ffffffffffffffffffffffffffffffffff021001]' \
    --account 0x37d1c7449bfe76fe9c445e626da06265e9377601 \
    --private-key 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 3,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x8addbd232737efb41e2aa45b481fe578b93f4bfb8dd6a971aad5e7593c3c47d2",
    "status": "OK"
  }
}

查看 receipt 信息：

$ cita-cli rpc getTransactionReceipt \
    --hash 0x8addbd232737efb41e2aa45b481fe578b93f4bfb8dd6a971aad5e7593c3c47d2 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "blockHash": "0x5956727ccb1de4876be148ef6fa54c764544cfd78cdc48b083603b40fbb71b8b",
    "blockNumber": "0x14",
    "contractAddress": null,
    "cumulativeQuotaUsed": "0x27a38",
    "errorMessage": null,
    "quotaUsed": "0x27a38",
    "logs": [
      {
        "address": "0xffffffffffffffffffffffffffffffffff020006",
        "blockHash": "0x5956727ccb1de4876be148ef6fa54c764544cfd78cdc48b083603b40fbb71b8b",
        "blockNumber": "0x14",
        "data": "0x",
        "logIndex": "0x0",
        "topics": [
          "0xef79a70821e438468db437d5f7401aecaf406a2cba3c7e7fd4339ef895dbb97e",
          "0x00000000000000000000000037d1c7449bfe76fe9c445e626da06265e9377601",
          "0x000000000000000000000000ffffffffffffffffffffffffffffffffff021000"
        ],
        "transactionHash": "0x8addbd232737efb41e2aa45b481fe578b93f4bfb8dd6a971aad5e7593c3c47d2",
        "transactionIndex": "0x0",
        "transactionLogIndex": "0x0"
      },
      {
        "address": "0xffffffffffffffffffffffffffffffffff020006",
        "blockHash": "0x5956727ccb1de4876be148ef6fa54c764544cfd78cdc48b083603b40fbb71b8b",
        "blockNumber": "0x14",
        "data": "0x",
        "logIndex": "0x1",
        "topics": [
          "0xef79a70821e438468db437d5f7401aecaf406a2cba3c7e7fd4339ef895dbb97e",
          "0x00000000000000000000000037d1c7449bfe76fe9c445e626da06265e9377601",
          "0x000000000000000000000000ffffffffffffffffffffffffffffffffff021001"
        ],
        "transactionHash": "0x8addbd232737efb41e2aa45b481fe578b93f4bfb8dd6a971aad5e7593c3c47d2",
        "transactionIndex": "0x0",
        "transactionLogIndex": "0x1"
      }
    ],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000400001000000200000000000000000000020000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000001000000010000000000000100000000000000000000000000000000000000008800080000000000000000000000002000000000000000000000000000000000000",
    "root": null,
    "transactionHash": "0x8addbd232737efb41e2aa45b481fe578b93f4bfb8dd6a971aad5e7593c3c47d2",
    "transactionIndex": "0x0"
  }
}

授予权限成功。

部署合约

参考部署合约。

如果账户想要调用测试合约的接口，需要根据接口生成一个新的权限，然后由 admin 把权限赋予账户。

生成新的权限

由超级管理员进行操作

$ cita-cli scm PermissionManagement newPermission \
    --name 0000000000000000000000000000000000000000000000000000000060fe47b1 \
    --contracts '[5839153e0efe76efe0c974b728c4f49ca7ed75cc]' \
    --function-hashes '[60fe47b1]' \
    --private-key 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 3,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x239fb9c6121d6c512e4b8e3422da378e6d329c4d5073fd7b83ee67d28cc89565",
    "status": "OK"
  }
}

获取 receipt 信息：

$ cita-cli rpc getTransactionReceipt \
    --hash 0x239fb9c6121d6c512e4b8e3422da378e6d329c4d5073fd7b83ee67d28cc89565 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "blockHash": "0xea33ec74f7ce12fae0a6c5df4137d3234e120a8c6cfd2c557052184409729c98",
    "blockNumber": "0x282",
    "contractAddress": null,
    "cumulativeQuotaUsed": "0x2290fe",
    "errorMessage": null,
    "quotaUsed": "0x2290fe",
    "logs": [
      {
        "address": "0xca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee",
        "blockHash": "0xea33ec74f7ce12fae0a6c5df4137d3234e120a8c6cfd2c557052184409729c98",
        "blockNumber": "0x282",
        "data": "0x0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000010000000000000000000000005839153e0efe76efe0c974b728c4f49ca7ed75cc000000000000000000000000000000000000000000000000000000000000000160fe47b100000000000000000000000000000000000000000000000000000000",
        "logIndex": "0x0",
        "topics": [
          "0xb533e8b79dc7485ba7e4435e3395df911c1a3c767225941003d88a7812d216f7"
        ],
        "transactionHash": "0x239fb9c6121d6c512e4b8e3422da378e6d329c4d5073fd7b83ee67d28cc89565",
        "transactionIndex": "0x0",
        "transactionLogIndex": "0x0"
      },
      {
        "address": "0xffffffffffffffffffffffffffffffffff020005",
        "blockHash": "0xea33ec74f7ce12fae0a6c5df4137d3234e120a8c6cfd2c557052184409729c98",
        "blockNumber": "0x282",
        "data": "0x0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000010000000000000000000000005839153e0efe76efe0c974b728c4f49ca7ed75cc000000000000000000000000000000000000000000000000000000000000000160fe47b100000000000000000000000000000000000000000000000000000000",
        "logIndex": "0x1",
        "topics": [
          "0x792f7322d94960c6e90863b5aef39075ca54620cfa13a822081d733f79c48f91",
          "0x000000000000000000000000ca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee",
          "0x0000000000000000000000000000000000000000000000000000000060fe47b1"
        ],
        "transactionHash": "0x239fb9c6121d6c512e4b8e3422da378e6d329c4d5073fd7b83ee67d28cc89565",
        "transactionIndex": "0x0",
        "transactionLogIndex": "0x1"
      }
    ],
    "logsBloom": "0x00000000000000020000000000000000000000000000008000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000080000000000000000040000000000000000040000000000000000001000000000000000000000000000000000000000000000000008000000800000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000200000000000000000000000000000000000000000000000000000000000000000000100000000000000000000100000000000000000000000000000800000002000000000000100000000100000",
    "root": null,
    "transactionHash": "0x239fb9c6121d6c512e4b8e3422da378e6d329c4d5073fd7b83ee67d28cc89565",
    "transactionIndex": "0x0"
  }
}

从 logs[0] 中获得新权限的地址为 0xca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee

使用新权限

把新权限赋予测试账户

由超级管理员进行操作。

$ cita-cli scm PermissionManagement setAuthorization \
    --permission 0xca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee \
    --account 0x37d1c7449bfe76fe9c445e626da06265e9377601 \
    --private-key 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 3,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0xc088f083c8ac7d89bd7056d09629f59c1f67cd6c97120807cee782c8200402e1",
    "status": "OK"
  }
}

获取 receipt 信息：

$ cita-cli rpc getTransactionReceipt \
    --hash 0xc088f083c8ac7d89bd7056d09629f59c1f67cd6c97120807cee782c8200402e1 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "blockHash": "0xbaf441b79671f0333adf1511361d258dcc606b3ecc6c42ac04d7e31794e1726b",
    "blockNumber": "0x554",
    "contractAddress": null,
    "cumulativeQuotaUsed": "0x13587",
    "errorMessage": null,
    "quotaUsed": "0x13587",
    "logs": [
      {
        "address": "0xffffffffffffffffffffffffffffffffff020006",
        "blockHash": "0xbaf441b79671f0333adf1511361d258dcc606b3ecc6c42ac04d7e31794e1726b",
        "blockNumber": "0x554",
        "data": "0x",
        "logIndex": "0x0",
        "topics": [
          "0xef79a70821e438468db437d5f7401aecaf406a2cba3c7e7fd4339ef895dbb97e",
          "0x00000000000000000000000037d1c7449bfe76fe9c445e626da06265e9377601",
          "0x000000000000000000000000ca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee"
        ],
        "transactionHash": "0xc088f083c8ac7d89bd7056d09629f59c1f67cd6c97120807cee782c8200402e1",
        "transactionIndex": "0x0",
        "transactionLogIndex": "0x0"
      }
    ],
    "logsBloom": "0x00000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400001000004200000000000000000000020000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000900080000000000000000000000000000000000000000000000000000000000000",
    "root": null,
    "transactionHash": "0xc088f083c8ac7d89bd7056d09629f59c1f67cd6c97120807cee782c8200402e1",
    "transactionIndex": "0x0"
  }
}

查询账户权限

查询测试账号的权限：

$ cita-cli scm Authorization queryPermissions \
    --account 0x37d1c7449bfe76fe9c445e626da06265e9377601 \
    --url http://127.0.0.1:1337

输出：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000003000000000000000000000000ffffffffffffffffffffffffffffffffff021000000000000000000000000000ffffffffffffffffffffffffffffffffff021001000000000000000000000000ca645d2b0d2e4c451a2dd546dbd7ab8c29c3dcee"
}

已经可以看到新添加的权限了。

调用测试合约

参考调用合约，查看是否调用成功。

可以看出结果已经是 1 了。