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 forvars_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:
descriptor – Parsed output descriptor or miniscript expression.
flags – Miniscript/Descriptor canonicalization flags controlling canonicalization.
output – Destination for the resulting canonical descriptor. The string returned should be freed using
wally_free_string
.
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 returnWALLY_NETWORK_NONE
, andwally_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:
descriptor – Parsed output descriptor or miniscript expression.
value_out – Destination for the resulting Miniscript/Descriptor feature flags.
- 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 towally_descriptor_to_script
orwally_descriptor_to_addresses
to generate a script/address corresponding to that variant type.For
combo()
, the variants arep2pk
,p2pkh
,p2wpkh
, andp2sh-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 ofx
,y
, orz
respectively. The index of the multi-path is passed towally_descriptor_to_script
orwally_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.
- 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.
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.- 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:
descriptor – Parsed output descriptor or miniscript expression.
index – The zero-based index of the key to get.
value_out – Destination for the resulting Miniscript/Descriptor feature flags.
- 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 beBIP32_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
andindex
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:
-
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 usingwally_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_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
Miniscript/Descriptor canonicalization flags
-
WALLY_MS_CANONICAL_NO_CHECKSUM
Do not include a checksum