wallet persistence

[endophysics]

This PR persists the Crosslink internal wallet across restarts by saving a local wallet.snapshot cache under state.cache_dir. The snapshot stores derived wallet state, known transactions, the PoW hash cache, and the Orchard shard tree, and is only loaded when its seed and genesis hash match the current node.

It also hardens startup behavior around the internal wallet and zaino:

• skips wallet snapshot persistence in ephemeral mode
• adds config knobs for disabling the headless wallet, disabling zaino, and resetting zaino on startup
• fails startup if the internal wallet requires zaino but zaino cannot start
• documents wallet.snapshot as a local tip-derived cache, not recovery authority

Snapshot parsing now rejects invalid magic/version data, oversized fields, mismatched seed/genesis, and trailing bytes. Focused tests cover round-trip loading, seed/genesis mismatch, and oversized snapshot rejection.

wallet.snapshot is intentionally treated as a local tip-derived cache, not consensus or recovery authority. If chain state is rolled back or rebuilt, operators should move it aside and let it regenerate from verified chain state.

[br33zybail]

Field report from running this branch in production (public bootstrap node, 108.254.151.52) through the 2026-07-15 h225000 fork incident. The snapshot guard worked as designed but discarded a provably-clean scan; suggesting a refinement.

Sequence: our node followed the minority branch at the fork, so the wallet snapshot's tip label was written as 225,000. After we invalidateblock'd back to the last common block (224,999), Zaino's tip read 224,970. On restart the guard fired: wallet snapshot at height 225000 is ahead of Zaino tip 224970; starting wallet scan from genesis

But the snapshot's highest scanned height was 213,760, ~11,000 blocks below the fork point, entirely common-history, and therefore uncontaminated by the orphaned branch. A full genesis rescan (~2 days here) re-derives state the snapshot already held safely.

Suggestion: gate on the snapshot's highest scanned height vs the reorg point (or Zaino tip), rather than the snapshot's tip label vs Zaino tip. Snapshots whose scanned region lies entirely below the divergence are safe to keep; the guard still fails closed when scan data could actually overlap orphaned blocks. Happy to draft the patch if useful, journal excerpts available.

[judah-caruso]

Thanks for submitting this @endophysics! The other devs and I will take a look at this as soon as we can.