Definition: A Bitcoin output script descriptor is a structured text expression that describes one or more Bitcoin output scripts and can specify the keys, derivation paths, and spending conditions a compatible wallet uses to identify or generate its addresses. It gives software an explicit description of a wallet’s output policy; it does not itself hold or transfer bitcoin.1
| BIP assigned | BIP 380 was assigned June 27, 2021, and is marked Deployed.1 |
|---|---|
| General specification | BIP 380 |
| Implementation reference | Bitcoin Core documentation2 |
| Directories | Bitcoin Technology & Infrastructure |
In-Depth Explanation
Why wallets use descriptors
A Bitcoin wallet has to do more than hold a key. It also needs to know how that key is used to form output scripts, which derivation paths to follow, and which addresses or outputs to watch. The same underlying key material can be used with different script types. A recovery phrase by itself may therefore be insufficient for some wallet restores if the wallet software cannot infer the original script type or derivation path. BIP 380 was designed to make that information explicit and portable between compatible applications.1
A descriptor is a description, not a Bitcoin transaction or a change to Bitcoin’s consensus rules. It tells compatible software how to recognize or derive a set of output scripts. The wallet still needs the appropriate signing key material to spend, while a descriptor can describe a changing set of addresses rather than naming just one destination.
Reading the expression
Descriptors use script expressions such as pkh(), wpkh(), wsh(), and tr(). These functions describe the kind of output script to construct. A key expression inside them can contain a public key or extended public key, optional key-origin information, and a derivation path. A wildcard such as * can represent a sequence of child keys rather than one fixed address. The supported expressions and nesting rules depend on the specification and the wallet software that reads them.2
| Expression shape | What it describes |
|---|---|
wpkh(KEY) |
A native SegWit pay-to-witness-public-key-hash output for the specified key. |
tr(KEY) |
A Taproot output using a key path without a script tree in the descriptor. |
tr(KEY, TREE) |
A Taproot output whose descriptor also specifies a tree of scripts. |
The Taproot-specific tr() form is defined separately in BIP 386. In simplified terms, the first argument supplies the internal key; an optional second argument describes the script tree committed to by the Taproot output.3
A schematic descriptor might look like wpkh([FINGERPRINT/84h/0h/0h]XPUB/0/*)#CHECKSUM. The bracketed part is key-origin information, the path and wildcard describe derived keys, and the checksum follows a #. This is only an illustration: the placeholders are not importable key data, and a real wallet may use a different path or expression.
Descriptor, address, seed phrase, and Miniscript
| Item | Role |
|---|---|
| Bitcoin address | A user-facing destination that corresponds to a particular output script. A descriptor can describe a rule for deriving a family of scripts and addresses. |
| BIP-39 recovery phrase | Encodes computer-generated entropy as words and converts it into a seed. Wallet software may also need script and derivation information to restore the same addresses.4 |
| Miniscript | A language for composing spending conditions. Supported descriptors can include Miniscript within certain script expressions; it is not the general descriptor format itself.2 |
| PSBT | A format for carrying an unsigned or partially signed transaction and signing data between wallets or signers. It complements descriptors but serves a different job.5 |
Checksums, compatibility, and safety
A descriptor may end in # followed by an eight-character checksum. The checksum helps compatible software detect many transcription errors; Bitcoin Core includes checksums in descriptor output, and some of its RPCs require them on input. A checksum is not a signature, does not prove who controls the keys, and does not make a malformed or unsupported descriptor usable. Check wallet-specific support before relying on an export or recovery procedure.12
Descriptors can contain public key information or, in some formats, private key material. Never publish or send a descriptor containing an extended private key such as an xprv or another private key. A public-only descriptor cannot by itself sign a transaction, but it can disclose which addresses belong to a wallet. Treat exports according to the key material they contain, and use the wallet maker’s own backup instructions.1
History
- October 2018: Bitcoin Core 0.17.0 release notes documented a
scantxoutsetRPC that accepted output descriptors, showing an early use in Core software.6 - June 27, 2021: BIP 380, “Output Script Descriptors General Operation,” was assigned and is marked Deployed. It specifies general descriptor syntax and checksums.1
- Taproot descriptor support: BIP 386 specifies the
tr()expression for describing Taproot outputs, including an optional script tree.3
Last updated: November 12, 2026.
Related Terms
Related Articles
CryptoGloss does not currently have an article focused specifically on output descriptors. These broader articles provide nearby Bitcoin and wallet context.
- Why Calling It a ‘Wallet’ May Have Been Crypto’s Biggest Mistake
- What Happens to Bitcoin When All 21 Million Are Mined?
- How the 2024 Bitcoin ETF Changed Crypto: Institutional Adoption, Inflows, and the Market Shift
- Bitcoin as Collateral Is Now a Real Thing. Here’s What That Actually Changes.
See Also
Sources
- Pieter Wuille and Ava Chow, “BIP 380: Output Script Descriptors General Operation,” Bitcoin Improvement Proposals, assigned June 27, 2021, status Deployed, https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki (accessed November 12, 2026).
- Bitcoin Core contributors, “Support for Output Descriptors in Bitcoin Core,” Bitcoin Core documentation, https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md (accessed November 12, 2026).
- Pieter Wuille and Ava Chow, “BIP 386: tr() Output Script Descriptors,” Bitcoin Improvement Proposals, assigned June 27, 2021, status Deployed, https://github.com/bitcoin/bips/blob/master/bip-0386.mediawiki (accessed November 12, 2026).
- Marek Palatinus, Pavol Rusnak, Aaron Voisine, and Sean Bowe, “BIP 39: Mnemonic Code for Generating Deterministic Keys,” Bitcoin Improvement Proposals, assigned September 10, 2013, status Deployed, https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki (accessed November 12, 2026).
- Ava Chow, “BIP 174: Partially Signed Bitcoin Transaction Format,” Bitcoin Improvement Proposals, assigned July 12, 2017, status Deployed, https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki (accessed November 12, 2026).
- Bitcoin Core contributors, “Bitcoin Core 0.17.0 Release Notes,” Bitcoin Core documentation, https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.17.0.md (accessed November 12, 2026).