Bitcoin Core walletpassphrasechange RPC: Passphrase Rotation Guide

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

Rotation authority

Require dual control for the exact wallet, host and maintenance window. A passphrase rotation is a custody ceremony, not routine help-desk work. Pause spending and key-export operations and record wallet identity, software version and tested recovery baseline before beginning.

Two-secret boundary

Protect both old and new passphrases from shell history, logs, monitoring, clipboard managers and process capture. Use a trusted local entry path and separate custodians where policy requires. Never send either secret through a ticket or chat transcript.

New secret quality

Generate a strong unique replacement with enough entropy and store it in the approved recovery system. Do not derive it predictably from the previous passphrase or reuse it across wallets. Verify entry through a controlled two-person procedure before committing the change.

Failure semantics

Wrong old passphrase, malformed input, timeout or connection loss must be treated distinctly. Do not assume the new secret is active after an ambiguous response. Limit guesses, preserve logs and test state carefully through a safe unlock-and-lock sequence without initiating a spend.

How specialists test it

Operators test the command on a non-production node first. They check a normal reply, an invalid request, a timeout and a restart. This shows what the response means and prevents one local result from being mistaken for a network-wide outcome.

Backups and recovery

Create a fresh protected wallet backup through the approved destination and test recovery on an isolated host. Inventory older encrypted backups because they may still require the previous passphrase. Retain or destroy the old credential according to documented backup-retention policy.

Ceremony drill

Practise successful rotation, wrong old secret, mismatched new entries, RPC timeout, backup failure and disaster restoration on a disposable wallet. Prove that the team can identify active credentials and recover funds without exposing either passphrase in evidence. Build a revision-pinned evidence pack on an isolated node, wallet or protocol harness.

Conclusion

walletpassphrasechange is a two-secret custody ceremony. Complete it only with protected entry, explicit state verification and a newly tested recovery path that accounts for older backups.