Skip to content

Wallets ​

Wallets are created from sdk.wallet. This page covers the ways to load one, how spend capability works, and how to share read-only access.

Spending and viewing keys ​

A wallet derives two kinds of keys:

  • A spending key authorizes spends and produces the proofs that move funds.
  • A viewing key detects and decrypts the wallet's own notes, which is what balances and history are computed from.

The two are separable. Sharing only the viewing key grants someone the ability to see a wallet's activity without the ability to spend from it — the basis for view-only wallets and shareable viewing keys below.

Loading a wallet ​

From a root secret ​

A 32-byte root secret gives a spend-capable wallet:

ts
const wallet = await sdk.wallet.fromRootSecret(rootSecret, { creationBlock: 21_000_000 });

From a mnemonic ​

A BIP-39 mnemonic works too; the checksum is validated on load. derivationIndex defaults to 0:

ts
const wallet = await sdk.wallet.fromMnemonic(mnemonic, {
  creationBlock: 21_000_000,
  derivationIndex: 0,
});

View-only from a viewing key ​

A shareable viewing key produces a wallet that can scan, report balances, and reconstruct history, but cannot spend:

ts
const wallet = await sdk.wallet.viewOnlyFromViewingKey(shareableViewingKey, {
  creationBlock: 21_000_000,
});

Ephemeral from a seed ​

An ephemeral wallet is held in memory only and never written to storage — its persists flag is false. It takes no creationBlock:

ts
const wallet = await sdk.wallet.ephemeralFromSeed(seed);

wallet.persists; // false

Spend capability ​

canSpend reflects whether a wallet has a signer attached. fromRootSecret and fromMnemonic are spend-capable by default. Pass viewOnly: true to load a wallet that can scan and report but holds no signer:

ts
const viewOnly = await sdk.wallet.fromRootSecret(rootSecret, {
  creationBlock: 21_000_000,
  viewOnly: true,
});

viewOnly.canSpend; // false

Calling a spend-path method — planTransfer, prove, or proveAll — on a wallet without a signer throws NoSpendCapabilityError:

ts
import { isArmadaError } from '@armada/sdk';

try {
  await viewOnly.planTransfer(request);
} catch (err) {
  isArmadaError(err, 'NO_SPEND_CAPABILITY'); // true
}

Match SDK errors on their code — isArmadaError does — not with instanceof or on the message. Every SDK error carries a stable code, while instanceof can be false when the SDK is loaded twice — for example once as an ES module and once as CommonJS. Errors lists every code.

Signers ​

Spend authorization goes through a SpendSigner:

ts
interface SpendSigner {
  getSpendingPublicKey(): Promise<[bigint, bigint]>;
  signBatch(requests: readonly SpendSignRequest[], options?: { signal?: AbortSignal }): Promise<EddsaSignature[]>;
  dispose?(): void;
}

By default the SDK attaches a LocalSigner derived from the secret you loaded the wallet with. To produce spend signatures elsewhere — a remote service, an HSM, a hardware device — attach an ExternalSigner, which delegates both calls to backends you provide:

ts
import { ExternalSigner } from '@armada/sdk';

const signer = new ExternalSigner(
  (requests) => myBackend.signBatch(requests),   // => Promise<EddsaSignature[]>
  () => myBackend.getSpendingPublicKey(),        // => Promise<[bigint, bigint]>
);

const wallet = await sdk.wallet.fromRootSecret(rootSecret, {
  creationBlock: 21_000_000,
  signer,
});

An explicit signer always takes precedence over the default LocalSigner. fromMnemonic accepts the same signer option. The signer must hold the wallet's spending key: if getSpendingPublicKey() returns another key, loading the wallet fails with SignerContractViolationError. Each signature the signer returns is checked against that key before proving, with the same error if it doesn't verify.

signBatch receives the proof's AbortSignal, if the caller passed one to prove or proveAll. A signer that waits on a person or a remote service should stop waiting and reject when it fires. If it fires while the signer is working, the SDK discards whatever comes back and throws AbortedError instead of proving.

Keeping the spend key out of the SDK ​

fromRootSecret and fromMnemonic derive the spend key from the secret, even when you pass a signer; the SDK zeroes that copy at once, but it was in memory. To keep it out of the SDK entirely, load the wallet from its shareable viewing key and attach the signer there:

ts
const wallet = await sdk.wallet.viewOnlyFromViewingKey(shareableViewingKey, {
  creationBlock: 21_000_000,
  signer, // e.g. an ExternalSigner over your HSM
});
wallet.canSpend; // true

Without a signer, the wallet is view-only. See Security for what key wiping can and can't guarantee.

Disposing a wallet ​

wallet.dispose() releases a wallet you're done with. It stops the wallet's watcher, cancels an in-flight sync or proof and waits for it to settle (it rejects with InstanceClosedError), disposes the signer the SDK made for the wallet, and wipes the wallet's viewing key. Cancelling a proof fires the signal its signer receives, so a signer waiting on approval should stop waiting; one that ignores the signal holds dispose() until it answers. A signer you passed in is yours to dispose, since it may serve other wallets. Every call on the wallet afterwards throws InstanceClosedError; calling dispose() again does nothing.

ts
const claim = await sdk.wallet.ephemeralFromSeed(seed);
// ... claim the payment ...
await claim.dispose();

sdk.close() disposes every wallet still open, so you only need dispose() for a wallet you finish with earlier — an ephemeral claim wallet, or a user who logs out.

Sharing a viewing key ​

shareViewingKey() returns a string encoding a wallet's viewing capability. Pass it to viewOnlyFromViewingKey to reconstruct a view-only wallet — useful for reporting or monitoring without exposing spend power:

ts
const shareable = wallet.shareViewingKey();

const viewOnly = await sdk.wallet.viewOnlyFromViewingKey(shareable, {
  creationBlock: 21_000_000,
});

shareViewingKey() is available on view-only wallets too.

Compatibility

Shareable viewing keys use a wire format that is byte-compatible with other wallets over the same shielded-pool design, so a key can be moved between compatible wallets. This is a wire-format compatibility only — each wallet still scans the pool it is configured for.