SDK接入

一、合约使用说明

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

二、命名解释

针对部分公共的参数命名，本章节做详细说明，后续章节不再单独说明：

命名	描述
CA	指得到国家管理部门认可的证书管理机构，如四川CA。
bid	链上用户身份，标识规则见《链上数字身份（BID）合约规范》，一个机构可能有多个bid。
eid	Uniform evidence id，统一证据标识，结构建议为：eid:method:identiy，如：eid:guxin:xxxxx,代表固信链上的存证id
udri	Uniform Data Resource Identifiers，统一数据资源标识，用于数据的全局唯一标识，由平台方调用三方服务接口获取。（建议增加平台标识，以避免碰撞）
数据主体	指依法享有数据资源持有权、数据加工使用权、数据产品经营权等数据权益的主体，通过上链存证保护自身权益。
审查机构	包括合规审查机构、安全审查机构等，拥有相应资质证书。
登记机构	由社会认可的登记机构，取得相应许可证书。
平台机构	通过运营技术平台，为数据主体等单位提供数据要素确权存证、审查存证、登记存证等服务。
扩展信息	扩展信息举例如下：——数据来源信息，包括交易获得、合法授权、自主生产的具体信息。——数据来源佐证材料，包括交易凭证、合法授权凭据、自主生产立项材料及其单项财务报表等佐证材料。——有效控制措施佐证材料，包括制度文件、针对该数据资源的访问控制策略等能证明组织拥有或控制该数据资源的佐证材料。——个人信息采集的合法佐证材料，包括用户协议、生效时间、个人知情同意记录等佐证材料。

三、接口详情

1、身份管理接口

1.1 配置管理权限

1.1.1. 配置管理权限

功能定位

由运营方(合约所有者)在链上给某个机构帐号地址赋予用户管理权限。

调用限制

该接口只有运营方(合约所有者)能调用。

接口定义

     function grantUserManagePermission(string memory bid,account address) public

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	被授予用户管理权限的权威机构的链上身份ID		是	string
account	被授予用户管理权限的权威机构进行用户角色管理签名交易时使用的私钥对应的地址。(后续的调用用户角色管理接口时，合约内部会判断msg.sender是否和该account一致,防止攻击者知道bid后用任何私钥签名即可进行任何用户角色管理)		是	address

1.1.2. 回收管理权限

功能定位

由运营方(合约所有者)在链上收回某个机构帐号地址的用户管理权限。

调用限制

该接口只有运营方(合约所有者)能调用。

接口定义

     function revokeUserManagePermission(string memory bid) public

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	被收回用户管理权限的权威机构的链上身份ID		是	string

1.2 用户角色管理

角色与权限的对应关系如表所示，只有被授予相应角色的用户才能进行表中对应的操作。

	确权存证	审查存证	登记存证	查询
数据主体	✔️			✔️
审查机构		✔️		✔️
登记机构			✔️	✔️
其他				✔️

1.2.1 添加用户

接口描述

由用户管理员在链上添加用户信息，同时可以绑定用户角色。

接口定义

     function addUser(string memory bid, string memory usci, string memory name,address account, string[] memory roles) public

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	机构链上身份ID		是	string
usci	机构统一社会信用代码	64	是	string
name	机构名称		是	string
account	机构存证上链时签名交易时使用的私钥对应的地址。(后续调用存证接口时，合约内部会判断msg.sender是否和该account一致,防止攻击者知道bid后用任何私钥签名即可存证任何数据)		是	address
roles	["角色1”，"角色2” ... ]		是	string[]

角色定义：

数据主体：data_holder

审查机构：reviewer

登记机构：registry

平台机构：platform

1.2.2 查询用户

接口描述

根据用户bid查询当前用户信息及其绑定的角色。

接口定义

     function getUserRoles(string memory bid) public view returns(string memory usci,string memory name,string[] memory roles)

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	机构链上身份ID		是	string

响应内容

参数名称	参数说明	长度	必须	数据类型
usci	机构统一社会信用代码	64	是	字符
name	机构名称		是
roles	["角色1”，"角色2” ... ]		是	string[]

1.2.3 添加用户角色

接口描述

为用户添加新的角色。

接口定义

     function grantUserRoles(string memory bid, string[] memory roles) public

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	机构链上身份ID		是
roles	["角色1”，"角色2” ... ]		是	string[]

1.2.4 回收用户角色

接口描述

由用户管理员回收用户的一或多个角色。

接口定义

    function revokeUserRoles(string memory bid, string memory[] roles) public

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	机构链上身份ID		是	string
roles	["角色1”，"角色2” ... ]		是	string[]

2、存证相关接口

2.1 确权存证

2.1.1 新增确权存证

功能定位

本接口仅用于拥有数据的“数据资源持有权”用户对数据资源进行首次确权存证。确权存证信息一经上链无法不支持调整，如需调整则需先撤回再新增，所以要认真确认上链数据的正确性。

由存证用户直接或通过服务平台调用该接口进行信息上链存证，无论是哪种方式，均由用户自己的密钥进行签名。

★针对每个存证要生成一个唯一的证据id，即eid，构造方式见名词术语定义。

调用限制：

合约需要对上链存证主体的身份进行验证，权限设置参见3.2节。

接口定义

function addDataRightEvidence(string memory udri, string memory bid, string[] memory dataHash, string[] memory dataRight, string[] memory metaData, string[] memory variableData) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识，由平台方调用三方服务接口获取	64	是	字符
bid	数据权益主体的机构链上身份ID	64	是	字符
dataHash	用户原始数据块的hash值，可以有1个或2个，SM3算法生成的Hash为必选，由SHA256生成的hash为可选。		是	string[]
dataRight	1.数据资源持有权（必选）;2.数据加工使用权（可选）;3.数据产品经营权（可选）。		是	建议string[]
metaData	参见下面的 metaData字段描述		是	string[]
variableData	可扩展信息，参见下面的 variabledata字段描述		否	string[]

metaData采用key & value依次写入数组的形式传输数据资源描述信息，便于以后扩展，具体内容如下表所示。（设计依据：T/SCBA 006—2023 《基于区块链的数据资源登记存证实施规范》）

参数名称	参数说明	必须	数据类型
dataName	数据资源名称	是	字符
classification	数据分类：包括公共数据、企业数据或个人数据。	是	字符
level	数据级别：包括核心数据、重要数据或一般数据。	是	字符
timeRange	数据起至时间范围，格式为：xxxxx	是	字符
dataSize	数据规模大小。不同的数据形态可能描述方法不一样，用户可以自己定义。	是	字符
dataForm	数据资源形态，参见1.2节定义。	是	数值
dataUrl	数据访问地址：包括数据存储位置、服务网址、特定数据库表、特定文件系统目录或其他位置	是	字符

variableData采用key & value依次写入数组的形式传输数据资源描述信息，便于以后扩展，目前用到的内容如下表所示。

参数名称	参数说明	必须	数据类型
extendDataHash	扩展信息的hash值	否	string
extendDataUrl	扩展信息的访问地址。	否	string

2.1.2 追加可变数据存证

用于追加存证数据的扩展信息，将扩展信息数据本地存储，将扩展信息url和hash值上链存证。追加的扩展信息作为新的记录存在，与原扩展信息同时作为数据的附属数据。

合约接口

function appendVariableData(string memory udri,string[] memory variableData) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识。	64	是	字符
variableData	可扩展信息，参见下面的 variableData字段描述		否	string[]

variabledata目前用到的内容如下表所示。

参数名称	参数说明	必须	数据类型
extendDataHash	扩展信息的hash值	否	string
extendDataUrl	扩展信息的访问地址。	否	string

2.1.3 撤回确权存证

功能定位

用于某一数据的权益主体撤回自己的权益存证。

调用限制：

只能由该权益的所有人或者权威机构进行撤销。

接口定义

function withdrawDataRightRegister( string memory udri, string[] memory dataRight) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
dataRight	拟撤回存证的权益：包括1.数据资源持有权;2.数据加工使用权;3.数据产品经营权		是	string[]

2.1.4 新增授权存证

功能定位

本接口仅用于拥有数据的“数据资源持有权”用户向其他用户授予该数据资源权利。

接口定义

function grantUserDataRight(string memory udri, string memory bid, string[] memory dataRight) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
bid	被授权用户链上身份ID	64	是	字符
dataRight	拟授权的存证的权益：包括1.数据资源持有权;2.数据加工使用权;3.数据产品经营权		是	string[]

2.1.5 撤回授权存证

功能定位

本接口仅用于拥有数据的“数据资源持有权”用户撤回向其他用户授予的该数据资源权利。

接口定义

function withdrawUserDataRight(string memory udri, string memory bid, string[] memory dataRight) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
bid	被撤回授权用户链上身份ID	64	是	字符
dataRight	拟撤回的数据权益：包括1.数据加工使用权;2.数据产品经营权		是	string[]

2.2 审查存证

2.2.1 新增审查存证

功能定位

第三方法律服务机构对数据资源或数据产品进行合规性审查，出具审查报告，并将审查结果及审查文件调用该合约接口上链存证。可以根据需要新增多次审查存证，如面向不同的数据交易机构要求进行多次审查的场景。

调用限制

仅限被授予审查机构的用户调用。

接口定义

function addReviewEvidence(string memory udri, string memory reviewerBid, string[] memory reviewDataHash, string[] memory metaData, string[] memory variableData) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识。	64	是	字符
reviewerBid	审查机构链上身份标识
reviewDataHash	审查结论材料数据块的hash值，可以有1个或2个，SM3算法生成的Hash为必选，由SHA256生成的hash为可选。		是	string[]
metaData	参见下面的 metaData可含字段		是	string[]
variableData	可扩展信息，参见下面的 variabledata字段描述		是	string[]

metadata的定义如下：

参数名称	参数说明	必须	数据类型
reviewTime	审查时间，出具审查报告的时间	是	字符
conclusion	审查结论	是	字符
reviewDataUrl	审查结论材料地址或者从访问页面可以明确找到对应材料的访问地址	是	字符

variabledata采用key & value依次写入数组的形式传输数据资源描述信息，便于以后扩展，目前用到的内容暂无。

参数名称	参数说明	必须	数据类型

2.2.2 撤回审查存证

功能定位

第三方法律服务机构撤回自己的审查存证，如果有多次审查存证记录，一并撤回，不支持对单一审查存证记录撤回。

调用限制

仅限新增审查存证的主体自身调用。

接口定义

function withdrawReviewEvidence(string memory udri,string memory reviewerBid) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识。	64	是	字符
reviewerBid	审查机构链上身份标识

2.3 登记存证（二阶段）

3、查询相关接口

3.1 查询用户数据信息

3.1.1 查询用户数据数量

接口描述

用于查询某个数据主体名下存证的数据数量，返回各类存证数据总数。

接口定义

function getDataCount(string calldata bid) public view returns (uint256 dataCount)

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	数据机构的链地址		是

返回参数

参数名称	参数说明	长度	必须	数据类型
dataCount	返回该企业用户名下有多少确权存证数据，返回总数，含已经注销的。		是	整数

3.1.2 查询用户数据列表

接口描述

用于查询某个数据主体名下存证数据的列表，返回存证数据相应的udri。

接口定义

function getDataList(string memory bid, uint256 start,unit256 count) public view returns (string[] memory udriArray)

传入参数

参数名称	参数说明	长度	必须	数据类型
bid	用户链上身份	64	是	字符
start	从哪个index开始查询		是	整数
count	返回多少个存证数据资源udri		是	整数

返回参数

参数名称	参数说明	长度	必须	数据类型
udriArray	该种类型下数据资源标识列表,(返回值数目可能小于传入值count)		是	数组

3.2 查询确权存证信息

3.2.1 查询存证数据标识

合约描述

该合约接口可用于新增存证信息前，需要根据数据块hash进行验证该数据是否已经上链，不允许相同数据进行存证；如果合约不存在该数据块hash，则返回空，如果存在，则返回该数据块对应的存证数据编码。

接口定义

function getUdriByDatahash(string calldata dataHash) public view returns (string memory udri)

传入参数

参数名称	参数说明	长度	必须	数据类型
dataHash	数据块hash，dataHashSM 或 dataHashSHA	64	是	字符

返回参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识（未查询到则为空）	64	是	字符

3.2.2 查询确权存证信息

接口描述

根据udri查询该数据资源的确权存证信息。

接口定义

function getRegisteredData(string memory udri) public view returns ( string memory dataHashSM, string memory dataHashSHA, string[] memory dataRight, string[] memory metaData, string[] memory variableData, bool isWithdraw)

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符

返回参数

参数名称	参数说明	必须	数据类型
dataHashSM	用户原始数据块的hash值（由SM3算法生成）	是	字符
dataHashSHA	用户原始数据块的hash值（由SHA256算法生成）	是	字符
dataRight	1.数据资源持有权;2.数据加工使用权;3.数据产品经营权		string[]
metadata	数据描述信息		string[]
variabledata	可扩展信息	否	string[]
status	撤回存证与否？

3.2.3 查询授权信息

功能定位

本接口仅用于获取某个用户对某个“数据资源”的权利。

接口定义

function getUserDataRight(string memory udri,string memory bid) public

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
bid	被授权用户链上身份ID	64	是	字符

返回参数

参数名称	参数说明	长度	必须	数据类型
dataRight	被授予的存证的权益：包括1.数据资源持有权;2.数据加工使用权;3.数据产品经营权			string[]

3.3 查询审查存证信息

3.3.1 查询审查存证数量

接口描述

用于查询某个数据的审查存证数量，返回各类审查存证数据总数。

接口定义

function getReviewCount(string calldata udri) public view returns (uint256 reviewCount)

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符

返回参数

参数名称	参数说明	长度	必须	数据类型
reviewCount	返回该企业用户名下有多少审查存证数据，返回总数，含已经注销的。		是	整数

3.3.2 查询审查存证信息

接口描述

根据udri查询该数据资源的审查存证信息。

接口定义

function getVerifyEvidence(string calldata udri, uint32 index) public view returns (bool isWithdraw, string memory reviewerBid, string[] memory metaData, string[] memory variableData)

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
index	index取值为[0, reviewCount)		是	整数

返回参数

参数名称	参数说明	必须	数据类型
isWithdraw	审查存证状态，是否已经撤销		bool
reviewerBid	审查机构链上身份标识
metadata	参考该章节的metadata格式描述	是	string[]
variabledata	可扩展信息，参考该章节的variabledata格式描述	否	string[]

3.3.3 查询审查存证次数

接口描述

获取某个审核机构对某个数据存证的审核次数

接口定义

function getReviewCountOfReviewer(string calldata udri, string calldata reviewerBid) public view returns (uint256 count)

传入参数

参数名称	参数说明	长度	必须	数据类型
udri	统一数据资源标识	64	是	字符
index	index取值为[0, reviewCount)		是	整数

返回参数

参数名称	参数说明	长度	必须	数据类型
reviewerBid	审查机构链上身份标识

四、调用示例

https://github.com/2CLabs/DRC-java-test

一、合约使用说明#

二、命名解释#

三、接口详情#

1、身份管理接口#

1.1 配置管理权限#

1.1.1. 配置管理权限#

功能定位#

调用限制#

接口定义#

传入参数#

1.1.2. 回收管理权限#

功能定位#

调用限制#

接口定义#

传入参数#

1.2 用户角色管理#

1.2.1 添加用户#

接口描述#

接口定义#

传入参数#

1.2.2 查询用户#

接口描述#

接口定义#

传入参数#

1.2.3 添加用户角色#

接口描述#

接口定义#

传入参数#

1.2.4 回收用户角色#

接口描述#

接口定义#

传入参数#

2、存证相关接口#

2.1 确权存证#

2.1.1 新增确权存证#

功能定位#

接口定义#

传入参数#

2.1.2 追加可变数据存证#

合约接口#

传入参数#

2.1.3 撤回确权存证#

功能定位#

接口定义#

传入参数#

2.1.4 新增授权存证#

功能定位#

接口定义#

传入参数#

2.1.5 撤回授权存证#

功能定位#

接口定义#

传入参数#

2.2 审查存证#

2.2.1 新增审查存证#

功能定位#

调用限制#

接口定义#

传入参数#

2.2.2 撤回审查存证#

功能定位#

调用限制#

接口定义#

传入参数#

2.3 登记存证（二阶段）#

3、查询相关接口#

3.1 查询用户数据信息#

3.1.1 查询用户数据数量#

接口描述#

接口定义#

传入参数#

3.1.2 查询用户数据列表#

接口描述#

接口定义#

传入参数#

3.2 查询确权存证信息#

3.2.1 查询存证数据标识#

接口定义#

传入参数#

一、合约使用说明

二、命名解释

三、接口详情

1、身份管理接口

1.1 配置管理权限

1.1.1. 配置管理权限

功能定位

调用限制

接口定义

传入参数

1.1.2. 回收管理权限

功能定位

调用限制

接口定义

传入参数

1.2 用户角色管理

1.2.1 添加用户

接口描述

接口定义

传入参数

1.2.2 查询用户

接口描述

接口定义

传入参数

1.2.3 添加用户角色

接口描述

接口定义

传入参数

1.2.4 回收用户角色

接口描述

接口定义

传入参数

2、存证相关接口

2.1 确权存证

2.1.1 新增确权存证

功能定位

接口定义

传入参数

2.1.2 追加可变数据存证

合约接口

传入参数

2.1.3 撤回确权存证

功能定位

接口定义

传入参数

2.1.4 新增授权存证

功能定位

接口定义

传入参数

2.1.5 撤回授权存证

功能定位

接口定义

传入参数

2.2 审查存证

2.2.1 新增审查存证

功能定位

调用限制

接口定义

传入参数

2.2.2 撤回审查存证

功能定位

调用限制

接口定义

传入参数

2.3 登记存证（二阶段）

3、查询相关接口

3.1 查询用户数据信息

3.1.1 查询用户数据数量

接口描述

接口定义

传入参数

3.1.2 查询用户数据列表

接口描述

接口定义

传入参数

3.2 查询确权存证信息

3.2.1 查询存证数据标识

接口定义

传入参数

3.2.2 查询确权存证信息