Upgrades and Migration
A pool can never be changed. Its script leaves are fixed when its address is made, and no key can spend it. So an upgrade is always a new pool, and the only question is how value gets there.
The old pool cannot judge the new pool’s code, so it cannot choose a successor for anyone. What it can enforce is that a note’s value goes only where its owner’s proof says. So migration is per user and opt-in: each owner proves a spend whose destination is the successor they choose. No key, timelock or vote moves anyone’s funds.
Two routes
Section titled “Two routes”| route | how | cost per note | status |
|---|---|---|---|
| M1 | withdraw (or exit) to the successor’s deposit address | ~570 vB (estimate) | built; run with stand-in verifiers |
| M3 | a migrate record in a settlement; the successor imports it | ~60 vB (estimate) | built; run with real proofs on 2026-11-04 |
M1 uses paths that already exist. Its amounts are public on the way between pools, which keeps a successor from inheriting the old circuits’ bugs.
M3 is cheaper and more private. A migrating contribution publishes a migrate record: the new note for the successor and the successor’s import address. The settlement pays the migrated total to that address. The successor’s import leaf brings the notes in. Since 2026-11-04 the migrant pays the successor’s import fee from the migrated value (carried in the record), so a brand-new successor can settle its first import on its own. M3 trusts the old circuits for the amounts it imports, so it is never the route out of a pool with a known soundness bug.
What has run
Section titled “What has run”With real proofs on a GSR regtest node (2026-11-04): five settlements across two pools, 197,000 sat migrated, imported, recovered from the chain in the successor, and partly withdrawn, with the supply check passing throughout. An import that pays a nonzero import fee has run with stand-in verifiers only.
The promise to a user
Section titled “The promise to a user”Proposed wording, from the design notes:
- Only you can move your note. No developer, prover, miner or majority of holders can spend it or send it elsewhere, before or after an upgrade, as long as the code that checks your proof is correct.
- Upgrades are opt-in. A new pool never takes your funds. If you do nothing, your note stays where it is, and you can withdraw it while that pool works, or exit it alone while its exit path works.
- Choose a successor with care. The old pool cannot check the new one. Your wallet can check that the address matches the published code; whether that code is right rests on its reviewers.
- A bug that lets someone forge notes can cost you money. The pool can never pay out more bitcoin than it holds. Within that, withdrawals are first come, first served, and no upgrade can undo a theft.
What no migration can fix
Section titled “What no migration can fix”- Choosing correct successor code. That is a matter of review, not of covenant.
- Undoing a soundness break. Forged notes look like real ones. Migration lets honest users leave; it cannot make them whole.
- A frozen pool coin. If code every leaf shares cannot be satisfied, the coin is stuck.
- Past privacy after a zero-knowledge flaw. Old proofs stay on chain.
- Users who do not act. Nothing moves them.
- Quantum computers. Moving to a quantum-safe output type needs Bitcoin to add one first.
Re-pins and test pools
Section titled “Re-pins and test pools”Every circuit change makes a new pool address (a re-pin). On test networks an old pool is simply abandoned and a new one is made; that is what happens on gsr-net now. Before real money, the plan is to use every re-pin as a migration drill instead.