共计 7767 个字符,预计需要花费 20 分钟才能阅读完成。
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 受权失败。