Bip32 Functions

int bip32_key_free(const struct ext_key *hdkey)

Free a key allocated by bip32_key_from_seed_alloc, bip32_key_from_seed_custom or bip32_key_unserialize_alloc.

Parameters:

hdkey – Key to free.

Returns:

int bip32_key_init(uint32_t version, uint32_t depth, uint32_t child_num, const unsigned char *chain_code, size_t chain_code_len, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, const unsigned char *hash160, size_t hash160_len, const unsigned char *parent160, size_t parent160_len, struct ext_key *output)

Initialize a key.

Returns:: See Error Codes

int bip32_key_init_alloc(uint32_t version, uint32_t depth, uint32_t child_num, const unsigned char *chain_code, size_t chain_code_len, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, const unsigned char *hash160, size_t hash160_len, const unsigned char *parent160, size_t parent160_len, struct ext_key **output)

As per bip32_key_init, but allocates the key.

Returns:: See Error Codes

int bip32_key_from_seed_custom(const unsigned char *bytes, size_t bytes_len, uint32_t version, const unsigned char *hmac_key, size_t hmac_key_len, uint32_t flags, struct ext_key *output)

Create a new master extended key from entropy.

This creates a new master key, i.e. the root of a new HD tree. The entropy passed in may produce an invalid key. If this happens, WALLY_ERROR will be returned and the caller should retry with new entropy.

Parameters:

bytes – Entropy to use.
bytes_len – Size of bytes in bytes. Must be one of the BIP32 Seed Entropy Lengths
version – Either BIP32_VER_MAIN_PRIVATE or BIP32_VER_TEST_PRIVATE, indicating mainnet or testnet/regtest respectively.
hmac_key – Custom data to HMAC-SHA512 with bytes before creating the key. Pass NULL to use the default BIP32 key of “Bitcoin seed”.
hmac_key_len – Size of hmac_key in bytes, or 0 if hmac_key is NULL.
flags – Either BIP32_FLAG_SKIP_HASH to skip hash160 calculation, or 0.
output – Destination for the resulting master extended key.

Returns:

See Error Codes

int bip32_key_from_seed(const unsigned char *bytes, size_t bytes_len, uint32_t version, uint32_t flags, struct ext_key *output)

As per bip32_key_from_seed_custom With the default BIP32 seed.

Returns:: See Error Codes

int bip32_key_from_seed_custom_alloc(const unsigned char *bytes, size_t bytes_len, uint32_t version, const unsigned char *hmac_key, size_t hmac_key_len, uint32_t flags, struct ext_key **output)

As per bip32_key_from_seed_custom, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_seed_alloc(const unsigned char *bytes, size_t bytes_len, uint32_t version, uint32_t flags, struct ext_key **output)

As per bip32_key_from_seed, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_serialize(const struct ext_key *hdkey, uint32_t flags, unsigned char *bytes_out, size_t len)

Serialize an extended key to memory using BIP32 format.

Parameters:

hdkey – The extended key to serialize.
flags – BIP32 Derivation Flags indicating which key to serialize. You can not serialize a private extended key from a public extended key.
bytes_out – Destination for the serialized key.
len – Size of bytes_out. Must be BIP32_SERIALIZED_LEN.

Returns:

See Error Codes

int bip32_key_unserialize(const unsigned char *bytes, size_t bytes_len, struct ext_key *output)

Un-serialize an extended key from memory.

Parameters:

bytes – Storage holding the serialized key.
bytes_len – Size of bytes in bytes. Must be BIP32_SERIALIZED_LEN.
output – Destination for the resulting extended key.

Returns:

See Error Codes

int bip32_key_unserialize_alloc(const unsigned char *bytes, size_t bytes_len, struct ext_key **output)

As per bip32_key_unserialize, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_parent(const struct ext_key *hdkey, uint32_t child_num, uint32_t flags, struct ext_key *output)

Create a new child extended key from a parent extended key.

Parameters:

hdkey – The parent extended key.
child_num – The child number to create. Numbers greater than or equal to BIP32_INITIAL_HARDENED_CHILD represent hardened keys that cannot be created from public parent extended keys.
flags – BIP32 Derivation Flags indicating the type of derivation wanted. You can not derive a private child extended key from a public parent extended key.
output – Destination for the resulting child extended key.

Returns:

See Error Codes

int bip32_key_from_parent_alloc(const struct ext_key *hdkey, uint32_t child_num, uint32_t flags, struct ext_key **output)

As per bip32_key_from_parent, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_parent_path(const struct ext_key *hdkey, const uint32_t *child_path, size_t child_path_len, uint32_t flags, struct ext_key *output)

Create a new child extended key from a parent extended key and a path.

Parameters:

hdkey – The parent extended key.
child_path – The path of child numbers to create.
child_path_len – The number of child numbers in child_path.
flags – BIP32 Derivation Flags indicating the type of derivation wanted.
output – Destination for the resulting child extended key.

Note

If child_path contains hardened child numbers, then hdkey must be an extended private key or this function will fail.

Returns:: See Error Codes

int bip32_key_from_parent_path_alloc(const struct ext_key *hdkey, const uint32_t *child_path, size_t child_path_len, uint32_t flags, struct ext_key **output)

As per bip32_key_from_parent_path, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_parent_path_str(const struct ext_key *hdkey, const char *path_str, uint32_t child_num, uint32_t flags, struct ext_key *output)

Create a new child extended key from a parent extended key and a path string.

Parameters:

hdkey – The parent extended key.
path_str – The BIP32 path string of child numbers to create.
child_num – The child number to use if path_str contains a * wildcard.
flags – BIP32 Derivation Flags indicating the type of derivation wanted. Note that BIP32_FLAG_STR_MULTIPATH is not supported. To derive a multi-path key, use bip32_path_from_str then bip32_key_from_parent_path.
output – Destination for the resulting child extended key.

Note

If child_path contains hardened child numbers, then hdkey must be an extended private key or this function will fail.

Returns:: See Error Codes

int bip32_key_from_parent_path_str_n(const struct ext_key *hdkey, const char *path_str, size_t path_str_len, uint32_t child_num, uint32_t flags, struct ext_key *output)

Create a new child extended key from a parent extended key and a known-length path string.

See bip32_key_from_parent_path_str.

Returns:: See Error Codes

int bip32_key_from_parent_path_str_alloc(const struct ext_key *hdkey, const char *path_str, uint32_t child_num, uint32_t flags, struct ext_key **output)

As per bip32_key_from_parent_path_str, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_parent_path_str_n_alloc(const struct ext_key *hdkey, const char *path_str, size_t path_str_len, uint32_t child_num, uint32_t flags, struct ext_key **output)

As per bip32_key_from_parent_path_str_n, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_with_tweak_from_parent_path(const struct ext_key *hdkey, const uint32_t *child_path, size_t child_path_len, uint32_t flags, struct ext_key *output)

Derive the pub tweak from a parent extended key and a path.

Parameters:

hdkey – The parent extended key.
child_path – The path of child numbers to create.
child_path_len – The number of child numbers in child_path.
flags – BIP32 Derivation Flags indicating the type of derivation wanted.
output – Destination for the resulting key.

Returns:

See Error Codes

int bip32_key_with_tweak_from_parent_path_alloc(const struct ext_key *hdkey, const uint32_t *child_path, size_t child_path_len, uint32_t flags, struct ext_key **output)

As per bip32_key_with_tweak_from_parent_path, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_to_base58(const struct ext_key *hdkey, uint32_t flags, char **output)

Convert an extended key to base58.

Parameters:

hdkey – The extended key.
flags – BIP32 Derivation Flags indicating which key to serialize. You can not serialize a private extended key from a public extended key.
output – Destination for the resulting key in base58. The string returned should be freed using wally_free_string.

Returns:

See Error Codes

int bip32_key_from_base58(const char *base58, struct ext_key *output)

Convert a base58 encoded extended key to an extended key.

Parameters:

base58 – The extended key in base58.
output – Destination for the resulting extended key.

Returns:

See Error Codes

int bip32_key_from_base58_n(const char *base58, size_t base58_len, struct ext_key *output)

Convert a known-length base58 encoded extended key to an extended key.

See bip32_key_from_base58.

Returns:: See Error Codes

int bip32_key_from_base58_alloc(const char *base58, struct ext_key **output)

As per bip32_key_from_base58, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_from_base58_n_alloc(const char *base58, size_t base58_len, struct ext_key **output)

As per bip32_key_from_base58_n, but allocates the key.

Note

The returned key should be freed with bip32_key_free.

Returns:: See Error Codes

int bip32_key_strip_private_key(struct ext_key *hdkey)

Converts a private extended key to a public extended key. Afterwards, only public child extended keys can be derived, and only the public serialization can be created. If the provided key is already public, nothing will be done.

Parameters:

hdkey – The extended key to convert.

Returns:

See Error Codes

int bip32_key_get_fingerprint(struct ext_key *hdkey, unsigned char *bytes_out, size_t len)

Get the BIP32 fingerprint for an extended key. Performs hash160 calculation if previously skipped with BIP32_FLAG_SKIP_HASH.

Parameters:

hdkey – The extended key.
bytes_out – Destination for the fingerprint.
len – Size of bytes_out. Must be BIP32_KEY_FINGERPRINT_LEN.

Returns:

See Error Codes

int bip32_path_from_str(const char *path_str, uint32_t child_num, uint32_t multi_index, uint32_t flags, uint32_t *child_path_out, uint32_t child_path_out_len, size_t *written)

Convert a BIP32 path string to a path.

Parameters:

path_str – The BIP32 path string of child numbers to convert from.
child_num – The child number to use if path_str contains a * wildcard.
multi_index – The multi-path item to use if path_str contains a <> multi-path.
flags – BIP32 Derivation Flags controlling path parsing behaviour.
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.

Returns:

See Error Codes

int bip32_path_from_str_n(const char *path_str, size_t path_str_len, uint32_t child_num, uint32_t multi_index, uint32_t flags, uint32_t *child_path_out, uint32_t child_path_out_len, size_t *written)

Convert a known-length BIP32 path string to an integer path.

See bip32_path_from_str.

Returns:: See Error Codes

int bip32_path_str_get_features(const char *path_str, uint32_t *value_out)

Get information about the structure of a BIP32 path string.

Parameters:

path_str – The BIP32 path string of child numbers to convert from.
value_out – Destination for the resulting BIP32 path feature flags.

Returns:

See Error Codes

int bip32_path_str_n_get_features(const char *path_str, size_t path_str_len, uint32_t *value_out)

Get information about the structure of a known_length BIP32 path string.

See bip32_path_str_get_features.

Returns:: See Error Codes

Bip32 Constants

BIP32 Seed Entropy Lengths

BIP32_ENTROPY_LEN_128: 128 bits

BIP32_ENTROPY_LEN_256: 256 bits

BIP32_ENTROPY_LEN_512: 512 bits

BIP32_KEY_FINGERPRINT_LEN: Length of a BIP32 key fingerprint

BIP32_SERIALIZED_LEN: Length of an ext_key serialized using BIP32 format

BIP32_INITIAL_HARDENED_CHILD: Child number of the first hardened child

BIP32_PATH_MAX_LEN: The maximum number of path elements allowed in a path

WALLY_BIP32_CHAIN_CODE_LEN

WALLY_BIP32_TWEAK_SUM_LEN

BIP32 Derivation Flags

BIP32_FLAG_KEY_PRIVATE: Indicate that we want to derive a private key in bip32_key_from_parent

BIP32_FLAG_KEY_PUBLIC: Indicate that we want to derive a public key in bip32_key_from_parent

BIP32_FLAG_SKIP_HASH: Indicate that we want to skip hash calculation when deriving a key in bip32_key_from_parent

BIP32_FLAG_KEY_TWEAK_SUM: Elements: Indicate that we want the pub tweak to be added to the calculation when deriving a key in bip32_key_from_parent

BIP32_FLAG_STR_WILDCARD: Allow a wildcard * or *'/*h in BIP32 path string expressions

BIP32_FLAG_STR_BARE: Do not allow a leading m/M or / in BIP32 path string expressions

BIP32_FLAG_ALLOW_UPPER: Allow upper as well as lower case M/H in BIP32 path string expressions

BIP32_FLAG_STR_MULTIPATH: Allow a multi-path expression <child_num_1;child_num_2;..> in BIP32 path string expressions

BIP32 extended key versions

BIP32_VER_MAIN_PUBLIC: Mainnet, public key

BIP32_VER_MAIN_PRIVATE: Mainnet, private key

BIP32_VER_TEST_PUBLIC: Testnet, public key

BIP32_VER_TEST_PRIVATE: Testnet, private key

BIP32 path feature flags

BIP32_PATH_LEN_MASK: Mask for the path length in bits 0-7

BIP32_PATH_LEN_SHIFT: Shift for the path length in bits 0-7

BIP32_PATH_MULTI_MASK: Mask for the number of multi-paths in bits 8-15

BIP32_PATH_MULTI_SHIFT: Shift for the number of multi-paths in bits 8-15

BIP32_PATH_WILDCARD_MASK: Mask for the wildcard position in bits 16-23

BIP32_PATH_WILDCARD_SHIFT: Shift for the wildcard position in bits 16-23

BIP32_PATH_IS_BARE: Path is bare

BIP32_PATH_IS_HARDENED: Path contains hardened elements

BIP32_PATH_IS_WILDCARD: Path contains a wildcard

BIP32_PATH_IS_MULTIPATH: Path contains a multi-path expression