Core Functions ============== .. c:function:: int wally_init(uint32_t flags) Initialize wally. This function must be called once before threads are created by the application. :param flags: Flags controlling what to initialize. Currently must be zero. :return: See :ref:`error-codes` .. c:function:: int wally_cleanup(uint32_t flags) Free any internally allocated memory. :param flags: Flags controlling what to clean up. Currently must be zero. :return: See :ref:`error-codes` .. c:function:: int wally_get_build_version(uint32_t *value_out) Get the version number of the library. :param value_out: Destination for the library build version. This is the value of `WALLY_BUILD_VER` when the library was compiled. :return: See :ref:`error-codes` .. c:function:: void *wally_malloc(size_t size) Allocate memory using the configured library allocator. :param size: Size of the memory region to allocate in bytes. The allocated memory must be freed using `wally_free`. .. c:function:: void *wally_calloc(size_t size) Allocate and zero memory using the configured library allocator. :param size: Size of the memory region to allocate in bytes. The allocated memory must be freed using `wally_free`. .. c:function:: void wally_free(void *ptr) Free memory allocated from the configured library allocator. :param ptr: The memory region to free. .. c:function:: char *wally_strdup_n(const char *str, size_t str_len) Duplicate a known-length string using the configured library allocator. :param str: The string to duplicate. :param str_len: The length of ``str`` in bytes. This function appends a NUL terminator to the string. The allocated string must be freed using `wally_free`. .. c:function:: char *wally_strdup(const char *str) Duplicate a string using the configured library allocator. :param str: The string to duplicate. :param str_len: The length of ``str`` in bytes. This function appends a NUL terminator to the string. The allocated string must be freed using `wally_free`. .. c:function:: struct secp256k1_context_struct *wally_get_secp_context(void) Fetch the wally internal secp256k1 context object. By default, a single global context is created on demand. This behaviour can be overridden by providing a custom context fetching function when calling `wally_set_operations`. .. c:function:: struct secp256k1_context_struct *wally_get_new_secp_context(void) Create a new wally-suitable secp256k1 context object. The created context is initialised to be usable by all wally functions. .. c:function:: void wally_secp_context_free(struct secp256k1_context_struct *ctx) Free a secp256k1 context object created by `wally_get_new_secp_context`. This function must only be called on context objects returned from `wally_get_new_secp_context`, it should not be called on the default context returned from `wally_get_secp_context`. .. c:function:: int wally_bzero(void *bytes, size_t bytes_len) Securely wipe memory. :param bytes: Memory to wipe :param bytes_len: Size of ``bytes`` in bytes. :return: See :ref:`error-codes` .. c:function:: int wally_free_string(char *str) Securely wipe and then free a string allocated by the library. :param str: String to free (must be NUL terminated UTF-8). :return: See :ref:`error-codes` .. c:function:: int wally_secp_randomize(const unsigned char *bytes, size_t bytes_len) Provide entropy to randomize the libraries internal libsecp256k1 context. Random data is used in libsecp256k1 to blind the data being processed, making side channel attacks more difficult. By default, Wally uses a single internal context for secp functions that is not initially randomized. The caller should call this function before using any functions that rely on libsecp256k1 (i.e. Anything using public/private keys). If the caller has overridden the library's default libsecp context fetching using `wally_set_operations`, then it may be necessary to call this function before calling wally functions in each thread created by the caller. If wally is used in its default configuration, this function should either be called before threads are created or access to wally functions wrapped in an application level mutex. :param bytes: Entropy to use. :param bytes_len: Size of ``bytes`` in bytes. Must be `WALLY_SECP_RANDOMIZE_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_hex_verify(const char *hex) Verify that a hexadecimal string is valid. :param hex: String to verify. :return: See :ref:`error-codes` .. c:function:: int wally_hex_n_verify(const char *hex, size_t hex_len) Verify that a known-length hexadecimal string is valid. See `wally_hex_verify`. :return: See :ref:`error-codes` .. c:function:: int wally_hex_from_bytes(const unsigned char *bytes, size_t bytes_len, char **output) Convert bytes to a (lower-case) hexadecimal string. :param bytes: Bytes to convert. :param bytes_len: Size of ``bytes`` in bytes. :param output: Destination for the resulting hexadecimal string. The string returned should be freed using `wally_free_string`. :return: See :ref:`error-codes` .. c:function:: int wally_hex_to_bytes(const char *hex, unsigned char *bytes_out, size_t len, size_t *written) Convert a hexadecimal string to bytes. :param hex: String to convert. :param bytes_out: Destination for the resulting bytes. :param len: The length of ``bytes_out`` in bytes. :param written: Destination for the number of bytes written to ``bytes_out``. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_hex_n_to_bytes(const char *hex, size_t hex_len, unsigned char *bytes_out, size_t len, size_t *written) Convert a known-length hexadecimal string to bytes. See `wally_hex_to_bytes`. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_base58_from_bytes(const unsigned char *bytes, size_t bytes_len, uint32_t flags, char **output) Create a base 58 encoded string representing binary data. :param bytes: Binary data to convert. :param bytes_len: The length of ``bytes`` in bytes. :param flags: Pass `BASE58_FLAG_CHECKSUM` if ``bytes`` should have a checksum calculated and appended before converting to base 58. :param output: Destination for the base 58 encoded string representing ``bytes``. The string returned should be freed using `wally_free_string`. :return: See :ref:`error-codes` .. c:function:: int wally_base58_to_bytes(const char *str_in, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written) Decode a base 58 encoded string back into into binary data. :param str_in: Base 58 encoded string to decode. :param flags: Pass `BASE58_FLAG_CHECKSUM` if ``bytes_out`` should have a checksum validated and removed before returning. In this case, ``len`` must contain an extra `BASE58_CHECKSUM_LEN` bytes to calculate the checksum into. The returned length will not include the checksum. :param bytes_out: Destination for converted binary data. :param len: The length of ``bytes_out`` in bytes. :param written: Destination for the length of the decoded bytes. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_base58_n_to_bytes(const char *str_in, size_t str_len, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written) Decode a known-length base 58 encoded string back into into binary data. See `wally_base58_to_bytes`. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_base58_get_length(const char *str_in, size_t *written) Return the length of a base 58 encoded string once decoded into bytes. Returns the exact number of bytes that would be required to store ``str_in`` as decoded binary, including any embedded checksum. If the string contains invalid characters then WALLY_EINVAL is returned. Note that no checksum validation takes place. In the worst case (an all zero buffer, represented by a string of '1' characters), this function will return strlen(``str_in``). You can therefore safely use the length of ``str_in`` as a buffer size to avoid calling this function in most cases. :param str_in: Base 58 encoded string to find the length of. :param written: Destination for the length of the decoded bytes. :return: See :ref:`error-codes` .. c:function:: int wally_base58_n_get_length(const char *str_in, size_t str_len, size_t *written) Return the length of a known-length base 58 encoded string once decoded into bytes. See `wally_base58_get_length`. :return: See :ref:`error-codes` .. c:function:: int wally_base64_from_bytes(const unsigned char *bytes, size_t bytes_len, uint32_t flags, char **output) Create a base64 encoded string representing binary data. :param bytes: Binary data to convert. :param bytes_len: The length of ``bytes`` in bytes. :param flags: Must be 0. :param output: Destination for the base64 encoded string representing ``bytes``. The string returned should be freed using `wally_free_string`. :return: See :ref:`error-codes` .. c:function:: int wally_base64_to_bytes(const char *str_in, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written) Decode a base64 encoded string back into into binary data. :param str_in: Base64 encoded string to decode. :param flags: Must be 0. :param bytes_out: Destination for converted binary data. :param len: The length of ``bytes_out`` in bytes. See `wally_base64_get_maximum_length`. :param written: Destination for the length of the decoded bytes. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_base64_n_to_bytes(const char *str_in, size_t str_len, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written) Decode a known-length base64 encoded string back into into binary data. See `wally_base64_to_bytes`. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_base64_get_maximum_length(const char *str_in, uint32_t flags, size_t *written) Return the maximum length of a base64 encoded string once decoded into bytes. Since base64 strings may contain line breaks and padding, it is not possible to compute their decoded length without fully decoding them. This function cheaply calculates the maximum possible decoded length, which can be used to allocate a buffer for `wally_base64_to_bytes`. In most cases the decoded data will be shorter than the value returned. :param str_in: Base64 encoded string to find the length of. :param flags: Must be 0. :param written: Destination for the maximum length of the decoded bytes. :return: See :ref:`error-codes` .. c:function:: int wally_base64_n_get_maximum_length(const char *str_in, size_t str_len, uint32_t flags, size_t *written) Return the maximum length of a known-length base64 encoded string once decoded into bytes. See `wally_base64_get_maximum_length`. :return: See :ref:`error-codes` .. c:function:: int wally_get_operations(struct wally_operations *output) Fetch the current overridable operations used by wally. :param output: Destination for the overridable operations. :return: See :ref:`error-codes` .. c:function:: int wally_set_operations(const struct wally_operations *ops) Set the current overridable operations used by wally. :param ops: The overridable operations to set. .. note:: Any NULL members in the passed structure are ignored. :return: See :ref:`error-codes` .. c:function:: int wally_is_elements_build(size_t *written) Determine if the library was built with elements support. :param written: 1 if the library supports elements, otherwise 0. :return: See :ref:`error-codes` Core Constants -------------- .. c:macro:: WALLY_OK Success .. c:macro:: WALLY_ERROR General error .. c:macro:: WALLY_EINVAL Invalid argument .. c:macro:: WALLY_ENOMEM malloc() failed .. c:macro:: WALLY_MAJOR_VER Library version .. c:macro:: WALLY_MINOR_VER .. c:macro:: WALLY_PATCH_VER .. c:macro:: WALLY_BUILD_VER .. c:macro:: WALLY_SECP_RANDOMIZE_LEN Length of entropy required for `wally_secp_randomize` .. c:macro:: BASE58_FLAG_CHECKSUM Indicates that a checksum should be generated, or validated and stripped off .. c:macro:: BASE58_CHECKSUM_LEN The number of extra bytes required to hold a base58 checksum