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_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 addresss. 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_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)

Miniscript/Descriptor canonicalization flags

WALLY_MS_CANONICAL_NO_CHECKSUM

Do not include a checksum