Skip to content

Recovery Scan Rules v1

This file freezes the wallet recovery and replay behavior used by the current Phase 3 confidentiality path.

For the integration-facing API/sync contract that applies these rules, see spec/reference-wallet-api-sync-contract-v1.md.

1) Trust boundary

Candidate discovery sources (full-node scan, light-client filters, public candidate feeds, or custom indexers) are advisory only.

They may provide candidate txids, block ranges, or pre-filtered transition lists, but they MUST NOT be treated as authoritative for:

  • ownership
  • note validity
  • commitment matching
  • spent-state truth

Wallets MUST derive ownership and validity locally from:

  • wallet keys (A, B) (scan/spend)
  • canonical envelope parsing
  • canonical note commitment checks
  • canonical nullifier policy
  • chain transition replay

2) Candidate handling

Wallet implementations should normalize candidate transition ordering before validation:

  • sort by (blockHeight, txIndex, txidHex) for connect events
  • deduplicate repeated candidates from mixed sources
  • ignore source-specific metadata during validity decisions

The same canonical candidate set must produce the same recovered wallet-note state regardless of feed ordering.

3) Replay and reorg behavior

Recovery state is event-replay driven:

  • connect events append transition effects
  • disconnect events remove previously connected events for the disconnected block
  • the post-reorg state is computed by replaying the remaining canonical connect set

This guarantees deterministic rollback/replay under reorg.

4) State model expectations

Recovery updates two deterministic projections:

  • wallet-note projection:
  • discovered notes (unspent by default)
  • spent markers keyed by note id / note hash + nullifier
  • protocol state-cell projection:
  • produced cells (active)
  • consumed cells (spent)
  • per-cell roots (noteRoot32, nullRoot32) and creation/spend provenance

5) Nullifier and commitment policy references

Wallet recovery MUST use the canonical helpers:

  • note commitment: deriveNoteCommitment32V1 / hashNoteLeafV1 over canonical NoteLeafV1 encoding
  • nullifier v1: deriveNullifier32V1 over canonical v1 preimage ordering

Normative formula details are frozen in spec/note-commitment-nullifier-formulas-v1.md.

6) Persistence expectations

Local stores may cache additional indices, but replay from:

  • chain transition data (or equivalent canonical event stream),
  • wallet keys, and
  • canonical helper policies

must always converge to the same final result.