TECHNICAL_DOC // KEYS / OUTPUT-DESCRIPTORS
OUTPUT
DESCRIPTORS
DESCRIPTORS
An output descriptor is a precise, human-readable string that fully describes
how to derive a set of Bitcoin addresses and scripts. It encodes the script type, key(s),
derivation paths, and range — everything a wallet needs to scan, receive, and spend
— in a single portable expression. Specified in BIP 380–386, they replace ad-hoc wallet
formats as the standard backup and interoperability format.
DESCRIPTOR_SYNTAX
DESCRIPTOR FORMAT
General structure:
FUNCTION(KEY_EXPRESSION)#CHECKSUM
Script functions:
pk(KEY) → P2PK (pay to pubkey)
pkh(KEY) → P2PKH (pay to pubkey hash)
wpkh(KEY) → P2WPKH (native SegWit v0)
sh(wpkh(KEY)) → P2SH-P2WPKH (nested SegWit)
wsh(SCRIPT) → P2WSH (SegWit v0 script hash)
tr(KEY) → P2TR (Taproot, key-path only)
tr(KEY,TREE) → P2TR (Taproot with script tree)
Key expression forms:
xpub... → single xpub (no derivation)
xpub.../0/* → xpub with derivation range
[fp/path]xpub → xpub with fingerprint + path context
REAL EXAMPLES
DESCRIPTOR EXAMPLES — COMMON WALLET TYPES
P2WPKH single-sig (BIP 84):
wpkh([d34db33f/84'/0'/0']xpub6CatW...eZnF/0/*)#checksum
↑ fingerprint ↑ BIP84 path ↑ xpub ↑ receive range
P2TR single-sig (BIP 86):
tr([d34db33f/86'/0'/0']xpub6Cpm7...kzAe/0/*)#checksum
P2WSH 2-of-3 multisig:
wsh(multi(2,
[fp1/48'/0'/0'/2']xpubA.../0/*,
[fp2/48'/0'/0'/2']xpubB.../0/*,
[fp3/48'/0'/0'/2']xpubC.../0/*
))#checksum
Change descriptor (index 1 instead of 0):
wpkh([d34db33f/84'/0'/0']xpub6CatW...eZnF/1/*)#checksum
DESCRIPTOR_TYPES
Taproot Script Tree Descriptor
BIP 386
The tr() function supports a script tree alongside the key-path spend. The tree is expressed as a binary structure of script leaves.
tr(KEY, TREE) syntax:
Single script leaf:
tr(xpub.../0/*, pk(xpub2.../0/*))
Two script leaves (50/50 branch):
tr(internal_key, {pk(key_A), pk(key_B)})
Nested tree (deep branch):
tr(internal_key, {pk(key_A), {pk(key_B), pk(key_C)}})
NUMS key for key-path disabled:
tr(50929b74c1a...NUMS_point, {script_A, script_B})
↑ provably unspendable via key-path → script-only spend
NUMS (Nothing-Up-My-Sleeve) points are used when no key-path spend should exist, forcing all spends through the script tree.
checksum-bip380-8-char-polynomial/">Descriptor Checksum
INTEGRITY
Every descriptor ends with an 8-character checksum after #, computed over the descriptor string. Prevents typos from generating incorrect addresses.
Checksum algorithm:
- Polynomial checksum over descriptor characters
- 8 alphanumeric characters (case-sensitive)
- Appended after # separator
- Validated by all compliant wallets on import
Example:
wpkh(xpub6ERApf...YGbu)#8zl0zxma ← checksum protects
^^^^^^^
Corrupt one char in xpub → checksum fails → wallet rejects
No silent address derivation from corrupted key material
Wallet Backup and Interoperability
USE CASE
Descriptors are the modern wallet backup standard — encoding everything needed to recover a wallet across different software implementations.
Traditional wallet backup problem:
xpub alone → which script type? which derivation path?
Wallet exports xpub → imported elsewhere → wrong addresses
Descriptor-based backup:
wpkh([fp/84'/0'/0']xpub.../0/*) → unambiguous
Import to any descriptor-aware wallet → exact same addresses
Standard wallet descriptor sets (exported as pair):
Receive: wpkh([fp/84'/0'/0']xpub.../0/*)#checksum
Change: wpkh([fp/84'/0'/0']xpub.../1/*)#checksum
Supported: Bitcoin Core (since v0.21), Sparrow, Specter,
Liana, Electrum (partial), Coldcard
TERMINOLOGY_INDEX
Descriptor
A string expression that fully specifies how to derive scripts and addresses from key material.
BIP 380–386
The BIP family specifying output descriptors. 380=base, 381=pk/pkh, 382=sh, 383=multi, 384=wpkh, 385=wsh, 386=tr.
Key Fingerprint
The first 4 bytes of HASH160(master public key). Used in descriptors as [fp/path] to identify the origin key.
Range Descriptor
A descriptor using /* or /0/* to specify an index range, generating a sequence of addresses.
NUMS Point
Nothing-Up-My-Sleeve point. A provably unspendable Taproot key-path used when only script-path spends are intended.
miniscript
A structured subset of Bitcoin Script expressible inside wsh() and tr() descriptors for complex spending conditions.
INTERACTIVE — TRY IT YOURSELF
WALLETS / OUTPUT DESCRIPTORS
Output Descriptors
Output descriptors (BIP380–386) are a human-readable language for describing sets of scriptPubKeys. A descriptor completely specifies how to derive keys and construct scripts — replacing the implicit assumptions of older wallet software. A wallet with a descriptor can be fully reconstructed from a backup without relying on unclear conventions.
DESCRIPTOR REFERENCE
| FUNCTION | SCRIPT TYPE | KEY TYPE | EXAMPLE | |
|---|---|---|---|---|
| pk(KEY) | P2PK | compressed pubkey | pk(02f9308a…) | |
| pkh(KEY) | P2PKH | pubkey or xpub | pkh(xpub…/0/*) | |
| wpkh(KEY) | P2WPKH | compressed pubkey | wpkh(xpub…/0/*) | |
| sh(SCRIPT) | P2SH | wraps any script | sh(wpkh(xpub…)) | |
| wsh(SCRIPT) | P2WSH | wraps any script | wsh(multi(…)) | |
| tr(KEY) | P2TR (BIP386) | internal key | tr(xpub…/0/*) | |
| multi(k,…) | k-of-n multisig | multiple keys | sh(multi(2,K1,K2,K3)) | |
| sortedmulti(k,…) | k-of-n multisig | BIP67 sorted | wsh(sortedmulti(2,K1,K2)) | |
| addr(ADDR) | any | Bitcoin address | addr(bc1q…) | |
| raw(HEX) | arbitrary script | — | raw(76a914…88ac) |
DESCRIPTOR PARSER
PARSE + ANNOTATE DESCRIPTORclick TRY buttons above to load examples
KEY EXPRESSIONS
Key expressions inside a descriptor can take several forms. Each encodes a different level of derivation capability:
| FORM | MEANING | EXAMPLE |
|---|---|---|
| HEX | Literal compressed/uncompressed pubkey | 02f9308a019… |
| WIF | Private key in WIF encoding | KwDiBf89Q… |
| xpub/xprv | Extended public/private key (BIP32) | xpub6ERApf… |
| /num | Normal (non-hardened) child derivation | xpub…/0/1 |
| /num' or /numh | Hardened child derivation (requires xprv) | xprv…/44'/0'/0' |
| /* | Range: derive child 0, 1, 2, … (address index) | xpub…/0/* |
| /*' | Hardened range | xprv…/0/*' |
| [fingerprint/path] | Origin: master fingerprint + derivation path | [d34db33f/44'/0'/0']xpub… |
Checksums (BIP380): Each descriptor may have a checksum appended after
# — eight lowercase alphanumeric characters encoding a CRC-like polynomial over the descriptor string. Wallets should store and verify checksums. The descriptor without checksum is still valid — the checksum is advisory.CHECKSUM CALCULATOR
COMPUTE DESCRIPTOR CHECKSUM