Address¶

typedef struct cardano_address_t cardano_address_t¶

Represents a Cardano address.

This structure encapsulates all the necessary information for a Cardano address.

cardano_error_t cardano_address_from_bytes(const byte_t *data, size_t size, cardano_address_t **address)¶

Constructs a Cardano address from a serialized byte array.

This function decodes a byte array into a cardano_address_t object. The function ensures that the byte array provided conforms to the expected format for a Cardano address before creating the address object.

Usage Example:

const byte_t serialized_address[] = { ... };
size_t size = sizeof(serialized_address);
cardano_address_t* address = NULL;

cardano_error_t result = cardano_address_from_bytes(serialized_address, size, &address);

if (result == CARDANO_SUCCESS)
{
  // Use the address

  // Clean up
  cardano_address_unref(&address);
}
else
{
  printf("Failed to decode address: %s\n", cardano_error_to_string(result));
}

Note

The caller is responsible for freeing the created cardano_address_t object by calling cardano_address_unref when it is no longer needed.

Parameters:¶

const byte_t *data¶: [in] A pointer to the byte array containing the serialized address data.
size_t size¶: [in] The size of the byte array.
cardano_address_t **address¶: [out] A pointer to a pointer of cardano_address_t that will be set to the address of the newly created address object upon successful decoding.

Returns:¶

A cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the address was successfully created, or an appropriate error code if an error occurred, such as invalid format or insufficient data for decoding.

size_t cardano_address_get_bytes_size(const cardano_address_t *address)¶

Retrieves the size of the byte array required to serialize a Cardano address.

This function calculates the number of bytes necessary to serialize the specified cardano_address_t object. It is useful for allocating the appropriate amount of memory before serializing the address using cardano_address_to_bytes.

Usage Example:

cardano_address_t* address = cardano_address_from_bytes(...);

if (address)
{
  size_t required_size = cardano_address_get_bytes_size(address);
  byte_t* buffer = (byte_t*)malloc(required_size);

  if (buffer)
  {
    // Serialize the address into buffer
    cardano_address_to_bytes(address, buffer, required_size);
    // Use the buffer ...
    free(buffer);
  }

  // Clean up the address object
  cardano_address_unref(&address);
}

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object whose serialized size is to be determined. The object must not be NULL.

Returns:¶

The size in bytes required to store the serialized form of the address. If the input address is NULL, the function returns 0, indicating an error in usage.

cardano_error_t cardano_address_to_bytes(const cardano_address_t *address, byte_t *data, size_t size)¶

Serializes a Cardano address into a byte array.

This function serializes the given cardano_address_t object into a preallocated buffer. The buffer must be large enough to hold the serialized data, which should be determined by calling cardano_address_get_bytes_size prior to this function.

Usage Example:

cardano_address_t* address = cardano_address_from_bytes(...);
size_t required_size = cardano_address_get_bytes_size(address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_address_to_bytes(address, buffer, required_size);

  if (result == CARDANO_SUCCESS)
  {
    // Use the serialized data
  }

  free(buffer);
}

cardano_address_unref(&address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object that is to be serialized. The object must not be NULL.
byte_t *data¶: [out] A pointer to the buffer where the serialized data will be written.
size_t size¶: [in] The size of the buffer pointed to by data. It must be at least as large as the value returned by cardano_address_get_bytes_size for successful serialization.

Returns:¶

Returns CARDANO_SUCCESS if the serialization is successful. If the buffer data is too small, returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE. If address or data is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

const byte_t *cardano_address_get_bytes(const cardano_address_t *address)¶

Retrieves a pointer to the internal byte array of a Cardano address.

This function provides read-only access to the internal byte representation of a Cardano address. The returned pointer points directly to the internal data structure within the cardano_address_t object. This approach avoids copying data and allows efficient access to the address’s byte representation.

Usage Example:

cardano_address_t* address = cardano_address_from_bytes(...);
const byte_t* byte_ptr = cardano_address_get_bytes(address);

if (byte_ptr)
{
  // Read the bytes but do not modify them
}

cardano_address_unref(&address);  // This also invalidates byte_ptr

Note

Modifying or freeing the data pointed to by the returned pointer will lead to undefined behavior. Treat this pointer as read-only.

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object whose byte array is to be accessed.

Returns:¶

A constant pointer to the internal byte array of the Cardano address. This pointer should not be modified or freed by the caller, as it is managed internally by the Cardano library. The content pointed to remains valid as long as the cardano_address_t object itself is not freed or modified.

cardano_error_t cardano_address_from_string(const char *data, size_t size, cardano_address_t **address)¶

Creates a Cardano address from a string representation.

This function constructs a cardano_address_t object by parsing the provided string. The string should contain a valid representation of a Cardano address, either in base58 or Bech32 format.

Usage Example:

const char* address_str = "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x";
size_t size = strlen(address_str);
cardano_address_t* address = NULL;

cardano_error_t result = cardano_address_from_string(address_str, size, &address);

if (result == CARDANO_SUCCESS)
{
  // Use the address
}
else
{
  printf("Failed to parse address: %d\n", result);
}

// Clean up the address object once done
cardano_address_unref(&address);

Parameters:¶

const char *data¶: [in] A pointer to the character array containing the string representation of the address.
size_t size¶: [in] The length of the string pointed to by data, not including the null terminator.
cardano_address_t **address¶: [out] A pointer to a pointer to cardano_address_t that will be set to the address of the newly created Cardano address object upon successful parsing. The caller is responsible for managing the lifecycle of this object, including freeing it when it is no longer needed using cardano_address_unref.

Returns:¶

Returns CARDANO_SUCCESS if the address is successfully created from the string. Returns CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the string is not a valid address format. If the data is NULL or address is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

size_t cardano_address_get_string_size(const cardano_address_t *address)¶

Retrieves the size needed for the string representation of a Cardano address.

This function calculates the size of the buffer required to hold the string representation of a cardano_address_t object, including the null terminator. This size is necessary to ensure that the buffer allocated for converting the address to a string is sufficient.

Usage Example:

cardano_address_t* address = cardano_address_new(...);
size_t required_size = cardano_address_get_string_size(address);

char* address_str = (char*)malloc(required_size);

if (address_str)
{
  cardano_error_t result = cardano_address_to_string(address, address_str, required_size);
  if (result == CARDANO_SUCCESS)
  {
    printf("Address: %s\n", address_str);
  }
  free(address_str);
}

// Clean up the address object once done
cardano_address_unref(&address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object for which the string size is being calculated. The object must not be NULL.

Returns:¶

The size in bytes needed to store the string representation of the address, including the null terminator. If the input address is NULL, the behavior is undefined.

cardano_error_t cardano_address_to_string(const cardano_address_t *address, char *data, size_t size)¶

Converts a Cardano address into its string representation.

This function serializes the given cardano_address_t object into a string format. The string is written to a user-provided buffer, and the size of this buffer must be adequate to hold the entire string, including the null terminator. The required size can be determined by calling cardano_address_get_string_size.

Usage Example:

cardano_address_t* address = cardano_address_new(...);
size_t required_size = cardano_address_get_string_size(address);
char* address_str = (char*)malloc(required_size);

if (address_str)
{
  cardano_error_t result = cardano_address_to_string(address, address_str, required_size);
  if (result == CARDANO_SUCCESS)
  {
    printf("Address: %s\n", address_str);
  }

  free(address_str);
}

// Clean up the address object once done
cardano_address_unref(&address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object that is to be converted to a string. The object must not be NULL.
char *data¶: [out] A pointer to the buffer where the string representation of the address will be written.
size_t size¶: [in] The size of the buffer pointed to by data. This size should be at least as large as the value returned by cardano_address_get_string_size to ensure successful serialization.

Returns:¶

Returns CARDANO_SUCCESS if the conversion is successful. If the buffer is too small, returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE. If the address or data is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

const char *cardano_address_get_string(const cardano_address_t *address)¶

Retrieves the string representation of a Cardano address.

This function provides access to the string form of the cardano_address_t object. The function returns a pointer to a constant string which represents the address. This string should not be modified or freed by the user, as it is managed internally by the address object.

Usage Example:

cardano_address_t* address = cardano_address_new(...);
const char* address_str = cardano_address_get_string(address);

if (address_str)
{
  printf("Address: %s\n", address_str);
}

// Clean up the address object once done
cardano_address_unref(&address);

Note

The returned string will remain valid as long as the cardano_address_t object is not modified or freed. Once cardano_address_unref is called on the address object, the string pointer should be considered invalid.

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object from which the string is to be retrieved.

Returns:¶

A constant pointer to the internal string representation of the address. If the input address is NULL, the return value is NULL, indicating an error.

bool cardano_address_is_valid_bech32(const char *data, size_t size)¶

Checks if the provided string is a valid Bech32-encoded Cardano address.

This function verifies if the given string conforms to the Bech32 encoding format specific to Cardano addresses.

Usage Example:

const char* address = "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgsqqxw8x";
size_t address_length = strlen(address);

bool is_valid = cardano_address_is_valid_bech32(address, address_length);

if (is_valid)
{
  printf("The address is a valid Bech32 Cardano address.\n");
}
else
{
  printf("The address is not a valid Bech32 Cardano address.\n");
}

Parameters:¶

const char *data¶: [in] A pointer to the character array containing the potential Bech32 address.
size_t size¶: [in] The length of the string pointed to by data.

Returns:¶

true if the string is a valid Bech32-encoded Cardano address; otherwise, false.

bool cardano_address_is_valid_byron(const char *data, size_t size)¶

Checks if the provided string is a valid Byron-encoded Cardano address.

This function verifies if the given string conforms to the Byron address encoding format used in earlier versions of the Cardano blockchain. It performs checks on the structure and integrity of the address, ensuring it follows the expected format and contains a valid checksum.

Usage Example:

const char* address = "Ae2tdPwUPEZFRbyhz3cpfC2CumGzNkFBN2L42rcUc2yjQpEkxDbkPodpMAi";
size_t address_length = strlen(address);

bool is_valid = cardano_address_is_valid_byron(address, address_length);

if (is_valid)
{
  printf("The address is a valid Byron Cardano address.\n");
}
else
{
  printf("The address is not a valid Byron Cardano address.\n");
}

Note

This function does not modify the input string and does not allocate any dynamic memory.

Parameters:¶

const char *data¶: [in] A pointer to the character array containing the potential Byron address.
size_t size¶: [in] The length of the string pointed to by data.

Returns:¶

true if the string is a valid Byron-encoded Cardano address; otherwise, false.

bool cardano_address_is_valid(const char *data, size_t size)¶

Checks if the provided string is a valid Cardano address.

This function verifies if the given string conforms to the encoding formats used for Cardano addresses, including both Byron and Shelley address formats. It checks the structure and integrity of the address, ensuring it follows the expected format.

Usage Example:

const char* address = "addr1qxy2cnx2l2s54at80au205tswxpnuvsgsn9rqlat4zuyghqp6v3hj4t4c7szlevu9hxy6w2scv0hecqlq5v3x6jts0sqqx5scn";
size_t address_length = strlen(address);

bool is_valid = cardano_address_is_valid(address, address_length);

if (is_valid)
{
  printf("The address is a valid Cardano address.\n");
}
else
{
  printf("The address is not a valid Cardano address.\n");
}

Parameters:¶

const char *data¶: [in] A pointer to the character array containing the potential Cardano address.
size_t size¶: [in] The length of the string pointed to by data.

Returns:¶

true if the string is a valid Cardano address; otherwise, false.

cardano_error_t cardano_address_get_type(const cardano_address_t *address, cardano_address_type_t *type)¶

Retrieves the type of a given Cardano address.

This function examines the provided cardano_address_t object and determines its address type, such as whether it is a base, pointer, enterprise, reward, or Byron address. The address type is determined based on the structure and prefix of the address.

Usage Example:

cardano_address_t* address = NULL;
cardano_address_type_t address_type;

cardano_error_t result = cardano_address_from_string("addr1...", strlen("addr1..."), &address);

if (result == CARDANO_SUCCESS)
{
  cardano_error_t get_type_result = cardano_address_get_type(address, &address_type);

  if (get_type_result != CARDANO_SUCCESS)
  {
    printf("Failed to determine the address type.\n");
  }
  else
  {
    printf("Address type: %d\n", address_type);
  }
}
else
{
  printf("Failed to determine the address type.\n");
}

cardano_address_unref(&address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object whose type is to be determined. The object must not be NULL.
cardano_address_type_t *type¶: [out] A pointer to cardano_address_type_t where the address type will be stored upon successful determination. This parameter cannot be NULL.

Returns:¶

Returns CARDANO_SUCCESS if the address type was successfully determined. Returns CARDANO_ERROR_POINTER_IS_NULL if the input address or type pointer is NULL. Returns other error codes as defined in cardano_error_t if the address type cannot be determined due to the address not conforming to any known Cardano address format.

cardano_error_t cardano_address_get_network_id(const cardano_address_t *address, cardano_network_id_t *network_id)¶

Retrieves the network ID from a given Cardano address.

This function extracts the network identifier from the provided cardano_address_t object. The network ID indicates whether the address belongs to the test network or the main network.

Usage Example:

cardano_address_t* address = NULL;
cardano_network_id_t network_id;

cardano_error_t result = cardano_address_from_string("addr1...", strlen("addr1..."), &address);

if (result == CARDANO_SUCCESS)
{
  cardano_error_t get_network_id = cardano_address_get_network_id(address, &network_id);

  if (get_network_id != CARDANO_SUCCESS)
  {
    printf("Failed to determine the address network id.\n");
  }
  else
  {
    printf("Network ID: %d\n", network_id);
  }
}
else
{
  printf("Failed to retrieve the network ID.\n");
}

cardano_address_unref(&address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object from which the network ID is to be retrieved.
cardano_network_id_t *network_id¶: [out] A pointer to cardano_network_id_t where the network ID will be stored upon successful extraction. This parameter cannot be NULL.

Returns:¶

Returns CARDANO_SUCCESS if the network ID was successfully retrieved. Returns CARDANO_ERROR_POINTER_IS_NULL if the input address or network_id pointer is NULL. Returns other error codes as defined in cardano_error_t if the network ID cannot be retrieved due to malformed or unrecognized address formats.

cardano_byron_address_t *cardano_address_to_byron_address(const cardano_address_t *address)¶

Converts a general Cardano address to a Byron-specific address format.

This function creates a cardano_byron_address_t object from a given cardano_address_t object.

Usage Example:

cardano_byron_address_t* byron_address = cardano_address_to_byron_address(address);

if (byron_address)
{
  // Byron address is successfully converted
  // Proceed with operations that require a Byron address

  cardano_byron_address_unref(&byron_address);
}
else
{
  printf("Conversion to Byron address format failed.\n");
}

cardano_address_unref(&shelley_address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object to be converted. The object must not be NULL and must represent a valid Byron address.

Returns:¶

A pointer to a newly created cardano_byron_address_t object if the conversion is successful. Returns NULL if the address cannot be converted to a Byron address due to an invalid format or if the provided address does not correspond to a Byron address. The caller is responsible for managing the lifecycle of the returned object, including freeing it when it is no longer needed using cardano_byron_address_unref.

cardano_reward_address_t *cardano_address_to_reward_address(const cardano_address_t *address)¶

Converts a general Cardano address to a reward-specific address format.

This function creates a cardano_reward_address_t object from a given cardano_address_t object.

Usage Example:

cardano_reward_address_t* reward_address = cardano_address_to_reward_address(address);

if (reward_address)
{
  // Reward address is successfully converted
  // Proceed with operations that require a reward address

  cardano_reward_address_unref(&reward_address);
}
else
{
  printf("Conversion to reward address format failed.\n");
}

cardano_address_unref(&general_address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object to be converted. The object must not be NULL and must represent a valid reward address.

Returns:¶

A pointer to a newly created cardano_reward_address_t object if the conversion is successful. Returns NULL if the address cannot be converted to a reward address due to an invalid format or if the provided address does not correspond to a reward address. The caller is responsible for managing the lifecycle of the returned object, including freeing it when it is no longer needed using cardano_reward_address_unref.

cardano_pointer_address_t *cardano_address_to_pointer_address(const cardano_address_t *address)¶

Converts a general Cardano address to a pointer address format.

This function creates a cardano_pointer_address_t object from a given cardano_address_t object.

Usage Example:

cardano_address_t* address = ...;
cardano_pointer_address_t* pointer_address = cardano_address_to_pointer_address(address);

if (pointer_address)
{
  // Pointer address is successfully converted
  // Proceed with operations that require a pointer address

  cardano_pointer_address_unref(&pointer_address);
}
else
{
  printf("Conversion to pointer address format failed.\n");
}

cardano_address_unref(&general_address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object to be converted. The object must not be NULL and must represent a valid pointer address.

Returns:¶

A pointer to a newly created cardano_pointer_address_t object if the conversion is successful. Returns NULL if the address cannot be converted to a pointer address due to an invalid format or if the provided address does not correspond to a pointer address. The caller is responsible for managing the lifecycle of the returned object, including freeing it when it is no longer needed using cardano_pointer_address_unref.

cardano_enterprise_address_t *cardano_address_to_enterprise_address(const cardano_address_t *address)¶

Converts a general Cardano address to an enterprise address format.

This function creates a cardano_enterprise_address_t object from a given cardano_address_t object.

Usage Example:

cardano_address_t* address = ...;
cardano_enterprise_address_t* enterprise_address = cardano_address_to_enterprise_address(address);

if (enterprise_address)
{
  // Enterprise address is successfully converted
  // Proceed with operations that require an enterprise address

  cardano_enterprise_address_unref(&enterprise_address);
}
else
{
  printf("Conversion to enterprise address format failed.\n");
}

cardano_address_unref(&general_address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object to be converted. The object must not be NULL and must represent a valid enterprise address.

Returns:¶

A pointer to a newly created cardano_enterprise_address_t object if the conversion is successful. Returns NULL if the address cannot be converted to an enterprise address due to an invalid format or if the provided address does not correspond to an enterprise address. The caller is responsible for managing the lifecycle of the returned object, including freeing it when it is no longer needed using cardano_enterprise_address_unref.

cardano_base_address_t *cardano_address_to_base_address(const cardano_address_t *address)¶

Converts a general Cardano address to a base address format.

This function creates a cardano_base_address_t object from a given cardano_address_t object.

Usage Example:

cardano_address_t* address = ...;
cardano_base_address_t* base_address = cardano_address_to_base_address(address);

if (base_address)
{
  // Base address is successfully converted
  // Proceed with operations that require a base address

  cardano_base_address_unref(&base_address);
}
else
{
  printf("Conversion to base address format failed.\n");
}

cardano_address_unref(&general_address);

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object to be converted. The object must not be NULL and must represent a valid base address.

Returns:¶

A pointer to a newly created cardano_base_address_t object if the conversion is successful. Returns NULL if the address cannot be converted to a base address due to an invalid format or if the provided address does not correspond to a base address. The caller is responsible for managing the lifecycle of the returned object, including freeing it when it is no longer needed using cardano_base_address_unref.

bool cardano_address_equals(const cardano_address_t *lhs, const cardano_address_t *rhs)¶

Compares two address objects for equality.

This function compares two address objects to determine if they are equal.

Usage Example:

cardano_address_t* address1 = NULL;
cardano_address_t* address2 = NULL;

// Assume address1 and address2 are initialized properly

bool are_equal = cardano_address_equals(address1, address2);

if (are_equal)
{
  printf("The address objects are equal.\n");
}
else
{
  printf("The address objects are not equal.\n");
}

// Clean up
cardano_address_unref(&address1);
cardano_address_unref(&address2);

Parameters:¶

const cardano_address_t *lhs¶: [in] Pointer to the first address object.
const cardano_address_t *rhs¶: [in] Pointer to the second address object.

Returns:¶

true if the address objects are equal, false otherwise.

void cardano_address_unref(cardano_address_t **address)¶

Decrements the address’s reference count.

If the reference count reaches zero, the address memory is deallocated.

Parameters:¶

cardano_address_t **address¶: [in] Pointer to the address whose reference count is to be decremented.

void cardano_address_ref(cardano_address_t *address)¶

Increments the address’s reference count.

Ensures that the address remains allocated until the last reference is released.

Parameters:¶

cardano_address_t *address¶: [in] address whose reference count is to be incremented.

size_t cardano_address_refcount(const cardano_address_t *address)¶

Retrieves the address’s current reference count.

Warning

Does not account for transitive references.

Parameters:¶

const cardano_address_t *address¶: [in] Target address.

Returns:¶

Current reference count of the address.

void cardano_address_set_last_error(cardano_address_t *address, const char *message)¶

Sets the last error message for a given address.

This function records an error message in the address’s last_error buffer, overwriting any previous message. The message is truncated if it exceeds the buffer size. This function is typically used to store descriptive error information that can be retrieved later with cardano_address_get_last_error.

Note

The error message is limited to 1023 characters due to the fixed size of the last_error buffer (1024 characters), including the null terminator. Messages longer than this limit will be truncated.

Parameters:¶

cardano_address_t *address¶: [inout] A pointer to the cardano_address_t instance whose last error message is to be set. If the address is NULL, the function has no effect.
const char *message¶: [in] A null-terminated string containing the error message to be recorded. If the message is NULL, the address’s last_error will be set to an empty string, indicating no error.

const char *cardano_address_get_last_error(const cardano_address_t *address)¶

Retrieves the last error message recorded for a specific address.

This function returns a pointer to the null-terminated string containing the last error message set by cardano_address_set_last_error for the given address. If no error message has been set, or if the last_error buffer was explicitly cleared, an empty string is returned, indicating no error.

Note

The returned string points to internal storage within the address and must not be modified by the caller. The string remains valid until the next call to cardano_address_set_last_error for the same address, or until the address is deallocated.

Parameters:¶

const cardano_address_t *address¶: [inout] A pointer to the cardano_address_t instance whose last error message is to be retrieved. If the address is NULL, the function returns a generic error message indicating the null address.

Returns:¶

A pointer to a null-terminated string containing the last error message for the specified address. If the address is NULL, “Object is NULL.” is returned to indicate the error.