Backup and restore

There is currently no single command or RPC method that produces a complete wallet backup (#195 tracks adding one). Until it exists, backing up a Zallet wallet means keeping copies of the files and secrets described here.

What needs backing up

A Zallet datadir contains two files that matter for recovery:

Additionally, each mnemonic phrase the wallet holds (created with zallet generate-mnemonic or imported with zallet import-mnemonic) is an independent root of spend authority that can be backed up on its own.

Two facts drive everything below:

• wallet.db as a whole is not encrypted. Spending key material inside it is encrypted to the age identity, but transaction history and viewing keys are stored in the clear — treat any copy of wallet.db as privacy-sensitive.
• A mnemonic is not a complete backup. It covers only the accounts derived from that seed. Spending keys imported with z_importkey, and watch-only material imported with z_importaddress or from a zcashd migration, exist only in wallet.db. If the wallet holds multiple mnemonics, each one must be backed up.

Taking a backup

1. Stop Zallet. wallet.db is a SQLite database; copying it while the wallet is running can produce a torn copy.
2. Copy wallet.db and the identity file to secure storage. The identity file only changes if you regenerate it; wallet.db changes continuously, so back it up on a schedule.
3. Record your recovery metadata (see below).

If you lose the identity file — or forget its passphrase, if it is passphrase-encrypted — the key material in every copy of wallet.db becomes permanently undecryptable. Store the identity file separately from wallet.db where practical, since together they grant full spending access.

Encrypting backups before upload

wallet.db as a whole is not encrypted (see Wallet encryption). Transaction history and viewing keys are stored in the clear, so any copy of the file, even one held by a backup service you do not fully control, exposes your full transaction history. Encrypt the database before uploading it to any third-party storage:

age -r <recipient> wallet.db > wallet.db.age

rage works the same way (rage -r <recipient> wallet.db > wallet.db.age). The recipient is the age public key from your wallet’s encryption identity, or any other age recipient you control.

Do not bundle the identity file in the same encrypted archive as wallet.db. Together they grant full spending access; encrypting them together means whoever decrypts the archive can spend. Back them up to separate locations.

Backing up a mnemonic

A phrase that Zallet generated for you exists nowhere else until you write it down, so Zallet asks you to confirm that you have: until you do, it will not derive new accounts or addresses from that phrase (see keystore.require_backup in the configuration reference). Export and decrypt the phrase as described below, write it down, and then run zallet confirm-backup, which asks you to read three of its words back. A phrase you imported with zallet import-mnemonic needs no confirmation, since you already had it.

zallet export-mnemonic exports the mnemonic for a given account. The output is not plain text: it is encrypted to the wallet’s age identity, so decrypting it later requires the identity file (and its passphrase, if set). If you want a plaintext copy — for example, to write on paper — decrypt the export with the age or rage CLI using your identity file.

Recovery metadata

Restoring accounts from a mnemonic requires more than the phrase itself. Record, at backup time, for each account (all visible in the output of the z_listaccounts and listaddresses RPC methods):

• the seed fingerprint (seedfp) identifying which mnemonic it derives from,
• the ZIP 32 account index,
• the account name, and
• the birthday height (recovery scans the chain from this height; an earlier guess works but slows recovery down).

Restoring

From a full backup (wallet.db + identity file)

1. Stop Zallet (if running).
2. Place the backed-up wallet.db and identity file at their configured locations in the datadir.
3. Start Zallet. The wallet resumes from the state captured in the backup and syncs forward; transactions received after the backup was taken are picked up by chain scanning.

This is the only restore path that recovers imported keys and watch-only material.

From a mnemonic

1. Set up a fresh wallet: create a config, then run zallet generate-encryption-identity and zallet init-wallet-encryption (see Wallet setup).
2. Import the phrase with zallet import-mnemonic. It prints the seed fingerprint; check it against your recovery metadata.
3. Start Zallet, then re-create each account with the z_recoveraccounts RPC method, passing the recorded name, seedfp, zip32_account_index, and birthday_height for each. The wallet then scans the chain from the birthday heights to recover funds and history.

Anything a mnemonic does not cover — imported spending keys, imported addresses and viewing keys — is not recovered by this path, and must be re-imported from its original source if you still have it.