SDK接入
一、合约使用说明
1、本合约在多条链上有部署，链的底层架构不一样，引入的SDK和SDK的初始化会有所差异。如果链底层链采用的是FISCO BCOS V3框架，接口调用的具体方法参考FISCO BCOS相关文档，详见：交易构造与调用 。如果链底层采用长安链底层技术架构，接口调用方法可以参考长安链官方的开发应用文档。两种链底层的调用方 法都可以参考第四部分的示例程序。 2、存证合约采用Solidity 0.8版本进行编写，本文档的接口均基于此基础之上。 3、由于区块链的异步性，事务类型的交易接口，只返回当前交易的Hash，具体的接口描述中不再说明。 4、本合约通过事件机制获取链上交易的执行结果，具体使用方法，详见第四部分的示例程序。
二、命名解释
| 命名 | 描述 |
|---|---|
| evidenceId | 存证交易返回的唯一ID |
| owner | 用户信息和分类代码拼接后的哈希代码，生成规则如下：将用户证件号用sha256处理后的值用“_”与分类ID连接，将连接后的字符串再用sha256进行哈希 |
三、接口详情
1、颁发存证登记
方法描述
颁发方在保存好文件之后，使用文件的哈希值进行上链登记到具体用户下。
方法定 义
function create(bytes32 owner, string calldata org, uint256 category, bytes32 hash, string calldata code, uint256 status, string calldata metadata) public returns (uint256);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| owner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
| org | string | 颁发机构 |
| category | uint256 | 分类索引 |
| hash | bytes32 | 文件内容哈希 |
| code | string | 文件编号 |
| status | uint256 | 文件状态索引 |
| metadata | string | 元数据，建议使用JSON编码 |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
2、更新存证状态
方法描述
将存证的状态更新为新状态，只有颁发方能调用。
方法定义
function updateStatus(uint256 evidenceId, uint256 newStatus) public;参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
| newStatus | uint256 | 状态索引 |
3、转移存证所有人
方法描述
将存证转移给新的用户，只有合约管理员能调用。用于存证紧急管理等场景。
方法定义
function transfer(uint256 evidenceId, bytes32 newOwner) public onlyOwner;参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
| newOwner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
4、查询用户拥有存证数量
方法描述
查询用户在某一分类下存证数量
方法定义
function balanceOf(bytes32 owner) public view returns (uint256);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| owner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| balance | uint256 | 存证数量 |
5、查询用户当前状态版本
方法描述
查询用户在某一分类下的状态版本，用于加速查询。如果上一 次查询版本和当前版本一样，则不需要再次遍历，使用缓存即可。
方法定义
function versionOf(bytes32 owner) public view returns (uint256);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| owner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| version | uint256 | 版本数字 |
6、查询存证的创建地址
方法描述
查询某一个存证的颁发方地址。
方法定义
function creatorOf(uint256 evidenceId) public view returns (address);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| creator | address | 颁发方地址 |
7、查询存证是否被用户拥有
方法描述
查询某一个存证是否被用户拥有。
方法定义
function isOwnedBy(uint256 evidenceId, bytes32 owner) public view returns (bool);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
| owner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| owned | bool | 是否被拥有 |
8、查询存证详情
方法描述
根据存证ID查询存证详情。
方法定义
function evidenceById(uint256 evidenceId) public view returns (string memory org, uint256 category, bytes32 hash, string memory code, uint256 status, string memory metadata, uint256 createTime);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| org | string | 颁发机构 |
| category | uint256 | 分类索引 |
| hash | bytes32 | 文件内容哈希 |
| code | string | 文件编号 |
| status | uint256 | 文件状态索引 |
| metadata | string | 元数据 |
| createTime | uint256 | 创建时间的时间戳 |
9、查询存证是否被用户拥有
方法描述
根据索引查询存证ID，用于遍历用户的所有存证。
方法定义
function evidenceIdByIndex(bytes32 owner, uint256 index) public view returns (uint256);参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| owner | bytes32 | 将用户信息和分类代码拼接后的哈希代码 |
| index | uint256 | 索引 |
响应参数说明
| 参数 | 类型 | 描述 |
|---|---|---|
| evidenceId | uint256 | 存证ID |
四、调用示例
创建存证调用示例(java)
查询存证调用示例(java)
修改于 2025-03-27 11:31:36