descriptor: allow fetching key origin info from keys

Author: jgriffiths

include/wally.hpp

@@ -528,6 +528,24 @@ inline int descriptor_get_key_features(const DESCRIPTOR& descriptor, size_t inde
     return ret;
 }
 
+template <class DESCRIPTOR, class BYTES_OUT>
+inline int descriptor_get_key_origin_fingerprint(const DESCRIPTOR& descriptor, size_t index, BYTES_OUT& bytes_out) {
+    int ret = ::wally_descriptor_get_key_origin_fingerprint(detail::get_p(descriptor), index, bytes_out.data(), bytes_out.size());
+    return ret;
+}
+
+template <class DESCRIPTOR>
+inline int descriptor_get_key_origin_path_str(const DESCRIPTOR& descriptor, size_t index, char** output) {
+    int ret = ::wally_descriptor_get_key_origin_path_str(detail::get_p(descriptor), index, output);
+    return ret;
+}
+
+template <class DESCRIPTOR>
+inline int descriptor_get_key_origin_path_str_len(const DESCRIPTOR& descriptor, size_t index, size_t* written) {
+    int ret = ::wally_descriptor_get_key_origin_path_str_len(detail::get_p(descriptor), index, written);
+    return ret;
+}
+
 template <class DESCRIPTOR>
 inline int descriptor_get_network(const DESCRIPTOR& descriptor, uint32_t* value_out) {
     int ret = ::wally_descriptor_get_network(detail::get_p(descriptor), value_out);

include/wally_descriptor.h

@@ -28,6 +28,7 @@ struct wally_descriptor;
 #define WALLY_MS_IS_RAW          0x10 /** Contains at least one raw key */
 #define WALLY_MS_IS_DESCRIPTOR   0x20 /** Contains only descriptor expressions (no miniscript) */
 #define WALLY_MS_IS_X_ONLY       0x40 /** Contains at least one x-only key */
+#define WALLY_MS_IS_PARENTED     0x80 /** Contains at least one key key with a parent key origin */
 
 /*** ms-canonicalization-flags Miniscript/Descriptor canonicalization flags */
 #define WALLY_MS_CANONICAL_NO_CHECKSUM 0x01 /** Do not include a checksum */
@@ -230,7 +231,7 @@ WALLY_CORE_API int wally_descriptor_get_key_features(
  * :param descriptor: Parsed output descriptor or miniscript expression.
  * :param index: The zero-based index of the key whose child path to get.
  * :param written: Destination for the length of the keys child path string,
- *|    excluding the NUL terminator.
+ *|    excluding the NUL terminator (zero if not present).
  */
 WALLY_CORE_API int wally_descriptor_get_key_child_path_str_len(
     const struct wally_descriptor *descriptor,
@@ -242,14 +243,55 @@ WALLY_CORE_API int wally_descriptor_get_key_child_path_str_len(
  *
  * :param descriptor: Parsed output descriptor or miniscript expression.
  * :param index: The zero-based index of the key whose child path to get.
- * :param output: Destination for the resulting path string (may be empty).
+ * :param output: Destination for the resulting path string (empty if not present).
  *|    The string returned should be freed using `wally_free_string`.
  */
 WALLY_CORE_API int wally_descriptor_get_key_child_path_str(
     const struct wally_descriptor *descriptor,
     size_t index,
     char **output);
 
+/**
+ * Get the keys parent BIP32 fingerprint in a parsed output descriptor or miniscript expression.
+ *
+ * :param descriptor: Parsed output descriptor or miniscript expression.
+ * :param index: The zero-based index of the key whose parent fingerprint to get.
+ * :param bytes_out: Destination for the fingerprint.
+ * FIXED_SIZED_OUTPUT(len, bytes_out, BIP32_KEY_FINGERPRINT_LEN)
+ *
+ * If the key does not contain key origin information then `WALLY_EINVAL is returned.
+ */
+WALLY_CORE_API int wally_descriptor_get_key_origin_fingerprint(
+    const struct wally_descriptor *descriptor,
+    size_t index,
+    unsigned char *bytes_out,
+    size_t len);
+
+/**
+ * Get the length of a keys parent path string in a parsed output descriptor or miniscript expression.
+ *
+ * :param descriptor: Parsed output descriptor or miniscript expression.
+ * :param index: The zero-based index of the key whose parent path to get.
+ * :param written: Destination for the length of the keys parent path string,
+ *|    excluding the NUL terminator (zero if not present).
+ */
+WALLY_CORE_API int wally_descriptor_get_key_origin_path_str_len(
+    const struct wally_descriptor *descriptor,
+    size_t index,
+    size_t *written);
+
+/**
+ * Get the keys parent path string in a parsed output descriptor or miniscript expression.
+ *
+ * :param descriptor: Parsed output descriptor or miniscript expression.
+ * :param index: The zero-based index of the key whose parent path to get.
+ * :param output: Destination for the resulting path string (empty if not present).
+ *|    The string returned should be freed using `wally_free_string`.
+ */
+WALLY_CORE_API int wally_descriptor_get_key_origin_path_str(
+    const struct wally_descriptor *descriptor,
+    size_t index,
+    char **output);
 
 /**
  * Get the maximum length of a script corresponding to an output descriptor.

src/descriptor.c

@@ -2085,7 +2085,12 @@ static int analyze_miniscript_key(ms_ctx *ctx, uint32_t flags,
             (node->data[9] != ']' && node->data[9] != '/'))
             return WALLY_EINVAL; /* Invalid key origin fingerprint */
         size = end - node->data + 1;
-        /* cut parent path */
+        /* Store offset and length of any origin info in the number field */
+        node->number = (size_t)(node->data - ctx->src) << 32u;
+        node->number |= size;
+        ctx->features |= WALLY_MS_IS_PARENTED;
+        node->flags |= WALLY_MS_IS_PARENTED;
+        /* Remove the key origin info from the key data */
         node->data = end + 1;
         node->data_len -= size;
     }
@@ -2980,6 +2985,57 @@ int wally_descriptor_get_key_child_path_str(
     return WALLY_OK;
 }
 
+int wally_descriptor_get_key_origin_fingerprint(
+    const struct wally_descriptor *descriptor, size_t index,
+    unsigned char *bytes_out, size_t len)
+{
+    const ms_node *node = descriptor_get_key(descriptor, index);
+    const char *fingerprint;
+    size_t written;
+    int ret;
+
+    if (!node || !bytes_out || len != BIP32_KEY_FINGERPRINT_LEN ||
+        !(node->flags & WALLY_MS_IS_PARENTED))
+        return WALLY_EINVAL;
+    fingerprint = descriptor->src + (((size_t)node->number) >> 32u) + 1;
+    ret = wally_hex_n_to_bytes(fingerprint, BIP32_KEY_FINGERPRINT_LEN * 2,
+                               bytes_out, len, &written);
+    return ret == WALLY_OK && written != BIP32_KEY_FINGERPRINT_LEN ? WALLY_EINVAL : ret;
+}
+
+int wally_descriptor_get_key_origin_path_str_len(
+    const struct wally_descriptor *descriptor, size_t index, size_t *written)
+{
+    const ms_node *node = descriptor_get_key(descriptor, index);
+
+    if (written)
+        *written = 0;
+    if (!node || !written)
+        return WALLY_EINVAL;
+    *written = node->flags & WALLY_MS_IS_PARENTED ? node->number & 0xffffffff : 0;
+    *written = *written < 11u ? 0 : *written - 11u;
+    return WALLY_OK;
+}
+
+int wally_descriptor_get_key_origin_path_str(
+    const struct wally_descriptor *descriptor, size_t index, char **output)
+{
+    const ms_node *node = descriptor_get_key(descriptor, index);
+    const char *path;
+    size_t path_len;
+
+    if (output)
+        *output = NULL;
+    if (!node || !output)
+        return WALLY_EINVAL;
+    path_len = node->flags & WALLY_MS_IS_PARENTED ? node->number & 0xffffffff : 0;
+    path_len = path_len < 11u ? 0 : path_len - 11u;
+    path = descriptor->src + (((size_t)node->number) >> 32u) + 10u;
+    if (!(*output = wally_strdup_n(path, path_len)))
+        return WALLY_ENOMEM;
+    return WALLY_OK;
+}
+
 static const char *get_multipath_child(const char* p, uint32_t *v)
 {
     *v = 0;

src/swig_java/swig.i

@@ -565,6 +565,9 @@ static jobjectArray create_jstringArray(JNIEnv *jenv, char **p, size_t len) {
 %returns_string(wally_descriptor_get_key_child_path_str);
 %returns_size_t(wally_descriptor_get_key_child_path_str_len);
 %returns_size_t(wally_descriptor_get_key_features);
+%returns_array_(wally_descriptor_get_key_origin_fingerprint, 3, 4, BIP32_KEY_FINGERPRINT_LEN);
+%returns_string(wally_descriptor_get_key_origin_path_str);
+%returns_size_t(wally_descriptor_get_key_origin_path_str_len);
 %returns_size_t(wally_descriptor_get_num_keys);
 %returns_size_t(wally_descriptor_get_num_paths);
 %returns_size_t(wally_descriptor_get_num_variants);

src/swig_python/python_extra.py_in

@@ -150,6 +150,7 @@ bip38_to_private_key = _wrap_bin(bip38_to_private_key, EC_PRIVATE_KEY_LEN)
 bip39_mnemonic_to_bytes = _wrap_bin(bip39_mnemonic_to_bytes, BIP39_ENTROPY_MAX_LEN, resize=True)
 bip39_mnemonic_to_seed512 = _wrap_bin(bip39_mnemonic_to_seed512, BIP39_SEED_LEN_512)
 bip85_get_bip39_entropy = _wrap_bin(bip85_get_bip39_entropy, HMAC_SHA512_LEN, resize=True)
+descriptor_get_key_origin_fingerprint = _wrap_bin(descriptor_get_key_origin_fingerprint, BIP32_KEY_FINGERPRINT_LEN)
 descriptor_to_script = _wrap_bin(descriptor_to_script, descriptor_to_script_get_maximum_length, resize=True)
 ec_private_key_bip341_tweak = _wrap_bin(ec_private_key_bip341_tweak, EC_PRIVATE_KEY_LEN)
 ec_public_key_bip341_tweak = _wrap_bin(ec_public_key_bip341_tweak, EC_PUBLIC_KEY_LEN)

src/test/test_descriptor.py

@@ -16,12 +16,14 @@
 POLICY           = 0x08 # WALLY_MINISCRIPT_POLICY_TEMPLATE
 UNIQUE_KEYPATHS  = 0x10 # WALLY_MINISCRIPT_UNIQUE_KEYPATHS
 
-MS_IS_RANGED = 0x1
-MS_IS_MULTIPATH = 0x2
-MS_IS_PRIVATE = 0x4
+MS_IS_RANGED       = 0x1
+MS_IS_MULTIPATH    = 0x2
+MS_IS_PRIVATE      = 0x4
 MS_IS_UNCOMPRESSED = 0x08
-MS_IS_RAW = 0x010
-MS_IS_DESCRIPTOR = 0x20
+MS_IS_RAW          = 0x010
+MS_IS_DESCRIPTOR   = 0x20
+MS_IS_X_ONLY       = 0x40
+MS_IS_PARENTED     = 0x80
 
 NO_CHECKSUM = 0x1 # WALLY_MS_CANONICAL_NO_CHECKSUM
 
@@ -326,12 +328,16 @@ def make_keys(xpubs):
 
     def test_key_iteration(self):
         """Test iterating descriptor keys"""
+        origin_fp = 'd34db33f'
+        origin_path = "44'/0'/0'"
+        origin = f'[{origin_fp}/{origin_path}]'
         k1 = 'xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB'
         k2 = 'xprvA2YKGLieCs6cWCiczALiH1jzk3VCCS5M1pGQfWPkamCdR9UpBgE2Gb8AKAyVjKHkz8v37avcfRjdcnP19dVAmZrvZQfvTcXXSAiFNQ6tTtU'
         wif = 'L1AAHuEC7XuDM7pJ7yHLEqYK1QspMo8n1kgxyZVdgvEpVC1rkUrM'
         pk = '03b428da420cd337c7208ed42c5331ebb407bb59ffbe3dc27936a227c619804284'
         pk_u = '0414fc03b8df87cd7b872996810db8458d61da8448e531569c8517b469a119d267be5645686309c6e6736dbd93940707cc9143d3cf29f1b877ff340e2cb2d259cf'
         policy_keys = wally_map_from_dict({f'@{i}': xpub for i,xpub in enumerate([k1])})
+        policy_keys_with_origins = wally_map_from_dict({f'@{i}': f'{origin}{xpub}' for i,xpub in enumerate([k1])})
         P = POLICY
 
         # Valid args
@@ -355,20 +361,43 @@ def test_key_iteration(self):
             (0, f'pk({pk_u})',        pk_u, '',        MS_IS_RAW|MS_IS_UNCOMPRESSED),
         ]:
             d = c_void_p()
-            keys = policy_keys if flags & P else None
-            ret = wally_descriptor_parse(descriptor, keys, NETWORK_BTC_MAIN, flags, d)
-            self.assertEqual(ret, WALLY_OK)
-            ret, num_keys = wally_descriptor_get_num_keys(d)
-            self.assertEqual((ret, num_keys), (WALLY_OK, 1))
-            ret, key_str = wally_descriptor_get_key(d, 0)
-            self.assertEqual((ret, key_str), (WALLY_OK, expected))
-            ret, path_len = wally_descriptor_get_key_child_path_str_len(d, 0)
-            self.assertEqual((ret, path_len), (WALLY_OK, len(child_path)))
-            ret, path_str = wally_descriptor_get_key_child_path_str(d, 0)
-            self.assertEqual((ret, path_str), (WALLY_OK, child_path))
-            ret, features = wally_descriptor_get_key_features(d, 0)
-            self.assertEqual((ret, features), (WALLY_OK, expected_features))
-            wally_descriptor_free(d)
+            buf, buf_len = make_cbuffer('0' * 8)
+
+            for with_origin in [False, True] if expected == k1 else [False]:
+                keys = None
+                if flags & P:
+                    keys = policy_keys_with_origins if with_origin else policy_keys
+                elif with_origin:
+                    continue
+                ret = wally_descriptor_parse(descriptor, keys, NETWORK_BTC_MAIN, flags, d)
+                self.assertEqual(ret, WALLY_OK)
+                ret, num_keys = wally_descriptor_get_num_keys(d)
+                self.assertEqual((ret, num_keys), (WALLY_OK, 1))
+                ret, key_str = wally_descriptor_get_key(d, 0)
+                self.assertEqual((ret, key_str), (WALLY_OK, expected))
+                ret, path_len = wally_descriptor_get_key_child_path_str_len(d, 0)
+                self.assertEqual((ret, path_len), (WALLY_OK, len(child_path)))
+                ret, path_str = wally_descriptor_get_key_child_path_str(d, 0)
+                self.assertEqual((ret, path_str), (WALLY_OK, child_path))
+                ret, features = wally_descriptor_get_key_features(d, 0)
+                if with_origin:
+                    expected_features |= MS_IS_PARENTED
+                self.assertEqual((ret, features), (WALLY_OK, expected_features))
+                ret = wally_descriptor_get_key_origin_fingerprint(d, 0, buf, buf_len)
+                # Ensure the key origin matches if present
+                if with_origin:
+                    self.assertEqual(ret, WALLY_OK)
+                    ret, fp = wally_hex_from_bytes(buf, buf_len)
+                    self.assertEqual((ret, fp), (WALLY_OK, origin_fp))
+                else:
+                    self.assertEqual(ret, WALLY_EINVAL)
+                ret, path_len = wally_descriptor_get_key_origin_path_str_len(d, 0)
+                expected_len = len(origin_path) if with_origin else 0
+                self.assertEqual((ret, path_len), (WALLY_OK, expected_len))
+                ret, path_str = wally_descriptor_get_key_origin_path_str(d, 0)
+                expected_path = origin_path if with_origin else ''
+                self.assertEqual((ret, path_str), (WALLY_OK, expected_path))
+                wally_descriptor_free(d)
 
 
 if __name__ == '__main__':

src/test/util.py

@@ -317,6 +317,9 @@ class wally_psbt(Structure):
     ('wally_descriptor_get_key_child_path_str', c_int, [c_void_p, c_size_t, c_char_p_p]),
     ('wally_descriptor_get_key_child_path_str_len', c_int, [c_void_p, c_size_t, c_size_t_p]),
     ('wally_descriptor_get_key_features', c_int, [c_void_p, c_size_t, c_uint32_p]),
+    ('wally_descriptor_get_key_origin_fingerprint', c_int, [c_void_p, c_size_t, c_void_p, c_size_t]),
+    ('wally_descriptor_get_key_origin_path_str', c_int, [c_void_p, c_size_t, c_char_p_p]),
+    ('wally_descriptor_get_key_origin_path_str_len', c_int, [c_void_p, c_size_t, c_size_t_p]),
     ('wally_descriptor_get_network', c_int, [c_void_p, c_uint32_p]),
     ('wally_descriptor_get_num_keys', c_int, [c_void_p, c_uint32_p]),
     ('wally_descriptor_get_num_paths', c_int, [c_void_p, c_uint32_p]),

src/wasm_package/src/const.js

@@ -128,6 +128,7 @@ export const WALLY_MINISCRIPT_UNIQUE_KEYPATHS = 0x10; /** For policy templates,
 export const WALLY_MS_CANONICAL_NO_CHECKSUM = 0x01; /** Do not include a checksum */
 export const WALLY_MS_IS_DESCRIPTOR = 0x20; /** Contains only descriptor expressions (no miniscript) */
 export const WALLY_MS_IS_MULTIPATH = 0x02; /** Allows multiple paths via ``<a;b;c>`` */
+export const WALLY_MS_IS_PARENTED = 0x80; /** Contains at least one key key with a parent key origin */
 export const WALLY_MS_IS_PRIVATE = 0x04; /** Contains at least one private key */
 export const WALLY_MS_IS_RANGED = 0x01; /** Allows key ranges via ``*`` */
 export const WALLY_MS_IS_RAW = 0x10; /** Contains at least one raw key */

src/wasm_package/src/functions.js

@@ -126,6 +126,8 @@ export function descriptor_get_features(descriptor: Ref_wally_descriptor): numbe
 export function descriptor_get_key(descriptor: Ref_wally_descriptor, index: number): string;
 export function descriptor_get_key_child_path_str_len(descriptor: Ref_wally_descriptor, index: number): number;
 export function descriptor_get_key_features(descriptor: Ref_wally_descriptor, index: number): number;
+export function descriptor_get_key_origin_fingerprint(descriptor: Ref_wally_descriptor, index: number): Buffer;
+export function descriptor_get_key_origin_path_str_len(descriptor: Ref_wally_descriptor, index: number): number;
 export function descriptor_get_network(descriptor: Ref_wally_descriptor): number;
 export function descriptor_get_num_keys(descriptor: Ref_wally_descriptor): number;
 export function descriptor_get_num_paths(descriptor: Ref_wally_descriptor): number;
@@ -728,6 +730,7 @@ export function base58_n_to_bytes(str_in: string, str_len: number, flags: number
 export function base58_to_bytes(str_in: string, flags: number): Buffer;
 export function base64_to_bytes(str_in: string, flags: number): Buffer;
 export function descriptor_get_key_child_path_str(descriptor: Ref_wally_descriptor, index: number): string;
+export function descriptor_get_key_origin_path_str(descriptor: Ref_wally_descriptor, index: number): string;
 export function descriptor_to_script(descriptor: Ref_wally_descriptor, depth: number, index: number, variant: number, multi_index: number, child_num: number, flags: number): Buffer;
 export function ec_sig_from_bytes(priv_key: Buffer|Uint8Array, bytes: Buffer|Uint8Array, flags: number): Buffer;
 export function ec_sig_from_bytes_aux(priv_key: Buffer|Uint8Array, bytes: Buffer|Uint8Array, aux_rand: Buffer|Uint8Array, flags: number): Buffer;