BIP393: Bringing Metadata to Bitcoin Wallet Descriptors | Bitcoin Index

Bitcoin wallet backups have gotten better over the years, but they’re still not perfect. You’ve probably heard of BIP39 seed phrases (the 12 or 24 words that back up your wallet). Those are great for backing up keys, but they don’t tell you everything you need to know to recover your funds.

That’s where output script descriptors come in. And now, with BIP393, descriptors are about to get smarter.

The problem with seed phrases

Here’s the issue: when you restore a wallet from a BIP39 seed phrase, you get the private keys back. But you don’t automatically know:

What kind of addresses to generate. Should the wallet create legacy addresses? Native SegWit? Taproot? Each type requires a different derivation path and produces different addresses.
Where to look for funds. Do you scan the entire blockchain from 2009? That’s slow. Do you guess when the wallet was created? You might miss early transactions.
How many addresses to check. Wallets generate addresses in sequence. If you only used addresses 1, 50, and 99, but the wallet stops scanning after 20 unused addresses, it’ll miss the funds at 50 and 99.

These aren’t theoretical problems. Users lose money this way.

Descriptors: the upgrade

Output script descriptors solve the first problem. They’re a standardized language that describes exactly how to generate addresses. Instead of just backing up keys, you back up a string that includes:

The key itself (as an extended public key)
The derivation path
The script type (P2WPKH, P2TR, etc.)
A checksum for error detection

A descriptor looks like this:

wpkh([deadbeef/84h/0h/0h]xpub.../0/*)#checksum

This tells the wallet: “Generate native SegWit addresses using this xpub, following this derivation path.” No guesswork.

Descriptors were introduced in BIP380 by Pieter Wuille and Ava Chow, and they’ve been in Bitcoin Core since version 0.17. They’re a huge step forward for wallet interoperability.

What descriptors still can’t tell you

Descriptors specify what to derive, but not the operational details you need for efficient recovery:

1. When to start scanning

If your wallet was created in 2024, there’s no point scanning blocks from 2009. But without a “birthday” block height, the wallet has to either scan everything (slow) or guess conservatively (might miss early funds).

This problem is especially painful for silent payments (BIP352), which require scanning every transaction to detect incoming payments. Without a starting point, recovery becomes impractically slow.

2. How far to scan

The “gap limit” is the number of consecutive unused addresses a wallet will generate before deciding there are no more funds. The default is usually 20.

If you generated 100 addresses but only used three of them (at positions 1, 50, and 99), a wallet with a gap limit of 20 will stop at address 21 and never find the funds at 50 and 99.

This happens more often than you’d think, especially with payment processors that pre-generate large batches of addresses.

3. Max label index (for silent payments)

Silent payments use “labels” to organize incoming payments into buckets. Without knowing the highest label index, a recovering wallet has to guess how many labels to scan for.

Enter BIP393: annotations

Craig Raw (the developer behind Sparrow Wallet and author of BIP329 for wallet label exports) proposed BIP393 to fill these gaps.

The idea is simple: add metadata to descriptors using URL-style query parameters.

Here’s what an annotated descriptor looks like:

wpkh([deadbeef/84h/0h/0h]xpub.../0/*)?bh=800000&gl=30#checksum

The ?bh=800000&gl=30 part adds two pieces of metadata:

bh=800000: Birthday block height. Don’t scan blocks before #800,000.
gl=30: Gap limit. Check up to 30 consecutive unused addresses before stopping.

For silent payment descriptors, there’s also:

ml=10: Max label. The highest label index to scan for.

Why this design works

It’s backward-compatible. The characters ?, &, and = are already part of the descriptor character set defined in BIP380. Wallets that don’t support annotations can ignore them. Wallets that do support them get the extra context.

It’s covered by the checksum. The checksum at the end of the descriptor covers the entire string, including annotations. If you make a typo in the birthday height, the checksum will catch it.

It doesn’t change the scripts. Annotations are purely informational. A descriptor with and without annotations generates the exact same addresses. This preserves the core property of descriptors: deterministic script generation.

What this means for users

If you’re restoring a wallet and the descriptor includes annotations, the wallet software can:

Skip scanning old blocks (faster recovery)
Know exactly how far to search for addresses (no missed funds)
Handle edge cases like large gap limits or silent payment labels

If you’re exporting a wallet backup, you can include annotations to make sure the next wallet has all the context it needs.

What this means for wallet developers

Supporting BIP393 means accepting and honoring bh, gl, and ml parameters when importing descriptors. It also means offering to export annotated descriptors, either by tracking these values automatically or prompting users for them.

Wallets like Sparrow, Bitcoin Core, Electrum, and others can exchange descriptors with confidence that critical recovery parameters won’t be lost in translation.

Current status

BIP393 was posted to the Bitcoin-Dev mailing list on February 27, 2026. It emerged from discussions around BIP392 (silent payment descriptors), where the need for recovery metadata became impossible to ignore.

As of March 2026, it’s a draft proposal. It was covered in Bitcoin Optech Newsletter #394 and discussed on the Bitcoin Optech Podcast with Craig Raw and Fabian Jahr.

The bigger picture

Descriptors were already a major step forward for wallet interoperability. BIP393 makes them complete for recovery purposes.

Before annotations, a descriptor backup might be technically valid but practically insufficient. After annotations, a descriptor can be a self-contained recovery package.

This is especially important for silent payments, where scanning is expensive and metadata is essential. But it’s useful for any wallet that wants to make recovery faster, safer, and more reliable.

Bitcoin wallet backups have come a long way from “write down these 12 words and hope for the best.” BIP393 is another step toward backups that actually work, every time, across any wallet.

Sources

Data as of March 18, 2026.