Core Functions

int wally_init(uint32_t flags)

Initialize wally.

As wally is not currently threadsafe, this function should be called once before threads are created by the application.

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

WALLY_OK or an error code.

Return type:

int

int wally_cleanup(uint32_t flags)

Free any internally allocated memory.

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

WALLY_OK or an error code.

Return type:

int

struct secp256k1_context_struct *wally_get_secp_context(void)

Fetch the wally internal secp256k1 context object.

The context is created on demand.

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:

WALLY_OK or an error code.

Return type:

int

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:

WALLY_OK or an error code.

Return type:

int

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. 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).

As wally is not currently threadsafe, 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:

WALLY_OK or an error code.

Return type:

int

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:

WALLY_OK or an error code.

Return type:

int

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:

WALLY_OK or an error code.

Return type:

int

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:

WALLY_OK or an error code.

Return type:

int

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:

WALLY_OK or an error code.

Return type:

int

int wally_base58_get_length(const char *str_in, size_t *written)

Return the length of a base58 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:

WALLY_OK or an error code.

Return type:

int

int wally_get_operations(struct wally_operations *output)

Fetch the current overridable operations used by wally.

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

WALLY_OK or an error code.

Return type:

int

int wally_set_operations(const struct wally_operations *ops)

Set the current overridable operations used by wally.

Parameters:
  • ops – The overridable operations to set.
Returns:

WALLY_OK or an error code.

Return type:

int

int wally_is_elements_build(uint64_t *value_out)

Determine if the library was built with elements support.

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

WALLY_OK or an error code.

Return type:

int