Fee¶

cardano_error_t cardano_compute_transaction_fee(cardano_transaction_t *transaction, cardano_utxo_list_t *resolved_ref_inputs, cardano_protocol_parameters_t *protocol_params, uint64_t *fee)¶

Computes the minimum transaction fee.

This function computes the minimum required transaction fee for the provided transaction, based on the resolved inputs and protocol parameters. The calculated fee considers factors such as the transaction size, execution units consumed by plutus scripts and size of included reference scripts.

Reference scripts are always priced, whatever their language and whether or not the transaction has redeemers: the ledger charges for every reference script found on the outputs behind the reference inputs and the spend inputs of a transaction, even if the script never runs. resolved_ref_inputs must therefore resolve both kinds of inputs. They are priced with the reference script cost per byte, stride and multiplier of protocol_params, as cardano_compute_script_ref_fee_with_params documents: a stride or a multiplier that is not set, as in the parameters of the eras before Dijkstra, takes its Conway value.

A transaction that carries sub transactions pays the fee of the whole batch. The size of the sub transactions is part of the size of the transaction, and the execution units of the redeemers of every sub transaction are added to the ones of the transaction. The reference scripts of the sub transactions are included if the resolved UTXOs of their reference inputs and spend inputs are given in resolved_ref_inputs. Including them is deliberate and may exceed the current ledger minimum, which does not charge for the reference scripts of sub transactions yet.

Usage Example:

cardano_transaction_t* tx = ...;
cardano_utxo_list_t* resolved_ref_inputs = ...;
cardano_protocol_parameters_t* protocol_params = ...;
uint64_t computed_fee = 0;

cardano_error_t result = cardano_compute_transaction_fee(
  tx,
  resolved_ref_inputs,
  protocol_params,
  &computed_fee);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the fee
  // computed_fee contains the result
}
else
{
  // Handle error
}

Note

The transaction size and the execution unit requirements for Plutus scripts influence the final fee. Ensure that the resolved UTXOs match the reference inputs and the spend inputs specified in the transaction to compute accurate fees.

Parameters:¶

cardano_transaction_t *transaction¶: [in] The pointer to the cardano_transaction_t object representing the transaction.
cardano_utxo_list_t *resolved_ref_inputs¶: [in] A pointer to the cardano_utxo_list_t containing every resolved UTXO whose reference script is priced: the ones behind the reference inputs and the spend inputs of the transaction and of its sub transactions. Every entry is priced, so a UTXO that a body both references and spends must be listed once, and a UTXO used by several bodies once per body.
cardano_protocol_parameters_t *protocol_params¶: [in] The pointer to the cardano_protocol_parameters_t structure that contains protocol-related parameters for fee calculation.
uint64_t *fee¶: [out] A pointer to a uint64_t that will hold the computed transaction fee upon success.

Returns:¶

CARDANO_SUCCESS if the fee was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_compute_min_ada_required(cardano_transaction_output_t *output, uint64_t coins_per_utxo_byte, uint64_t *lovelace_required)¶

Computes the minimum ADA required for a transaction output.

This function calculates the minimum amount of ADA (in lovelace) that must be present in a UTXO, based on its size and the coins_per_utxo_byte parameter from the protocol. The size of the UTXO is determined by the provided transaction output object, and the protocol parameter coins_per_utxo_byte specifies the cost per byte for UTXOs.

Usage Example:

cardano_transaction_output_t* output = ...;
uint64_t coins_per_utxo_byte = 4310;  // Example value from protocol parameters
uint64_t min_ada = 0;

cardano_error_t result = cardano_compute_min_ada_required(output, coins_per_utxo_byte, &min_ada);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the minimum ADA required for the UTXO
  // min_ada now holds the result
}

Note

The minimum ADA ensures that the UTXO is valid and meets protocol requirements. It accounts for factors such as the size of the UTXO, including assets, scripts, and other elements within the output.

Parameters:¶

cardano_transaction_output_t *output¶: [in] The pointer to the cardano_transaction_output_t object representing the transaction output for which the minimum ADA is being calculated.
uint64_t coins_per_utxo_byte¶: [in] The protocol parameter specifying the cost in lovelace per byte of the UTXO.
uint64_t *lovelace_required¶: [out] A pointer to a uint64_t that will hold the calculated minimum amount of ADA (in lovelace) required for the UTXO.

Returns:¶

CARDANO_SUCCESS if the minimum ADA was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_compute_min_script_fee(cardano_transaction_t *tx, cardano_ex_unit_prices_t *prices, cardano_utxo_list_t *resolved_reference_inputs, cardano_unit_interval_t *coins_per_ref_script_byte, uint64_t *min_fee)¶

Computes the script part of the minimum fee of a transaction: execution units and reference scripts.

This function calculates the script part of the minimum fee of a transaction. The fee is based on:

The execution units required by the scripts.
The prices of execution units.
The size of the reference scripts and the cost per reference script byte.

The execution units are the total of the whole batch: the redeemers of the witness set of the transaction plus the redeemers of the witness set of every sub transaction it carries, since the transaction that carries the sub transactions pays for their script execution. A transaction without sub transactions only accounts for its own redeemers.

Reference scripts are always priced, whatever their language: when the batch has no redeemers the execution unit part of the fee is zero and the computed fee is the reference script fee alone. The reference scripts of the sub transactions resolved in resolved_reference_inputs are included. This is deliberate and may exceed the current ledger minimum, which does not charge for the reference scripts of sub transactions yet.

The reference scripts are priced as cardano_compute_script_ref_fee prices them, with the Conway values of the reference script cost stride and multiplier. cardano_compute_transaction_fee prices them with the stride and the multiplier of its protocol parameters instead.

Usage Example:

cardano_transaction_t* tx = ...;  // The transaction object
cardano_ex_unit_prices_t* prices = ...;  // Prices for execution units
cardano_utxo_list_t* resolved_reference_inputs = ...;  // List of resolved UTXOs
cardano_unit_interval_t* coins_per_ref_script_byte = ...;  // Cost per byte for reference scripts
uint64_t min_fee = 0;

cardano_error_t result = cardano_compute_min_script_fee(tx, prices, resolved_reference_inputs, coins_per_ref_script_byte, &min_fee);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the minimum fee for the transaction
  // min_fee now holds the calculated value
}

Note

The calculated fee accounts for the execution requirements of all the Plutus scripts included and for the size of every reference script listed in resolved_reference_inputs, measured as cardano_get_serialized_script_size documents.

Parameters:¶

cardano_transaction_t *tx¶: [in] The pointer to the cardano_transaction_t object representing the transaction for which the script fee is being calculated.
cardano_ex_unit_prices_t *prices¶: [in] The pointer to the cardano_ex_unit_prices_t object containing the prices for execution units (memory and steps).
cardano_utxo_list_t *resolved_reference_inputs¶: [in] A pointer to the cardano_utxo_list_t object holding every resolved UTXO whose reference script is priced: the ones behind the reference inputs and the spend inputs of the transaction and of its sub transactions. Every entry is priced, so a UTXO that a body both references and spends must be listed once, and a UTXO used by several bodies once per body.
cardano_unit_interval_t *coins_per_ref_script_byte¶: [in] The pointer to the cardano_unit_interval_t object representing the cost per byte of reference scripts.
uint64_t *min_fee¶: [out] A pointer to a uint64_t where the calculated minimum fee for the transaction will be stored.

Returns:¶

CARDANO_SUCCESS if the minimum script fee was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_compute_min_fee_without_scripts(cardano_transaction_t *tx, uint64_t min_fee_constant, uint64_t min_fee_coefficient, uint64_t *min_fee)¶

Computes the minimum fee required for a transaction without considering script costs.

This function calculates the minimum transaction fee based on the serialized size of the transaction and the protocol parameters for fee calculation. The fee is computed as:

\( \text{min_fee} = \text{min_fee_constant} + (\text{min_fee_coefficient} \times \text{tx_size}) \)

where tx_size is the size of the transaction in bytes.

Usage Example:

cardano_transaction_t* tx = ...;  // The transaction to calculate the fee for
uint64_t min_fee_constant = 155381;  // Example value from protocol parameters
uint64_t min_fee_coefficient = 44;   // Example value from protocol parameters
uint64_t min_fee = 0;

cardano_error_t result = cardano_compute_min_fee_without_scripts(tx, min_fee_constant, min_fee_coefficient, &min_fee);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the minimum fee
  // min_fee now holds the calculated fee
}

Note

This function only computes the base fee without considering any costs related to scripts or smart contract execution.

Parameters:¶

cardano_transaction_t *tx¶: [in] A pointer to the cardano_transaction_t object representing the transaction.
uint64_t min_fee_constant¶: [in] The constant fee factor (A) from the protocol parameters.
uint64_t min_fee_coefficient¶: [in] The fee-per-byte coefficient (B) from the protocol parameters.
uint64_t *min_fee¶: [out] A pointer to a uint64_t where the computed minimum fee will be stored.

Returns:¶

CARDANO_SUCCESS if the minimum fee was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_compute_script_ref_fee(cardano_utxo_list_t *resolved_reference_inputs, cardano_unit_interval_t *coins_per_ref_script_byte, uint64_t *script_ref_fee)¶

Computes the script reference fee for transaction inputs.

This function calculates the fee component that is contributed by reference scripts on the inputs of a transaction. The fee is computed based on the size of the reference scripts and the protocol parameter coins_per_ref_script_byte. The total size is priced in tiers of 25600 bytes, the last one possibly partial, and every tier costs 1.2 times as much per byte as the previous one. As the ledger does, the prices are exact fractions: the price of every tier is added exactly and the fee is the floor of the total, taken once, so no tier is rounded on its own. The tier size and the multiplier are the Conway values of the reference script cost stride and multiplier protocol parameters. To price with the stride and the multiplier of a parameter set, as the Dijkstra ledger does, use cardano_compute_script_ref_fee_with_params.

The fee is exact when the denominator of the price in lowest terms times 5 to the power of the number of tiers minus one fits in 64 bits, and the integer parts of the prices of the tiers and the fee fit too. A price with a very large denominator, such as one built with cardano_unit_interval_from_double, or a very large price can break that condition; the fee is then a conservative upper bound of the exact fee, which never falls below it and, for prices up to about 50 lovelace per byte, is within a lovelace of it.

The ledger charges for every reference script found on the outputs behind the reference inputs and the spend inputs of a transaction, whatever the language of the script (native scripts included) and whether or not the script runs. The size of each script is the one reported by cardano_get_serialized_script_size, which is the size the ledger prices.

The total size is not distinct: every entry of the list is counted, so a reference script that appears in several entries is priced once per entry. The ledger takes the inputs of a body as a set, so a UTXO that a body both references and spends must be listed once. Counting every entry matches how the ledger measures the reference script size of a batch, where a UTXO referenced by the transaction and by one of its sub transactions counts twice. For the sub transactions the ledger only applies that measure to the reference script size limit of the transaction and does not charge for their reference scripts yet. Including them in the list is deliberate and may exceed the current ledger minimum.

Usage Example:

cardano_utxo_list_t* resolved_ref_inputs = ...;  // Resolved UTXO inputs, potentially containing reference scripts
cardano_unit_interval_t* coins_per_ref_script_byte = ...;  // Protocol parameter for fee per byte of reference script
uint64_t script_ref_fee = 0;

cardano_error_t result = cardano_compute_script_ref_fee(resolved_ref_inputs, coins_per_ref_script_byte, &script_ref_fee);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the script reference fee
  // script_ref_fee now holds the calculated fee value
}

Note

This function helps determine the additional cost of including reference scripts in a transaction’s inputs based on the protocol’s fee model.

Parameters:¶

cardano_utxo_list_t *resolved_reference_inputs¶: [in] A pointer to the cardano_utxo_list_t object holding every resolved UTXO whose reference script is priced: the ones behind the reference inputs and the spend inputs of the transaction. Entries without a reference script add nothing.
cardano_unit_interval_t *coins_per_ref_script_byte¶: [in] The fee cost per byte of reference script data, as defined by the protocol parameters.
uint64_t *script_ref_fee¶: [out] A pointer to a uint64_t where the computed reference script fee will be stored.

Returns:¶

CARDANO_SUCCESS if the reference script fee was successfully computed, CARDANO_ERROR_INVALID_ARGUMENT if there are reference scripts to price and coins_per_ref_script_byte has a zero denominator, CARDANO_ERROR_INTEGER_OVERFLOW if the fee, or the upper bound computed in its place, does not fit in 64 bits, or another appropriate error code indicating failure. On failure script_ref_fee is set to zero.

cardano_error_t cardano_compute_script_ref_fee_with_params(cardano_utxo_list_t *resolved_reference_inputs, cardano_protocol_parameters_t *protocol_params, uint64_t *script_ref_fee)¶

Computes the script reference fee for transaction inputs with the reference script pricing of a set of protocol parameters.

This function prices the reference scripts of resolved_reference_inputs as cardano_compute_script_ref_fee does, with the tiered model of the ledger, but takes the price of a byte, the size of a tier and the multiplier from protocol_params: the reference script cost per byte, the reference script cost stride and the reference script cost multiplier. The ledger of Dijkstra reads the stride and the multiplier from its protocol parameters, while the earlier eras use the fixed values of 25600 bytes and 6/5, which is what cardano_compute_script_ref_fee uses.

A stride of 0 or a multiplier that is not set means the parameter set does not carry it, as the parameters of the eras before Dijkstra do not, and the Conway value is used in its place. When neither is set, the fee is the one cardano_compute_script_ref_fee computes. The multiplier is priced as the exact fraction it holds: the ledger requires it to be positive, and a multiplier below 1 lowers the price of every further tier. A multiplier with a zero numerator, which the ledger never produces, is not rejected and makes every tier after the first free.

The fee is exact when the denominator of the price in lowest terms times the denominator of the multiplier in lowest terms to the power of the number of tiers minus one fits in 64 bits, and the integer parts of the prices of the tiers and the fee fit too. A price or a multiplier with a large denominator, such as one built with cardano_unit_interval_from_double, many tiers or a very large price can break that condition; the fee is then a conservative upper bound of the exact fee, which never falls below it. The excess is a tiny fraction of the fee, usually a few lovelace at most, when the denominators are small, and grows with them, up to about a thousandth of the fee for a multiplier denominator around 10^15, as cardano_unit_interval_from_double produces. With denominators close to 2^64 the bound can be several times the exact fee.

Every entry of the list is counted, as cardano_compute_script_ref_fee documents, and the size of each script is the one reported by cardano_get_serialized_script_size.

Usage Example:

cardano_utxo_list_t* resolved_ref_inputs = ...;  // Resolved UTXO inputs, potentially containing reference scripts
cardano_protocol_parameters_t* protocol_params = ...;  // Protocol parameters of the current era
uint64_t script_ref_fee = 0;

cardano_error_t result = cardano_compute_script_ref_fee_with_params(resolved_ref_inputs, protocol_params, &script_ref_fee);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the script reference fee
  // script_ref_fee now holds the calculated fee value
}

Parameters:¶

cardano_utxo_list_t *resolved_reference_inputs¶: [in] A pointer to the cardano_utxo_list_t object holding every resolved UTXO whose reference script is priced: the ones behind the reference inputs and the spend inputs of the transaction. Entries without a reference script add nothing.
cardano_protocol_parameters_t *protocol_params¶: [in] The pointer to the cardano_protocol_parameters_t object that holds the reference script cost per byte, stride and multiplier.
uint64_t *script_ref_fee¶: [out] A pointer to a uint64_t where the computed reference script fee will be stored.

Returns:¶

CARDANO_SUCCESS if the reference script fee was successfully computed, CARDANO_ERROR_POINTER_IS_NULL if an argument is NULL or protocol_params has no reference script cost per byte, CARDANO_ERROR_INVALID_ARGUMENT if there are reference scripts to price and the cost per byte or the multiplier has a zero denominator, CARDANO_ERROR_INTEGER_OVERFLOW if the fee, or the upper bound computed in its place, does not fit in 64 bits, or another appropriate error code indicating failure. On failure after the arguments are checked, script_ref_fee is set to zero.

cardano_error_t cardano_get_total_ex_units_in_redeemers(cardano_redeemer_list_t *redeemers, cardano_ex_units_t **total)¶

Computes the total execution units (exUnits) from a list of redeemers.

This function aggregates the total execution units consumed by all redeemers in the provided cardano_redeemer_list_t. Execution units are a critical metric used in Plutus script evaluation, where both memory and CPU units are factored.

Usage Example:

cardano_redeemer_list_t* redeemers = ...;  // Redeemer list for the transaction
cardano_ex_units_t* total_ex_units = NULL;

cardano_error_t result = cardano_get_total_ex_units_in_redeemers(redeemers, &total_ex_units);

if (result == CARDANO_SUCCESS)
{
  // Successfully computed the total execution units for the redeemers
  // total_ex_units now holds the summed execution units
}

// Clean up after use
cardano_ex_units_unref(total_ex_units);

Note

The total object must be managed by the caller. After use, it should be properly de-referenced with cardano_ex_units_unref to avoid memory leaks.

Parameters:¶

cardano_redeemer_list_t *redeemers¶: [in] A pointer to the cardano_redeemer_list_t object representing the list of redeemers.
cardano_ex_units_t **total¶: [out] A pointer to a cardano_ex_units_t object where the total execution units will be stored. This will contain the sum of the memory and CPU units from all redeemers.

Returns:¶

CARDANO_SUCCESS if the total execution units were successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_get_serialized_coin_size(uint64_t lovelace, size_t *size_in_bytes)¶

Computes the serialized size of a given amount of lovelace.

This function calculates the size in bytes required to serialize a given amount of lovelace.

Usage Example:

uint64_t lovelace = 1000000;  // Example amount of 1 ADA
size_t size_in_bytes = 0;

cardano_error_t result = cardano_get_serialized_coin_size(lovelace, &size_in_bytes);

if (result == CARDANO_SUCCESS)
{
  // The size_in_bytes now holds the serialized size of the lovelace amount
}

Parameters:¶

uint64_t lovelace¶: [in] The amount of lovelace to calculate the serialized size for.
size_t *size_in_bytes¶: [out] A pointer to a size_t where the size of the serialized lovelace in bytes will be stored.

Returns:¶

CARDANO_SUCCESS if the size was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_get_serialized_output_size(cardano_transaction_output_t *output, size_t *size_in_bytes)¶

Computes the serialized size of a given transaction output.

This function calculates the size in bytes required to serialize a given transaction output.

Usage Example:

cardano_transaction_output_t* output = { ... };  // Assume this is initialized
size_t size_in_bytes = 0;

cardano_error_t result = cardano_get_serialized_output_size(output, &size_in_bytes);

if (result == CARDANO_SUCCESS)
{
  // The size_in_bytes now holds the serialized size of the output
}

Parameters:¶

cardano_transaction_output_t *output¶: [in] A pointer to the cardano_transaction_output_t object for which the serialized size is to be calculated.
size_t *size_in_bytes¶: [out] A pointer to a size_t where the size of the serialized output in bytes will be stored.

Returns:¶

CARDANO_SUCCESS if the size was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_get_serialized_script_size(cardano_script_t *script, size_t *size_in_bytes)¶

Computes the serialized size of a given script, the size the ledger prices for a reference script.

This function calculates the size in bytes of the serialized script alone, without the two element array that holds the language tag followed by the script in a script reference: for a Plutus script, the bytes of the script, the ones its byte string holds, without the header of the byte string; for a native script, the bytes of its CBOR. A native script decoded from CBOR is measured with the bytes it was decoded from, so a script stored on chain with a longer, non minimal encoding (for example a slot written as an 8 byte integer) is measured with those bytes, as the ledger measures it.

This is the size the ledger prices for a reference script, and the one cardano_compute_script_ref_fee prices. The encoding of the script with its language tag, as a script reference carries it, is the one cardano_script_to_cbor writes, which is 2 bytes larger for a native script and 3 to 7 bytes larger for a Plutus script.

Usage Example:

cardano_script_t* script = { ... };  // Assume this is initialized
size_t size_in_bytes = 0;

cardano_error_t result = cardano_get_serialized_script_size(script, &size_in_bytes);

if (result == CARDANO_SUCCESS)
{
  // The size_in_bytes now holds the serialized size of the script
}

Parameters:¶

cardano_script_t *script¶: [in] A pointer to the cardano_script_t object for which the serialized size is to be calculated.
size_t *size_in_bytes¶: [out] A pointer to a size_t where the size of the serialized script in bytes will be stored.

Returns:¶

CARDANO_SUCCESS if the size was successfully computed, or an appropriate error code indicating failure.

cardano_error_t cardano_get_serialized_transaction_size(cardano_transaction_t *transaction, size_t *size_in_bytes)¶

Computes the serialized size of a given transaction.

This function calculates the size in bytes required to serialize a given transaction.

Usage Example:

cardano_transaction_t* transaction = { ... };  // Assume this is initialized
size_t size_in_bytes = 0;

cardano_error_t result = cardano_get_serialized_transaction_size(transaction, &size_in_bytes);

if (result == CARDANO_SUCCESS)
{
  // The size_in_bytes now holds the serialized size of the transaction
}

Parameters:¶

cardano_transaction_t *transaction¶: [in] A pointer to the cardano_transaction_t object for which the serialized size is to be calculated.
size_t *size_in_bytes¶: [out] A pointer to a size_t where the size of the serialized transaction in bytes will be stored.

Returns:¶

CARDANO_SUCCESS if the size was successfully computed, or an appropriate error code indicating failure.