@armada/sdk / index / WalletScanState
Class: WalletScanState
Defined in: src/sync/scan-engine.ts:134
Accumulates wallet state across incremental scan batches. Leaves from ALL commitment types are inserted into per-treeNumber merkletrees in (tree, position) order (append-only, position-gap checked); commitments the wallet owns become TXOs; nullifiers are recorded tree-scoped. Balances are a pure projection over the accumulated TXO/nullifier sets.
Constructors
Constructor
new WalletScanState():
WalletScanState
Returns
WalletScanState
Accessors
txoCount
Get Signature
get txoCount():
number
Defined in: src/sync/scan-engine.ts:275
Returns
number
Methods
restore()
staticrestore(snapshot):WalletScanState
Defined in: src/sync/scan-engine.ts:346
Rebuild a WalletScanState from a snapshot — trees are re-derived from their leaves.
Parameters
snapshot
Returns
WalletScanState
apply()
apply(
events,decryptors):Promise<ApplyResult>
Defined in: src/sync/scan-engine.ts:147
Fold a decoded event batch into wallet state. Batches MUST arrive in scan order (ascending block/position) — the append-only merkletree requires each leaf's position to equal the tree's current length. Returns the owned TXOs + nullifiers newly seen in this batch.
Parameters
events
decryptors
Returns
Promise<ApplyResult>
treeRoot()
treeRoot(
tree):string
Defined in: src/sync/scan-engine.ts:227
Current commitment root of tree (no-0x hex); the empty-tree root if unseen.
Parameters
tree
number
Returns
string
treeNumbers()
treeNumbers():
number[]
Defined in: src/sync/scan-engine.ts:233
Tree numbers with at least one inserted leaf, ascending.
Returns
number[]
ownedTxos()
ownedTxos(): readonly
TXO[]
Defined in: src/sync/scan-engine.ts:238
All owned notes ever received (spent or not) — the receive side of history reconstruction.
Returns
readonly TXO[]
spentNullifiers()
spentNullifiers(): readonly
SpentNullifier[]
Defined in: src/sync/scan-engine.ts:243
All spent-note markers seen (with txid/block) — the spend side of history reconstruction.
Returns
readonly SpentNullifier[]
unshieldEvents()
unshieldEvents(): readonly
DecodedUnshield[]
Defined in: src/sync/scan-engine.ts:248
All public withdrawals seen — matched to the wallet's own spend txids for unshield/yield history.
Returns
readonly DecodedUnshield[]
sentOutputs()
sentOutputs(): readonly
SentOutput[]
Defined in: src/sync/scan-engine.ts:253
Notes the wallet authored (recovered sender-side) — the recipient/fee detail of its own sends.
Returns
readonly SentOutput[]
verifyRoots()
verifyRoots(
expectedRoots):void
Defined in: src/sync/scan-engine.ts:261
Verify each tree's locally-built root against the on-chain root (0x-prefixed or bare). Throws a typed RootMismatchError (code ROOT_MISMATCH) carrying tree context on the first mismatch.
Parameters
expectedRoots
ReadonlyMap<number, string>
Returns
void
balances()
balances(
nullifyingKey,options):TokenBalance[]
Defined in: src/sync/scan-engine.ts:271
Per-token spendable/pending over all accumulated TXOs + spent nullifiers.
Parameters
nullifyingKey
bigint
options
Returns
treeLength()
treeLength(
tree):number
Defined in: src/sync/scan-engine.ts:280
Number of leaves inserted into tree.
Parameters
tree
number
Returns
number
merkleProof()
merkleProof(
tree,position):MerkleProof
Defined in: src/sync/scan-engine.ts:285
Merkle proof for a note at (tree, position) — the spend witness's pathElements/leavesIndices.
Parameters
tree
number
position
number
Returns
spendableTxos()
spendableTxos(
nullifyingKey):TXO[]
Defined in: src/sync/scan-engine.ts:297
Unspent owned TXOs (tree-scoped nullifier–filtered), ready to hand to planTransfer. Excludes any note whose (tree, getNullifier(nullifyingKey, position)) appears in the recorded spent set.
Parameters
nullifyingKey
bigint
Returns
TXO[]
snapshot()
snapshot():
ScanStateSnapshot
Defined in: src/sync/scan-engine.ts:305
JSON-serializable snapshot of the accumulated tree/TXO/nullifier state, for persistence.