@twin.org/dlt-account 0.9.2-next.2

package/dist/types/helpers/accountHelper.d.ts

@@ -0,0 +1,143 @@
+import type { IVaultConnector } from "@twin.org/vault-models";
+import type { IAccountConfig } from "../models/IAccountConfig.js";
+/**
+ * Helper class for account management operations.
+ */
+export declare class AccountHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Default name for the mnemonic secret.
+     */
+    static readonly DEFAULT_MNEMONIC_SECRET_NAME: string;
+    /**
+     * Default name for the seed secret.
+     */
+    static readonly DEFAULT_SEED_SECRET_NAME: string;
+    /**
+     * Default coin type.
+     */
+    static readonly DEFAULT_COIN_TYPE: number;
+    /**
+     * Default pre-calculation chunk size.
+     */
+    static readonly DEFAULT_CALC_CHUNK_SIZE: number;
+    /**
+     * Default scan range.
+     */
+    static readonly DEFAULT_SCAN_RANGE_SIZE: number;
+    /**
+     * Create a new account by generating a mnemonic and seed, storing them in the vault, and pre-caching the first chunk of derived keys.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector.
+     * @param identity The identity of the user to access the vault keys.
+     * @param mnemonic The mnemonic to store, if undefined a new one will be generated and returned.
+     * @param accountIndex The account index to pre-cache.
+     * @returns The mnemonic that was stored.
+     */
+    static createAccountKeys(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string, mnemonic?: string, accountIndex?: number): Promise<string>;
+    /**
+     * Rename all vault entries for an account from one identity to another.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector.
+     * @param fromIdentity The source identity whose vault entries should be copied.
+     * @param toIdentity The destination identity that will receive the copied entries.
+     */
+    static renameAccountKeys(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, fromIdentity: string, toIdentity: string): Promise<void>;
+    /**
+     * Remove all vault entries for an account.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector.
+     * @param identity The identity of the user whose vault keys should be removed.
+     */
+    static removeAccountKeys(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string): Promise<void>;
+    /**
+     * Get the key for storing the seed.
+     * @param identity The identity to use.
+     * @param vaultSeedId The seed ID to use.
+     * @returns The seed key.
+     */
+    static buildSeedKey(identity: string, vaultSeedId?: string): string;
+    /**
+     * Get the key for storing the mnemonic.
+     * @param identity The identity to use.
+     * @param vaultMnemonicId The mnemonic ID to use.
+     * @returns The mnemonic key.
+     */
+    static buildMnemonicKey(identity: string, vaultMnemonicId?: string): string;
+    /**
+     * Ensure a range of BIP44-derived keys are registered as individual vault keys and return their public keys.
+     * If the first key of the range already exists the range is considered registered and only public keys are derived.
+     * If not registered, all keys are derived and added to the vault before returning the public keys.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index.
+     * @param internal Whether the addresses are internal or external.
+     * @param addressIndex Any address index within the desired chunk; aligned internally.
+     * @param seedProvider Callback invoked at most once per call to supply the seed when a chunk is not yet registered.
+     * @returns The base64-encoded public keys for each address in the range.
+     */
+    static getPublicKeys(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string, accountIndex: number, internal: boolean, addressIndex: number, seedProvider: () => Promise<Uint8Array>): Promise<string[]>;
+    /**
+     * Build the vault key name for a specific derived address.
+     * @param identity The identity to use.
+     * @param accountIndex The account index.
+     * @param internal Whether the address is internal or external.
+     * @param addressIndex The address index.
+     * @returns The vault key name.
+     */
+    static buildAddressKeyName(identity: string, accountIndex: number, internal: boolean, addressIndex: number): string;
+    /**
+     * Get address for the identity.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index to get the addresses for.
+     * @param startAddressIndex The start index for the addresses.
+     * @param isInternal Whether the addresses are internal.
+     * @returns The address.
+     */
+    static getAddress(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string, accountIndex: number, startAddressIndex: number, isInternal?: boolean): Promise<string>;
+    /**
+     * Get addresses for the identity.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector.
+     * @param identity The identity of the user to access the vault keys.
+     * @param accountIndex The account index to get the addresses for.
+     * @param startAddressIndex The start index for the addresses.
+     * @param count The number of addresses to generate.
+     * @param isInternal Whether the addresses are internal.
+     * @returns The list of addresses.
+     */
+    static getAddresses(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string, accountIndex: number, startAddressIndex: number, count: number, isInternal?: boolean): Promise<string[]>;
+    /**
+     * Get the seed from the vault, deriving it from the mnemonic if necessary.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @returns The seed bytes.
+     */
+    static getSeed(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string): Promise<Uint8Array>;
+    /**
+     * Find the vault key name and public key for a specific address by scanning derived keys.
+     * @param accountConfig The account configuration.
+     * @param vaultConnector The vault connector to use.
+     * @param identity The identity of the user to access the vault keys.
+     * @param address The owner address whose key should be located.
+     * @param accountIndex The account index to search.
+     * @returns The vault key name and the public key bytes.
+     */
+    static findAddressKey(accountConfig: IAccountConfig | undefined, vaultConnector: IVaultConnector, identity: string, address: string, accountIndex?: number): Promise<{
+        keyName: string;
+        publicKey: Uint8Array;
+    }>;
+    /**
+     * Derive an address from a public key.
+     * @param publicKey The public key to derive the address from.
+     * @returns The derived address.
+     */
+    static publicKeyToAddress(publicKey: Uint8Array): string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./helpers/accountHelper.js";
+export * from "./models/IAccountConfig.js";

package/dist/types/models/IAccountConfig.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The configuration for an account.
+ */
+export interface IAccountConfig {
+    /**
+     * The ID of the vault seed.
+     */
+    vaultSeedId?: string;
+    /**
+     * The ID of the vault mnemonic.
+     */
+    vaultMnemonicId?: string;
+    /**
+     * The coin type.
+     */
+    coinType?: number;
+    /**
+     * The maximum number of addresses to scan for the account.
+     */
+    maxAddressScanRange?: number;
+}

package/docs/changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.9.2-next.2](https://github.com/iotaledger/twin-dlt/compare/dlt-account-v0.9.2-next.1...dlt-account-v0.9.2-next.2) (2026-08-07)
+
+
+### Features
+
+* linting and dependency update ([6eb1848](https://github.com/iotaledger/twin-dlt/commit/6eb18480bb1b4608e3590b7e03f5f525ea2e0952))
+
+## Changelog

package/docs/examples.md

@@ -0,0 +1,146 @@
+# DLT Account Examples
+
+These examples show how to create, query, and manage distributed ledger accounts through a vault connector, covering the full lifecycle from creation to removal.
+
+## AccountHelper
+
+```typescript
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+const identity = 'did:example:alice';
+
+// Generate a fresh mnemonic automatically, store it with its derived seed,
+// and pre-cache the first chunk of BIP44 address keys for account index 0.
+const mnemonic = await AccountHelper.createAccountKeys(undefined, vaultConnector, identity);
+
+// Or import a known mnemonic for an existing account.
+const existingMnemonic =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const stored = await AccountHelper.createAccountKeys(
+  undefined,
+  vaultConnector,
+  'did:example:bob',
+  existingMnemonic
+);
+console.log(stored === existingMnemonic); // true
+```
+
+```typescript
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+const identity = 'did:example:alice';
+
+// Retrieve three consecutive external addresses starting at index 0.
+const addresses = await AccountHelper.getAddresses(undefined, vaultConnector, identity, 0, 0, 3);
+console.log(addresses.length); // 3
+
+// Get a single external address at a known index.
+const address = await AccountHelper.getAddress(undefined, vaultConnector, identity, 0, 0);
+console.log(address === addresses[0]); // true
+
+// Retrieve internal (change) addresses for account index 1.
+const internalAddresses = await AccountHelper.getAddresses(
+  undefined,
+  vaultConnector,
+  identity,
+  1,
+  0,
+  5,
+  true
+);
+console.log(internalAddresses.length); // 5
+```
+
+```typescript
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+const identity = 'did:example:alice';
+
+// Generate addresses then find the vault key for a specific one.
+const addresses = await AccountHelper.getAddresses(undefined, vaultConnector, identity, 0, 0, 5);
+const { keyName, publicKey } = await AccountHelper.findAddressKey(
+  undefined,
+  vaultConnector,
+  identity,
+  addresses[2]
+);
+console.log(keyName); // "did:example:alice/account/0/0/2"
+console.log(AccountHelper.publicKeyToAddress(publicKey) === addresses[2]); // true
+```
+
+```typescript
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+
+// Move all vault entries for an identity from one DID to another.
+await AccountHelper.renameAccountKeys(
+  undefined,
+  vaultConnector,
+  'did:example:old-identity',
+  'did:example:new-identity'
+);
+```
+
+```typescript
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+const identity = 'did:example:alice';
+
+// Remove all vault entries for the identity: mnemonic, seed, and all derived keys.
+await AccountHelper.removeAccountKeys(undefined, vaultConnector, identity);
+```
+
+```typescript
+import { Converter } from '@twin.org/core';
+import type { IVaultConnector } from '@twin.org/vault-models';
+import { AccountHelper } from '@twin.org/dlt-account';
+
+declare const vaultConnector: IVaultConnector;
+const identity = 'did:example:alice';
+
+// Retrieve the seed bytes, deriving from the mnemonic if not yet stored.
+const seed = await AccountHelper.getSeed(undefined, vaultConnector, identity);
+console.log(seed instanceof Uint8Array); // true
+
+// Derive and cache a chunk of 25 public keys starting at address index 0.
+const publicKeys = await AccountHelper.getPublicKeys(
+  undefined,
+  vaultConnector,
+  identity,
+  0,
+  false,
+  0,
+  async () => seed
+);
+console.log(publicKeys.length); // 25
+
+// Convert a base64-encoded public key to its on-chain hex address.
+const derivedAddress = AccountHelper.publicKeyToAddress(Converter.base64ToBytes(publicKeys[0]));
+console.log(derivedAddress.startsWith('0x')); // true
+```
+
+```typescript
+import { AccountHelper } from '@twin.org/dlt-account';
+
+const identity = 'did:example:alice';
+
+// Build vault key names for secrets and derived address keys.
+console.log(AccountHelper.buildSeedKey(identity)); // "did:example:alice/seed"
+console.log(AccountHelper.buildMnemonicKey(identity)); // "did:example:alice/mnemonic"
+console.log(AccountHelper.buildAddressKeyName(identity, 0, false, 7)); // "did:example:alice/account/0/0/7"
+console.log(AccountHelper.buildAddressKeyName(identity, 1, true, 0)); // "did:example:alice/account/1/1/0"
+
+// Override default key names via IAccountConfig.
+console.log(AccountHelper.buildSeedKey(identity, 'deployment-seed')); // "did:example:alice/deployment-seed"
+console.log(AccountHelper.buildMnemonicKey(identity, 'deployment-mnemonic')); // "did:example:alice/deployment-mnemonic"
+```