Identity SDK

Introduction

Overview

The Identity SDK is a client-side JS/TS SDK used to maintain users’ identities using the Decentralised Identity Paradigm (DID) by interacting with a set of contracts on Shibarium and other networks.

It is integrated with DID Registry Contract (can be deployed on any EVM chain), which is used to maintain a single store of the user’s identity information.

With the Identity SDK, developers are able to create and manage identities, and add verification methods and services.

Use Cases

This SDK can be used to create W3C-compliant DID-based identities for users. With decentralized identities, a lot of interesting use cases can be developed:

• Authentication and Single Sign-On (SSO): Users can authenticate to websites, dApps, or services without needing passwords, using their decentralized identity (like DID-based wallets).
• Decentralized Reputation Systems: In platforms like marketplaces or social networks, DID allows users to build and maintain their reputation across multiple ecosystems without a central authority managing the data.
• Verifiable Credentials and Digital Certificates: The SDK can issue, manage, and verify verifiable credentials (e.g., diplomas, certifications, or proof of identity), enabling trustless verification by any third party.
• Privacy: Users can share verified identity information (like KYC data) only when needed, maintaining control over their privacy.

Audience

Developers.

Installation

Prerequisites

To get started, you need to have the following installed on your machine:

• node.js
• npm/yarn/pnpm

Install the dependencies:

pnpm install

Compile the smart contracts from the main branch of identity-contracts:

pnpm compile

Build package at /lib with vite:

pnpm build:vite

Publish Locally, if the npm package is not available. First, install yalc and publish the package:

yalc push --sig

Then in the dependent repo, add identity-sdk:

yalc add identity-sdk
yalc link identity-sdk
pnpm install

note

Use Vite in dependent projects for the smoothest experience as Vite has native WASM support.

Getting started

Methods

This SDK provides methods to create, update, and revoke DIDs; add, delete, and retrieve verification methods and services; and manage identity spaces.

Constructor

Description

Creates a new instance of the IdentitySDK. It takes three parameters: a signer, a set of identity addresses, and a flag indicating whether to return data from methods.

create

create(params: SDKCreationParams)

Description

This method creates an instance of the IdentitySDK class with the provided parameters, including a signer object, identity addresses, network name (optional), and return data flag (optional). If not provided, it defaults to using mainnet as the network.

Parameters

parameter	required/optional	type	description
params	Required	SDKCreationParams	Object containing initialization parameters for the SDK.
params.signer	Required	Signer	Signer instance for signing transactions.
params.network	Optional	string	Network name (e.g., "mainnet", "testnet"). Defaults to "mainnet".
params.identityAddresses	Optional	IdentityAddresses	Custom identity addresses. If not provided, defaults based on the network.
params.returnData	Optional	boolean	Flag indicating if methods should return data. Defaults to false.

Example

createIdentity

createIdentity(aka: string, verificationMethods: VerificationMethod[], services: Service[], controllerAdr?: string)

Description

Creates a new DID with the specified properties and returns its string representation.

Parameters

parameter	required/optional	type	description
aka	Requested	string	A known-as (aka) identifier for the identity.
verificationMethods	Requested	VerificationMethod[]	Array of verification methods to associate with the DID.
services	Requested	Service[]	Array of services to associate with the DID.
controllerAdr	Optional	string	Controller address (defaults to current signer if not provided).

Returns: Promise<string>

Example

updateIdentity

updateIdentity(aka: string, verificationMethods: VerificationMethod[], services: Service[], controllerAdr?: string)

Description

Updates an existing DID with new property values.

Parameters

parameter	required/optional	type	description
aka	Requested	string	A known-as (aka) identifier for the identity.
verificationMethods	Requested	VerificationMethod[]	Array of updated verification methods.
services	Requested	Service[]	Array of updated services.
controllerAdr	Optional	string	Controller address (defaults to current signer if not provided).

Returns: Promise<string>

Example

revokeIdentity

revokeIdentity(aka: string, verificationMethods: VerificationMethod[], services: Service[], controllerAdr?: string)

Description

Revokes the current DID.

Parameters

parameter	required/optional	type	description
controllerAdr	Optional	string	Controller address (defaults to current signer if not provided).

Returns: Promise<string>

Example

addPubKey

addPubKey(verificationMethod: VerificationMethod, controllerAdr?: string)

Description

Adds a verification method to the current DID.

Parameters

parameter	required/optional	type	description
verificationMethod	Requested	VerificationMethod	Verification method to add to the DID.
controllerAdr	Optional	string	Controller address (defaults to current signer if not provided).

Returns: Promise<string>

Example

getPubKeys

getPubKeys(id: string)

Description

Retrieves all verification methods for a given DID.

Parameters

parameter	required/optional	type	description
id	Requested	string	DID identifier.

Returns: Promise<VerificationMethod[]>

Example

getPubKeysForVR

getPubKeysForVR(id: string, vrIndex: number)

Description

Retrieves verification methods for a specific verification relationship (VR) of a DID.

Parameters

parameter	required/optional	type	description
id	Requested	string	DID identifier.
vrIndex	Requested	number	Index of the verification relationship to retrieve.

Returns: Promise<VerificationMethod[]>

Example

deletePubKey

deletePubKey(index: number, controllerAdr?: string)

Description

Deletes a verification method at the specified index from the current DID.

Parameters

parameter	required/optional	type	description
index	Requested	number	Index of the public key in the DID Document to remove.
controllerAdr	Optional	string	Controller address (defaults to current signer).

Returns: Promise<Void[]>

Example

addService

addService(service: Service, controllerAdr?: string)

Description

Adds a service to the current DID.

Parameters

parameter	required/optional	type	description
service	Requested	Service	A service object to add to the DID.
controllerAdr	Optional	string	Controller address (defaults to current signer).

Returns: Promise<Void>

Example

getServices

getServices(id: string)

Description

Retrieves all services for a given DID.

Parameters

parameter	required/optional	type	description
id	Requested	string	DID identifier.

Returns: Promise<Service[]>

Example

deleteService

deleteService(index: number, controllerAdr?: string)

Description

Deletes a service at the specified index from the current DID.

Parameters

parameter	required/optional	type	description
index	Requested	number	Index of the service in the DID Document to remove.
controllerAdr	Optional	string	Controller address (defaults to current signer).

Returns: Promise<void | string>

Example

getIdentity

getIdentity(id: string)

Description

Resolves a given DID and retrieves its associated data in the form of a DIDDoc object.

Parameters

parameter	required/optional	type	description
id	Requested	string	DID identifier.

Returns: Promise<DIDDoc>

Example

contractIDFromController

contractIDFromController(controller: string)

Description

Derives a DID from a given controller address.

Parameters

parameter	required/optional	type	description
controller	Requested	string	Controller Ethereum address.

Returns: Promise<string>

Example

idFromAddress

idFromAddress(adr: string, toPlainText: boolean = false)

Description

Derives a DID from a given address. Optionally converts the resulting DID to plain text.

Parameters

parameter	required/optional	type	description
adr	Requested	string	Ethereum address from which to derive the DID.
toPlainText	Requested	boolean	Whether to return DID in plain text format.

Returns: string

Example

idFromSigner

idFromSigner(signer: Signer, toPlainText: boolean = false)

Description

Derives a DID from a given signer.

Parameters

parameter	required/optional	type	description
signer	Requested	Signer	Signer instance to derive the DID from.
toPlainText	Requested	boolean	Whether to return DID in plain text format.

Returns: Promise<string>

Example

isIdentityRegistered

isIdentityRegistered(id: string)

Description

Checks whether a given DID is registered or not.

Parameters

parameter	required/optional	type	description
id	Requested	string	DID identifier.

Returns: Promise<boolean>

Example

Configuration options

Deploy

To deploy the contracts:

pnpm deploy:contracts

Start fhEVM

For local testing, start a local fhEVM docker container that includes everything needed to deploy FHE-encrypted smart contracts

# In one terminal, keep it opened
# The node logs are printed
pnpm fhevm:start

To stop:

pnpm fhevm:stop

Get some native coins

If the testnet is not available, this command will provide coins. Replace ADDRESS with the address of the public key you have placed at .env.

docker exec -i fhevm faucet ADDRESS

Compile from local identity-contracts

Compile the smart contracts from a directory/repository named identity-contracts, placed at the same level as this repo:

pnpm compile:cp

Run Account Abstraction Tests

To run the tests, type:

pnpm test:aa

To run only DID tests and not AA tests:

pnpm test:did

note

AA SDK tests only work with Puppynet by default.