中移链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 调用 【中移链DDC-SDK技术对接全流程（二）】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 授权失败。