Backup & recovery

This is the page that, if you skip it, is the one that costs you money. Read it before you put anything real in.

Self-custody has a hard edge: there is no "forgot password" email, no support agent who can let you back in. What protects you is a backup you made ahead of time. Two of them, actually, and you want both.

The two things that can save you#

Your 24-word recovery phrase, on paper. This alone can rebuild your keys from nothing, on any machine. It is the master key. Anyone who reads it owns your money, so treat it like cash — offline, private, somewhere you will still have it in five years.

A copy of your wallet folder (~/.canonical), taken with the wallet stopped. This restores your whole setup — addresses, teammates, rules, history — not just the keys.

terminal

# stop the wallet first, then:
cp -a ~/.canonical ~/canonical-backup-$(date +%Y%m%d)

Keep the two apart. The phrase can recover the money on its own; the folder without the phrase is useless if the keys inside are ever lost.

Making a wallet: create vs. bring your own#

Create (wallet wallet create) makes a brand-new wallet with a fresh 24-word phrase. It shows the phrase once and then makes you confirm it before it will let you sign — that gate exists so you cannot fund a wallet whose phrase you never actually wrote down.
Import brings an existing wallet in — wallet wallet import-mnemonic for a phrase you already have (there is a raw-private-key path too). Imported wallets are ready immediately but stay locked until you unlock.

The confirm-your-backup step only applies to freshly created wallets:

terminal

wallet wallet reveal-backup    # shows the phrase again — but ONLY before you confirm
wallet wallet verify-backup    # confirm a few words; now signing is unlocked

Once you confirm, reveal-backup stops working. That is intentional — the phrase belongs on paper, not on tap from a running program.

Locked and unlocked#

Your keys sit encrypted on disk. Unlocking (wallet wallet unlock) decrypts them into memory so the wallet can sign, and starts a timer. The wallet re-locks when you tell it to, when that timer runs out, or when it restarts — wiping the keys back out of memory. Nothing is lost; you just unlock again.

Check where you stand anytime, and why:

terminal

wallet --json status     # look at "locked" and "lock_reason"

More addresses from the same phrase#

terminal

wallet wallet derive-account

This adds another address, still covered by your one recovery phrase — you do not need a separate backup per address. It sticks even if the wallet locks later.

Changing your password#

Your password is what encrypts the vault; it is not your recovery phrase. Changing it re-encrypts your keys under the new password and leaves your addresses exactly as they were.

A safety catch you might trip#

On startup the wallet checks that its key file is the same one it saw last time. If it does not match — say you copied a vault.json in from somewhere else — it refuses to unlock and tells you why (vault_document_changed). Do not fight it: restore the whole folder from a good backup instead. It is protecting you from quietly running with the wrong keys.

If the worst happens#

Situation	What to do
Forgot the password, have the phrase	Recreate the wallet from the phrase, set a new password.
Lost the machine, have a folder backup	Restore ~/.canonical on a new machine, unlock.
Lost the machine, have only the phrase	Fresh install, recreate from the phrase. You keep the money; you lose extras like teammate registrations and history.
Lost both the phrase and the folder	The money is gone. No one — including us — can recover it. This is the real cost of holding your own keys.

If a file ever looks corrupted#

If the wallet finds a damaged file it sets it aside (renamed *.corrupt-...) and carries on safely rather than crashing. If you see one, prefer restoring from your backup over continuing. Troubleshooting has the details.