Skip to content

@armada/sdk / wallet / Wallet

Interface: Wallet ​

Defined in: src/wallet/index.ts:44

A loaded wallet: viewing capability ± spend capability (view-only = no SpendSigner attached).

Properties ​

shieldedAddress ​

readonly shieldedAddress: string

Defined in: src/wallet/index.ts:45


canSpend ​

readonly canSpend: boolean

Defined in: src/wallet/index.ts:46


persists ​

readonly persists: boolean

Defined in: src/wallet/index.ts:52

Whether this wallet's scan state is written to the StorageAdapter. false for ephemeral (claimable-payment) wallets, which are in-memory only and never touch storage (SPEC §4.2/§4.3/§6.5) — no decrypted note data, and no seed-derived identity, ever hits disk on either side of a claim.

Methods ​

sync() ​

sync(): Promise<{ fromBlock: number; syncedThrough: number; scanned: boolean; }>

Defined in: src/wallet/index.ts:59

Scan the pool from the wallet's last synced block to chain head, updating its TXO/balance state. Resumes from the persisted checkpoint (no rescan from genesis). Returns the window that was covered: fromBlock (the resume point = checkpoint + 1), the new syncedThrough (chain head), and scanned (false when head hadn't advanced past the checkpoint, i.e. no work was done).

Returns ​

Promise<{ fromBlock: number; syncedThrough: number; scanned: boolean; }>


syncStatus() ​

syncStatus(): Promise<{ syncedThrough: number; syncing: boolean; }>

Defined in: src/wallet/index.ts:65

Current sync state (SPEC §4.4 sdk.sync.status) — the persisted checkpoint block and whether a sync is in flight. Cheap: the checkpoint was loaded from storage when the wallet was created; this does no getLogs and no state change.

Returns ​

Promise<{ syncedThrough: number; syncing: boolean; }>


balances() ​

balances(): Promise<TokenBalance[]>

Defined in: src/wallet/index.ts:67

Per-token spendable/pending balances over the synced TXO set.

Returns ​

Promise<TokenBalance[]>


history() ​

history(options?): Promise<HistoryEntry[]>

Defined in: src/wallet/index.ts:72

Reconstructed transaction history from the wallet's own scan state (SPEC §5). Works view-only. Makes no network request: each entry's timestamp was recorded during sync, which fetches every pool-event block's (#135).

Parameters ​

options? ​
sinceBlock? ​

number

Returns ​

Promise<HistoryEntry[]>


planTransfer() ​

planTransfer(request): Promise<Plan[]>

Defined in: src/wallet/index.ts:86

Plan a shielded spend as ONE OR MORE supported-shape groups (SPEC §4.6). Returns a single-element array for the common case; a fragmented single-recipient transfer that no registered shape can cover in one proof is split across several groups (recipient receives multiple notes), all submitted atomically as one transact([...]). A k-group split pays the quoted per-proof broadcaster fee k times (each proof costs the relayer its own verification gas). Prove the whole array with proveAll, then combine the handles' toTransactionData() into one buildTransactCalldata([...]). A spend blocked only by its change note, with change of at most one per-proof fee, pays that change to the broadcaster with the fee instead (one proof, one output fewer — cheaper than a split). Throws TooFragmentedError past the batch cap, or when a split's extra fees don't fit a balance that covers one (consolidate first); UnsupportedCircuitShapeError for an unsplittable spend (unshield / multi-recipient) whose shape isn't registered.

Parameters ​

request ​

PlanTransferRequest

Returns ​

Promise<Plan[]>


planTransferAfter() ​

planTransferAfter(consolidation, request): Promise<PlanSelection[]>

Defined in: src/wallet/index.ts:93

Dry-run planTransfer against the wallet as it would be once consolidation (from consolidate) confirms — its inputs gone, its merged notes in the current tree. Answers "will this spend work after merging?" before the user pays for the merge. Same planner rules and typed errors as planTransfer; returns selections WITHOUT merkle proofs (they describe notes that don't exist yet, so can't be proved).

Parameters ​

consolidation ​

readonly Plan[]

request ​

PlanTransferRequest

Returns ​

Promise<PlanSelection[]>


maxTransferAmount() ​

maxTransferAmount(request): Promise<bigint>

Defined in: src/wallet/index.ts:102

The largest amount a single-recipient private transfer can send right now, fee included — what a "Max" button should offer (planTransfer accepts it). Applies the same rules as planTransfer: a transfer spends ONE tree's notes (so it can be less than the balance minus a fee), a split pays the quoted per-proof transfer fee once per proof, the batch cap limits how many notes one send can spend, and notes held by a pending spend are left out. Returns 0n when nothing can be sent. Planning only (no proofs, no RPC); works view-only.

Parameters ​

request ​

MaxTransferRequest

Returns ​

Promise<bigint>


maxUnshieldAmount() ​

maxUnshieldAmount(request): Promise<bigint>

Defined in: src/wallet/index.ts:111

The largest amount an unshield can take out right now, fee included — the unshield flows' "Max" (planTransfer accepts it). An unshield is never split, so it's one proof: the notes one proof can spend, from ONE tree, less one per-proof fee at the tier the unshield's binding selects (plain, cross-chain, or a yield adapter call — pass unshield as for planTransfer, without the amount). Notes held by a pending spend are left out. Returns 0n when nothing can be unshielded. Planning only (no proofs, no RPC); works view-only.

Parameters ​

request ​

MaxUnshieldRequest

Returns ​

Promise<bigint>


consolidate() ​

consolidate(request): Promise<Plan[]>

Defined in: src/wallet/index.ts:124

Plan a consolidation (issue #98): merge ONE token's notes into fewer notes the wallet owns, as up to 4 proofs submitted atomically in one relayer transact([...]). Notes in older merkle trees go first (spending them moves their value into the current tree), then the smallest current-tree notes. Every proof pays the quoted transfer fee in USDC; a non-USDC run adds one USDC group that pays for the whole batch. Fragmented spends that can't split (unshields, yield) or that exceed one batch (TooFragmentedError) become possible after one or more runs. Prove with proveAll, then preflight and markSpendPending the whole array as for planTransfer. Throws NothingToConsolidateError when nothing is worth merging (e.g. only dust worth less than the fee), InsufficientBalanceError when a non-USDC run's fee can't be covered, and InvalidRequestError when the pool config has no supportedShapes. Requires spend capability.

Parameters ​

request ​

ConsolidateRequest

Returns ​

Promise<Plan[]>


preflight() ​

preflight(plan, options?): Promise<PreflightResult>

Defined in: src/wallet/index.ts:133

Cheap pre-proof checks over a plan — or every group of a split spend — (SPEC §4.7): root freshness, input nullifiers unspent, CCTP messenger liveness for a cross-chain unshield (when pool.cctp is configured), and — if you pass quoteDeadline, epoch ms on the LOCAL clock — that the fee quote the plan binds is still usable. Returns a finding per check; the caller decides policy, or passes the result to assertPreflight to throw the matching typed error. Works view-only. Turns the 30s-proof-then-revert failure into a typed, pre-proof result.

Parameters ​

plan ​

Plan | readonly Plan[]

options? ​
quoteDeadline? ​

number

Returns ​

Promise<PreflightResult>


prove() ​

prove(plan, options?): Promise<ProofHandle>

Defined in: src/wallet/index.ts:135

Requests signatures from the attached SpendSigner during witness assembly, then proves.

Parameters ​

plan ​

Plan

options? ​

ProveOptions

Returns ​

Promise<ProofHandle>


proveAll() ​

proveAll(plans, options?): Promise<ProofHandle[]>

Defined in: src/wallet/index.ts:142

Prove every group returned by planTransfer. The attached SpendSigner receives ALL groups' intents in ONE signBatch call before any signature is released (SPEC §4.2.1), so a split spend is approved as one unit; then each group is proved in order. Returns one handle per plan, in plan order. onProgress spans the whole batch (0→1 once across all plans).

Parameters ​

plans ​

readonly Plan[]

options? ​

ProveOptions

Returns ​

Promise<ProofHandle[]>


markSpendPending() ​

markSpendPending(plan, txid): Promise<void>

Defined in: src/wallet/index.ts:155

Optimistically mark a plan's input notes as spent when its transaction is submitted (issue #55), so a rapid follow-up planTransfer won't reselect them before the on-chain Nullified event is scanned — turning the "second tx reverts with Note already spent" race into a clean second selection. Call it right after broadcasting; the txid identifies the submission. Idempotent per note. The hold is released automatically when the spend confirms (its Nullified event supersedes it), by clearSpendPending(txid) on a known drop/revert, or by the pendingSpendTtlMs safety-net TTL. Pass every group of a split spend (the whole planTransfer array) so none of its inputs stay selectable. Requires spend capability (rejects with NoSpendCapabilityError). Resolves once the hold is written to storage, so it survives a reload from then on — await it before treating the submission as recorded.

Parameters ​

plan ​

Plan | readonly Plan[]

txid ​

string

Returns ​

Promise<void>


clearSpendPending() ​

clearSpendPending(txid): Promise<void>

Defined in: src/wallet/index.ts:160

Release the optimistic holds for a submission that will not confirm (dropped/reverted tx). Resolves once the release is written to storage.

Parameters ​

txid ​

string

Returns ​

Promise<void>


pendingSpendTxids() ​

pendingSpendTxids(): string[]

Defined in: src/wallet/index.ts:168

The submissions (the txids given to markSpendPending) whose holds are still in place — not yet confirmed, cleared or past the pendingSpendTtlMs TTL (pruned first, as balances are). A pure read of the holds. A hold is released in the same sync that scans its spend's Nullified event, which is also when the spend's change note is found — so an app can show a post-send balance (spendable + pending + each held spend's summary.changeValue) that hands over to the scanned one with no gap and no double count.

Returns ​

string[]


shareViewingKey() ​

shareViewingKey(): string

Defined in: src/wallet/index.ts:170

Export this wallet's shareable viewing key (Railgun wire format) — grants view-only capability.

Returns ​

string


spendableNullifiers() ​

spendableNullifiers(): readonly object[]

Defined in: src/wallet/index.ts:177

The (tree, nullifier) of every currently-spendable owned note — a pure read of the scan state. For an on-chain nullifier cross-check (WI-5): querying the pool's nullifier set for these catches a quick-sync indexer that omitted a Nullified event, which the commitment-root verify can't detect (a missing nullifier doesn't change the tree root). Works view-only.

Returns ​

readonly object[]


on() ​

on<K>(event, listener): Unsubscribe

Defined in: src/wallet/index.ts:184

Subscribe to scan/balance events (SPEC §5.2); returns an unsubscribe fn. The typed, multi-listener replacement for the stock engine's single global balance callback. Per sync() that does work: scan:started → scan:complete, then balance:updated for each token whose balance changed (a token fully spent emits a zero). scan:error fires if the scan throws.

Type Parameters ​

K ​

K extends keyof SyncEventMap

Parameters ​

event ​

K

listener ​

(payload) => void

Returns ​

Unsubscribe


watch() ​

watch(options?): Unsubscribe

Defined in: src/wallet/index.ts:195

Keep the wallet synced automatically (SPEC §4.4, issue #59): runs sync() immediately, then every intervalMs (default pool.autoSyncIntervalMs, 10s) with exponential backoff on error, until the returned function is called (or the SDK is closed). A watcher only schedules the verified pull sync() — it adds no trust surface — and coalesces with manual sync()/post-tx refreshes. Errors surface through the scan:error event and the optional onError; the loop keeps running.

Runs sync() once immediately by default; pass immediate: false to wait one interval (e.g. when you've just synced explicitly). Works view-only. Throws InvalidRequestError if already watching.

Parameters ​

options? ​
intervalMs? ​

number

immediate? ​

boolean

onError? ​

(err) => void

Returns ​

Unsubscribe


dispose() ​

dispose(): Promise<void>

Defined in: src/wallet/index.ts:203

Release the wallet (SPEC §4.1): stop its watcher, cancel an in-flight sync or proof and wait for it to settle (it rejects with InstanceClosedError; a proof's signal fires, so a signer waiting on approval can stop), dispose the signer the SDK made for it (one you passed in is yours to dispose), and wipe its viewing key. Every call afterwards throws InstanceClosedError; calling it again does nothing. sdk.close() disposes every wallet still open, so call this for a wallet you're done with before then (e.g. an ephemeral claim wallet). Key wiping is best-effort: JavaScript can't wipe bigint or string copies.

Returns ​

Promise<void>