Transaction Builder¶

typedef struct cardano_tx_builder_t cardano_tx_builder_t¶

High-Level Transaction Builder for Cardano Blockchain.

The cardano_tx_builder_t type serves as a comprehensive interface for constructing Cardano transactions programmatically encapsulating the complexities of transaction assembly, balancing, and validation.

Key Features:

• Modular Design: Incrementally add inputs, outputs, certificates, metadata, and scripts, enabling flexible transaction construction.

• Automatic Fee Calculation and Balancing: Automatically calculates fees and ensures the transaction is balanced according to Cardano’s protocol parameters.

• Support for Advanced Constructs: Facilitates multi-asset transactions, Plutus smart contracts, token minting/burning, and governance actions.

• Extensibility: Allows for custom coin selection strategies.

cardano_tx_builder_t *cardano_tx_builder_new(cardano_protocol_parameters_t *params, const cardano_slot_config_t *slot_config)¶

Creates a new transaction builder instance.

This function initializes a new transaction builder (cardano_tx_builder_t) using the supplied protocol parameters and slot configuration. The builder enables incremental, rule-safe construction of a transaction, including input selection, output balancing, fee calculation, and script evaluation—based on the specified protocol settings.

The protocol parameters determine limits and constants such as:

• Minimum fees (minFeeA, minFeeB)

• Execution unit prices and limits

• Maximum transaction size

• UTxO cost per byte

• Cost models for script evaluation

The slot configuration provides time/slot conversion rules needed for unix time to slot conversions.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...;            // Initialized protocol parameters
cardano_slot_config_t slot_config = CARDANO_PREVIEW_SLOT_CONFIG; // Constants for slot config for every public network can be found at cardano/slot_config.h

cardano_tx_builder_t* tx_builder =
    cardano_tx_builder_new(protocol_params, &slot_config);

if (tx_builder != NULL)
{
  // Proceed with constructing the transaction
}

cardano_tx_builder_unref(&tx_builder);

Note

The caller is responsible for releasing the cardano_tx_builder_t instance using cardano_tx_builder_unref once it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *params¶

[in] A pointer to a cardano_protocol_parameters_t structure containing the protocol parameters used to configure the transaction builder. Must not be NULL.

const cardano_slot_config_t *slot_config¶

[in] A pointer to the cardano_slot_config_t structure that defines the slot/time translation rules for the current network. Must not be NULL. Constants for every public network can be found at cardano/slot_config.h: CARDANO_MAINNET_SLOT_CONFIG CARDANO_PREVIEW_SLOT_CONFIG CARDANO_PREPROD_SLOT_CONFIG

Returns:¶

A pointer to a newly created cardano_tx_builder_t instance configured with the given protocol parameters and slot configuration, or NULL if memory allocation fails or if any argument is invalid.

void cardano_tx_builder_set_coin_selector(cardano_tx_builder_t *builder, cardano_coin_selector_t *coin_selector)¶

Sets the coin selector for the transaction builder.

This function assigns a specific coin selection strategy to the transaction builder. The coin selector determines how UTXOs are selected to cover the transaction’s required value. Any errors related to coin selection configuration or validation are deferred and will be reported only when cardano_tx_builder_build is called.

If this function is not called, the default coin selector (large first coin selector) will be used.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_coin_selector_t* coin_selector = ...;  // Initialized coin selector
cardano_tx_builder_set_coin_selector(tx_builder, coin_selector);

...

cardano_error_t result = cardano_tx_builder_build(tx_builder);

if (result != CARDANO_SUCCESS)
{
  const char* error_msg = cardano_tx_builder_get_last_error(tx_builder);
  printf("Failed to build transaction: %s\n", error_msg);
}

 cardano_tx_builder_unref(&tx_builder);

See also

cardano_tx_builder_build

Note

Errors arising from coin selector configuration or compatibility will be deferred until the transaction is finalized with cardano_tx_builder_build. This deferred error handling allows for smoother configuration and incremental transaction building.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the coin selector is to be set.

cardano_coin_selector_t *coin_selector¶

[in] A pointer to the cardano_coin_selector_t structure that specifies the coin selection strategy.

void cardano_tx_builder_set_tx_evaluator(cardano_tx_builder_t *builder, cardano_tx_evaluator_t *tx_evaluator)¶

Sets the transaction evaluator for a transaction builder.

This function assigns a transaction evaluator to the specified transaction builder. The evaluator will be used to compute the execution units required for evaluating transactions. It enables users to incorporate custom evaluation logic during transaction creation.

If this function is not called, the default evaluator (provider tx evaluator) will be used.

Note: This function defers error reporting until the transaction is built using cardano_tx_builder_build. If an issue arises during evaluator setup, it will be reported at that stage.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_tx_evaluator_t* tx_evaluator = ...;  // Initialized transaction evaluator
cardano_tx_builder_set_tx_evaluator(tx_builder, tx_evaluator);

...

cardano_error_t result = cardano_tx_builder_build(tx_builder);

if (result != CARDANO_SUCCESS)
{
  const char* error_msg = cardano_tx_builder_get_last_error(tx_builder);
  printf("Failed to build transaction: %s\n", error_msg);
}

cardano_tx_builder_unref(&tx_builder);

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the evaluator will be set.

cardano_tx_evaluator_t *tx_evaluator¶

[in] A pointer to the cardano_tx_evaluator_t instance that will serve as the transaction evaluator.

void cardano_tx_builder_set_network_id(cardano_tx_builder_t *builder, cardano_network_id_t network_id)¶

Sets the network ID for the transaction builder.

This function configures the transaction builder (cardano_tx_builder_t) with a specific network ID.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialize or obtain a transaction builder
cardano_network_id_t network_id = CARDANO_MAINNET;  // Set the network ID to mainnet
cardano_tx_builder_set_network_id(tx_builder, network_id);

Note

This function only sets the network ID within the builder and does not perform any validation until cardano_tx_builder_build is called, which will report any related errors at that time.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for which the network ID is being set.

cardano_network_id_t network_id¶

[in] The network ID to assign to the transaction builder. This ID specifies the target network (e.g., mainnet, testnet) for which the transaction is intended.

void cardano_tx_builder_set_change_address(cardano_tx_builder_t *builder, cardano_address_t *change_address)¶

Sets the change address for the transaction builder.

This function specifies the address to which any remaining balance (after covering transaction outputs and fees) will be sent. The address is stored within the transaction builder (cardano_tx_builder_t) and applied during the final transaction construction.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_address_t* change_addr = ...;    // The change address to be set
cardano_tx_builder_set_change_address(tx_builder, change_addr);

Note

This function only assigns the change address to the builder; any validation related to the address will be deferred until cardano_tx_builder_build is called, at which point related errors may be reported.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for which the change address is being set.

cardano_address_t *change_address¶

[in] A pointer to the cardano_address_t object representing the change address. Ownership of this address is not transferred; it must remain valid for the duration of the transaction builder’s usage.

void cardano_tx_builder_set_change_address_ex(cardano_tx_builder_t *builder, const char *change_address, size_t address_size)¶

Sets the change address for the transaction builder using a raw address string.

This function allows specifying the change address directly as a raw string.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* raw_change_address = "addr1q...";  // Raw encoded change address
size_t address_size = strlen(raw_change_address);
cardano_tx_builder_set_change_address_ex(tx_builder, raw_change_address, address_size);

Note

This function only assigns the change address to the builder. Any errors related to the validity of the address are deferred until cardano_tx_builder_build is called, where issues may be reported.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for which the change address is being set.

const char *change_address¶

[in] A pointer to a character array containing the raw change address in encoded form.

size_t address_size¶

[in] The size of the change address array.

void cardano_tx_builder_set_collateral_change_address(cardano_tx_builder_t *builder, cardano_address_t *collateral_change_address)¶

Sets the collateral change address for the transaction builder.

This function assigns a collateral change address to the transaction builder (cardano_tx_builder_t), specifying where any remaining balance from collateral inputs will be sent. Collateral is used in transactions that contain scripts, acting as a safeguard in case script validation fails.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_address_t* collateral_address = ...;  // Prepared collateral change address
cardano_tx_builder_set_collateral_change_address(tx_builder, collateral_address);

Note

This function only sets the collateral change address; any issues or validation errors with the address are deferred until cardano_tx_builder_build is called, at which point an error may be reported if necessary.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for which the collateral change address is being set.

cardano_address_t *collateral_change_address¶

[in] A pointer to the cardano_address_t object representing the collateral change address.

void cardano_tx_builder_set_collateral_change_address_ex(cardano_tx_builder_t *builder, const char *collateral_change_address, size_t address_size)¶

Sets the collateral change address for the transaction builder using a raw address string.

This function allows setting the collateral change address as a raw byte string in the transaction builder (cardano_tx_builder_t). The collateral change address specifies where any remaining balance from collateral inputs will be sent, used as a safeguard in script-validated transactions.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* collateral_address_str = "...";  // Raw collateral change address as a string
size_t address_len = strlen(collateral_address_str);
cardano_tx_builder_set_collateral_change_address_ex(tx_builder, collateral_address_str, address_len);

Note

This function only assigns the provided address string to the builder; any validation errors related to the address will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for which the collateral change address is being set.

const char *collateral_change_address¶

[in] A constant pointer to the raw byte string representing the collateral change address.

size_t address_size¶

[in] The size (in bytes) of the collateral_change_address string.

void cardano_tx_builder_set_minimum_fee(cardano_tx_builder_t *builder, uint64_t minimum_fee)¶

Sets the minimum transaction fee for the transaction builder.

This function allows setting a minimum transaction fee for a transaction being constructed with the specified transaction builder (cardano_tx_builder_t).

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
uint64_t min_fee = 1000000;  // Minimum fee in lovelace
cardano_tx_builder_set_minimum_fee(tx_builder, min_fee);

Note

Setting this fee does not validate its sufficiency for the transaction; validation will occur when cardano_tx_builder_build is called, where an error will be reported if the fee is inadequate.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the minimum fee will be set.

uint64_t minimum_fee¶

[in] The minimum fee amount, specified in lovelace.

void cardano_tx_builder_set_donation(cardano_tx_builder_t *builder, uint64_t donation)¶

Sets the donation amount for the transaction builder.

This function sets the donation amount. Donations are a Conway-era feature that contributes a specific amount to the treasury.

Usage Example:

cardano_tx_builder_t* tx_builder = ...; // Initialized transaction builder
uint64_t donation = 1000000;         // 1 ADA donation in lovelace

cardano_tx_builder_set_donation(tx_builder, donation);

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the donation will be set.

uint64_t donation¶

[in] The donation amount, specified in lovelace.

void cardano_tx_builder_set_utxos(cardano_tx_builder_t *builder, cardano_utxo_list_t *utxos)¶

Sets the available UTXOs for coin selection in transaction balancing.

This function assigns a list of available UTXOs (cardano_utxo_list_t) to the transaction builder. These UTXOs will be utilized during the coin selection process to meet the transaction’s balance requirements.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_utxo_list_t* utxos = ...;        // List of available UTXOs
cardano_tx_builder_set_utxos(tx_builder, utxos);

Note

This function only sets the UTXOs for potential selection; the actual coin selection will occur when cardano_tx_builder_build is called, allowing the transaction builder to balance the transaction.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance that will use the specified UTXOs.

cardano_utxo_list_t *utxos¶

[in] A pointer to the cardano_utxo_list_t containing the UTXOs available for selection.

void cardano_tx_builder_set_collateral_utxos(cardano_tx_builder_t *builder, cardano_utxo_list_t *utxos)¶

Sets the UTXO list for collateral when scripts are included in the transaction.

This function assigns a specific list of UTXOs (cardano_utxo_list_t) for use as collateral if the transaction involves script execution. If this collateral UTXO list is not set, the transaction builder will default to using the general UTXO list provided via cardano_tx_builder_set_utxos.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_utxo_list_t* collateral_utxos = ...;  // UTXOs designated for collateral
cardano_tx_builder_set_collateral_utxos(tx_builder, collateral_utxos);

Note

Only necessary if the transaction contains scripts that require collateral. Without this setting, the transaction builder defaults to the general UTXO set.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance that will utilize the specified UTXOs for collateral.

cardano_utxo_list_t *utxos¶

[in] A pointer to the cardano_utxo_list_t containing the UTXOs designated for collateral.

void cardano_tx_builder_set_invalid_after(cardano_tx_builder_t *builder, uint64_t slot)¶

Sets the expiration slot for a transaction, beyond which it is no longer valid.

This function specifies the slot number after which the transaction will be considered invalid. Setting this value helps enforce transaction timeouts, allowing the transaction to expire if not included in a block before the specified slot.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
uint64_t expiration_slot = 5000000;  // Slot after which the transaction becomes invalid
cardano_tx_builder_set_invalid_after(tx_builder, expiration_slot);

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance being configured.

uint64_t slot¶

[in] The slot number after which the transaction will be marked as invalid.

void cardano_tx_builder_set_invalid_after_ex(cardano_tx_builder_t *builder, uint64_t unix_time)¶

Sets the expiration time for a transaction based on Unix time (in seconds).

This function configures the transaction’s validity based on a specified Unix timestamp, marking the transaction as invalid if it is not included in a block before this time. The Unix timestamp is expressed in seconds since the epoch (January 1, 1970, UTC). This setting is useful for transactions that need to expire at a specific real-world time.

Usage Example:

#include <time.h>

cardano_tx_builder_t* tx_builder = ...;   // Initialized transaction builder
time_t current_time = time(NULL);         // Get current Unix time in seconds
uint64_t expiration_time = current_time + 2 * 60 * 60;  // Set expiration to 2 hours from now

cardano_tx_builder_set_invalid_after_ex(tx_builder, expiration_time);

Note

If any errors occur while setting the expiration, they will not be immediately reported. Instead, they will be deferred and can be checked when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance being configured.

uint64_t unix_time¶

[in] The Unix timestamp (in seconds) at which the transaction expires.

void cardano_tx_builder_set_invalid_before(cardano_tx_builder_t *builder, uint64_t slot)¶

Sets the minimum valid slot for a transaction.

This function configures the earliest slot at which the transaction will be considered valid. Transactions created with this setting will not be valid for inclusion in a block until the specified slot.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;   // Initialized transaction builder
uint64_t min_valid_slot = 123456;         // Example slot number
cardano_tx_builder_set_invalid_before(tx_builder, min_valid_slot);

Note

Any errors arising from setting this parameter will be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance being configured.

uint64_t slot¶

[in] The minimum slot number at which the transaction is valid.

void cardano_tx_builder_set_invalid_before_ex(cardano_tx_builder_t *builder, uint64_t unix_time)¶

Sets the minimum valid time (Unix timestamp) for a transaction.

This function configures the earliest time, in Unix timestamp format (seconds since Epoch), at which the transaction will be considered valid. Transactions created with this setting will not be valid for inclusion in a block until the specified timestamp.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;   // Initialized transaction builder
uint64_t min_valid_time = 7200 + time(NULL);  // Set to 2 hours from now
cardano_tx_builder_set_invalid_before_ex(tx_builder, min_valid_time);

Note

Any errors resulting from setting this parameter will be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance being configured.

uint64_t unix_time¶

[in] The minimum Unix timestamp (in seconds) at which the transaction is valid.

void cardano_tx_builder_add_reference_input(cardano_tx_builder_t *builder, cardano_utxo_t *utxo)¶

Adds a reference input to the transaction.

This function appends a specified UTXO as a reference input to the transaction being built. Reference inputs are utilized by Plutus scripts to access additional data without consuming the UTXO in the transaction.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_utxo_t* reference_utxo = ...;    // UTXO to add as a reference input
cardano_tx_builder_add_reference_input(tx_builder, reference_utxo);

Note

Any errors resulting from adding this input will be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance in which to add the reference input.

cardano_utxo_t *utxo¶

[in] A pointer to the cardano_utxo_t structure representing the UTXO to be used as a reference input.

void cardano_tx_builder_send_lovelace(cardano_tx_builder_t *builder, cardano_address_t *address, uint64_t amount)¶

Sends a specified amount of lovelace to a given address.

This function adds a transaction output to the builder, targeting a specific address and setting the amount of lovelace to be sent.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;            // Initialized transaction builder
cardano_address_t* recipient_address = ...;         // Recipient address
uint64_t lovelace_amount = 1000000;                // Amount of lovelace to send (e.g., 1 ADA)

cardano_tx_builder_send_lovelace(tx_builder, recipient_address, lovelace_amount);

Note

Any errors related to sending lovelace, such as balance requirements or transaction limits, will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the output will be added.

cardano_address_t *address¶

[in] A pointer to the cardano_address_t structure representing the recipient address.

uint64_t amount¶

[in] The amount of lovelace to send to the specified address.

void cardano_tx_builder_send_lovelace_ex(cardano_tx_builder_t *builder, const char *address, size_t address_size, uint64_t amount)¶

Sends a specified amount of lovelace to a given address in string format.

This function adds a transaction output to the builder, targeting a specific address in string format and setting the amount of lovelace to be sent.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;         // Initialized transaction builder
const char* recipient_address = "addr1...";      // Recipient address in string format
size_t address_size = strlen(recipient_address); // Size of the address string
uint64_t lovelace_amount = 1000000;             // Amount of lovelace to send (e.g., 1 ADA)

cardano_tx_builder_send_lovelace_ex(tx_builder, recipient_address, address_size, lovelace_amount);

Note

Errors, such as insufficient balance or invalid address, will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the output will be added.

const char *address¶

[in] A pointer to a character array containing the recipient address in string format.

size_t address_size¶

[in] The size of the address string.

uint64_t amount¶

[in] The amount of lovelace to send to the specified address.

void cardano_tx_builder_send_value(cardano_tx_builder_t *builder, cardano_address_t *address, cardano_value_t *value)¶

Sends a specified value (which may include ADA and other assets) to a given address.

This function adds a transaction output to the builder, specifying an address and a complex value that can include multiple assets in addition to ADA.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_address_t* recipient_address = ...;  // Address to send to
cardano_value_t* transfer_value = ...;  // Value to transfer (e.g., ADA and assets)

cardano_tx_builder_send_value(tx_builder, recipient_address, transfer_value);

Note

Errors, such as insufficient balance or invalid assets, will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the output will be added.

cardano_address_t *address¶

[in] A pointer to a cardano_address_t object representing the recipient address.

cardano_value_t *value¶

[in] A pointer to a cardano_value_t object containing the ADA and any additional assets to send.

void cardano_tx_builder_send_value_ex(cardano_tx_builder_t *builder, const char *address, size_t address_size, cardano_value_t *value)¶

Sends a specified value (which may include ADA and other assets) to a given address provided as raw string.

This function adds a transaction output to the builder, specifying an address in character array format along with a complex value that may include multiple assets.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* recipient_address = "addr1...";  // Bech32 address
size_t address_size = strlen(recipient_address);
cardano_value_t* transfer_value = ...;  // Value to transfer (e.g., ADA and assets)

cardano_tx_builder_send_value_ex(tx_builder, recipient_address, address_size, transfer_value);

Note

Errors, such as insufficient balance or invalid assets, will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the output will be added.

const char *address¶

[in] A character array containing the recipient’s address in bech32 or hex format.

size_t address_size¶

[in] The length of the address character array.

cardano_value_t *value¶

[in] A pointer to a cardano_value_t object containing the ADA and any additional assets to send.

void cardano_tx_builder_lock_lovelace(cardano_tx_builder_t *builder, cardano_address_t *script_address, uint64_t amount, cardano_datum_t *datum)¶

Locks a specified amount of lovelace at a script address.

This function adds a transaction output to the builder that sends lovelace to a script address.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;         // Initialized transaction builder
cardano_address_t* script_addr = ...;           // Script address
uint64_t lovelace_amount = 5000000;             // Amount of lovelace to lock
cardano_datum_t* datum = ...;                   // Datum associated with the script

cardano_tx_builder_lock_lovelace(tx_builder, script_addr, lovelace_amount, datum);

Note

Errors such as an invalid amount or address will be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the locked output will be added.

cardano_address_t *script_address¶

[in] A pointer to the cardano_address_t representing the script address where the lovelace will be locked.

uint64_t amount¶

[in] The amount of lovelace to be locked at the script address.

cardano_datum_t *datum¶

[in] A pointer to the cardano_datum_t object containing the data to lock with the transaction.

void cardano_tx_builder_lock_lovelace_ex(cardano_tx_builder_t *builder, const char *script_address, size_t script_address_size, uint64_t amount, cardano_datum_t *datum)¶

Locks a specified amount of lovelace at a script address using an address in raw byte format.

This function adds a transaction output to the builder, sending lovelace to a script address.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;           // Initialized transaction builder
const char* script_addr_bytes = ...;              // Raw bytes of script address
size_t script_addr_size = ...;                    // Size of the address in bytes
uint64_t lovelace_amount = 5000000;               // Amount of lovelace to lock
cardano_datum_t* datum = ...;                     // Datum associated with the script

cardano_tx_builder_lock_lovelace_ex(tx_builder, script_addr_bytes, script_addr_size, lovelace_amount, datum);

Note

Errors such as an invalid amount or address will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the locked output will be added.

const char *script_address¶

[in] A pointer to a raw byte array containing the script address where the lovelace will be locked.

size_t script_address_size¶

[in] The size, in bytes, of the script address.

uint64_t amount¶

[in] The amount of lovelace to be locked at the specified script address.

cardano_datum_t *datum¶

[in] A pointer to the cardano_datum_t object containing the datum for the script output.

void cardano_tx_builder_lock_value(cardano_tx_builder_t *builder, cardano_address_t *script_address, cardano_value_t *value, cardano_datum_t *datum)¶

Locks a specified value (including ADA and multi-asset tokens) at a script address.

This function adds a transaction output to the builder, sending a specified value to a script address.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;       // Initialized transaction builder
cardano_address_t* script_addr = ...;         // Script address to lock value at
cardano_value_t* value = ...;                 // Value including ADA and/or tokens
cardano_datum_t* datum = ...;                 // Datum associated with the script

cardano_tx_builder_lock_value(tx_builder, script_addr, value, datum);

Note

Errors such as invalid address or value will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the locked output will be added.

cardano_address_t *script_address¶

[in] A pointer to the cardano_address_t object representing the script address where the value will be locked.

cardano_value_t *value¶

[in] A pointer to the cardano_value_t object representing the amount and type of value (ADA or tokens) to be locked at the script address.

cardano_datum_t *datum¶

[in] A pointer to the cardano_datum_t object containing the datum for the script output.

void cardano_tx_builder_lock_value_ex(cardano_tx_builder_t *builder, const char *script_address, size_t script_address_size, cardano_value_t *value, cardano_datum_t *datum)¶

Locks a specified value (including ADA and multi-asset tokens) at a script address using a raw address string.

This function adds a transaction output to the builder, sending a specified value to a script address represented by a raw address string.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;       // Initialized transaction builder
const char* script_addr_str = "addr_test1..."; // Raw address string for the script address
size_t script_addr_size = strlen(script_addr_str);
cardano_value_t* value = ...;                 // Value including ADA and/or tokens
cardano_datum_t* datum = ...;                 // Datum associated with the script (optional)

cardano_tx_builder_lock_value_ex(tx_builder, script_addr_str, script_addr_size, value, datum);

Note

Errors such as invalid address or value will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the locked output will be added.

const char *script_address¶

[in] A pointer to a character array containing the raw script address string where the value will be locked.

size_t script_address_size¶

[in] The size of the script_address string in bytes.

cardano_value_t *value¶

[in] A pointer to the cardano_value_t object representing the amount and type of value (ADA or tokens) to be locked at the script address.

cardano_datum_t *datum¶

[in] A pointer to the cardano_datum_t object containing the datum for the script output.

void cardano_tx_builder_add_input(cardano_tx_builder_t *builder, cardano_utxo_t *utxo, cardano_plutus_data_t *redeemer, cardano_plutus_data_t *datum)¶

Adds an input to the transaction.

This function appends a specified UTXO as an input to the transaction being built. Optionally, it allows attaching a redeemer and datum if the input is associated with a Plutus script.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_utxo_t* input_utxo = ...;        // UTXO to add as an input
cardano_plutus_data_t* redeemer = ...;   // Optional redeemer for the input
cardano_plutus_data_t* datum = ...;      // Optional datum for the input

cardano_tx_builder_add_input(tx_builder, input_utxo, redeemer, datum);

Note

Any errors resulting from adding this input will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance in which to add the input.

cardano_utxo_t *utxo¶

[in] A pointer to the cardano_utxo_t structure representing the UTXO to be used as an input.

cardano_plutus_data_t *redeemer¶

[in] A pointer to the cardano_plutus_data_t structure representing the redeemer for the Plutus script (optional; can be NULL).

cardano_plutus_data_t *datum¶

[in] A pointer to the cardano_plutus_data_t structure representing the datum for the Plutus script (optional; can be NULL).

void cardano_tx_builder_add_output(cardano_tx_builder_t *builder, cardano_transaction_output_t *output)¶

Adds an output to the transaction.

This function appends a specified transaction output to the transaction being built.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;            // Initialized transaction builder
cardano_transaction_output_t* tx_output = ...;     // Transaction output to add

cardano_tx_builder_add_output(tx_builder, tx_output);

Note

Any errors related to adding this output, such as exceeding balance requirements, will be deferred and reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance to which the output will be added.

cardano_transaction_output_t *output¶

[in] A pointer to the cardano_transaction_output_t structure representing the transaction output to be added.

void cardano_tx_builder_set_metadata(cardano_tx_builder_t *builder, uint64_t tag, cardano_metadatum_t *metadata)¶

Sets metadata for a transaction builder with a specified tag.

This function attaches metadata to a transaction being built, associating it with a specific metadata tag. Metadata can include additional information for the transaction, often used to encode arbitrary data on-chain.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;       // Initialized transaction builder
uint64_t metadata_tag = 12345;                // Example metadata tag
cardano_metadatum_t* metadata = ...;          // Initialized metadata object

cardano_tx_builder_set_metadata(tx_builder, metadata_tag, metadata);

Note

This function only stores a reference to the metadata. Errors, such as invalid metadata format, will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the metadata will be added.

uint64_t tag¶

[in] A unique identifier for the metadata, typically a 64-bit unsigned integer.

cardano_metadatum_t *metadata¶

[in] A pointer to the cardano_metadatum_t object containing the metadata to be added.

void cardano_tx_builder_set_metadata_ex(cardano_tx_builder_t *builder, uint64_t tag, const char *metadata_json, size_t json_size)¶

Sets metadata for a transaction builder from a JSON string with a specified tag.

This function allows adding metadata to the transaction by parsing a JSON string representation of the metadata. The metadata is associated with a specified tag, allowing for organized and accessible on-chain data.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;   // Initialized transaction builder
uint64_t metadata_tag = 12345;            // Example metadata tag
const char* metadata_json = "{ \"name\": \"some_name\" }";  // Metadata JSON as string
size_t json_size = strlen(metadata_json);

cardano_tx_builder_set_metadata_ex(tx_builder, metadata_tag, metadata_json, json_size);

Note

This function will parse the JSON string to convert it into metadata. Errors, such as invalid JSON format, will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance where the metadata will be added.

uint64_t tag¶

[in] A unique identifier for the metadata, typically a 64-bit unsigned integer.

const char *metadata_json¶

[in] A pointer to a JSON string representing the metadata content.

size_t json_size¶

[in] The length of the metadata_json string.

void cardano_tx_builder_mint_token(cardano_tx_builder_t *builder, cardano_blake2b_hash_t *policy_id, cardano_asset_name_t *name, int64_t amount, cardano_plutus_data_t *redeemer)¶

Adds a token minting operation to the transaction builder.

This function allows the user to specify a token minting operation within a transaction, including the policy ID, asset name, amount, and an optional redeemer for Plutus scripts. This enables minting (positive amount) or burning (negative amount) of tokens.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;    // Initialized transaction builder
cardano_blake2b_hash_t* policy_id = ...;   // Policy ID for the token
cardano_asset_name_t* asset_name = ...;    // Asset name for the token
int64_t mint_amount = 100;                 // Amount to mint
cardano_plutus_data_t* redeemer = ...;     // Optional redeemer for Plutus scripts

cardano_tx_builder_mint_token(tx_builder, policy_id, asset_name, mint_amount, redeemer);

Note

Errors related to this operation will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance for building the transaction.

cardano_blake2b_hash_t *policy_id¶

[in] A pointer to a cardano_blake2b_hash_t representing the unique minting policy ID.

cardano_asset_name_t *name¶

[in] A pointer to a cardano_asset_name_t defining the name of the asset being minted or burned.

int64_t amount¶

[in] The number of tokens to mint or burn; positive values indicate minting, and negative values indicate burning.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t structure, representing a redeemer if a Plutus script is used. Can be NULL if no redeemer is required.

void cardano_tx_builder_mint_token_ex(cardano_tx_builder_t *builder, const char *policy_id_hex, size_t policy_id_size, const char *name_hex, size_t name_size, int64_t amount, cardano_plutus_data_t *redeemer)¶

Adds a token minting operation to the transaction builder using policy ID and asset name in hexadecimal format.

This function allows the transaction builder to mint or burn tokens associated with a specific policy ID and asset name. The minting or burning amount and an optional redeemer for Plutus scripts are specified.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;     // Initialized transaction builder
const char* policy_id_hex = "abcdef123456"; // Example policy ID in hexadecimal format
size_t policy_id_size = strlen(policy_id_hex); // Size of policy ID
const char* name_hex = "74657374";          // Asset name in hexadecimal ("test" in hex)
size_t name_size = strlen(name_hex);        // Size of asset name
int64_t mint_amount = 100;                  // Amount to mint (positive for minting, negative for burning)
cardano_plutus_data_t* redeemer = ...;      // Optional redeemer for Plutus script

cardano_tx_builder_mint_token_ex(tx_builder, policy_id_hex, policy_id_size, name_hex, name_size, mint_amount, redeemer);

Note

Any errors related to minting policies or Plutus script requirements will only be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for transaction construction.

const char *policy_id_hex¶

[in] A string in hexadecimal format representing the policy ID of the token to mint or burn.

size_t policy_id_size¶

[in] The size of the policy_id_hex string.

const char *name_hex¶

[in] A string in hexadecimal format representing the asset name within the policy ID.

size_t name_size¶

[in] The size of the name_hex string.

int64_t amount¶

[in] The amount of tokens to mint (positive) or burn (negative).

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t structure, representing a redeemer if a Plutus script is involved. Set to NULL if not required.

void cardano_tx_builder_mint_token_with_id(cardano_tx_builder_t *builder, cardano_asset_id_t *asset_id, int64_t amount, cardano_plutus_data_t *redeemer)¶

Adds a token minting operation to the transaction builder using a predefined asset ID.

This function allows minting or burning of tokens within a transaction by specifying an asset ID, along with the amount and an optional redeemer for Plutus scripts.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;   // Initialized transaction builder
cardano_asset_id_t* asset_id = ...;       // Predefined asset ID for the token
int64_t mint_amount = 50;                 // Amount to mint (positive for minting, negative for burning)
cardano_plutus_data_t* redeemer = ...;    // Optional Plutus script redeemer

cardano_tx_builder_mint_token_with_id(tx_builder, asset_id, mint_amount, redeemer);

Note

Any errors related to this operation are deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used to build the transaction.

cardano_asset_id_t *asset_id¶

[in] A pointer to a cardano_asset_id_t structure representing the asset to mint or burn.

int64_t amount¶

[in] The amount of tokens to mint (positive) or burn (negative).

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t structure, representing a redeemer if a Plutus script is involved. Set to NULL if not required.

void cardano_tx_builder_mint_token_with_id_ex(cardano_tx_builder_t *builder, const char *asset_id_hex, size_t hex_size, int64_t amount, cardano_plutus_data_t *redeemer)¶

Adds a token minting operation to the transaction builder using an asset ID in hexadecimal format.

This function enables minting or burning tokens for a specific asset identified by its unique asset_id in hexadecimal format. The minting or burning amount, along with an optional redeemer for Plutus scripts, is specified.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;       // Initialized transaction builder
const char* asset_id_hex = "abcdef1234567890"; // Example asset ID in hexadecimal format
size_t hex_size = strlen(asset_id_hex);        // Size of asset ID
int64_t mint_amount = 100;                     // Amount to mint (positive for minting, negative for burning)
cardano_plutus_data_t* redeemer = ...;         // Optional redeemer for Plutus script

cardano_tx_builder_mint_token_with_id_ex(tx_builder, asset_id_hex, hex_size, mint_amount, redeemer);

Note

Any errors will only be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for transaction construction.

const char *asset_id_hex¶

[in] A string in hexadecimal format representing the unique asset ID.

size_t hex_size¶

[in] The size of the asset_id_hex string.

int64_t amount¶

[in] The amount of tokens to mint (positive) or burn (negative).

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t structure, representing a redeemer if a Plutus script is involved. Set to NULL if not required.

void cardano_tx_builder_pad_signer_count(cardano_tx_builder_t *builder, size_t count)¶

Pads the transaction signer count for fee calculation purposes.

This function pads the expected signature count in the transaction builder. It allows the transaction to calculate the fee considering additional signers.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
size_t extra_signers = 2;                // Additional signers to pad for fee calculation

cardano_tx_builder_pad_signer_count(tx_builder, extra_signers);

Note

This function influences only the fee estimation and does not modify the actual required signers for the transaction. Errors related to setting the signer count are deferred and will only be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for transaction construction.

size_t count¶

[in] The number of expected signers to pad, affecting fee calculation.

void cardano_tx_builder_add_signer(cardano_tx_builder_t *builder, cardano_blake2b_hash_t *pub_key_hash)¶

Adds a signer to the transaction being built.

This function registers a specific signer for the transaction by providing their public key hash.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_blake2b_hash_t* signer_hash = ...;  // Public key hash for the signer

cardano_tx_builder_add_signer(tx_builder, signer_hash);

Note

Errors related to adding signers are deferred and will only be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for transaction construction.

cardano_blake2b_hash_t *pub_key_hash¶

[in] A pointer to the cardano_blake2b_hash_t structure representing the public key hash of the signer to be added.

void cardano_tx_builder_add_signer_ex(cardano_tx_builder_t *builder, const char *pub_key_hash, size_t hash_size)¶

Adds a signer to the transaction by specifying their public key hash in hexadecimal format.

This function registers a signer by accepting their public key hash as a hexadecimal string.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* pub_key_hash = "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
size_t hash_size = strlen(pub_key_hash);

cardano_tx_builder_add_signer_ex(tx_builder, pub_key_hash, hash_size);

Note

Errors associated with adding a signer are deferred and will only be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for transaction construction.

const char *pub_key_hash¶

[in] A string representing the public key hash in hexadecimal format.

size_t hash_size¶

[in] The size of the pub_key_hash string.

void cardano_tx_builder_add_datum(cardano_tx_builder_t *builder, cardano_plutus_data_t *datum)¶

Adds a datum to the transaction builder for use in script-locked UTXOs.

This function registers a Plutus datum with the transaction builder, which can then be referenced by outputs that are locked by Plutus scripts.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_plutus_data_t* datum = ...;      // Initialized Plutus datum

cardano_tx_builder_add_datum(tx_builder, datum);

Note

Errors related to adding a datum are deferred and will be reported when cardano_tx_builder_build is called. The caller must ensure that the datum remains valid until the transaction is built.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for constructing the transaction.

cardano_plutus_data_t *datum¶

[in] A pointer to a cardano_plutus_data_t object representing the datum to be included.

void cardano_tx_builder_withdraw_rewards(cardano_tx_builder_t *builder, cardano_reward_address_t *address, int64_t amount, cardano_plutus_data_t *redeemer)¶

Withdraws rewards from a specified reward account in the transaction builder.

This function instructs the transaction builder to withdraw the available rewards for the specified reward account. It uses the associated cardano_provider_t to fetch the available reward balance for the given account address and adds the withdrawal to the transaction.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;           // Initialized transaction builder
cardano_reward_address_t* reward_address = ...;    // Initialized reward address
cardano_plutus_data_t* redeemer = ...;            // Optional redeemer data

cardano_tx_builder_withdraw_rewards(tx_builder, reward_address, 2532145, redeemer);

Note

Errors related to reward withdrawal will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for constructing the transaction.

cardano_reward_address_t *address¶

[in] A pointer to the cardano_reward_address_t representing the reward account address from which rewards should be withdrawn.

int64_t amount¶

[in] The amount of rewards to withdraw from the account. It must be the full available reward balance.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t that serves as the redeemer for script-locked withdrawals, if applicable.

void cardano_tx_builder_withdraw_rewards_ex(cardano_tx_builder_t *builder, const char *reward_address, size_t address_size, int64_t amount, cardano_plutus_data_t *redeemer)¶

Withdraws rewards from a specified reward account using a string address in the transaction builder.

This function instructs the transaction builder to withdraw available rewards from the specified reward account, using a string format for the reward address. It uses the associated cardano_provider_t to fetch the available reward balance for the given address and includes the withdrawal in the transaction.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;          // Initialized transaction builder
const char* reward_addr = "stake1u9...";         // Reward address in string format
size_t address_size = strlen(reward_addr);       // Length of the reward address string
cardano_plutus_data_t* redeemer = ...;           // Optional redeemer data

cardano_tx_builder_withdraw_rewards_ex(tx_builder, reward_addr, address_size, 966584122, redeemer);

Note

Errors related to reward withdrawal will be deferred until cardano_tx_builder_build is called. Ensure the reward address and redeemer remain valid until the transaction is built.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for constructing the transaction.

const char *reward_address¶

[in] A string representing the reward account address from which rewards are to be withdrawn.

size_t address_size¶

[in] The size of the reward address string in bytes.

int64_t amount¶

[in] The amount of rewards to withdraw from the account. It must be the full available reward balance.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t that acts as the redeemer for script-locked withdrawals, if applicable.

void cardano_tx_builder_register_reward_address(cardano_tx_builder_t *builder, cardano_reward_address_t *address, cardano_plutus_data_t *redeemer)¶

Registers a staking reward address.

This function adds a staking reward address to be registered in the transaction, allowing the specified reward account to start receiving staking rewards.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;          // Initialized transaction builder
cardano_reward_address_t* reward_addr = ...;     // Reward address to register
cardano_plutus_data_t* redeemer = ...;           // Optional redeemer data for script-locked registration

cardano_tx_builder_register_reward_address(tx_builder, reward_addr, redeemer);

Note

Any errors related to reward address registration will be reported when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance used for constructing the transaction.

cardano_reward_address_t *address¶

[in] A pointer to the cardano_reward_address_t representing the reward account to be registered.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t, which provides the redeemer data if the registration is script-locked.

void cardano_tx_builder_register_reward_address_ex(cardano_tx_builder_t *builder, const char *reward_address, size_t address_size, cardano_plutus_data_t *redeemer)¶

Registers a staking reward address using a hexadecimal address string.

This function registers a staking reward address in the transaction builder, allowing the specified reward account, provided as a hexadecimal string, to receive staking rewards. The transaction builder leverages the cardano_provider_t to validate this process.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;       // Initialized transaction builder
const char* reward_address = "stake1uxxx...";
size_t address_size = strlen(reward_address);
cardano_plutus_data_t* redeemer = ...;        // Optional redeemer data for script-locked registration

cardano_tx_builder_register_reward_address_ex(tx_builder, reward_address, address_size, redeemer);

Note

Errors related to the reward address registration will be reported only when cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction construction.

const char *reward_address¶

[in] A pointer to a bech32 string representing the reward address.

size_t address_size¶

[in] The size of the reward_address string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t, used if the registration requires redeemer data for script-locked transactions.

void cardano_tx_builder_deregister_reward_address(cardano_tx_builder_t *builder, cardano_reward_address_t *address, cardano_plutus_data_t *redeemer)¶

Deregisters a staking reward address.

This function deregisters the reward address, effectively preventing it from receiving future staking rewards. a cardano_plutus_data_t redeemer can be provided for script-locked accounts.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_reward_address_t* reward_address = ...; // Reward address to be deregistered
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer data for script-locked deregistration

cardano_tx_builder_deregister_reward_address(tx_builder, reward_address, redeemer);

Note

Errors related to the deregistration process are deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

cardano_reward_address_t *address¶

[in] A pointer to the cardano_reward_address_t structure representing the reward address to deregister.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t for providing redeemer data if required for deregistration.

void cardano_tx_builder_deregister_reward_address_ex(cardano_tx_builder_t *builder, const char *reward_address, size_t address_size, cardano_plutus_data_t *redeemer)¶

Deregisters a staking reward address.

This function deregisters the reward address, preventing future staking rewards from being sent to the specified reward account. It accepts the reward address in a raw string format along with the length of the address. Optionally, a cardano_plutus_data_t redeemer can be provided for script-locked accounts.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* reward_address = "stake1uxxx...";  // Reward address in raw string format
size_t address_size = strlen(reward_address);
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer data for script-locked deregistration

cardano_tx_builder_deregister_reward_address_ex(tx_builder, reward_address, address_size, redeemer);

Note

Errors related to the deregistration process are deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

const char *reward_address¶

[in] A pointer to a raw string containing the reward address to be deregistered.

size_t address_size¶

[in] The length of the reward address string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to cardano_plutus_data_t for providing redeemer data if required for deregistration.

void cardano_tx_builder_delegate_stake(cardano_tx_builder_t *builder, cardano_reward_address_t *address, cardano_blake2b_hash_t *pool_id, cardano_plutus_data_t *redeemer)¶

Delegates stake from a specified staking reward address to a staking pool.

This function delegates stake from a specified staking reward address to a staking pool, identified by its unique pool ID.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_reward_address_t* reward_address = ...;  // Reward address for staking
cardano_blake2b_hash_t* pool_id = ...;  // Pool ID to delegate stake to
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer for script-locked delegation

cardano_tx_builder_delegate_stake(tx_builder, reward_address, pool_id, redeemer);

Note

Any errors associated with this delegation action will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

cardano_reward_address_t *address¶

[in] A pointer to the cardano_reward_address_t representing the staking reward address to delegate.

cardano_blake2b_hash_t *pool_id¶

[in] A pointer to the cardano_blake2b_hash_t representing the hash ID of the pool to delegate to.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t for providing redeemer data if required for script-locked accounts.

void cardano_tx_builder_delegate_stake_ex(cardano_tx_builder_t *builder, const char *reward_address, size_t address_size, const char *pool_id, size_t pool_id_size, cardano_plutus_data_t *redeemer)¶

Delegates stake from a specified staking reward address to a staking pool.

This function allows for delegating stake from a specified staking reward address to a staking pool, using hex-encoded strings for the reward address and pool ID. The delegation request will be added to the transaction managed by the builder instance.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* reward_address = "stake1u9...";
size_t reward_address_size = strlen(reward_address);
const char* pool_id = "pool1xy...";
size_t pool_id_size = strlen(pool_id);
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer for script-locked delegation

cardano_tx_builder_delegate_stake_ex(tx_builder, reward_address, reward_address_size, pool_id, pool_id_size, redeemer);

Note

Errors related to this action will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

const char *reward_address¶

[in] A bech32 string representing the staking reward address for delegation.

size_t address_size¶

[in] The size of the reward_address string.

const char *pool_id¶

[in] A bech32 string representing the pool ID to which stake is delegated.

size_t pool_id_size¶

[in] The size of the pool_id string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t for providing redeemer data if required for script-locked accounts.

void cardano_tx_builder_delegate_voting_power(cardano_tx_builder_t *builder, cardano_reward_address_t *address, cardano_drep_t *drep, cardano_plutus_data_t *redeemer)¶

Adds a voting power delegation to a DRep for governance purposes.

This function enables delegating voting power from a specified reward address to DRep.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_reward_address_t* reward_address = ...;  // Reward address delegating voting power
cardano_drep_t* drep = ...;  // DRep receiving the delegated voting power
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer data

cardano_tx_builder_delegate_voting_power(tx_builder, reward_address, drep, redeemer);

Note

Errors associated with this delegation will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

cardano_reward_address_t *address¶

[in] A pointer to the cardano_reward_address_t representing the staking reward address that is delegating voting power.

cardano_drep_t *drep¶

[in] A pointer to the cardano_drep_t structure that identifies the decentralized representative receiving the delegated voting power.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t for providing redeemer data, useful for script-locked accounts.

void cardano_tx_builder_delegate_voting_power_ex(cardano_tx_builder_t *builder, const char *reward_address, size_t address_size, const char *drep_id, size_t drep_id_size, cardano_plutus_data_t *redeemer)¶

Delegates voting power to a DRep using raw data.

This function enables the delegation of voting power from a specified reward address to a DRep using string-based identifiers. The DRep ID can be provided in either CIP-105 or CIP-129 format.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
const char* reward_address = "stake1u9...";  // Reward address delegating voting power
size_t address_size = strlen(reward_address);
const char* drep_id = "drep1q...";  // DRep ID in CIP-129 format
size_t drep_id_size = strlen(drep_id);
cardano_plutus_data_t* redeemer = ...;  // Optional redeemer data

// Alternatively, using CIP-105 format
// const char* drep_id = "drep...";  // DRep ID in CIP-105 format
// size_t drep_id_size = strlen(drep_id);

cardano_tx_builder_delegate_voting_power_ex(tx_builder, reward_address, address_size, drep_id, drep_id_size, redeemer);

Note

The DRep ID must conform to either CIP-105 or CIP-129 format. Errors related to this delegation will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

const char *reward_address¶

[in] A string representing the staking reward address for the account delegating voting power.

size_t address_size¶

[in] The length of the reward_address string.

const char *drep_id¶

[in] A string representing the ID of the decentralized representative (DRep) receiving the voting power. The DRep ID can be in CIP-105 or CIP-129 format.

size_t drep_id_size¶

[in] The length of the drep_id string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t for providing redeemer data, useful for script-locked accounts.

void cardano_tx_builder_register_drep(cardano_tx_builder_t *builder, cardano_drep_t *drep, cardano_anchor_t *anchor, cardano_plutus_data_t *redeemer)¶

Registers a DRep in the transaction.

This function registers a DRep with an optional anchor and redeemer in the transaction being constructed.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;  // Initialized transaction builder
cardano_drep_t* drep = ...;              // DRep to register
cardano_anchor_t* anchor = ...;          // Optional governance anchor
cardano_plutus_data_t* redeemer = ...;   // Optional redeemer data

cardano_tx_builder_register_drep(tx_builder, drep, anchor, redeemer);

Note

Errors related to this registration will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

cardano_drep_t *drep¶

[in] A pointer to the cardano_drep_t instance representing the decentralized representative to be registered.

cardano_anchor_t *anchor¶

[in] An optional pointer to a cardano_anchor_t instance providing an anchor for governance (e.g., delegation details).

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t instance for providing redeemer data, which may be required for script-locked DReps.

void cardano_tx_builder_register_drep_ex(cardano_tx_builder_t *builder, const char *drep_id, size_t drep_id_size, const char *metadata_url, size_t metadata_url_size, const char *metadata_hash_hex, size_t metadata_hash_hex_size, cardano_plutus_data_t *redeemer)¶

Registers a DRep by ID in the transaction.

This function registers a DRep in the transaction using a specified DRep ID. The DRep ID must be provided in either CIP-105 or CIP-129 bech32 format. An optional redeemer data can be included for script-locked DReps.

Usage Example:

// Using CIP-105 format (bech32-encoded DRep ID with specific prefix)
cardano_tx_builder_t* tx_builder = ...;    // Initialized transaction builder
const char* drep_id = "drep1q...";
size_t drep_id_size = strlen(drep_id);
const char* metadata_url = "https://example.com/drep_metadata.json";
size_t metadata_url_size = strlen(metadata_url);
const char* metadata_hash_hex = "abcdef123456...";  // Hex-encoded hash of metadata file
size_t metadata_hash_hex_size = strlen(metadata_hash_hex);
cardano_plutus_data_t* redeemer = ...;     // Optional redeemer data

cardano_tx_builder_register_drep_ex(
  tx_builder,
  drep_id,
  drep_id_size,
  metadata_url,
  metadata_url_size,
  metadata_hash_hex,
  metadata_hash_hex_size,
  redeemer);

Note

The drep_id must be in bech32 format as specified by either CIP-105 or CIP-129, which differ in their internal binary encoding. Ensure that the correct format is used according to the DRep’s identification scheme. Errors related to this registration will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

const char *drep_id¶

[in] A pointer to a character array containing the DRep ID in bech32 format (either CIP-105 or CIP-129).

size_t drep_id_size¶

[in] The size of the drep_id string.

const char *metadata_url¶

[in] The URL pointing to the DRep metadata file.

size_t metadata_url_size¶

[in] The size of the metadata_url string.

const char *metadata_hash_hex¶

[in] The hash of the DRep metadata file in hexadecimal format.

size_t metadata_hash_hex_size¶

[in] The size of the metadata_hash_hex string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t instance for providing redeemer data, which may be required for script-locked DReps.

void cardano_tx_builder_update_drep(cardano_tx_builder_t *builder, cardano_drep_t *drep, cardano_anchor_t *anchor, cardano_plutus_data_t *redeemer)¶

Updates an existing DRep in the transaction.

This function allows updating a DRep in the transaction with a specified DRep object, optionally providing a governance anchor and redeemer data for script DReps.

Usage Example:

cardano_tx_builder_t* tx_builder = ...;    // Initialized transaction builder
cardano_drep_t* drep = ...;                // DRep object to update
cardano_anchor_t* anchor = ...;            // Optional anchor
cardano_plutus_data_t* redeemer = ...;     // Optional redeemer data

cardano_tx_builder_update_drep(tx_builder, drep, anchor, redeemer);

Note

Any errors related to updating the DRep will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

cardano_drep_t *drep¶

[in] A pointer to the cardano_drep_t instance representing the DRep to be updated.

cardano_anchor_t *anchor¶

[in] An optional pointer to a cardano_anchor_t instance, providing governance anchor details associated with the DRep.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t instance for providing redeemer data, which may be required for script-locked DReps.

void cardano_tx_builder_update_drep_ex(cardano_tx_builder_t *builder, const char *drep_id, size_t drep_id_size, const char *metadata_url, size_t metadata_url_size, const char *metadata_hash_hex, size_t metadata_hash_hex_size, cardano_plutus_data_t *redeemer)¶

Updates an existing DRep in the transaction by ID.

This function updates a DRep in the transaction using a specified DRep ID. The DRep ID must be provided in bech32 format, conforming to either CIP-105 or CIP-129 standards. Optionally, you can provide a redeemer for script-locked DReps.

Usage Example:

// Using CIP-105 format (bech32-encoded DRep ID with specific prefix)
cardano_tx_builder_t* tx_builder = ...;    // Initialized transaction builder
const char* drep_id = "drep1q...";
size_t drep_id_size = strlen(drep_id);
const char* metadata_url = "https://example.com/drep_metadata.json";
size_t metadata_url_size = strlen(metadata_url);
const char* metadata_hash_hex = "abcdef123456...";  // Hex-encoded hash of metadata file
size_t metadata_hash_hex_size = strlen(metadata_hash_hex);
cardano_plutus_data_t* redeemer = ...;     // Optional redeemer data

cardano_tx_builder_update_drep_ex(
  tx_builder,
  drep_id,
  drep_id_size,
  metadata_url,
  metadata_url_size,
  metadata_hash_hex,
  metadata_hash_hex_size,
  redeemer);

Note

The drep_id must be in bech32 format as specified by either CIP-105 or CIP-129, which differ in their internal binary encoding. Ensure that the correct format is used according to the DRep’s identification scheme. Errors associated with updating the DRep will be deferred until cardano_tx_builder_build is called.

Parameters:¶

cardano_tx_builder_t *builder¶

[in] A pointer to the cardano_tx_builder_t instance managing the transaction.

const char *drep_id¶

[in] A pointer to a character array containing the DRep ID in bech32 format (either CIP-105 or CIP-129).

size_t drep_id_size¶

[in] The size of the drep_id string.

const char *metadata_url¶

[in] The URL pointing to the DRep metadata file.

size_t metadata_url_size¶

[in] The size of the metadata_url string.

const char *metadata_hash_hex¶

[in] The hash of the DRep metadata file in hexadecimal format.

size_t metadata_hash_hex_size¶

[in] The size of the metadata_hash_hex string.

cardano_plutus_data_t *redeemer¶

[in] An optional pointer to a cardano_plutus_data_t instance for providing redeemer data, which may be required for script-locked DReps.