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_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: 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 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_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)