Descriptor Functions

int wally_descriptor_parse(const char *descriptor, const struct wally_map *vars_in, uint32_t network, uint32_t flags, struct wally_descriptor **output)

Parse an output descriptor or miniscript expression.

Parameters:

  • descriptor – Output descriptor or miniscript expression to parse.

  • vars_in – Map of variable names to values, or NULL.

  • network – Network the descriptor belongs to. Pass WALLY_NETWORK_NONE for miniscript-only expressions or to infer the network. Must be one of the Address network constants.

  • flags – Miniscript/Descriptor parsing flags. The maximum depth of the descriptor can be limited by passing the depth in the upper 16 bits of the flags.

  • output – Destination for the resulting parsed descriptor. The descriptor returned should be freed using wally_descriptor_free.

Variable names can be used in the descriptor string and will be substituted with the contents of vars_in during parsing. Key names for vars_in must be 16 characters or less in length and start with a letter.

Returns:

See Error Codes

int wally_descriptor_free(struct wally_descriptor *descriptor)

Free a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression to free.

Returns:

See Error Codes

int wally_descriptor_canonicalize(const struct wally_descriptor *descriptor, uint32_t flags, char **output)

Canonicalize a descriptor.

Parameters:

Note

Other canonicalization (hardened derivation indicator

mapping, and private to public key mapping) is not yet implemented.

Returns:

See Error Codes

int wally_descriptor_get_checksum(const struct wally_descriptor *descriptor, uint32_t flags, char **output)

Create an output descriptor checksum.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • flags – For future use. Must be 0.

  • output – Destination for the resulting descriptor checksum. The string returned should be freed using wally_free_string.

Returns:

See Error Codes

int wally_descriptor_get_network(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the network used in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • value_out – Destination for the resulting network, returned as one of the Address network constants.

A descriptor parsed with WALLY_NETWORK_NONE will infer its network from the contained key expressions. If the descriptor does not contain network information (e.g. its keys are raw keys), then this function will return WALLY_NETWORK_NONE, and wally_descriptor_set_network must be called to set a network for the descriptor before addresses can be generated from it.

Returns:

See Error Codes

int wally_descriptor_set_network(struct wally_descriptor *descriptor, uint32_t network)

set the network for a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • network – Network the descriptor should belong to. One of the Address network constants.

Note

The network can only be set if it is currently WALLY_NETWORK_NONE.

Returns:

See Error Codes

int wally_descriptor_get_features(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the features used in a parsed output descriptor or miniscript expression.

Parameters:
Returns:

See Error Codes

int wally_descriptor_get_num_variants(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the number of variants in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • value_out – Destination for the number of available variants.

Expressions such as combo() can return more than one script/address for a given key or key path. Each available type is represented as a variant numbered from zero. The variant is passed to wally_descriptor_to_script or wally_descriptor_to_addresses to generate a script/address corresponding to that variant type.

For combo(), the variants are p2pk, p2pkh, p2wpkh, and p2sh-p2wpkh in order from 0-3. If the expression’s key is uncompressed, only the first two variants are available.

Returns:

See Error Codes

int wally_descriptor_get_num_paths(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the number of multi-path items in a descriptors path expression(s).

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • value_out – Destination for the number of ranges.

Paths in descriptor key expressions can contain multiple paths in the format <x;y;z>, where each item corresponds to a new path with the given path elements being one of x, y, or z respectively. The index of the multi-path is passed to wally_descriptor_to_script or wally_descriptor_to_addresses to generate a script/address corresponding to the corresponding key path.

Returns:

See Error Codes

int wally_descriptor_get_depth(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the maximum depth of a descriptors parse tree.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • value_out – Destination for the descriptor depth.

This function is intended for use by callers that need to limit the size of descriptors they process (for example, to limit stack usage).

Returns:

See Error Codes

int wally_descriptor_get_num_keys(const struct wally_descriptor *descriptor, uint32_t *value_out)

Get the number of keys in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • value_out – Destination for the number of keys.

Note

Repeated keys are counted once for each time they appear, and any blinding key within the descriptor is not included in the count.

Returns:

See Error Codes

int wally_descriptor_get_key(const struct wally_descriptor *descriptor, size_t index, char **output)

Get the string representation of a key in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key to get, or WALLY_MS_BLINDING_KEY_INDEX to fetch the descriptors blinding key representaton (if any).

  • output – Destination for the resulting string representation. The string returned should be freed using wally_free_string.

Note

Keys may be BIP32 xpub/xpriv, WIF or hex pubkeys, and may be x-only. The caller can use wally_descriptor_get_key_features to determine the type of a given key.

Note

Raw private blinding keys are returned as hex, not WIF.

Returns:

See Error Codes

int wally_descriptor_get_key_features(const struct wally_descriptor *descriptor, size_t index, uint32_t *value_out)

Get the features of a key in a parsed output descriptor or miniscript expression.

Parameters:
Returns:

See Error Codes

int wally_descriptor_get_key_child_path_str_len(const struct wally_descriptor *descriptor, size_t index, size_t *written)

Get the length of a keys child path string in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key whose child path to get.

  • written – Destination for the length of the keys child path string, excluding the NUL terminator (zero if not present).

Returns:

See Error Codes

int wally_descriptor_get_key_child_path_str(const struct wally_descriptor *descriptor, size_t index, char **output)

Get the keys child path string in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key whose child path to get.

  • output – Destination for the resulting path string (empty if not present). The string returned should be freed using wally_free_string.

Returns:

See Error Codes

int wally_descriptor_get_key_origin_fingerprint(const struct wally_descriptor *descriptor, size_t index, unsigned char *bytes_out, size_t len)

Get the keys parent BIP32 fingerprint in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key whose parent fingerprint to get.

  • bytes_out – Destination for the fingerprint.

  • len – Size of bytes_out. Must be BIP32_KEY_FINGERPRINT_LEN.

If the key does not contain key origin information then WALLY_EINVAL is returned.

Returns:

See Error Codes

int wally_descriptor_get_key_origin_path_str_len(const struct wally_descriptor *descriptor, size_t index, size_t *written)

Get the length of a keys parent path string in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key whose parent path to get.

  • written – Destination for the length of the keys parent path string, excluding the NUL terminator (zero if not present).

Returns:

See Error Codes

int wally_descriptor_get_key_origin_path_str(const struct wally_descriptor *descriptor, size_t index, char **output)

Get the keys parent path string in a parsed output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • index – The zero-based index of the key whose parent path to get.

  • output – Destination for the resulting path string (empty if not present). The string returned should be freed using wally_free_string.

Returns:

See Error Codes

int wally_descriptor_to_script_get_maximum_length(const struct wally_descriptor *descriptor, uint32_t depth, uint32_t index, uint32_t variant, uint32_t multi_index, uint32_t child_num, uint32_t flags, size_t *written)

Get the maximum length of a script corresponding to an output descriptor.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • depth – Depth of the expression tree to generate from. Pass 0 to generate from the root.

  • index – The zero-based index of the child at depth depth to generate from.

  • variant – The variant of descriptor to generate. See wally_descriptor_get_num_variants.

  • multi_index – The multi-path item to generate. See wally_descriptor_get_num_paths.

  • child_num – The BIP32 child number to derive, or 0 for static descriptors.

  • flags – For future use. Must be 0.

  • written – Destination for the resulting maximum script length.

Note

This function overestimates the script size required, but is cheap to compute (does not require script generation).

Returns:

See Error Codes

int wally_descriptor_to_script(const struct wally_descriptor *descriptor, uint32_t depth, uint32_t index, uint32_t variant, uint32_t multi_index, uint32_t child_num, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written)

Create a script corresponding to an output descriptor or miniscript expression.

Parameters:

  • descriptor – Parsed output descriptor or miniscript expression.

  • depth – Depth of the expression tree to generate from. Pass 0 to generate from the root.

  • index – The zero-based index of the child at depth depth to generate from.

  • variant – The variant of descriptor to generate. See wally_descriptor_get_num_variants.

  • multi_index – The multi-path item to generate. See wally_descriptor_get_num_paths.

  • child_num – The BIP32 child number to derive, or 0 for static descriptors.

  • flags – For future use. Must be 0.

  • bytes_out – Destination for the resulting scriptPubKey or script.

  • len – The length of bytes_out in bytes.

  • written – Destination for the number of bytes written to bytes_out.

Note

For miniscript expressions, the script generated is untyped bitcoin script. For descriptors, a scriptPubKey is generated.

Note

depth and index can be used to generate sub-scripts from the expression tree. These are expected to be useful once introspection of the expression is improved, e.g. to allow generating the nested script inside sh() or wsh() expressions.

Returns:

See Variable Length Output Buffers

int wally_descriptor_to_address(const struct wally_descriptor *descriptor, uint32_t variant, uint32_t multi_index, uint32_t child_num, uint32_t flags, char **output)

Create an address corresponding to an output descriptor.

Parameters:

  • descriptor – Parsed output descriptor.

  • variant – The variant of descriptor to generate. See wally_descriptor_get_num_variants.

  • multi_index – The multi-path item to generate. See wally_descriptor_get_num_paths.

  • child_num – The BIP32 child number to derive, or zero for static descriptors.

  • flags – For future use. Must be 0.

  • output – Destination for the resulting address. The string returned should be freed using wally_free_string.

Returns:

See Error Codes

int wally_descriptor_to_addresses(const struct wally_descriptor *descriptor, uint32_t variant, uint32_t multi_index, uint32_t child_num, uint32_t flags, char **output, size_t num_outputs)

Create addresses that correspond to the derived range of an output descriptor.

Parameters:

  • descriptor – Parsed output descriptor.

  • variant – The variant of descriptor to generate. See wally_descriptor_get_num_variants.

  • multi_index – The multi-path item to generate. See wally_descriptor_get_num_paths.

  • child_num – The BIP32 child number to derive, or zero for static descriptors.

  • flags – For future use. Must be 0.

  • output – Destination for the resulting addresses.

  • 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.

Returns:

See Error Codes

Descriptor Constants

Miniscript/Descriptor parsing flags

WALLY_MINISCRIPT_TAPSCRIPT

Tapscript, use x-only pubkeys

WALLY_MINISCRIPT_ONLY

Only allow miniscript (not descriptor) expressions

WALLY_MINISCRIPT_REQUIRE_CHECKSUM

Require a checksum to be present

WALLY_MINISCRIPT_POLICY_TEMPLATE

Only allow policy templates with @n BIP32 keys

WALLY_MINISCRIPT_UNIQUE_KEYPATHS

For policy templates, ensure BIP32 derivation paths differ for identical keys

WALLY_MINISCRIPT_AS_ELEMENTS

Treat non-elements expressions as elements, e.g. tr() as eltr()

WALLY_MINISCRIPT_DEPTH_MASK

Mask for limiting maximum depth

WALLY_MINISCRIPT_DEPTH_SHIFT

Shift to convert maximum depth to flags

Miniscript/Descriptor feature flags

WALLY_MS_IS_RANGED

Allows key ranges via *

WALLY_MS_IS_MULTIPATH

Allows multiple paths via <a;b;c>

WALLY_MS_IS_PRIVATE

Contains at least one private key

WALLY_MS_IS_UNCOMPRESSED

Contains at least one uncompressed key

WALLY_MS_IS_RAW

Contains at least one raw key

WALLY_MS_IS_DESCRIPTOR

Contains only descriptor expressions (no miniscript)

WALLY_MS_IS_X_ONLY

Contains at least one x-only key

WALLY_MS_IS_PARENTED

Contains at least one key key with a parent key origin

WALLY_MS_IS_ELEMENTS

Contains Elements expressions or was parsed as Elements

WALLY_MS_IS_SLIP77

A confidential ct() descriptor with SLIP-77 blinding

WALLY_MS_IS_ELIP150

A confidential ct() descriptor with ELIP-150 blinding

WALLY_MS_IS_ELIP151

A confidential ct() descriptor with ELIP-151 blinding

WALLY_MS_ANY_BLINDING_KEY

SLIP-77, ELIP-150 or ELIP-151 blinding key present

Miniscript/Descriptor canonicalization flags

WALLY_MS_CANONICAL_NO_CHECKSUM

Do not include a checksum

WALLY_MS_BLINDING_KEY_INDEX