Detect spent orchard notes via PIR

[p0mvn]

Summary

Integrate the nullifier PIR (Private Information Retrieval) service so the app can detect spent orchard notes before the block scanner catches up. Without PIR, a spent note's balance appears available until full shard-tree scanning confirms the spend — which can take a long time and would lead to broadcast failures if the user tries to spend the stale balance.

How it works

1. Startup: After the SDK synchronizer registers for updates (registerForSynchronizersUpdate), the app fires checkSpendabilityPIR which calls the PIR server via sdkSynchronizer.checkWalletSpendability(pirUrl). The server checks each unspent orchard note's nullifier against a compact nullifier database.
2. During sync: Whenever foundTransactions (new transactions discovered mid-sync) or syncReachedUpToDate (sync completed) fires, checkSpendabilityPIR is triggered again — alongside the normal transaction refresh.
3. Deduplication: The PIR effect uses .cancellable(id: PIRCheckCancelId, cancelInFlight: true) so rapid events during a long sync coalesce into a single server request.
4. Result handling: checkSpendabilityPIRResult stores the result in @Shared(.pirSpendabilityResult) and triggers both a transaction list refresh and a balance update.
5. Detected-spend placeholder: When fetchedTransactions processes the transaction list, it also calls getPIRPendingSpends() which queries the local pir_spent_notes SQLite table for notes not yet confirmed by the scanner. If any exist, a synthetic "Detected spend" TransactionState row is appended to the activity feed. This placeholder auto-reconciles — once the scanner catches up and the note appears in orchard_received_note_spends, getPIRPendingSpends returns empty and the placeholder disappears.

Feature flag

All PIR code paths are gated behind WalletConfig.isEnabled(.pirSpendability):

• registerForSynchronizersUpdate — only sends checkSpendabilityPIR if flag is on
• checkSpendabilityPIR — early-returns .none if flag is off
• foundTransactions / syncReachedUpToDate — only triggers PIR check if flag is on
• fetchTransactionsForTheSelectedAccount — only calls getPIRPendingSpends() if flag is on
• fetchedTransactions — only appends the PIR placeholder if flag is on

The flag is defined in WalletConfig (not FeatureFlags) as the single source of truth, togglable via WalletConfigProvider / debug flows.

Demo

Detect Spend During Sync

https://www.youtube.com/watch?v=TMFQUpdcnLo

Once the spend is detected, the balance decreases by the full note amount. The decreased balance remains spendable — enabled by the sync nullifier PIR — until the wallet scans the spend and discovers the output change note.

Comparison to No PIR via Debug Settings

https://www.youtube.com/watch?v=JOKyPA1pqwI

Without PIR, the full balance appears available even though it is partially spent, which would lead to a broadcast failure. Triggering a PIR check via the debug menu shows the balance dropping to the correct spendable amount.

Screenshot

Related PRs

• librustzcash (0.19.x backport): zcash_client_sqlite: Backport PIR spent-note tracking to 0.19.x zcash/librustzcash#2268
• zcash-swift-wallet-sdk: zcash-swift-wallet-sdk: Nullifier PIR integration zcash/zcash-swift-wallet-sdk#1674
• zodl-ios: Detect spent orchard notes via PIR #1675

Test plan

1. Have a wallet with at least one orchard note that has been spent
2. Launch the app — PIR runs at startup and the balance should reflect the spend before the scanner catches up
3. Observe "Detected spend" row in the activity feed
4. Wait for the scanner to catch up — the placeholder should disappear and be replaced by the real transaction
5. Force-close and reopen the app — PIR should re-trigger and the placeholder should reappear if scanning hasn't caught up yet
6. Disable pirSpendability flag — verify no PIR requests are made and no placeholder appears

Checklist

• Self-review in GitHub web interface
• Automated tests added (PIRSpendabilityTests.swift — 10 tests covering success/failure, flag gating, placeholder insertion)
• CHANGELOG updated
• App run and changes verified manually
• Demo videos provided