Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Backup & recovery

Three things to back up. They have different recovery characteristics — treat them differently.

What to back up

FileLose it = lose what?Recoverable from?
wallet.key (encrypted)Your funds. Without the file and the passphrase, the coins are unspendable.Nothing. There is no seed phrase recovery.
node_identity.keyYour node's P2P identity. Losing it doesn't lose funds, but other peers will see you as a new node. Leaking it lets others impersonate you.Auto-regenerated on next start, with a new identity.
chain/ + state/ (the data directory)Sync time only. You can rebuild from peers.Re-syncing from peers.

Wallet backup (most important)

Make at least two copies, store in physically different places, and write down the passphrase separately:

cp ~/.exfer/wallet.key ~/Documents/exfer-wallet-2026-05-16.key
# also: USB stick, encrypted cloud bucket, locked drawer, etc.

Because the file is encrypted, it is safe to put on cloud storage. But losing the passphrase is the same as losing the file — both are required.

Recommendation:

  • Two physical copies (e.g. two USB sticks, in two locations).
  • One encrypted cloud copy.
  • Passphrase: stored in a password manager whose master password is itself durably backed up.

Recover a wallet

exfer wallet info --wallet /path/to/backup.key
# enter passphrase when prompted

If the file decrypts, the wallet is intact. The address and balance follow from the keypair plus chain state.

Node identity backup (sensitive)

~/.exfer/node_identity.key is the Ed25519 identity your node uses on the P2P network. Treat it like an SSH host key:

  • Back it up only if you specifically want to preserve your node's identity across reinstalls (rarely necessary).
  • Never share it. Anyone holding it can impersonate your node, which can let them join peer-trust slots reserved for your node.

Permissions are enforced at 0600. If your filesystem strips perms (WSL on a Windows drive, some NAS mounts), pass --repair-perms instead of backing up the file manually.

Data directory backup (optional)

The chain/ and state/ directories can be regenerated by re-syncing from peers, so backing them up is purely a sync-time optimization. If you do back them up:

  • Take the snapshot only while the node is stopped — copying a live database can produce a corrupt snapshot.
  • Use a tool that copies atomically (rsync --delete after stop, or LVM snapshot).
  • Verify the restored node syncs cleanly to the current tip before trusting it.
sudo systemctl stop exfer
sudo rsync -a --delete /var/lib/exfer/chain /backup/exfer-chain-$(date +%F)/
sudo rsync -a --delete /var/lib/exfer/state /backup/exfer-state-$(date +%F)/
sudo systemctl start exfer

Restoring from a stale snapshot is fine — the node will catch up the missing tip blocks from peers on next start.

Upgrading the binary

sudo systemctl stop exfer
# replace /usr/local/bin/exfer with the new release binary
sudo systemctl start exfer
journalctl -fu exfer

The on-disk database format is not guaranteed to be backward- compatible across major versions. Before a major upgrade:

  1. Read the upstream CHANGELOG for migration notes.
  2. Snapshot chain/ and state/.
  3. Have a plan to roll back the binary if startup fails.

Minor (v1.x.y → v1.x.z) upgrades are typically a drop-in replacement.

Disaster recovery

Worst case (host destroyed, no chain snapshot, no node identity):

  1. Reinstall the binary on a new host.
  2. Restore wallet.key from your offline backup.
  3. Run exfer node (or exfer mine) — a fresh node_identity.key is generated, the chain re-syncs from peers.
  4. Use exfer wallet balance --rpc <node> to confirm funds visible.

Time to recover: download + IBD (see Sync the chain).