@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
readonlyshieldedAddress:string
Defined in: src/wallet/index.ts:45
canSpend
readonlycanSpend:boolean
Defined in: src/wallet/index.ts:46
persists
readonlypersists: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
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
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
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
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
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
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
options?
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?
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
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
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
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>