1. DAC合约
合约接入
  • TEC合约
    • API接入
    • SDK接入
  • DAC合约
    • API接入
    • SDK接入
  • BID合约
    • SDK接入
  • DRC合约
    • SDK接入
  • EPC合约
    • SDK接入
  1. DAC合约

SDK接入

一、合约使用说明#

1、底层链采用的FISCO BCOS V3框架,由于区块链智能合约调用与传统的HTTP接口具有差异性,接口调用的具体方法参考FISCO BCOS相关文档,详见:交易构造与调用 ,也可参考第四部分的示例程序。
2、资产合约采用Solidity 0.8版本进行编写,本文档的接口均基于此基础之上。
3、由于区块链的异步性,事务类型的交易接口,只返回当前交易的Hash,具体的接口描述中不再说明。
4、本合约通过事件机制获取链上交易的执行结果,具体使用方法,详见第四部分的示例程序。

二、命名解释#

针对部分公共的参数命名,本章节做详细说明,后续章节不再单独说明:
命名描述
DACDigital Asset Certificate的简称,即具体某一个数字资产,是数字资产的最小单位。
DACID单个数字资产在链上的唯一ID,由区块链主动生成。
category数字资产类别,是一个或者多个相同属性DAC的集合。单个数字资产一定关联某个数字资产类别。
categoryID数字资产类别在链上的唯一ID,由区块链主动生成。
categoryName数字资产名称、或者数字资产在链下业务系统可标识资产类型的ID、编号等。
owner拥有者,对应到DAC上是指当前DAC的持有者账户,对应到数字资产分类上是指该分类的发行方账户。
approve授权,是指将owner具备的权限,赋予给另外一个区块链账户,
这里的权限专指链上数字资产的转移、销毁权限。不是业务上的使用授权。
txHash链上交易的唯一Hash,该hash链上、链下均可以独立计算,且算法一致。

三、接口详情#

1、创建数字资产类别#

方法描述#

数字资产发行方创建资产类别,其类别的owner既是当前发起调用的账户,创建完成后,返回交易Hash,后续通过交易Hash去链上查询categoryID

方法定义#

    /**
     * @dev user create a unique category,and the category owner is caller.
     * @param categoryName, the category name, Obligatory.
     * @param metadata, the category metadata.
     * Emits {CreateCategory} event.
     */
    function createCategory(string calldata categoryName, string calldata metadata) external;

参数说明#

参数是否必传描述
categoryName是数字资产名称
metadata是数字资产类别元数据,json格式。没有内部属性时可传空json串
metadata统一可传的参数如下:(也可以自定义其它参数,但是如下参数命名不可修改其含义)
参数是否必传描述
DACName是数字资产名称
creator是数字资产的创作者,可以存储链上身份名称、或者作者姓名
issuer否数字资产发行方,可以存储链上身份名称、发行机构编号、机构名称等
totalSupply是该类数字资产的总发行量
DACUrl否数字资产访问地址
DACHash是数字资产的内容Hash值
authUrl否授权发行凭证访问地址
authHash否授权发行凭证Hash值

2、发行数字资产#

方法描述#

数字资产发行方在数字资产类别的基础上发行数字资产

方法定义#

   /**
     * @dev category owner mint DAC.
     * @param categoryID, the category id. Obligatory.
     * @param to, the owner address of the DAC. Obligatory.
     * @param amount, mint amount. Obligatory.
     * @param metadata, the metadata of DAC. 
     * Emits {Mint} event.
     * Requirements:
     * - Only category owner can exe this method.
     * - categoryID is exist.
     * - category is not unfreeze status
     */
    function mint(uint256 categoryID, uint256 amount, address to, string calldata metadata) external;

请求参数说明#

参数是否必传描述
categoryID是数字资产类别
amount是发行数量,总和应小于 totalSupply
to是发行的目标地址账户
metadata是数字资产元数据,json格式。没有内部属性时可传空json串

3、数字资产授权#

方法描述#

数字资产当前拥有者将某个资产的操作权限授权委托给另外的账户地址,授权后目标账户可以对数字资产进行转移、销毁操作。使用本方法,单个数字资产同时只能存在一个授权,即多次调用该方法,会取消上一次的授权,如果授权的地址是空地址,则表示取消授权。

方法定义#

    /**
     * @dev Gives permission to `to` to transfer DAC to another account.
     * The approval is cleared when the DAC is transferred.
     * Only a single account can be approved at a time, so approve to the zero address clears previous approvals.
     * @param to, the owner address of the DAC,Obligatory.
     * @param DACID, the DAC ID, Obligatory
     * Emits {Approval} event.
     * Requirements:
     * - Only DACID's owner can execute this method.
     * - DACID must exist.
     * - category is not freeze status
     */
    function approve(address to, uint256 DACID) external;

请求参数说明#

参数是否必传描述
to是授权的目标地址
DACID是授权的数字资产ID

4、数字资产批量授权#

方法描述#

拥有者将所有数字资产的转移、销毁权限,委托授权给另外一个账户。使用本方法不不限制授权数量,即一个账户,可以授权多个账户操作自己的所有数字资产。同时,本授权对授权之后获取的数字资产,同样有效。

方法定义#

    /**
     * @dev Approve or remove `operator` as an operator for the caller.
     * Operators can call {transferFrom} or {transferFromBatch} for any DAC owned by the caller.
     * @param operator, the operator address. Obligatory.
     * @param approved, approve or remove approve. Obligatory.
     * Emits {ApprovalForAll} event.
     * Requirements:
     * - The `operator` cannot be the caller.
     * - Only DACID's owner can execute this method.
     */
    function setApprovalForAll(address operator, bool approved) external;

请求参数说明#

参数是否必传描述
operator是授权的目标地址
approved是授权、或者取消授权

5、转移数字资产#

方法描述#

数字资产拥有者将资产转移给其它账户

方法定义#

    /**
     * @dev transfers DAC from `from` to `to`.
     * @param from, the DAC owner address. Obligatory.
     * @param to, the to address. Obligatory
     * @param DACID, the DAC ID. Obligatory
     * @param extData,the extra data for transaction
     * Emits {Transfer} event.
     * Requirements:
     * - Only DACID's owner or approved can execute this method.
     * - DACID must exist.
     * - category is not freeze status.
     * - to addrss is not zero
     */
    function transferFrom(address from, address to, uint256 DACID, string calldata extData) external;

请求参数说明#

参数是否必传描述
from是转移者
to是转移的目标地址账户
DACID是数字资产ID
extData是扩展数据,json格式。用于记录转移的其它数据如转移价格、条件等业务数据

6、批量转移数字资产#

方法描述#

数字资产拥有者将多个数字资产同时转移给某个账户

方法定义#

    /**
    * @dev transfers DAC from `from` to `to`.
    * @param from, the owner address of all the DAC. Obligatory.
    * @param to, the to address. Obligatory
    * @param DACIDs, the DAC ID. Obligatory
    * @param extData,the extra data for transaction
    * Emits {Transfer} event.
    * Requirements:
    * - Only DACID's owner or approved can execute this method.
    * - DACID must exist.
    * - category is not freeze status.
    * - to addrss is not zero.
    */
    function transferFromBatch(address from, address to, uint256[] calldata DACIDs, string calldata extData) external;

请求参数说明#

参数是否必传描述
from是转移者
to是转移的目标地址账户
DACIDs是待转移的数字资产ID集合
extData是扩展数据,json格式。用于记录转移的其它数据如转移价格、条件等业务数据

7、批量转移数字资产#

方法描述#

数字资产销毁,数字资产拥有者和被授权的对象账户可以执行该操作

方法定义#

    /**
    * @dev burn DAC.
    * @param DACID, the DACID.
    * Emits {Burn} event.
    * Requirements:
    * - Only DACID's owner or approved can execute this method.
    * - DACID must exist.and the DAC status is normal
    */
    function burn(uint256 DACID) external;

请求参数说明#

参数是否必传描述
DACID是数字资产ID

8、查询数字资产类别#

方法描述#

通过数字资产类别ID,查询数字资产类别详情

方法定义#

    /**
     * @dev query category by id
     * @return id the categoryId,if return 0,this category not exist
     * @return categoryName the return category name.
     * @return owner, the category owner.
     * @return status the category status.
     * @return metadata the category metadata.
     */
    function queryCategory(uint256 categoryID) external view returns (uint256 id, string calldata categoryName, address owner, uint256 status, string calldata metadata);external;

请求参数说明#

参数是否必传描述
categoryID是数字资产分类ID

响应参数说明#

参数是否必传描述
id是数字资产分类ID,这里命名为id是solidity语法限制,出参不能和入参命名一致。
如果返回的id为0,表示该数字资产分类ID在链上不存在。
categoryName是创建数字资产分类时上传的数字资产名称
owner是发行方账户地址
status是数字资产分类状态
0:正常
1:冻结
metadata是创建数字资产分类时上传的数字资产分类元数据

9、查询数字资产#

方法描述#

通过数字资产ID,查询数字资产详情

方法定义#

    /**
     * @dev query DAC by ID
     * @param DACID, the DAC ID. Obligatory
     * @return owner  the current owner of DAC,if owner is zero, that's means the DAC is not exist or burned
     * @return categoryID the category id
     * @return status  the DAC status
     */
    function queryDAC(uint256 DACID) external view returns (address owner, uint256 categoryID,
        uint256 status, string memory metadata);

请求参数说明#

参数是否必传描述
DACID是数字资产ID

响应参数说明#

参数是否必传描述
owner是当前数字资产的持有者,如果owner为0,则表示该数字资产不存在或者已经被销毁
categoryID是所属数字资产分类的ID
status是数字资产分类状态
0:正常
1:冻结
2:销毁
metadata是发行数字资产时上传的数字资产元数据

10、查询单个数字资产授权#

方法描述#

通过数字资产ID,查询当前唯一存在的授权账户,本接口查询“数字资产授权”接口的业务结果

方法定义#

    /**
     * @dev Returns the account approved for DAC.
     * @return operator the account approved for DAC
     * Requirements:
     * - DACID must exist.
     */
    function getApproved(uint256 DACID) external view returns (address operator);

请求参数说明#

参数是否必传描述
DACID是数字资产ID

响应参数说明#

参数是否必传描述
operator是授权的目标账户地址

11、查询批量授权#

方法描述#

查询是否存在授权关系,本授权不针对具体某一个数字资产,而是针对接口4的“数字资产批量授权”,即所有数字资产的授权。

方法定义#

    /**
     * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`.
     * @param owner, owner of DAC
     * @param operator, the operator address
     * @return the approve result
     */
    function isApprovedForAll(address owner, address operator) external view returns (bool);

请求参数说明#

参数是否必传描述
owner是数字资产授权账户
operator是数字资产

响应参数说明#

参数是否必传描述
无是返回单个参数,是否存在授权

12、查询数字资产数量#

方法描述#

查询某个分类下数字资产的总量

方法定义#

    /**
     * @dev query total supply of one category
     * @param categoryID, the category's id
     * @return totalSupply, the count of DACs under this category
     */
    function totalSupplyOfCategory(uint256 categoryID) external view returns (uint256);

请求参数说明#

参数是否必传描述
categoryID是数字资产分类的ID

响应参数说明#

参数是否必传描述
无是返回单个参数,即数量

12、查询持有数量#

方法描述#

查询某个账户地址持有多少个数字资产

方法定义#

    /**
     * @dev Get the balance of an account's DAC on contact.
     * @param owner,The address of the DAC holder
     */
    function balanceOf(address owner) external view returns (uint256);

请求参数说明#

参数是否必传描述
owner是数字资产拥有者账户地址

响应参数说明#

参数是否必传描述
无是返回单个参数,即持有数量

13、查询持有的数字资产#

方法描述#

通过索引查询某个账户地址的数字资产

方法定义#

 /**
     * @dev Get the DAC by index.
     * @param owner The owner address
     * @param index [1, holdDACCount]
     * @return DACID the DAC ID
     * @return categoryID the category id
     * @return status  the DAC status
     */
    function getDACByIndex(address owner, uint256 index) external view returns (uint256 DACID, uint256 categoryID, uint256 status, string memory metadata);

请求参数说明#

参数是否必传描述
owner是数字资产拥有者账户地址
index是本索引大小,不超过接口12,即当前账户地址持有的数量上限。

响应参数说明#

参数是否必传描述
owner是当前数字资产的持有者,如果owner为0,则表示该数字资产不存在或者已经被销毁
categoryID是所属数字资产分类的ID
status是数字资产分类状态
0:正常
1:冻结
2:销毁
metadata是发行数字资产时上传的数字资产元数据

四、调用示例#

为了方便开发者对智能合约的调用,FISCO BCOS官方提供了生成客户端代码的工具,通过该工具为本数字资产合约生成的java客户端代码可通过如下地址下载:资产合约java客户端代码,开发者可以直接使用该客户端,如下示例均基于该客户端代码进行编写。

创建数字资产类别调用示例#

查询链上数字资产类别ID示例#

发行数字资产调用示例#

查询数字资产ID示例#

数字资产转移调用示例#

查询数字资产详情调用示例#

修改于 2024-01-04 08:29:05
上一页
API接入
下一页
SDK接入
Built with