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.
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.
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
- map_in – The map to find
-
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
- map_in – The map to find
-
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.
- map_in – The map to find
-
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:
-
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 combine into.
- 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 - map_in – The map to find the public key of
-
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 resulting privately derived key is returned. If no key is found,*output
is set toNULL
andWALLY_OK
is returned.Returns: See Error Codes - map_in – The map to search for derived keys of
-
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 beBIP32_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 beEC_PUBLIC_KEY_UNCOMPRESSED_LEN
orBIP32_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 beEC_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_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 beBIP32_SERIALIZED_LEN
for an extended bip32 public key, orEC_PUBLIC_KEY_UNCOMPRESSED_LEN
orEC_PUBLIC_KEY_LEN
for a public key. - fingerprint – The master key fingerprint for the pubkey.
- fingerprint_len – Length of
fingerprint
in bytes. Must beBIP32_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_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 beBIP32_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 beBIP32_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 andwritten
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