Seed Recovery
This is the floor the design holds to: someone who was offline for a long time, and finds every Cheshire node gone, can rebuild their whole wallet and history from their twelve words and Bitcoin alone, then leave with all their funds.
It works because every record is on chain and bound to the proof that made it, and nothing a wallet needs is published anywhere else.
Where each note comes from
Section titled “Where each note comes from”| your note | how the wallet finds it |
|---|---|
| change from your own spend | its (rho, r) come from your sk and the nullifier of the spend’s first input, which is on chain |
| a deposit | its (rho, r) come from your sk and a deposit counter; its amount is the record’s public deposit word |
| a payment to you | from the payment code handshake and a counter; the amount from the memo word |
| your prover pay | from a one-time pay key your seed derives for each settlement’s starting state (paying the provers) |
How a recovery runs
Section titled “How a recovery runs”- Start from the pool’s genesis (the app knows it, or learns it on its first sync).
- Read every settlement in order, checking each in its block (the light client).
- Replay the records to rebuild both trees.
- For each record, try your keys: your change, your deposits, every handshake addressed to you, every payroll for your pay keys.
- Keep the notes that open, and drop the ones whose nullifiers are already in the tree (spent).
- Resume your payment counters past what you already used.
On the iOS app, Restore takes the twelve words and does this over the next syncs. From a
shell, cheshire-aggregator recover and prover-wallet do the same.
What it needs
Section titled “What it needs”- The twelve words (and the passphrase, if you set one).
- Bitcoin’s blocks since the pool’s genesis: archival block data, which every full node has.
- A light client needs either a Cheshire node to serve the history, or Bitcoin peers that serve compact filters. With the pool pinned, peers alone are enough.
What it does not cover
Section titled “What it does not cover”- Deposit coins still on their way in (not yet settled) are found from the wallet’s saved deposit records, not from the seed alone. A fresh wallet does not yet scan for them automatically. A group return pays them back to keys your seed derives, so the coins are not lost, only not yet found by a fresh install.
- A payment with a wrong memo cannot be found (payment codes).
Status
Section titled “Status”Run on a GSR regtest node with real proofs: after every one of nine settlements in the share-chain runs (2026-10-29, 2026-11-04), every wallet was rebuilt from its key and the chain alone to the expected balance, and a prover’s wallet recovered its pay from its seed and spent it. The light client’s recovery (no node of your own) was checked in the stand-in regtest run.