Output Descriptors: The Standard That Makes Bitcoin Wallets Portable

A 12-word seed phrase is not a complete wallet backup. It captures the secret key material, but it says nothing about how that key material is used: which script type generates addresses, which derivation path the wallet follows, or whether the wallet is a single-signature setup or a multisig quorum. Output descriptors solve this gap. They are a compact string format, standardized across BIPs 380 through 386, that fully describes how to derive and watch for a wallet's outputs. With a descriptor, any compatible software can reconstruct the exact same set of addresses and spending conditions, making wallet portability a reality rather than a gamble.

Why Seed Phrases Are Not Enough

The BIP-39 mnemonic standard gives users a human-readable backup of their private key entropy. Combined with BIP-32 hierarchical deterministic derivation, wallet software can regenerate an entire tree of keys from those 12 or 24 words. But the seed alone does not specify which branches of that tree the wallet actually uses.

Consider a user who created a wallet in 2019 using BIP-84 native SegWit addresses at derivation path m/84'/0'/0'. They write down their seed phrase and, years later, attempt to restore it in a different wallet that defaults to BIP-86 Taproot addresses at m/86'/0'/0'. The restored wallet shows a zero balance. The keys are mathematically correct, but the software is looking at the wrong branch of the key tree and generating the wrong address type.

What a seed phrase captures vs. what it misses: A BIP-39 seed encodes 128 or 256 bits of entropy. Everything else about wallet configuration is implicit: the script type, the derivation path, the gap limit, any multisig parameters, and any timelocked recovery conditions. If any of these assumptions differ between the original wallet and the recovery wallet, funds appear to vanish.

The Multisig Problem

The portability gap becomes critical with multisig wallets. A 2-of-3 multisig requires three extended public keys, a threshold, and a specific script structure. Having one seed phrase out of three is useless without knowing the other two xpubs, the ordering of keys in the redeem script, and the exact derivation paths each cosigner uses. No amount of seed phrase backups can reconstruct this configuration on their own.

What Output Descriptors Are

An output descriptor is a string expression that completely specifies how to compute a set of output scripts (and therefore addresses) from key material. The format was introduced by Pieter Wuille and Ava Chow and first implemented in Bitcoin Core v0.17.0 in October 2018 alongside the scantxoutset RPC command. The standard is now formally specified across seven BIPs.

All seven BIPs carry the "Deployed" status as Informational documents. BIPs 380 through 385 were implemented in Bitcoin Core v0.17.0, while BIP 386 (Taproot descriptors) arrived in Bitcoin Core v22.0 following the Taproot activation in November 2021.

Descriptor Syntax Explained

Every descriptor follows the same pattern: a function name wrapping a key expression or nested script expression, followed by an 8-character checksum separated by #. The key expression includes an optional key origin (the master fingerprint and derivation path) plus the key itself.

Key Expressions

A key expression encodes everything needed to derive a public key. The format is: [fingerprint/derivation/path]xpub.../child/path/*. The fingerprint is the first four bytes (8 hex characters) of the master key's Hash160, and the derivation path uses h or ' to denote hardened derivation steps. The trailing /* wildcard tells wallet software to generate a range of addresses by incrementing the final index.

For example, a native SegWit single-sig descriptor looks like this:

wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)#checksum

This single string tells any compatible wallet: use the P2WPKH script type, derive from master fingerprint d34db33f at path m/84'/0'/0', and generate external (receiving) addresses by incrementing the final index.

Common Descriptor Functions

Each function maps to a specific Bitcoin Script template:

• pkh(KEY): Pay-to-Public-Key-Hash (legacy P2PKH, addresses starting with 1)
• wpkh(KEY): Pay-to-Witness-Public-Key-Hash (native SegWit, addresses starting with bc1q)
• sh(wpkh(KEY)): Wrapped SegWit (P2SH-P2WPKH, addresses starting with 3)
• tr(KEY): Pay-to-Taproot key-path spend (P2TR, addresses starting with bc1p)
• multi(k, KEY1, KEY2, ...): k-of-n bare multisig
• sortedmulti(k, KEY1, KEY2, ...): k-of-n multisig with lexicographic key sorting for deterministic script generation
• combo(KEY): shorthand that produces P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH outputs for a single key

Multisig Descriptors in Practice

A 2-of-3 multisig descriptor encodes the threshold, all three cosigner keys with their origins, and the script wrapping:

wsh(sortedmulti(2,[aabbccdd/48h/0h/0h/2h]xpub.../0/*,[11223344/48h/0h/0h/2h]xpub.../0/*,[55667788/48h/0h/0h/2h]xpub.../0/*))#checksum

The sortedmulti function ensures all wallets produce the same redeem script regardless of the order cosigners are listed, which solves a longstanding interoperability problem with multisig setups.

The Descriptor Checksum

Every descriptor ends with a # followed by an 8-character checksum using the bech32 character set: qpzry9x8gf2tvdw0s3jn54khce6mua7l. The checksum employs a BCH error-detecting code with specific polynomial generator constants, providing strong error detection: any single-character error is always caught, up to four errors are detected in descriptors up to 501 characters, and random errors have only a 1-in-2⁴⁰ (roughly 1 in a trillion) chance of passing undetected.

Bitcoin Core's getdescriptorinfo RPC computes and appends the checksum for any descriptor string. This makes it easy for developers to generate valid checksums without implementing the algorithm themselves.

Descriptors and PSBTs: A Complete Portable Workflow

Output descriptors define what a wallet owns. PSBTs (Partially Signed Bitcoin Transactions, specified in BIP-174) define how a wallet spends. Together, they form a complete portable workflow for constructing, signing, and broadcasting transactions across different software and hardware devices.

The Air-Gapped Signing Workflow

A typical hardware wallet workflow using descriptors and PSBTs follows these steps:

1. The hardware signing device (like a Coldcard) exports its descriptor containing the xpub and key origin information
2. The watch-only wallet software imports this descriptor to monitor addresses and construct transactions
3. When spending, the software creates a PSBT with the unsigned transaction plus derivation path metadata
4. The PSBT is transferred to the signing device via SD card, QR code, or NFC
5. The signer verifies and adds its signature, returning the signed PSBT
6. The software finalizes and broadcasts the transaction

The descriptor ensures the watch-only wallet can generate all the correct addresses and scripts. The PSBT carries the derivation paths the signer needs to locate the correct private keys. Neither piece alone is sufficient: descriptors without PSBTs cannot spend, and PSBTs without descriptors cannot verify change outputs belong to the user.

Why change verification matters: When a wallet constructs a transaction, it typically sends remaining funds to a change address the user controls. A signing device needs to verify that the change address is actually derived from the user's keys. Descriptors provide this proof: the signer checks that the change output matches the descriptor pattern and refuses to sign if it does not.

Miniscript: Extending Descriptors with Spending Policies

Miniscript, specified in BIP-379, extends the descriptor language with a structured subset of Bitcoin Script that supports analysis, composition, and generic signing. From a user's perspective, Miniscript is not a separate language but an expansion of what descriptors can express.

Miniscript expressions are valid inside wsh() and tr() contexts. Where standard descriptors can express "2-of-3 multisig," Miniscript can express conditions like "2-of-3 multisig, OR after 52560 blocks (roughly one year) a single recovery key can spend." This enables timelocked recovery paths, decaying multisig thresholds, and inheritance planning directly within the descriptor format.

Liana: Miniscript Descriptors in Action

Liana, developed by Wizardsardine, demonstrates the practical power of Miniscript descriptors. A Liana wallet descriptor encodes the primary spending key alongside one or more timelocked recovery keys. After a configurable period of inactivity (specified as a relative timelock using OP_CSV), the recovery keys activate and can move funds. As long as the primary owner makes at least one transaction before the timelock expires, the recovery path resets.

This policy is fully captured in the descriptor string. Backing up the descriptor (along with the relevant seed phrases) is sufficient to reconstruct the entire wallet and its recovery conditions in any Miniscript-compatible software.

Wallet Adoption Across the Ecosystem

Descriptor support has moved from experimental to standard across the Bitcoin wallet ecosystem. The following table summarizes the current state of adoption among major wallets and signing devices.

Bitcoin Core's Descriptor Journey

The evolution of descriptor support in Bitcoin Core illustrates how the standard matured from an experimental feature to the sole wallet format:

• v0.17.0 (October 2018): output descriptors introduced with the scantxoutset RPC for scanning the UTXO set
• v0.21.0 (January 2021): experimental descriptor wallets with SQLite backend, legacy wallets remained the default
• v23.0 (April 2022): descriptor wallets became the default for newly created wallets via createwallet
• v26.0 (December 2023): legacy wallet creation deprecated, requiring an explicit override flag
• v30.0 (October 2025): legacy wallets removed entirely; BDB wallets can no longer be created or loaded

The migratewallet RPC (available since v24.0) automates conversion of legacy wallets to descriptor format, and remains available in v30.0 for users who need to migrate old wallet files.

BIP-388: Wallet Policies for Hardware Devices

While descriptors are powerful, their full generality can be challenging for resource-constrained hardware signing devices. BIP-388, authored by Salvatore Ingala, defines "wallet policies": a simplified representation that separates extended public keys from the descriptor template. This makes descriptors practical for devices with limited RAM and no persistent storage, while preserving full compatibility with the underlying descriptor standard.

A wallet policy replaces inline key expressions with indexed placeholders like @0/** and lists the actual keys separately. This lets hardware wallets display compact policy summaries for user verification without parsing arbitrarily complex descriptor strings. Ledger's Bitcoin app implements BIP-388 natively, including support for MuSig2 expressions.

Practical Guide: Exporting and Importing Descriptors

Exporting from Bitcoin Core

Bitcoin Core's listdescriptors RPC returns all descriptors for a loaded wallet. For a standard single-sig wallet, this typically returns descriptors for external addresses (receiving) and internal addresses (change):

bitcoin-cli listdescriptors

The output includes the descriptor strings with checksums, the derivation range, and the timestamp of each descriptor's creation. Adding true as a parameter exports private descriptors containing xprv keys instead of xpub keys.

Importing into a Different Wallet

To import descriptors into Bitcoin Core, use the importdescriptors RPC, which accepts an array of descriptor objects with optional parameters for the scan range and timestamp. In Sparrow Wallet, you can import a descriptor by clicking the scan icon in the Settings tab and loading the descriptor from a QR code or file. The wallet automatically recognizes the script type, derivation path, and key origin from the descriptor string.

Hardware Wallet Export

Coldcard exports descriptors through its Advanced/Tools menu under Export Wallet. The export includes the full key expression with master fingerprint and derivation path in the BIP-380 format: [fingerprint/path]xpub. Transfers happen via SD card, NFC, or QR code, maintaining an air gap between the signing device and the networked wallet software.

What Descriptors Mean for Wallet Recovery

The combination of seed phrases and descriptors creates a robust backup strategy. The seed phrase protects the private key material. The descriptor protects the configuration: script type, derivation path, multisig parameters, and any Miniscript spending policies. Both are needed for a complete recovery.

For single-signature wallets following standard BIP-44/49/84/86 paths, most modern wallet software can scan all common derivation paths and recover funds from a seed phrase alone. But this relies on the wallet implementing every historical derivation convention and being willing to scan multiple paths. Descriptors eliminate this guesswork entirely.

For multisig and Miniscript wallets, descriptors are not optional: they are essential. Without the descriptor, you cannot reconstruct the redeem script, identify which addresses belong to the wallet, or determine the spending conditions. Wallet developers working on Bitcoin wallet SDKs increasingly treat descriptor export as a mandatory backup feature rather than an advanced option.

Challenges and Limitations

Privacy Considerations

A descriptor containing an xpub reveals the entire address chain for that key. Anyone with the descriptor can derive all past and future addresses, compromising the user's financial privacy. This means descriptor backups need the same security treatment as seed phrase backups: encrypted storage, physical security, and limited distribution. The xpub itself cannot spend funds, but it reveals the complete transaction history.

No Universal Import Standard

While BIPs 380-386 standardize the descriptor language itself, there is no single standard for how wallets exchange descriptors. Different wallets use different file formats, QR encoding schemes, and import mechanisms. Bitcoin Secure Multisig Setup (BSMS) addresses this for multisig workflows, and BIP-388 wallet policies help hardware devices, but a fully unified import and export standard remains a work in progress.

Complexity for Non-Technical Users

Descriptor strings are designed for machine readability. A string like wsh(sortedmulti(2,[aabbccdd/48h/0h/0h/2h]xpub.../0/*)) communicates everything a developer needs but means little to a typical user. Wallet software needs to abstract this complexity into clear backup and restore workflows that handle descriptors behind the scenes.

Descriptors and the Broader Bitcoin Ecosystem

Output descriptors are a Layer 1 standard focused on on-chain wallet portability. They complement the work happening at higher layers of the Bitcoin stack. Protocols like Spark provide instant off-chain transfers with self-custody, while descriptors ensure the on-chain foundation beneath these systems is portable and interoperable.

For developers building wallets that integrate both on-chain and Layer 2 functionality, descriptors provide a clear standard for the on-chain component. The Spark SDK handles the off-chain layer, while output descriptors handle on-chain address generation and UTXO management. Developers working with both layers can explore the wallet SDK comparison for a deeper look at how these standards integrate in practice.

Looking Ahead

The trajectory is clear: descriptors are becoming the universal language for Bitcoin wallet configuration. With Bitcoin Core having removed legacy wallets entirely in v30.0, every new Bitcoin Core wallet is now a descriptor wallet. Miniscript support (BIP-379) continues to expand the expressiveness of descriptors beyond simple key-and-threshold schemes into arbitrary spending policies.

As the ecosystem converges on descriptors, the practical benefit for users grows: true wallet portability, where moving between software is as simple as exporting and importing a string. For multisig and complex custody setups, descriptors transform what was once a fragile, implementation-specific process into a standardized, interoperable one. The 12-word seed phrase remains essential, but it is no longer the whole story.

This article is for educational purposes only. It does not constitute financial or investment advice. Bitcoin and Layer 2 protocols involve technical and financial risk. Always do your own research and understand the tradeoffs before using any protocol.