中移链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 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 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 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 授权失败。

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

一、 中移链 DDC-SDK 简介

二、 名词解释

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

（一）DDC授权

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

（二）DDC授权查询

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

（三）账户授权

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

（四）账户授权查询

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

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

（一）账户授权

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

（二）账户授权查询

1、功能介绍

2、API 方法定义

3、输入参数

4、输出参数

5、API 调用

五、 常见问题

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

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

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

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

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

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

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

你可能感兴趣的:(区块链智能合约)

一、中移链 DDC-SDK 简介

二、名词解释

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

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

五、常见问题