中移链DDC-SDK技术对接全流程(一)

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

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

本文档是关于中移链 DDC-SDK 技术在对接全流程中如何调用DDC-SDK的生成、转移、销毁以及对应批量的操作指南,适用于 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 的生成、批量生成、转移、批量转移、冻结、解冻以及销毁等功能。

二、 名词解释

中移链:基于 EOS 区块链改造,满足 BSN 开放联盟链要求,且符合国内监管政策的区块链框架。其中,开放联盟链是对公有链技术进行改造,增加了节点权限控制、系统合约权限控制、点对点转账控制等功能。

BSN:区块链服务网络 BSN(“服务网络”或者“ BSN ”)是为开发者提供了一站式的区块链开发、部署和运行环境服务,整合了各大云服务商、框架商以及多个门户方的资源。

DDC:DDC(Decentralized Digital Certificate)指的是存在于 BSN 区块链服务网络上的“分布式数字凭证”,它代表了现实或数字世界中某一事物在区块链上的唯一数字化权益证明。

ERC-721:不可替代的代币标准,规定了符合标准的 Token 都需有唯一的 Token ID。在 ERC-721 标准里,每个 Token 都是独一无二的,且是不可以分割的。

ERC-1155:多副本标准,管理多种代币类型的合约标准接口。单个部署的合约可能包括可替代代币、不可替代代币或其他配置(例如半可替代代币)的任意组合。

运营方:中移数藏平台的建设方,拥有最高操作权限,比如区块链服务网络 BSN。主要负责添加平台方、终端用户账户,添加合约方法访问权限,DDC 的冻结、解冻,业务费充值,以及计费规则设置等。

平台方:中移数藏平台的企业用户,拥有业务主模块操作权限。例如某公司主要负责添加终端用户账户,业务费充值,可调用 721 或 1155 所对应的API接口,进行 BSN-DDC 的生成、转移、授权以及销毁等。

终端用户:企业用户下的个人用户,一般不直接访问中移数藏平台。例如张三可通过访问集成 DDC-SDK 的第三方平台,进行 BSN-DDC 的生成、转移、授权以及销毁等。

三、 开发前准备

(一)创建链账户、分配资源、创建项目

1.  分别创建 1 个或多个平台方账户和终端用户账户;

2.  为刚创建的链账户分配资源,至少应分配:1SYS NET、1SYS CPU、1024KB RAM;

3.  创建一个项目,选择中移链框架,获取项目 id。

参考链接:https://bsnbase.com/static/tm...

(二)引入 DDC-SDK 依赖包、初始化平台方配置

1.  引入 bsn-eos-sdk 和 cmbos-sdk 的 jar 包;

2.  引入 EOS 官方 java-sdk 以及相关依赖包;

3.  初始化平台方配置,包括:EOS 链访问地址、DDC 合约账户名、平台方账户私钥等。

参考链接:https://mp.weixin.qq.com/s/07O4Udm5VASyx2vqya14Eg

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

(一)生成

1、功能介绍

平台方、终端用户通过调用该方法进行 DDC 的创建。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction safeMint(String from, String to, String ddcURI, String memo);
    2) EOS 合约方法:void ddc::mint_721(name sender, name to, uint64_t amount, std::string ddc_uri, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
from 调用者账户 string
to 接收者账户 string
ddcURI ddc资源标识符 string
memo 备注 string

4、输出参数

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

5、API 调用

1)测试用例

@Test
public void mint721() throws InterruptedException {
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用生成方法
    PushedTransaction pt = ddc721Service.safeMint(accountList.get(1), accountList.get(2), "https://bitnodes.io/227", UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待3秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":10,
                "account":"ddc.platform",
                "business_type":1,
                "func_name":"mint",
                "fee":"0.0001 FEE",
                "balance":"9999.9978 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "ddc_id":10,
                "ddc_uri":"https://bitnodes.io/227",
                "allowed":1,
                "amount":1,
                "business_type":1,
                "ddc_name":"",
                "ddc_symbol":""
            },
            "actAccount":"ddc.contract",
            "actName":"receiptmint"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "amount":1,
                "ddc_uri":"https://bitnodes.io/227",
                "business_type":1,
                "memo":"635afbee-182d-4f30-ac54-66e19f6b1c9a"
            },
            "actAccount":"ddc.contract",
            "actName":"mint"
        }
    ],
    "blockNum":2326811,
    "blockTime":"2022-08-12T03:20:40.000",
    "transactionId":"e65a424715ee952eb9402ed129608b61ffee723f12dffa54ad5e95858628294a"
}
true

(二)转移

1、功能介绍

平台方、终端用户通过调用该方法进行 DDC 的转移。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction transferFrom(String sender, String from, String to, BigInteger ddcId, String memo);
    2) EOS 合约方法:void ddc::transfer_721(name sender, name from, name to, uint64_t ddc_id, uint64_t amount, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
sender 调用者账户 string
from 拥有者账户 string
to 接收者账户 string
ddcId ddc721唯一标识 biginteger
memo 备注 string

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void transferFrom721() throws InterruptedException {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用转移方法
    PushedTransaction pt = ddc721Service.transferFrom(accountList.get(2), accountList.get(2), accountList.get(1), BigInteger.valueOf(13), UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待3秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":13,
                "account":"ddc.con1",
                "business_type":1,
                "func_name":"transfer",
                "fee":"0.0001 FEE",
                "balance":"999.9999 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.con1",
                "from":"ddc.con1",
                "to":"ddc.platform",
                "ddc_id":13,
                "amount":1,
                "memo":"dbb28320-d825-4dc8-b73a-7c0c4a9a4586",
                "business_type":1
            },
            "actAccount":"ddc.contract",
            "actName":"transfer"
        }
    ],
    "blockNum":2362399,
    "blockTime":"2022-08-12T08:17:14.000",
    "transactionId":"74c2aa072b58ced81570ab11668e87beb4990f25385740b2c8f88c632ad3abe5"
}
true

(三)销毁

1、功能介绍

平台方、终端用户通过调用该方法进行 DDC 的销毁。

2、API 方法定义

    1)SDK 方法定义:PushedTransaction burn(String sender, String owner, BigInteger ddcId);
    2)EOS 合约方法:void ddc::burn_721(name sender, name owner, uint64_t ddc_id);

3、输入参数

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

4、输出参数

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

5、API 调用

1)测试用例

@Test
public void burn721() throws InterruptedException {
    DDC721Service ddc721Service = new DDC721ServiceImpl();
    //调用销毁方法
    PushedTransaction pt = ddc721Service.burn(accountList.get(1), accountList.get(1), BigInteger.valueOf(13));
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":13,
                "account":"ddc.platform",
                "business_type":1,
                "func_name":"burn",
                "fee":"0.0001 FEE",
                "balance":"9999.9972 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "owner":"ddc.platform",
                "ddc_id":13,
                "business_type":1
            },
            "actAccount":"ddc.contract",
            "actName":"burn"
        }
    ],
    "blockNum":2364299,
    "blockTime":"2022-08-12T08:33:04.000",
    "transactionId":"cd78e6e1143163989d2efb6314bb1cdf7c5ad5ccd8ad01c4c2e8154a5e60785f"
}
true

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

(一)生成

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的创建。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction safeMint(String from, String to, BigInteger amount, String ddcURI, String memo);
    2) EOS 合约方法:void ddc::mint_1155(name sender, name to, uint64_t amount, std::string ddc_uri, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
from 调用者账户 string
to 接收者账户 string
amount ddc 数量 biginteger
ddcURI ddc 资源标识符 string
memo 备注 string

4、输出参数

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

5、API 调用

1)测试用例

@Test
public void mint721() throws InterruptedException {
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用生成方法
    PushedTransaction pt = ddc1155Service.safeMint(accountList.get(1), accountList.get(2), BigInteger.valueOf(1), "https://bitnodes.io/234", UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2)输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":14,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"mint",
                "fee":"0.0001 FEE",
                "balance":"9999.9971 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "ddc_id":14,
                "ddc_uri":"https://bitnodes.io/234",
                "allowed":1,
                "amount":1,
                "business_type":2,
                "ddc_name":"",
                "ddc_symbol":""
            },
            "actAccount":"ddc.contract",
            "actName":"receiptmint"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "amount":1,
                "ddc_uri":"https://bitnodes.io/234",
                "business_type":2,
                "memo":"1094b83b-f020-4312-8337-b23d9101508d"
            },
            "actAccount":"ddc.contract",
            "actName":"mint"
        }
    ],
    "blockNum":2365369,
    "blockTime":"2022-08-12T08:41:59.000",
    "transactionId":"94de12442c5a0c5b8228c601f3738c6ed98786f15432f9b9021c501a8e408f98"
}
true

(二)批量生成

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的批量创建。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction safeMintBatch(String from, String to, List amounts, List ddcURIs,String memo);
    2) EOS 合约方法:void ddc::mintbatch_1155(name sender, name to, std::vector amounts, std::vector ddc_uris, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
from 调用者账户 string
to 接收者账户 string
amounts ddc 数量集合 list
ddcURIs ddc 资源标识符集合 list
memo 备注 string

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void mintBatch() throws InterruptedException {
    List amounts = Arrays.asList(BigInteger.valueOf(1), BigInteger.valueOf(2));
    List ddcURIS = Arrays.asList("https://bitnodes.io/231", "https://bitnodes.io/232");
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用批量生成方法
    PushedTransaction pt = ddc1155Service.safeMintBatch(accountList.get(1), accountList.get(2), amounts, ddcURIS, UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":15,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"mintbatch",
                "fee":"0.0001 FEE",
                "balance":"9999.9970 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "ddc_id":15,
                "ddc_uri":"https://bitnodes.io/231",
                "allowed":1,
                "amount":1,
                "business_type":2,
                "ddc_name":"",
                "ddc_symbol":""
            },
            "actAccount":"ddc.contract",
            "actName":"receiptmint"
        },
        {
            "actData":{
                "ddc_id":16,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"mintbatch",
                "fee":"0.0001 FEE",
                "balance":"9999.9969 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "ddc_id":16,
                "ddc_uri":"https://bitnodes.io/232",
                "allowed":1,
                "amount":2,
                "business_type":2,
                "ddc_name":"",
                "ddc_symbol":""
            },
            "actAccount":"ddc.contract",
            "actName":"receiptmint"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "to":"ddc.con1",
                "amounts":[
                    1,
                    2
                ],
                "ddc_uris":[
                    "https://bitnodes.io/231",
                    "https://bitnodes.io/232"
                ],
                "business_type":2,
                "memo":"770dd28c-01cd-4027-bec6-4b1598ae19b1"
            },
            "actAccount":"ddc.contract",
            "actName":"mintbatch"
        }
    ],
    "blockNum":2367146,
    "blockTime":"2022-08-12T08:56:47.500",
    "transactionId":"6a1c0b8e16ed1ea47a99a58852db3967863312ed8d78969c26dd3eb14111e1c5"
}
true

(三)转移

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的转移。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction transferFrom(String sender, String from, String to, BigInteger ddcId, BigInteger amount);
    2) EOS 合约方法:void ddc::transfer_1155(name sender, name from, name to, uint64_t ddc_id, uint64_t amount, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
sender 调用者账户 string
from 拥有者账户 string
to 接收者账户 string
ddcId ddc1155唯一标识 biginteger
amount ddc 数量 biginteger
memo 备注 string

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void transferFrom1155() throws InterruptedException {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用转移方法
    PushedTransaction pt = ddc1155Service.transferFrom(accountList.get(2), accountList.get(2), accountList.get(1), BigInteger.valueOf(15), BigInteger.valueOf(1), UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2)输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":15,
                "account":"ddc.con1",
                "business_type":2,
                "func_name":"transfer",
                "fee":"0.0001 FEE",
                "balance":"999.9998 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.con1",
                "from":"ddc.con1",
                "to":"ddc.platform",
                "ddc_id":15,
                "amount":1,
                "memo":"1dc78366-845a-4fcc-9052-a99a2aa3a4c4",
                "business_type":2
            },
            "actAccount":"ddc.contract",
            "actName":"transfer"
        }
    ],
    "blockNum":2368911,
    "blockTime":"2022-08-12T09:11:30.000",
    "transactionId":"c56e67f05dfd39be34ee0f44c51bdfb4cef4023777c6dfe8157544fce277c6bd"
}
true

(四)批量转移

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的批量转移。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction safeBatchTransferFrom(String sender, String from, String to, List ddcIds, List amounts,String memo);
    2) EOS 合约方法:void ddc::batchtrans_1155(name sender, name from, name to, std::vector ddc_ids, std::vector amounts, std::string memo);

3、输入参数

字段 字段名 类型 是否必传 备注
sender 调用者账户 string
from 拥有者账户 string
to 接收者账户 string
ddcIds ddc1155唯一标识集合 list
amounts ddc 数量集合 list
memo 备注 string

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void safeBatchTransferFrom() throws InterruptedException {
    //设置调用者账户私钥
    ChainConfig.setPk("5JAT6ZYDhvvWVP2UMat84BhCyu5U3PYMYtkzqXEgoPoyhdJJfV1");
    List ddcIds = Arrays.asList(BigInteger.valueOf(17), BigInteger.valueOf(18));
    List amounts = Arrays.asList(BigInteger.valueOf(1), BigInteger.valueOf(2));
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用批量转移方法
    PushedTransaction pt = ddc1155Service.safeBatchTransferFrom(accountList.get(2), accountList.get(2), accountList.get(1), ddcIds, amounts, UUID.randomUUID().toString());
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":17,
                "account":"ddc.con1",
                "business_type":2,
                "func_name":"batchtrans",
                "fee":"0.0001 FEE",
                "balance":"999.9997 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "ddc_id":18,
                "account":"ddc.con1",
                "business_type":2,
                "func_name":"batchtrans",
                "fee":"0.0001 FEE",
                "balance":"999.9996 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.con1",
                "from":"ddc.con1",
                "to":"ddc.platform",
                "ddc_ids":[
                    17,
                    18
                ],
                "amounts":[
                    1,
                    2
                ],
                "memo":"23666160-19f0-4fcc-98d4-d9b81da08cd3",
                "business_type":2
            },
            "actAccount":"ddc.contract",
            "actName":"batchtrans"
        }
    ],
    "blockNum":2370846,
    "blockTime":"2022-08-12T09:27:37.500",
    "transactionId":"433ec66abe96400ca61028ebd814630c1087cf5476891e7a4e519b3e82832adc"
}
true

(五)销毁

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的销毁。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction burn(String sender, String owner, BigInteger ddcId);
    2) EOS 合约方法:void ddc::burn_1155(name sender, name owner, uint64_t ddc_id);

3、输入参数

字段 字段名 类型 是否必传 备注
sender 调用者账户 string
owner 拥有者账户 string
ddcId ddc1155唯一标识 string

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void burn1155() throws InterruptedException {
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用销毁方法
    PushedTransaction pt = ddc1155Service.burn(accountList.get(1), accountList.get(1), BigInteger.valueOf(15));
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2)输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":15,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"burn",
                "fee":"0.0001 FEE",
                "balance":"9999.9966 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "owner":"ddc.platform",
                "ddc_id":15,
                "business_type":2
            },
            "actAccount":"ddc.contract",
            "actName":"burn"
        }
    ],
    "blockNum":2374925,
    "blockTime":"2022-08-12T10:01:37.000",
    "transactionId":"39379bb15ae08644aa964ded0c8afe16dc1c7d5f7f45e26a744e7b76142f61e0"
}
true

(六)批量销毁

1、功能介绍

平台方、终端用户通过调用该方法进行多副本 DDC 的批量销毁。

2、API 方法定义

    1) SDK 方法定义:PushedTransaction burnBatch(String sender, String owner, List ddcIds);
    2) EOS 合约方法:void ddc::burnbatch_1155(name sender, name owner, std::vector ddc_ids);

3、输入参数

字段 字段名 类型 是否必传 备注
sender 调用者账户 string
owner 拥有者账户 string
ddcIds ddc1155唯一标识集合 list

4、输出参数

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

5、API 调用

1) 测试用例

@Test
public void safeBatchTransferFrom() throws InterruptedException {
    List ddcIds = Arrays.asList(BigInteger.valueOf(17), BigInteger.valueOf(18));
    DDC1155Service ddc1155Service = new DDC1155ServiceImpl();
    //调用批量销毁方法
    PushedTransaction pt = ddc1155Service.burnBatch(accountList.get(1), accountList.get(1), ddcIds);
    //解析交易响应数据
    Map trxMap = ChainUtil.getInstance().parseTrxResp(pt);
    System.out.println(JSON.toJSONString(trxMap, true));
    //由于较低概率存在区块链分叉,因此等待 3 秒后,校验交易哈希是否存在
    Thread.sleep(3000);
    Boolean flag = ChainUtil.getInstance().checkTrxId(trxMap);
    System.out.println(flag);
}

2) 输出结果

{
    "actionTraces":[
        {
            "actData":{
                "ddc_id":17,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"burnbatch",
                "fee":"0.0001 FEE",
                "balance":"9999.9965 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "ddc_id":18,
                "account":"ddc.platform",
                "business_type":2,
                "func_name":"burnbatch",
                "fee":"0.0001 FEE",
                "balance":"9999.9964 FEE"
            },
            "actAccount":"ddc.contract",
            "actName":"receiptpay"
        },
        {
            "actData":{
                "sender":"ddc.platform",
                "owner":"ddc.platform",
                "ddc_ids":[
                    17,
                    18
                ],
                "business_type":2
            },
            "actAccount":"ddc.contract",
            "actName":"burnbatch"
        }
    ],
    "blockNum":2375718,
    "blockTime":"2022-08-12T10:08:13.500",
    "transactionId":"4061125000a91199f9f98ce496d9b0254615ed2807dca9f4370ab78c6d0cd489"
}
true

六、 常见问题

(一)生成方法的参数校验,返回错误信息:not active sender、not active to user、Invalid role!、invalid permission、platform mismatch等,如何处理?

not active sender:调用者账户状态不可用,原因是调用者账户不存在、平台管理账户状态不为活跃状态、或者运营管理账户状态不为活跃状态;

not active to user:接收者账户状态不可用,原因是接收者账户不存在、平台管理账户状态不为活跃状态、或者运营管理账户状态不为活跃状态;

Invalid role! :角色不为平台方或终端用户,原因是调用者账户的角色不为平台方或终端用户;

invalid permission:调用者账户无调用权限,原因是调用者账户的角色在角色方法表不存在、或者调用者账户的角色没有该方法的调用权限;

platform mismatch:调用者账户与接收者账户不属于同一平台,原因有以下几种情况:

1.若调用者账户和接收者账户都为平台方,则校验调用者账户的 did 与接收者账户的 did 是否匹配。

2. 若调用者账户为平台方且接收者账户为终端用户,则校验调用者账户的 did 与接收者账户的 leader_did 是否匹配。

3. 若调用者账户为终端用户且接收者账户为平台方,则校验调用者账户的 leader_did 与接收者账户的 did 是否匹配。

4. 若调用者账户和接收者账户都为终端用户,则校验调用者账户的 leader_did 与接收者账户的 leader_did 是否匹配。

(二)转移方法的参数校验,返回错误信息:invalid ddc id!、ddc id not allowed!、from is not owner、not approve、can't find balance等,如何处理?

invalid ddc id! :ddc_id 不存在,原因是在 ddc 信息表中查询不到该 ddc_id; 

ddc id not allowed! :ddc_id 已被冻结,原因是该 ddc_id 已被运营方冻结;

from is not owner:from 账户不是 ddc_id 拥有者,原因是拥有者账户与该 ddc_id 的实际拥有者不一致;

not approve:ddc_id 未授权,原因是调用者账户既不是 ddc_id 的拥有者,也不是 ddc_id 的被授权者;

can't find balance:找不到 ddc 余额,原因是拥有者账户的 ddc 余额不足。

(三)销毁方法的参数校验,返回错误信息:can not find ddc id、ddc does not belong to owner等,如何处理?

can not find ddc id:ddc_id 已被持有,原因是该 ddc_id 已被其他人持有;

ddc does not belong to owner:owner 账户不是 ddc_id 拥有者,原因是拥有者账户与该 ddc_id 的实际拥有者不一致。

(四)执行交易时,返回错误信息:unsatisfied_authorization,异常描述:Provided keys, permissions, and delays do not satisfy declared authorizations,如何处理?

unsatisfied_authorization:提供的密钥、许可和延时不能满足声称的授权,原因是调用者账户的实际私钥与签名时传入的私钥不一致,可以修改下签名时传入的私钥。

(五)执行交易时,返回错误信息:ram_usage_exceeded,异常描述:Account using more than allotted RAM usage,如何处理?

ram_usage_exceeded:账号使用的内存超限,原因是调用者账户在执行交易过程中,需要消耗的内存超过了账户自身拥有的内存,可以给调用者账户购买一些内存。

(六)执行交易时,返回错误信息:tx_cpu_usage_exceeded,异常描述:Transaction exceeded the current CPU usage limit imposed on the transaction,如何处理?

tx_cpu_usage_exceeded:交易 CPU 占用超限,原因是调用者账户在执行交易过程中,需要占用的 CPU 超过了事务允许的最大执行时间,可以给调用者账户抵押一些 CPU 资源。

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

blockNum:区块高度;

blockTime:区块时间;

transactionId:交易哈希;

actionTraces:方法列表;

actName:方法名称;

actAccount:合约账户;

actData:方法数据;

ddc_id:ddc 唯一标识(区分721和1155类型,同种类型ddc_id唯一);

account:调用账户;

business_type:业务类型(1:ERC721,2:ERC1155);

func_name:方法名称;

fee:业务费;

balance:业务费余额;

sender:调用者账户;

to:接收者账户;

ddc_uri:ddc 资源标识符;

allowed:是否允许操作(false:不允许,true:允许);

amount:ddc 数量;

ddc_name:ddc 名称;

ddc_symbol:ddc 符号;

memo:备注;

from:拥有者账户;

owner:拥有者账户;

amounts:ddc 数量集合;

ddc_uris:ddc 资源标识符集合;

ddc_ids:ddc 唯一标识集合(区分721和1155类型,同种类型ddc_id唯一);

你可能感兴趣的:(中移链DDC-SDK技术对接全流程(一))