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

SDK接入

一、合约使用说明#

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

二、命名解释#

针对部分公共的参数命名,本章节做详细说明,后续章节不再单独说明:
命名描述
BIDBlockchain based Identity,即链上身份,用于链上的数字身份识别,标识方式为:bid:method:identity,如用公钥标识的方式为:bid:key:1234567890
IDPid provide,简称IDP,即身份提供方,有权为普通用户颁发身份证明。如CA机构可以为用户颁发数字证书,学校可以为学生颁发成绩证书等。
usciUnified Social Credit Identifier,中国境内企业的统一社会信用代码

三、接口详情#

1、登记IDP身份#

方法描述#

IDP首先要作为普通用户进行BID初始登记,登记完成后,由权威机构对IDP身份进行认证。

方法定义#

    /**
     * register idp, can be called by anyone, will only be valid after been granted
     * @param bid, bid to be registered
     * @param usci, unified social credit identifier
     * @param name, company or organization name
     * Emits {IdpCreated} event
     */
    function registerIdp(string calldata bid, string calldata name, string calldata usci) public;

参数说明#

参数是否必传描述
bid是待登记IDP的bid
usci是机构统一社会信用代码
name是机构全称

2、认证IDP身份#

方法描述#

由权威机构对IDP角色进行认证。

方法定义#

   /**
     * grant idp, can only be called by admin
     * @param bid, bid of idp to be granted
     * @param idpType, type of idp
     * Emits {IdpGranted} event
     */
    function grantIdpRole(string calldata bid, uint256 idpType) public onlyRole(DEFAULT_ADMIN_ROLE);

请求参数说明#

参数是否必传描述
bid是待给予认证IDP的bid
idpType是IDP的类型, 0为CA机构

3、取消IDP认证#

方法描述#

由权威机构收回机构的IDP角色。

方法定义#

    /**
     * revoke idp grantee, can only be called by admin
     * @param bid, bid of idp to be granted
     * Emits {IdpRevoked} event
     */
    function revokeIdpRole(string calldata bid) public onlyRole(DEFAULT_ADMIN_ROLE);

请求参数说明#

参数是否必传描述
bid是待取消认证IDP的bid

4、登记BID身份#

方法描述#

用户需要首先在链上登记BID身份,登记完成后,由IDP进行认证。

方法定义#

    /**
     * register bid, can be called by anyone, will only be valid after been certificated
     * @param bid, bid to be registered
     * @param socialCode, personal-sha256(id card number), business-unified social credit identifier
     * @param name, personal-sha256(real name), business-company or organization name
     * @param userType, 0-personal, 1-business
     * Emits {BidCreated} event
     */
     function registerBid(string calldata bid, string calldata name, string calldata socialCode, IdentityType userType) public;

请求参数说明#

参数是否必传描述
bid是待登记的bid
socialCode是社会身份编码:个人用户为身份证号码;机构用户为统一社会信用代码(usci)的明文。
name是个人用户为姓名;机构用户为机构名称的明文。
type是用户类型,0为个人用户,1为机构用户

5、认证BID身份#

由IDP机构认证其他用户的社会身份,实现公钥地址与用户法定身份的绑定。

方法定义#

    /**
     * certificate bid, can only be called by idp, and when the bid is not certificated or exceeded the validity
     * @param bid, bid to be certificated
     * @param validity, unix timestamp of the certification is valid
     * @param comment, comment message for the certification
     * Emits {BidCertificated} event
     */
    function certificateBid(string calldata bid, uint256 validity, string calldata comment) public onlyRole(IDP_ROLE);

请求参数说明#

参数是否必传描述
bid是待认证的bid
validity是认证有效期,格式为:毫秒级时间戳
comment是认证备注

6、取消BID认证#

方法描述#

IDP机构取消对某个bid的社会身份认证,只能由该bid被认证的IDP调用。

方法定义#

   /**
     * revoke bid certification, can only be called by verification idp, and when the bid is certificated and not exceeded the validity
     * @param bid, bid which owns the verification to be revoked
     * @param comment, comment message for the revoke
     * @emit BidCertificationRevoked
     */
    function revokeBidCertification(string calldata bid, string calldata comment) public onlyRole(IDP_ROLE);

请求参数说明#

参数是否必传描述
bid是待取消认证的bid
comment是取消认证备注

7、查询BID信息#

方法描述#

查询bid对应的身份信息及认证信息。如果bid未登记则报错。

方法定义#

    /**
     * query bid information
     * @param bid: bid to query
     * @return userType, 0-personal, 1-business
     * @return socialCode, personal-sha256(id card number), business-unified social credit identifier
     * @return name, personal-sha256(real name), business-company or organization name
     * @return publicKey, bid creator address
     * @return idpBid, bid of the verification idp
     * @return comment, comment message for the certification or revocation
     * @return validity, unix timestamp of the certification is valid
     * @return verified, whether the bid is verified, will be false if validity is exceeded
     * @return verifiedAt, verification or revocation timestamp
     */
    function queryBid(string calldata bid) public view returns (IdentityType userType, string memory socialCode, string memory name, address publicKey, string memory idpBid, string memory comment, uint256 validity, bool verified, uint256 verifiedAt);

请求参数说明#

参数是否必传描述
bid是待查询的bid

响应参数说明#

参数是否必传描述
userType是用户类型,0为个人用户,1为机构用户
socialCode是社会身份编码:个人用户为身份证号码的hash值;机构用户为统一社会信用代码(usci)的明文。
name是个人用户为姓名的hash值;机构用户为机构名称的明文。
publicKey是登记bid的用户链地址
idpBid是进行认证的IDP的bid
comment是认证或者取消认证的备注
validity是认证有效期,格式为:毫秒级时间戳
verified是BID身份是否认证
verifiedAt是BID身份认证时间,格式为:毫秒级时间戳

9、查询IDP信息#

方法描述#

查询bid对应的IDP认证信息。如果bid不是IDP或者IDP未通过认证则报错。

方法定义#

   /**
     * query idp information
     * @param bid, bid to query
     * @return idpType, type of idp
     * @return usci, unified social credit identifier
     * @return name, company or organization name
     * @return publicKey, idp creator address
     */
    function queryIdp(string calldata bid) public view returns (uint256 idpType, string memory usci, string memory name, address publicKey);

请求参数说明#

参数是否必传描述
bid是待查询的bid

响应参数说明#

参数是否必传描述
idpType是IDP的类型, 0为CA机构
usci是机构统一社会信用代码
name是机构全称
publicKey是登记idp的机构链地址

#

四、调用示例#

为了方便开发者对智能合约的调用,FISCO BCOS官方提供了生成客户端代码的工具,通过该工具为本链上数字身份合约生成的java客户端代码可通过如下地址下载:链上数字身份合约的SDK和java示例代码,开发者可以参考下面的示例代码进行开发。

登记Bid调用示例(java)#

查询Bid详情调用示例(java)#

修改于 2024-05-17 07:17:48
上一页
SDK接入
下一页
SDK接入
Built with