Output script descriptors

In short

Structured expressions describing an output script and the information to restore a wallet.

Detailed explanation
Output script descriptors, or simply descriptors, are structured expressions that fully describe an output script (scriptPubKey) and provide all the necessary information to track transactions to or from a specific script. These descriptors facilitate the management of keys in HD wallets through a standard description of the structure and types of addresses used.
The main interest of descriptors lies in their ability to encapsulate all the essential information for restoring a wallet in a single string (in addition to the recovery phrase). By saving a descriptor with the corresponding mnemonic phrases, it is possible to restore not only the private keys but also the precise structure of the wallet and the associated script parameters. Indeed, recovering a wallet requires not only knowledge of the initial seed but also specific indexes for the derivation of child key pairs, as well as the xpub of each factor in the case of a multisig wallet. Previously, it was assumed that this information was implicitly known by all. However, with the diversification of scripts and the emergence of more complex configurations, this information could become difficult to extrapolate, thus turning these data into private and hard-to-bruteforce information. The use of descriptors greatly simplifies the process: it is enough to know the recovery phrase(s) and the corresponding descriptor to restore everything reliably and securely.
A descriptor consists of several elements:
  • Script functions like pk (Pay-to-PubKey), pkh (Pay-to-PubKey-Hash), wpkh (Pay-to-Witness-PubKey-Hash), sh (Pay-to-Script-Hash), wsh (Pay-to-Witness-Script-Hash), tr (Pay-to-Taproot), multi (Multisignature), and sortedmulti (Multisignature with sorted keys);
  • Derivation paths, for example, [d34db33f/44h/0h/0h] indicating a derived path and a specific master key fingerprint;
  • Keys in various formats such as hexadecimal public keys or extended public keys (xpub);
  • A checksum, preceded by a hash, to verify the integrity of the descriptor.
For example, a descriptor for a P2WPKH wallet could look like:
wpkh([cdeab12f/84h/0h/0h]xpub6CUGRUonZSQ4TWtTMmzXdrXDtyPWKiKbERr4d5qkSmh5h17
C1TjvMt7DJ9Qve4dRxm91CDv6cNfKsq2mK1rMsJKhtRUPZz7MQtp3y6atC1U/<0;1>/#jy0l7n
r4
In this descriptor, the derivation function wpkh indicates a Pay-to-Witness-Public-Key-Hash script type. It is followed by the derivation path which contains:
  • cdeab12f: the fingerprint of the master key;
  • 84h: which signifies the use of a BIP84 purpose, intended for SegWit v0 addresses;
  • 0h: which indicates that it is a BTC currency on the mainnet;
  • 0h: which refers to the specific account number used in the wallet.
The descriptor also includes the extended public key used in this wallet:
xpub6CUGRUonZSQ4TWtTMmzXdrXDtyPWKiKbERr4d5qkSmh5h17C1TjvMt7DJ9Qve4dRxm91CDv6
cNfKsq2mK1rMsJKhtRUPZz7MQtp3y6atC1U
Next, the notation /<0;1>/* specifies that the descriptor can generate addresses from the external (0) and internal (1) chain, with a wildcard (*) allowing for the sequential derivation of multiple addresses in a configurable manner, similar to managing a "gap limit" on traditional wallet software.
Finally, #jy0l7nr4 represents the checksum to verify the integrity of the descriptor.
TermDefinition
51% attack
An attack where a malicious actor controls more than half of the mining hash power, allowing them to manipulate transactions, notably by performing double spends.
Account
In an HD wallet, a derivation level (depth 3) allowing hierarchical organization of keys and addresses.
Activation method
The process by which the Bitcoin community decides to activate a soft fork, seeking consensus among miners and users to avoid a blockchain split.
Adaptor signature
A cryptographic technique linking a signature to a secret, such that publishing the signature reveals the secret. Useful for atomic swaps without a trusted intermediary.
Addr
An old Bitcoin network message that allowed communicating IP addresses of nodes accepting connections. Replaced by addrv2 (BIP155) to support longer address formats.
Addr.dat
An old file in Bitcoin Core that stored information about network peers. Replaced by peers.dat since version 0.7.0.
Address reuse
A discouraged practice of using the same Bitcoin address multiple times to receive payments, which harms privacy by allowing funds to be traced.
Address spoofing
An attack where a malicious actor creates an address closely resembling the victim's to deceive them and divert their payments.
Addrv2
A new network message format (BIP155) allowing the broadcasting of Bitcoin node addresses. Supports longer addresses such as Tor v3 or I2P.
Agorism
A libertarian political philosophy advocating economic action outside of state control (counter-economy) to progressively undermine state power.
Air cooling
A cooling system for mining machines using fans to dissipate heat. The most widespread and least expensive method.
Altcoin
Designates any cryptocurrency other than Bitcoin. A contraction of alternative and coin.
Aluvm
A virtual machine designed for deterministic execution of smart contracts, notably within the context of the RGB protocol on Bitcoin.
Analysis heuristic
An empirical method used to trace Bitcoin flows on the blockchain based on observable characteristics within transactions.
Ancestor mining
A principle whereby a miner selects transactions taking into account the fees of parent transactions, not only their own fees. Also called CPFP.
Anchor
In the RGB protocol, a set of data proving the inclusion of a commitment in a Bitcoin transaction, without publicly revealing its content.
Anchor outputs
A mechanism on Lightning allowing adjustment of the fees of a commitment transaction after its creation, to ensure quick channel closure.
Anchors.dat
A Bitcoin Core file storing IP addresses of nodes the client was connected to before shutdown, to facilitate reconnection on restart.
Anonsets (anonymity sets)
Indicators measuring the degree of privacy of a UTXO by counting the number of indistinguishable UTXOs in a set, typically after a coinjoin.
Anyprevout (apo)
A proposal (BIP118) adding new SigHash flags allowing the creation of signatures that do not cover any specific input of the transaction.
51% attack
An attack where a malicious actor controls more than half of the mining hash power, allowing them to manipulate transactions, notably by performing double spends.
Account
In an HD wallet, a derivation level (depth 3) allowing hierarchical organization of keys and addresses.
Activation method
The process by which the Bitcoin community decides to activate a soft fork, seeking consensus among miners and users to avoid a blockchain split.
Adaptor signature
A cryptographic technique linking a signature to a secret, such that publishing the signature reveals the secret. Useful for atomic swaps without a trusted intermediary.
Addr
An old Bitcoin network message that allowed communicating IP addresses of nodes accepting connections. Replaced by addrv2 (BIP155) to support longer address formats.
Addr.dat
An old file in Bitcoin Core that stored information about network peers. Replaced by peers.dat since version 0.7.0.
Address reuse
A discouraged practice of using the same Bitcoin address multiple times to receive payments, which harms privacy by allowing funds to be traced.
Address spoofing
An attack where a malicious actor creates an address closely resembling the victim's to deceive them and divert their payments.
Addrv2
A new network message format (BIP155) allowing the broadcasting of Bitcoin node addresses. Supports longer addresses such as Tor v3 or I2P.
Agorism
A libertarian political philosophy advocating economic action outside of state control (counter-economy) to progressively undermine state power.
Air cooling
A cooling system for mining machines using fans to dissipate heat. The most widespread and least expensive method.
Altcoin
Designates any cryptocurrency other than Bitcoin. A contraction of alternative and coin.
Aluvm
A virtual machine designed for deterministic execution of smart contracts, notably within the context of the RGB protocol on Bitcoin.
Analysis heuristic
An empirical method used to trace Bitcoin flows on the blockchain based on observable characteristics within transactions.
Ancestor mining
A principle whereby a miner selects transactions taking into account the fees of parent transactions, not only their own fees. Also called CPFP.
Anchor
In the RGB protocol, a set of data proving the inclusion of a commitment in a Bitcoin transaction, without publicly revealing its content.
Anchor outputs
A mechanism on Lightning allowing adjustment of the fees of a commitment transaction after its creation, to ensure quick channel closure.
Anchors.dat
A Bitcoin Core file storing IP addresses of nodes the client was connected to before shutdown, to facilitate reconnection on restart.
Anonsets (anonymity sets)
Indicators measuring the degree of privacy of a UTXO by counting the number of indistinguishable UTXOs in a set, typically after a coinjoin.
Anyprevout (apo)
A proposal (BIP118) adding new SigHash flags allowing the creation of signatures that do not cover any specific input of the transaction.