@armada/sdk / index / WalletScanState
Class: WalletScanState
Defined in: src/sync/scan-engine.ts:158
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:344
Returns
number
Methods
restore()
staticrestore(snapshot):WalletScanState
Defined in: src/sync/scan-engine.ts:472
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:177
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:291
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:297
Tree numbers with at least one inserted leaf, ascending.
Returns
number[]
ownedTxos()
ownedTxos(): readonly
TXO[]
Defined in: src/sync/scan-engine.ts:302
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:307
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:312
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:317
Notes the wallet authored (recovered sender-side) — the recipient/fee detail of its own sends.
Returns
readonly SentOutput[]
shieldRelayerFees()
shieldRelayerFees():
ReadonlyMap<string,bigint>
Defined in: src/sync/scan-engine.ts:322
Per-txid relayer fee paid in a gasless shield we co-authored (issue #88) — feeds history recovery.
Returns
ReadonlyMap<string, bigint>
verifyRoots()
verifyRoots(
expectedRoots):void
Defined in: src/sync/scan-engine.ts:330
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:340
Per-token spendable/pending/pendingSpent over all accumulated TXOs + spent + in-flight nullifiers.
Parameters
nullifyingKey
bigint
options
Returns
treeLength()
treeLength(
tree):number
Defined in: src/sync/scan-engine.ts:349
Number of leaves inserted into tree.
Parameters
tree
number
Returns
number
merkleProof()
merkleProof(
tree,position):MerkleProof
Defined in: src/sync/scan-engine.ts:354
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:368
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 OR in the optimistic in-flight set (issue #55) — so a note with a submitted-but-unconfirmed spend is not reselected before its Nullified event is scanned.
Parameters
nullifyingKey
bigint
Returns
TXO[]
markSpendPending()
markSpendPending(
entries,txid,addedAt):void
Defined in: src/sync/scan-engine.ts:384
Optimistically mark notes as spent by an in-flight (submitted, unconfirmed) transaction, so spendableTxos/balances stop offering them until the on-chain Nullified event confirms the spend (or clearSpendPending/prunePendingSpends releases them). Idempotent per (tree, nullifier); entries already confirmed-spent are ignored (the confirmed set is authoritative). addedAt is an epoch-ms timestamp used for TTL expiry, and txid groups a submission for later release.
Parameters
entries
readonly object[]
txid
string
addedAt
number
Returns
void
clearSpendPending()
clearSpendPending(
txid):void
Defined in: src/sync/scan-engine.ts:401
Release the optimistic holds placed by one submission (by its txid) — e.g. the transaction was dropped or reverted, so its inputs return to spendable immediately rather than waiting for the TTL.
Parameters
txid
string
Returns
void
prunePendingSpends()
prunePendingSpends(
cutoff):void
Defined in: src/sync/scan-engine.ts:412
Drop optimistic holds added before cutoff (epoch ms). The safety net: an abandoned/never-mined submission can't lock its inputs forever, including across a reload where the confirming event will never arrive. Confirmed spends clear themselves via the Nullified event during scan.
Parameters
cutoff
number
Returns
void
pendingSpends()
pendingSpends(): readonly
PendingSpend[]
Defined in: src/sync/scan-engine.ts:419
The optimistic in-flight spends currently held — for persistence and balance projection.
Returns
readonly PendingSpend[]
snapshot()
snapshot():
ScanStateSnapshot
Defined in: src/sync/scan-engine.ts:424
JSON-serializable snapshot of the accumulated tree/TXO/nullifier state, for persistence.