Recovery & witnesses
Reconstruct finalized Merkle membership from paged accounts, reconcile pending operations and understand note recovery limits.
The default OnChainPagedMerkleWitnessProvider reconstructs a membership path from finalized on-chain accounts. It fetches TreeState, PageDirectory and all 16 leaf pages in one atomic 18-account request, validates page digests and roots, then verifies the 16-level path against the tree root. It does not require event history or Merkle sidecars for a normal witness.
The SDK supports RpcMerkleWitnessProvider for finalized history reconstruction and authenticated Shield-event recovery. Recovery methods require a provider with the needed event/spent-state capabilities; the default paged account provider is optimized for witnesses, not historical event scanning.
Restart reconciliation
After a process restart, call await shielded.reconcilePending() before selecting notes for another operation. The journal records the operation, submitted signature, signed bytes and expected output preimages. Reconciliation checks finalized transaction state, authenticated program events and canonical spent-nullifier accounts before publishing local note state.
shielded.recoverShieldedNotes(pool) can recover decryptable Shield notes from authenticated finalized events when configured with a history-capable provider. It verifies owner commitment and canonical spent state; ciphertext for other wallets is ignored.
Recovery limits
- A lost seed cannot regenerate the spend secret.
- Losing the seed and encrypted journal/backup removes note recovery material.
- Random Private Swap output preimages are not available in the public event; chain-only recovery of an output whose local preimage and backups are lost is not possible.
- If the process terminates during proving before a transaction signature exists, the input remains reserved/unresolved. A timeout alone does not prove that another process abandoned the proof, so the SDK fails closed.
- The provider needs an RPC plan supporting one 18-account request for the default path. The release validation observed a provider plan that capped requests at five accounts and returned HTTP 413.
See Tree paging, NoteStore and Confirmation lifecycle.