Byron Address¶

typedef struct cardano_byron_address_t cardano_byron_address_t¶: Represents a Byron-era address in the Cardano blockchain.

cardano_error_t cardano_byron_address_from_credentials(cardano_blake2b_hash_t *root, cardano_byron_address_attributes_t attributes, cardano_byron_address_type_t type, cardano_byron_address_t **address)¶

Creates a Byron-era address from given credentials.

This function generates a cardano_byron_address_t object based on the provided root hash, address attributes, and address type.

Usage Example:

cardano_blake2b_hash_t* root_hash = ...; // Assume root_hash is initialized
cardano_byron_address_attributes_t attributes = { .derivation_path = "...", .magic = 0x1234 };
cardano_byron_address_t* byron_address = NULL;

cardano_error_t result = cardano_byron_address_from_credentials(
     root_hash, attributes,
     CARDANO_BYRON_ADDRESS_TYPE_PUBKEY,
     &byron_address);

if (result == CARDANO_SUCCESS && byron_address)
{
  // Byron address has been successfully created and can be used
  // Free the Byron address when done
  cardano_byron_address_unref(byron_address);
}
else
{
  // Handle error
}

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_byron_address_t object, including freeing it when it is no longer needed.

Parameters:¶

cardano_blake2b_hash_t *root¶: [in] A pointer to cardano_blake2b_hash_t representing the root hash of the address.
cardano_byron_address_attributes_t attributes¶: [in] A cardano_byron_address_attributes_t structure containing optional address attributes such as derivation path and network magic.
cardano_byron_address_type_t type¶: [in] The type of Byron address, defined by cardano_byron_address_type_t, which indicates whether the address is based on a public key, a script, or a redeem key.
cardano_byron_address_t **address¶: [out] A pointer to a pointer of cardano_byron_address_t where the newly created Byron address object will be stored.

Returns:¶

A cardano_error_t indicating the result of the operation. Returns CARDANO_SUCCESS on success or an appropriate error code on failure.

cardano_error_t cardano_byron_address_from_address(const cardano_address_t *address, cardano_byron_address_t **byron_address)¶

Converts a generic Cardano address to a Byron-era address.

This function attempts to convert a cardano_address_t object into a cardano_byron_address_t object.

Usage Example:

cardano_address_t* generic_address = ...; // Assume this is initialized and points to a Byron address
cardano_byron_address_t* byron_address = NULL;

cardano_error_t result = cardano_byron_address_from_address(generic_address, &byron_address);

if (result == CARDANO_SUCCESS && byron_address)
{
  // Byron address has been successfully converted and can be used
  // Free the Byron address when done
  cardano_byron_address_unref(byron_address);
}
else
{
  // Handle error
}

Note

The caller is responsible for managing the lifecycle of the created cardano_byron_address_t object, including freeing it when it is no longer needed.

Parameters:¶

const cardano_address_t *address¶: [in] A constant pointer to the generic cardano_address_t object to be converted.
cardano_byron_address_t **byron_address¶: [out] A pointer to a pointer of cardano_byron_address_t where the newly created Byron address object will be stored if the conversion is successful.

Returns:¶

A cardano_error_t indicating the result of the operation. Returns CARDANO_SUCCESS on successful conversion, CARDANO_ERROR_INVALID_ADDRESS_TYPE if the input address is not a valid Byron address, or other appropriate error codes for different failures.

cardano_address_t *cardano_byron_address_to_address(const cardano_byron_address_t *byron_address)¶

Converts a Byron-era address to a generic Cardano address.

This function converts a cardano_byron_address_t object to a cardano_address_t object.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is initialized
cardano_address_t* cardano_address = cardano_byron_address_to_address(byron_address);

if (cardano_address)
{
  // Use the generic Cardano address
  // Remember to free the Cardano address when done
  cardano_address_unref(&cardano_address);
}
else
{
  // Handle conversion failure
}

Note

If the conversion fails, NULL is returned. It is the caller’s responsibility to check the return value before using it.

Parameters:¶

const cardano_byron_address_t *byron_address¶: [in] A constant pointer to the cardano_byron_address_t object that represents the Byron-era address to be converted.

Returns:¶

A pointer to a new cardano_address_t object representing the generic Cardano address. This object represents a “strong reference” to the address, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object, including freeing it when it is no longer needed.

cardano_error_t cardano_byron_address_get_attributes(const cardano_byron_address_t *address, cardano_byron_address_attributes_t *attributes)¶

Retrieves attributes from a Byron-era address.

This function extracts the attributes associated with a Byron-era address encapsulated in a cardano_byron_address_t object. These attributes might include optional fields such as a derivation path or a network magic identifier, which were specific to the Byron address format.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is initialized
cardano_byron_address_attributes_t attributes;
cardano_error_t result = cardano_byron_address_get_attributes(byron_address, &attributes);

if (result == CARDANO_SUCCESS)
{
  // Use the attributes
}
else
{
  // Handle error
  printf("Failed to retrieve attributes: %d\n", result);
}

Note

The function assumes the address pointer and the attributes pointer are not NULL. If either is NULL, the function returns CARDANO_ERROR_POINTER_IS_NULL.

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_address_t object from which the attributes are to be retrieved.
cardano_byron_address_attributes_t *attributes¶: [out] A pointer to a cardano_byron_address_attributes_t structure where the attributes of the address will be stored.

Returns:¶

CARDANO_SUCCESS if the attributes were successfully retrieved, or an appropriate error code if an error occurred.

cardano_error_t cardano_byron_address_get_type(const cardano_byron_address_t *address, cardano_byron_address_type_t *type)¶

Retrieves the type of a Byron-era address.

This function extracts the type from a Byron-era address encapsulated in a cardano_byron_address_t object. The type determines the nature of the credentials used in the address, such as a public key, a script, or a redeem key.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is initialized
cardano_byron_address_type_t type;
cardano_error_t result = cardano_byron_address_get_type(byron_address, &type);

if (result == CARDANO_SUCCESS)
{
  // Use the retrieved type
  switch (type)
  {
    case CARDANO_BYRON_ADDRESS_TYPE_PUBKEY:
      printf("Address type is Public Key\n");
      break;
    case CARDANO_BYRON_ADDRESS_TYPE_SCRIPT:
      printf("Address type is Script\n");
      break;
    case CARDANO_BYRON_ADDRESS_TYPE_REDEEM:
      printf("Address type is Redeem Key\n");
      break;
    default:
      printf("Unknown address type\n");
  }
}
else
{
  // Handle error
  printf("Failed to retrieve address type: %d\n", result);
}

Note

The function assumes the address pointer and the type pointer are not NULL. If either is NULL, the function returns CARDANO_ERROR_POINTER_IS_NULL.

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_address_t object from which the type is to be retrieved.
cardano_byron_address_type_t *type¶: [out] A pointer to a cardano_byron_address_type_t variable where the type of the address will be stored.

Returns:¶

CARDANO_SUCCESS if the type was successfully retrieved, or an appropriate error code if an error occurred.

cardano_error_t cardano_byron_address_get_root(const cardano_byron_address_t *address, cardano_blake2b_hash_t **root)¶

Retrieves the root hash from a Byron-era address.

This function extracts the root hash associated with a Byron-era address, which is encapsulated in a cardano_byron_address_t object.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is initialized
cardano_blake2b_hash_t* root_hash = NULL;
cardano_error_t result = cardano_byron_address_get_root(byron_address, &root_hash);

if (result == CARDANO_SUCCESS)
{
  // Use the root hash
  // ...

  // Clean up
  cardano_blake2b_hash_unref(&root_hash);
}
else
{
  // Handle error
  printf("Failed to retrieve root hash: %d\n", result);
}

Note

The function assumes the address pointer is not NULL and that root is a valid double pointer. If either is NULL, the function returns CARDANO_ERROR_POINTER_IS_NULL.

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_address_t object from which the root hash is to be retrieved.
cardano_blake2b_hash_t **root¶: [out] A pointer to a pointer of cardano_blake2b_hash_t that will be set to point to the root hash of the address. The function will allocate memory for the root hash, and it is the caller’s responsibility to free it using cardano_blake2b_hash_unref when it is no longer needed.

Returns:¶

CARDANO_SUCCESS if the root hash was successfully retrieved, or an appropriate error code if an error occurred.

cardano_error_t cardano_byron_address_from_bytes(const byte_t *data, size_t size, cardano_byron_address_t **address)¶

Constructs a Byron-era address from a byte array.

This function creates a cardano_byron_address_t object from raw byte data, interpreting it as a serialized Byron address. It verifies the structure and validity of the data before constructing the address object.

Usage Example:

const byte_t address_data[] = {...}; // Assume this contains valid Byron address bytes
size_t address_data_size = sizeof(address_data);
cardano_byron_address_t* byron_address = NULL;
cardano_error_t result = cardano_byron_address_from_bytes(address_data, address_data_size, &byron_address);
if (result == CARDANO_SUCCESS) {
  // Byron address is successfully created and can be used
  // ...

  // Once done, clean up
  cardano_address_unref(&byron_address);
} else {
  printf("Failed to create Byron address from bytes: %d\n", result);
}

Note

The caller is responsible for managing the lifecycle of the created cardano_byron_address_t object. Specifically, once the address is no longer needed, the caller must release it by calling cardano_address_unref.

Parameters:¶

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

Returns:¶

CARDANO_SUCCESS if the Byron address is successfully created from the provided bytes, CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the byte array does not represent a valid Byron address, or CARDANO_ERROR_POINTER_IS_NULL if any pointer parameter is NULL.

size_t cardano_byron_address_get_bytes_size(const cardano_byron_address_t *address)¶

Retrieves the size in bytes of the serialized form of a Byron-era address.

This function calculates the size of the byte array needed to store the serialized form of a given cardano_byron_address_t object. This size is useful for allocating the correct amount of memory for serialization.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is a valid Byron address object
size_t required_size = cardano_byron_address_get_bytes_size(byron_address);

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

  if (buffer)
  {
    // Proceed to serialize the Byron address into the buffer
    ...
    free(buffer);
  }
}
else
{
  printf("Error determining the required size for the serialized Byron address.\n");
}

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_address_t object whose serialized size is to be determined.

Returns:¶

The size in bytes required to store the serialized form of the Byron address. Returns zero if the input address is NULL or if any other error occurs.

const byte_t *cardano_byron_address_get_bytes(const cardano_byron_address_t *address)¶

Retrieves a pointer to the internal byte array representation of a Byron-era address.

This function provides direct read-only access to the internal byte array that represents a Byron-era address in its serialized form. This is useful for operations that require direct access to the raw data of the address, such as hashing or verification.

Usage Example:

cardano_byron_address_t* byron_address = ...; // Assume this is a valid Byron address object
const byte_t* byte_data = cardano_byron_address_get_bytes(byron_address);

if (byte_data)
{
  // Use the byte data for reading purposes
  ...
}
else
{
  printf("Failed to access the byte data of the Byron address.\n");
}

Note

Modifying the data pointed to by the returned pointer is undefined behavior.

Parameters:¶

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

Returns:¶

A pointer to the constant byte array representing the serialized Byron address. If the input address is NULL, returns NULL. The data should not be modified, and the lifetime of the returned pointer is tied to the lifetime of the cardano_byron_address_t object.

cardano_error_t cardano_byron_address_to_bytes(const cardano_byron_address_t *address, byte_t *data, size_t size)¶

Serializes a Byron-era address into a byte array.

This function serializes the given cardano_byron_address_t object into a preallocated buffer in its raw byte form. The buffer size can be determined by calling cardano_byron_address_get_bytes_size prior to this function.

Usage Example:

cardano_byron_address_t* byron_address = cardano_byron_address_new(...);
size_t required_size = cardano_byron_address_get_bytes_size(byron_address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_byron_address_to_bytes(byron_address, buffer, required_size);

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

cardano_byron_address_unref(&byron_address);

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_address_t object that is to be serialized.
byte_t *data¶: [out] A pointer to the buffer where the serialized byte 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_byron_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 is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

cardano_error_t cardano_byron_address_from_base58(const char *data, size_t size, cardano_byron_address_t **address)¶

Creates a Byron-era address from a Base58-encoded string.

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

Usage Example:

const char* base58_address = "3P3QsMVK8...";
size_t base58_size = strlen(base58_address);
cardano_byron_address_t* byron_address = NULL;

cardano_error_t result = cardano_byron_address_from_base58(base58_address, base58_size, &byron_address);

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

  // Once done, ensure to clean up and release the Byron address
  cardano_byron_address_unref(&byron_address);
}
else
{
  printf("Failed to decode Byron address from Base58: %d\n", result);
}

Note

The function checks the format and validity of the Base58 string. It is the caller’s responsibility to ensure that the string is correctly formatted and of appropriate length. Malformed or incorrect Base58 data may lead to decoding errors.

Parameters:¶

const char *data¶: [in] A pointer to a character array containing the Base58-encoded representation of the address.
size_t size¶: [in] The size of the Base58 string in bytes.
cardano_byron_address_t **address¶: [out] A pointer to a pointer to cardano_byron_address_t that will be set to the address of the newly created Byron 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 Base58 data could not be decoded into a valid Byron address.

size_t cardano_byron_address_get_base58_size(const cardano_byron_address_t *address)¶

Retrieves the size in bytes of the Base58-encoded representation of a Byron-era address.

This function calculates the size necessary to store the Base58-encoded representation of a given cardano_byron_address_t address object, including the null-termination character.

Usage Example:

cardano_byron_address_t* byron_address = NULL;
// Assume byron_address is already created and valid
size_t base58_size = cardano_byron_address_get_base58_size(byron_address);

if (base58_size > 0)
{
  char* base58_string = (char*)malloc(base58_size);

  if (base58_string)
  {
    // Proceed to convert address to Base58 string
  }

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

Parameters:¶

const cardano_byron_address_t *address¶: [in] A pointer to a cardano_byron_address_t object whose Base58 size is to be retrieved.

Returns:¶

The size in bytes of the Base58-encoded representation of the address. Returns 0 if the address pointer is NULL or if the address is invalid.

cardano_error_t cardano_byron_address_to_base58(const cardano_byron_address_t *address, char *data, size_t size)¶

Converts a Byron-era address into a Base58-encoded string.

This function takes a cardano_byron_address_t object and converts it to its Base58 string representation. The resulting string is written into the provided data buffer, which must be large enough to hold the Base58 string and the null-termination character.

Usage Example:

cardano_byron_address_t* byron_address = NULL;
// Assume byron_address is previously created and valid
size_t base58_size = cardano_byron_address_get_base58_size(byron_address);
char* base58_string = (char*) malloc(base58_size);

if (base58_string)
{
  cardano_error_t result = cardano_byron_address_to_base58(byron_address, base58_string, base58_size);

  if (result == CARDANO_SUCCESS)
  {
    printf("Base58 representation: %s\n", base58_string);
  }
  else
  {
    printf("Failed to convert Byron address to Base58: %d\n", result);
  }

  free(base58_string);
}

Parameters:¶

const cardano_byron_address_t *address¶: [in] A pointer to the cardano_byron_address_t object to be converted.
char *data¶: [out] A pointer to a character buffer where the Base58-encoded string will be stored.
size_t size¶: [in] The size of the provided buffer in bytes. This size should be at least the value returned by cardano_byron_address_get_base58_size for this address.

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 Base58 representation including the null terminator.

const char *cardano_byron_address_get_string(const cardano_byron_address_t *address)¶

Retrieves the string representation of a byron era address.

This function provides access to the string representation of a cardano_byron_address_t object. The string is in Base58. 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_byron_address_t* byron_address = ...; // Assume this is initialized
const char* address_str = cardano_byron_address_get_string(byron_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_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_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_byron_address_t object.

cardano_error_t cardano_byron_address_get_network_id(const cardano_byron_address_t *address, cardano_network_id_t *network_id)¶

Retrieves the network ID from a given Cardano byron address.

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

Usage Example:

cardano_byron_address_t* address = NULL;
cardano_network_id_t network_id;

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

Parameters:¶

const cardano_byron_address_t *address¶: [in] A constant pointer to the cardano_byron_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_byron_address_unref(cardano_byron_address_t **address)¶

Decrements the byron address’s reference count.

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

Parameters:¶

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

void cardano_byron_address_ref(cardano_byron_address_t *address)¶

Increments the byron address’s reference count.

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

Parameters:¶

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

size_t cardano_byron_address_refcount(const cardano_byron_address_t *address)¶

Retrieves the byron address’s current reference count.

Warning

Does not account for transitive references.

Parameters:¶

const cardano_byron_address_t *address¶: [in] Target byron address.

Returns:¶

Current reference count of the byron address.

void cardano_byron_address_set_last_error(cardano_byron_address_t *address, const char *message)¶

Sets the last error message for a given byron address.

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

const char *cardano_byron_address_get_last_error(const cardano_byron_address_t *address)¶

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

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

Parameters:¶

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

Returns:¶

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