中移链DDC-SDK技术对接全流程（二）

id:BSN_2021 公众号：BSN 研习社 作者：中移信息

2021 年 10 月，BSN 提出搭建 BSN-DDC 基础网络，区块链团队自主研发中移链（ CMBaaS ）DDC 并与 BSN 开展合作，面向存在 DDC 业务需求的各行业客户提供接入服务，使其可便捷管理 DDC 操作，从而灵活升级产品模式，助力客户业务创新。

本文档是关于中移链 DDC-SDK 技术在对接全流程中如何调用DDC-SDK的DDC授权、账户授权以及对应查询的操作指南，适用于 BSN 开放联盟链–中移链 DDC-SDK 开发者，帮助读者了解如何以平台方的角色集成中移链 DDC-SDK。

一、 中移链 DDC-SDK 简介

中移链 DDC-SDK 是用于与中移链 DDC 合约交互的 API 工具，主要功能可参考《 BSN-DDC_SDK_EOS 平台方详细设计》接口文档。在《 BSN-DDC EOS合约详细设计》文档的基础上，为 BSN-DDC EOS合约提供对应的 Java SDK 接口，方便运营方或平台方通过 Java SDK 实现对合约的远程调用。

中移链 DDC-SDK 主要包含四个模块：BSN-DDC-权限模块、BSN-DDC 计费模块、BSN-DDC-721 业务主模块、BSN-DDC-1155 业务主模块。以下是各个模块的功能介绍：

BSN-DDC 权限模块：负责 DDC 相关账户的添加、查询和更新状态，以及控制不同角色对合约方法的访问权限。

BSN-DDC 计费模块：负责 DDC 相关账户的业务费充值和余额查询，以及允许查询、设置和删除DDC的计费规则。

BSN-DDC-721 业务主模块：用于对外提供一整套完整的 721 所对应的 API 接口便于链账户调用，API 接口包括 BSN-DDC 的生成、授权、转移以及销毁等功能。

BSN-DDC-1155 业务主模块：用于对外提供一整套完整的 1155 所对应的API接口便于链账户调用，API 接口包括 BSN-DDC 的生成、批量生成、授权、转移、批量转移、销毁以及批量销毁等功能。

二、 名词解释

链账户：链账户是存储在区块链上的人类可读名称。根据权限配置，它可以通过个人或个人组的授权而拥有。需要账户才能将任何有效交易转移或推送到区块链，一般是由1-5、a-z组成的12位字符。

智能合约：智能合约是一段代码，可以在区块链上执行，并将合约执行状态作为该区块链实例的不可变历史的一部分。因此，开发者可以依赖区块链作为可信计算环境，智能合约的输入、执行和结果是独立的，不受外部影响。

公私钥对：一个钱包可管理多对公私钥，一对公私钥可管理多个链账户。链账户的使用安全以及权限由公私钥负责，链账户在创建时就绑定了其对应的公私钥。其中，公钥一般由“EOS”串开头，长度为53位。

RAM：RAM 充当永久存储，用于存储账户名称、权限、代币余额和其他数据，以实现快速的链上数据访问。RAM 需要购买并且不是基于质押，因为它是一种有限的持久性资源，以字节（byte）为单位。

CPU：CPU 代表一个方法的处理时间，以微秒（us）为单位。如get account，表示将交易推送到合约帐户时可以支配的处理时间量。CPU是一种瞬态系统资源，属于EOSIO的抵押机制，会在使用后的24小时内线性恢复。

NET：NET 是交易的网络带宽，以字节（byte）为单位。当区块链执行交易时，它会消耗CPU和NET，因此必须抵押足够的NET才能完成交易。NET也是一种瞬态系统资源，属于EOSIO的抵押机制，会在使用后的24小时内线性恢复。

方法权限：根据权限合约对某个账户进行角色判定的逻辑实现，不同账户角色可调用不同的方法权限。运营方通过调用添加方法或删除方法，可以对不同角色的方法权限进行修改。

业务费：根据计费合约对调用DDC合约进行业务费扣除的逻辑实现，不同合约方法可制定不同的计费规则。运营方通过调用设置计费规则或删除计费规则，可以对不同方法的业务费扣除进行修改。

三、 调用 BSN-DDC-721 的 API 方法

（一）DDC授权

1、功能介绍

DDC拥有者通过调用该方法进行DDC的授权。

2、API 方法定义

    1) SDK 方法定义：PushedTransaction approve(String sender, String to, BigInteger ddcId);
    2) EOS 合约方法：ACTION ddc::approve(name sender, name to, uint64_t ddc_id, uint64_t business_type);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是	DDC拥有者
to	被授权账户	string	是
ddcId	ddc721唯一标识	string	是

4、输出参数

字段	字段名	类型	备注
transactionId	交易hash	string
processed	执行信息	object

5、API 调用

1）测试用例

@Test
public void approve721() {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用DDC授权方法
    PushedTransaction pt = ddc721Service.approve(accountList.get(2), accountList.get(1), BigInteger.valueOf(21));
    //解析交易响应数据
    Map<String, Object> trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
}

2） 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "sender":"ddc.con1",
                "to":"ddc.platform",
                "ddc_id":21,
                "business_type":1
            },
            "actAccount":"ddc.contract",
            "actName":"approve"
        }
    ],
    "blockNum":5994222,
    "blockTime":"2022-09-02T08:42:25.500",
    "transactionId":"2bb60abf16d75c612e5e8fb65529a0dfc7eab2112dc219da5f9e9d81947cf2f7"
}

（二）DDC授权查询

1、功能介绍

DDC拥有者通过调用该方法进行DDC授权的结果查询。

2、API 方法定义

    1）SDK 方法定义：Boolean getApproved(String sender, String to, BigInteger ddcId);
    2）EOS 合约方法：get_table_rows(name contract, uint64_t primary, uint64 ddc_id);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是	DDC拥有者
to	被授权账户	string	是
ddcId	ddc721唯一标识	biginteger	是

4、输出参数

字段	字段名	类型	备注
		boolean	true 授权成功; false 授权失败

5、API 调用

1） 测试用例

@Test
public void getApproved721() {
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用DDC授权查询方法
    boolean flag = ddc721Service.getApproved(accountList.get(2), accountList.get(1), BigInteger.valueOf(21));
    System.out.println(flag);
}

2） 输出结果

true

（三）账户授权

1、功能介绍

平台方、终端用户通过调用该方法进行账户所有DDC的授权。

2、API 方法定义

    1）SDK 方法定义：PushedTransaction setApprovalForAll(String sender, String to, Boolean approved);
    2）EOS 合约方法：void ddc::approval_all_721(name sender, name to, bool approved);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是
to	被授权账户	string	是
approved	授权标识	boolean	是

4、输出参数

字段	字段名	类型	备注
transactionId	交易 hash	string
processed	执行信息	object

5、API 调用

1）测试用例

@Test
public void approveall721() {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用账户授权方法
    PushedTransaction pt = ddc721Service.setApprovalForAll(accountList.get(2), accountList.get(1), true);
    //解析交易响应数据
    Map<String, Object> trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
}

2） 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "sender":"ddc.con1",
                "to":"ddc.platform",
                "approved":1,
                "business_type":1
            },
            "actAccount":"ddc.contract",
            "actName":"approvalall"
        }
    ],
    "blockNum":6463172,
    "blockTime":"2022-09-05T01:50:20.500",
    "transactionId":"8f0474922d2bc54858cad62d73e041cdd5ae5af645f093257f2a615ecdb8d04e"
}

（四）账户授权查询

1、功能介绍

平台方、终端用户通过调用该方法进行账户所有DDC的授权结果查询。

2、API 方法定义

    1）SDK 方法定义：Boolean isApprovedForAll(String sender, String to);
    2）EOS 合约方法：get_table_rows(name contract, name table, name account);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是	DDC拥有者
to	被授权账户	string	是

4、输出参数

字段	字段名	类型	备注
		boolean	true 授权成功; false 授权失败

5、API 调用

1） 测试用例

@Test
public void isApprovedForAll721() {
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用账户授权查询方法
    boolean flag = ddc721Service.isApprovedForAll(accountList.get(2), accountList.get(1));
    System.out.println(flag);
}

2） 输出结果

true

四、 调用 BSN-DDC-1155 的 API 方法

（一）账户授权

1、功能介绍

平台方、终端用户通过调用该方法进行账户所有DDC的授权。

2、API 方法定义

    1）SDK 方法定义：PushedTransaction setApprovalForAll(String sender, String to, Boolean approved);
    2）EOS 合约方法：void ddc::approval_all_1155(name sender, name to, bool approved);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是
to	被授权账户	string	是
approved	授权标识	boolean	是

4、输出参数

字段	字段名	类型	备注
transactionId	交易 hash	string
processed	执行信息	object

5、API 调用

1）测试用例

@Test
public void approveall1155() {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用账户授权方法
    PushedTransaction pt = ddc1155Service.setApprovalForAll(accountList.get(2), accountList.get(1), true);
    //解析交易响应数据
    Map<String, Object> trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
}

2） 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "sender":"ddc.con1",
                "to":"ddc.platform",
                "approved":1,
                "business_type":2
            },
            "actAccount":"ddc.contract",
            "actName":"approvalall"
        }
    ],
    "blockNum":6465302,
    "blockTime":"2022-09-05T02:08:05.500",
    "transactionId":"e38abcbb8bcbf6637d089083a259d3f8a7946299efc756b9ddc6c2a0f963f1d2"
}

（二）账户授权查询

1、功能介绍

平台方、终端用户通过调用该方法进行账户所有DDC的授权结果查询。

2、API 方法定义

    1）SDK 方法定义：Boolean isApprovedForAll(String sender, String to);
    2）EOS 合约方法：get_table_rows(name contract, name table, name account);

3、输入参数

字段	字段名	类型	是否必传	备注
sender	调用者账户	string	是	DDC拥有者
to	被授权账户	string	是

4、输出参数

字段	字段名	类型	备注
		boolean	true 授权成功; false 授权失败

5、API 调用

1） 测试用例

@Test
public void isApprovedForAll1155() {
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用账户授权查询方法
    boolean flag = ddc1155Service.isApprovedForAll(accountList.get(2), accountList.get(1));
    System.out.println(flag);
}

2） 输出结果

true

五、 常见问题

（一）DDC授权方法的参数校验，返回错误信息：can’t approve self、not approve、user already approve等，如何处理？

can’t approve self：不能给自己授权，原因是调用者账户与被授权账户属于同一账户；
not approve：没有进行授权，原因是调用者账户既不是DDC的拥有者，也没有得到DDC的授权；
user already approve：已经进行过授权，原因是被授权账户已经得到了DDC的授权。

（二）执行交易时，返回错误信息：abi_serialization_deadline_exception，异常描述：ABI serialization time has exceeded the deadline，如何处理？

abi_serialization_deadline_exception：ABI序列化时间超过截止值，原因是事务执行超时了，一般允许的最大值为500ms，可以进行重试或者减少单次执行的数据量。

（三）执行交易时，返回错误信息：tx_net_usage_exceeded，异常描述：Transaction exceeded the current network usage limit imposed on the transaction，如何处理？

tx_net_usage_exceeded：交易网络占用超限，原因是调用者账户在执行交易过程中，需要占用的 NET 超过了事务允许的最大网络资源，可以给调用者账户抵押一些 NET 资源。

（四）执行交易时，返回错误信息：contract_query_exception，异常描述：Contract can’t be found cmeosddcnfty，如何处理？

contract_query_exception：合约查询异常，原因是cmeosddcnfty账户不是DDC合约部署账户，BSN上中移链的DDC合约部署账户是reddateddc22。

（五）执行交易时，返回错误信息：transaction_exception，异常描述：action’s authorizing actor ‘guotie111111’ does not exist，如何处理？

transaction_exception：交易异常，原因是guotie111111账户在链上不存在，或者guotie111111账户未接入官方DDC合约。

（六）执行交易时，返回错误信息：eosio_assert_message_exception，异常描述：assertion failure with message: not enough fee to pay，如何处理？

eosio_assert_message_exception：消息条件验证失败，原因是调用者账户的业务费不足以支付此次合约调用，可以给该账户充值一些业务费。

六、输出结果中相关字段解析

blockNum：区块高度；

blockTime：区块时间；

transactionId：交易哈希；

actionTraces：方法列表；

actName：方法名称；

actAccount：合约账户；

actData：方法数据；

sender：调用者账户；

to：被授权账户；

ddc_id：ddc 唯一标识（区分721和1155类型，同种类型ddc_id唯一）；

business_type：业务类型（1：ERC721，2：ERC1155）；

approved：授权标识（1：授权，0：取消授权）；

查询结果：true 授权成功，false 授权失败。