Add support for output descriptors/miniscript.

Co-authored-by: Jon Griffiths <[email protected]>

Author: k-matsuzawa

.gitignore

@@ -80,6 +80,7 @@ docs/source/bip39.rst
 docs/source/core.rst
 docs/source/crypto.rst
 docs/source/map.rst
+docs/source/descriptor.rst
 docs/source/psbt.rst
 docs/source/psbt_members.rst
 docs/source/script.rst

docs/source/conf.py

@@ -82,7 +82,8 @@ def extract_docs(infile, outfile):
 else:
     for m in [
         'core', 'crypto', 'address', 'bip32', 'bip38', 'bip39', 'map',
-        'script', 'psbt', 'symmetric', 'transaction', 'elements', 'anti_exfil'
+        'script', 'psbt', 'descriptor', 'symmetric', 'transaction',
+        'elements', 'anti_exfil'
         ]:
         extract_docs('../../include/wally_%s.h' % m, '%s.rst' % m)
 

docs/source/index.rst

@@ -14,6 +14,7 @@ libwally-core documentation
    map
    psbt
    script
+   descriptor
    symmetric
    transaction
    elements

include/wally.hpp

@@ -421,6 +421,37 @@ inline int cleanup(uint32_t flags) {
     return ret;
 }
 
+template <class DESCRIPTOR, class VARS_IN>
+inline int descriptor_canonicalize(const DESCRIPTOR& descriptor, const VARS_IN& vars_in, uint32_t flags, char** output) {
+    int ret = ::wally_descriptor_canonicalize(detail::get_p(descriptor), detail::get_p(vars_in), flags, output);
+    return ret;
+}
+
+template <class DESCRIPTOR, class VARS_IN>
+inline int descriptor_get_checksum(const DESCRIPTOR& descriptor, const VARS_IN& vars_in, uint32_t flags, char** output) {
+    int ret = ::wally_descriptor_get_checksum(detail::get_p(descriptor), detail::get_p(vars_in), flags, output);
+    return ret;
+}
+
+template <class DESCRIPTOR, class VARS_IN>
+inline int descriptor_to_address(const DESCRIPTOR& descriptor, const VARS_IN& vars_in, uint32_t child_num, uint32_t network, uint32_t flags, char** output) {
+    int ret = ::wally_descriptor_to_address(detail::get_p(descriptor), detail::get_p(vars_in), child_num, network, flags, output);
+    return ret;
+}
+
+template <class DESCRIPTOR, class VARS_IN>
+inline int descriptor_to_addresses(const DESCRIPTOR& descriptor, const VARS_IN& vars_in, uint32_t child_num, uint32_t network, uint32_t flags, char** output, size_t num_outputs) {
+    int ret = ::wally_descriptor_to_addresses(detail::get_p(descriptor), detail::get_p(vars_in), child_num, network, flags, output, num_outputs);
+    return ret;
+}
+
+template <class DESCRIPTOR, class VARS_IN, class BYTES_OUT>
+inline int descriptor_to_scriptpubkey(const DESCRIPTOR& descriptor, const VARS_IN& vars_in, uint32_t child_num, uint32_t network, uint32_t depth, uint32_t index, uint32_t flags, BYTES_OUT& bytes_out, size_t* written = 0) {
+    size_t n;
+    int ret = ::wally_descriptor_to_scriptpubkey(detail::get_p(descriptor), detail::get_p(vars_in), child_num, network, depth, index, flags, bytes_out.data(), bytes_out.size(), written ? written : &n);
+    return written || ret != WALLY_OK ? ret : n == static_cast<size_t>(bytes_out.size()) ? WALLY_OK : WALLY_EINVAL;
+}
+
 template <class PRIV_KEY>
 inline int ec_private_key_verify(const PRIV_KEY& priv_key) {
     int ret = ::wally_ec_private_key_verify(priv_key.data(), priv_key.size());
@@ -787,6 +818,13 @@ inline int map_sort(const MAP_IN& map_in, uint32_t flags) {
     return ret;
 }
 
+template <class MINISCRIPT, class VARS_IN, class BYTES_OUT>
+inline int miniscript_to_script(const MINISCRIPT& miniscript, const VARS_IN& vars_in, uint32_t child_num, uint32_t flags, BYTES_OUT& bytes_out, size_t* written = 0) {
+    size_t n;
+    int ret = ::wally_miniscript_to_script(detail::get_p(miniscript), detail::get_p(vars_in), child_num, flags, bytes_out.data(), bytes_out.size(), written ? written : &n);
+    return written || ret != WALLY_OK ? ret : n == static_cast<size_t>(bytes_out.size()) ? WALLY_OK : WALLY_EINVAL;
+}
+
 template <class PASS, class SALT, class BYTES_OUT>
 inline int pbkdf2_hmac_sha256(const PASS& pass, const SALT& salt, uint32_t flags, uint32_t cost, BYTES_OUT& bytes_out) {
     int ret = ::wally_pbkdf2_hmac_sha256(pass.data(), pass.size(), salt.data(), salt.size(), flags, cost, bytes_out.data(), bytes_out.size());

include/wally_address.h

@@ -16,7 +16,9 @@ struct ext_key;
 #define WALLY_CA_PREFIX_LIQUID_REGTEST 0x04 /** Liquid v1 confidential address prefix for regtest */
 #define WALLY_CA_PREFIX_LIQUID_TESTNET 0x17 /** Liquid v1 confidential address prefix for testnet */
 
+#define WALLY_NETWORK_NONE 0x00 /** Used for miniscript parsing only */
 #define WALLY_NETWORK_BITCOIN_MAINNET 0x01 /** Bitcoin mainnet */
+#define WALLY_NETWORK_BITCOIN_REGTEST 0xff  /** Bitcoin regtest: Behaves as testnet except for segwit */
 #define WALLY_NETWORK_BITCOIN_TESTNET 0x02 /** Bitcoin testnet */
 #define WALLY_NETWORK_LIQUID 0x03 /** Liquid v1 */
 #define WALLY_NETWORK_LIQUID_REGTEST 0x04 /** Liquid v1 regtest */

include/wally_descriptor.h

@@ -0,0 +1,145 @@
+#ifndef LIBWALLY_CORE_DESCRIPTOR_H
+#define LIBWALLY_CORE_DESCRIPTOR_H
+
+#include "wally_core.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct wally_map;
+
+/* Miniscript type flag */
+#define WALLY_MINISCRIPT_WITNESS_SCRIPT 0x00 /** Witness script */
+#define WALLY_MINISCRIPT_TAPSCRIPT      0x01 /** Tapscript */
+
+/**
+ * Canonicalize a descriptor.
+ *
+ * :param descriptor: Output descriptor.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param flags: For future use. Must be 0.
+ * :param output: Destination for the resulting canonical descriptor.
+ *|    The string returned should be freed using `wally_free_string`.
+ *
+ * Replaces any variables from ``vars_in`` with their mapped values,
+ * and adds a checksum if required. Key names for ``vars_in`` must be 16
+ * characters or less and start with a letter.
+ *
+ * .. note:: Other canonicalization (hardened derivation indicator
+ * mapping, and private to public key mapping) is not yet implemented.
+ */
+WALLY_CORE_API int wally_descriptor_canonicalize(
+    const char *descriptor,
+    const struct wally_map *vars_in,
+    uint32_t flags,
+    char **output);
+
+/**
+ * Create a script corresponding to a miniscript string.
+ *
+ * :param miniscript: Miniscript string.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param child_num: The BIP32 child number to derive.
+ * :param flags: Flags controlling the type of script to create. Use one of
+ *|    ``WALLY_MINISCRIPT_WITNESS_SCRIPT`` or ``WALLY_MINISCRIPT_TAPSCRIPT``.
+ * :param bytes_out: Destination for the resulting scriptPubkey.
+ * :param len: The length of ``bytes_out`` in bytes.
+ * :param written: Destination for the number of bytes written to ``bytes_out``.
+ */
+WALLY_CORE_API int wally_miniscript_to_script(
+    const char *miniscript,
+    const struct wally_map *vars_in,
+    uint32_t child_num,
+    uint32_t flags,
+    unsigned char *bytes_out,
+    size_t len,
+    size_t *written);
+
+/**
+ * Create a scriptPubKey corresponding to an output descriptor.
+ *
+ * :param descriptor: Output descriptor.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param child_num: The BIP32 child number to derive.
+ * :param network: ``WALLY_NETWORK_`` constant descripting the network to generate for.
+ * :param depth: Number of the descriptor depth. Default is 0.
+ * :param index: Number of the descriptor index. Default is 0.
+ * :param flags: For future use. Must be 0.
+ * :param bytes_out: Destination for the resulting scriptPubkey.
+ * :param len: The length of ``bytes_out`` in bytes.
+ * :param written: Destination for the number of bytes written to ``bytes_out``.
+ */
+WALLY_CORE_API int wally_descriptor_to_scriptpubkey(
+    const char *descriptor,
+    const struct wally_map *vars_in,
+    uint32_t child_num,
+    uint32_t network,
+    uint32_t depth,
+    uint32_t index,
+    uint32_t flags,
+    unsigned char *bytes_out,
+    size_t len,
+    size_t *written);
+
+/**
+ * Create an address corresponding to an output descriptor.
+ *
+ * :param descriptor: Output descriptor.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param child_num: The BIP32 child number to derive.
+ * :param network: ``WALLY_NETWORK_`` constant descripting the network to generate for.
+ * :param flags: For future use. Must be 0.
+ * :param output: Destination for the resulting addresss.
+ *|    The string returned should be freed using `wally_free_string`.
+ */
+WALLY_CORE_API int wally_descriptor_to_address(
+    const char *descriptor,
+    const struct wally_map *vars_in,
+    uint32_t child_num,
+    uint32_t network,
+    uint32_t flags,
+    char **output);
+
+/**
+ * Create addresses that correspond to the derived range of an output descriptor.
+ *
+ * :param descriptor: Output descriptor.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param child_num: The first BIP32 child number to derive.
+ * :param network: ``WALLY_NETWORK_`` constant descripting the network to generate for.
+ * :param flags: For future use. Must be 0.
+ * :param output: Destination for the resulting addresses.
+ * :param num_outputs: The number of items in ``output``. Addresses will be
+ *|    generated into this array starting from child_num, incrementing by 1.
+ *|    The addresses returned should be freed using `wally_free_string`.
+ */
+WALLY_CORE_API int wally_descriptor_to_addresses(
+    const char *descriptor,
+    const struct wally_map *vars_in,
+    uint32_t child_num,
+    uint32_t network,
+    uint32_t flags,
+    char **output,
+    size_t num_outputs);
+
+/**
+ * Create an output descriptor checksum.
+ *
+ * :param descriptor: Output descriptor.
+ * :param vars_in: Map of variable names to values, or NULL.
+ * :param flags: For future use. Must be 0.
+ * :param output: Destination for the resulting descriptor checksum.
+ *|    The string returned should be freed using `wally_free_string`.
+ */
+WALLY_CORE_API int wally_descriptor_get_checksum(
+    const char *descriptor,
+    const struct wally_map *vars_in,
+    uint32_t flags,
+    char **output);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LIBWALLY_CORE_DESCRIPTOR_H */

src/Makefile.am

@@ -14,6 +14,7 @@ include_HEADERS += $(top_srcdir)/include/wally_bip38.h
 include_HEADERS += $(top_srcdir)/include/wally_bip39.h
 include_HEADERS += $(top_srcdir)/include/wally_core.h
 include_HEADERS += $(top_srcdir)/include/wally_crypto.h
+include_HEADERS += $(top_srcdir)/include/wally_descriptor.h
 include_HEADERS += $(top_srcdir)/include/wally_elements.h
 include_HEADERS += $(top_srcdir)/include/wally_map.h
 include_HEADERS += $(top_srcdir)/include/wally_psbt.h
@@ -158,6 +159,7 @@ all: swig_java/wallycore.jar
 
 SWIG_JAVA_TEST_DEPS = \
     $(sjs)/$(cbt)/test_bip32.class \
+    $(sjs)/$(cbt)/test_descriptor.class \
     $(sjs)/$(cbt)/test_tx.class \
     $(sjs)/$(cbt)/test_scripts.class \
     $(sjs)/$(cbt)/test_mnemonic.class
@@ -190,6 +192,7 @@ libwallycore_la_SOURCES = \
     bip38.c \
     bip39.c \
     bech32.c \
+    descriptor.c \
     ecdh.c \
     elements.c \
     blech32.c \
@@ -222,6 +225,7 @@ libwallycore_la_INCLUDES = \
     include/wally_bip39.h \
     include/wally_core.h \
     include/wally_crypto.h \
+    include/wally_descriptor.h \
     include/wally_elements.h \
     include/wally_map.h \
     include/wally_psbt.h \
@@ -288,6 +292,14 @@ test_tx_LDADD = $(lib_LTLIBRARIES) @CTEST_EXTRA_STATIC@
 if PYTHON_MANYLINUX
 test_tx_LDADD += $(PYTHON_LIBS)
 endif
+TESTS += test_descriptor
+noinst_PROGRAMS += test_descriptor
+test_descriptor_SOURCES = ctest/test_descriptor.c
+test_descriptor_CFLAGS = -I$(top_srcdir)/include $(AM_CFLAGS)
+test_descriptor_LDADD = $(lib_LTLIBRARIES) @CTEST_EXTRA_STATIC@
+if PYTHON_MANYLINUX
+test_descriptor_LDADD += $(PYTHON_LIBS)
+endif
 if BUILD_ELEMENTS
 TESTS += test_elements_tx
 noinst_PROGRAMS += test_elements_tx
@@ -314,6 +326,7 @@ check-libwallycore: $(PYTHON_TEST_DEPS)
 	$(AM_V_at)$(PYTHON_TEST) test/test_bip32.py
 	$(AM_V_at)$(PYTHON_TEST) test/test_bip38.py
 	$(AM_V_at)$(PYTHON_TEST) test/test_bip39.py
+	$(AM_V_at)$(PYTHON_TEST) test/test_descriptor.py
 	$(AM_V_at)$(PYTHON_TEST) test/test_ecdh.py
 	$(AM_V_at)$(PYTHON_TEST) test/test_hash.py
 	$(AM_V_at)$(PYTHON_TEST) test/test_hex.py
@@ -340,6 +353,7 @@ endif
 if USE_SWIG_PYTHON
 check-swig-python: $(SWIG_PYTHON_TEST_DEPS)
 	$(AM_V_at)$(PYTHON_SWIGTEST) swig_python/contrib/bip32.py
+	$(AM_V_at)$(PYTHON_SWIGTEST) swig_python/contrib/descriptor.py
 	$(AM_V_at)$(PYTHON_SWIGTEST) swig_python/contrib/mnemonic.py
 	$(AM_V_at)$(PYTHON_SWIGTEST) swig_python/contrib/psbt.py
 	$(AM_V_at)$(PYTHON_SWIGTEST) swig_python/contrib/sha.py
@@ -366,6 +380,7 @@ if BUILD_ELEMENTS
 	$(AM_V_at)$(JAVA_TEST)test_pegs
 endif
 	$(AM_V_at)$(JAVA_TEST)test_bip32
+	$(AM_V_at)$(JAVA_TEST)test_descriptor
 	$(AM_V_at)$(JAVA_TEST)test_mnemonic
 	$(AM_V_at)$(JAVA_TEST)test_scripts
 	$(AM_V_at)$(JAVA_TEST)test_tx

src/address.c

@@ -166,6 +166,7 @@ int wally_scriptpubkey_to_address(const unsigned char *scriptpubkey, size_t scri
         case WALLY_NETWORK_BITCOIN_MAINNET:
             bytes[0] = WALLY_ADDRESS_VERSION_P2PKH_MAINNET;
             break;
+        case WALLY_NETWORK_BITCOIN_REGTEST:
         case WALLY_NETWORK_BITCOIN_TESTNET:
             bytes[0] = WALLY_ADDRESS_VERSION_P2PKH_TESTNET;
             break;
@@ -188,6 +189,7 @@ int wally_scriptpubkey_to_address(const unsigned char *scriptpubkey, size_t scri
         case WALLY_NETWORK_BITCOIN_MAINNET:
             bytes[0] = WALLY_ADDRESS_VERSION_P2SH_MAINNET;
             break;
+        case WALLY_NETWORK_BITCOIN_REGTEST:
         case WALLY_NETWORK_BITCOIN_TESTNET:
             bytes[0] = WALLY_ADDRESS_VERSION_P2SH_TESTNET;
             break;