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
-
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:
-
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
-
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
-
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_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 beEC_XONLY_PUBLIC_KEY_LEN
.val – The PSBT merkle path.
val_len – Length of
val
in bytes. Must be a multiple ofSHA256_LEN
.
- 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,EC_PUBLIC_KEY_UNCOMPRESSED_LEN
,EC_PUBLIC_KEY_LEN
, orEC_XONLY_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_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 beEC_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 ofSHA256_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 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