Disaster recovery process
Back up your signers, and recover a vault's private keys if you lose access to enough of them
Disaster recovery rebuilds a vault's private keys from your signers' backups, outside io.finnet. Use it if your organisation can no longer sign for a vault, for example because it has lost access to enough signers to meet the threshold.
You don't need disaster recovery to replace a single lost device. Restore the signer's backup on a new device, or replace the signer with a reshare.
Test your recovery before a vault holds real assets. Run a full drill on a test vault: back up the signers, then recover the vault's keys on an air-gapped computer. A missing key or an out-of-date backup can lock you out of your assets permanently.
For the full checklist, see Before you go live.
When to use it
Use disaster recovery when you can't sign a transaction to move a vault's assets, for example because of:
- A critical software failure.
- An attack that takes the service offline.
- The service shutting down.
- The loss of too many signers' key shares.
- A compromised signer that means you must recreate the vault.
Some of these are outside io.finnet's control, so the disaster recovery tool is open source and runs entirely offline. Keep your own copy.
How it works
The disaster recovery tool combines the key shares from enough signers' backups to meet the vault's threshold, and rebuilds the vault's private keys. Each backup is encrypted, and needs its own key to read it:
| Signer | Backup | Key |
|---|---|---|
| Mobile Signer | A backup file exported from the app. | The 24-word secret phrase the app showed when you exported it. |
| Virtual Signer | A recovery bundle, or the .dr files it contains. | Your organisation's ML-KEM-768 private key. |
The person who runs the recovery sees the vault's private keys. They get full control of the vault's assets, and of any smart contract permissions held by its addresses. Choose them with care.
Back up a Mobile Signer
- In the app, open Settings and tap Export backups.
- Tap Generate secret phrase. The app shows a new 24-word secret phrase for this backup.
- Record the phrase and store it offline, away from the device. Tick I have stored this secret phrase safely.
- Tap Export backup file, and choose where to save it. Save it off the device, somewhere your organisation permits.
The backup file is a ZIP containing one encrypted file for each of your signers. Each export has its own secret phrase, so keep each phrase with a record of which backup file it opens.
Export a new backup after the signer joins a vault, and after every reshare. A backup taken before the latest reshare may not recover the vault.
To restore a backup on a new device, install the app, choose Restore from backup, import the backup file, and enter its secret phrase. See Mobile Signer.
Back up a Virtual Signer
A Virtual Signer has no secret phrase. Before it first starts, your organisation generates an ML-KEM-768 key pair and gives the signer the public key. The signer then writes encrypted .dr files each time it takes part in a key generation or reshare.
Collect them into a recovery bundle on the signer's host:
docker compose exec vs-broker signerctl share backupMove the bundle off the host, and keep the private key offline, separately from the bundle. Export a new bundle after the signer joins a vault, after every reshare, and on a regular schedule.
A bundle recovers a vault. It doesn't restore a running Virtual Signer: back up its storage volume for that. See Virtual Signer disaster recovery for the full procedure, including generating and checking the key pair.
Recover a vault
- Gather the backups and keys. Collect up-to-date backups from enough signers to meet the vault's threshold, and their keys: each Mobile Signer backup's secret phrase, and the private key for each Virtual Signer.
- Prepare an air-gapped computer. Use a computer with no network connection, and copy the recovery tool, backups, and keys to it.
- Run the recovery tool. It combines the shares and rebuilds the vault's private keys. See Run the recovery tool.
- Import the keys into a wallet, and move the assets. See Import the recovered keys.
Get the recovery tool
Download a binary from the releases page, or build it from source with Go by following the repository's README. Building it yourself gives you the most assurance.
Binaries are available for Linux and FreeBSD (x86-64 and ARM64), Windows (x86-64), and macOS (Apple Silicon). Each is a .tar.gz archive:
tar -xzf recovery-tool-*.tar.gzOn macOS, clear the download quarantine before you run it:
xattr -dr com.apple.quarantine recovery-tool*Use version 6.5.0 or later to recover Virtual Signer bundles.
Run the recovery tool
These examples use the macOS binary. Replace recovery-tool-mac with the binary for your platform.
Pass the backup files. The tool asks for each Mobile Signer backup's secret phrase:
./recovery-tool-mac mobile-backup-1.zip mobile-backup-2.zipFor Virtual Signers, add -keys with the path to each private key. You can repeat -keys, or separate several paths with commas. Mobile Signer backups, Virtual Signer bundles, and loose .dr files can all go in the same run:
./recovery-tool-mac -keys signer1_priv.pem,signer2_priv.pem signer1-backup.zip signer2-backup.zip mobile-backup.zip| Option | Use |
|---|---|
-keys | ML-KEM-768 private keys for Virtual Signer backups. -private-key also works for a single key. |
-vault-id | The vault to recover, so the tool doesn't ask you to choose. |
-threshold, -nonce | Override the threshold and reshare nonce the tool detects. Older backups may need -threshold. |
-password | Export an Ethereum wallet file protected by this password. |
-web | Open the browser interface at http://localhost:8080. It runs locally and needs no network connection. |
The browser interface reads loose .dr files, but not Virtual Signer bundles. Use the command line for bundles.
A vault export from an older app release can't be combined with Virtual Signer backups. Recover it in a separate run, with only its secret phrase.
Import the recovered keys
Ethereum and EVM networks
Run the tool with -password to export a wallet.json file, and keep it safe. In MetaMask, add an account and import the file.
Bitcoin
The tool exports two WIF private keys for the Electrum wallet: one for mainnet (bc1 addresses) and one for testnet (tb1 addresses). Use the one for your vault's network. Anyone with the WIF can spend the funds.
To recover a testnet key, start Electrum with the --testnet flag. On macOS:
open -n /Applications/Electrum.app --args --testnetIn Electrum, create a new wallet and choose to import private keys:


Add p2wpkh: before the WIF, and paste it in:

Set a password for the wallet:

When Electrum has synced, it shows the vault's balances.
Tron
Import the private key into TronLink. See TronLink's import guide.
Other networks
For XRP Ledger, Solana, Bittensor, and other networks, the browser interface generates the commands to check balances and build transactions. See the tool's README for the scripts it uses.
Updated 17 days ago