Skip to main content

UnifiedIdentityWallet

@totemsdk/root-identity


@totemsdk/root-identity / UnifiedIdentityWallet

Class: UnifiedIdentityWallet

Constructors​

Constructor​

new UnifiedIdentityWallet(baseSeed, childCount?): UnifiedIdentityWallet

Parameters​

baseSeed​

Uint8Array

32-byte raw seed (use UnifiedIdentityWallet.fromPhrase for mnemonic input)

childCount?​

number = MAX_CHILD_COUNT

Number of child addresses (1–64, default 64)

Returns​

UnifiedIdentityWallet

Methods​

getAddressMap()​

getAddressMap(): object

Root address and children as a structured object.

Returns​

object

children​

children: string[]

root​

root: string


getAllAddresses()​

getAllAddresses(): string[]

All addresses: root first, then all children in order.

Returns​

string[]


getChildAddress()​

getChildAddress(index): string

Minima spend address for child index (0-based).

Parameters​

index​

number

Returns​

string


getChildCount()​

getChildCount(): number

Number of child addresses configured for this wallet.

Returns​

number


getChildPublicKey()​

getChildPublicKey(index): string

64-char hex public key for child index.

Parameters​

index​

number

Returns​

string


getChildTreeKey()​

getChildTreeKey(index): TreeKey

Get (or create and cache) the TreeKey for child index (0-based).

Use this for transaction signing — the child TreeKey is the spend key. Call getChildUses / setChildUses to manage the watermark manually.

Parameters​

index​

number

Returns​

TreeKey


getChildUses()​

getChildUses(index): number

Number of times child index has signed (for persistence).

Parameters​

index​

number

Returns​

number


getMaxUsesPerSlot()​

getMaxUsesPerSlot(): number

Maximum one-time signatures available per slot (3 levels × 64 keys = 262 144).

Returns​

number


getRootAddress()​

getRootAddress(): string

Minima address for the root key. NEVER use this address for spending.

Returns​

string


getRootPublicKey()​

getRootPublicKey(): string

64-char hex public key for the root key.

Returns​

string


getRootTreeKey()​

getRootTreeKey(): TreeKey

Get (or create and cache) the root identity TreeKey.

Use this only for off-chain attestation signing, not for spending.

Returns​

TreeKey


getRootUses()​

getRootUses(): number

Number of times the root identity key has signed (for persistence).

Returns​

number


getWatermarkState()​

getWatermarkState(): object

Return a serialisable snapshot of all current watermark counters.

Persist the returned object (e.g. to encrypted storage) and pass it back to restoreWatermarkState() at the start of the next session so that no one-time-use signing slot is ever reused.

Returns​

object

childUses​

childUses: Record<number, number>

rootUses​

rootUses: number


proveOwnership()​

proveOwnership(childIndices): OwnershipProof

Produce an ownership proof demonstrating that this root identity controls all given child addresses.

The root key signs a canonical JSON message containing all child public keys (sorted) and a timestamp, enabling third-party verification without any network access.

Parameters​

childIndices​

number[]

Which children to include (0-based)

Returns​

OwnershipProof


restoreWatermarkState()​

restoreWatermarkState(state): void

Restore watermark counters from a previously persisted snapshot.

Call this immediately after constructing the wallet to prevent slot reuse across sessions. Out-of-range or invalid entries are silently skipped.

Parameters​

state​
childUses?​

Record<number, number>

rootUses?​

number

Returns​

void


setChildUses()​

setChildUses(index, uses): void

Restore child watermark from a previously persisted value.

Parameters​

index​

number

uses​

number

Returns​

void


setRootUses()​

setRootUses(uses): void

Restore root watermark from a previously persisted value.

Parameters​

uses​

number

Returns​

void


signFromChild()​

signFromChild(index, message): WotsProof

Sign message with child key index (0-based) for on-chain transactions. Each child maintains its own independent use counter.

Parameters​

index​

number

message​

string

Returns​

WotsProof

Throws​

if child TreeKey is exhausted or index out of range


signFromRoot()​

signFromRoot(message): WotsProof

Sign message with the root identity key (for off-chain attestations). Hashes the message with SHA3-256 before signing.

Parameters​

message​

string

Returns​

WotsProof

Throws​

if root TreeKey is exhausted (262 144 uses)


fromPhrase()​

static fromPhrase(phrase, childCount?): UnifiedIdentityWallet

Create a wallet from a Minima-compatible BIP39 seed phrase.

Parameters​

phrase​

string

childCount?​

number = MAX_CHILD_COUNT

Returns​

UnifiedIdentityWallet


generatePhrase()​

static generatePhrase(): string

Generate a new random Minima-compatible 24-word seed phrase.

Returns​

string


validatePhrase()​

static validatePhrase(phrase): boolean

Validate a Minima-compatible seed phrase.

Parameters​

phrase​

string

Returns​

boolean


verifyOwnershipProof()​

static verifyOwnershipProof(proof): boolean

Verify an ownership proof produced by proveOwnership.

Returns true only when:

  • The canonical message is reconstructed correctly (child keys are sorted).
  • The root WOTS signature validates against the root public key and address.
  • Every child public key correctly derives the corresponding child address.

Pure crypto — no network access required. Always returns false (never throws) on malformed or incomplete proof data.

Parameters​

proof​

OwnershipProof

Returns​

boolean