Line data    Source code

       1             : // Copyright (c) 2018-2020 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 <optional.h>
       9             : #include <outputtype.h>
      10             : #include <script/script.h>
      11             : #include <script/sign.h>
      12             : #include <script/signingprovider.h>
      13             : 
      14             : #include <vector>
      15             : 
      16             : using ExtPubKeyMap = std::unordered_map<uint32_t, CExtPubKey>;
      17             : 
      18             : /** Cache for single descriptor's derived extended pubkeys */
      19       67593 : class DescriptorCache {
      20             : private:
      21             :     /** Map key expression index -> map of (key derivation index -> xpub) */
      22             :     std::unordered_map<uint32_t, ExtPubKeyMap> m_derived_xpubs;
      23             :     /** Map key expression index -> parent xpub */
      24             :     ExtPubKeyMap m_parent_xpubs;
      25             : 
      26             : public:
      27             :     /** Cache a parent xpub
      28             :      *
      29             :      * @param[in] key_exp_pos Position of the key expression within the descriptor
      30             :      * @param[in] xpub The CExtPubKey to cache
      31             :      */
      32             :     void CacheParentExtPubKey(uint32_t key_exp_pos, const CExtPubKey& xpub);
      33             :     /** Retrieve a cached parent xpub
      34             :      *
      35             :      * @param[in] key_exp_pos Position of the key expression within the descriptor
      36             :      * @param[in] xpub The CExtPubKey to get from cache
      37             :      */
      38             :     bool GetCachedParentExtPubKey(uint32_t key_exp_pos, CExtPubKey& xpub) const;
      39             :     /** Cache an xpub derived at an index
      40             :      *
      41             :      * @param[in] key_exp_pos Position of the key expression within the descriptor
      42             :      * @param[in] der_index Derivation index of the xpub
      43             :      * @param[in] xpub The CExtPubKey to cache
      44             :      */
      45             :     void CacheDerivedExtPubKey(uint32_t key_exp_pos, uint32_t der_index, const CExtPubKey& xpub);
      46             :     /** Retrieve a cached xpub derived at an index
      47             :      *
      48             :      * @param[in] key_exp_pos Position of the key expression within the descriptor
      49             :      * @param[in] der_index Derivation index of the xpub
      50             :      * @param[in] xpub The CExtPubKey to get from cache
      51             :      */
      52             :     bool GetCachedDerivedExtPubKey(uint32_t key_exp_pos, uint32_t der_index, CExtPubKey& xpub) const;
      53             : 
      54             :     /** Retrieve all cached parent xpubs */
      55             :     const ExtPubKeyMap GetCachedParentExtPubKeys() const;
      56             :     /** Retrieve all cached derived xpubs */
      57             :     const std::unordered_map<uint32_t, ExtPubKeyMap> GetCachedDerivedExtPubKeys() const;
      58             : };
      59             : 
      60             : /** \brief Interface for parsed descriptor objects.
      61             :  *
      62             :  * Descriptors are strings that describe a set of scriptPubKeys, together with
      63             :  * all information necessary to solve them. By combining all information into
      64             :  * one, they avoid the need to separately import keys and scripts.
      65             :  *
      66             :  * Descriptors may be ranged, which occurs when the public keys inside are
      67             :  * specified in the form of HD chains (xpubs).
      68             :  *
      69             :  * Descriptors always represent public information - public keys and scripts -
      70             :  * but in cases where private keys need to be conveyed along with a descriptor,
      71             :  * they can be included inside by changing public keys to private keys (WIF
      72             :  * format), and changing xpubs by xprvs.
      73             :  *
      74             :  * Reference documentation about the descriptor language can be found in
      75             :  * doc/descriptors.md.
      76             :  */
      77      315668 : struct Descriptor {
      78      315668 :     virtual ~Descriptor() = default;
      79             : 
      80             :     /** Whether the expansion of this descriptor depends on the position. */
      81             :     virtual bool IsRange() const = 0;
      82             : 
      83             :     /** Whether this descriptor has all information about signing ignoring lack of private keys.
      84             :      *  This is true for all descriptors except ones that use `raw` or `addr` constructions. */
      85             :     virtual bool IsSolvable() const = 0;
      86             : 
      87             :     /** Convert the descriptor back to a string, undoing parsing. */
      88             :     virtual std::string ToString() const = 0;
      89             : 
      90             :     /** Whether this descriptor will return one scriptPubKey or multiple (aka is or is not combo) */
      91             :     virtual bool IsSingleType() const = 0;
      92             : 
      93             :     /** Convert the descriptor to a private string. This fails if the provided provider does not have the relevant private keys. */
      94             :     virtual bool ToPrivateString(const SigningProvider& provider, std::string& out) const = 0;
      95             : 
      96             :     /** Expand a descriptor at a specified position.
      97             :      *
      98             :      * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
      99             :      * @param[in] provider The provider to query for private keys in case of hardened derivation.
     100             :      * @param[out] output_scripts The expanded scriptPubKeys.
     101             :      * @param[out] out Scripts and public keys necessary for solving the expanded scriptPubKeys (may be equal to `provider`).
     102             :      * @param[out] write_cache Cache data necessary to evaluate the descriptor at this point without access to private keys.
     103             :      */
     104             :     virtual bool Expand(int pos, const SigningProvider& provider, std::vector<CScript>& output_scripts, FlatSigningProvider& out, DescriptorCache* write_cache = nullptr) const = 0;
     105             : 
     106             :     /** Expand a descriptor at a specified position using cached expansion data.
     107             :      *
     108             :      * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
     109             :      * @param[in] read_cache Cached expansion data.
     110             :      * @param[out] output_scripts The expanded scriptPubKeys.
     111             :      * @param[out] out Scripts and public keys necessary for solving the expanded scriptPubKeys (may be equal to `provider`).
     112             :      */
     113             :     virtual bool ExpandFromCache(int pos, const DescriptorCache& read_cache, std::vector<CScript>& output_scripts, FlatSigningProvider& out) const = 0;
     114             : 
     115             :     /** Expand the private key for a descriptor at a specified position, if possible.
     116             :      *
     117             :      * @param[in] pos The position at which to expand the descriptor. If IsRange() is false, this is ignored.
     118             :      * @param[in] provider The provider to query for the private keys.
     119             :      * @param[out] out Any private keys available for the specified `pos`.
     120             :      */
     121             :     virtual void ExpandPrivate(int pos, const SigningProvider& provider, FlatSigningProvider& out) const = 0;
     122             : 
     123             :     /** @return The OutputType of the scriptPubKey(s) produced by this descriptor. Or nullopt if indeterminate (multiple or none) */
     124             :     virtual Optional<OutputType> GetOutputType() const = 0;
     125             : };
     126             : 
     127             : /** Parse a `descriptor` string. Included private keys are put in `out`.
     128             :  *
     129             :  * If the descriptor has a checksum, it must be valid. If `require_checksum`
     130             :  * is set, the checksum is mandatory - otherwise it is optional.
     131             :  *
     132             :  * If a parse error occurs, or the checksum is missing/invalid, or anything
     133             :  * else is wrong, `nullptr` is returned.
     134             :  */
     135             : std::unique_ptr<Descriptor> Parse(const std::string& descriptor, FlatSigningProvider& out, std::string& error, bool require_checksum = false);
     136             : 
     137             : /** Get the checksum for a `descriptor`.
     138             :  *
     139             :  * - If it already has one, and it is correct, return the checksum in the input.
     140             :  * - If it already has one that is wrong, return "".
     141             :  * - If it does not already have one, return the checksum that would need to be added.
     142             :  */
     143             : std::string GetDescriptorChecksum(const std::string& descriptor);
     144             : 
     145             : /** Find a descriptor for the specified `script`, using information from `provider` where possible.
     146             :  *
     147             :  * A non-ranged descriptor which only generates the specified script will be returned in all
     148             :  * circumstances.
     149             :  *
     150             :  * For public keys with key origin information, this information will be preserved in the returned
     151             :  * descriptor.
     152             :  *
     153             :  * - If all information for solving `script` is present in `provider`, a descriptor will be returned
     154             :  *   which is IsSolvable() and encapsulates said information.
     155             :  * - Failing that, if `script` corresponds to a known address type, an "addr()" descriptor will be
     156             :  *   returned (which is not IsSolvable()).
     157             :  * - Failing that, a "raw()" descriptor is returned.
     158             :  */
     159             : std::unique_ptr<Descriptor> InferDescriptor(const CScript& script, const SigningProvider& provider);
     160             : 
     161             : #endif // BITCOIN_SCRIPT_DESCRIPTOR_H