Map Functions

int wally_map_init(size_t allocation_len, wally_map_verify_fn_t verify_fn, struct wally_map *output)

Initialize a new map.

Parameters:

• allocation_len – The number of items to allocate space for.

• verify_fn – A function to verify items before storing, or NULL.

• output – Map to initialize.

Returns:

See Error Codes

int wally_map_init_alloc(size_t allocation_len, wally_map_verify_fn_t verify_fn, struct wally_map **output)

Allocate and initialize a new map.

Parameters:

• allocation_len – The number of items to allocate space for.

• verify_fn – A function to verify items before storing, or NULL.

• output – Destination for the new map.

Returns:

See Error Codes

int wally_map_free(struct wally_map *map_in)

Free a map allocated by wally_map_init_alloc.

Parameters:

• map_in – The map to free.

Returns:

See Error Codes

int wally_map_clear(struct wally_map *map_in)

Remove all entries from a map.

Parameters:

• map_in – The map to clear.

Note

This function frees all pre-allocated memory, and thus can be used to free a map initialised with wally_map_init without freeing the map struct itself.

Returns:

See Error Codes

int wally_map_add(struct wally_map *map_in, const unsigned char *key, size_t key_len, const unsigned char *value, size_t value_len)

Add an item to a map.

Parameters:

• map_in – The map to add to.

• key – The key to add.

• key_len – Length of key in bytes.

• value – The value to add.

• value_len – Length of value in bytes.

Note

If the key given is already in the map, this call succeeds without altering the map.

Returns:

See Error Codes

int wally_map_add_integer(struct wally_map *map_in, uint32_t key, const unsigned char *value, size_t value_len)

Add an item to a map keyed by an integer.

As per wally_map_add, using an integer key.

Returns:

See Error Codes

int wally_map_replace(struct wally_map *map_in, const unsigned char *key, size_t key_len, const unsigned char *value, size_t value_len)

Add an item to a map, replacing it if already present.

See wally_map_add.

Returns:

See Error Codes

int wally_map_replace_integer(struct wally_map *map_in, uint32_t key, const unsigned char *value, size_t value_len)

Add an item to a map keyed by an integer, replacing it if already present.

See wally_map_add_integer.

Returns:

See Error Codes

int wally_map_remove(struct wally_map *map_in, const unsigned char *key, size_t key_len)

Remove an item from a map.

Parameters:

• map_in – The map to remove from.

• key – The key to add.

• key_len – Length of key in bytes.

Returns:

See Error Codes

int wally_map_remove_integer(struct wally_map *map_in, uint32_t key)

Remove an item from a map keyed by an integer.

See wally_map_remove_integer.

Returns:

See Error Codes

int wally_map_find_from(const struct wally_map *map_in, size_t index, const unsigned char *key, size_t key_len, size_t *written)

Find an item in a map from a given position onwards.

Parameters:

• map_in – The map to find key in.

• index – The zero-based index of the item to start searching from.

• key – The key to find.

• key_len – Length of key in bytes.

• written – On success, set to zero if the item is not found, otherwise the index of the item plus one.

Returns:

See Error Codes

int wally_map_find(const struct wally_map *map_in, const unsigned char *key, size_t key_len, size_t *written)

Find an item in a map.

Parameters:

• map_in – The map to find key in.

• key – The key to find.

• key_len – Length of key in bytes.

• written – On success, set to zero if the item is not found, otherwise the index of the item plus one.

Returns:

See Error Codes

int wally_map_find_integer(const struct wally_map *map_in, uint32_t key, size_t *written)

Find an item in a map keyed by an integer.

As per wally_map_find, using an integer key.

Returns:

See Error Codes

const struct wally_map_item *wally_map_get(const struct wally_map *map_in, const unsigned char *key, size_t key_len)

Find an item in a map.

Parameters:

• map_in – The map to find key in.

• key – The key to find.

• key_len – Length of key in bytes.

Note

This is a non-standard call for low-level use. It returns the map item directly without copying, or NULL if not found/an error occurs.

const struct wally_map_item *wally_map_get_integer(const struct wally_map *map_in, uint32_t key)

Find an item in a map keyed by an integer.

As per wally_map_get, using an integer key.

int wally_map_get_num_items(const struct wally_map *map_in, size_t *written)

Get the number of key/value items in a map.

Parameters:

• map_in – The map to return the number of items from.

• written – Destination for the number of items.

Returns:

See Error Codes

int wally_map_get_item_key_length(const struct wally_map *map_in, size_t index, size_t *written)

Get the length of an items key in a map.

Parameters:

• map_in – The map to return the items key length from.

• index – The zero-based index of the item whose key length to return.

• written – Destination for the length of the items key in bytes.

Note

Returns 0 if the items key is an integer.

Returns:

See Error Codes

int wally_map_get_item_key(const struct wally_map *map_in, size_t index, unsigned char *bytes_out, size_t len, size_t *written)

Return an items key from a map.

Parameters:

• map_in – The map to return the items key from.

• index – The zero-based index of the item whose key to return.

• bytes_out – Destination for the resulting data.

• len – The length of bytes_out in bytes.

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

Note

Returns WALLY_ERROR if the items key is an integer.

Returns:

See Variable Length Output Buffers

int wally_map_get_item_integer_key(const struct wally_map *map_in, size_t index, size_t *written)

Return an items integer key from a map.

Parameters:

• map_in – The map to return the items key from.

• index – The zero-based index of the item whose key to return.

• written – Destination for the items integer key.

Note

Returns WALLY_ERROR if the items key is not an integer.

Returns:

See Error Codes

int wally_map_get_item_length(const struct wally_map *map_in, size_t index, size_t *written)

Get the length of an item in a map.

Parameters:

• map_in – The map to return the item length from.

• index – The zero-based index of the item whose length to return.

• written – Destination for the length of the item in bytes.

Returns:

See Error Codes

int wally_map_get_item(const struct wally_map *map_in, size_t index, unsigned char *bytes_out, size_t len, size_t *written)

Return an item from a map.

Parameters:

• map_in – The map to return the item from.

• index – The zero-based index of the item to return.

• bytes_out – Destination for the resulting data.

• len – The length of bytes_out in bytes.

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

Returns:

See Variable Length Output Buffers

int wally_map_sort(struct wally_map *map_in, uint32_t flags)

Sort the items in a map.

Parameters:

• map_in – The map to sort.

• flags – Flags controlling sorting. Must be 0.

Returns:

See Error Codes

int wally_map_combine(struct wally_map *map_in, const struct wally_map *source)

Combine the items from a source map into another map.

Parameters:

• map_in – the destination to combine into.

• source – the source to copy items from.

Note

If this call fails, map_in may be left partially updated.

Returns:

See Error Codes

int wally_map_assign(struct wally_map *map_in, const struct wally_map *source)

Replace a maps contents with another map.

Parameters:

• map_in – the destination to assign to.

• source – the source to copy items from.

Note

If this call fails, map_in is left untouched.

Returns:

See Error Codes

int wally_map_find_bip32_public_key_from(const struct wally_map *map_in, size_t index, const struct ext_key *hdkey, size_t *written)

Find an item in a public-key keyed map given a BIP32 derived key.

Parameters:

• map_in – The map to find the public key of hdkey in.

• index – The zero-based index of the item to start searching from.

• hdkey – The BIP32 key to find.

• written – On success, set to zero if the item is not found, otherwise the index of the item plus one.

Note

This function searches for the compressed, x-only and then uncompressed public keys, in order. The caller can determine which by checking the length of the map item when an item is found.

Returns:

See Error Codes

int wally_map_keypath_get_bip32_key_from(const struct wally_map *map_in, size_t index, const struct ext_key *hdkey, struct ext_key *output, size_t *written)

Return a BIP32 derived private key matching the keypath of a parent in a map.

Parameters:

• map_in – The map to search for derived keys of hdkey in.

• index – The zero-based index of the item to start searching from.

• hdkey – The BIP32 parent private key to derive matches from.

• output – Destination for the resulting derived key. If a matching key is not found, output is zeroed.

• written – On success, set to zero if a matching derived key is not found, otherwise the index of the matching key plus one.

Note

This function searches for keys in the map that are children of hdkey. If one is found, the corresponding private extended key is derived from hdey into output and written is set to the index of the matching key plus one. If no key is found, *output is set to NULL and WALLY_OK is returned.

Returns:

See Error Codes

int wally_map_keypath_get_bip32_public_key_from(const struct wally_map *map_in, size_t index, const struct ext_key *hdkey, struct ext_key *output, size_t *written)

Return a BIP32 derived public key matching the keypath of a parent in a map.

Parameters:

• map_in – The map to search for derived keys of hdkey in.

• index – The zero-based index of the item to start searching from.

• hdkey – The BIP32 parent private key to derive matches from.

• output – Destination for the resulting derived key. If a matching key is not found, output is zeroed.

• written – On success, set to zero if a matching derived key is not found, otherwise the index of the matching key plus one.

Note

The public key equivalent of wally_map_keypath_get_bip32_key_from, however note that it requires a private extended key if the child path may contain hardend child indices.

Returns:

See Error Codes

int wally_map_keypath_get_bip32_key_from_alloc(const struct wally_map *map_in, size_t index, const struct ext_key *hdkey, struct ext_key **output)

Return a BIP32 derived key matching the keypath of a parent in a map.

Parameters:

• map_in – The map to search for derived keys of hdkey in.

• index – The zero-based index of the item to start searching from.

• hdkey – The BIP32 parent key to derive matches from.

• output – Destination for the resulting derived key, if any.

Note

This function searches for keys in the map that are children of hdkey. If one is found, the corresponding privately derived key is returned. If no key is found, *output is set to NULL and WALLY_OK is returned.

Returns:

See Error Codes

int wally_keypath_bip32_verify(const unsigned char *key, size_t key_len, const unsigned char *val, size_t val_len)

Verify a PSBT keypath keyed by a serialized bip32 extended public key.

Parameters:

• key – An extended public key in bip32 format.

• key_len – Length of key in bytes. Must be BIP32_SERIALIZED_LEN.

• val – The 4 byte PSBT serialized master key fingerprint followed by the serialized path.

• val_len – Length of val in bytes.

Returns:

See Error Codes

int wally_keypath_public_key_verify(const unsigned char *key, size_t key_len, const unsigned char *val, size_t val_len)

Verify a PSBT keypath keyed by a compressed or uncompressed public key.

Parameters:

• key – Public key bytes.

• key_len – Length of key in bytes. Must be EC_PUBLIC_KEY_UNCOMPRESSED_LEN or BIP32_SERIALIZED_LEN.

• val – The 4 byte PSBT serialized master key fingerprint followed by the serialized path.

• val_len – Length of val in bytes.

Returns:

See Error Codes

int wally_keypath_xonly_public_key_verify(const unsigned char *key, size_t key_len, const unsigned char *val, size_t val_len)

Verify a PSBT keypath keyed by an x-only public key.

Parameters:

• key – Public key bytes.

• key_len – Length of key in bytes. Must be EC_XONLY_PUBLIC_KEY_LEN,

• val – The 4 byte PSBT serialized master key fingerprint followed by the serialized path.

• val_len – Length of val in bytes.

Returns:

See Error Codes

int wally_merkle_path_xonly_public_key_verify(const unsigned char *key, size_t key_len, const unsigned char *val, size_t val_len)

Verify a merkle path keyed by an x-only public key.

Parameters:

• key – Public key bytes.

• key_len – Length of key in bytes. Must be EC_XONLY_PUBLIC_KEY_LEN.

• val – The PSBT merkle path.

• val_len – Length of val in bytes. Must be a multiple of SHA256_LEN.

Returns:

See Error Codes

int wally_bip341_control_block_verify(const unsigned char *bytes, size_t bytes_len)

Verify a taproot control block as specified in BIP-0341.

Parameters:

• bytes – Control block bytes.

• bytes_len – Length of bytes in bytes. Must be at least EC_XONLY_PUBLIC_KEY_LEN + 1.

Returns:

See Error Codes

int wally_map_keypath_bip32_init_alloc(size_t allocation_len, struct wally_map **output)

Allocate and initialize a new BIP32 keypath map.

Parameters:

• allocation_len – The number of items to allocate space for.

• output – Destination for the new map.

Returns:

See Error Codes

int wally_map_keypath_public_key_init_alloc(size_t allocation_len, struct wally_map **output)

Allocate and initialize a new public key keypath map.

Parameters:

• allocation_len – The number of items to allocate space for.

• output – Destination for the new map.

Returns:

See Error Codes

int wally_map_keypath_add(struct wally_map *map_in, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *fingerprint, size_t fingerprint_len, const uint32_t *child_path, size_t child_path_len)

Convert and add a public key and path to a keypath map.

Parameters:

• map_in – The keypath map to add to.

• pub_key – The public key or extended public key to add.

• pub_key_len – Length of pub_key in bytes. Must be BIP32_SERIALIZED_LEN for an extended bip32 public key, EC_PUBLIC_KEY_UNCOMPRESSED_LEN, EC_PUBLIC_KEY_LEN, or EC_XONLY_PUBLIC_KEY_LEN for a public key.

• fingerprint – The master key fingerprint for the pubkey.

• fingerprint_len – Length of fingerprint in bytes. Must be BIP32_KEY_FINGERPRINT_LEN.

• child_path – The BIP32 derivation path for the pubkey.

• child_path_len – The number of items in child_path.

Returns:

See Error Codes

int wally_map_merkle_path_add(struct wally_map *map_in, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *merkle_hashes, size_t merkle_hashes_len)

Convert and add a public key and merkle path to a map.

Parameters:

• map_in – The map to add to.

• pub_key – The public key or extended public key to add.

• pub_key_len – Length of pub_key in bytes. Must be EC_XONLY_PUBLIC_KEY_LEN bytes.

• merkle_hashes – Series of 32-byte leaf hashes. Must be NULL if merkle_hashes_len is 0.

• merkle_hashes_len – Length of merkle_hashes in bytes. Must be a multiple of SHA256_LEN.

Returns:

See Error Codes

int wally_keypath_get_fingerprint(const unsigned char *val, size_t val_len, unsigned char *bytes_out, size_t len)

Get the key fingerprint from a PSBT keypath’s serialized value.

Parameters:

• val – The serialized keypath value as stored in a keypath map.

• val_len – Length of val in bytes.

• bytes_out – Destination for the fingerprint.

• len – Size of bytes_out. Must be BIP32_KEY_FINGERPRINT_LEN.

Returns:

See Error Codes

int wally_map_keypath_get_item_fingerprint(const struct wally_map *map_in, size_t index, unsigned char *bytes_out, size_t len)

Return an item’s key fingerprint from a keypath map.

Parameters:

• map_in – The map to return the item’s fingerprint from.

• index – The zero-based index of the item whose key fingerprint to return.

• bytes_out – Destination for the resulting data.

• len – Size of bytes_out. Must be BIP32_KEY_FINGERPRINT_LEN.

Note

The same key fingerprint may be present in a keypath map more than once.

Returns:

See Error Codes

int wally_keypath_get_path_len(const unsigned char *val, size_t val_len, size_t *written)

Get the path length from a PSBT keypath’s serialized value.

Parameters:

• val – The serialized keypath value as stored in a keypath map.

• val_len – Length of val in bytes.

• written – Destination for the items path length.

Returns:

See Error Codes

int wally_map_keypath_get_item_path_len(const struct wally_map *map_in, size_t index, size_t *written)

Get the length of an item’s key path from a keypath map.

Parameters:

• map_in – The map to return the item’s path length from.

• index – The zero-based index of the item whose path length to return.

• written – Destination for the items path length.

Returns:

See Error Codes

int wally_keypath_get_path(const unsigned char *val, size_t val_len, uint32_t *child_path_out, size_t child_path_out_len, size_t *written)

Get the path from a PSBT keypath’s serialized value.

Parameters:

• val – The serialized keypath value as stored in a keypath map.

• val_len – Length of val in bytes.

• child_path_out – Destination for the resulting path.

• child_path_out_len – The number of items in child_path_out.

• written – Destination for the number of items written to child_path_out.

Note

If the path is longer than child_path_out_len, WALLY_OK is returned and written contains the length required. It is valid for a path to be zero-length.

Note

This function should be used to read paths from serialized keypath values to prevent endianness issues on big-endian hosts.

Returns:

See Error Codes

int wally_map_keypath_get_item_path(const struct wally_map *map_in, size_t index, uint32_t *child_path_out, size_t child_path_out_len, size_t *written)

Get the path from a PSBT keypath’s serialized value.

Parameters:

• map_in – The map to return the item’s path from.

• index – The zero-based index of the item whose path to return.

• child_path_out – Destination for the resulting path.

• child_path_out_len – The number of items in child_path_out.

• written – Destination for the number of items written to child_path_out.

Note

See the notes for wally_keypath_get_path.

Returns:

See Error Codes

int wally_map_hash_preimage_verify(const unsigned char *key, size_t key_len, const unsigned char *val, size_t val_len)

Verify a preimage map key and value pair.

Parameters:

• key – The preimage hash, prefixed by a hash type byte.

• key_len – Length of key in bytes.

• val – The preimage data hashed to produce key.

• val_len – Length of val in bytes.

Note

Multiple preimage types are stored in the same map, prefixed by a leading byte. The exact format of storage is implementation dependent and may change in the future.

Returns:

See Error Codes

int wally_map_preimage_init_alloc(size_t allocation_len, struct wally_map **output)

Allocate and initialize a new preimage map.

Parameters:

• allocation_len – The number of items to allocate space for.

• output – Destination for the new map.

Returns:

See Error Codes

int wally_map_preimage_ripemd160_add(struct wally_map *map_in, const unsigned char *value, size_t value_len)

Add a ripemd160 preimage to a preimage map.

Parameters:

• map_in – The preimage map to add to.

• value – The data to store.

• value_len – Length of value in bytes.

Returns:

See Error Codes

int wally_map_preimage_sha256_add(struct wally_map *map_in, const unsigned char *value, size_t value_len)

Add a sha256 preimage to a preimage map.

Parameters:

• map_in – The preimage map to add to.

• value – The data to store.

• value_len – Length of value in bytes.

Returns:

See Error Codes

int wally_map_preimage_hash160_add(struct wally_map *map_in, const unsigned char *value, size_t value_len)

Add a hash160 preimage to a preimage map.

Parameters:

• map_in – The preimage map to add to.

• value – The data to store.

• value_len – Length of value in bytes.

Returns:

See Error Codes

int wally_map_preimage_sha256d_add(struct wally_map *map_in, const unsigned char *value, size_t value_len)

Add a sha256d preimage to a preimage map.

Parameters:

• map_in – The preimage map to add to.

• value – The data to store.

• value_len – Length of value in bytes.

Returns:

See Error Codes