Pointer Address

typedef struct cardano_pointer_address_t cardano_pointer_address_t

Represents a pointer address in the Cardano blockchain ecosystem.

A pointer address indirectly specifies the stake key that should control the stake for the address. It references a stake key by a stake key pointer, which is a location on the blockchain of the stake key registration certificate for that key.

cardano_error_t cardano_pointer_address_from_credentials(cardano_network_id_t network_id, cardano_credential_t *payment, cardano_stake_pointer_t pointer, cardano_pointer_address_t **pointer_address)

Creates a pointer address from network and payment credentials and a stake pointer.

This function constructs a cardano_pointer_address_t object by using a network identifier, payment credentials, and a stake pointer. The stake pointer directs to a stake key registration certificate on the blockchain, allowing the address to indirectly specify staking rights without embedding a stake key.

Usage Example: 

cardano_credential_t* payment_credential = ...;     // Initialized elsewhere
cardano_stake_pointer_t stake_pointer = { 5756214, 1, 0 };  // Example pointer to a stake key registration
cardano_pointer_address_t* pointer_address = NULL;
cardano_error_t result = cardano_pointer_address_from_credentials(
     CARDANO_NETWORK_ID_MAIN_NET,
     payment_credentials,
     stake_pointer,
     &pointer_address);

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

Note

The caller is responsible for managing the lifecycle of the created cardano_pointer_address_t object, including ensuring that cardano_pointer_address_unref is called to free the address object when it is no longer needed, to prevent 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_stake_pointer_t pointer

[in] A cardano_stake_pointer_t structure that specifies the location of the stake key registration certificate on the blockchain.

cardano_pointer_address_t **pointer_address

[out] A pointer to a pointer to cardano_pointer_address_t that will be set to the address of the newly created pointer address object upon successful address creation.

Returns:

Returns CARDANO_SUCCESS if the pointer address was successfully created. Returns CARDANO_ERROR_POINTER_IS_NULL if any of the pointers (payment or pointer_address) are NULL.

cardano_error_t cardano_pointer_address_from_address(const cardano_address_t *address, cardano_pointer_address_t **pointer_address)

Converts a general Cardano address to a pointer address.

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

Usage Example: 

cardano_address_t* general_address = NULL;
// Assume general_address is previously created and represents a valid Cardano address
cardano_pointer_address_t* pointer_address = NULL;
cardano_error_t result = cardano_pointer_address_from_address(general_address, &pointer_address);

if (result == CARDANO_SUCCESS)
{
  // The address has been successfully converted to a pointer address
  // Use the pointer address as needed

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

Note

It is the caller’s responsibility to manage the lifecycle of the created cardano_pointer_address_t object, including calling cardano_pointer_address_unref to free the address 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 a pointer address.

cardano_pointer_address_t **pointer_address

[out] A pointer to a pointer to cardano_pointer_address_t that will be set to the address of the newly created pointer address object upon successful conversion.

Returns:

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

cardano_address_t *cardano_pointer_address_to_address(const cardano_pointer_address_t *pointer_address)

Converts a pointer address to a general Cardano address.

This function takes a cardano_pointer_address_t object representing a pointer address and converts it back to a general cardano_address_t object. This is useful for operations that require the use of a generic address format instead of a pointer-specific format, particularly in interfaces that do not support the direct use of pointer addresses.

Usage Example: 

cardano_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is previously created and represents a valid pointer address
cardano_address_t* general_address = cardano_pointer_address_to_address(pointer_address);

if (general_address != NULL)
{
  // The pointer 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 pointer 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_pointer_address_t *pointer_address

[in] A pointer to the cardano_pointer_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 pointer_address is NULL.

cardano_credential_t *cardano_pointer_address_get_payment_credential(cardano_pointer_address_t *pointer_address)

Retrieves the payment credential from a pointer address.

This function extracts the payment credential from a cardano_pointer_address_t object.

Usage Example: 

cardano_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is previously created and represents a valid pointer address
const cardano_credential_t* payment_credential = cardano_pointer_address_get_payment_credential(pointer_address);

if (payment_credential != NULL)
{
  // The payment credential can be used to initiate transactions or for other purposes

  cardano_credential_unref(&payment_credential);
}
else
{
  printf("Failed to retrieve payment credential from pointer 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_pointer_address_t *pointer_address

[in] A pointer to the cardano_pointer_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 pointer_address is NULL.

cardano_error_t cardano_pointer_address_get_stake_pointer(const cardano_pointer_address_t *address, cardano_stake_pointer_t *pointer)

Retrieves the stake pointer from a pointer address.

This function extracts the stake pointer from a cardano_pointer_address_t object.

Usage Example: 

cardano_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is previously created and represents a valid pointer address
cardano_stake_pointer_t stake_pointer;
cardano_error_t result = cardano_pointer_address_get_stake_pointer(pointer_address, &stake_pointer);

if (result == CARDANO_SUCCESS)
{
  printf("Stake Pointer - Slot: %llu, Tx Index: %llu, Cert Index: %llu\n",
         stake_pointer.slot, stake_pointer.tx_index, stake_pointer.cert_index);
}
else
{
  printf("Failed to retrieve stake pointer from address: %d\n", result);
}

Parameters:
const cardano_pointer_address_t *address

[in] A pointer to the cardano_pointer_address_t object from which the stake pointer is to be retrieved.

cardano_stake_pointer_t *pointer

[out] A pointer to a cardano_stake_pointer_t structure that will be populated with the stake pointer information if the retrieval is successful.

Returns:

Returns CARDANO_SUCCESS if the stake pointer was successfully retrieved. Returns CARDANO_ERROR_POINTER_IS_NULL if the address or pointer argument is NULL.

cardano_error_t cardano_pointer_address_from_bytes(const byte_t *data, size_t size, cardano_pointer_address_t **address)

Creates a pointer address from a byte array.

This function constructs a cardano_pointer_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_pointer_address_t* pointer_address = NULL;

cardano_error_t result = cardano_pointer_address_from_bytes(serialized_address, serialized_size, &pointer_address);

if (result == CARDANO_SUCCESS)
{
  // Use the pointer address as needed
  // Once done, ensure to clean up and release the pointer address
  cardano_pointer_address_unref(&pointer_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_pointer_address_t object, including ensuring that cardano_pointer_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_pointer_address_t **address

[out] A pointer to a pointer to cardano_pointer_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_pointer_address_get_bytes_size(const cardano_pointer_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_pointer_address_t object.

Usage Example: 

cardano_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is already created and valid
size_t required_size = cardano_pointer_address_get_bytes_size(pointer_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_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_address_get_bytes(const cardano_pointer_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_pointer_address_t object.

Usage Example: 

cardano_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is already created and valid
const byte_t* address_bytes = cardano_pointer_address_get_bytes(pointer_address);
size_t bytes_size = cardano_pointer_address_get_bytes_size(pointer_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_pointer_address_t object is not modified or freed. Use cardano_pointer_address_get_bytes_size to determine the size of the byte array.

Parameters:
const cardano_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_address_to_bytes(const cardano_pointer_address_t *address, byte_t *data, size_t size)

Serializes a pointer address into a byte array.

This function takes a cardano_pointer_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_pointer_address_t* pointer_address = NULL;
// Assume pointer_address is previously created and valid
size_t required_size = cardano_pointer_address_get_bytes_size(pointer_address);
byte_t* buffer = (byte_t*)malloc(required_size);

if (buffer)
{
  cardano_error_t result = cardano_pointer_address_to_bytes(pointer_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_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_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_pointer_address_from_bech32(const char *data, size_t size, cardano_pointer_address_t **address)

Creates an enterprise address from a Bech32-encoded string.

This function constructs a cardano_pointer_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_pointer_address_t* cardano_pointer = NULL;

cardano_error_t result = cardano_pointer_address_from_bech32(bech32_data, bech32_size, &cardano_pointer);

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

  // Once done, ensure to clean up and release the enterprise address
  cardano_pointer_address_unref(&cardano_pointer);
}
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_pointer_address_t **address

[out] A pointer to a pointer to cardano_pointer_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_pointer_address_get_bech32_size(const cardano_pointer_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_pointer_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_pointer_address_t* cardano_pointer = NULL;
// Assume cardano_pointer is already created and valid
size_t bech32_size = cardano_pointer_address_get_bech32_size(cardano_pointer);

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_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_address_to_bech32(const cardano_pointer_address_t *address, char *data, size_t size)

Converts an enterprise address to a Bech32-encoded string.

This function takes a cardano_pointer_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_pointer_address_t* cardano_pointer = NULL;
// Assume cardano_pointer is previously created and valid
size_t required_size = cardano_pointer_address_get_bech32_size(cardano_pointer) + 1; // +1 for null-termination
char* bech32_string = (char*) malloc(required_size);
if (bech32_string)
{
  cardano_error_t result = cardano_pointer_address_to_bech32(cardano_pointer, 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_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_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_pointer_address_get_string(const cardano_pointer_address_t *address)

Retrieves the string representation of an enterprise address.

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

Usage Example: 

cardano_pointer_address_t* cardano_pointer = NULL;
// Assume cardano_pointer is previously created and valid
const char* address_string = cardano_pointer_address_get_string(cardano_pointer);

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_pointer_address_t object is not modified or freed.

Parameters:
const cardano_pointer_address_t *address

[in] A pointer to the cardano_pointer_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_pointer_address_get_network_id(const cardano_pointer_address_t *address, cardano_network_id_t *network_id)

Retrieves the network ID from a given Cardano pointer address.

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

Usage Example: 

cardano_pointer_address_t* address = NULL;
cardano_network_id_t network_id;

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

Parameters:
const cardano_pointer_address_t *address

[in] A constant pointer to the cardano_pointer_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_pointer_address_unref(cardano_pointer_address_t **address)

Decrements the pointer address’s reference count.

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

Parameters:
cardano_pointer_address_t **address

[in] Pointer to the pointer address whose reference count is to be decremented.

void cardano_pointer_address_ref(cardano_pointer_address_t *address)

Increments the pointer address’s reference count.

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

Parameters:
cardano_pointer_address_t *address

[in] pointer address whose reference count is to be incremented.

size_t cardano_pointer_address_refcount(const cardano_pointer_address_t *address)

Retrieves the pointer address’s current reference count.

Warning

Does not account for transitive references.

Parameters:
const cardano_pointer_address_t *address

[in] Target pointer address.

Returns:

Current reference count of the pointer address.

void cardano_pointer_address_set_last_error(cardano_pointer_address_t *address, const char *message)

Sets the last error message for a given pointer address.

This function records an error message in the pointer 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_pointer_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_pointer_address_t *address

[inout] A pointer to the cardano_pointer_address_t instance whose last error message is to be set. If the pointer 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 pointer address’s last_error will be set to an empty string, indicating no error.

const char *cardano_pointer_address_get_last_error(const cardano_pointer_address_t *address)

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

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

Parameters:
const cardano_pointer_address_t *address

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

Returns:

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