Bip32 Functions =============== .. c:function:: 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`. :param hdkey: Key to free. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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. :param bytes: Entropy to use. :param bytes_len: Size of ``bytes`` in bytes. Must be one of the :ref:`bip32-entropy-length` :param version: Either `BIP32_VER_MAIN_PRIVATE` or `BIP32_VER_TEST_PRIVATE`, indicating mainnet or testnet/regtest respectively. :param hmac_key: Custom data to HMAC-SHA512 with ``bytes`` before creating the key. Pass NULL to use the default BIP32 key of "Bitcoin seed". :param hmac_key_len: Size of ``hmac_key`` in bytes, or 0 if ``hmac_key`` is NULL. :param flags: Either `BIP32_FLAG_SKIP_HASH` to skip hash160 calculation, or 0. :param output: Destination for the resulting master extended key. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The extended key to serialize. :param flags: :ref:`bip32-flags` indicating which key to serialize. You can not serialize a private extended key from a public extended key. :param bytes_out: Destination for the serialized key. :param len: Size of ``bytes_out``. Must be `BIP32_SERIALIZED_LEN`. :return: See :ref:`error-codes` .. c:function:: int bip32_key_unserialize(const unsigned char *bytes, size_t bytes_len, struct ext_key *output) Un-serialize an extended key from memory. :param bytes: Storage holding the serialized key. :param bytes_len: Size of ``bytes`` in bytes. Must be `BIP32_SERIALIZED_LEN`. :param output: Destination for the resulting extended key. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The parent extended key. :param 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. :param flags: :ref:`bip32-flags` indicating the type of derivation wanted. You can not derive a private child extended key from a public parent extended key. :param output: Destination for the resulting child extended key. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The parent extended key. :param child_path: The path of child numbers to create. :param child_path_len: The number of child numbers in ``child_path``. :param flags: :ref:`bip32-flags` indicating the type of derivation wanted. :param 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. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The parent extended key. :param path_str: The BIP32 path string of child numbers to create. :param child_num: The child number to use if ``path_str`` contains a ``*`` wildcard. :param flags: :ref:`bip32-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`. :param 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. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The parent extended key. :param child_path: The path of child numbers to create. :param child_path_len: The number of child numbers in ``child_path``. :param flags: :ref:`bip32-flags` indicating the type of derivation wanted. :param output: Destination for the resulting key. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: int bip32_key_to_base58(const struct ext_key *hdkey, uint32_t flags, char **output) Convert an extended key to base58. :param hdkey: The extended key. :param flags: :ref:`bip32-flags` indicating which key to serialize. You can not serialize a private extended key from a public extended key. :param output: Destination for the resulting key in base58. The string returned should be freed using `wally_free_string`. :return: See :ref:`error-codes` .. c:function:: int bip32_key_from_base58(const char *base58, struct ext_key *output) Convert a base58 encoded extended key to an extended key. :param base58: The extended key in base58. :param output: Destination for the resulting extended key. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` .. c:function:: 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. :param hdkey: The extended key to convert. :return: See :ref:`error-codes` .. c:function:: 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`. :param hdkey: The extended key. :param bytes_out: Destination for the fingerprint. :param len: Size of ``bytes_out``. Must be `BIP32_KEY_FINGERPRINT_LEN`. :return: See :ref:`error-codes` .. c:function:: int bip32_path_from_str_len(const char *path_str, uint32_t child_num, uint32_t multi_index, uint32_t flags, size_t *written) Get the number of child path elements in a BIP32 path string. :param path_str: The BIP32 path string of child numbers to convert from. :param child_num: The child number to use if ``path_str`` contains a ``*`` wildcard. :param multi_index: The multi-path item to use if ``path_str`` contains a ``<>`` multi-path. :param flags: :ref:`bip32-flags` controlling path parsing behaviour. :param written: Destination for the number of path elements in the path string. :return: See :ref:`error-codes` .. c:function:: 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, size_t child_path_out_len, size_t *written) Convert a BIP32 path string to a path. :param path_str: The BIP32 path string of child numbers to convert from. :param child_num: The child number to use if ``path_str`` contains a ``*`` wildcard. :param multi_index: The multi-path item to use if ``path_str`` contains a ``<>`` multi-path. :param flags: :ref:`bip32-flags` controlling path parsing behaviour. :param child_path_out: Destination for the resulting path. :param child_path_out_len: The number of items in ``child_path_out``. :param written: Destination for the number of items written to ``child_path_out``. :return: See :ref:`error-codes` .. c:function:: int bip32_path_from_str_n_len(const char *path_str, size_t path_str_len, uint32_t child_num, uint32_t multi_index, uint32_t flags, size_t *written) Get the number of child path elements in a known-length BIP32 path string. See `bip32_path_from_str_len`. :return: See :ref:`error-codes` .. c:function:: 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, size_t child_path_out_len, size_t *written) Convert a known-length BIP32 path string to an integer path. See `bip32_path_from_str`. :return: See :ref:`error-codes` .. c:function:: int bip32_path_str_get_features(const char *path_str, uint32_t *value_out) Get information about the structure of a BIP32 path string. :param path_str: The BIP32 path string of child numbers to convert from. :param value_out: Destination for the resulting :ref:`path-feature-flags`. :return: See :ref:`error-codes` .. c:function:: 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`. :return: See :ref:`error-codes` Bip32 Constants --------------- .. _bip32-entropy-length: BIP32 Seed Entropy Lengths ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: BIP32_ENTROPY_LEN_128 128 bits .. c:macro:: BIP32_ENTROPY_LEN_256 256 bits .. c:macro:: BIP32_ENTROPY_LEN_512 512 bits .. c:macro:: BIP32_KEY_FINGERPRINT_LEN Length of a BIP32 key fingerprint .. c:macro:: BIP32_SERIALIZED_LEN Length of an ext_key serialized using BIP32 format .. c:macro:: BIP32_INITIAL_HARDENED_CHILD Child number of the first hardened child .. c:macro:: BIP32_PATH_MAX_LEN The maximum number of path elements allowed in a path .. c:macro:: WALLY_BIP32_CHAIN_CODE_LEN .. c:macro:: WALLY_BIP32_TWEAK_SUM_LEN .. _bip32-flags: BIP32 Derivation Flags ^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: BIP32_FLAG_KEY_PRIVATE Indicate that we want to derive a private key in `bip32_key_from_parent` .. c:macro:: BIP32_FLAG_KEY_PUBLIC Indicate that we want to derive a public key in `bip32_key_from_parent` .. c:macro:: BIP32_FLAG_SKIP_HASH Indicate that we want to skip hash calculation when deriving a key in `bip32_key_from_parent` .. c:macro:: 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` .. c:macro:: BIP32_FLAG_STR_WILDCARD Allow a wildcard ``*`` or ``*'``/``*h`` in BIP32 path string expressions .. c:macro:: BIP32_FLAG_STR_BARE Do not allow a leading ``m``/``M`` or ``/`` in BIP32 path string expressions .. c:macro:: BIP32_FLAG_ALLOW_UPPER Allow upper as well as lower case ``M``/``H`` in BIP32 path string expressions .. c:macro:: BIP32_FLAG_STR_MULTIPATH Allow a multi-path expression ```` in BIP32 path string expressions .. _bip32-version-codes: BIP32 extended key versions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: BIP32_VER_MAIN_PUBLIC Mainnet, public key .. c:macro:: BIP32_VER_MAIN_PRIVATE Mainnet, private key .. c:macro:: BIP32_VER_TEST_PUBLIC Testnet, public key .. c:macro:: BIP32_VER_TEST_PRIVATE Testnet, private key .. _path-feature-flags: BIP32 path feature flags ^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: BIP32_PATH_LEN_MASK Mask for the path length in bits 0-7 .. c:macro:: BIP32_PATH_LEN_SHIFT Shift for the path length in bits 0-7 .. c:macro:: BIP32_PATH_MULTI_MASK Mask for the number of multi-paths in bits 8-15 .. c:macro:: BIP32_PATH_MULTI_SHIFT Shift for the number of multi-paths in bits 8-15 .. c:macro:: BIP32_PATH_WILDCARD_MASK Mask for the wildcard position in bits 16-23 .. c:macro:: BIP32_PATH_WILDCARD_SHIFT Shift for the wildcard position in bits 16-23 .. c:macro:: BIP32_PATH_IS_BARE Path is bare .. c:macro:: BIP32_PATH_IS_HARDENED Path contains hardened elements .. c:macro:: BIP32_PATH_IS_WILDCARD Path contains a wildcard .. c:macro:: BIP32_PATH_IS_MULTIPATH Path contains a multi-path expression