@armada/sdk / wallet / Wallet
Interface: Wallet
Defined in: src/wallet/index.ts:35
A loaded wallet: viewing capability ± spend capability (view-only = no SpendSigner attached).
Properties
shieldedAddress
readonlyshieldedAddress:string
Defined in: src/wallet/index.ts:36
canSpend
readonlycanSpend:boolean
Defined in: src/wallet/index.ts:37
persists
readonlypersists:boolean
Defined in: src/wallet/index.ts:43
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:50
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:55
Current sync state (SPEC §4.4 sdk.sync.status) — the persisted checkpoint block and whether a sync is in flight. Cheap: hydrates the checkpoint from storage once, does no getLogs and no state change.
Returns
Promise<{ syncedThrough: number; syncing: boolean; }>
balances()
balances():
Promise<TokenBalance[]>
Defined in: src/wallet/index.ts:57
Per-token spendable/pending balances over the synced TXO set.
Returns
Promise<TokenBalance[]>
history()
history(
options?):Promise<HistoryEntry[]>
Defined in: src/wallet/index.ts:59
Reconstructed transaction history from the wallet's own scan state (SPEC §5). Works view-only.
Parameters
options?
sinceBlock?
number
Returns
Promise<HistoryEntry[]>
planTransfer()
planTransfer(
request):Promise<Plan>
Defined in: src/wallet/index.ts:60
Parameters
request
Returns
Promise<Plan>
preflight()
preflight(
plan,options?):Promise<PreflightResult>
Defined in: src/wallet/index.ts:66
Cheap pre-proof checks over a plan (SPEC §4.7) — root freshness, input nullifiers unspent, and (if a feeQuote is passed) quote freshness. Returns a finding per check; the caller decides policy. Works view-only. Turns the 30s-proof-then-revert failure into a typed, pre-proof result.
Parameters
plan
options?
feeQuote?
Returns
Promise<PreflightResult>
prove()
prove(
plan,options?):Promise<ProofHandle>
Defined in: src/wallet/index.ts:68
Requests signatures from the attached SpendSigner during witness assembly, then proves.
Parameters
plan
options?
Returns
Promise<ProofHandle>
markSpendPending()
markSpendPending(
plan,txid):void
Defined in: src/wallet/index.ts:78
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. Requires spend capability.
Parameters
plan
txid
string
Returns
void
clearSpendPending()
clearSpendPending(
txid):void
Defined in: src/wallet/index.ts:80
Release the optimistic holds for a submission that will not confirm (dropped/reverted tx).
Parameters
txid
string
Returns
void
exportDisclosure()
exportDisclosure(
txoRef):Promise<Uint8Array<ArrayBufferLike>>
Defined in: src/wallet/index.ts:82
Verifiable single-note disclosure receipt (SPEC §5.3). Available on view-only wallets too.
Parameters
txoRef
string
Returns
Promise<Uint8Array<ArrayBufferLike>>
shareViewingKey()
shareViewingKey():
string
Defined in: src/wallet/index.ts:84
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:91
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:98
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:109
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