Reward Address¶

typedef struct cardano_reward_address_t cardano_reward_address_t¶: Represents a reward address in the Cardano blockchain ecosystem.

cardano_error_t cardano_reward_address_from_credentials(cardano_network_id_t network_id, cardano_credential_t *credential, cardano_reward_address_t **reward_address)¶

Creates a reward address from network and credentials.

This function constructs a cardano_reward_address_t object by using a network identifier and credentials.

Usage Example:

cardano_credential_t credential = {...};  // Initialized elsewhere
cardano_reward_address_t* reward_address = NULL;
cardano_error_t result = cardano_reward_address_from_credentials(CARDANO_NETWORK_ID_MAIN_NET, &credential, &reward_address);

if (result == CARDANO_SUCCESS)
{
  // Use the reward address for receiving staking rewards
  // Once done, ensure to clean up and release the reward address
  cardano_reward_address_unref(&reward_address);
}
else
{
  printf("Failed to create reward address: %d\n", result);
}

Parameters:¶

cardano_network_id_t network_id¶: [in] The network identifier, which specifies the Cardano network (e.g., mainnet, testnet).
cardano_credential_t *credential¶: [in] A pointer to a cardano_credential_t object representing the credentials, typically linked to a staking key.
cardano_reward_address_t **reward_address¶: [out] A pointer to a pointer to cardano_reward_address_t that will be set to the address of the newly created reward address object upon successful address creation.

Returns:¶

Returns CARDANO_SUCCESS if the reward address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if any of the pointers (or reward_address) are NULL.

cardano_error_t cardano_reward_address_from_address(const cardano_address_t *address, cardano_reward_address_t **reward_address)¶

Converts a general Cardano address to a specific reward address.

This function constructs a cardano_reward_address_t object from an existing cardano_address_t object.

Usage Example:

cardano_address_t* general_address = NULL;  // Assume general_address is previously created and valid
cardano_reward_address_t* reward_address = NULL;
cardano_error_t result = cardano_reward_address_from_address(general_address, &reward_address);

if (result == CARDANO_SUCCESS)
{
  // Once done, ensure to clean up and release the reward address
  cardano_reward_address_unref(&reward_address);
}
else
{
  printf("Failed to convert to reward address: %d\n", result);
}

Note

It is the responsibility of the caller to manage the lifecycle of the created cardano_reward_address_t object, ensuring that cardano_reward_address_unref is called to free the address object when it is no longer needed, to prevent memory leaks.

Parameters:¶

const cardano_address_t *address¶: [in] A pointer to the cardano_address_t object that represents a general Cardano address.
cardano_reward_address_t **reward_address¶: [out] A pointer to a pointer to cardano_reward_address_t that will be set to the address of the newly created reward address object upon successful conversion.

Returns:¶

Returns CARDANO_SUCCESS if the reward address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if any of the pointers (address or reward_address) are NULL.

cardano_address_t *cardano_reward_address_to_address(const cardano_reward_address_t *reward_address)¶

Converts a reward address to a general Cardano address.

This function takes a cardano_reward_address_t object representing a reward address and converts it back to a general cardano_address_t object.

Usage Example:

cardano_reward_address_t* reward_address = NULL;
// Assume reward_address is previously created and represents a valid reward address
cardano_address_t* general_address = cardano_reward_address_to_address(reward_address);

if (general_address != NULL)
{
  // The reward address has been successfully converted to a general Cardano address
  // Use the general address as needed

  // Once done, ensure to clean up and release the general address
  cardano_address_unref(&general_address);
}
else
{
  printf("Failed to convert reward address to a general address\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_address_t object, including calling cardano_address_unref to free the object when it is no longer needed. Failure to do so can result in memory leaks.

Parameters:¶

const cardano_reward_address_t *reward_address¶: [in] A pointer to the cardano_reward_address_t object that is to be converted into a general Cardano address.

Returns:¶

A pointer to a newly created cardano_address_t object representing the general address. Returns NULL if the reward_address is NULL.

cardano_credential_t *cardano_reward_address_get_credential(cardano_reward_address_t *reward_address)¶

Retrieves the credential from a reward address.

This function extracts the credential from a cardano_reward_address_t object.

Usage Example:

cardano_reward_address_t* reward_address = NULL;
// Assume reward_address is previously created and represents a valid reward address
const cardano_credential_t* _credential = cardano_reward_address_get__credential(reward_address);

if (_credential != NULL)
{
  // The credential can be used for transactions or other purposes

  cardano_credential_unref(&_credential);
}
else
{
  printf("Failed to retrieve credential from reward address\n");
}

Note

The lifecycle of the returned cardano_credential_t object must be managed by the caller. It is important to call cardano_credential_unref to free this object when it is no longer needed to prevent memory leaks.

Parameters:¶

cardano_reward_address_t *reward_address¶: [in] A pointer to the cardano_reward_address_t object from which the credential is to be retrieved.

cardano_error_t cardano_reward_address_from_bytes(const byte_t *data, size_t size, cardano_reward_address_t **address)¶

Creates a pointer address from a byte array.

This function constructs a cardano_reward_address_t object by decoding a byte array that represents a pointer address in serialized form.

Usage Example:

byte_t serialized_address[] = { ... };
size_t serialized_size = sizeof(serialized_address);
cardano_reward_address_t* reward_address = NULL;

cardano_error_t result = cardano_reward_address_from_bytes(serialized_address, serialized_size, &reward_address);

if (result == CARDANO_SUCCESS)
{
  // Use the pointer address as needed
  // Once done, ensure to clean up and release the pointer address
  cardano_reward_address_unref(&reward_address);
}
else
{
  printf("Failed to create pointer address from bytes: %d\n", result);
}

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_reward_address_t object, including ensuring that cardano_reward_address_unref is called to free the address object when it is no longer needed, to prevent memory leaks.

Parameters:¶

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

Returns:¶

Returns CARDANO_SUCCESS if the address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if the data or address pointer is NULL. Returns CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the byte array data could not be decoded into a valid pointer address.

size_t cardano_reward_address_get_bytes_size(const cardano_reward_address_t *address)¶

Retrieves the size in bytes required to serialize a pointer address.

This function calculates the size necessary to store the serialized byte array representation of a given cardano_reward_address_t object.

Usage Example:

cardano_reward_address_t* reward_address = NULL;
// Assume reward_address is already created and valid
size_t required_size = cardano_reward_address_get_bytes_size(reward_address);

if (required_size > 0)
{
  byte_t* buffer = (byte_t*)malloc(required_size);

  if (buffer)
  {
    // Proceed to serialize the pointer address into buffer
  }

 free(buffer);
}
else
{
  printf("Invalid address or unable to determine size\n");
}

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object whose serialized size is to be retrieved.

Returns:¶

The size in bytes required to serialize the pointer address. Returns 0 if the address pointer is NULL or if the address is invalid.

const byte_t *cardano_reward_address_get_bytes(const cardano_reward_address_t *address)¶

Retrieves the byte array representation of a pointer address.

This function provides access to the serialized byte array form of a cardano_reward_address_t object.

Usage Example:

cardano_reward_address_t* reward_address = NULL;
// Assume reward_address is already created and valid
const byte_t* address_bytes = cardano_reward_address_get_bytes(reward_address);
size_t bytes_size = cardano_reward_address_get_bytes_size(reward_address);

if (address_bytes != NULL)
{
  // Process or transmit the byte array
}
else
{
  printf("Failed to retrieve byte array from pointer address\n");
}

Note

The returned byte array is managed internally and should not be freed or modified by the caller. It remains valid as long as the cardano_reward_address_t object is not modified or freed. Use cardano_reward_address_get_bytes_size to determine the size of the byte array.

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object whose byte array is to be retrieved.

Returns:¶

A pointer to the constant byte array representing the pointer address. Returns NULL if the address pointer is NULL.

cardano_error_t cardano_reward_address_to_bytes(const cardano_reward_address_t *address, byte_t *data, size_t size)¶

Serializes a pointer address into a byte array.

This function takes a cardano_reward_address_t object and serializes it into a binary format. The serialized bytes are written into the provided data buffer, which must be large enough to hold the entire binary representation of the address.

Usage Example:

cardano_reward_address_t* reward_address = NULL;
// Assume reward_address is previously created and valid
size_t required_size = cardano_reward_address_get_bytes_size(reward_address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_reward_address_to_bytes(reward_address, buffer, required_size);

  if (result == CARDANO_SUCCESS)
  {
    // The buffer now contains the serialized address
    // Proceed with using the buffer for storage, transmission, etc.
  }
  else
  {
    printf("Failed to serialize pointer address: %d\n", result);
  }

 free(buffer);
}
else
{
  printf("Memory allocation for buffer failed\n");
}

Note

The buffer provided in data must be sufficiently large to accommodate the serialized data to prevent buffer overflow errors.

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object to be serialized.
byte_t *data¶: [out] A pointer to a byte array where the serialized data will be written.
size_t size¶: [in] The size of the provided buffer in bytes. This size should be at least the value returned by cardano_reward_address_get_bytes_size to ensure it can hold the serialized data.

Returns:¶

Returns CARDANO_SUCCESS if the address was successfully serialized into the byte array. Returns CARDANO_ERROR_POINTER_IS_NULL if the address or data pointer is NULL. Returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE if the size is too small to hold the serialized data.

cardano_error_t cardano_reward_address_from_bech32(const char *data, size_t size, cardano_reward_address_t **address)¶

Creates an reward address from a Bech32-encoded string.

This function constructs a cardano_reward_address_t object by decoding the provided Bech32-encoded string that represents the address data.

Usage Example:

const char* bech32_data = "addr1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx...";
size_t bech32_size = strlen(bech32_data);
cardano_reward_address_t* cardano_reward_address = NULL;

cardano_error_t result = cardano_reward_address_from_bech32(bech32_data, bech32_size, &cardano_reward_address);

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

  // Once done, ensure to clean up and release the  reward address
  cardano_reward_address_unref(&cardano_reward_address);
}
else
{
  printf("Failed to decode  reward address from Bech32: %d\n", result);
}

Parameters:¶

const char *data¶: [in] A pointer to a character array containing the Bech32-encoded representation of the address.
size_t size¶: [in] The size of the Bech32 string in bytes.
cardano_reward_address_t **address¶: [out] A pointer to a pointer to cardano_reward_address_t that will be set to the address of the newly created reward address object upon successful decoding.

Returns:¶

Returns CARDANO_SUCCESS if the address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if the data or address pointer is NULL. Returns CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the Bech32 data could not be decoded into a valid reward address.

size_t cardano_reward_address_get_bech32_size(const cardano_reward_address_t *address)¶

Retrieves the size in bytes of the Bech32-encoded representation of an reward address.

This function calculates the size necessary to store the Bech32-encoded representation of a given cardano_reward_address_t address object. This size includes the characters needed to represent the Bech32 string but does not include the null-termination character.

Usage Example:

cardano_reward_address_t* cardano_reward_address = NULL;
// Assume cardano_reward_address is already created and valid
size_t bech32_size = cardano_reward_address_get_bech32_size(cardano_reward_address);

if (bech32_size > 0)
{
  char* bech32_string = (char*) malloc(bech32_size);

  if (bech32_string)
  {
    // Proceed to convert address to Bech32 string
  }

  free(bech32_string);
}
else
{
  printf("Invalid address or unable to determine size\n");
}

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object whose Bech32 size is to be retrieved.

Returns:¶

The size in bytes of the Bech32-encoded representation of the address, including the null terminator. Returns 0 if the address pointer is NULL or if the address is invalid.

cardano_error_t cardano_reward_address_to_bech32(const cardano_reward_address_t *address, char *data, size_t size)¶

Converts an reward address to a Bech32-encoded string.

This function takes a cardano_reward_address_t object and converts it into a Bech32 string, writing the result into the provided data buffer. The buffer must be large enough to hold the entire Bech32 string including the null-termination character.

Usage Example:

cardano_reward_address_t* cardano_reward_address = NULL;
// Assume cardano_reward_address is previously created and valid
size_t required_size = cardano_reward_address_get_bech32_size(cardano_reward_address) + 1; // +1 for null-termination
char* bech32_string = (char*) malloc(required_size);
if (bech32_string)
{
  cardano_error_t result = cardano_reward_address_to_bech32(cardano_reward_address, bech32_string, required_size);
  if (result == CARDANO_SUCCESS)
  {
    printf("Bech32 representation: %s\n", bech32_string);
  }
  else
  {
    printf("Failed to convert  reward address to Bech32: %d\n", result);
  }
  free(bech32_string);
}
else
{
  printf("Memory allocation failed for Bech32 buffer\n");
}

Note

It is crucial to ensure that the buffer provided in data is sufficiently large to accommodate the Bech32 string and the null-termination character to prevent buffer overflow errors.

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object to be converted.
char *data¶: [out] A pointer to a character buffer where the Bech32-encoded string will be stored.
size_t size¶: [in] The size of the provided buffer in bytes. This size must be at least the value returned by cardano_reward_address_get_bech32_size to ensure it can hold the Bech32 string and the null terminator.

Returns:¶

Returns CARDANO_SUCCESS if the conversion was successful. Returns CARDANO_ERROR_POINTER_IS_NULL if the address or data pointer is NULL. Returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE if the size is too small to hold the Bech32 representation including the null terminator.

const char *cardano_reward_address_get_string(const cardano_reward_address_t *address)¶

Retrieves the string representation of an reward address.

This function provides access to the string form of a cardano_reward_address_t object. It allows for easy display and logging of the address in a human-readable format.

Usage Example:

cardano_reward_address_t* cardano_reward_address = NULL;
// Assume cardano_reward_address is previously created and valid
const char* address_string = cardano_reward_address_get_string(cardano_reward_address);

if (address_string != NULL)
{
  printf("Enterprise Address: %s\n", address_string);
}
else
{
  printf("Failed to retrieve string representation of the  reward address\n");
}

Note

The returned string is managed internally and should not be freed or modified by the caller. It remains valid as long as the cardano_reward_address_t object is not modified or freed.

Parameters:¶

const cardano_reward_address_t *address¶: [in] A pointer to the cardano_reward_address_t object whose string representation is to be retrieved.

Returns:¶

A pointer to a constant character string representing the reward address. Returns NULL if the address pointer is NULL or if the address cannot be properly serialized into a string form.

cardano_error_t cardano_reward_address_get_network_id(const cardano_reward_address_t *address, cardano_network_id_t *network_id)¶

Retrieves the network ID from a given Cardano reward address.

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

Usage Example:

cardano_reward_address_t* address = NULL;
cardano_network_id_t network_id;

cardano_error_t get_network_id = cardano_reward_address_get_network_id(address, &network_id);

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

cardano_reward_address_unref(&address);

Parameters:¶

const cardano_reward_address_t *address¶: [in] A constant pointer to the cardano_reward_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.

void cardano_reward_address_unref(cardano_reward_address_t **address)¶

Decrements the reward address’s reference count.

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

Parameters:¶

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

void cardano_reward_address_ref(cardano_reward_address_t *address)¶

Increments the reward address’s reference count.

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

Parameters:¶

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

size_t cardano_reward_address_refcount(const cardano_reward_address_t *address)¶

Retrieves the reward address’s current reference count.

Warning

Does not account for transitive references.

Parameters:¶

const cardano_reward_address_t *address¶: [in] Target reward address.

Returns:¶

Current reference count of the reward address.

void cardano_reward_address_set_last_error(cardano_reward_address_t *address, const char *message)¶

Sets the last error message for a given reward address.

This function records an error message in the reward 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_reward_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_reward_address_t *address¶: [inout] A pointer to the cardano_reward_address_t instance whose last error message is to be set. If the reward 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 reward address’s last_error will be set to an empty string, indicating no error.

const char *cardano_reward_address_get_last_error(const cardano_reward_address_t *address)¶

Retrieves the last error message recorded for a specific reward address.

This function returns a pointer to the null-terminated string containing the last error message set by cardano_reward_address_set_last_error for the given reward 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 reward address and must not be modified by the caller. The string remains valid until the next call to cardano_reward_address_set_last_error for the same reward address, or until the reward address is deallocated.

Parameters:¶

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

Returns:¶

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