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.
• 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.
• 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(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_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 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_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_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, or EC_PUBLIC_KEY_UNCOMPRESSED_LEN or EC_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_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