Bitcoin Core backupwallet RPC: Verifiable Backup Guide

This guide explains Bitcoin Core backupwallet RPC in plain English. It shows what the command does, what its result means and what it cannot prove.

Destination semantics

The single destination argument can identify a directory or a path including the filename. Interpret it on the node host, not the operator’s workstation. Resolve the final absolute path, reject symbolic-link surprises and confirm the backup is outside the active wallet path. Core 0.15.1 had already added protection against backing up onto the source, but wrappers should still fail closed.

Correct wallet scope

In multiwallet mode, route the call to the exact wallet endpoint and record its wallet identifier. A successful copy of wallet A is irrelevant when the recovery plan required wallet B. Enumerate all loaded and offline wallet files under the effective walletdir and reconcile them against the backup catalogue without exposing balances or private metadata.

Permissions and encryption

A wallet file may contain private keys, scripts, labels and transaction history. Create the destination with restrictive ownership, encrypt removable or remote storage and keep encryption keys in a separate recovery system. Do not place backups in web roots, shared synchronisation folders or build artefacts merely because the RPC can write there.

Freshness and keypool

A backup is a point-in-time copy. Historical non-HD wallets and some imported or experimental scripts can require a newer copy after addresses or keys are added; addmultisigaddress explicitly required one. Record creation height, time, wallet version and relevant keypool state, then rotate backups under a retention policy that prevents one corruption event replacing every good generation.

Integrity and transfer

Hash the completed copy with an approved digest, record size and store the manifest separately. If the file is transferred, verify the digest at the destination and monitor for truncated or zero-length artefacts. A checksum detects accidental change, not malicious replacement unless the manifest itself is authenticated.

Restore drill

On an isolated node with no production RPC credentials, restore the backup using the documented version boundary, rescan from a conservative height and compare known receive and change scripts plus transaction history. Prove a controlled signature without broadcasting. Never overwrite the live wallet as a test and never expose seed or private-key material in evidence.

Automation and rollback

Backup jobs should fail visibly on path, permission, disk, lock or RPC errors and should verify the new artefact before expiring an older generation. If a new wallet version is unreadable by older software, keep the compatible binary and migration notes with the recovery package. Rollback means restoring service from a verified generation, not blindly copying the latest file.

Conclusion

backupwallet creates an important wallet copy, but only a verified recovery process makes it a backup. Scope the correct wallet, protect and authenticate the artefact, retain history and prove restoration without touching production.