Skip to content

Web3Names Service

The Web3Names module provides tools to claim, resolve, query credentials, and release Web3Names on the IDCHAIN blockchain. Web3Names are human-readable aliases (e.g., johndoe-claimer) that can be linked to DIDs, making them easier to share and discover.

Overview

Web3Names Service allows developers to:

  • Claim a Web3Name for a DID (must meet format rules).
  • Resolve a Web3Name to fetch the linked DID Document.
  • Query published credentials associated with a Web3Name.
  • Release a Web3Name (unlink and free it for others).

All operations are performed with on-chain verification and Web3Name uniqueness guarantees.

Naming Rules

A valid Web3Name must:

  • Contain only lowercase letters (a-z), digits (0-9), hyphen (-), and underscore (_).
  • Be between 3 and 32 characters long.
  • Be unique on the blockchain.
  • Match regex: /^[a-z0-9-_]{3,32}$/

API Reference

Claim

Web3Names.claim(userDid, submitterAccount, name): Promise<void>

Claims a new Web3Name for a DID.

Parameters:

  • userDid (UidDocument): The DID Document for which to claim the name.
  • submitterAccount (UidKeyringPair): The account authorized to submit the transaction.
  • name (string): Desired Web3Name (must pass format validation).

Returns:

  • void (throws error if invalid name or name already taken).

Example:

await Web3Names.claim(userDid.document, userAccount, "johndoe-claimer");
console.log("Web3Name claimed successfully");

Resolve

Web3Names.resolve(web3Name): Promise<UidDocument>

Resolves a Web3Name to fetch its associated DID Document.

Parameters:

  • web3Name (string): The Web3Name to resolve.

Returns:

  • UidDocument: The DID Document linked to the Web3Name.

Example:

const didDoc = await Web3Names.resolve("johndoe-claimer");
console.log("Resolved DID Document:", didDoc);

Release

Web3Names.release(userDid, submitterAccount): Promise<void>

Releases (de-registers) a Web3Name, freeing it for reuse by others.

Parameters:

  • userDid (UidDocument): The DID Document currently owning the Web3Name.
  • submitterAccount (UidKeyringPair): The authorized account.

Returns:

  • void

Example:

await Web3Names.release(userDid.document, userAccount);
console.log("Web3Name released");

Full Usage Example

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

async function manageWeb3Names() {
  const { mnemonic, account: userAccount } = await AccountService.generateAccount();

  const userDidInfo = await DidService.createDidClaimer(userAccount, {
    authentication: { publicKey: userAccount.publicKey, type: "ed25519" },
  }, async ({ data }) => ({
    keyType: "ed25519",
    signature: userAccount.sign(data),
  }));

  const userDid = userDidInfo.document;

  // Claim a Web3Name
  const web3Name = "johndoe-claimer";
  await Web3Names.claim(userDid, userAccount, web3Name);
  console.log(`Web3Name "${web3Name}" claimed`);

  // Resolve DID from Web3Name
  const resolvedDid = await Web3Names.resolve(web3Name);
  console.log("Resolved DID Document:", resolvedDid);

  // Fetch published credentials (if any)
  try {
    const publishedCreds = await Web3Names.queryPublishedCredentials(web3Name);
    console.log("Published Credentials:", publishedCreds);
  } catch (err) {
    console.log("No credentials found or fetch failed:", err);
  }

  // Release Web3Name
  await Web3Names.release(userDid, userAccount);
  console.log(`Web3Name "${web3Name}" released`);

Error Handling

  • Invalid Web3Name: Throws if the name does not match the allowed pattern.
  • Unresolved DID: queryPublishedCredentials throws if DID cannot be resolved.
  • Revoked Credentials: Fetch operation will reject if any credential is invalid.
  • Endpoint Errors: If IPFS/HTTP endpoint is unreachable or invalid JSON is returned.
  • DID Service: Create and manage DIDs linked to Web3Names.
  • Credential Service: Issue credentials tied to the DID associated with the Web3Name.