Grandma's Wallet
A Bitcoin Cash wallet whose keys can be replaced by a trusted recoverer after a public waiting period. Every coin has its own address and key, as in an ordinary HD wallet. A single controller on chain can release any of them to a new owner. Applications give authority to a token in the wallet, so recovering an application position is the same as moving a coin.
This page is the illustrated overview, brought in line with what is built and run as of 19 November 2026. The specification for implementation is Grandmas_Wallet_Architecture_Proposal_v0.4.md in the repository, the order of work is in IMPLEMENTATION_PLAN_v0.4.md, and the test records are in docs/results. What is designed and not yet built is listed under Costs and open points.
The design
Every ordinary address of the wallet can be spent in two ways. Its own key spends it directly, like any single-key address. The wallet's controller can also release it, and the controller obeys whoever owns the wallet's identity today. Recovery changes the owner of the identity. The new owner then moves every coin and token to addresses of its own keys.
The parts
Controller. One coin holding the identity NFT. Its state names the owner's controller key, the recoverer's key and the waiting period. It moves only for recovery, sweeps, the vault and changes of settings.
Recoverable addresses. One per coin, each with its own key for every day and a hidden link to the identity for recovery. A second kind, the vault address, has no key and never changes.
Recoverer and viewing key. The recoverer can replace the owner after the waiting period. It also keeps the viewing key, which lets a new device find every address. Neither lets it spend.
Three rules and a connection. Authority is a token. The wallet's inputs and outputs are the wallet's business. The template says what a token means. The wallet builds each transaction from the application's XO template.
Identity and controller
The wallet's identity is the token category of one NFT. The coin that holds this NFT is the controller. The NFT's commitment is the controller's state, 69 bytes. The controller's script accepts five actions. Four of them send the NFT back to itself with the next state. The fifth closes the wallet and destroys the NFT.
| Action | Signed by | What it does | Used for |
|---|---|---|---|
ownerAuthorize | Owner's controller key | Continues the controller unchanged as Active. Cancels a pending request. | Sweeps, spending from the vault, cancelling a request |
requestRecovery | Recoverer's key | Marks the state Pending and names the proposed new owner key. The waiting period starts. | The first step of recovery |
finalizeRecovery | Recoverer's key | Only after the waiting period. Installs exactly the proposed key and raises the epoch by one. | The second step of recovery |
ownerUpdate | Owner's controller key | Replaces the owner key, the recoverer or the waiting period. Clears a pending request, and raises the epoch when the owner key changes. | Moving to a new seed without the recoverer; changing the recoverer. A change of the waiting period is not on the wallet's screens. |
ownerClose | Owner's controller key | Ends the identity. The transaction has one output without a token, so the NFT is destroyed and the controller's 1,000 satoshis go to that output. | Emptying a wallet for good. Not offered in the wallet's ordinary interface. |
In every action the signature must cover every input and output. In the four that continue the controller, it is input 0 and output 0 of its transaction, the NFT continues and the coin's value does not shrink.
Closing cannot be undone. A vault address works only while the identity's NFT exists, so after closing nobody can spend from one, and a coin that arrives there later is lost. There is no recovery afterwards. The action is part of every controller so that a wallet can be emptied to the last satoshi; the test runs end this way. See Fees and emptying.
The controller's script does not check its own first state. Before trusting an identity, a wallet checks the transaction that created it (one NFT of the category, no way to make another, a valid first state, locked by the controller script) and follows every step of the controller from there to today.
Two properties carry the scheme
- The waiting period is enforced by the network. It is a relative time lock on the controller's own coin. Nobody can shorten it.
- The recoverer's key never spends a coin. A coin released through the controller requires the controller to continue unchanged, with the same owner and no request pending. A request leaves a claim pending and a completion changes the owner, so neither can carry coins with it. This check is one shared function,
ownerApproves(identity), used by every address script. A recoverer who installs a key of its own after a wait that nobody cancelled is then the owner; that is the trust placed in it.
function ownerApproves(bytes32 identity) {
// Input 0 is this identity's controller.
require(tx.inputs[0].tokenCategory == identity + 0x01);
bytes state = tx.inputs[0].nftCommitment;
require(state.length == 69);
require(state.split(1)[0] == 0x01);
// It continues as Active with the same owner, epoch, recoverer and delay.
require(tx.outputs[0].tokenCategory == identity + 0x01);
require(tx.outputs[0].nftCommitment == 0x0100 + state.slice(2, 49) + bytes20(0));
}
Only an owner-signed step produces that successor: ownerAuthorize, or an ownerUpdate that changes nothing. The owner's signature on the controller, which covers the whole transaction, is therefore what approves the release. The simulator under A wallet's life shows the state byte by byte.
Keys and addresses
The wallet works like an HD wallet and uses the same building blocks: twelve words (BIP39) and a tree of keys computed from them (BIP32). One seed on the phone gives a key for every address, and every coin can sit at its own address. What is added is a second, hidden way into each address, and a viewing key that lets someone other than the phone find the addresses again.
secret = hash256(blinding seed ‖ kind ‖ number), the kind as one byte and the number as four bytes, lowest first.| Value | Place in the key tree |
|---|---|
| Controller key | m / P' / C' / 0' / 0 |
| Address key, kind c, number i | m / P' / Ac' / 0' / i (c = 0 given out, 1 change) |
| Blinding seed | SHA-256 of the private key at m / P' / A0' / B' |
| Funding key. The recoverer's balance, in the tree of its own words. A phone's is used only by a wallet that creates itself, which the pages no longer do. | m / P' / W' / 0' / 0 |
| Recoverer's credential, twelve words of its own for each wallet | Recovery key m / P' / C' / 0' / 0 of its own tree |
This is the key tree of the XO engine, which signs with no other key: every key of a template is at m / P' / T' / 0' / n. P is XO's purpose number, 2415 on mainnet and 42415 on test networks. T is the template's number, which follows from the template's content: C for the controller template, A0 and A1 for the two address templates, W for XO's standard wallet template. n counts up from 0. B is 1,651,272,046, a number of this scheme (the bytes of "blin"). The templates that hold keys never change, because a changed template would give other keys.
How this differs from an HD wallet
| HD wallet | This wallet | |
|---|---|---|
| Address | Hash of a public key | Hash of a script that holds the key's hash and a tag |
| Ways to spend | The key | The key, or the controller |
| What gives the addresses | The seed, or the extended public key | The seed or the viewing key, and also the identity |
| Kept per address | A key | A key and a secret |
| Keys outside the address branches | None | The controller key and the blinding branch |
| Losing the seed | Loses the coins | A new seed takes over the identity and the coins are moved to its addresses |
Finding everything again
A device that holds the identity and a viewing key finds that seed's coins in two passes. No list of addresses has to be kept anywhere.
- Quick pass. For each kind of address it derives number 0, 1, 2 and so on, looks each up on chain, and stops after a run of unused ones: 20 for addresses given out, 5 for change and for vault addresses. This is how any HD wallet is restored, and it nearly always finds everything.
- Full pass. It looks up every number of every range. Each kind has a fixed number of addresses per seed, the same for every wallet, so nothing about the ranges has to be stored. This finds what the quick pass can miss, for example an address given out past a gap after the transaction that had closed the gap was dropped.
For each address it finds, the device also has the secret, which is what the recovery path needs. The wallet is reported as fully found only when the full pass has finished for every seed it has had. A server that does not answer gives "incomplete", never "empty".
After a recovery the new device has a new seed and a new viewing key. It gives the new viewing key to the recoverer before the request is made, so the wallet is never without a recovery path. The same holds when an owner moves to a new seed with the old phone at hand: the recoverer confirms that it holds the new viewing key, and only then does the owner key change. Earlier viewing keys are kept: they find payments that still arrive at earlier addresses.
Creating a wallet: whoever has the coins creates it
An address needs the identity, and the identity is the identifier of a transaction, so a wallet's very first coins cannot arrive at a recoverable address. The phone does not fund its own creation: the recoverer does, from its own coins. A bank gives a new customer a small starting balance as part of its service; a friend or family member gives the person they help their first coins. Both pages are open at the same moment, in person or on a call.
- Scan and ask. The phone scans the recoverer's code, makes its keys, and stores its viewing key in its new backup. Once a store has confirmed, it sends a sealed, signed request over the session the code offers: an identifier, its controller key's hash, its viewing key, the access to its backup, the waiting period it was told, and the number of its address for the starting balance.
- Create. The recoverer creates the wallet from its own coins, paying itself first when it has no coin that is output 0 of its transaction. One transaction: the controller naming the owner's key, the recoverer's own key and the waiting period; the starting balance at a change address of the new wallet; the rest back to the recoverer's balance. A bank's page creates without anyone saying yes; a friend's page asks "Set up …'s wallet with …?" first.
- Keep and answer. The recoverer assembles the kit from the request and what it created, keeps it, leaves its receipt in the phone's backup, and answers with the identity, the creating transaction and the hash of its key.
- Check and open. The phone checks the creation as any client does, and that it names its own key, the recoverer that answered and the waiting period it was told. Then it shows "Your wallet is ready", with the balance and "Protected by …".
A request is carried out once: the phone sends the same request again until it has its answer, and the recoverer's page keeps every request and every step, so a reload on either side, or an answer that is lost, gives the same wallet, never a second. The first transaction is trusted. The recoverer could refuse, or create a wallet the phone refuses; it cannot make the phone accept one that names another owner, another recoverer or another waiting period.
Nothing waits for a block. The phone goes on as soon as the network has the creation; the starting balance can be spent at once. This is safe for ordinary addresses because each has two ways in: its own key, which does not involve the identity, and the controller. If the creation were replaced or a block that held it were undone, the coins already paid to them would still be spent by their keys. Only their recoverability would be gone until they are moved. A vault address has no key. It is given out from the first moment as well, and a payment to one would be lost with the creation; that was weighed against making the user wait, and accepted.
So the wallet watches the creation until a block holds it. If it disappears, the set-up did not hold: the wallet says so plainly on its first screen and is set up again with the recoverer. It makes no identity of its own. It keeps the addresses it gave out, numbers the new ones past them, and once it is set up again moves what arrived at the earlier ones to the new wallet with ordinary key payments.
How an address is made
The wallet makes a new address whenever one is needed. Making one writes nothing on chain and does not involve the controller.
| When | Kind of address | Which number |
|---|---|---|
| The user asks to be paid | Given out | The next one never shown before |
| A payment leaves change | Change | The next one not handed out |
| An application's transaction sends the wallet a coin or a token | Change; a vault address when the template asks for a lasting one | The next one not handed out |
| The recoverer creates the wallet with a starting balance | Change | The one the phone named in its request |
| The user wants an address to publish, or to be paid at for years | Vault | The next one |
Every address is built in the same steps. Choose a kind and a number to follow them for one example wallet.
- The phone can do every step. A holder of the viewing key can do all but the private key: it gets each public key from the extended public key.
- Nobody can go backwards from an address. The address is a hash of the script. The tag inside the script is a hash of the identity and a secret that only the viewing key gives.
- Two addresses of one wallet share nothing visible. Each has its own key and its own secret, so each has its own tag.
- The payer sees an ordinary script address. Nothing shows that it is recoverable or which wallet it belongs to. Spending it by key shows the kind of address, and still not the wallet.
- The wallet stays inside a window and a range. It shows no address more than 20 numbers past the last used one of its kind (5 for change and for vault addresses), and none past the fixed range of its kind. When the window is full it offers an address it has already given out, and says so.
- An address made for something that did not happen gets its number used again only if it was never shown and nothing was signed. Otherwise it stays taken and stays watched.
The recoverable address
A script address (P2SH32) with two ways to spend.
contract RecoverableAddress(bytes32 tag, bytes20 keyHash) {
// Everyday path: the key this address was made for.
function spend(pubkey pk, sig s) {
require(hash160(pk) == keyHash);
require(checkSig(s, pk));
}
// Recovery path: whoever owns the identity today, through the controller.
function sweep(bytes32 identity, bytes32 addressSecret) {
ownerApproves(identity);
require(hash256(identity + addressSecret) == tag);
}
}
contract VaultAddress(bytes32 tag) {
// No key. Only the identity's current owner, through the controller.
function spend(bytes32 identity, bytes32 addressSecret) {
ownerApproves(identity);
require(hash256(identity + addressSecret) == tag);
}
}
Compiled, the rules are 96 bytes for the recoverable address and 75 for the vault address, before the tag and the key hash are added. Measured in a trial, an input spent by its key is 296 bytes, a swept input 260 and a vault input 217, against 141 for an ordinary single-key input. The contracts' tests hold these figures.
The wallet's ordinary address, a fresh one for each coin, token and change output. Used for everything the wallet does with applications. After a recovery its contents are swept to addresses of the new seed.
For an address that must outlive a key change: one published to be paid at any time, or a payout address agreed long before the payout arrives. It is meant to be used more than once. Spending from it needs the controller at input 0, so a token is moved from the vault to an ordinary address before an application can use it.
Who can spend what
| Who | Addresses of the current seed | Addresses of an earlier seed | Vault addresses |
|---|---|---|---|
| Owner, current seed | Yes, by signature | Yes, through the controller | Yes, through the controller |
| Recoverer | No | No | No |
| Holder of an earlier seed | No | Yes, until the coin is swept | No |
| Application | Never holds a key. It gets what the owner signs for, one transaction at a time. | ||
The price of the design is in the third row. A coin left at an earlier address still obeys that address's key. Completing a recovery does not disarm the earlier seed by itself; sweeping does, coin by coin. The new device sweeps as soon as recovery completes. See Costs and open points.
A wallet's life
Press the actions in any order. The strip shows the controller's 69 bytes; press a field to read what it is for. The cards show where the coins and tokens sit. Each one is at its own address; the cards group them by the seed their addresses were made from.
Things to try: complete a recovery and use the loan before sweeping. Complete a recovery and let the earlier seed act before the sweep. Request a recovery, then pay someone, and see that the request stays pending.
Fees and emptying
The wallet pays the lowest fee that nodes relay, and works it out from the transaction itself.
- The rate is one satoshi per byte, which is what nodes require. It is fixed in the software and is not a setting on a screen; the wallet does not raise it by itself.
- The fee is exact. It is the size of the signed transaction times the rate. The size is known before signing, because signatures, keys and scripts have fixed lengths: the wallet adds up exact sizes, not estimates.
- The smallest output depends on the output. Nodes relay nothing below 546 satoshis at a single-key address, 576 at an address of this wallet, 888 for the controller, and more for an output with a token. The wallet computes this for every output it creates.
- Change is what can be saved. Every coin costs its bytes once, whenever it is spent. A change output costs bytes now and again when it is spent, so the wallet prefers a choice of coins that needs none.
- Nothing goes to the fee unseen. If what is left is too small to return as change, the wallet compares leaving it to the fee with adding a coin, takes the cheaper, and shows the amount.
- A check before sending. The signed transaction must pay the fee its actual size requires and less than a change output's worth (576 satoshis) above it, hold no output below its smallest value, and pass every script in the virtual machine. There is no other limit on the fee in satoshis, which would stand in the way of a transaction with many inputs.
Where each fee comes from
| Transaction | Who pays | From where |
|---|---|---|
| A payment, an application's action | Owner | The coins being spent |
| A cancel, a change of settings, a spend from a vault address | Owner | The wallet's coins, like a payment: the smallest coin that pays alone, with change to a fresh address. No coin is kept apart. For a cancel, when the ordinary coins hold less than the fee, a vault coin or an unswept coin at an earlier address pays. |
| The sweep after a recovery | New owner | The swept coins; a coin of the new seed when only tokens are swept |
| The request and the completion | Recoverer | Its one balance, in the same transaction that spends the controller. Nothing is kept apart for a wallet, and the owner gives it nothing. |
| Creating the wallet, and its starting balance | Recoverer | Its balance, an ordinary address of its own |
The controller's 1,000 satoshis are not a fee fund. They are what the output needs to exist, and the script does not let an action spend them, except closing.
Sending everything
- What goes: every coin without a token, to one address. There is no change, and the amount is the total less the exact fee. A coin worth no more than the bytes it costs is left out and listed. A very large wallet takes several transactions of at most 100,000 bytes.
- Coins that only the controller can move, at vault addresses or at an earlier seed's addresses, go in the same transaction with the controller.
- Satoshis under a token stay with the token. They leave when the token is sent, or when the user destroys the token on purpose.
- It cannot be done only when the total less the fee is below the smallest output. A single coin of 576 satoshis leaves 236 after its fee of 340, which cannot be sent. The wallet then shows the total, the fee and the smallest output.
- What is left: the controller, coins with tokens, and whatever the recoverer holds. The wallet stays usable and recoverable. Until it holds Bitcoin Cash again it cannot pay for a cancellation.
Receiving and sending tokens
- Every address can hold tokens. Its token-aware form (
z…orr…after the prefix) pays the same script; it is the receiver's word that its wallet knows tokens. The Receive screen shows it first; unticking "Receiving a token?" shows the plain form. - An amount, or one NFT. A fungible token is one balance per category; the wallet gathers its coins, the largest first and leaving alone those that also carry an NFT, and the rest comes back to a fresh change address. An NFT goes whole, commitment and capability unchanged, with any amount on its coin.
- The fee from ordinary coins. Each token output holds the smallest value it may; what the token coins held beyond that comes back with the change in Bitcoin Cash.
- Only to a token-aware address. A plain address is refused before anything is built: a wallet that does not know tokens can destroy them.
- A token that gives more than itself (a key to a position, an NFT that can mint or be changed) is sent only after the review says what it gives and the user ticks that they understand.
Closing
Sending everything with ownerClose in the last transaction also takes the controller's value and ends the identity. Measured at one satoshi per byte:
| Measured | Result |
|---|---|
| Closing with no other coin | 1,000 − 681 = 319 satoshis, below the smallest output: it cannot be sent |
| Closing together with other coins | Adds 1,000 satoshis and 637 bytes: 363 satoshis more arrive |
| Every other controller transaction | 45 bytes larger, because the script is longer |
Closing is therefore the last step of emptying a wallet, never a step of its own. A sweep or a vault spend cannot be part of it; what only the controller can move is moved first. The wallet's ordinary interface does not offer it. A library function does, which the test runs use; it refuses while a vault coin, a token or an unswept coin at an earlier address is held, or before the full search has finished. Whoever holds the owner's key can also build the transaction without this software. The recoverer cannot close.
Recovery flow
- 0
Setup, while all is well
Owner and recovererThe phone scans the recoverer's code and asks; the recoverer creates the wallet from its own coins, naming the phone's key, its own key and the waiting period, keeps the kit and leaves a signed receipt; the phone checks the creation and opens its wallet. Recovery is on once the wallet finds the receipt, which is already there.
- 1
A new device asks
New device and recovererThe recoverer presses "Customer lost their phone", or "… lost their phone", and its page shows a code. The new phone chooses "I lost my phone" and scans it. It makes a new seed and gives the recoverer, over the session of the code, the hash of its controller key, its own viewing key signed with that key, the access to a new backup, and a key for the answer. It does not need to know the wallet's identity yet. The recoverer satisfies itself that the person is the wallet's user before it shows the code; how it does so is its own process, and the design depends on it.
- 2
Request
RecovererThe recoverer's page signs
requestRecoverynaming that key as soon as the request arrives on the lost phone's code. A request that comes another way, as a link or on a set-up code, waits in the page's list until the recoverer has made sure who is asking and chosen the wallet. The controller is then Pending, on chain. The owner's wallet sees the request and warns at once; the waiting period counts from the block that holds it. - 3
Wait, and the owner's chance to refuse
Owner, if the phone is not lostThe wallet watches its controller on several servers. If a request appears that the owner did not ask for, the owner cancels it with one signature of the controller key. Ordinary payments do not touch the controller, so they do not cancel a request. The cancel is a transaction of its own, by hand or, unless the user turns that off, automatically while the wallet's page is open. Any transaction of the owner that carries the controller, such as a sweep, cancels as well. The fee of about 1,100 satoshis comes from the wallet's coins. A wallet that holds only tokens says on the warning that it needs a little Bitcoin Cash to refuse, and where to receive it.
- 4
Complete and hand over
RecovererAfter the waiting period the recoverer signs
finalizeRecovery. The proposed key becomes the owner and the epoch goes up. No coin has moved. As soon as the network shows the completion, the recoverer gives the new device the identity, the viewing key of every earlier seed and the access to earlier backups, sealed to the device: over the session of the lost phone's code when both pages are open, otherwise as a code the new phone scans. The new device sweeps and gives out addresses. - 5
Sweep
New deviceWith the identity and the earlier viewing keys the new device finds every address in use: a quick search first, then a full search of every range. It moves what is there to addresses of its own seed, in transactions that carry the controller, signed with
ownerAuthorize. Each swept input shows the identity and its address secret. Coins, fungible tokens and NFTs move the same way. The fee comes out of the swept coins. A large wallet is swept in several transactions: every coin with a token first, understood or not, then the others by value. - 6
Understand what the tokens are
New device, with the applications' templatesA swept NFT is already under the new owner's control. To show it as "a jar with 0.3 BCH that opens in March" the wallet needs the application's template, from its backup or from the application when the user connects again. A template from an earlier owner's backup is a suggestion: the user trusts it again before the wallet acts on it. Recovery does not wait for this.
- 7
Keep watching
New deviceThe new device watches the controller, and it follows the earlier addresses it found in use for payments that still arrive there. Its coins pay for refusing a request, as on any device. See A payment to an old address.
The recovery kit and the recoverer's key
- The kit contains the identity, the recoverer's credential for this wallet, the viewing key of every seed, where the sealed backups are kept and how to read them, and the settings, for the recoverer to compare with the chain. The recoverer assembles the first kit itself, from the phone's request and the wallet it created, and adds to it whenever the wallet gets a new seed.
- One scan, both pages open. The recoverer's page shows one QR code that holds its name, its key and the address of a WizardConnect session it keeps open while it is shown. The phone scans it, and everything else goes over the session: the set-up request and its answer, a lost phone's request and the hand-over. A code scanned from the bank's page or a friend's screen is a trusted channel: for these there is no fingerprint to compare and no invitation answered hours later. Moving to a new phone with the old one at hand, and changing the recoverer, still use sealed links and a fingerprint compared over another channel; the kit for a new recoverer can also go over its session.
- One page, two ways of working. "I'm a bank": "New customer" shows an activation code and the wallet is set up the moment the phone asks, with nobody saying yes; a list of customers; "Customer lost their phone". "I'm helping someone I know": "Help someone set up" asks who and shows the code, then "Set up …'s wallet with …?" and one tap. Both show the recoverer's balance and an address to fund it, and settings for the starting balance and the waiting period, which the wallet shows as a fact.
- The recoverer's key is one per wallet, not one per coin. Only its hash is on chain, in the controller. No address contains it, and the recoverer never signs for a coin of the wallet. It signs two kinds of transaction: the request and the completion.
- The recoverer uses a different key for every wallet, so the controllers of two wallets with the same recoverer show nothing in common. The recoverer makes this key as a set of twelve words of its own when it creates the wallet; the phone never knows it. (A phone that replaces its recoverer still makes the new one's words, as before.)
- The recoverer pays its own fees, about 2,000 satoshis for a request and a completion, from its one balance, the same that it creates wallets from. A request, or a completion, is one transaction: the wallet's controller, unlocked with the recoverer's key for that wallet, and a coin of the balance for the fee, with the change back to the balance. Nothing is kept apart for a wallet, and the whole balance can be sent to another address. The owner gives the recoverer nothing: the allowance of earlier versions is dropped. What it shows on chain: the wallets a recoverer has created or acted for share its balance as their payer.
- A receipt decides. The wallet says that recovery is on only when the recoverer's signed receipt matches what it was sent and the controller's state on chain.
- A new seed with the old phone at hand, and a new recoverer, follow one order: the recoverer first confirms that it holds what it needs, and only then does the owner sign the change. A recoverer that is replaced keeps what it has already seen.
What each party holds and can do
| Party | Holds | Can do | Cannot do |
|---|---|---|---|
| Owner's device | The seed; the identity; the viewing key | Spend, cancel a request, change the recoverer | |
| Recoverer | Its key for this wallet; the identity; the viewing keys; coins of its own for fees | Request and complete a recovery, and pay their fees. See every address and balance of the wallet. | Spend a coin of the wallet with its key. Shorten the wait. Complete with a key other than the one requested. |
| New device | Its own new seed. After completion: the identity and the earlier viewing keys. | After completion: sweep and spend | Anything before the wait is over |
| Backup stores | Sealed records: copies of the viewing keys, trusted templates, the recoverer's receipts, notes on which template made which token, withdrawals of trust | Hand the records back | Read them |
What the waiting period does and does not protect. It protects against a recoverer who acts without being asked, as long as the owner notices in time. A recoverer who names their own key and is not cancelled gets the wallet. It does not protect against a thief who can use the owner's phone: such a thief can spend at once, as with any wallet.
If a recovery completes against the owner's will, the owner's keys still spend every coin that has not been swept. A wallet that finds itself owned by a key it does not hold stops giving out addresses, makes sure of what it sees on more than one server, and offers to move its coins out at once, to an address the user enters: one of another wallet that does not share this wallet's recoverer. That is a race against the new owner's sweep. Coins at vault addresses cannot be saved this way.
What still waits for a block, and why
Everything that can go on before a block does. A transaction that disappears later takes with it only what was built on it: the wallet follows the chain at every check, and coins at addresses of a device stay that device's by key. Three things wait, each for a reason that cannot be designed away:
- The waiting period of a recovery counts from the block that holds the request. It is a time lock that the network enforces, and a transaction that is not in a block has no age yet. The period is the owner's whole protection, so it is measured by the chain and not by a clock anyone could claim. The owner's wallet shows the request and warns as soon as it is seen; only the count starts with the block.
- A phone stops for good only when a block holds another owner. The moment the network shows another key as the owner, the phone gives out nothing and takes on nothing. A completion that is not in a block can still lose to the owner's cancellation, so until a block holds it the phone only pauses, and carries on by itself if the change disappears.
- Time locks of applications, such as a savings jar's date or a loan's periods, belong to their contracts, not to the wallet.
A payment to an old address
After a recovery, someone may still pay an address the wallet gave out before: an old invoice, an address saved in an exchange's withdrawal list. That coin is not lost. The new owner collects it through the controller, by the same path as the sweep. This is not the vault address; the two are compared below.
- The coin lands at the old address. Receiving runs no script, and nothing on chain tells the payer that the wallet has a new owner.
- The new device notices it. It holds the earlier viewing key, which the recoverer handed over. From it the device derives the same addresses the old phone used. It is to keep watching every address that was used and the window past the last one, and to look up the whole range again from time to time. Today it searches once, on arrival, and then follows the addresses it found in use (not yet built).
- The new device collects it. One transaction: the controller at input 0, approved by the new owner, and the coin, unlocked by showing the identity and that address's secret. The secret comes from the earlier viewing key. The coin goes to an address of the new seed. The wallet shows such a coin, and the user moves it with one tap.
- Until then the coin has two masters. The key the address was made for is on the lost phone, and it still opens the address. This matters only if someone can use that phone.
An old address and a vault address
| Ordinary address from before a recovery | Vault address | |
|---|---|---|
| Has a key | Yes, a key of the earlier seed | No |
| Who can spend a coin that arrives after a recovery | The new owner, through the controller. Also the earlier seed, until the coin is collected. | The new owner only, through the controller |
| What the new owner does with it | Collects it once it is seen, with one tap, to an address of the new seed | Nothing urgent. Spends it through the controller when wanted. |
| What is needed to find and open it | The identity and the viewing key of the seed that made the address | |
| Meant for | One payment; a fresh address is shown for the next | Being paid again and again, or a payout fixed long in advance |
| If the lost phone is found and unlocked | A coin not yet collected can be taken | Nothing can be taken |
| Cost | None in everyday use | Every spend carries the controller, and the first spend shows in public that the address belongs to the identity |
So the wallet shows a fresh ordinary address for a one-off payment and offers a vault address for anything that is published or stored by others. After a recovery it tells the user that people who pay them need a new address.
What others can see
No address shows the identity or another address of the wallet. The ordinary links between coins that are spent together remain, as with any wallet. Choose who is looking.
What ties a coin to the identity
| Event | What becomes linked, in public |
|---|---|
| Creating the wallet | The recoverer's coins it was created from, the address of the recoverer's balance, and the address of the starting balance |
| A cancel or a change of settings | The coin that pays the fee, and its change. The wallet takes the smallest coin that pays alone, so that little is tied. |
| The recoverer's request and completion | Coins of the recoverer's balance and its address, which every wallet it created or acted for shares. Nothing leads to a coin of the owner. |
| Sending everything when a coin in it needs the controller; closing | Every coin in that transaction, and the address it pays |
| A sweep, or collecting a late payment | Every address emptied, and the new addresses the coins go to |
| Spending from a vault address | That vault address |
Nothing else the wallet does shows the identity. A link, once made, spreads in the ordinary way: a coin that is tied to the identity ties to it whatever it is later spent together with.
The controller is readable on purpose
Anyone can see that a controller exists, and read its state. Its state names no address. Hiding the state behind a hash would gain little: every transaction of the controller has to show the state to the script, so it would become public the first time the controller is used. Two simple measures do more:
- The recoverer uses a different key for every wallet. Two wallets with the same recoverer then show nothing in common.
- The owner's controller key signs nothing else on chain. It never appears in an address.
What a recovery reveals
A sweep has the controller as its first input and shows the identity in every swept input. Everything the wallet held at that moment is tied together, in public. Coins received afterwards at new addresses are not, until they are spent together with coins that are. A token whose history is public, such as a loan key, links its position before and after the sweep.
Limiting this would take several controllers, each covering part of the addresses. Hiding it fully would need a way to prove the link without showing it, which this project has not found for Bitcoin Cash and does not claim. Neither is part of this design. A later version of the wallet's scripts could add either without changing applications, because applications are never sent the identity or the controller and deal only with tokens.
Rules for applications
An application that follows these three rules is recoverable by this wallet, and by any other wallet that implements the same scheme, without knowing that recovery exists.
Authority is a token
Whoever may act on a position is whoever spends its ownership NFT in the same transaction. Payouts go to an address the wallet supplied.
No user key or key hash inside an application contract. A key cannot be replaced; a token can be moved. A token its holder can copy moves the authority without taking it from an earlier holder.
The wallet's parts are the wallet's business
The application does not assume the wallet's inputs are P2PKH or have a fixed size. Tokens and change go to an address the wallet names.
"Back to the address it came from" is acceptable: after a sweep that is a new address.
The token leads to the position
From the NFT (its category and commitment), the template and the chain, a wallet can find the position, work out what its actions need, and list the actions it offers.
No application server, no private note and no secret that existed only on the lost phone is needed. What the application itself goes on needing, such as a price oracle, is named in the template.
Why these are enough
- Recovery never touches an application contract. The sweep moves the NFT from one wallet address to another. The position stays where it is.
- The application's transaction layout is its own. The controller is not in application transactions, so an application may fix its input and output positions as it likes.
- A wallet can recover what it does not understand. An NFT of an unknown application is swept like any coin. Its meaning can be learned later.
- Part of this can be checked by a program. Whether a template leaves the wallet's outputs to the wallet, and whether its declaration leads to a position on chain, can be checked mechanically. Whether a contract gives authority to the token and to nothing else takes reading and testing it. A checker therefore gives one of three answers: verified, a violation found, or not verified.
What the rules exclude: positions opened by a key written into the contract, positions whose owner is known only to a server, and front ends that insist on building the transaction themselves from the wallet's public keys.
Template extension
An XO template describes an application's roles, actions, transactions, inputs, outputs and scripts, and the engine builds every transaction from it. Two things are missing for recovery: a way to say that an output is locked by whatever address the wallet chooses, and a way to say what a token means. Both are built as a declaration: a document beside the template, bound to it by identifier and content hash, which the wallet reads and XO does not know. The templates pass XO's validator and run on the unmodified engine. The specification, written as a proposal to XO's authors, is docs/xo-position-recovery.md. The field names are proposals and have not been discussed with them. The fragments below are from the declarations of the Savings Jar and of the loan.
1. An output the wallet locks
// in the template: a variable holds the output's locking script "jarKeyOutput": { "name": "Jar key", "lockingScript": "$(<keyHolder>)", "valueSatoshis": "1000", "token": { "category": "$(<keyCategory>)", "nft": { "capability": "none", "commitment": "$(<unlockTimeBytes>)" } } } // in the declaration: the wallet fills that variable, with a fresh address "actions": { "open": { "creates": "keyCategory", "outputs": { "keyHolder": "receive" } } }
The declaration names the kind of address for each output that is the wallet's. A request may name it too, and must then agree.
| Kind | The wallet supplies | Number taken |
|---|---|---|
receive | A fresh ordinary address of the "change" kind, for a coin or token created now | The next one |
change | A fresh ordinary address of the same kind, for what is left over | The next one |
return | The script of the coin that holds the token the action spends. For contracts that require a token to go back where it came from. | None |
lasting | A vault address, for an address stored now and paid later | The next vault number |
The wallet fills each kind itself and never from an address the application supplies. A return is refused when the token sits at an address of an earlier seed or at a vault address: it is moved first.
A marker inside the template, "lockingScript": { "wallet": "receive" }, would say the same in one place, and on an input "any coin of the wallet". XO's validator rejects properties it does not know, so that form needs XO's agreement and is not built.
2. What a token means
{ "profile": "recoverable-app-v1", "version": 1,
"template": { "identifier": "04db6aef…", "contentHash": "5450fe6a…" },
"authority": {
"jarKey": {
"token": "jarKeyOutput", // which output creates the token
"position": { // how to find what it controls
"lockingScript": "savingsJarLockingScript",
"variables": { "keyCategory": "token.category",
"unlockTime": "token.commitment" } },
"actions": ["deposit", "withdraw"] } }, // what its holder can do
"actions": { // what the wallet supplies for each action
"withdraw": { "spends": "jarKey", "position": "savingsJarInput",
"outputs": { "keyHolder": "receive" },
"variables": { "keyCategory": "token.category", "keyInput": "token.inputIndex", … } } } }
A wallet that holds an NFT and trusts this template fills the two variables from the NFT, builds the jar's address, looks it up on chain and offers the listed actions. For each action the declaration says what the wallet's part is: the token it spends, where the position stands in the transaction, the application's own coins, the outputs the wallet locks, and where each variable's value comes from: the token, the position, a companion coin, an input, or some bytes of a commitment. An action marked fromApplication needs the application's page. The others the wallet offers from its own list of tokens.
3. A position found through a companion coin
"loanKey": {
"token": "keyOutput",
"position": {
"companion": { "lockingScript": "sidecarContract",
"tokenCategory": "token.category", "commitment": "01" },
"relative": -1, // the loan is the output before its sidecar
"genuine": { "lockingScript": "loanContract", // what makes it the real loan:
"tokenCategory": "e7979ccd…" } }, // it carries the deployment's own token
"state": { "debt": "position.commitment[1..7]", "collateral": "position.valueSatoshis" },
"actions": ["manage", "repay", "close"]
}
ParyonUSD keeps a small sidecar coin next to each loan, carrying the loan key's category. The wallet finds the unspent sidecar with that category; the loan is the output before it in the same transaction. Anyone could make a look-alike, so a declaration that finds a position through a companion must say what makes it genuine, or the wallet does not read it. Here the coin before the sidecar must be at the loan's script and carry the deployment's own token, which only Paryon's contracts issue. When more than one coin passes, the wallet takes none. state lets the wallet show what a position holds. This found a live loan on chipnet after a recovery; see ParyonUSD.
4. What the template calls its tokens
"tokens": {
"pusd": { "kind": "fungible", "category": "…", // a category the template names
"name": "ParyonUSD", "symbol": "PUSD", "decimals": 2 },
"loanKey": { "kind": "nft", "authority": "loanKey", // whatever category each key has
"name": "Loan key" }
}
Optional, and ignored by a wallet that does not read it. A description of tokens the template does not deal in is a violation. The wallet shows a name and an amount in the token's decimals only from templates the user trusts, says which one, and uses no name when two trusted templates disagree. No registry is asked: it would be a source the user has not chosen, fetched over the network, and no better checked.
5. The wallet's own templates
The wallet is itself described by XO templates. The engine derives a template's keys from the template's content, so the controller, the addresses given out and the change addresses are three small templates that never change. A fourth, which holds no key and may change, has the wallet's actions, the address of an earlier seed (which can only be swept) and the vault address. XO's standard wallet template is the fifth, for single-key coins such as the recoverer's balance. One transaction can take inputs and outputs of several templates; that is how a sweep carries the controller and the coins, and how an application's transaction takes the wallet's coins.
Trials ran this through the unmodified engine on a local node: one script per address with the wallet's tag, a payment by key, a sweep of several coins each with its own secret, and a new seed taking over an identity that another account created.
Tying a token to a template without a backup. The backup keeps one line per token saying which template made it. If the backup is gone, the wallet can test a token against each template the user trusts: find the position the way that template's declaration says, and check what it finds.
Talking to applications
WizardConnect gives an application and a wallet an encrypted channel, started from an address the application shows as text or a QR code; the wallet page reads such a code with the phone's camera. What travels over it depends on what the wallet offers when it connects.
The ordinary flow cannot serve this wallet. It hands the application the wallet's public keys, and the application derives P2PKH addresses from them and builds the transaction itself. This wallet's addresses are scripts that cannot be derived from public keys alone. The live front ends of Moria and ParyonUSD, read on 16 November 2026, both refuse any wallet address that is not P2PKH, over WalletConnect as well.
The xo_v1 extension
A wallet announces the extension in the WizardConnect session. Nothing in it names an application.
{ "xo_v1": { "version": 1, "network": "chipnet",
"profiles": ["recoverable-app-v1"], // the application rules this wallet relies on
"bindings": ["receive", "change", "return", "lasting"] } } // what the wallet fills in itself
The announcement lists no templates. A list of what the user trusts would tell each application which others the user deals with. The application names its template in its request.
| Message | Direction | Meaning |
|---|---|---|
xo_template_offer / xo_template_answer | application → wallet, and back | The application presents its template without asking for an action; the user trusts it, or not |
xo_action_request | application → wallet | The template's identifier, content hash and declaration (and their texts if the wallet lacks them), the action, the role, the variables, the application's coins the action spends, which of the wallet's tokens it spends, and the time. A request more than ten minutes old is refused. |
xo_action_response | wallet → application | Taken on, to wait for the user; refused with a reason; or the template's texts are needed, and the application asks again with them |
xo_invitation_update | wallet → application | Approved by the user; the template is in the backup; sent |
xo_action_result | wallet → application | The transaction and the tokens the wallet received; or an error, the user's refusal among them |
xo_positions_request / xo_positions | both | Which tokens of this template does the wallet hold, and what does each lead to: a position that is open, closed, not found, incomplete or ambiguous? Answered for the application the user trusted the template with, and for another only once the user allows it. |
Rules the wallet follows
- An unknown template is shown to the user with its name, description and actions, and is trusted only on their word. The template and its declaration are bound by content hash; a later download does not replace them. A request that names another declaration for a trusted template is shown again, and the new one takes over only on the user's word.
- The wallet states what it knows about a template: verified, a violation found, or not verified. Verified means that the checks the wallet can run have passed, not that the contract was audited. Not verified is the ordinary state of a template met for the first time. A violation is named, with the rule it breaks and what that means for recovery, and such a template is not taken in: the user can only decline.
- A template is in the backup before the first signature. Until a backup store confirms that it holds the template, the action is refused. A token whose template went with the phone would be swept and not understood.
- The user keeps the list. The wallet lists the templates it trusts, its own among them, and for each the applications that may see its tokens, which the user can remove. Trust can be withdrawn: waiting requests are declined, the backup is told, and the template stays as a suggestion. Templates from an earlier owner's backup are suggestions as well.
- The user sees two things before approving: the action in the template's words, and the wallet's own figures from the transaction it built. The application cannot influence the second.
- A request is carried out at most once. It is identified by its
id; a repeat gets the stored outcome, and the sameidwith other content is refused. Outcomes are kept for 30 days. - The application is never sent the identity, a viewing key, or anything about other applications. It learns the addresses that appear in its own transactions. It can study the chain like anyone.
- A position is a token. The wallet answers a positions request from the NFTs it holds on chain.
- The wallet signs with the address keys. The controller is not part of an application's transaction.
- A token that carries authority is spent only in transactions the wallet built itself from a template the user trusts, or sent on by the wallet's own Send after the tick described under Fees and emptying. Whoever gets such a token spent in a transaction of their own shape can use its authority.
- A standard signing request is refused. The wallet builds every transaction itself, so it answers no request to sign one that an application built.
- The wallet can act without the application. From its own list of tokens it offers the actions the declaration gives a token's holder, except those that need the application's page. This is how a recovered loan was closed.
Between the wallet and a recoverer's page
The same kind of session carries a phone's set-up request to the recoverer's page and the new wallet back, a lost phone's request and the hand-over, and a kit for a new recoverer, under a second extension of this project's own, separate from xo_v1. The recoverer's page shows the session's address inside its QR code; the wallet announces only this extension and offers nothing else.
{ "gw_recoverer_v1": { "version": 1 } }
| Message | Direction | Meaning |
|---|---|---|
gw_recoverer_particulars | recoverer's page → wallet | Its name, page and encryption key, as its code gives them, and what it offers a new wallet: the waiting period and the starting balance. The wallet sends nothing to a page with another key. |
gw_recoverer_enroll | wallet → recoverer's page | A phone's set-up request, sealed, with an identifier; sent again until answered |
gw_recoverer_enroll_answer | recoverer's page → wallet | Received; created, with the identity, the creating transaction and the recovery key hash, all checked by the phone; or refused with a reason |
gw_recoverer_sealed | wallet → recoverer's page | The sealed bytes a link would carry, and what they are: a kit for a new recoverer, or a new phone's takeover request |
gw_recoverer_sealed_answer | either way | Received; kept; or refused with a reason. Kept is not a receipt: recovery is on only when the wallet finds the receipt. From the phone, kept says it has the hand-over. |
gw_recoverer_hand_over | recoverer's page → wallet | The hand-over after a recovery, sealed to the new phone; sent again until it is kept |
The hand-over reaches the new phone over the session of the lost phone's code if both pages are open when the recoverer completes; otherwise the new phone scans its code from the recoverer's screen.
This is the part that most needs XO. XO has invitations and a sync client but no protocol between a website and a wallet. A standard would best come from XO, or as a WizardConnect extension that both projects agree on.
Savings Jar
The demonstration application. A jar holds savings until a date. Anyone can pay in. After the date, whoever holds the jar's key NFT can empty it. The jar's contract knows nothing about wallets, keys or recovery.
contract SavingsJar(bytes32 keyCategory, int unlockTime) {
// Deposits are ordinary payments to the jar's address.
function withdraw(int keyInput) {
// Opens for whoever spends the jar's key NFT in this transaction.
require(tx.inputs[keyInput].tokenCategory == keyCategory);
require(tx.time >= unlockTime);
}
}
- The key. Opening a jar creates one NFT of a fresh category and sends it to the wallet. Its commitment is the unlock time.
- The jar's address follows from the key alone:
P2SH32( SavingsJar(key.category, key.commitment) ). That is rule 3. - One contract for every wallet. An ordinary wallet holds the key NFT at a P2PKH address and the application builds the transaction. Grandma's Wallet holds it at a recoverable address and builds the transaction itself. The jar cannot tell the difference. Both were run on chipnet, the ordinary wallet being an unmodified Cashonize.
- The key is kept. Anyone can pay in again later, and a jar whose key was destroyed could never be emptied. The contract does not require this; the template's withdrawal returns the key, and the wallet checks that output before it signs.
The jar trusts the category. Only the transaction that opens the jar can create tokens of it, and the wallet builds that transaction from the template with exactly one NFT. A wallet that made two keys for one jar would only have two keys to its own jar.
What this asks of the wallet: it must carry out template actions that create a token. Creating a category needs a wallet coin that is output 0 of its transaction, so the wallet may first have to make one by paying itself.
ParyonUSD
ParyonUSD lends its dollar token, PUSD, against BCH collateral. Each loan is managed by whoever holds its loan key NFT. That is rule 1 already, on chain, in contracts that need no change. This project wrote an XO template with a declaration for it, and a loan page of its own. On Paryon's chipnet deployment a loan was opened from the wallet, outlived the loss of the phone, and was closed by the new one. Paryon's public contracts are used unchanged. Its team was not asked, and the loan page says on every screen that it is an independent demonstration.
The loan key is a bearer NFT. The borrowing contract checks its category and not where it is sent. The key can mint, so its holder can make further keys, and a sweep cannot cancel a copy made earlier. For a seed that someone else has read, the remedy is to close the loan.
The five contracts read put no condition on the wallet's script. Managing a loan requires the key to go back to the address it left, which is the return kind. The official front end accepts P2PKH wallets only; this project's loan page serves the wallet.
The sidecar coin carries the loan key's category, so the loan is found from the key. The declaration says so, and says what makes the loan genuine.
What was run, and what was not
Run on chipnet, 18 November 2026
- On Paryon's test deployment
chipnet-fast-periods-6, with the contracts of the npm package@paryonusd/contracts1.1.0. - By plain script: a loan key was made, 100 PUSD borrowed against about 0.6 BCH, collateral added and the loan closed. The key and the PUSD arrived at recoverable addresses. No step waited for a block.
- Through the wallet, from the template: the same, with no code in the wallet that knows Paryon. Then the phone was lost. After the waiting period of 8 minutes the new device swept the key and the PUSD, found the loan from the template in its backup and the chain, and closed it from its own list of tokens.
- From the loan page, in browsers: the same course. The new phone listed the loan with its debt and collateral and closed it without the page.
- The engine built every transaction, the borrow with four Paryon contract inputs and seven fixed outputs. Paryon's shared contracts have too long a history for the engine to follow, so the wallet unlocks them from the template and hands the coins over.
- Each course cost between 102,000 and 110,000 satoshis, 90,915 of them Paryon's borrowing fee.
Not run, and what to know
- A repayment that leaves the loan open was not sent. It takes a loan of 200 PUSD, about 1.1 test BCH. It passes in the virtual machine against the live outputs.
- The deployment's keepers have stopped: its stored price was near $275 while the oracle signed $208. The contracts ask for 100 PUSD at least, at 110% collateral, plus a 0.25% fee. The loan page reckons at the lower price and takes nothing under 115%, so a loan needs about 0.6 test BCH.
- The sweep and an action of the loan are separate transactions: the sweep needs the controller as its first input, Paryon's actions their price contract.
- The other 21 contracts (interest, redemption, liquidation, staking) were read only as far as they bear on a loan.
- Paryon's transaction-building library is not public; ours is written from the contracts. Its repository states no licence, so the npm package is used as a dependency and not copied.
One consequence for privacy: managing a loan returns the loan key to the address it left, so the key stays at one address for as long as the wallet does not move it. That address is known to anyone who looks at the loan. A sweep moves the key, and the key's public history then links the loan to the recovery.
Other applications
Where four existing applications stand against the three rules. Contract findings are from their published sources. ParyonUSD was run with this wallet; the other three were not.
| Application | Rule 1 · Authority | Rule 2 · Wallet's parts | What it would take |
|---|---|---|---|
| ParyonUSD | Met Loan key NFT, which its holder can copy; staking receipt NFT | Front end P2PKH wallets only | Done for loans: a template with a declaration, and a loan page. No contract change was needed. |
| Moria | Met Borrower NFT, named in the loan by its hash | Front end P2PKH wallets only | A template and a front end, as for ParyonUSD. Its chipnet deployment was not checked. |
| Cauldron | Not met A pool is opened by a key hash written into it | Met for trades, which fit any position | A pool variant whose withdrawal follows a token. A contract change. |
| BCH Bull (AnyHedge) | Partly Payout goes to any script, so to a vault address. Early exit needs two fixed keys. | Not studied | Payout at maturity survives recovery as it is. Early exit needs authority by token or by address. |
Trading on Cauldron holds no position, so it needs only rule 2 and a template. The pattern across the four: applications that already use an ownership NFT need a front end; applications that wrote a key into a contract need a contract variant.
Backup and self-recovery
What a recovery depends on
| Information | Needed for | If it is lost |
|---|---|---|
| Identity | Everything | The recoverer cannot act. It is in the kit. |
| Viewing key of every seed | Finding coins and showing their secrets | Coins at that seed's addresses cannot be found or swept by a new owner. This is the one thing that must not be lost; the recoverer's kit holds them all. |
| An application's template | Showing what a token means and using its position | The token is still swept and safe. The template can be had again from the application or from any copy, and is trusted again by the user. |
| Which template made which token | Convenience | The wallet can test a token against the templates the user trusts. |
No record per payment or per address is needed, which keeps the backup small. Backup stores hold sealed copies and cannot read them. The recoverer can read them, so a record counts only if it is signed by a key that the controller's history shows as an owner, or as the owner a pending request proposes. A signature does not show when a record was made, so for viewing keys the recoverer's receipt decides which record counts, and a record from an earlier seed never overrides the current owner's. After a recovery, or a move to a new seed, the new device starts a new backup, because the earlier phone knows the key of the old one.
A backup the user keeps
The design does not need one and supports one.
- What to keep for the current seed: four lines: the network, the address scheme, the wallet's identity (64 characters) and the twelve words. The first two say which rules the words belong to, and a backup without them is refused. A device with all four is the same owner. It recomputes every key and address of that seed, finds its coins by searching, and needs no controller transaction and no waiting period. Nothing more is needed, because the search ranges are the same for every wallet. The first screen takes it under "I have my own backup".
- What that leaves out: addresses of earlier seeds. If the wallet has been recovered or moved to a new seed before, payments that still arrive at earlier addresses, and earlier vault addresses, are found only with the earlier viewing keys. A complete backup adds them.
- It is not a standard wallet backup. The words alone restore nothing in another wallet, and nothing here without the identity.
- It goes stale at a recovery or a change of owner, because the wallet then has a new seed. It must be made again, and an old backup cannot undo the change.
- Whoever holds it has the wallet at once. The waiting period guards against the recoverer, not against someone holding the words.
Being your own recoverer
The recoverer's role is a key and the kit. Nothing requires a business: a second device of the user's, or a family member's phone, can hold the kit. A wallet has one recoverer at a time, and the owner can replace it.
Design choices
| Choice | Alternative | Why this way |
|---|---|---|
| The controller stays out of everyday transactions | Every spend passes through the controller, so a key change takes effect at once and nothing has to move | That alternative puts one coin into every transaction of the wallet. All activity becomes linkable, only one action can be in flight, two such wallets cannot share a transaction, and every application has to make room for the controller at a fixed position. |
| Authority is a token | The application's contract names the wallet's identity and checks the controller itself | The application would have to know this scheme and carry its code. A token is something existing applications already use, and it moves with an ordinary transfer. |
| The wallet builds the transaction | The application builds it from the wallet's public keys and the wallet signs | The application would have to understand the wallet's scripts. With a template the wallet knows what it is signing and the application needs no knowledge of the wallet. |
| One address per coin, identity hidden in a tag | One address for the whole wallet, with the identity in its script | A single address makes the wallet as traceable as an account number. The tag costs one hash and one secret per address. |
| The recoverer keeps the viewing key | The new device finds addresses from public data alone | Addresses that can be found from public data can be found by everyone. The recoverer is already trusted with the wallet's future. |
| Readable controller state | A hashed state | The state is shown whenever the controller is used. A key per wallet for the recoverer removes the one field that could link wallets. |
| A vault address beside the ordinary ones | Only key-bearing addresses | Some payments arrive long after the address was given out. A key-bearing address goes stale at recovery; a vault address does not. |
The parts, in the order they depend on each other, and where each stands
- Trials with the XO engine. Done: it holds one address per coin, carries a sweep, combines templates in one transaction and lets a new seed take over, with keys of its own tree.
- The recoverable address and the vault address, the controller's closing action, the exact fee and the smallest value of each output. Built; run on a local node and on chipnet.
- The wallet's keys. Seed, address chains, viewing key; giving out and finding addresses. Built; a full pass was measured.
- Creating a wallet, and the wallet on the XO engine. First coins, receiving and paying, choosing coins, sending everything. Built; run on a local node.
- The recoverer. Recovery kit, receipts, request, completion; the owner's monitor and cancel. Built; run on a local node.
- A new device takes over. Finding addresses with the viewing keys; the sweep. Also a new seed without loss, and a new recoverer. Built; run on a local node and on chipnet.
- The pages for the wallet and the recoverer, and the public demonstration. Built; public on chipnet.
- Applications. The
xo_v1extension; building from an application's template; actions that create tokens; finding a position from a token. Built; run on a local node. - Savings Jar, with its template and declaration. Built; run in browsers on chipnet with this wallet and with an unmodified Cashonize.
- ParyonUSD. A loan from recoverable addresses by plain script, then from the template, then from the loan page. Built; a live loan was recovered on chipnet.
- Two short specifications for XO. The application rules as a template profile are written, in
docs/xo-position-recovery.md. The one for the recoverable address is not.
The stages, and what must hold before each is done, are in IMPLEMENTATION_PLAN_v0.4.md. The record of each stage's acceptance tests is in docs/results, and the runs on a local node and on chipnet are in docs/runs.
The pages
| Page | What the user meets |
|---|---|
| Wallet | The first screen has two groups. "New wallet": "I have a code from my bank" and "Someone I trust is setting it up". "I had a wallet before": "I lost my phone", "I still have my old phone" and "I have my own backup". Then the balance, Receive, Send, the applications with the list of templates, and Recovery. The screens carry little text; explanations sit behind a "?". Codes are scanned with the camera, or pasted. On a test network the page says so, and names the recoverer page where someone trying it out can play the bank. |
| Recoverer | "I'm a bank" or "I'm helping someone I know", chosen once. Its balance with an address to fund it, its wallets or customers, the requests that came as links, the chain's clock for the waiting period, settings, and "Start afresh", which erases what the page keeps; the words of its balance can be saved first. |
| Savings Jar | Serves a wallet that carries out actions itself and an ordinary wallet, such as Cashonize. It can offer its template, and list the jars a wallet holds. |
| Loan page | "Borrow PUSD against BCH" on Paryon's chipnet contracts. Not affiliated with Paryon, and it says so. |
| Landing page | Links the four pages, and says how to arrange the screens and what to try. |
While a page opens, the engine checks the chain's block headers; when that takes long, the page offers to check afresh. Every screen that can hold the user has a way back.
Costs and open points
Costs of the design
- An earlier seed works until the sweep. Someone who later finds the lost phone can take a coin that was not swept. The new device sweeps as soon as recovery completes.
- Payments to an earlier address. A coin sent to an old address after recovery can be moved by the new owner through the controller, and also by the earlier seed. People who pay the wallet need a new address, or a vault address, which does not go stale.
- A vault address before the first block. The wallet gives one out as soon as it is created. If the creation then disappears, a payment already made to that address can be spent by nobody. Ordinary addresses keep their keys and do not have this risk.
- A token that can be copied. Recovery moves a token. Where the holder of a token can make more of it, as with Paryon's loan key, a copy made before the sweep keeps its power.
- The recoverer can read the wallet. The viewing key shows every address and balance. It gives no power to spend.
- The viewing key of every seed is needed to recover. Without it the new owner cannot find that seed's addresses or show their secrets. The recoverer has to keep each one; sealed copies are in the backup stores.
- A recovery is public. The sweep ties together everything the wallet held.
- A request is not cancelled by ordinary use. The owner's device has to notice it and cancel.
- Refusing needs a little Bitcoin Cash. No coin is kept apart for it. A wallet that holds tokens or positions and next to no Bitcoin Cash cannot refuse a request until about 1,100 satoshis arrive; the warning says so and shows an address.
- Larger transactions. Spending a script address costs more bytes than P2PKH: 296 for an input spent by its key against 141, as measured.
- The first coins are traceable. They can be followed to the creation of the identity.
- Applications have to be reached through a template. Front ends that build transactions from the wallet's public keys cannot serve it.
- A complete search is a long one. It looks up every address of fixed ranges, for every seed the wallet has had. A seed has a fixed number of fresh addresses; after that the wallet uses addresses again or the owner moves to a new seed.
- An old identity can outlive its rules. A vault address that was published goes on being paid, so a wallet that moves to new controller rules keeps the old identity in service.
- Templates that hold keys can never change. A change means other keys: a new seed's worth of addresses, or a new identity.
- Closing has a price. The action makes every controller transaction 45 bytes larger, and closing turns the identity's vault addresses into addresses nobody can spend from.
Open points
- The ranges. The sizes proposed from measurement are 10,000 addresses given out, 10,000 for change and 1,000 vault addresses for each seed. Repeating the full search once a week is proposed and not built.
- Confidence in the chain. The engine checks block headers when a page opens. What the wallet reads about its own transactions and their confirmations it still takes from the servers it is set up with, two in the demonstration, the user's own node among them. It shows it as information, waits for it only for the things under "What still waits for a block", and does not call chain state verified.
- Watching on a phone. A phone that is switched on is not thereby watching the chain. Background operation on phones has to be shown before protection is claimed. The wallet watches while its page is open, and says so beside its status.
- Whether closing stays. A released wallet could keep the action in the controller, keep it out of the interface as now, or offer it.
- Both pages at once. Setting a wallet up and asking for it on a new phone need the recoverer's page and the phone open at the same moment. That has been tried in browsers on one machine, not on real phones or through public relays.
- The template extension. Whether "the wallet's own address" and the recovery declaration belong in the XO schema or stay in a companion document, as built, is for XO to say. The proposal to its authors is
docs/xo-position-recovery.md. - Application state that is not on chain. Accounts opened by signing a message with a key, or state kept on a server, are outside these rules.
- Positions that change without the wallet. A liquidated or redeemed loan leaves the wallet holding a key to nothing. The wallet then shows the position as closed, and as incomplete or ambiguous when the chain does not settle it. None of these has been met on a live deployment.
- The extended public key and a leaked address key. As in any HD wallet, the two together give every key of the chain. The viewing key must stay away from anyone who could also obtain one of the wallet's private keys.
- None of this is audited.
Designed, not yet built
- Watching earlier addresses. The design has the new device watch every earlier address that was used and the window past it, repeat the full search, and collect a late coin by itself. The wallet searches once, when it arrives on a device. After that it follows only the earlier addresses it found in use, so a payment to an old address that had never been used is not seen. A coin it does see is moved with a tap.
- Plain coins at a vault address. Tokens there can be moved to an ordinary address. Bitcoin Cash there leaves only when everything is sent, or as the fee of a cancel.
- A spare payer for every controller fee. A vault coin or an unswept coin pays for a cancel when the ordinary coins cannot. A change of settings and a move of vault tokens have no such payer.
- Labels. The backup can hold them. The wallet sets none.
- Closing for a user. It is a function that the test runs call, with no screen or tool of its own.
- For XO. The marker inside a template for an output the wallet locks, and a specification of the recoverable address.
Sources
- ParyonUSD: npm package
@paryonusd/contracts1.1.0; its live front end and chipnet deployment. - Moria, Cauldron and AnyHedge: their published contract sources and, for Moria, its live front end.
- WizardConnect and WalletConnect for Bitcoin Cash: their published protocol descriptions.
- XO: its guide and template format.
- This project's records:
docs/results,docs/runs,docs/decisions.mdanddocs/xo-position-recovery.md.