BSN-DDC基础网络DDC SDK详细设计五：官方合约BSN-DDC-1155

Posted 2023-04-05 BSN研习社

2022年1月25日，区块链服务网络发展联盟（简称“BSN联盟”）推出了“BSN-DDC基础网络”（简称DDC网络）。DDC网络的推出，为NFT技术在我国的落地提供基础设施能力支撑，并为其合规发展保驾护航。

DDC（Distributed Digital Certificate）即分布式数字凭证，其属性和功能类似于NFT。NFT是现实或数字世界中某个事物在区块链上的数字化权益证明，尽管目前大多被用于数字艺术品版权领域，然而其本质上是一种区块链分布式数据库技术，并不带有特定的业务属性，它的潜在使用场景是非常广泛的，可应用在数字商品凭证、票证、账户管理、知识产权等各种领域。

DDC网络不直接向个人用户提供服务，而是向拥有DDC/NFT业务的平台方提供极其便捷的网络接入服务，以方便这些平台以极低的成本提供DDC/NFT的生成和管理服务。

DDC-SDK 是用于开发者与DDC合约交互的 API 工具。为了让运营方或各平台方对DDC-SDK整体设计有一个全面详细的了解，同时为项目的开发、测试、验证、交付等环节提供原始依据以及开发指导，BSN研习社推出BSN-DDC基础网络DDC SDK详细设计系列。分别从整体设计，DID功能设计，DDC权限管理、费用管理，官方合约BSN-DDC-721，官方合约 BSN-DDC-1155，交易查询、区块查询、签名事件，数据解析，示例等八个方面，全面详细的介绍DDC-SDK。

本期是系列文章第五期，官方合约BSN-DDC-1155。

3.2.1  BSN-DDC-1155

3.2.4.1  安全生成

3.2.4.1.1   功能介绍

平台方或终端用户可以通过调用该方法进行DDC的安全生成。

3.2.4.1.2   API定义

• 方法定义：String safeMint(String sender,String to,BigInteger amount,String ddcURI,byte[] data);

• 合约方法：safeMint(address to,uint256 amount, string memory ddcURI, bytes memory data);

• 调用者：平台方、终端用户；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查接收者账户地址信息是否为空；

3. 检查接收者账户地址格式是否正确；

4. 检查需要生成的DDC数量是否大于0；

5. 检查DDCURI信息是否为空；

6. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
接收者账户	to	String	是
DDC数量	amount	BigInteger	是
DDCURI	ddcURI	String	是
附加数据	data	byte[]	否

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.2  批量安全生成

3.2.4.2.1   功能介绍

平台方或终端用户可以通过调用该方法进行DDC的批量安全生成。

3.2.4.2.2   API定义

• 方法定义：String safeMintBatch(String sender,String to,Multimap<BigInteger,String> ddcInfo,byte[] data);

• 合约方法：safeMintBatch(address to,uint256[] amounts, string[] ddcURIs, bytes memory data);

• 调用者：平台方、终端用户；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查接收者账户地址信息是否为空；

3. 检查接收者账户地址格式是否正确；

4. 检查生成的DDC数量集合大小是否大于0；

5. 检查生成的DDC数量集合中每个DDC数量是否大于0；

6. 检查生成的DDCURI集合大小是否大于0；

7. 检查生成的DDCURI集合中每个DDCURI是否为空；

8. 检查生成的DDC数量集合与DDCURI集合的大小是否相等；

9. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
接收者账户	to	String	是
DDC信息合计	ddcInfo	Multimap<BigInteger,String>	是
附加数据	data	byte[]	否

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.3    账户授权

3.2.4.3.1   功能介绍

DDC拥有者可以通过调用该方法进行账户授权，发起者需要是DDC的拥有者。

3.2.4.3.2   API定义

• 方法定义：

  String setApprovalForAll(String sender,String operator, Boolean approved);

• 合约方法：

  setApprovalForAll(address operator, bool approved);

• 调用者：DDC拥有者；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查授权者账户地址信息是否为空；

3. 检查授权者账户地址格式是否正确；

4. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
授权者账户	operator	String	是
授权标识	approved	Boolean	是

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.4    账户授权查询

3.2.4.4.1   功能介绍

运营方、平台方或终端用户可以通过调用该方法进行账户授权查询。

3.2.4.4.2   API定义

• 方法定义：

  Boolean isApprovedForAll(String owner,String operator);

• 合约方法：

  isApprovedForAll(address owner,address operator) returns (bool);

• 调用者：运营方、平台方或终端用户；

• 核心逻辑：

1. 检查拥有者账户地址信息是否为空；

2. 检查拥有者账户地址格式是否正确；

3. 检查授权者账户地址信息是否为空；

4. 检查授权者账户地址格式是否正确；

5. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
拥有者账户	owner	String	是
授权者账户	operator	Boolean	是

• 输出参数：

字段名	字段	类型	必传	备注
		Boolean	是

3.2.4.5  安全转移

3.2.4.5.1   功能介绍

DDC拥有者或DDC授权者可以通过调用该方法进行DDC的转移。

3.2.4.5.2   API定义

• 方法定义：

  String safeTransferFrom(String sender,String from,String to,BigInteger ddcId,BigInteger amount,byte[] data);

• 合约方法：

  safeTransferFrom(address from,address to,uint256 ddcId,uint256 amount,bytes memory data);

• 调用者：DDC拥有者、DDC授权者；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查拥有者账户地址信息是否为空;

3. 检查拥有者账户地址格式是否正确；

4. 检查接收者账户地址信息是否为空；

5. 检查接收者账户地址格式是否正确；

6. 检查DDCID数值是否大于0；

7. 检查DDC转移所对应的数量是否大于0；

8. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
拥有者账户	from	String	是
接收者账户	to	String	是
DDCID	ddcId	BigInteger	是
数量	amount	BigInteger	是	DDCID所对应的数量
附加数据	data	byte[]	否

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.6  批量安全转移

3.2.4.6.1   功能介绍

DDC拥有者或DDC授权者可以通过调用该方法进行DDC的批量转移。

3.2.4.6.2   API定义

• 方法定义：

  String safeBatchTransferFrom(String sender,String from,String to,Map<BigInteger,BigInteger> ddcs, byte[] data);

• 合约方法：

  safeBatchTransferFrom(address from, address to,uint256[] ddcIds,uint256[] amounts,bytes memory data);

• 调用者：DDC拥有者、DDC授权者；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查拥有者账户地址信息是否为空;

3. 检查拥有者账户地址格式是否正确；

4. 检查接收者账户地址信息是否为空；

5. 检查接收者账户地址格式是否正确；

6. 检查转移的ddcs集合大小是否大于0；

7. 检查转移的ddcs集合中每个DDCID是否大于0；

8. 检查转移的ddcs集合中每个DDC数量是否大于0；

9. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
拥有者账户	from	String	是
接收者账户	to	String	是
拥有者DDCID集合	ddcs	Map<BigInteger,BigInteger>	是
附加数据	data	byte[]	否

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.7  销毁

3.2.4.7.1   功能介绍

DDC拥有者或DDC授权者可以通过调用该方法进行DDC的销毁。

3.2.4.7.2   API定义

• 方法定义：

  String burn(String sender,String owner,BigInteger ddcId);

• 合约方法：burn(address owner,uint256 ddcId);

• 调用者：DDC拥有者、DDC授权者；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查拥有者账户地址信息是否为空;

3. 检查拥有者账户地址格式是否正确；

4. 检查需要销毁的DDCID集合长度是否大于0；

5. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
拥有者账户	owner	String	是
DDCID	ddcId	BigInteger	是

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.8  批量销毁

3.2.4.8.1   功能介绍

DDC拥用者或DDC授权者可以通过调用该方法进行DDC的批量销毁。

3.2.4.8.2   API定义

• 方法定义：

  String burnBatch(String sender,String owner,List<BigInteger> ddcIds);

• 合约方法：

  burnBatch(address owner,uint256[] ddcIds);

• 调用者：DDC拥用者、DDC授权者；

• 核心逻辑：

1. 检查sender为标准备address格式；

2. 检查拥有者账户地址信息是否为空;

3. 检查拥有者账户地址格式是否正确；

4. 检查需要销毁的DDCID集合大小是否大于0；

5. 检查需要销毁的DDCID集合中每个DDCID数值是否大于0；

6. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
拥有者账户	owner	String	是
DDCID集合	ddcIds	List<BigInteger>	是

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

3.2.4.9  查询数量

3.2.4.9.1   功能介绍

运营方、平台方以及终端用户可以通过调用该方法进行查询当前账户拥有的DDC的数量。

3.2.4.9.2   API定义

• 方法定义：

  BigInteger balanceOf(String owner,BigInteger ddcId);

• 合约方法：

  balanceOf(address owner, uint256 ddcId) returns (uint256);

• 调用者：运营方、平台方以及终端用户；

• 核心逻辑：

1. 检查拥有者账户地址信息是否为空；

2. 检查拥有者账户地址格式是否正确；

3. 检查DDCID集合长度是否大于0；

4. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
拥有者账户	owner	String	是
DDCID	ddcId	BigInteger	是

• 输出参数：

字段名	字段	类型	必传	备注
数量		BigInteger	是	拥有者账户所对应的DDCID所拥用的数量

3.2.4.10 批量查询数量

3.2.4.10.1 功能介绍

运营方、平台方以及终端用户可以通过调用该方法进行批量查询账户拥有的DDC的数量。

3.2.4.10.2 API定义

• 方法定义：

  List<BigInteger> balanceOfBatch(Multimap<String,BigInteger>ddcs);

• 合约方法：

  balanceOfBatch(address[] memory owners,uint256[] memory ddcIds) returns (uint256[] memory);

• 调用者：运营方、平台方以及终端用户；

• 核心逻辑：

1. 检查ddcs集合大小是否大于0；

2. 检查ddcs集合中拥有者账户地址信息是否为空；

3. 检查ddcs集合中拥有者账户地址格式是否正确；

4. 检查ddcs集合中每个DDCID数值是否大于0；

5. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
拥有者DDCID集合	ddcs	Multimap<String,BigInteger>	是

• 输出参数：

字段名	字段	类型	必传	备注
数量集合		List<BigInteger>	是	拥有者账户所对应的每个DDCID所拥用的数量

3.2.4.11  获取DDCURI

3.2.4.11.1 功能介绍

运营方、平台方以及终端用户可以通过调用该方法进行查询当前DDC的资源标识符。

3.2.4.11.2 API定义

• 方法定义：String ddcURI(BigInteger ddcId);

• 合约方法：ddcURI(uint256 ddcId) returns (string memory);

• 调用者：运营方、平台方以及终端用户；

• 核心逻辑：

1. 检查DDCID数值是否大于0；

2. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
DDCID	ddcId	BigInteger	是

• 输出参数：

字段名	字段	类型	必传	备注
DDCURI		String	是

3.2.4.12  URI设置

3.2.4.12.1 功能介绍

DDC拥有者或DDC授权者通过调用该方法对DDC的资源标识符进行设置。

3.2.4.12.2 API定义

• 方法定义：String setURI(String sender,String owner,BigInteger ddcId,String ddcURI);

• 合约方法：setURI(address owner,uint256 ddcId,string memory ddcURI);

• 调用者：DDC拥有者、DDC授权者；

• 核心逻辑：

1. 检查sender为标准备address格式;

2. 检查owner地址格式是否正确；

3. 检查ddcId数值是否大于0；

4. 检查ddcURI是否为空字符串；

5. 检查签名事件是否被注册；

• 输入参数：

字段名	字段	类型	必传	备注
调用者	sender	String	是	调用者地址
DDC拥有者	owner	String	是
DDC唯一标识	ddcId	BigInteger	是
DDC资源标识符	ddcURI	String	是

• 输出参数：

字段名	字段	类型	必传	备注
		String	是	交易哈希

本文资料内容来源于BSN-DDC SDK详细设计-V1.0，GitHub地址为：

https://github.com/BSN-DDC/did-sdk

欲浏览更多信息，请您点击登录查看。

中移链EOSJS实战使用

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

中移（动）信息技术有限公司（以下统称“IT公司”）与BSN在2021年10月开展合作，由BSN搭建BSN-DDC基础网络，IT公司区块链团队自主研发基于EOS的中移链DDC，面向存在DDC业务需求的各行业客户提供接入服务，使其可便捷管理DDC操作，从而灵活升级产品模式，助力客户业务创新。

一、中移链eosjs简述

中移链是基于EOS区块链框架改造，满足BSN开放联盟链要求，符合国内监管政策。中移链区块链是一个具有行业领先的交易速度和灵活的实用程序的区块链平台，专为企业级用例而设计，并为公共和私有区块链部署而构建。
中移链是可定制的，通过基于角色的权限系统和安全的应用程序交易处理来满足跨行业的广泛业务需求。
中移链架构引入了一种新的块链架构，旨在实现分布式应用的性能扩展。这是通过创建一个可以构建应用程序的类似操作系统的架构来实现的。中移链的家族成员很多，其中eosjs使其家族中最为重要的成员之一。

​​eosjs​​​是一个 Javascript 库，其核心是提供了一些 API，能使​​中移链Nodeos RPC API​​与基于中移链的区块链集成，这使js（包括nodejs、html中的js、前端框架里的js）具有能直接操作区块链的能力。

二、eosjs的使用。

（一）环境准备

确保安装了较新版本的 ​​Node.js​​。

（二）安装

通过yarn安装eosjs

yarn add eosjs

通过npm安装eosjs

npm install eosjs

（三）eosjs核心描述

eosjs核心： eosjs包主要提供JsonRpc对象和Api对象。

JsonRpc

​​JsonRpc​​​是一个无状态且轻量级的远程过程调用（RPC）传送协议。其传递内容如下：
1、必需参数：能连接到的节点的字符串形式；
2、可选参数：​​​fetch​​​对象。
通过new一个JsonRpc对象，在构造函数里传两个参数，第一个参数必填，即字符串形式的URL（节点的URL地址）；第二个参数非必填，即​​​fetch​​对象，一般在nodejs里传过去，其他（例如:vue端）不需要。代码如下：

const rpc = new JsonRpc(http://172.0.0.1:8888,  fetch );

api

在区块链上发送交易和触发操作，必须有一个​​Api​​​实例，该实例在其构造函数中接收 SignatureProvider 对象。
SignatureProvider 对象必须包含与正在执行操作的参与者和权限要求相对应的私钥。获取到一个api的完整代码如下：

const defaultPrivateKey = "5JWuxonweDjwWFuXRwt4sqj5YriEc8ehZh6EKszYYcf3Puh6gAa"; // bob
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);
const rpc = new JsonRpc(http://172.0.0.1:8888,  fetch );
const api = new Api( rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() );

SignatureProviders 通过​​dist/eosjs-api-interfaces.SignatureProvider​​接口实现。如下所示：

const  JsSignatureProvider  = require(eosjs/dist/eosjs-jssig);

该方法是开发者为签名提供者提供的一个简单选项，主要是作为示例，鉴于安全性考量，建议仅在开发中使用。

在生产代码中，建议使用安全保险库（即​​eosjs-api-interfaces.SignatureProvider​​​接口），确保签署交易时的安全性，官方推荐的库： ​​Ledger Signature Provider**​​。

（四）基本用法

1、在nodejs中使用​​eosjs​​：通过commonjs 语法导入。

关键代码如下：

const  Api, JsonRpc  = require(eosjs);//引入eosjs里两个核心对象
const  JsSignatureProvider  = require(eosjs/dist/eosjs-jssig);      // 签名提供者，只能在开发环境中使用
const fetch = require(node-fetch);  // node only; not needed in browsers，只有nodejs中需要，浏览器中不需要。node-fetch版本需要用到2.6.6版
const  TextEncoder, TextDecoder  = require(util); //转码器

const defaultPrivateKey = "5JWuxonweDjwWFuXRwt4sqj5YriEc8ehZh6EKszYYcf3Puh6gAa"; //操作链的私钥
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);//对私钥签名
const rpc = new JsonRpc(http://172.0.0.1:8888,  fetch ); // http://172.0.0.1:8888为链的地址
const api = new Api( rpc, signatureProvider, textDecoder: new TextDecoder(), textEncoder: new TextEncoder() ); //实例化api，通过api就可以直接操作链了
    //下面自执行函数是一个交易操作
      (async () => 
        const result = await api.transact(
          actions: [
            account: eosio.token,
            name: transfer,
            authorization: [
              actor: eosio,
              permission: active,
            ],
            data: 
              from: eosio,
              to: user2,
              quantity: 0.0001 SYS,
              memo: test,
            ,
          ]
        , 
          blocksBehind: 3,
          expireSeconds: 30,
        );
        console.dir(result);
      )();

2、在浏览器中使用​​eosjs​​。

首先将eosjs从官方仓库拉取下来，仓库地址为：https://github.com/EOSIO/eosjs.git 。
在cmd管理器里依次执行下列代码:
（1）从远程仓库拉取代码。

git clone https://github.com/EOSIO/eosjs.git

（2）进入到eosjs文件夹下。

cd ./eosjs

（3）加载依赖包。

npm install

（4）运行导出压缩过的eosjs。

npm run build-web

或

yarn build-web

这将创建​​dist-web​​​文件夹和 Web 分发模块。确保​​externals.min.js​​​包含 eosjs 使用的外部包。
（5）在目标html里使用​​​<script>​​​标签进行引入​​dist-web​​文件夹里的文件。代码如下：

<pre style="width: 100%; height: 100%; margin:0px; "></pre>

<script src=dist-web/externals.min.js></script>
<script src=dist-web/eosjs-api.min.js></script>
<script src=dist-web/eosjs-jsonrpc.min.js></script>
<script src=dist-web/eosjs-jssig.min.js></script>

引入之后再到script标签里添加如下代码：

<script>
  let pre = document.getElementsByTagName(pre)[0];
  const privateKey = 5JWuxonweDjwWFuXRwt4sqj5YriEc8ehZh6EKszYYcf3Puh6gAa;
  const rpc = new eosjs_jsonrpc.JsonRpc(http://172.0.0.1:8888);
  const signatureProvider = new eosjs_jssig.JsSignatureProvider([privateKey]);
  const api = new eosjs_api.Api( rpc, signatureProvider );
  (async () => 
        const result = await api.transact(
          actions: [
            account: eosio.token,
            name: transfer,
            authorization: [
              actor: eosio,
              permission: active,
            ],
            data: 
              from: eosio,
              to: user2,
              quantity: 0.0001 SYS,
              memo: test,
            ,
          ]
        , 
          blocksBehind: 3,
          expireSeconds: 30,
        );
        console.dir(result);
     pre.textContent += \\n\\nTransaction pushed!\\n\\n + JSON.stringify(result, null, 2)

      )();
</script>

在浏览器中点击html，成功后将运行 pre.textContent，页面上会打印出交易后返回的结果的序列化。
在​​​dist-web​​文件夹和 Web 分发模块创建后，在eos的文件夹下新建一个html，再将上面两部分的代码复制进去，通过浏览器打开即可看到运行结果。

3、在vue项目中使用​​eosjs​​​：通过​​ES 模块语法​​导入。

具体代码如下：

import  Api, JsonRpc  from eosjs;
import  JsSignatureProvider  from eosjs/dist/eosjs-jssig; 
//可以把下面代码封装成一个方法在created周期函数中直接调用，或者直接扔created周期函数中也行。
const defaultPrivateKey = "5JWuxonweDjwWFuXRwt4sqj5YriEc8ehZh6EKszYYcf3Puh6gAa"; 
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);
const rpc = new JsonRpc(http://172.0.0.1:8888);
const api = new Api( rpc, signatureProvider );
(async () => 
        const result = await api.transact(
          actions: [
            account: eosio.token,
            name: transfer,
            authorization: [
              actor: eosio,
              permission: active,
            ],
            data: 
              from: eosio,
              to: user2,
              quantity: 0.0001 SYS,
              memo: test,
            ,
          ]
        , 
          blocksBehind: 3,
          expireSeconds: 30,
        );
        console.dir(result);

      )();

4、在react项目中使用​​eosjs​​​：通过​​ES 模块语法​​导入。

在react项目中使用eosjs，代码与在vue项目是相同的，需要注意的一点是react-script的版本问题：
因为是通过react的脚手架创建项目，默认使用的react-scripts是最新版本，在交易的时候会报buffer错误，这就需要将 "react-scripts"的版本更改为"react-scripts": "4.0.3"。