Skip to main content

Identity Wallet

An identity wallet holds the identity of the user and carries the following components:

  • Key Management Store (kms): it allows the user to sign data using keys and offers the storage that is allocated to these keys. It’s an abstraction that allows for communication with different kinds of key storage.

  • Data Storage Interface: it is an interface that allows you to communicate with Credential storage, Identity storage, Merkle tree storage, and State interfaces. This interface lets you create an identity for the user.

  • Credential Wallet: it contains business logic on the top of the Credential storage. An Identity Wallet uses a Credential Wallet for mapping the credentials issued to an Identity.

The methods described below let you create and manage an identity wallet.

Create an Identity using createIdentity()​

This method creates an Auth Baby Jubjub Credential (for signing on behalf of an identity) and an Identifier for an Identity. The Baby Jubjub Key is the elliptic curve implementation used in Iden3.

Firstly, to create an Identity, the three Merkle trees (Claims tree, Revocation tree, and Roots of Root tree) are created. Auth BJJ key is then added to the Claims tree. The hash of these three trees creates a root that is used to create an Identity State. The first state created is called the Genesis State and it is from this Genesis State that a unique Identifier (in the DID format) is generated.

The root of the three trees is used to create a Merkle Tree Proof (MTP) which verifies the existence of a credential on the Merkle tree.

createIdentity(opts: IdentityCreationOptions): Promise<{ did: DID; credential: W3CCredential }>;

IdentityCreationOptions lets you select the following options for creating an Identity:

interface IdentityCreationOptions {
  method?: DidMethod;
  blockchain?: Blockchain;
  networkId?: NetworkId;
  revocationOpts: {
    id: string;
    type: CredentialStatusType;
    nonce?: number;
  };
  seed?: Uint8Array;
}

where method is the type of did method used to create an identity.

seed is a random/non-random number used to generate the BJJ key-pair.

revocationOpts contains the way the status of the Auth BJJ credential can be fetched.

The createIdentity method returns a did (Decentralised Identifier) in the DID format and a credential based on the W3C standard for a Verifiable Credential.

note

It is worth noting that did is a Decentralized Identifier associated with an identity and enables verifiable identities. A did could be a person, thing, organization, or even an abstract entity. The controller of the did can prove that it is the real owner of the identity without the need to seek permissions/approvals from any centralized authority.

A did is expressed in the following format, as per w3.org standards:

did: did method: did method-specific identifier

info

To know more about Iden3 core elements (Baby Jubjub Key, Credentials, and Identifiers), read the Iden3 tutorials.

Click here for the API Reference.

Create Profiles using createProfile()​

This method creates profiles based on the genesis identifier. To keep the user's identity hidden from a Verifier, we can generate different profiles from his/her existing identifier. Therefore, a user has the option to select a particular profile for a particular Verifier so that his real identity is not revealed.

createProfile(did: DID, nonce: number, verifier: string): Promise<DID>;

where did is the DID from which a profile is generated.

nonce is a unique integer used to generate a profile.

verifier is the verifier identity/alias in the string format.

This method returns a profile ID.

Click here for the API Reference.

Other methods to work with profiles:

  /**
   *
   * gets profile identity by genesis identifiers
   *
   * @param {string} did - genesis identifier from which profile has been derived
   * @returns `{Promise<Profile[]>}`
   */
  async getProfilesByDID(did: DID): Promise<Profile[]> {
    return this._storage.identity.getProfilesByGenesisIdentifier(did.string());
  }

  /**
   *
   * gets profile identity by verier
   *
   * @param {string} verifier - verifier for which profile has been created
   * @returns `{Promise<Profile[]>}`
   */
  async getProfileByVerifier(verifier: string): Promise<Profile | undefined> {
    return this._storage.identity.getProfileByVerifier(verifier);
  }

Generate Key using generateKey() method​

This method creates a new Baby Jubjub or ECDSA type of key.

 generateKey(keyType: KmsKeyType): Promise<KmsKeyId>;

where keyType is the type of key supported by the Key Management System.

This method returns a Promise<KmsKeyId> which generates the key of the type mentioned in keyType parameter.

Click here for the API Reference.

Issue Credentials using issueCredential() method​

This method lets an Issuer grant a credential to a user as requested by the user.

  issueCredential(issuerDID: DID, req: CredentialRequest,opts?:options): Promise<W3CCredential>;

where issuerDID is the identifier of the Issuer in the did format we described earlier.

opts are merklization options. If you use IPFS schemas, you must pass IPFS node or gateway URL.

This method returns a core claim which is then added to the Merkle tree and this claim is then transformed into a Verifiable Credential based on the W3C standards and issued to the user. The core claim is signed by the Issuer and a BabyJubjub Signature Proof is also added to the credential.

Click here for the API Reference.

Create a Tree Model using getDIDTreeModel() method​

This method creates a tree model for a did; the model consists of a Claims tree, a Revocation tree, a Roots of Root tree, and the identity hash of the state created from these trees.

getDIDTreeModel(did: DID): Promise<TreesModel>;

This method returns a Promise<TreesModel> which returns the three Merkle trees from the database storage.

Click here for the API Reference.

Generate Merkle Tree proof using generateCredentialMtp() Method​

This method generates Merkle Tree Proof (MTP) for the inclusion or non-inclusion of a credential in the Claims tree by following the path from the leaf to the root in the given Merkle tree storage.

info

To know more about the credential's inclusion in a Merkle tree, read our Iden3 core specification tutorials.

  generateCredentialMtp(
    did: DID,
    credential: W3CCredential,
    treeState?: TreeState
  ): Promise<MerkleTreeProofWithTreeState>;

where did is the DID of the Issuer that issued the credential to the user.

credential is the Verifiable Credential (in the W3C format) used to generate the MTP.

TreeState is the tree's state used to generate the MTP. If we do not pass the TreeState parameter, the method considers the latest state of the Identity for creating MTP.

This method returns MerkletTreeProof along with the TreeState for which the proof is generated.

Click here for the API Reference.

Generate Non-Revocation Merkle Tree Proof using generateNonRevocationMtp() method​

This method generates a Merkle Tree Proof for the inclusion or non-inclusion of the revocation nonce of a credential in the Revocation Tree.

  generateNonRevocationMtp(
    did: DID,
    credential: W3CCredential,
    treeState?: TreeState
  ): Promise<MerkleTreeProofWithTreeState>;

where did is the DID of the Issuer that issues the credential.

credential is the Verifiable Credential (in the W3C format) used to generate the Non-Revocation Merkle Tree Proof. TreeState is the tree's state used to generate the Non-Revocation MTP. If we do not pass the TreeState parameter, the method considers the latest state of the Identity for creating MTP.

This method returns MerkletTreeProof along with the TreeState for which proof is generated.

note

To know more about the Revocation of a credential, read here.

Click here for the API Reference.

Sign Credential Using Sign() Method​

This method signs a payload of an arbitrary size with an Auth BJJ Credential, which contains a public key and a reference to the Key Management Store (where we store and fetch a private key for the credential).

sign(payload: Uint8Array, credential: W3CCredential): Promise<Signature>;

where payload is any arbitrary string or an unsigned integer array.

credential is Auth BJJ Credential in the W3C format.

This method returns the signature object.

Click here for the API Reference.

Sign a Challenge using signChallenge() method​

This method signs a big integer with the Auth BJJ Credential, which identifies a key for signing.

signChallenge(payload: bigint, credential: W3CCredential): Promise<Signature>;

where payload is a big number (bigint). A big number is used in cryptography to prevent anyone from figuring them out.

credential is Auth BJJ Credential in the W3C format.

This method returns the signature object.

Click here for the API Reference.

Revoke Credential using revokeCredential() method​

This method generates a Revocation Nonce for a credential that we need to revoke (or render invalid due to its expiry, loss, or any other reason).

revokeCredential(issuerDID: DID, credential: W3CCredential): Promise<number>;

where issuerDID is the Issuer's identifier.

credential is the W3C Credential that needs to be revoked.

This method returns the Revocation Nonce of the credential.

Click here for the API Reference.

Generate Iden3 Sparse Merkle Tree Proof using generateIden3SparseMerkleTreeProof() Method​

This method generates the Iden3 SparseMerkleTree (SMTP) proof that an Issuer state of a specific credential is included in the Merkle Tree or not.

With the IssueCredential() method, a Credential is generated along with the Signature Proof. This credential is then added to the Claims Merkle tree and therefore, the state of the tree is changed. For this, another proof called SMTP is required. This proof generates the changed state of the tree by taking Issuer DID, transaction data, and the list of credentials that are part of the changed state as the input parameters. The JS SDK updates the credential with this SMT Proof, which is included in the state, the transaction data, and the Issuer.

generateIden3SparseMerkleTreeProof(
    issuerDID: DID,
    credentials: W3CCredential[],
    txId: string,
    blockNumber?: number,
    blockTimestamp?: number
  ): Promise<W3CCredential[]>;

where issuerDID is the Issuer's identifier.

credentials is the list of Verifiable Credentials required to generate the proof.

txId is a hash of the transaction for which the state transition is done.

blockNumber is the number of the block in which the state transition has been done.

blockTimestamp is the timestamp of the block at which the state transition has been done.

This method returns a list of credentials along with a Sparse Merkle Tree Proof.

Click here for the API Reference.

Publish State to Reverse Hash Service with publishStateToRHS() Method​

If we are using a browser, we need to fetch the revocation status via rhsURL (Reverse Hash Service URL) by pushing the state update to this URL.

The publishStateRHS method publishes the updated state of the tree to the Reverse Hash Service.

publishStateToRHS(issuerDID: DID, rhsURL: string, revokedNonces?: number[]): Promise<void>;

where issuerDID is the did of the Issuer.

rhsURL is the Reverse Hash Service URL.

revokedNonces are the nonces of the revoked credentials.

Click here for the API Reference.

Get Core Claim Representation with getCoreClaimFromCredential() Method​

This method extracts the core claim from either the Signature proof or the Merkle Tree Proof. If we have both types of proofs for the credential, this method extracts the core representation from the Merkle Tree Proof.

getCoreClaimFromCredential(credential: W3CCredential): Promise<Claim>;

where credential is the Verifiable Credential in the W3C format that is used to extract the core representation of the claim.

The method returns the core claim representation of the credential.

Click here for the API Reference.