Your seed phrase might not be enough

What BIP 138 does

The key that opens a backup is derived from the cosigners’ public keys, specifically their extended public keys (xpubs), which are already written inside the descriptor. To open a backup, a cosigner only has to provide their public key.

Why

• Signing devices guard private keys tightly. Their secure chips are built to sign transactions, not to run custom decryption code, and they may never let the private key out. But every Bitcoin signing device can export a public key. The specification lists this as a required property: decryption must not need private key material.
• No new secret to lose. A password would be one more thing to remember, store and pass on to heirs. Your devices already hold everything needed.
• Nothing to hide from cosigners. The only people who hold these public keys are the people already in the wallet. They know the descriptor anyway, so the backup only needs to stay closed to everyone else.
• It works with any device. Being vendor-neutral was an explicit goal.

What was considered instead

• Classic public-key encryption, where opening requires the private key. Rejected because it needs signing devices to run custom decryption.
• Encrypting the whole backup separately for each cosigner. Rejected because the file would grow by a full copy per cosigner. Instead, the backup is locked once and only a small “envelope” is added per cosigner.

The trade-off

Since public material opens the backup, a backup must never contain private keys or seeds. The specification requires them to be stripped out before encrypting. This is a backup for the descriptor, never for the keys.

Where this was decided

• BIP 138, Expected properties and Scope
• Original proposal, ideas 1 and 2
• Review: private keys must be removed before storing

What BIP 138 does

Each cosigner gets their own envelope, so any one of them can open the backup on their own.

Why

• Recovery should be easy when things go wrong. If opening the backup required several people, losing the descriptor would turn into a coordination problem: finding cosigners, scheduling, and doing extra rounds of steps, often under stress.
• Thresholds don’t fit every wallet. Advanced wallets can have timelocks and recovery paths. For example, a recovery partner who can only spend after a year still needs to read the descriptor to do so. A rule like “any 2 of 3 can open it” doesn’t fit cleanly onto such setups.
• Simple formats get adopted. Optional advanced features make interfaces harder and hurt compatibility between wallets. A format nobody implements protects nobody.
• Opening isn’t spending. A cosigner who opens the backup learns the descriptor, not the power to spend.

What was considered instead

Threshold decryption, where several cosigners must combine their keys to open the backup, possibly mirroring the wallet’s own spending rules. It was explored in the discussion and in separate tools, and it does give stronger privacy if one key is compromised. It was kept out of the default to keep the scheme simple. The specification lists threshold-based decryption as a possible future extension.

The trade-off

Any single cosigner, including an heir or a recovery partner, can read the wallet’s descriptor. If you don’t want someone to have that ability, the practical answer is to not give them a copy of the backup until it’s needed, or to leave their key out (see Can some keys be left out?).

Where this was decided

• Threshold alternative proposed
• Why it wasn’t the default
• Inheritance example and response
• BIP 138, Future extensions

What BIP 138 does

Everything needed to create a backup is already inside the descriptor: the cosigners’ public keys. A wallet can produce a backup straight from it.

Why

• Watch-only wallets can do it. Many people manage their multisig from an app that only holds public information. That app can create backups whenever it wants: right after setup, or every time something changes.
• No hardware dance. Requiring every signing device to be present for each backup would make backups rare, and rare backups are how descriptors get lost.
• Copies can be checked. Any software holding the descriptor can verify that a stored copy is intact and still opens.

What was considered instead

A dedicated backup key on each device, fetched from a fixed location instead of reusing the descriptor’s keys. That would make it obvious which key to try at recovery time. It was set aside because every device would need to be connected whenever a backup is made.

The trade-off

Recovery software has to work out which of a device’s many possible public keys to try. BIP 138 handles this with a list of common locations to try automatically (see Why are derivation paths optional?).

Where this was decided

• Dedicated-key idea and response
• Verifying backups against corruption

What BIP 138 does

• One well-known “unspendable” key, used by some Taproot wallets as a placeholder, is always excluded.
• Wallets may leave out any other key they know to be public, or any key the user doesn’t want to be able to open the backup.
• Wallets that exclude extra keys should document it, and must make the user aware of every excluded key.
• A cosigner whose key was left out simply can’t open the backup. Everyone else still can.

Why

• A key everyone knows would unlock everything. The placeholder key is a published constant used by many wallets. If it got an envelope, anyone could open the backup.
• Not every cosigner needs to read the descriptor. Leaving out a key’s envelope is the simplest form of access control the scheme offers.
• No surprises at recovery time. A cosigner who discovers they can’t open the backup only when they need it would be a nasty surprise. Hence the warning requirement.

What was considered instead

Using only a fixed subset of keys, decided by the format itself. Rejected because which keys should be able to open the backup depends on the wallet and its owner.

The trade-off

Excluding keys is wallet-specific behavior, so users depend on their wallet being clear about it.

Where this was decided

• Placeholder key raised in review and follow-up
• Document exclusions
• BIP 138, Secret generation

What BIP 138 does

Only public keys that never appear directly on the blockchain are used to open a backup. Keys that would be revealed the first time coins are spent are not allowed. If a wallet’s keys are all of that kind, a backup can’t be made at all.

Keys that are combined into a single shared key (a “MuSig” key) are an exception: they can be used, because only the combined key shows up on-chain, never the individual ones.

Why

When you spend bitcoin, the public keys involved become visible to everyone. If one of those exact keys could open the backup, anyone watching the blockchain could read your wallet’s descriptor after your first spend. Using a key from one step higher in the key hierarchy, which is never published by spending, keeps the backup closed.

What was considered instead

Nothing. This was a gap found during review: an earlier draft would have allowed such keys. A BIP editor spotted it, and the rule was added.

The trade-off

A few unusual descriptor styles can’t be backed up with BIP 138 as-is. Wallets must refuse rather than create a backup that leaks.

Where this was decided

• Issue raised in review
• BIP 138, Descriptor key requirements

What BIP 138 does

The specification explicitly supports single-signature wallets, and the same format works regardless of how many keys are involved.

Why

• A single-key wallet can be restored from its seed, but its extras can’t: transaction labels, which accounts were used, when the wallet was created. One format for every wallet is simpler for software and for users.
• A reviewer initially wondered whether single-key wallets were left out. The specification was clarified to say plainly that they are included.

The trade-off

For single-key wallets, the backup protects convenience and privacy rather than access to funds, so it matters much less than for multisig.

Where this was decided

• Review question and answer
• BIP 138, Secret generation

What BIP 138 does

The specification warns that some single-key wallet apps, including the desktop apps of some popular hardware wallet makers, send the account’s extended public key (xpub) to their servers to look up balances. If that same xpub is later reused as a key in a multisig, that server could open any copy of the multisig’s backup it obtains. The specification recommends building a multisig from accounts whose xpub was never sent to such a server, such as the accounts dedicated to multisig (the BIP 48 or BIP 87 layouts).

Why

The whole scheme rests on one assumption: only the wallet’s cosigners know its public keys. Sharing an xpub with a service quietly breaks that assumption for that key.

What was considered instead

Nothing that the format alone could fix. Whether an xpub was ever shared depends on how it was used, so the specification states the risk clearly.

The trade-off

Even in this case, the server learns the descriptor, and with it your addresses and how the wallet is built,, not the ability to spend. Good key hygiene avoids the issue entirely.

Where this was decided

• BIP 138, Secret generation (warning)

What BIP 138 does

A signing device can produce many public keys, each from a different “path”. To open a backup, recovery software has to ask the device for the right one.

• A backup may include hints about which paths were used, but doesn’t have to.
• Software that talks to signing devices should automatically try the common paths, for the first ten accounts of each standard layout.
• Some devices refuse, or ask for on-screen confirmation, for certain paths. Software should treat those as allowed to fail and warn the user if nothing opens.
• The backup never contains device fingerprints, the short identifiers that name each cosigner’s device.

Why

• Standard paths are easy to guess anyway, so writing them down adds little for recovery and gives away information about how the wallet is built.
• Fingerprints would point at the participants. Leaving them out keeps the backup from saying who is involved.
• Hints remain available for people who used an unusual path and would otherwise struggle to recover.

What was considered instead

• Always storing the paths in plain view. Convenient, but it reveals the number of participants.
• A single fixed path for backups. Simple, but not supported without prompts on every device.

The final list was shaped by checking which paths popular signing devices hand out without asking.

The trade-off

Recovery can take a few more attempts, and on some devices an extra confirmation, in exchange for a backup that reveals less.

Where this was decided

• Plain-text paths: benefit and privacy cost
• Testing which paths devices export without prompts
• BIP 138, Derivation paths

What BIP 138 does

Wallets should add random decoy envelopes that no key can open, rounding the total up to a fixed step: 5, 10, 20, and so on. Envelopes are also put in a standard order with duplicates removed. Recovery software doesn’t need to tell real from fake; it simply tries each one.

Why

• The count is a clue. Without decoys, anyone holding a copy could count the envelopes and learn, for example, “this is a 3-key wallet”. That’s useful to an attacker sizing up a target.
• Order is a clue too. If different wallets ordered envelopes differently, a backup could reveal which software made it. A standard order prevents this.
• Decoys cost almost nothing. They’re small, and opening simply tries more envelopes.

What was considered instead

Leaving the participant count visible. The original drafts did, and it was listed as something to improve. Decoys were the simplest way to blur it without changing how backups are opened.

The trade-off

Slightly larger backups. A determined observer still learns a range (“between 6 and 10 cosigners”), not nothing.

Where this was decided

• Participant count raised in review
• Decoy proposal
• BIP 138, Individual secrets

What BIP 138 does

Wallets may pad a backup up to a fixed set of sizes, starting at 10 KiB with each step about a quarter larger than the last. Padding is recommended for contents that change over time, such as transaction labels or full wallet backups, and unnecessary for contents that don’t, such as a descriptor alone. The padding sits inside the encryption, so even software reading the file only sees the padded size.

Why

• Growth is a signal. Picture a wallet that uploads a fresh backup every time you receive a payment. Even fully encrypted, the file grows a little each time, telling your storage provider when you transact and roughly how much your labels have grown.
• Static backups don’t leak this way. A descriptor alone never changes, so padding it would only make it bigger.
• Inside is better than outside. Padding added outside the encryption could be stripped or measured. Inside, it’s indistinguishable from content.

What was considered instead

Mandatory padding for everything. Rejected because users who only back up a descriptor would end up copying much larger files for no benefit.

The trade-off

Padded backups are larger. The steps keep the overhead under about 25% above the size needed.

Where this was decided

• Padding proposed in review
• Make it optional
• BIP 138, Padding

What BIP 138 does

Backups are encrypted with ChaCha20-Poly1305, a widely used, standard method that both hides the contents and detects any tampering or corruption. It is the only algorithm the specification defines.

Why

• It’s already in Bitcoin Core, where it protects peer-to-peer connections (BIP 324). The alternative would have meant adding a new cryptographic dependency just for backups.
• It runs well on small hardware without special chip support, which suits signing devices and embedded systems.
• One algorithm means one thing to implement. Writers can choose freely, but readers have to support every allowed option. With two, every reader would need both.

What was considered instead

AES-GCM, the original choice. It was replaced after an implementer noticed Bitcoin Core doesn’t ship it. Keeping both was considered and dropped, for the reason above.

The trade-off

None for users. The format keeps a marker for which algorithm was used, so a future version can add another if ever needed.

Where this was decided

• Question raised while implementing and response
• Supporting two algorithms burdens readers
• Discussion on Delving
• BIP 138, Encryption

What BIP 138 does

Every backup uses a new random value (a “nonce”) during encryption. An all-zero value, which would signal a broken random number generator, is forbidden.

Why

Encryption of this kind is only safe if that value is never reused with different contents. Wallets back up repeatedly, for instance as labels change, so randomness is the standard, well-understood way to guarantee that. Deriving it from the contents instead is possible in theory, but means stepping away from standard practice to save about 32 bytes on a file that’s typically hundreds of bytes or more.

What was considered instead

Fully deterministic backups, where the same input always produces the same file. This was a nice-to-have in the original proposal.

The trade-off

Two backups of the same wallet don’t look identical, so you can’t compare copies byte for byte. You check a copy by opening it instead, which any wallet holding the descriptor can do.

Where this was decided

• Original wish for determinism
• Why reviewers chose randomness
• BIP 138, Encryption

What BIP 138 does

A backup can contain several items, for example a wallet policy plus transaction labels. Each item is labeled with what it is:

• the number of the BIP that defines it (descriptor, wallet policy, labels, full wallet backup…);
• a vendor-specific tag, for a wallet’s own extras;
• or a plain-text note.

When software meets an item it doesn’t understand, it skips it and keeps reading. The format also reserves a way to mark future items that older software must refuse rather than misread.

Why

• Keep each piece simple. Rather than one giant all-in-one file format, each item stays in its own existing standard and the backup simply carries them together.
• This couldn’t be added later. Allowing several items after the fact would have broken compatibility with existing backups, so it was built in from the start.
• Unknown extras must never block recovery. Picture a note placed before the descriptor: a wallet that only understands descriptors must still find the descriptor. That’s why every item states its size, so it can be skipped cleanly.
• No central registry. Labeling items by BIP number means nobody has to maintain a list of approved types.
• Old software should fail safely. For truly new kinds of content, refusing is better than guessing.

What was considered instead

• One item per backup, keeping a clean line between unlocking and reading the contents. Changed after review, because support for several items couldn’t be added later without breaking compatibility.
• A fixed list of content types. Replaced by BIP numbers, which need no upkeep.

The trade-off

Wallets may pick different combinations of items. Interoperability relies on the core item, the descriptor or wallet policy, being understood everywhere.

Where this was decided

• Labels by BIP number, no registry
• Case for several items
• BIP 138, Content type

What BIP 138 does

When a backup holds a descriptor or wallet policy, it can also say, for each account:

• when it was created (a “birth time”), so software knows how far back to search the blockchain;
• which range of addresses has been used;
• whether it is archived, meaning it should be restored to see past coins but not used for new addresses.

All of these are optional. Several accounts can be stored in one backup.

Why

• Searching the whole blockchain is slow. Knowing a wallet didn’t exist before a certain date lets software skip years of history.
• Old setups shouldn’t come back to life by accident. If you replaced a multisig, the old one is still worth restoring to see its history, but you don’t want new payments going to it.
• These hints already exist in wallets. Writing them down in a standard way means they survive a move from one wallet to another.

What was considered instead

Leaving the descriptor format to another standard. Reviewers argued that descriptors are the main use case and no other BIP defined how to store them, so BIP 138 specifies it.

The trade-off

None for the user. Software that doesn’t use the hints just scans more slowly.

Where this was decided

• Proposal to specify descriptor storage
• BIP 138, Descriptor and wallet policy backup content

What BIP 138 does

• As text, a backup is written in Base64, a common way to turn data into plain characters you can paste into an email or note.
• As a file, the binary form uses the extension .bip138 and the text form uses .txt.

Why

• Wallets already speak Base64. Partially signed transactions (PSBTs, BIP 174) are usually exchanged this way, so the code is already there.
• Text travels everywhere. You can email it to yourself, paste it into a password manager, or print it.
• The extension says what’s inside, so software doesn’t have to guess.

What was considered instead

A Bech32m text form, similar to Bitcoin addresses, which is friendlier to print and type. It’s listed as a possible future extension.

The trade-off

Base64 is less forgiving to retype by hand than Bech32m.

Where this was decided

• Base64 suggestion in review
• BIP 138, Text representation

What BIP 138 does

Each backup starts with a “BIP138” marker and a version number, and records which encryption algorithm it used. The specification lists possible future extensions:

• additional encryption algorithms;
• threshold-based opening, where several cosigners must cooperate;
• better hiding of the number of participants;
• a Bech32m text form.

Why

Backups are meant to sit untouched for years. Whatever changes later, software must be able to tell what it’s looking at and still open older backups.

Compatibility with earlier versions

The Liana wallet shipped an early version of this scheme before it became BIP 138. Those backups are not compatible with BIP 138 and can be told apart by their different marker (“BEB” instead of “BIP138”).

The trade-off

None for the user. Keeping room to grow costs a few bytes per backup.

Where this was decided

• BIP 138, Future extensions
• BIP 138, Backward compatibility