乐趣区

关于区块链:中移链DDCSDK技术对接全流程二

jiezi

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 受权失败。

退出移动版