Descriptor wallet - Revision history

NotATether: Add Descriptor syntax, Bitcoin Core, and Compatibility sections

2026-09-13T07:35:10Z

Add Descriptor syntax, Bitcoin Core, and Compatibility sections

← Older revision		Revision as of 07:35, 13 September 2026
Line 2:		Line 2:

	[[Bitcoin Core]] introduced descriptor wallets in 0.21 and made them the default for new wallets in 23.0. Legacy Berkeley DB wallets that inferred that the same pubkey might appear in P2PKH, P2WPKH, or P2SH-P2WPKH are a different model. HD wallets after BIP 32 still had an underspecified mapping from keys to scripts: the same xpub might mean P2PKH in one program and P2WPKH in another, and multisig coordinators disagreed on key order, witness versus scriptSig, and change paths. Descriptors make that mapping explicit so that two programs that import the same string watch the same outputs and produce compatible [[PSBT]]s.		[[Bitcoin Core]] introduced descriptor wallets in 0.21 and made them the default for new wallets in 23.0. Legacy Berkeley DB wallets that inferred that the same pubkey might appear in P2PKH, P2WPKH, or P2SH-P2WPKH are a different model. HD wallets after BIP 32 still had an underspecified mapping from keys to scripts: the same xpub might mean P2PKH in one program and P2WPKH in another, and multisig coordinators disagreed on key order, witness versus scriptSig, and change paths. Descriptors make that mapping explicit so that two programs that import the same string watch the same outputs and produce compatible [[PSBT]]s.

			== Descriptor syntax ==

	A descriptor combines a function such as <code>pkh()</code>, <code>wpkh()</code>, <code>sh(wpkh())</code>, <code>wsh(sortedmulti(…))</code>, <code>tr()</code>, or <code>addr()</code>; keys (hex public keys, WIF private keys, or xpub/xprv with origin info and a path, often ending in <code>/</code> for a range); and an optional checksum after <code>#</code>. An example BIP 84 receive-and-change form is <code>wpkh([deadbeef/84h/0h/0h]xpub…/<0;1>/)#checksum</code>. The origin <code>[fingerprint/path]</code> tells a hardware signer which seed and path to use; multipath <code><0;1></code> (BIP 389) covers the external and internal chains in one string.		A descriptor combines a function such as <code>pkh()</code>, <code>wpkh()</code>, <code>sh(wpkh())</code>, <code>wsh(sortedmulti(…))</code>, <code>tr()</code>, or <code>addr()</code>; keys (hex public keys, WIF private keys, or xpub/xprv with origin info and a path, often ending in <code>/</code> for a range); and an optional checksum after <code>#</code>. An example BIP 84 receive-and-change form is <code>wpkh([deadbeef/84h/0h/0h]xpub…/<0;1>/)#checksum</code>. The origin <code>[fingerprint/path]</code> tells a hardware signer which seed and path to use; multipath <code><0;1></code> (BIP 389) covers the external and internal chains in one string.

			== Bitcoin Core ==

	Bitcoin Core stores descriptors in an SQLite wallet database, marks some as active for receiving or change, and scans a range (by default on the order of a thousand indices, expandable) for matching outputs. Import uses <code>importdescriptors</code>; the older <code>importaddress</code> family is not available on descriptor wallets. Creating a blank watch-only wallet and importing an xpub descriptor is the supported watch-only path. [[Miniscript]] descriptors (<code>wsh(miniscript)</code>, <code>tr(miniscript)</code>) express policies that the wallet can both watch and, when it has the keys, satisfy; raw and addr descriptors watch scripts the wallet cannot necessarily spend.		Bitcoin Core stores descriptors in an SQLite wallet database, marks some as active for receiving or change, and scans a range (by default on the order of a thousand indices, expandable) for matching outputs. Import uses <code>importdescriptors</code>; the older <code>importaddress</code> family is not available on descriptor wallets. Creating a blank watch-only wallet and importing an xpub descriptor is the supported watch-only path. [[Miniscript]] descriptors (<code>wsh(miniscript)</code>, <code>tr(miniscript)</code>) express policies that the wallet can both watch and, when it has the keys, satisfy; raw and addr descriptors watch scripts the wallet cannot necessarily spend.
Line 11:		Line 15:
	Backup and recovery center on exporting the descriptor strings (and any private keys or seed that underpins them), not on dumping an ambiguous key pool. A receive descriptor without the matching change multipath can leave change outputs invisible after restore. Checksum verification catches transcription errors before a wallet watches the wrong script.		Backup and recovery center on exporting the descriptor strings (and any private keys or seed that underpins them), not on dumping an ambiguous key pool. A receive descriptor without the matching change multipath can leave change outputs invisible after restore. Checksum verification catches transcription errors before a wallet watches the wrong script.

	Related BIPs refine the language: BIP 381–386 cover specific script templates, BIP 389 adds multipath expressions, and later work extends Taproot and Miniscript forms. Wallets that only implement a subset must document which descriptor functions they accept so coordinators do not assume full Core parity. Migrating a legacy Core wallet to descriptors is a one-way conversion that rewrites how the wallet tracks scripts.		== Compatibility ==

			Related BIPs refine the language: BIP 381–386 cover specific script templates, BIP 389 adds multipath expressions, and later work extends Taproot and Miniscript forms. Wallets that only implement a subset must document which descriptor functions they accept so coordinators do not assume full Core parity. Migrating a legacy Core wallet to descriptors is a one-way conversion that rewrites how the wallet tracks scripts. Multisig coordinators that publish a single descriptor string reduce mismatch risk between hardware signers and watch-only software. Changing key order or a derivation path requires a new descriptor and usually a new birthday rescan.

	== See also ==		== See also ==

NotATether: Expand See also links

2026-09-13T07:24:47Z

Expand See also links

← Older revision		Revision as of 07:24, 13 September 2026
Line 17:		Line 17:
	* [[Miniscript]]		* [[Miniscript]]
	* [[PSBT]]		* [[PSBT]]
			* [[Segregated Witness]]
			* [[Taproot]]
	* [[Hardware wallet]]		* [[Hardware wallet]]
	* [[Electrum]]		* [[Electrum]]

NotATether: Add related BIPs and legacy migration

2026-09-13T07:24:45Z

Add related BIPs and legacy migration

← Older revision		Revision as of 07:24, 13 September 2026
Line 10:		Line 10:

	Backup and recovery center on exporting the descriptor strings (and any private keys or seed that underpins them), not on dumping an ambiguous key pool. A receive descriptor without the matching change multipath can leave change outputs invisible after restore. Checksum verification catches transcription errors before a wallet watches the wrong script.		Backup and recovery center on exporting the descriptor strings (and any private keys or seed that underpins them), not on dumping an ambiguous key pool. A receive descriptor without the matching change multipath can leave change outputs invisible after restore. Checksum verification catches transcription errors before a wallet watches the wrong script.

			Related BIPs refine the language: BIP 381–386 cover specific script templates, BIP 389 adds multipath expressions, and later work extends Taproot and Miniscript forms. Wallets that only implement a subset must document which descriptor functions they accept so coordinators do not assume full Core parity. Migrating a legacy Core wallet to descriptors is a one-way conversion that rewrites how the wallet tracks scripts.

	== See also ==		== See also ==

NotATether: Add backup and checksum recovery notes

2026-09-13T07:24:44Z

Add backup and checksum recovery notes

← Older revision		Revision as of 07:24, 13 September 2026
Line 8:		Line 8:

	Bitcoin Core is the reference descriptor wallet. Sparrow, hardware-wallet coordinators, and several libraries speak the same language; [[Hardware wallet\|hardware signers]] use origin information in PSBTs derived from descriptors. [[Electrum]]'s native wallet format is not descriptor-based, though Electrum can spend outputs that descriptors would also describe.		Bitcoin Core is the reference descriptor wallet. Sparrow, hardware-wallet coordinators, and several libraries speak the same language; [[Hardware wallet\|hardware signers]] use origin information in PSBTs derived from descriptors. [[Electrum]]'s native wallet format is not descriptor-based, though Electrum can spend outputs that descriptors would also describe.

			Backup and recovery center on exporting the descriptor strings (and any private keys or seed that underpins them), not on dumping an ambiguous key pool. A receive descriptor without the matching change multipath can leave change outputs invisible after restore. Checksum verification catches transcription errors before a wallet watches the wrong script.

	== See also ==		== See also ==

NotATether: Create Descriptor wallet stub: Bitcoin Core descriptor model (0.21 / default 23.0), BIP 380 strings, PSBT/Miniscript; Output descriptor title not created

2026-09-13T07:23:05Z

Create Descriptor wallet stub: Bitcoin Core descriptor model (0.21 / default 23.0), BIP 380 strings, PSBT/Miniscript; Output descriptor title not created

New page

A '''descriptor wallet''' is a wallet whose set of spendable scripts is defined by output descriptors rather than by an ad-hoc collection of keys and inferred scripts. A descriptor is a compact string that names a script template, the keys or extended public keys that fill it, a derivation path, and a checksum. The idea is specified in BIP 380 and related BIPs.

[[Bitcoin Core]] introduced descriptor wallets in 0.21 and made them the default for new wallets in 23.0. Legacy Berkeley DB wallets that inferred that the same pubkey might appear in P2PKH, P2WPKH, or P2SH-P2WPKH are a different model. HD wallets after BIP 32 still had an underspecified mapping from keys to scripts: the same xpub might mean P2PKH in one program and P2WPKH in another, and multisig coordinators disagreed on key order, witness versus scriptSig, and change paths. Descriptors make that mapping explicit so that two programs that import the same string watch the same outputs and produce compatible [[PSBT]]s.

A descriptor combines a function such as <code>pkh()</code>, <code>wpkh()</code>, <code>sh(wpkh())</code>, <code>wsh(sortedmulti(…))</code>, <code>tr()</code>, or <code>addr()</code>; keys (hex public keys, WIF private keys, or xpub/xprv with origin info and a path, often ending in <code>/*</code> for a range); and an optional checksum after <code>#</code>. An example BIP 84 receive-and-change form is <code>wpkh([deadbeef/84h/0h/0h]xpub…/<0;1>/*)#checksum</code>. The origin <code>[fingerprint/path]</code> tells a hardware signer which seed and path to use; multipath <code><0;1></code> (BIP 389) covers the external and internal chains in one string.

Bitcoin Core stores descriptors in an SQLite wallet database, marks some as active for receiving or change, and scans a range (by default on the order of a thousand indices, expandable) for matching outputs. Import uses <code>importdescriptors</code>; the older <code>importaddress</code> family is not available on descriptor wallets. Creating a blank watch-only wallet and importing an xpub descriptor is the supported watch-only path. [[Miniscript]] descriptors (<code>wsh(miniscript)</code>, <code>tr(miniscript)</code>) express policies that the wallet can both watch and, when it has the keys, satisfy; raw and addr descriptors watch scripts the wallet cannot necessarily spend.

Bitcoin Core is the reference descriptor wallet. Sparrow, hardware-wallet coordinators, and several libraries speak the same language; [[Hardware wallet|hardware signers]] use origin information in PSBTs derived from descriptors. [[Electrum]]'s native wallet format is not descriptor-based, though Electrum can spend outputs that descriptors would also describe.

== See also ==
* [[Bitcoin Core]]
* [[Miniscript]]
* [[PSBT]]
* [[Hardware wallet]]
* [[Electrum]]

== External links ==
* [https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki BIP 380: Output Script Descriptors General Operation]
* [https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki BIP 32 (hierarchical deterministic wallets)]
* [https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki BIP 84 (derivation paths for native SegWit)]
* [https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md Bitcoin Core descriptor documentation]

[[Category:Technical]]