Provider API

Each API contains at least 3 parts: Description, Params, Return, for the verification of several API (e.g. did_login, did_requestCredentialDigest, did_requestCredentialContent, did_sign) we provide the Verification Method in the SDK respectively.

All Methods

• Provider API

  • All Methods

    • Authorization Method

      • requestAuth( )

      • isAuth( )

    • DID Request Method

      • getCurrentDid( )

      • did_login(param)

      • requestAuthAndLogin(param)

    • VC Request Method

      • requestCredentialDigest(params)

      • requestCredentialContent(params)

    • DID-Key Method

      • sign(param)

      • encrypt(params)

      • decrypt(params)

    • ZKP Method

      • generateZkp(params)

Authorization Method

requestAuth( )

public requestAuth(): Promise<boolean> {
    return this.request('wallet_requestAuth', undefined);
}

Description

This API is designed for websites to request authorization from Users. User permission is the premise of all interaction, if the website hasn't obtained User permission yet, it can not be able to use the following API to interact with the User.

If this API returns Error Code -32001, it means that the User rejects this request.

Return

• Boolean - whether the User request for authorization is successfully allowed.

---

isAuth( )

public isAuth(): Promise<boolean> {
    return this.request('wallet_isAuth', undefined);
}

Description

This API's return shows whether the authorization is allowed. It is used for developer to query the user's authorization permission status. If the query status is true, developer can continue to call other APIs. Otherwise, developer must first call wallet_requestAuth() to get permission.

Return

• Boolean - whether the user allows authorization already.

---

DID Request Method

getCurrentDid( )

public getCurrentDid(): Promise<RequestRpcs<'did_getCurrent'>['did_getCurrent'][1]> {
    return this.request('did_getCurrent', undefined);
  }

Description

As mentioned before, DID is the unique identifier of an entity. This API aims to fetch the current didUri in the zkID Wallet, which helps developers to identify each User.

Return

• DidInfo Object - an example is shown below:

export type DidInfo = {
  didUri: DidUrl;
  document: DidDocument;
  authenticationKey: HexString;
  encryptionKey: HexString[];
  attestationKey?: HexString;
  delegationKey?: HexString;
};

---

did_login(param)

  public didLogin(
    data: HexString | Uint8Array | string | number
  ): Promise<RequestRpcs<'did_login'>['did_login'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_login', { payload });
  }

Description

This API is for users to login the website with their DID. With this API, the user needs to make a signature on some message (given by the website) via the user's DID AuthenticationKey. Once the user has successfully signed, the API returns the result of the user's signature, and developers can verify the validity of the signature through the Verify Method in our SDK. If the verification passes, then the login request should be permitted.

If this API returns Error Code -32001, it means that the User rejects this request.

Param:

• data (required)

// data is the one to be signed
param: [{
    "data": "0x....."
}]

Return:

• HexString - the user's signature on that data

Usage Of Return

After receiving the HexString signature, developers need to verify its validity in order to check user's identity. In the SDK, we offer this verifyDidLogin function to help achieve that.

requestAuthAndLogin(param)

  public requestAuthAndLogin(
    data: HexString | Uint8Array | string | number
  ): Promise<RequestRpcs<'wallet_requestAuthAndLogin'>['wallet_requestAuthAndLogin'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('wallet_requestAuthAndLogin', { payload });
  }

Description

This API is used to request authorization from Users, and ask the User to sign on some specific data to achieve DID Login. You can see this API as the combination of requestAuth and did_login.

If the User hasn't give an authorization to the website, this function will request for the authorization first, and then do did_login.

If the User already give an authorization to the website, then this function does the same thing as did_login.

If this API returns Error Code -32001, it means that the User rejects this request.

Param:

• data (required)

// data is the one to be signed
param: [{
    "data": "0x....."
}]

Return:

• HexString - the user's signature on that data

Usage Of Return

After receiving the HexString signature, developers need to verify its validity in order to check user's identity. In the SDK, we offer this verifyDidLogin function to help achieve that.

VC Request Method

requestCredentialDigest(params)

  public requestCredentialDigest(
    challenge: string,
    ctypehash?: HexString,
    attester?: DidUrl
  ): Promise<VerifiablePresentation> {
    return this.request('did_requestCredentialDigest', { challenge, ctypehash, attester });
  }

Description

This API is used to obtain a Digest Disclosure of a credential, which won't reveal any details of other information. The return result contains some digest information(roothash, attested status, revoked status) and several helper information (including ctypeHash, owner, attester, signature)

If this API returns Error Code -32001, it means that the User rejects this request.

If this API returns Error Code -32801, it means that the Credential doesn't exist.

If this API returns Error Code -32010, it means that the User hasn't give any authorization to this website, the request is not legal.

Params:

• challenge (required): a random string

• ctypehash (optional),the ctypehash of credential, if passed, the wallet will only return the credential with the same ctypehash

• attester (optional): attester's DID Url

params_example: [{
    "challenge": "..."
    "ctypehash": "0x....",
    "attester": "...",
}]

Return:

• VerifiablePresentation

Usage Of Return

This verifyCredentialDigest method provided in our SDK can be used to check whether the Digest Disclosure is valid, whether the User is the Credential's Owner.

---

requestCredentialContent(params)

  public requestCredentialContent(
    challenge: string,
    contentKeys?: string[],
    ctypehash?: HexString,
    attester?: DidUrl
  ): Promise<VerifiablePresentation> {
    return this.request('did_requestCredentialContent', {
      challenge,
      contentKeys,
      ctypehash,
      attester
    });
  }

Description

This API is used to obtain a further disclosure of a credential, developers could use this API to achieve Selective Disclosure or All Credential Content Disclosure via passing different params.

If this API returns Error Code -32001, it means that the User rejects this request.

If this API returns Error Code -32801, it means that the Credential doesn't exist.

If this API returns Error Code -32802, it means that the Credential Metadata doesn't match.

Params:

• challenge (required): a random string

• contentKeys (optional): the content keys need to be disclosed

• ctypehash (optional),the ctypehash of credential, if passed, the wallet will only return the credential with the same ctypehash

• attester (optional): attester's DID Url

params_example: [{
    "challenge": "..."
    "contentKeys": ["...", "...", "..."],
    "ctypehash": "0x....",
    "attester": "...",
}]

Developers will get the Selective Disclosure result if they pass specific contentKeys into this API; Otherwise, if the field contentKeys is empty, they will obtain a All Credential Content Disclosure.

Return:

• VerifiablePresentation

Usage Of Return

This verifyCredentialContent method provided in our SDK can be used to check whether the Selective Disclosure or All Credential Content Disclosure is valid, whether the User is the Credential's Owner.

---

DID-Key Method

sign(param)

public sign(
    data: HexString | Uint8Array | string | number,
    keyId?: DidUrl
  ): Promise<RequestRpcs<'did_sign'>['did_sign'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_sign', { payload, keyId });
  }

Description

This API is for users to make a signature on some data via the user's DID AuthenticationKey. Once the user has successfully signed, the API returns the result of the user's signature, and developers can verify the validity of the signature through the Verify Method in our SDK.

If this API returns Error Code -32001, it means that the User rejects this request.

Param:

• data (required): data to be signed

• key_Id(optional): the key used to sign, if not specified, use authenticationkey by defalut.

// data is the one to be signed
param: [{
    "data": "0x....."
}]

Return:

• HexString - the user's signature on that data

---

encrypt(params)

  public encrypt(
    data: HexString | Uint8Array | string | number,
    receiver: DidUrl
  ): Promise<RequestRpcs<'did_encrypt'>['did_encrypt'][1]> {
    const message: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_encrypt', { message, receiver });
  }

Description

This API uses user's and peer's AgreementKey to encrypt data, can be used for build secret communication channel. Using this API, both parties of message transmission do not need to worry about message eavesdropping or leakage, encrypted messages can only be read through Decryption Method.

If this API returns Error Code -32001, it means that the User rejects this request.

Params:

• data (required) : the data to be encrypted

• receiver:(required): the DID Url of the receiver, used to encrypt

Return:

• HexString - the encryption result

---

decrypt(params)

  public decrypt(
    data: HexString | Uint8Array | string | number,
    sender: DidUrl
  ): Promise<HexString> {
    const message: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_decrypt', { message, sender });
  }

Description

This API uses user's and peer's AgreementKey to decrypt data, can be used for decrypt message transferred by secret communication channel.

If this API returns Error Code -32001, it means that the User rejects this request.

Params

• data (required) : the data to be decrypted

• sender:(required): the DID Url of the sender, used to decrypt

Return:

• HexString - the decryption result

ZKP Method

generateZkp(params)

  public generateZkp(
    params: RequestRpcs<'proof_generate'>['proof_generate'][0]
  ): Promise<RequestRpcs<'proof_generate'>['proof_generate'][1]> {
    return this.request('proof_generate', params);
  }

Description

This API is used to generate zero-knowledge proof with specific ZKP Program and VC.

The ZKP Program used should be passed as a parameter. Besides, the VC used to run such ZKP Program should also be specified via its ctypehash and attester.

Params

• ZkpGenRequest

  • ctype (optional) : the specified ctypehash of the VC

  • attester:(optional): the specified attester's DID Url

  • program :(required): String of the ZKP Program

Return:

• ZkpGenResponse

  • outputs - the execution result of the ZKP Program

  • starkproof - the zero-knowledge proof of running such ZKP Program

  • programHash - the ZKP Program's hash

  • ctype - the specified ctypehash of the VC

  • attester - the specified attester's DID Url