---

name: bitcoin-descriptors description: | Output descriptors: BIP380-385 family. Descriptor language for declaring scriptPubKey templates with key origin info, ranges, checksums. Functions: pkh, wpkh, sh, wsh, tr, multi, sortedmulti, multi_a, addr, raw, combo, rawtr. USE WHEN: importing watch-only wallets, defining multisig, declaring scan ranges, exchanging key info between wallets. allowed-tools: Read, Grep, Glob

Output Descriptors

Descriptor language: a way to describe a set of scriptPubKey templates (addresses) with all metadata needed to derive, scan, and sign them.

Why descriptors

Pre-descriptors, "import this xpub at BIP44 paths" required convention. Different wallets used different paths, making coordination fragile. Descriptors make the script type, derivation, and key origin explicit.

Core syntax

function(args)#checksum

Functions:

Func	Output type
pk(KEY)	P2PK
pkh(KEY)	P2PKH
wpkh(KEY)	P2WPKH (native segwit single-sig)
sh(SCRIPT)	P2SH wrapper
wsh(SCRIPT)	P2WSH wrapper (segwit script)
tr(KEY) or tr(KEY, TREE)	P2TR (Taproot)
rawtr(KEY)	P2TR with raw output key (no tweak) — rare, only when key already includes a commitment
multi(k, KEY1, KEY2, ...)	unsorted k-of-n multisig (legacy ordering)
sortedmulti(k, KEY1, KEY2, ...)	k-of-n with keys lexicographically sorted at runtime
multi_a(k, KEY1, KEY2, ...)	k-of-n multisig in Tapscript (uses CHECKSIGADD)
addr(ADDRESS)	hard-coded address
raw(HEX)	hard-coded scriptPubKey (advanced/debug)
combo(KEY)	shorthand for pk + pkh + wpkh + sh-wpkh (legacy compat)

Keys

A KEY is one of:

• Hex pubkey (66 char compressed or 130 uncompressed).
• WIF privkey (signing-capable descriptor).
• xpub / xprv (extended key).
• xpub with derivation: xpub.../84h/0h/0h/0/* or xpub.../<0;1>/* (multipath BIP389).

Key origin

Prefix [fingerprint/path] declares where this key came from in a master tree:

[d34db33f/84h/0h/0h]xpub.../<0;1>/*

• d34db33f = fingerprint of master key (4-byte hex).
• 84h/0h/0h = path used to reach this xpub from master.
• <0;1>/* = multipath: receive (0) and change (1) derivation chains.

Key origin is mandatory for any cross-wallet coordination (multisig, hardware signing). Without it, signers can't tell which device should sign.

Checksums

Every descriptor ends with #XXXXXXXX (8 chars, BCH code over the character set). Wallet APIs typically auto-compute via getdescriptorinfo.

Ranges

A descriptor with * in derivation is a ranged descriptor. Import specifies a range:

{
  "desc": "wpkh([d34db33f/84h/0h/0h]xpub.../<0;1>/*)#abcd1234",
  "active": true,
  "range": [0, 999],
  "next_index": 0,
  "timestamp": "now"
}

Range = inclusive integer range of indices to scan.

Examples

Single-sig watch-only

wpkh([d34db33f/84h/0h/0h]xpub.../<0;1>/*)#chk

2-of-3 multisig (P2WSH)

wsh(sortedmulti(2,
  [d34db33f/48h/0h/0h/2h]xpub.../<0;1>/*,
  [b15ec0de/48h/0h/0h/2h]xpub.../<0;1>/*,
  [c0ffee00/48h/0h/0h/2h]xpub.../<0;1>/*
))#chk

Taproot single-sig with key-only

tr([d34db33f/86h/0h/0h]xpub.../<0;1>/*)#chk

Taproot key-path + 2-of-3 script-path (Tapscript multisig)

tr([fp/86h/0h/0h]xpub.../<0;1>/*,
   multi_a(2,
     [a/86h/0h/0h]xpub1.../<0;1>/*,
     [b/86h/0h/0h]xpub2.../<0;1>/*,
     [c/86h/0h/0h]xpub3.../<0;1>/*))#chk

RPC integration

RPC	Purpose
getdescriptorinfo "desc"	Compute checksum, validate syntax
deriveaddresses "desc" range	Generate addresses for a range
importdescriptors	Add to descriptors wallet (watch-only or signing)
listdescriptors	List descriptors in current wallet

Common bugs

• Missing key-origin → can't be used in multisig coordination.
• Hardened path component without an xprv → derivation fails (you can't derive hardened from xpub).
• Forgetting checksum on import in some implementations → rejection.
• Mixing multi (unsorted, key order matters for multisig signing) vs sortedmulti — multi requires same exact order on every signer.

See also

• psbt/SKILL.md
• miniscript/SKILL.md
• ../../wallets/hd/SKILL.md