READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server340 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

12,180 bytes · SHA-256 60abeb5ffb086166… · View upstream ↗

1// Copyright (c) 2018-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_SCRIPT_DESCRIPTOR_H
6#define BITCOIN_SCRIPT_DESCRIPTOR_H
7
8#include <outputtype.h>
9#include <pubkey.h>
10#include <uint256.h>
11
12#include <cstddef>
13#include <cstdint>
14#include <memory>
15#include <optional>
16#include <set>
17#include <string>
18#include <string_view>
19#include <unordered_map>
20#include <vector>
21
22class CScript;
23class SigningProvider;
24struct FlatSigningProvider;
25
26using ExtPubKeyMap = std::unordered_map<uint32_t, CExtPubKey>;
27
28/** Cache for single descriptor's derived extended pubkeys */
29class DescriptorCache {
30private:
31    /** Map key expression index -> map of (key derivation index -> xpub) */
32    std::unordered_map<uint32_t, ExtPubKeyMap> m_derived_xpubs;
33    /** Map key expression index -> parent xpub */
34    ExtPubKeyMap m_parent_xpubs;
35    /** Map key expression index -> last hardened xpub */
36    ExtPubKeyMap m_last_hardened_xpubs;
37
38public:
39    /** Cache a parent xpub
40     *
41     * @param[in] key_exp_pos Position of the key expression within the descriptor
42     * @param[in] xpub The CExtPubKey to cache
43     */
44    void CacheParentExtPubKey(uint32_t key_exp_pos, const CExtPubKey& xpub);
45    /** Retrieve a cached parent xpub
46     *
47     * @param[in] key_exp_pos Position of the key expression within the descriptor
48     * @param[out] xpub The CExtPubKey to get from cache
49     */
50    bool GetCachedParentExtPubKey(uint32_t key_exp_pos, CExtPubKey& xpub) const;
51    /** Cache an xpub derived at an index
52     *
53     * @param[in] key_exp_pos Position of the key expression within the descriptor
54     * @param[in] der_index Derivation index of the xpub
55     * @param[in] xpub The CExtPubKey to cache
56     */
57    void CacheDerivedExtPubKey(uint32_t key_exp_pos, uint32_t der_index, const CExtPubKey& xpub);
58    /** Retrieve a cached xpub derived at an index
59     *
60     * @param[in] key_exp_pos Position of the key expression within the descriptor
61     * @param[in] der_index Derivation index of the xpub
62     * @param[out] xpub The CExtPubKey to get from cache
63     */
64    bool GetCachedDerivedExtPubKey(uint32_t key_exp_pos, uint32_t der_index, CExtPubKey& xpub) const;
65    /** Cache a last hardened xpub
66     *
67     * @param[in] key_exp_pos Position of the key expression within the descriptor
68     * @param[in] xpub The CExtPubKey to cache
69     */
70    void CacheLastHardenedExtPubKey(uint32_t key_exp_pos, const CExtPubKey& xpub);
71    /** Retrieve a cached last hardened xpub
72     *
73     * @param[in] key_exp_pos Position of the key expression within the descriptor
74     * @param[out] xpub The CExtPubKey to get from cache
75     */
76    bool GetCachedLastHardenedExtPubKey(uint32_t key_exp_pos, CExtPubKey& xpub) const;
77
78    /** Retrieve all cached parent xpubs */
79    ExtPubKeyMap GetCachedParentExtPubKeys() const;
80    /** Retrieve all cached derived xpubs */
81    std::unordered_map<uint32_t, ExtPubKeyMap> GetCachedDerivedExtPubKeys() const;
82    /** Retrieve all cached last hardened xpubs */
83    ExtPubKeyMap GetCachedLastHardenedExtPubKeys() const;
84
85    /** Combine another DescriptorCache into this one.
86     * Returns a cache containing the items from the other cache unknown to current cache
87     */
88    DescriptorCache MergeAndDiff(const DescriptorCache& other);
89};
90
91/** \brief Interface for parsed descriptor objects.
92 *
93 * Descriptors are strings that describe a set of scriptPubKeys, together with
94 * all information necessary to solve them. By combining all information into
95 * one, they avoid the need to separately import keys and scripts.
96 *
97 * Descriptors may be ranged, which occurs when the public keys inside are
98 * specified in the form of HD chains (xpubs).
99 *
100 * Descriptors always represent public information - public keys and scripts -
101 * but in cases where private keys need to be conveyed along with a descriptor,
102 * they can be included inside by changing public keys to private keys (WIF
103 * format), and changing xpubs by xprvs.
104 *
105 * Reference documentation about the descriptor language can be found in
106 * doc/descriptors.md.
107 */
108struct Descriptor {
109    virtual ~Descriptor() = default;
110
111    /** Whether the expansion of this descriptor depends on the position. */
112    virtual bool IsRange() const = 0;
113
114    /** Whether this descriptor has all information about signing ignoring lack of private keys.
115     *  This is true for all descriptors except ones that use `raw` or `addr` constructions. */
116    virtual bool IsSolvable() const = 0;
117
118    /** Convert the descriptor back to a string, undoing parsing. */
119    virtual std::string ToString(bool compat_format=false) const = 0;
120
121    /** Convert the descriptor to the canonical string.
122     * The canonical string is the same as the public string but always uses h as the hardened indicator
123     */
124    virtual std::string ToCanonicalString() const = 0;
125
126    /** Whether this descriptor will return at most one scriptPubKey or multiple (aka is or is not combo) */
127    virtual bool IsSingleType() const = 0;
128
129    /** Whether the given provider has all private keys required by this descriptor.
130     * @return `false` if the descriptor doesn't have any keys or subdescriptors,
131     *         or if the provider does not have all private keys required by
132     *         the descriptor.
133     */
134    virtual bool HavePrivateKeys(const SigningProvider& provider) const = 0;
135
136    /** Convert the descriptor to a private string. This uses public keys if the relevant private keys are not in the SigningProvider.
137     *  If none of the relevant private keys are available, the output string in the "out" parameter will not contain any private key information,
138     *  and this function will return "false".
139     *  @param[in] provider The SigningProvider to query for private keys.
140     *  @param[out] out The resulting descriptor string, containing private keys if available.
141     *  @returns true if at least one private key available.
142     */
143    virtual bool ToPrivateString(const SigningProvider& provider, std::string& out) const = 0;
144
145    /** Convert the descriptor to a normalized string. Normalized descriptors have the xpub at the last hardened step. This fails if the provided provider does not have the private keys to derive that xpub. */
146    virtual bool ToNormalizedString(const SigningProvider& provider, std::string& out, const DescriptorCache* cache = nullptr) const = 0;
147
148    /** Whether the descriptor can be used to produce its address(es) without needing a cache or private keys. */
149    virtual bool CanSelfExpand() const = 0;
150
151    /** Expand a descriptor at a specified position.
152     *
153     * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
154     * @param[in] provider The provider to query for private keys in case of hardened derivation.
155     * @param[out] output_scripts The expanded scriptPubKeys.
156     * @param[out] out Scripts and public keys necessary for solving the expanded scriptPubKeys (may be equal to `provider`).
157     * @param[out] write_cache Cache data necessary to evaluate the descriptor at this point without access to private keys.
158     */
159    virtual bool Expand(int pos, const SigningProvider& provider, std::vector<CScript>& output_scripts, FlatSigningProvider& out, DescriptorCache* write_cache = nullptr) const = 0;
160
161    /** Expand a descriptor at a specified position using cached expansion data.
162     *
163     * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
164     * @param[in] read_cache Cached expansion data.
165     * @param[out] output_scripts The expanded scriptPubKeys.
166     * @param[out] out Scripts and public keys necessary for solving the expanded scriptPubKeys (may be equal to `provider`).
167     */
168    virtual bool ExpandFromCache(int pos, const DescriptorCache& read_cache, std::vector<CScript>& output_scripts, FlatSigningProvider& out) const = 0;
169
170    /** Expand the private key for a descriptor at a specified position, if possible.
171     *
172     * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
173     * @param[in] provider The provider to query for the private keys.
174     * @param[out] out Any private keys available for the specified `pos`.
175     */
176    virtual void ExpandPrivate(int pos, const SigningProvider& provider, FlatSigningProvider& out) const = 0;
177
178    /** @return The OutputType of the scriptPubKey(s) produced by this descriptor. Or nullopt if indeterminate (multiple or none) */
179    virtual std::optional<OutputType> GetOutputType() const = 0;
180
181    /** Get the size of the scriptPubKey for this descriptor. */
182    virtual std::optional<int64_t> ScriptSize() const = 0;
183
184    /** Get the maximum size of a satisfaction for this descriptor, in weight units.
185     *
186     * @param use_max_sig Whether to assume ECDSA signatures will have a high-r.
187     */
188    virtual std::optional<int64_t> MaxSatisfactionWeight(bool use_max_sig) const = 0;
189
190    /** Get the maximum size number of stack elements for satisfying this descriptor. */
191    virtual std::optional<int64_t> MaxSatisfactionElems() const = 0;
192
193    /** Return all (extended) public keys for this descriptor, including any from subdescriptors.
194     *
195     * @param[out] pubkeys Any public keys
196     * @param[out] ext_pubs Any extended public keys
197     */
198    virtual void GetPubKeys(std::set<CPubKey>& pubkeys, std::set<CExtPubKey>& ext_pubs) const = 0;
199
200    /** Whether this descriptor produces any scripts with the Expand functions */
201    virtual bool HasScripts() const = 0;
202
203    /** Semantic/safety warnings (includes subdescriptors). */
204    virtual std::vector<std::string> Warnings() const = 0;
205
206    /** Get the maximum key expression index. Used only for tests */
207    virtual uint32_t GetMaxKeyExpr() const = 0;
208
209    /** Get the number of key expressions in this descriptor. Used only for tests */
210    virtual size_t GetKeyCount() const = 0;
211};
212
213/** Parse a `descriptor` string. Included private keys are put in `out`.
214 *
215 * If the descriptor has a checksum, it must be valid. If `require_checksum`
216 * is set, the checksum is mandatory - otherwise it is optional.
217 *
218 * If a parse error occurs, or the checksum is missing/invalid, or anything
219 * else is wrong, an empty vector is returned.
220 */
221std::vector<std::unique_ptr<Descriptor>> Parse(std::string_view descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum = false);
222
223/** Get the checksum for a `descriptor`.
224 *
225 * - If it already has one, and it is correct, return the checksum in the input.
226 * - If it already has one that is wrong, return "".
227 * - If it does not already have one, return the checksum that would need to be added.
228 */
229std::string GetDescriptorChecksum(const std::string& descriptor);
230
231/** Find a descriptor for the specified `script`, using information from `provider` where possible.
232 *
233 * A non-ranged descriptor which only generates the specified script will be returned in all
234 * circumstances.
235 *
236 * For public keys with key origin information, this information will be preserved in the returned
237 * descriptor.
238 *
239 * - If all information for solving `script` is present in `provider`, a descriptor will be returned
240 *   which is IsSolvable() and encapsulates said information.
241 * - Failing that, if `script` corresponds to a known address type, an "addr()" descriptor will be
242 *   returned (which is not IsSolvable()).
243 * - Failing that, a "raw()" descriptor is returned.
244 */
245std::unique_ptr<Descriptor> InferDescriptor(const CScript& script, const SigningProvider& provider);
246
247/** Hash of the COMPAT string representation of the descriptor that is not supposed to change over time.
248 * Due to the hash's usage in previous versions, the COMPAT string is computed with some quirks.
249 *
250 * The hash is the sha256 of the public descriptor using apostrophes as the hardened indicator, except inside of

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.