Enterprise Address¶

typedef struct cardano_enterprise_address_t cardano_enterprise_address_t¶

Represents an enterprise address in the Cardano blockchain ecosystem.

Enterprise addresses carry no stake rights, so using these addresses means that you are opting out of participation in the proof-of-stake protocol.

Note that using addresses with no stake rights effectively decreases the total amount of stake, which plays into the hands of a potential adversary.

cardano_error_t cardano_enterprise_address_from_credentials(cardano_network_id_t network_id, cardano_credential_t *payment, cardano_enterprise_address_t **enterprise_address)¶

Creates an enterprise address from specified network and payment credentials.

This function constructs a cardano_enterprise_address_t object by combining a network identifier and payment credentials. The resulting enterprise address does not include staking capabilities.

Usage Example:

cardano_credential_t payment_credentials = {...};  // Initialized elsewhere
cardano_enterprise_address_t* address = NULL;
cardano_error_t result = cardano_enterprise_address_from_credentials(CARDANO_NETWORK_ID_MAIN_NET, &payment_credentials, &address);

if (result == CARDANO_SUCCESS)
{
  // Use the address for transactions
  // Once done, ensure to clean up and release the enterprise address
  cardano_enterprise_address_unref(&address);
}
else
{
  printf("Failed to create enterprise address: %d\n", result);
}

Note

The caller is responsible for managing the lifecycle of the created cardano_enterprise_address_t object. This involves ensuring that cardano_enterprise_address_unref is called to free the address object when it is no longer needed, to avoid memory leaks.

Parameters:¶

cardano_network_id_t network_id¶: [in] The network identifier, which specifies the Cardano network (e.g., mainnet, testnet).
cardano_credential_t *payment¶: [in] A pointer to a cardano_credential_t object representing the payment credentials.
cardano_enterprise_address_t **enterprise_address¶: [out] A pointer to a pointer to cardano_enterprise_address_t that will be set to the address of the newly created enterprise address object upon successful address creation.

Returns:¶

Returns CARDANO_SUCCESS if the enterprise address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if the payment or enterprise_address pointer is NULL.

cardano_error_t cardano_enterprise_address_from_address(const cardano_address_t *address, cardano_enterprise_address_t **enterprise_address)¶

Converts a general Cardano address to an enterprise address.

This function takes an existing cardano_address_t object and attempts to create a corresponding cardano_enterprise_address_t object.

Usage Example:

cardano_address_t* general_address = NULL;
// Assume general_address is previously created and represents a valid Cardano address
cardano_enterprise_address_t* enterprise_address = NULL;
cardano_error_t result = cardano_enterprise_address_from_address(general_address, &enterprise_address);

if (result == CARDANO_SUCCESS)
{
  // The address has been successfully converted to an enterprise address
  // Use the enterprise address for transactions

  // Once done, ensure to clean up and release the enterprise address
  cardano_enterprise_address_unref(&enterprise_address);
}
else
{
  printf("Failed to convert to enterprise address: %d\n", result);
}

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_enterprise_address_t object, including calling cardano_enterprise_address_unref to free the object when it is no longer needed.

Parameters:¶

const cardano_address_t *address¶: [in] A pointer to the cardano_address_t object that is to be converted into an enterprise address.
cardano_enterprise_address_t **enterprise_address¶: [out] A pointer to a pointer to cardano_enterprise_address_t that will be set to the address of the newly created enterprise address object upon successful conversion.

Returns:¶

Returns CARDANO_SUCCESS if the conversion was successful. Returns CARDANO_ERROR_POINTER_IS_NULL if the address or enterprise_address pointer is NULL. Returns CARDANO_ERROR_INVALID_ADDRESS_FORMAT if the provided address cannot be converted to an enterprise address.

cardano_address_t *cardano_enterprise_address_to_address(const cardano_enterprise_address_t *enterprise_address)¶

Converts an enterprise address to a general Cardano address.

This function takes a cardano_enterprise_address_t object representing an enterprise address and converts it to a general cardano_address_t object.

Usage Example:

cardano_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is previously created and represents a valid enterprise address
cardano_address_t* general_address = cardano_enterprise_address_to_address(enterprise_address);

if (general_address != NULL)
{
  // The enterprise 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 enterprise 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_enterprise_address_t *enterprise_address¶: [in] A pointer to the cardano_enterprise_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 enterprise_address is NULL or if the conversion fails due to an invalid address format.

cardano_credential_t *cardano_enterprise_address_get_payment_credential(cardano_enterprise_address_t *enterprise_address)¶

Retrieves the payment credential from an enterprise address.

This function extracts the payment credential from a cardano_enterprise_address_t object.

Usage Example:

cardano_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is previously created and represents a valid enterprise address
cardano_credential_t* payment_credential = cardano_enterprise_address_get_payment_credential(enterprise_address);

if (payment_credential != NULL)
{
  // The payment credential can be used to initiate transactions or for other purposes
  // Once done with the credential, ensure to clean up and release it
  cardano_credential_unref(&payment_credential);
}
else
{
  printf("Failed to retrieve payment credential from enterprise 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_enterprise_address_t *enterprise_address¶: [in] A pointer to the cardano_enterprise_address_t object from which the payment credential is to be retrieved.

Returns:¶

A pointer to a cardano_credential_t object representing the payment credential. Returns NULL if the enterprise_address is NULL.

cardano_error_t cardano_enterprise_address_from_bytes(const byte_t *data, size_t size, cardano_enterprise_address_t **address)¶

Creates an enterprise address from a byte array.

This function constructs a cardano_enterprise_address_t object by decoding a byte array that represents an enterprise address in serialized form.

Usage Example:

byte_t serialized_address[] = { ... };  // Example serialized data
size_t serialized_size = sizeof(serialized_address);
cardano_enterprise_address_t* enterprise_address = NULL;

cardano_error_t result = cardano_enterprise_address_from_bytes(serialized_address, serialized_size, &enterprise_address);

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

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_enterprise_address_t object, including ensuring that cardano_enterprise_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 enterprise address data.
size_t size¶: [in] The size of the byte array in bytes.
cardano_enterprise_address_t **address¶: [out] A pointer to a pointer to cardano_enterprise_address_t that will be set to the address of the newly created enterprise 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 enterprise address.

size_t cardano_enterprise_address_get_bytes_size(const cardano_enterprise_address_t *address)¶

Retrieves the size in bytes required to serialize an enterprise address.

This function calculates the size necessary to store the serialized byte array representation of a given cardano_enterprise_address_t object. This size is useful for allocating buffer space before serializing an enterprise address into its binary form.

Usage Example:

cardano_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is already created and valid
size_t required_size = cardano_enterprise_address_get_bytes_size(enterprise_address);

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

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

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

Parameters:¶

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

Returns:¶

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

const byte_t *cardano_enterprise_address_get_bytes(const cardano_enterprise_address_t *address)¶

Retrieves the byte array representation of an enterprise address.

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

Usage Example:

cardano_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is already created and valid
const byte_t* address_bytes = cardano_enterprise_address_get_bytes(enterprise_address);

if (address_bytes != NULL)
{
  // Process or transmit the byte array
}
else
{
  printf("Failed to retrieve byte array from enterprise 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_enterprise_address_t object is not modified or freed. Use cardano_enterprise_address_get_bytes_size to determine the size of the byte array.

Parameters:¶

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

Returns:¶

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

cardano_error_t cardano_enterprise_address_to_bytes(const cardano_enterprise_address_t *address, byte_t *data, size_t size)¶

Serializes an enterprise address into a byte array.

This function takes a cardano_enterprise_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_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is previously created and valid
size_t required_size = cardano_enterprise_address_get_bytes_size(enterprise_address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_enterprise_address_to_bytes(enterprise_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 enterprise address: %d\n", result);
  }

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

Parameters:¶

const cardano_enterprise_address_t *address¶: [in] A pointer to the cardano_enterprise_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_enterprise_address_get_bytes_size for this address.

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_enterprise_address_from_bech32(const char *data, size_t size, cardano_enterprise_address_t **address)¶

Creates an enterprise address from a Bech32-encoded string.

This function constructs a cardano_enterprise_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_enterprise_address_t* enterprise_address = NULL;

cardano_error_t result = cardano_enterprise_address_from_bech32(bech32_data, bech32_size, &enterprise_address);

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

  // Once done, ensure to clean up and release the enterprise address
  cardano_enterprise_address_unref(&enterprise_address);
}
else
{
  printf("Failed to decode enterprise 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_enterprise_address_t **address¶: [out] A pointer to a pointer to cardano_enterprise_address_t that will be set to the address of the newly created enterprise 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 enterprise address.

size_t cardano_enterprise_address_get_bech32_size(const cardano_enterprise_address_t *address)¶

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

This function calculates the size necessary to store the Bech32-encoded representation of a given cardano_enterprise_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_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is already created and valid
size_t bech32_size = cardano_enterprise_address_get_bech32_size(enterprise_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_enterprise_address_t *address¶: [in] A pointer to the cardano_enterprise_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_enterprise_address_to_bech32(const cardano_enterprise_address_t *address, char *data, size_t size)¶

Converts an enterprise address to a Bech32-encoded string.

This function takes a cardano_enterprise_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_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is previously created and valid
size_t required_size = cardano_enterprise_address_get_bech32_size(enterprise_address) + 1; // +1 for null-termination
char* bech32_string = (char*) malloc(required_size);
if (bech32_string)
{
  cardano_error_t result = cardano_enterprise_address_to_bech32(enterprise_address, bech32_string, required_size);
  if (result == CARDANO_SUCCESS)
  {
    printf("Bech32 representation: %s\n", bech32_string);
  }
  else
  {
    printf("Failed to convert enterprise 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_enterprise_address_t *address¶: [in] A pointer to the cardano_enterprise_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_enterprise_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_enterprise_address_get_string(const cardano_enterprise_address_t *address)¶

Retrieves the string representation of an enterprise address.

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

Usage Example:

cardano_enterprise_address_t* enterprise_address = NULL;
// Assume enterprise_address is previously created and valid
const char* address_string = cardano_enterprise_address_get_string(enterprise_address);

if (address_string != NULL)
{
  printf("Enterprise Address: %s\n", address_string);
}
else
{
  printf("Failed to retrieve string representation of the enterprise 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_enterprise_address_t object is not modified or freed.

Parameters:¶

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

Returns:¶

A pointer to a constant character string representing the enterprise 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_enterprise_address_get_network_id(const cardano_enterprise_address_t *address, cardano_network_id_t *network_id)¶

Retrieves the network ID from a given Cardano enterprise address.

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

Usage Example:

cardano_enterprise_address_t* address = NULL;
cardano_network_id_t network_id;

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

Parameters:¶

const cardano_enterprise_address_t *address¶: [in] A constant pointer to the cardano_enterprise_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_enterprise_address_unref(cardano_enterprise_address_t **address)¶

Decrements the enterprise address’s reference count.

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

Parameters:¶

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

void cardano_enterprise_address_ref(cardano_enterprise_address_t *address)¶

Increments the enterprise address’s reference count.

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

Parameters:¶

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

size_t cardano_enterprise_address_refcount(const cardano_enterprise_address_t *address)¶

Retrieves the enterprise address’s current reference count.

Warning

Does not account for transitive references.

Parameters:¶

const cardano_enterprise_address_t *address¶: [in] Target enterprise address.

Returns:¶

Current reference count of the enterprise address.

void cardano_enterprise_address_set_last_error(cardano_enterprise_address_t *address, const char *message)¶

Sets the last error message for a given enterprise address.

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

const char *cardano_enterprise_address_get_last_error(const cardano_enterprise_address_t *address)¶

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

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

Parameters:¶

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

Returns:¶

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