Base Address¶

typedef struct cardano_base_address_t cardano_base_address_t¶: Defines a pointer to a structure representing a Cardano base address.

cardano_error_t cardano_base_address_from_credentials(cardano_network_id_t network_id, cardano_credential_t *payment, cardano_credential_t *stake, cardano_base_address_t **base_address)¶

Constructs a Cardano base address from payment and stake credentials.

This function creates a base address by combining payment and stake credentials, along with specifying the network ID (either mainnet or testnet).

Usage Example:

cardano_credential_t* payment_credential = ...; // Assume this is initialized
cardano_credential_t* stake_credential = ...; // Assume this is initialized
cardano_base_address_t* base_address = NULL;
cardano_error_t result = cardano_base_address_from_credentials(
    CARDANO_NETWORK_ID_MAIN_NET, payment_credential, stake_credential, &base_address);

if (result == CARDANO_SUCCESS)
{
  // Use the base_address
  cardano_base_address_unref(&base_address);
}

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_base_address_t object, which includes freeing it when it is no longer needed by calling cardano_base_address_unref.

Parameters:¶

cardano_network_id_t network_id¶: [in] The network identifier, specifying whether the address is for mainnet or testnet.
cardano_credential_t *payment¶: [in] The payment credential, which is a pointer to a cardano_credential_t that defines who controls the funds.
cardano_credential_t *stake¶: [in] The stake credential, which is a pointer to a cardano_credential_t that who controls staking rewards are directed.
cardano_base_address_t **base_address¶: [out] A pointer to a pointer to cardano_base_address_t that will hold the address if the function succeeds.

Returns:¶

Returns CARDANO_SUCCESS if the address was successfully created, otherwise it returns an error code indicating what went wrong (e.g., CARDANO_ERROR_POINTER_IS_NULL if any input pointers are NULL).

cardano_error_t cardano_base_address_from_address(const cardano_address_t *address, cardano_base_address_t **base_address)¶

Converts a general Cardano address to a base address.

This function takes a general Cardano address and attempts to interpret it as a base address, which is a specific type of Cardano address that includes separate payment and stake credentials. If the conversion is successful, a new cardano_base_address_t object is created.

Usage Example:

cardano_address_t* general_address = ...; // Assume this is initialized as a general Cardano address
cardano_base_address_t* base_address = NULL;
cardano_error_t result = cardano_base_address_from_address(general_address, &base_address);

if (result == CARDANO_SUCCESS)
{
  // The conversion was successful, and base_address can now be used
  cardano_base_address_unref(&base_address);
}
else
{
  printf("Failed to convert to base address: %d\n", result);
}

Note

The newly created cardano_base_address_t object is fully managed by the caller, who is responsible for freeing it when it is no longer needed by calling cardano_base_address_unref.

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the cardano_address_t object representing the general Cardano address to be converted.
cardano_base_address_t **base_address¶: [out] A pointer to a pointer to cardano_base_address_t that will hold the base address object if the conversion is successful.

Returns:¶

Returns CARDANO_SUCCESS if the conversion is successful. If the address is not of a base address type, returns an appropriate error code such as CARDANO_ERROR_INVALID_ADDRESS_TYPE. If the address is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

cardano_address_t *cardano_base_address_to_address(const cardano_base_address_t *base_address)¶

Converts a base address to a general Cardano address.

This function takes a cardano_base_address_t object and converts it into a general cardano_address_t object. This allows for the use of the base address in any context that requires a generic address format.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
cardano_address_t* general_address = cardano_base_address_to_address(base_address);

if (general_address)
{
  // The conversion was successful, and general_address can now be used
  cardano_address_unref(&general_address);
}
else
{
  printf("Failed to convert base address to general address\n");
}

Note

The newly created cardano_address_t object is fully managed by the caller, who is responsible for freeing it when it is no longer needed by calling cardano_address_unref.

Parameters:¶

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

Returns:¶

A pointer to a new cardano_address_t object that represents the general Cardano address. If the conversion fails due to memory allocation issues, returns NULL.

cardano_credential_t *cardano_base_address_get_payment_credential(cardano_base_address_t *base_address)¶

Retrieves the payment credential from a base address.

This function extracts the payment credential from a cardano_base_address_t object. The payment credential is a hash of a public key or a script that is authorized to spend funds from the address.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
cardano_credential_t* payment_credential = cardano_base_address_get_payment_credential(base_address);

if (payment_credential)
{
  // Use the payment credential
  cardano_credential_unref(&payment_credential);
}
else
{
   printf("Failed to retrieve payment credential from base address\n");
}

Note

The newly created cardano_credential_t object is fully managed by the caller, who is responsible for freeing it when it is no longer needed by calling cardano_credential_unref.

Parameters:¶

cardano_base_address_t *base_address¶: [in] A constant pointer to the cardano_base_address_t object from which the payment credential is to be retrieved.

Returns:¶

A pointer to a cardano_credential_t object that holds the payment credential. If the base address does not have a payment credential or if an error occurs, returns NULL.

cardano_credential_t *cardano_base_address_get_stake_credential(cardano_base_address_t *base_address)¶

Retrieves the stake credential from a base address.

This function extracts the stake credential from a cardano_base_address_t object. The stake credential is a hash of a public key or a script that is in control of the staking rewards from the address.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
cardano_credential_t* stake_credential = cardano_base_address_get_stake_credential(base_address);

if (stake_credential)
{
  // Use the stake credential
  cardano_credential_unref(&stake_credential);
}
else
{
   printf("Failed to retrieve stake credential from base address\n");
}

Note

The newly created cardano_credential_t object is fully managed by the caller, who is responsible for freeing it when it is no longer needed by calling cardano_credential_unref.

Parameters:¶

cardano_base_address_t *base_address¶: [in] A constant pointer to the cardano_base_address_t object from which the stake credential is to be retrieved.

Returns:¶

A pointer to a cardano_credential_t object that holds the stake credential. If the base address does not have a stake credential or if an error occurs, returns NULL.

cardano_error_t cardano_base_address_from_bytes(const byte_t *data, size_t size, cardano_base_address_t **address)¶

Creates a base address from a serialized byte array.

This function constructs a cardano_base_address_t object from a byte array that contains serialized address data. It attempts to deserialize the data and create a base address object from it.

Usage Example:

const byte_t serialized_data[] = {0x00, 0x01, 0x02, ...}; // example serialized data
size_t size = sizeof(serialized_data);
cardano_base_address_t* base_address = NULL;
cardano_error_t result = cardano_base_address_from_bytes(serialized_data, size, &base_address);

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

  // Once done, ensure to clean up and release the base address
  cardano_address_unref(&base_address);
}
else
{
  printf("Failed to create base address from bytes: %d\n", result);
}

Note

The newly created cardano_base_address_t object is fully managed by the caller, who is responsible for freeing it when it is no longer needed by calling cardano_address_unref.

Parameters:¶

const byte_t *data¶: [in] A pointer to the byte array containing the serialized base address data.
size_t size¶: [in] The size of the byte array in bytes.
cardano_base_address_t **address¶: [out] A pointer to a pointer to cardano_base_address_t. On successful deserialization, this will point to a newly allocated base address object.

Returns:¶

A cardano_error_t indicating the result of the function call. This will be CARDANO_SUCCESS if the address was successfully created from the provided data. If an error occurs, a corresponding error code will be returned.

size_t cardano_base_address_get_bytes_size(const cardano_base_address_t *address)¶

Retrieves the size of the byte array needed to serialize a base address.

This function calculates the size in bytes that a serialized form of the specified cardano_base_address_t object would occupy. This size is necessary to allocate a buffer of appropriate size for serialization.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
size_t required_size = cardano_base_address_get_bytes_size(base_address);

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

  if (buffer)
  {
    // Proceed to serialize the base address
  }
  free(buffer);
}
else
{
  printf("Failed to determine the size needed for serialization\n");
}

Parameters:¶

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

Returns:¶

The size in bytes required to serialize the base address. If the input address is NULL, the function returns 0.

const byte_t *cardano_base_address_get_bytes(const cardano_base_address_t *address)¶

Retrieves a pointer to the internal byte array representation of a base address.

This function provides access to the internal byte array that represents the serialized form of a cardano_base_address_t object. The data returned by this function is useful for operations that require direct access to the serialized address, such as hashing or networking.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
const byte_t* byte_data = cardano_base_address_get_bytes(base_address);

if (byte_data)
{
  // Use the byte array for operations like sending over a network
}
else
{
  printf("Failed to retrieve byte data from base address\n");
}

Parameters:¶

const cardano_base_address_t *address¶: [in] A constant pointer to the cardano_base_address_t object from which the byte array is to be retrieved. The object must not be NULL.

Returns:¶

A pointer to the constant byte array that represents the serialized base address. If the input address is NULL, returns NULL. The data returned by this function should not be modified or freed by the caller, as it is managed internally by the Cardano library.

cardano_error_t cardano_base_address_to_bytes(const cardano_base_address_t *address, byte_t *data, size_t size)¶

Serializes a base address into a provided byte array.

This function serializes the specified cardano_base_address_t object into a byte array provided by the caller. The size of the buffer must be sufficient to hold the serialized data; the required size can be obtained by calling cardano_base_address_get_bytes_size.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
size_t required_size = cardano_base_address_get_bytes_size(base_address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_base_address_to_bytes(base_address, buffer, required_size);

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

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

cardano_base_address_unref(&base_address);

Parameters:¶

const cardano_base_address_t *address¶: [in] A constant pointer to the cardano_base_address_t object to be serialized.
byte_t *data¶: [out] A pointer to the buffer where the serialized data will be written. This buffer must be pre-allocated by the caller.
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_base_address_get_bytes_size to ensure successful serialization.

Returns:¶

Returns CARDANO_SUCCESS if the serialization 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.

cardano_error_t cardano_base_address_from_bech32(const char *data, size_t size, cardano_base_address_t **address)¶

Creates a base address from a Bech32 encoded string.

This function decodes a Bech32 encoded string and constructs a cardano_base_address_t object. The Bech32 string should correctly represent a Cardano base address according to the Cardano address specifications. This function will parse the string and if valid, will allocate and initialize a new base address object.

Usage Example:

const char* bech32_data = "addr1qxy...";
size_t bech32_size = strlen(bech32_data);
cardano_base_address_t* base_address = NULL;

cardano_error_t result = cardano_base_address_from_bech32(bech32_data, bech32_size, &base_address);

if (result == CARDANO_SUCCESS && base_address != NULL)
{
  // The base address has been successfully created
  // Use the base_address for operations
}
else
{
  printf("Failed to create base address from Bech32 data: %d\n", result);
}

// Clean up
cardano_base_address_unref(base_address);

Note

The caller is responsible for freeing the created cardano_base_address_t object using the cardano_base_address_unref function when it is no longer needed.

Parameters:¶

const char *data¶: [in] A pointer to the character array containing the Bech32 encoded address.
size_t size¶: [in] The length of the character array pointed to by data.
cardano_base_address_t **address¶: [out] A pointer to a pointer to cardano_base_address_t. If the decoding is successful, this will be set to point to the newly created base address object.

Returns:¶

Returns CARDANO_SUCCESS if the base address is successfully created from the Bech32 string. Returns CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the Bech32 string does not conform to the expected format or if the decoding fails. Returns CARDANO_ERROR_POINTER_IS_NULL if any of the input pointers are NULL.

size_t cardano_base_address_get_bech32_size(const cardano_base_address_t *address)¶

Calculates the size of the Bech32 encoded string of a base address.

This function calculates the length of the Bech32 string that would be generated from the given cardano_base_address_t object. This size includes the null terminator needed for string termination in C.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
size_t bech32_size = cardano_base_address_get_bech32_size(base_address);

if (bech32_size > 0)
{

  char* bech32_string = (char*)malloc(bech32_size);

  if (bech32_string)
  {
    // Proceed to encode or use the bech32_string as needed
    free(bech32_string);
  }
}

Parameters:¶

const cardano_base_address_t *address¶: [in] A constant pointer to the cardano_base_address_t object whose Bech32 string size is to be calculated.

Returns:¶

The size in bytes of the Bech32 string representation of the address, including the null terminator. If the input address is NULL, returns 0.

cardano_error_t cardano_base_address_to_bech32(const cardano_base_address_t *address, char *data, size_t size)¶

Encodes a base address into a Bech32 formatted string.

This function converts a cardano_base_address_t object into its corresponding Bech32 string representation. The caller must provide a buffer of sufficient size to hold the Bech32 encoded string, which can be determined by cardano_base_address_get_bech32_size.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
size_t bech32_size = cardano_base_address_get_bech32_size(base_address);

char* bech32_string = (char*)malloc(bech32_size);

if (bech32_string)
{
  cardano_error_t result = cardano_base_address_to_bech32(base_address, bech32_string, bech32_size);

  if (result == CARDANO_SUCCESS)
  {
    printf("Bech32 Address: %s\n", bech32_string);
  }
  else
  {
    printf("Failed to encode base address to Bech32: %d\n", result);
  }

  free(bech32_string);
}

Parameters:¶

const cardano_base_address_t *address¶: [in] A constant pointer to the cardano_base_address_t object to be encoded.
char *data¶: [out] A pointer to a buffer where the Bech32 string will be written.
size_t size¶: [in] The size of the buffer provided in data. This size must be at least as large as the value returned by cardano_base_address_get_bech32_size to ensure successful encoding.

Returns:¶

Returns CARDANO_SUCCESS if the address was successfully encoded into Bech32 format. If the provided buffer is too small, returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE. If address or data is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

const char *cardano_base_address_get_string(const cardano_base_address_t *address)¶

Retrieves the string representation of a base address.

This function provides access to the string representation of a cardano_base_address_t object. The string is in Bech32 or another. This function does not allocate new memory for the string; instead, it returns a pointer to the internal representation within the object.

Usage Example:

cardano_base_address_t* base_address = ...; // Assume this is initialized
const char* address_str = cardano_base_address_get_string(base_address);

if (address_str)
{
  printf("Base Address: %s\n", address_str);
}
else
{
  printf("Failed to retrieve string representation of the base address.\n");
}

Parameters:¶

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

Returns:¶

A constant pointer to the internal string representation of the address. If the address is NULL, returns NULL. The returned string should not be modified or freed by the caller, as it is managed internally by the cardano_base_address_t object.

cardano_error_t cardano_base_address_get_network_id(const cardano_base_address_t *address, cardano_network_id_t *network_id)¶

Retrieves the network ID from a given Cardano base address.

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

Usage Example:

cardano_base_address_t* address = NULL;
cardano_network_id_t network_id;

cardano_error_t get_network_id = cardano_base_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_base_address_unref(&address);

Parameters:¶

const cardano_base_address_t *address¶: [in] A constant pointer to the cardano_base_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_base_address_unref(cardano_base_address_t **address)¶

Decrements the base address’s reference count.

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

Parameters:¶

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

void cardano_base_address_ref(cardano_base_address_t *address)¶

Increments the base address’s reference count.

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

Parameters:¶

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

size_t cardano_base_address_refcount(const cardano_base_address_t *address)¶

Retrieves the base address’s current reference count.

Warning

Does not account for transitive references.

Parameters:¶

const cardano_base_address_t *address¶: [in] Target base address.

Returns:¶

Current reference count of the base address.

void cardano_base_address_set_last_error(cardano_base_address_t *address, const char *message)¶

Sets the last error message for a given base address.

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

const char *cardano_base_address_get_last_error(const cardano_base_address_t *address)¶

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

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

Parameters:¶

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

Returns:¶

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