Core Functions

int wally_init(uint32_t flags)

Initialize wally.

This function must be called once before threads are created by the application.

Parameters:
  • flags – Flags controlling what to initialize. Currently must be zero.
Returns:

See Error Codes
int wally_cleanup(uint32_t flags)

Free any internally allocated memory.

Parameters:
  • flags – Flags controlling what to clean up. Currently must be zero.
Returns:

See Error Codes
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 overriden by providing a custom context fetching function when calling wally_set_operations.

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.

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.

int wally_bzero(void *bytes, size_t bytes_len)

Securely wipe memory.

Parameters:
  • bytes – Memory to wipe
  • bytes_len – Size of bytes in bytes.
Returns:

See Error Codes
int wally_free_string(char *str)

Securely wipe and then free a string allocated by the library.

Parameters:
  • str – String to free (must be NUL terminated UTF-8).
Returns:

See Error Codes
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 overriden 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.

Parameters:
  • bytes – Entropy to use.
  • bytes_len – Size of bytes in bytes. Must be WALLY_SECP_RANDOMIZE_LEN.
Returns:

See Error Codes
int wally_hex_verify(const char *hex)

Verify that a hexadecimal string is valid.

Parameters:
  • hex – String to verify.
Returns:

See Error Codes
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 Error Codes

int wally_hex_from_bytes(const unsigned char *bytes, size_t bytes_len, char **output)

Convert bytes to a (lower-case) hexadecimal string.

Parameters:
  • bytes – Bytes to convert.
  • bytes_len – Size of bytes in bytes.
  • output – Destination for the resulting hexadecimal string. The string returned should be freed using wally_free_string.
Returns:

See Error Codes
int wally_hex_to_bytes(const char *hex, unsigned char *bytes_out, size_t len, size_t *written)

Convert a hexadecimal string to bytes.

Parameters:
  • hex – String to convert.
  • bytes_out – Where to store the resulting bytes.
  • 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_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 Variable Length Output Buffers

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.

Parameters:
  • bytes – Binary data to convert.
  • bytes_len – The length of bytes in bytes.
  • flags – Pass BASE58_FLAG_CHECKSUM if bytes should have a checksum calculated and appended before converting to base 58.
  • output – Destination for the base 58 encoded string representing bytes. The string returned should be freed using wally_free_string.
Returns:

See Error Codes
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.

Parameters:
  • str_in – Base 58 encoded string to decode.
  • 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.
  • bytes_out – Destination for converted binary data.
  • len – The length of bytes_out in bytes.
  • written – Destination for the length of the decoded bytes.
Returns:

See Variable Length Output Buffers
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 Variable Length Output Buffers

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.

Parameters:
  • str_in – Base 58 encoded string to find the length of.
  • written – Destination for the length of the decoded bytes.
Returns:

See Error Codes
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 Error Codes

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.

Parameters:
  • bytes – Binary data to convert.
  • bytes_len – The length of bytes in bytes.
  • flags – Must be 0.
  • output – Destination for the base64 encoded string representing bytes. The string returned should be freed using wally_free_string.
Returns:

See Error Codes
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.

Parameters:
  • str_in – Base64 encoded string to decode.
  • flags – Must be 0.
  • bytes_out – Destination for converted binary data.
  • len – The length of bytes_out in bytes. See wally_base64_get_maximum_length.
  • written – Destination for the length of the decoded bytes.
Returns:

See Variable Length Output Buffers
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.

Parameters:
  • str_in – Base64 encoded string to find the length of.
  • flags – Must be 0.
  • written – Destination for the maximum length of the decoded bytes.
Returns:

See Error Codes
int wally_get_operations(struct wally_operations *output)

Fetch the current overridable operations used by wally.

Parameters:
  • output – Destination for the overridable operations.
Returns:

See Error Codes
int wally_set_operations(const struct wally_operations *ops)

Set the current overridable operations used by wally.

Parameters:
  • ops – The overridable operations to set.

Note

Any NULL members in the passed structure are ignored.

Returns:See Error Codes
int wally_is_elements_build(size_t *written)

Determine if the library was built with elements support.

Parameters:
  • written – 1 if the library supports elements, otherwise 0.
Returns:

See Error Codes