Skip to content

Account Service

The AccountService module provides utilities to generate blockchain accounts and keypairs for interacting with the IDCHAIN network.
It supports mnemonic-based account creation, keypair generation for DID operations, and automatic funding (via faucet token transfer) for new accounts.

Overview

This service helps developers:

  • Generate new accounts (with mnemonic and address).
  • Derive accounts from existing mnemonics.
  • Generate specialized keypairs for DID creation (authentication, key agreement, assertion, delegation).

The generated keys are compatible with all other IDCHAIN modules (DID, Credential, Web3Names).

API Reference

GenerateAccount

AccountService.generateAccount(): Promise<{ mnemonic: string; account: UidKeyringPair; }>

Generates a new blockchain account with a random mnemonic, derives its keypair, and automatically requests a token transfer for initial balance.

Returns:

  • mnemonic: The 12-word mnemonic phrase (string).
  • account: A UidKeyringPair object containing:
  • address: SS58-formatted blockchain address.
  • sign(data: Uint8Array): Uint8Array: Signing method.

Example:

const { mnemonic, account } = await AccountService.generateAccount();
console.log("Mnemonic:", mnemonic);
console.log("Address:", account.address);

GetAccount

AccountService.getAccount(mnemonic: string): Promise<UidKeyringPair>

Derives a blockchain account keypair from an existing mnemonic.

Parameters:

  • mnemonic (string, required): A valid mnemonic phrase (12/24 words).

Returns:

  • UidKeyringPair: Same as above, with signing capability.

Throws:

  • Error("Mnemonic is not provided or invalid") if mnemonic is missing or not a string.

Example:

const existingAccount = await AccountService.getAccount("seed seed seed ...");
console.log("Recovered address:", existingAccount.address);

GenerateKeypairs

AccountService.generateKeypairs(mnemonic: string): Promise<{ authentication, keyAgreement, assertionMethod, capabilityDelegation }>

Generates multiple keypairs for DID operations, derived from the same mnemonic:

  • authentication: Main key for signing and authentication.
  • keyAgreement: Encryption key for secure messaging.
  • assertionMethod: Key used for issuing verifiable credentials.
  • capabilityDelegation: Key for delegation and authorization.

Parameters:

  • mnemonic (string, required): The mnemonic seed for deriving keys.

Returns: An object with:

  • authentication: UidKeyringPair
  • keyAgreement: UidEncryptionKeypair
  • assertionMethod: UidKeyringPair
  • capabilityDelegation: UidKeyringPair

Example:

const keys = await AccountService.generateKeypairs(mnemonic);
console.log("Authentication key:", keys.authentication.address);
console.log(
  "Encryption key (public):",
  keys.keyAgreement.publicKey.toString("hex")
);

Usage Example

import { AccountService } from "@baliola/idchain-sdk";

async function setupAccounts() {
  // Create a new account for a DID Attester
  const { mnemonic, account } = await AccountService.generateAccount();
  console.log("Attester Mnemonic:", mnemonic);
  console.log("Attester Address:", account.address);

  // Derive keys for DID creation
  const keypairs = await AccountService.generateKeypairs(mnemonic);
  console.log("Authentication key address:", keypairs.authentication.address);

  // Recover an existing account
  const recovered = await AccountService.getAccount(mnemonic);
  console.log("Recovered Address:", recovered.address);
}

setupAccounts();

Error Handling

  • Invalid mnemonic: All methods throw if the provided mnemonic is null, not a string, or improperly formatted.
  • Token funding failure: On generateAccount, if the faucet transfer (transferToken) fails, an error will be thrown.

For production apps, wrap calls in try-catch:

try {
  const { mnemonic, account } = await AccountService.generateAccount();
} catch (err) {
  console.error("Account generation failed:", err);
}