Skip to content

DID Service

The DidService module provides tools to create, resolve, update, and delete Decentralized Identifiers (DIDs) on the IDCHAIN blockchain. It supports both simple DIDs (for claimers) and full DIDs (for attesters with additional keys for credentials and delegation).

Overview

DID Service helps developers:

  • Create DID for a Claimer (basic authentication key only).
  • Create DID for an Attester (authentication, encryption, assertion, delegation keys).
  • Attach service endpoints (e.g., for publishing credentials).
  • Resolve DID Documents.
  • Delete DIDs when no longer needed.

All DID operations are DID-authenticated, meaning transactions are signed using the DID’s keys and submitted with an authorized account.

API Reference

Create Did Claimer

DidService.createDidClaimer(submitterAccount, { authentication }, signCallback): Promise<DidInfo>

Creates a Claimer DID (simplified DID with only an authentication key).

Parameters:

  • submitterAccount (UidKeyringPair): The account authorized to submit the DID transaction.
  • authentication (NewDidVerificationKey): Object with publicKey and type (e.g., "ed25519").
  • signCallback (GetStoreTxSignCallback): Async callback used to sign the DID creation payload.

Returns:

  • DidInfo: Object containing:
  • document: UidDocument (the created DID Document).
  • metadata: Extra chain-related info (e.g., deactivation status).

Example:

const claimerKeys = await AccountService.generateKeypairs(mnemonic);
const signCallback = async ({ data }) => ({
  keyType: "ed25519",
  signature: claimerKeys.authentication.sign(data),
});

const didInfo = await DidService.createDidClaimer(
  accountClaimer,
  {
    authentication: {
      publicKey: claimerKeys.authentication.publicKey,
      type: claimerKeys.authentication.type,
    },
  },
  signCallback
);

console.log("Claimer DID URI:", didInfo.document.uri);

Create Did Attester

DidService.createDidAttester(submitterAccount, { authentication, keyAgreement, assertionMethod, capabilityDelegation }, signCallback): Promise<UidDocument>

Creates a Full Attester DID with multiple keys for different purposes:

  • authentication – Authentication & signing.
  • keyAgreement – Encryption.
  • assertionMethod – Credential issuance.
  • capabilityDelegation – Delegation and authorization.

Parameters:

  • submitterAccount (UidKeyringPair): Account submitting the transaction.
  • Keys(objects): Each containing publicKey and type.
  • signCallback (GetStoreTxSignCallback): Async callback for signing.

Returns:

  • UidDocument: The full DID Document stored on-chain.

Example:

const keys = await AccountService.generateKeypairs(mnemonic);
const signCallback = async ({ data }) => ({
  keyType: "ed25519",
  signature: keys.authentication.sign(data),
});

const attesterDid = await DidService.createDidAttester(
  accountAttester,
  {
    authentication: {
      publicKey: keys.authentication.publicKey,
      type: keys.authentication.type,
    },
    keyAgreement: {
      publicKey: keys.keyAgreement.publicKey,
      type: keys.keyAgreement.type,
    },
    assertionMethod: {
      publicKey: keys.assertionMethod.publicKey,
      type: keys.assertionMethod.type,
    },
    capabilityDelegation: {
      publicKey: keys.capabilityDelegation.publicKey,
      type: keys.capabilityDelegation.type,
    },
  },
  signCallback
);

console.log("Attester DID URI:", attesterDid.uri);

Resolve Did

DidService.resolveDid(account: UidKeyringPair): Promise<UidDocument | null>

Resolves a DID Document for a given account.

Parameters:

  • account (UidKeyringPair): Account whose DID will be resolved.

Returns:

  • UidDocument if found, null if DID does not exist or is deactivated.

Example:

const resolved = await DidService.resolveDid(accountAttester);
if (resolved) {
  console.log("Resolved DID Document:", resolved);
}

Delete Did

DidService.deleteDid(submitterAccount, fullDid): Promise<void>

Deletes a DID from the blockchain. Must be signed by the DID authentication key and submitted by the authorized account.

Parameters:

  • submitterAccount (UidKeyringPair): Account authorized to perform the deletion.
  • fullDid (Uid): DID URI to delete.

Returns:

  • void (throws error if failed).

Example:

await DidService.deleteDid(accountClaimer, userDid.document.uri);
console.log("DID deleted successfully");

Usage Example

import { AccountService, DidService } from "@idchain-sdk";

async function manageDids() {
  const { mnemonic, account } = await AccountService.generateAccount();
  const keys = await AccountService.generateKeypairs(mnemonic);

  // Create an Attester DID
  const attesterDid = await DidService.createDidAttester(
    account,
    {
      authentication: {
        publicKey: keys.authentication.publicKey,
        type: keys.authentication.type,
      },
      keyAgreement: {
        publicKey: keys.keyAgreement.publicKey,
        type: keys.keyAgreement.type,
      },
      assertionMethod: {
        publicKey: keys.assertionMethod.publicKey,
        type: keys.assertionMethod.type,
      },
      capabilityDelegation: {
        publicKey: keys.capabilityDelegation.publicKey,
        type: keys.capabilityDelegation.type,
      },
    },
    async ({ data }) => ({
      keyType: "ed25519",
      signature: keys.authentication.sign(data),
    })
  );

  console.log("Attester DID:", attesterDid.uri);

  // Attach a service endpoint
  await DidService.setServiceDid(
    attesterDid.uri,
    account,
    "#vc-endpoint",
    "https://gateway.example"
  );

  // Resolve and then delete DID
  const resolved = await DidService.resolveDid(account);
  console.log("Resolved DID:", resolved?.uri);

  await DidService.deleteDid(account, attesterDid.uri);
  console.log("DID removed");
}

manageDids();

Error Handling

  • Unresolved DID: deleteDid throw if the DID cannot be resolved ("Could not resolve DID").
  • Deactivated DID: resolveDid returns null if the DID is deactivated or missing.
  • Signing Errors: If signCallback fails or keys are invalid, DID creation will throw.