Protocol Parameters¶

typedef struct cardano_protocol_parameters_t cardano_protocol_parameters_t¶: Protocol parameters govern various aspects of the Cardano network.

cardano_error_t cardano_protocol_parameters_new(cardano_protocol_parameters_t **protocol_parameters)¶

Creates and initializes a new instance of the protocol parameters.

This function allocates and initializes a new instance of the protocol parameters, representing a set of updates to the Cardano protocol parameters.

Usage Example:

cardano_protocol_parameters_t* protocol_parameters = NULL;

// Attempt to create a new protocol parameters object
cardano_error_t result = cardano_protocol_parameters_new(&protocol_parameters);

if (result == CARDANO_SUCCESS)
{
  // Use the protocol_parameters

  // Once done, ensure to clean up and release the protocol_parameters
  cardano_protocol_parameters_unref(&protocol_parameters);
}

Parameters:¶

cardano_protocol_parameters_t **protocol_parameters¶: [out] On successful initialization, this will point to a newly created protocol parameters object. This object represents a “strong reference”, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the protocol parameters is no longer needed, the caller must release it by calling cardano_protocol_parameters_unref.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the protocol parameters was successfully created, or an appropriate error code indicating the failure reason.

uint64_t cardano_protocol_parameters_get_min_fee_a(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the linear minimum fee coefficient (a) from the protocol parameters.

This function returns the value of the linear fee coefficient (a) from the given cardano_protocol_parameters_t object. The minimum fee for a transaction is calculated using the formula:

min_fee = a * size_of_transaction + b

where a is the linear fee coefficient and b is the constant fee coefficient.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t min_fee_a = cardano_protocol_parameters_get_min_fee_a(protocol_params);

printf("Linear fee coefficient (a): %llu\n", min_fee_a);

Note

The linear fee coefficient is part of the Cardano network protocol parameters and is used to calculate the minimum required transaction fees.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The value of the linear fee coefficient (a). If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_min_fee_b(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the constant minimum fee coefficient (b) from the protocol parameters.

This function returns the value of the constant fee coefficient (b) from the given cardano_protocol_parameters_t object. The minimum fee for a transaction is calculated using the formula:

min_fee = a * size_of_transaction + b

where a is the linear fee coefficient and b is the constant fee coefficient.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t min_fee_b = cardano_protocol_parameters_get_min_fee_b(protocol_params);

printf("Constant fee coefficient (b): %llu\n", min_fee_b);

Note

The constant fee coefficient is part of the Cardano network protocol parameters and is used to calculate the minimum required transaction fees.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The value of the constant fee coefficient (b). If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_max_block_body_size(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum block body size from the protocol parameters.

This function returns the maximum size, in bytes, allowed for the body of a block in the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_block_body_size = cardano_protocol_parameters_get_max_block_body_size(protocol_params);

printf("Maximum block body size: %llu bytes\n", max_block_body_size);

Note

The block body size is a critical protocol parameter that limits the total size of all transactions and other data included in a single block on the Cardano blockchain.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum block body size in bytes. If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_max_tx_size(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum transaction size from the protocol parameters.

This function returns the maximum size, in bytes, allowed for a transaction in the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_tx_size = cardano_protocol_parameters_get_max_tx_size(protocol_params);

printf("Maximum transaction size: %llu bytes\n", max_tx_size);

Note

The maximum transaction size is a protocol parameter that limits the total size of a transaction, ensuring that it fits within a block.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum transaction size in bytes. If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_max_block_header_size(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum block header size from the protocol parameters.

This function returns the maximum size, in bytes, allowed for the header of a block in the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_block_header_size = cardano_protocol_parameters_get_max_block_header_size(protocol_params);

printf("Maximum block header size: %llu bytes\n", max_block_header_size);

Note

The block header contains essential metadata for the block, including the hash of the previous block, and this limit ensures that the header does not exceed the specified size.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum block header size in bytes. If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_key_deposit(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the key deposit value from the protocol parameters.

This function returns the key deposit required for staking key registration, as specified in the given cardano_protocol_parameters_t object. The key deposit is an amount of ADA required to register a staking key on the Cardano blockchain.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t key_deposit = cardano_protocol_parameters_get_key_deposit(protocol_params);

printf("Key deposit: %llu lovelaces\n", key_deposit);

Note

The key deposit is a refundable deposit required to participate in the staking process.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The key deposit amount in lovelaces (1 ADA = 1,000,000 lovelaces). If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_pool_deposit(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the pool deposit value from the protocol parameters.

This function returns the pool deposit required for registering a stake pool, as specified in the given cardano_protocol_parameters_t object. The pool deposit is an amount of ADA required to register a stake pool on the Cardano blockchain.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t pool_deposit = cardano_protocol_parameters_get_pool_deposit(protocol_params);

printf("Pool deposit: %llu lovelaces\n", pool_deposit);

Note

The pool deposit is a refundable deposit required for stake pool registration.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The pool deposit amount in lovelaces (1 ADA = 1,000,000 lovelaces). If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_max_epoch(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the max pool retirement epoch bounds.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_epoch = cardano_protocol_parameters_get_max_epoch(protocol_params);

printf("Maximum epoch duration: %llu slots\n", max_epoch);

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum epoch duration in slots. If the protocol_parameters pointer is NULL, the function will return 0.

uint64_t cardano_protocol_parameters_get_n_opt(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the desired number of stake pools (n_opt) from the protocol parameters.

This function returns the value of n_opt, which represents the optimal number of stake pools for the Cardano network, as specified in the given cardano_protocol_parameters_t object. This parameter is used to calculate pool rewards and incentivize decentralization.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t n_opt = cardano_protocol_parameters_get_n_opt(protocol_params);

printf("Optimal number of stake pools (n_opt): %llu\n", n_opt);

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The optimal number of stake pools (n_opt). If the protocol_parameters pointer is NULL, the function will return 0.

cardano_unit_interval_t *cardano_protocol_parameters_get_pool_pledge_influence(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the pool pledge influence factor from the protocol parameters.

This function returns the pool pledge influence factor (represented as a unit interval) from the given cardano_protocol_parameters_t object. The pool pledge influence factor determines how much a stake pool’s pledge (the amount of ADA the pool operator commits) influences the pool’s rewards.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* pledge_influence = cardano_protocol_parameters_get_pool_pledge_influence(protocol_params);

if (pledge_influence != NULL)
{
  // Use the pool pledge influence factor

  // Clean up when done
  cardano_unit_interval_unref(&pledge_influence);
}
else
{
  printf("Failed to retrieve the pool pledge influence factor.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_unit_interval_t object. Specifically, the caller must release the object by calling cardano_unit_interval_unref when it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_unit_interval_t object representing the pool pledge influence factor. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_unit_interval_t *cardano_protocol_parameters_get_expansion_rate(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the monetary expansion rate from the protocol parameters.

This function returns the expansion rate (represented as a unit interval) from the given cardano_protocol_parameters_t object. The expansion rate determines how much of the remaining reserves are added to the total supply of ADA in each epoch.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* expansion_rate = cardano_protocol_parameters_get_expansion_rate(protocol_params);

if (expansion_rate != NULL)
{
  // Use the expansion rate as needed

  // Clean up when done
  cardano_unit_interval_unref(&expansion_rate);
}
else
{
  printf("Failed to retrieve the expansion rate.\n");
}

Note

The expansion rate affects the rate at which ADA is gradually released from the reserves into circulation.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_unit_interval_t object representing the expansion rate. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_unit_interval_t *cardano_protocol_parameters_get_treasury_growth_rate(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the treasury growth rate from the protocol parameters.

This function returns the treasury growth rate (represented as a unit interval) from the given cardano_protocol_parameters_t object. The treasury growth rate determines the portion of the total monetary expansion that is allocated to the treasury, which is used to fund community-driven projects and developments.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* treasury_growth_rate = cardano_protocol_parameters_get_treasury_growth_rate(protocol_params);

if (treasury_growth_rate != NULL)
{
  // Use the treasury growth rate as needed

  // Clean up when done
  cardano_unit_interval_unref(&treasury_growth_rate);
}
else
{
  printf("Failed to retrieve the treasury growth rate.\n");
}

Note

The treasury growth rate affects how much of the monetary expansion goes into the treasury versus rewards for staking participants.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_unit_interval_t object representing the treasury growth rate. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_unit_interval_t *cardano_protocol_parameters_get_d(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the decentralization parameter (d) from the protocol parameters.

This function returns the decentralization parameter (represented as a unit interval) from the given cardano_protocol_parameters_t object. The decentralization parameter controls the proportion of blocks produced by federated nodes (IOHK, Emurgo, CF) versus community stake pools. A value of 1 means full centralization (all blocks produced by federated nodes), and a value of 0 means full decentralization.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* d_param = cardano_protocol_parameters_get_d(protocol_params);

if (d_param != NULL)
{
  // Use the decentralization parameter as needed

  // Clean up when done
  cardano_unit_interval_unref(&d_param);
}
else
{
  printf("Failed to retrieve the decentralization parameter.\n");
}

Note

The decentralization parameter affects the rate at which block production shifts from federated nodes to community-operated stake pools.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_unit_interval_t object representing the decentralization parameter. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_buffer_t *cardano_protocol_parameters_get_extra_entropy(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the extra entropy value from the protocol parameters.

This function returns the extra entropy value from the given cardano_protocol_parameters_t object. Extra entropy is an optional parameter that can be used to introduce additional randomness into the protocol’s random number generation process.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_buffer_t* extra_entropy = cardano_protocol_parameters_get_extra_entropy(protocol_params);

if (extra_entropy != NULL)
{
  // Use the extra entropy data

  // Clean up when done
  cardano_buffer_unref(&extra_entropy);
}
else
{
  printf("No extra entropy is set in the protocol parameters.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_buffer_t object. Specifically, the caller must release the object by calling cardano_buffer_unref when it is no longer needed.

Note

Extra entropy is an optional protocol parameter that may be used for adding randomness to certain processes, such as leader election, but it is not always set.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_buffer_t object containing the extra entropy data. If no extra entropy is set, or if the protocol_parameters pointer is NULL, the function returns NULL.

cardano_protocol_version_t *cardano_protocol_parameters_get_protocol_version(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the protocol version from the protocol parameters.

This function returns the protocol version from the given cardano_protocol_parameters_t object. The protocol version is used to track updates to the Cardano protocol, which may include changes to consensus rules or transaction formats.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_protocol_version_t* protocol_version = cardano_protocol_parameters_get_protocol_version(protocol_params);

if (protocol_version != NULL)
{
  // Use the protocol version as needed

  // Clean up when done
  cardano_protocol_version_unref(&protocol_version);
}
else
{
  printf("Failed to retrieve the protocol version.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_protocol_version_t object. Specifically, the caller must release the object by calling cardano_protocol_version_unref when it is no longer needed.

Note

The protocol version reflects the version of the Cardano protocol in use, which can change over time as improvements or updates are introduced through hard forks or other governance mechanisms.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_protocol_version_t object representing the protocol version. If the protocol_parameters pointer is NULL, the function returns NULL.

uint64_t cardano_protocol_parameters_get_min_pool_cost(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the minimum pool cost from the protocol parameters.

This function returns the minimum pool cost from the given cardano_protocol_parameters_t object. The minimum pool cost represents the minimum fixed fee that a stake pool operator must charge for delegators to participate in the pool.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t min_pool_cost = cardano_protocol_parameters_get_min_pool_cost(protocol_params);

printf("Minimum pool cost: %llu lovelaces\n", min_pool_cost);

Note

The minimum pool cost ensures that pool operators charge a base fee for providing services and helps sustain the operation of smaller pools in the Cardano ecosystem.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The minimum pool cost in lovelaces (1 ADA = 1,000,000 lovelaces). If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_ada_per_utxo_byte(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the ADA cost per UTXO byte from the protocol parameters.

This function returns the cost, in lovelaces, required per byte of UTXO stored on the blockchain, as specified in the given cardano_protocol_parameters_t object. This cost affects how much ADA is required to store UTXOs, incentivizing efficient use of the blockchain.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t ada_per_utxo_byte = cardano_protocol_parameters_get_ada_per_utxo_byte(protocol_params);

printf("ADA per UTXO byte: %llu lovelaces\n", ada_per_utxo_byte);

Note

The cost per UTXO byte ensures that there is a fee associated with storing UTXOs on the blockchain, helping to maintain the economic sustainability of the system.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The cost in lovelaces per UTXO byte. If the protocol_parameters pointer is NULL, the function will return 0.

cardano_costmdls_t *cardano_protocol_parameters_get_cost_models(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the cost models from the protocol parameters.

This function returns the cost models used to calculate the execution costs for Plutus smart contracts, as specified in the given cardano_protocol_parameters_t object. Each cost model defines the resource costs (such as CPU and memory) for executing various Plutus operations.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_costmdls_t* cost_models = cardano_protocol_parameters_get_cost_models(protocol_params);

if (cost_models != NULL)
{
  // Use the cost models as needed

  // Clean up when done
  cardano_costmdls_unref(&cost_models);
}
else
{
  printf("Failed to retrieve the cost models.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_costmdls_t object. Specifically, the caller must release the object by calling cardano_costmdls_unref when it is no longer needed.

Note

The cost models are essential for calculating the fees for Plutus script execution based on the resource usage specified by the smart contract.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_costmdls_t object representing the cost models. If the protocol_parameters pointer is NULL, the function will return NULL.

cardano_ex_unit_prices_t *cardano_protocol_parameters_get_execution_costs(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the execution unit prices from the protocol parameters.

This function returns the execution unit prices for Plutus script execution from the given cardano_protocol_parameters_t object. Execution unit prices define the cost of using resources such as CPU and memory during the execution of Plutus smart contracts.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_unit_prices_t* execution_costs = cardano_protocol_parameters_get_execution_costs(protocol_params);

if (execution_costs != NULL)
{
  // Use the execution unit prices as needed

  // Clean up when done
  cardano_ex_unit_prices_unref(&execution_costs);
}
else
{
  printf("Failed to retrieve the execution unit prices.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_ex_unit_prices_t object. Specifically, the caller must release the object by calling cardano_ex_unit_prices_unref when it is no longer needed.

Note

The execution unit prices are essential for calculating transaction fees based on the resource usage (CPU and memory) of Plutus smart contracts.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_ex_unit_prices_t object representing the execution unit prices. If the protocol_parameters pointer is NULL, the function will return NULL.

cardano_ex_units_t *cardano_protocol_parameters_get_max_tx_ex_units(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum execution units for a transaction from the protocol parameters.

This function returns the maximum execution units (CPU and memory) allowed for a single transaction on the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object. These execution units are used to limit the computational resources consumed by Plutus scripts within a transaction.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_units_t* max_tx_ex_units = cardano_protocol_parameters_get_max_tx_ex_units(protocol_params);

if (max_tx_ex_units != NULL)
{
  // Use the maximum execution units as needed

  // Clean up when done
  cardano_ex_units_unref(&max_tx_ex_units);
}
else
{
  printf("Failed to retrieve the maximum transaction execution units.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_ex_units_t object. Specifically, the caller must release the object by calling cardano_ex_units_unref when it is no longer needed.

Note

These limits ensure that a transaction does not consume excessive computational resources, helping maintain the overall efficiency of the network.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_ex_units_t object representing the maximum execution units for a transaction. If the protocol_parameters pointer is NULL, the function will return NULL.

cardano_ex_units_t *cardano_protocol_parameters_get_max_block_ex_units(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum execution units for a block from the protocol parameters.

This function returns the maximum execution units (CPU and memory) allowed for a single block on the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object. These execution units are used to limit the computational resources consumed by Plutus scripts within all transactions in a block.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_units_t* max_block_ex_units = cardano_protocol_parameters_get_max_block_ex_units(protocol_params);

if (max_block_ex_units != NULL)
{
  // Use the maximum block execution units as needed

  // Clean up when done
  cardano_ex_units_unref(&max_block_ex_units);
}
else
{
  printf("Failed to retrieve the maximum block execution units.\n");
}

Note

These limits ensure that no single block can consume excessive computational resources, maintaining network performance and security.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_ex_units_t object representing the maximum execution units for a block. If the protocol_parameters pointer is NULL, the function will return NULL.

uint64_t cardano_protocol_parameters_get_max_value_size(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum value size from the protocol parameters.

This function returns the maximum size (in bytes) allowed for a transaction output’s value in the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object. The value size includes the amount of ADA and any additional tokens in the transaction output.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_value_size = cardano_protocol_parameters_get_max_value_size(protocol_params);

printf("Maximum value size: %llu bytes\n", max_value_size);

Note

The maximum value size helps ensure that individual transaction outputs do not exceed the size limits, maintaining efficiency and preventing potential abuse of network resources.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum value size in bytes. If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_collateral_percentage(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the collateral percentage required for Plutus scripts from the protocol parameters.

This function returns the percentage of the transaction fee that must be provided as collateral for Plutus script execution, as specified in the given cardano_protocol_parameters_t object. Collateral is required to cover the costs if a Plutus script fails to execute.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t collateral_percentage = cardano_protocol_parameters_get_collateral_percentage(protocol_params);

printf("Collateral percentage: %llu%%\n", collateral_percentage);

Note

The collateral percentage determines how much ADA must be set aside to cover potential costs associated with failed Plutus script execution. This amount is based on the total transaction fee.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The collateral percentage as an integer value. If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_max_collateral_inputs(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the maximum number of collateral inputs allowed for a transaction from the protocol parameters.

This function returns the maximum number of collateral inputs that can be included in a transaction on the Cardano blockchain, as specified in the given cardano_protocol_parameters_t object. Collateral inputs are required to cover transaction costs in case of failed Plutus script execution.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t max_collateral_inputs = cardano_protocol_parameters_get_max_collateral_inputs(protocol_params);

printf("Maximum collateral inputs: %llu\n", max_collateral_inputs);

Note

The maximum number of collateral inputs ensures that transactions cannot include an excessive number of collateral inputs, helping maintain network performance and preventing potential abuse.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The maximum number of collateral inputs allowed for a transaction. If the protocol_parameters pointer is NULL, the function returns 0.

cardano_pool_voting_thresholds_t *cardano_protocol_parameters_get_pool_voting_thresholds(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the pool voting thresholds from the protocol parameters.

This function returns the voting thresholds for stake pools, as specified in the given cardano_protocol_parameters_t object.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_pool_voting_thresholds_t* voting_thresholds = cardano_protocol_parameters_get_pool_voting_thresholds(protocol_params);

if (voting_thresholds != NULL)
{
  // Use the voting thresholds as needed

  // Clean up when done
  cardano_pool_voting_thresholds_unref(&voting_thresholds);
}
else
{
  printf("Failed to retrieve the pool voting thresholds.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_pool_voting_thresholds_t object. Specifically, the caller must release the object by calling cardano_pool_voting_thresholds_unref when it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_pool_voting_thresholds_t object representing the pool voting thresholds. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_drep_voting_thresholds_t *cardano_protocol_parameters_get_drep_voting_thresholds(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the DRep voting thresholds from the protocol parameters.

This function returns the voting thresholds for decentralized representatives (DReps) as specified in the given cardano_protocol_parameters_t object.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_drep_voting_thresholds_t* drep_voting_thresholds = cardano_protocol_parameters_get_drep_voting_thresholds(protocol_params);

if (drep_voting_thresholds != NULL)
{
  // Use the DRep voting thresholds as needed

  // Clean up when done
  cardano_drep_voting_thresholds_unref(&drep_voting_thresholds);
}
else
{
  printf("Failed to retrieve the DRep voting thresholds.\n");
}

Note

The caller is responsible for managing the lifecycle of the returned cardano_drep_voting_thresholds_t object. Specifically, the caller must release the object by calling cardano_drep_voting_thresholds_unref when it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_drep_voting_thresholds_t object representing the DRep voting thresholds. If the protocol_parameters pointer is NULL, the function returns NULL.

uint64_t cardano_protocol_parameters_get_min_committee_size(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the minimum committee size from the protocol parameters.

This function returns the minimum size of the governance committee as specified in the given cardano_protocol_parameters_t object. The committee size is relevant for governance-related decisions on the Cardano blockchain.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t min_committee_size = cardano_protocol_parameters_get_min_committee_size(protocol_params);

printf("Minimum committee size: %llu\n", min_committee_size);

Note

The minimum committee size defines the number of members required to form a valid governance committee for making decisions on protocol changes and other governance activities.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The minimum committee size as a 64-bit unsigned integer. If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_committee_term_limit(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the committee term limit from the protocol parameters.

This function returns the maximum number of terms a committee member can serve, as specified in the given cardano_protocol_parameters_t object. The term limit helps define governance rules for the rotation and tenure of committee members on the Cardano blockchain.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t committee_term_limit = cardano_protocol_parameters_get_committee_term_limit(protocol_params);

printf("Committee term limit: %llu terms\n", committee_term_limit);

Note

The committee term limit defines how long a member can serve on the governance committee before requiring rotation or re-election, contributing to governance stability.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The committee term limit as a 64-bit unsigned integer. If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_governance_action_validity_period(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the governance action validity period from the protocol parameters.

This function returns the validity period for governance actions, as specified in the given cardano_protocol_parameters_t object. The validity period determines the length of time a governance action remains valid before expiring.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t validity_period = cardano_protocol_parameters_get_governance_action_validity_period(protocol_params);

printf("Governance action validity period: %llu slots\n", validity_period);

Note

The governance action validity period ensures that governance proposals and actions have a defined lifespan, ensuring timely decision-making and avoiding stale actions.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The governance action validity period as a 64-bit unsigned integer, representing the number of slots. If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_governance_action_deposit(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the deposit required for submitting a governance action from the protocol parameters.

This function returns the deposit amount required to submit a governance action, as specified in the given cardano_protocol_parameters_t object. The deposit is required to discourage spam proposals and to ensure that proposers are committed to the action.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t governance_deposit = cardano_protocol_parameters_get_governance_action_deposit(protocol_params);

printf("Governance action deposit: %llu lovelaces\n", governance_deposit);

Note

The governance action deposit ensures that there is a cost associated with submitting proposals, which helps maintain the quality and seriousness of governance actions.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The deposit required for governance actions, in lovelaces (1 ADA = 1,000,000 lovelaces). If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_drep_deposit(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the deposit required for registering as a DRep (Decentralized Representative) from the protocol parameters.

This function returns the deposit amount required to register as a DRep, as specified in the given cardano_protocol_parameters_t object. The deposit is required to ensure that DRep candidates are committed to participating in governance.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t drep_deposit = cardano_protocol_parameters_get_drep_deposit(protocol_params);

printf("DRep registration deposit: %llu lovelaces\n", drep_deposit);

Note

The DRep deposit ensures that registering as a Decentralized Representative carries a cost, preventing spam registrations and ensuring that candidates are committed.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The DRep registration deposit in lovelaces (1 ADA = 1,000,000 lovelaces). If the protocol_parameters pointer is NULL, the function returns 0.

uint64_t cardano_protocol_parameters_get_drep_inactivity_period(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the DRep (Decentralized Representative) inactivity period from the protocol parameters.

This function returns the inactivity period for a DRep, as specified in the given cardano_protocol_parameters_t object. The inactivity period defines how long a DRep can remain inactive (i.e., without participating in governance actions) before they are considered inactive.

Usage Example:

const cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t inactivity_period = cardano_protocol_parameters_get_drep_inactivity_period(protocol_params);

printf("DRep inactivity period: %llu slots\n", inactivity_period);

Note

The DRep inactivity period ensures that DReps remain active in governance decisions. If a DRep does not participate in governance for this period, they may be removed or flagged as inactive.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

The DRep inactivity period as a 64-bit unsigned integer representing the number of slots. If the protocol_parameters pointer is NULL, the function returns 0.

cardano_unit_interval_t *cardano_protocol_parameters_get_ref_script_cost_per_byte(cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the cost per byte for reference scripts from the protocol parameters.

This function returns the cost per byte associated with storing a reference script, as specified in the given cardano_protocol_parameters_t object. Reference scripts allow transactions to use Plutus scripts without including the full script in each transaction, optimizing storage and efficiency.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* script_cost = cardano_protocol_parameters_get_ref_script_cost_per_byte(protocol_params);

if (script_cost != NULL)
{
  // Use the reference script cost per byte as needed

  // Clean up when done
  cardano_unit_interval_unref(&script_cost);
}
else
{
  printf("Failed to retrieve the reference script cost per byte.\n");
}

Note

The cost per byte is important for calculating the storage fees associated with storing reference scripts on-chain, ensuring fair pricing for transactions that utilize reference scripts.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.

Returns:¶

A pointer to a cardano_unit_interval_t object representing the cost per byte for reference scripts. If the protocol_parameters pointer is NULL, the function returns NULL.

cardano_error_t cardano_protocol_parameters_set_min_fee_a(cardano_protocol_parameters_t *protocol_parameters, uint64_t min_fee_a)¶

Sets the minimum fee coefficient “A” in the protocol parameters.

This function sets the minimum fee coefficient “A” in the given cardano_protocol_parameters_t object. The “A” parameter is part of the fee calculation formula that determines the minimum fee for transactions. The formula is: fee = A * size + B, where “A” is the multiplier for the transaction size and “B” is the fixed constant.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_min_fee_a = 44; // New value for the fee coefficient "A"

cardano_error_t result = cardano_protocol_parameters_set_min_fee_a(protocol_params, new_min_fee_a);

if (result == CARDANO_SUCCESS)
{
  printf("Minimum fee coefficient 'A' set successfully.\n");
}
else
{
  printf("Failed to set minimum fee coefficient 'A'.\n");
}

Note

The minimum fee coefficient “A” is an important parameter in determining the cost of transactions, ensuring that larger transactions pay a proportional fee based on their size.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t min_fee_a¶: [in] The new value for the minimum fee coefficient “A”.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the minimum fee coefficient “A” was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_min_fee_b(cardano_protocol_parameters_t *protocol_parameters, uint64_t min_fee_b)¶

Sets the minimum fee constant “B” in the protocol parameters.

This function sets the minimum fee constant “B” in the given cardano_protocol_parameters_t object. The “B” parameter is part of the fee calculation formula that determines the minimum fee for transactions. The formula is: fee = A * size + B, where “A” is the multiplier for the transaction size and “B” is the fixed constant.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_min_fee_b = 155381; // New value for the fee constant "B"

cardano_error_t result = cardano_protocol_parameters_set_min_fee_b(protocol_params, new_min_fee_b);

if (result == CARDANO_SUCCESS)
{
  printf("Minimum fee constant 'B' set successfully.\n");
}
else
{
  printf("Failed to set minimum fee constant 'B'.\n");
}

Note

The minimum fee constant “B” ensures that every transaction pays a base fee, independent of its size. This base fee prevents spam and ensures a minimum cost for processing any transaction.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t min_fee_b¶: [in] The new value for the minimum fee constant “B”.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the minimum fee constant “B” was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_block_body_size(cardano_protocol_parameters_t *protocol_parameters, uint64_t max_block_body_size)¶

Sets the maximum block body size in the protocol parameters.

This function sets the maximum allowable size (in bytes) for a block’s body in the given cardano_protocol_parameters_t object. The block body includes the actual transaction data and other relevant information within a block.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_max_block_body_size = 65536; // New value for the maximum block body size in bytes

cardano_error_t result = cardano_protocol_parameters_set_max_block_body_size(protocol_params, new_max_block_body_size);

if (result == CARDANO_SUCCESS)
{
  printf("Maximum block body size set successfully.\n");
}
else
{
  printf("Failed to set maximum block body size.\n");
}

Note

The maximum block body size defines the upper limit on how large a block’s body can be, ensuring that blocks remain within a manageable size for network transmission and validation.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t max_block_body_size¶: [in] The new maximum block body size, in bytes.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum block body size was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_tx_size(cardano_protocol_parameters_t *protocol_parameters, uint64_t max_tx_size)¶

Sets the maximum transaction size in the protocol parameters.

This function sets the maximum allowable size (in bytes) for a transaction in the given cardano_protocol_parameters_t object. The transaction size includes all the data required to validate and execute the transaction on the Cardano blockchain.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_max_tx_size = 16384; // New value for the maximum transaction size in bytes

cardano_error_t result = cardano_protocol_parameters_set_max_tx_size(protocol_params, new_max_tx_size);

if (result == CARDANO_SUCCESS)
{
  printf("Maximum transaction size set successfully.\n");
}
else
{
  printf("Failed to set maximum transaction size.\n");
}

Note

The maximum transaction size ensures that individual transactions do not exceed a specified size limit, which helps maintain network efficiency and prevents oversized transactions from overloading the system.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t max_tx_size¶: [in] The new maximum transaction size, in bytes.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum transaction size was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_block_header_size(cardano_protocol_parameters_t *protocol_parameters, uint64_t max_block_header_size)¶

Sets the maximum block header size in the protocol parameters.

This function sets the maximum allowable size (in bytes) for a block’s header in the given cardano_protocol_parameters_t object. The block header contains essential information about the block, such as metadata, the previous block’s hash, and other necessary validation data.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_max_block_header_size = 1100; // New value for the maximum block header size in bytes

cardano_error_t result = cardano_protocol_parameters_set_max_block_header_size(protocol_params, new_max_block_header_size);

if (result == CARDANO_SUCCESS)
{
  printf("Maximum block header size set successfully.\n");
}
else
{
  printf("Failed to set maximum block header size.\n");
}

Note

The maximum block header size defines the upper limit on how large the header of a block can be, ensuring that headers remain manageable for storage, validation, and transmission across the network.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t max_block_header_size¶: [in] The new maximum block header size, in bytes.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum block header size was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_key_deposit(cardano_protocol_parameters_t *protocol_parameters, uint64_t key_deposit)¶

Sets the key deposit value in the protocol parameters.

This function sets the deposit amount required for registering a new stake key in the given cardano_protocol_parameters_t object. The key deposit helps prevent spam registrations of stake keys by requiring users to deposit a certain amount of ADA when registering a new key.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_key_deposit = 2000000; // New value for the key deposit (2 ADA in lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_key_deposit(protocol_params, new_key_deposit);

if (result == CARDANO_SUCCESS)
{
  printf("Key deposit set successfully.\n");
}
else
{
  printf("Failed to set key deposit.\n");
}

Note

The key deposit helps secure the network by requiring a financial commitment for registering a stake key, which is returned when the key is deregistered.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t key_deposit¶: [in] The new key deposit value, in lovelaces (1 ADA = 1,000,000 lovelaces).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the key deposit value was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_pool_deposit(cardano_protocol_parameters_t *protocol_parameters, uint64_t pool_deposit)¶

Sets the pool deposit value in the protocol parameters.

This function sets the deposit amount required for registering a new stake pool in the given cardano_protocol_parameters_t object. The pool deposit helps ensure that pool operators are committed to maintaining their stake pool by requiring a financial commitment.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_pool_deposit = 500000000; // New value for the pool deposit (500 ADA in lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_pool_deposit(protocol_params, new_pool_deposit);

if (result == CARDANO_SUCCESS)
{
  printf("Pool deposit set successfully.\n");
}
else
{
  printf("Failed to set pool deposit.\n");
}

Note

The pool deposit is returned to the pool operator when the pool is deregistered. It is designed to prevent spam or low-effort stake pools from being created.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t pool_deposit¶: [in] The new pool deposit value, in lovelaces (1 ADA = 1,000,000 lovelaces).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the pool deposit value was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_epoch(cardano_protocol_parameters_t *protocol_parameters, uint64_t max_epoch)¶

Sets the maximum epoch duration in the protocol parameters.

This function sets the maximum number of epochs for which certain operations (such as stake key registrations or pool certificates) remain valid, as specified in the given cardano_protocol_parameters_t object. The maximum epoch defines the lifespan of these operations within the blockchain.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_max_epoch = 21600; // New value for the maximum epoch

cardano_error_t result = cardano_protocol_parameters_set_max_epoch(protocol_params, new_max_epoch);

if (result == CARDANO_SUCCESS)
{
  printf("Maximum epoch set successfully.\n");
}
else
{
  printf("Failed to set maximum epoch.\n");
}

Note

Setting a maximum epoch ensures that certain blockchain operations and commitments have a limited duration and need to be re-registered or updated after the specified period.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t max_epoch¶: [in] The new maximum epoch value.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum epoch was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_n_opt(cardano_protocol_parameters_t *protocol_parameters, uint64_t n_opt)¶

Sets the optimal number of stake pools (n_opt) in the protocol parameters.

This function sets the optimal number of stake pools (n_opt) in the given cardano_protocol_parameters_t object. The n_opt parameter is used to calculate rewards and incentivize the desired level of decentralization within the network.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_n_opt = 500; // New value for the optimal number of stake pools

cardano_error_t result = cardano_protocol_parameters_set_n_opt(protocol_params, new_n_opt);

if (result == CARDANO_SUCCESS)
{
  printf("Optimal number of stake pools (n_opt) set successfully.\n");
}
else
{
  printf("Failed to set optimal number of stake pools.\n");
}

Note

The n_opt value plays a key role in determining the distribution of staking rewards across pools and is important for achieving the desired level of decentralization in the network.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t n_opt¶: [in] The new value for the optimal number of stake pools.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the optimal number of stake pools was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_pool_pledge_influence(cardano_protocol_parameters_t *protocol_parameters, cardano_unit_interval_t *pool_pledge_influence)¶

Sets the pool pledge influence (a0) in the protocol parameters.

This function sets the pool pledge influence (a0) in the given cardano_protocol_parameters_t object. The pool pledge influence determines how much a stake pool’s pledge (the amount of ADA the pool operator commits) affects the rewards distribution. A higher pledge results in a higher ranking for the stake pool, which influences the rewards the pool receives.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* new_pledge_influence = ...; // Assume new_pledge_influence is initialized

cardano_error_t result = cardano_protocol_parameters_set_pool_pledge_influence(protocol_params, new_pledge_influence);

if (result == CARDANO_SUCCESS)
{
  printf("Pool pledge influence set successfully.\n");
}
else
{
  printf("Failed to set pool pledge influence.\n");
}

// Clean up when done
cardano_unit_interval_unref(&new_pledge_influence);

Note

The caller is responsible for managing the lifecycle of the cardano_unit_interval_t object. The object must be released by calling cardano_unit_interval_unref when it is no longer needed.

Note

The pool pledge influence is crucial in encouraging stake pool operators to commit more ADA to their pool, helping to secure the network.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_unit_interval_t *pool_pledge_influence¶: [in] A pointer to an initialized cardano_unit_interval_t object representing the new pool pledge influence. This value must be between 0 and 1 (inclusive).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the pool pledge influence was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_expansion_rate(cardano_protocol_parameters_t *protocol_parameters, cardano_unit_interval_t *expansion_rate)¶

Sets the expansion rate in the protocol parameters.

This function sets the expansion rate in the given cardano_protocol_parameters_t object. The expansion rate controls how much of the rewards are taken from reserves and added to the total rewards distributed to stakers. It is expressed as a unit interval between 0 and 1, where 1 means the entire reward comes from reserves.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* new_expansion_rate = ...; // Assume new_expansion_rate is initialized

cardano_error_t result = cardano_protocol_parameters_set_expansion_rate(protocol_params, new_expansion_rate);

if (result == CARDANO_SUCCESS)
{
  printf("Expansion rate set successfully.\n");
}
else
{
  printf("Failed to set expansion rate.\n");
}

// Clean up when done
cardano_unit_interval_unref(&new_expansion_rate);

Note

The caller is responsible for managing the lifecycle of the cardano_unit_interval_t object. The object must be released by calling cardano_unit_interval_unref when it is no longer needed.

Note

The expansion rate defines the percentage of new ADA minted in each epoch and controls how quickly the total supply of ADA increases over time.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_unit_interval_t *expansion_rate¶: [in] A pointer to an initialized cardano_unit_interval_t object representing the new expansion rate. This value must be between 0 and 1 (inclusive).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the expansion rate was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_treasury_growth_rate(cardano_protocol_parameters_t *protocol_parameters, cardano_unit_interval_t *treasury_growth_rate)¶

Sets the treasury growth rate in the protocol parameters.

This function sets the treasury growth rate in the given cardano_protocol_parameters_t object. The treasury growth rate determines the proportion of rewards that are allocated to the treasury, which funds governance and development activities. It is expressed as a unit interval between 0 and 1, where 1 means all rewards go to the treasury.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* new_treasury_growth_rate = ...; // Assume new_treasury_growth_rate is initialized

cardano_error_t result = cardano_protocol_parameters_set_treasury_growth_rate(protocol_params, new_treasury_growth_rate);

if (result == CARDANO_SUCCESS)
{
  printf("Treasury growth rate set successfully.\n");
}
else
{
  printf("Failed to set treasury growth rate.\n");
}

// Clean up when done
cardano_unit_interval_unref(&new_treasury_growth_rate);

Note

The caller is responsible for managing the lifecycle of the cardano_unit_interval_t object. The object must be released by calling cardano_unit_interval_unref when it is no longer needed.

Note

The treasury growth rate defines how much of the staking rewards are redirected to the treasury to fund community-driven projects and governance.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_unit_interval_t *treasury_growth_rate¶: [in] A pointer to an initialized cardano_unit_interval_t object representing the new treasury growth rate. This value must be between 0 and 1 (inclusive).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the treasury growth rate was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_d(cardano_protocol_parameters_t *protocol_parameters, cardano_unit_interval_t *d)¶

Sets the decentralization parameter (d) in the protocol parameters.

This function sets the decentralization parameter (d) in the given cardano_protocol_parameters_t object. The decentralization parameter controls the extent to which the network is decentralized. As the value of d approaches 0, the network becomes more decentralized, with more blocks being produced by the community rather than by centralized entities. The value is expressed as a unit interval between 0 and 1, where 1 indicates full centralization and 0 represents full decentralization.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* new_d = ...; // Assume new_d is initialized

cardano_error_t result = cardano_protocol_parameters_set_d(protocol_params, new_d);

if (result == CARDANO_SUCCESS)
{
  printf("Decentralization parameter set successfully.\n");
}
else
{
  printf("Failed to set decentralization parameter.\n");
}

// Clean up when done
cardano_unit_interval_unref(&new_d);

Note

The caller is responsible for managing the lifecycle of the cardano_unit_interval_t object. The object must be released by calling cardano_unit_interval_unref when it is no longer needed.

Note

The decentralization parameter (d) defines how decentralized the network is, influencing the control over block production.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_unit_interval_t *d¶: [in] A pointer to an initialized cardano_unit_interval_t object representing the new decentralization parameter (d). This value must be between 0 and 1 (inclusive).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the decentralization parameter was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_extra_entropy(cardano_protocol_parameters_t *protocol_parameters, cardano_buffer_t *extra_entropy)¶

Sets the extra entropy value in the protocol parameters.

This function sets the extra entropy in the given cardano_protocol_parameters_t object. Extra entropy allows for additional randomness to be injected into the protocol, contributing to the randomness used in leader election and other protocol processes.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_buffer_t* new_extra_entropy = ...; // Assume new_extra_entropy is initialized

cardano_error_t result = cardano_protocol_parameters_set_extra_entropy(protocol_params, new_extra_entropy);

if (result == CARDANO_SUCCESS)
{
  printf("Extra entropy set successfully.\n");
}
else
{
  printf("Failed to set extra entropy.\n");
}

// Clean up when done
cardano_buffer_unref(&new_extra_entropy);

Note

The caller is responsible for managing the lifecycle of the cardano_buffer_t object. The object must be released by calling cardano_buffer_unref when it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_buffer_t *extra_entropy¶: [in] A pointer to an initialized cardano_buffer_t object representing the new extra entropy. This can be used to provide additional randomness for protocol operations. Passing NULL will unset the extra entropy.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the extra entropy was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_protocol_version(cardano_protocol_parameters_t *protocol_parameters, cardano_protocol_version_t *protocol_version)¶

Sets the protocol version in the protocol parameters.

This function sets the protocol version in the given cardano_protocol_parameters_t object. The protocol version indicates the current version of the Cardano protocol being used, and it can be updated as part of governance decisions and protocol upgrades.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_protocol_version_t* new_protocol_version = ...; // Assume new_protocol_version is initialized

cardano_error_t result = cardano_protocol_parameters_set_protocol_version(protocol_params, new_protocol_version);

if (result == CARDANO_SUCCESS)
{
  printf("Protocol version set successfully.\n");
}
else
{
  printf("Failed to set protocol version.\n");
}

// Clean up when done
cardano_protocol_version_unref(&new_protocol_version);

Note

The caller is responsible for managing the lifecycle of the cardano_protocol_version_t object. The object must be released by calling cardano_protocol_version_unref when it is no longer needed.

Note

The protocol version is critical to ensuring network consensus and smooth upgrades, allowing nodes to recognize and adapt to changes in protocol rules.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_protocol_version_t *protocol_version¶: [in] A pointer to an initialized cardano_protocol_version_t object representing the new protocol version.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the protocol version was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_min_pool_cost(cardano_protocol_parameters_t *protocol_parameters, uint64_t min_pool_cost)¶

Sets the minimum pool cost in the protocol parameters.

This function sets the minimum pool cost in the given cardano_protocol_parameters_t object. The minimum pool cost defines the least amount of ADA that a stake pool can charge as fees in order to cover its operational costs. This ensures that pool operators are incentivized to maintain their pools and remain competitive in the network.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_min_pool_cost = 340000000; // New value for the minimum pool cost (340 ADA in lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_min_pool_cost(protocol_params, new_min_pool_cost);

if (result == CARDANO_SUCCESS)
{
  printf("Minimum pool cost set successfully.\n");
}
else
{
  printf("Failed to set minimum pool cost.\n");
}

Note

Setting an appropriate minimum pool cost helps prevent spam or low-effort stake pools from undercharging and destabilizing the network.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t min_pool_cost¶: [in] The new minimum pool cost value, in lovelaces (1 ADA = 1,000,000 lovelaces).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the minimum pool cost was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_ada_per_utxo_byte(cardano_protocol_parameters_t *protocol_parameters, uint64_t ada_per_utxo_byte)¶

Sets the ADA per UTXO byte in the protocol parameters.

This function sets the cost, in ADA, per byte of UTXO storage in the given cardano_protocol_parameters_t object. The ADA per UTXO byte parameter defines how much ADA is required to store each byte of a UTXO (Unspent Transaction Output). This helps ensure that the blockchain remains efficient by incentivizing smaller UTXO sizes and discouraging excessive on-chain storage.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_ada_per_utxo_byte = 4310; // New value for ADA per UTXO byte (in lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_ada_per_utxo_byte(protocol_params, new_ada_per_utxo_byte);

if (result == CARDANO_SUCCESS)
{
  printf("ADA per UTXO byte set successfully.\n");
}
else
{
  printf("Failed to set ADA per UTXO byte.\n");
}

Note

This value helps maintain efficient storage usage on the blockchain by charging for UTXO space. A higher value may encourage smaller, more efficient transactions.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t ada_per_utxo_byte¶: [in] The new ADA per UTXO byte value, in lovelaces (1 ADA = 1,000,000 lovelaces).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the ADA per UTXO byte value was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_cost_models(cardano_protocol_parameters_t *protocol_parameters, cardano_costmdls_t *cost_models)¶

Sets the cost models in the protocol parameters.

This function sets the cost models in the given cardano_protocol_parameters_t object. Cost models define the computational costs associated with running Plutus scripts on the blockchain. Each cost model specifies how much computational resources (in terms of CPU and memory) different operations within a script will consume, and this is used to determine the fees that will be charged for executing those scripts.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_costmdls_t* new_cost_models = ...; // Assume new_cost_models is initialized

cardano_error_t result = cardano_protocol_parameters_set_cost_models(protocol_params, new_cost_models);

if (result == CARDANO_SUCCESS)
{
  printf("Cost models set successfully.\n");
}
else
{
  printf("Failed to set cost models.\n");
}

// Clean up when done
cardano_costmdls_unref(&new_cost_models);

Note

The caller is responsible for managing the lifecycle of the cardano_costmdls_t object. The object must be released by calling cardano_costmdls_unref when it is no longer needed.

Note

Setting accurate cost models ensures that transaction fees fairly reflect the computational resources consumed by Plutus scripts.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_costmdls_t *cost_models¶: [in] A pointer to an initialized cardano_costmdls_t object representing the new cost models. These cost models will replace any previously set models in the protocol parameters.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the cost models were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_execution_costs(cardano_protocol_parameters_t *protocol_parameters, cardano_ex_unit_prices_t *execution_costs)¶

Sets the execution costs in the protocol parameters.

This function sets the execution costs (or ex-unit prices) in the given cardano_protocol_parameters_t object. Execution costs define the fees for running Plutus smart contracts, represented as prices for each execution unit (ex-unit) of CPU and memory. These prices determine how much a transaction that includes Plutus scripts will need to pay for using computational resources on the blockchain.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_unit_prices_t* new_execution_costs = ...; // Assume new_execution_costs is initialized

cardano_error_t result = cardano_protocol_parameters_set_execution_costs(protocol_params, new_execution_costs);

if (result == CARDANO_SUCCESS)
{
  printf("Execution costs set successfully.\n");
}
else
{
  printf("Failed to set execution costs.\n");
}

// Clean up when done
cardano_ex_unit_prices_unref(&new_execution_costs);

Note

The caller is responsible for managing the lifecycle of the cardano_ex_unit_prices_t object. The object must be released by calling cardano_ex_unit_prices_unref when it is no longer needed.

Note

Setting appropriate execution costs helps ensure fair pricing for computational resources when running Plutus scripts.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_ex_unit_prices_t *execution_costs¶: [in] A pointer to an initialized cardano_ex_unit_prices_t object representing the new execution costs. These costs will replace any previously set execution costs in the protocol parameters.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the execution costs were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_tx_ex_units(cardano_protocol_parameters_t *protocol_parameters, cardano_ex_units_t *max_tx_ex_units)¶

Sets the maximum execution units per transaction in the protocol parameters.

This function sets the maximum execution units that can be consumed by a single transaction in the given cardano_protocol_parameters_t object. Execution units are the computational resources (e.g., CPU and memory) required to run Plutus scripts. By setting a limit on the maximum execution units per transaction, the protocol ensures that no transaction can monopolize blockchain resources.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_units_t* new_max_tx_ex_units = ...; // Assume new_max_tx_ex_units is initialized

cardano_error_t result = cardano_protocol_parameters_set_max_tx_ex_units(protocol_params, new_max_tx_ex_units);

if (result == CARDANO_SUCCESS)
{
  printf("Max transaction execution units set successfully.\n");
}
else
{
  printf("Failed to set max transaction execution units.\n");
}

// Clean up when done
cardano_ex_units_unref(&new_max_tx_ex_units);

Note

The caller is responsible for managing the lifecycle of the cardano_ex_units_t object. The object must be released by calling cardano_ex_units_unref when it is no longer needed.

Note

This setting helps control resource usage and prevent excessive computational demand by any single transaction.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_ex_units_t *max_tx_ex_units¶: [in] A pointer to an initialized cardano_ex_units_t object representing the maximum execution units for a transaction.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum transaction execution units were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_block_ex_units(cardano_protocol_parameters_t *protocol_parameters, cardano_ex_units_t *max_block_ex_units)¶

Sets the maximum execution units per block in the protocol parameters.

This function sets the maximum execution units that can be consumed by all transactions in a single block, in the given cardano_protocol_parameters_t object. Execution units represent computational resources (e.g., CPU and memory) required to run Plutus scripts. Setting a limit on the maximum execution units per block ensures that the blockchain remains performant and that no single block consumes excessive resources.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_ex_units_t* new_max_block_ex_units = ...; // Assume new_max_block_ex_units is initialized

cardano_error_t result = cardano_protocol_parameters_set_max_block_ex_units(protocol_params, new_max_block_ex_units);

if (result == CARDANO_SUCCESS)
{
  printf("Max block execution units set successfully.\n");
}
else
{
  printf("Failed to set max block execution units.\n");
}

// Clean up when done
cardano_ex_units_unref(&new_max_block_ex_units);

Note

The caller is responsible for managing the lifecycle of the cardano_ex_units_t object. The object must be released by calling cardano_ex_units_unref when it is no longer needed.

Note

Limiting execution units per block helps prevent any single block from consuming too much computational capacity, ensuring that the blockchain remains balanced in its resource use.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_ex_units_t *max_block_ex_units¶: [in] A pointer to an initialized cardano_ex_units_t object representing the maximum execution units allowed per block.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum block execution units were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_value_size(cardano_protocol_parameters_t *protocol_parameters, int64_t max_value_size)¶

Sets the maximum size of a value in the protocol parameters.

This function sets the maximum size, in bytes, of a value (such as assets or tokens) that can be included in a transaction output in the given cardano_protocol_parameters_t object. Limiting the size of values helps prevent excessive data from being stored in a single transaction, promoting efficiency and scalability on the blockchain.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
int64_t new_max_value_size = 4000; // Set the maximum value size to 4000 bytes

cardano_error_t result = cardano_protocol_parameters_set_max_value_size(protocol_params, new_max_value_size);

if (result == CARDANO_SUCCESS)
{
  printf("Max value size set successfully.\n");
}
else
{
  printf("Failed to set max value size.\n");
}

Note

Setting a reasonable maximum value size ensures that no single transaction carries excessive data, helping the network process transactions efficiently.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
int64_t max_value_size¶: [in] The new maximum size of a value, in bytes. This is an int64_t type.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum value size was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_collateral_percentage(cardano_protocol_parameters_t *protocol_parameters, uint64_t collateral_percentage)¶

Sets the collateral percentage required for Plutus script transactions in the protocol parameters.

This function sets the percentage of the transaction fee that must be provided as collateral in case the execution of a Plutus script fails. The collateral is used to cover the fees for the failed transaction, and setting a required percentage helps ensure the network remains secure and compensated for failed script executions.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_collateral_percentage = 150; // Set the collateral percentage to 150%

cardano_error_t result = cardano_protocol_parameters_set_collateral_percentage(protocol_params, new_collateral_percentage);

if (result == CARDANO_SUCCESS)
{
  printf("Collateral percentage set successfully.\n");
}
else
{
  printf("Failed to set collateral percentage.\n");
}

Note

Setting an appropriate collateral percentage ensures that script failures are adequately compensated without affecting the network’s integrity or transaction throughput.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t collateral_percentage¶: [in] The new collateral percentage, as a uint64_t. This percentage is relative to the transaction fees.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the collateral percentage was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_max_collateral_inputs(cardano_protocol_parameters_t *protocol_parameters, uint64_t max_collateral_inputs)¶

Sets the maximum number of collateral inputs allowed in a Plutus script transaction.

This function sets the maximum number of collateral inputs that can be provided in a single transaction involving Plutus scripts. Collateral inputs are required when executing Plutus scripts to cover potential costs in case the script fails. By limiting the number of collateral inputs, the protocol ensures that transactions remain efficient and do not consume excessive resources.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_max_collateral_inputs = 3; // Set the maximum collateral inputs to 3

cardano_error_t result = cardano_protocol_parameters_set_max_collateral_inputs(protocol_params, new_max_collateral_inputs);

if (result == CARDANO_SUCCESS)
{
  printf("Max collateral inputs set successfully.\n");
}
else
{
  printf("Failed to set max collateral inputs.\n");
}

Note

Setting a maximum number of collateral inputs ensures that transactions using Plutus scripts remain within acceptable resource limits.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t max_collateral_inputs¶: [in] The new maximum number of collateral inputs allowed in a transaction.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the maximum collateral inputs were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_pool_voting_thresholds(cardano_protocol_parameters_t *protocol_parameters, cardano_pool_voting_thresholds_t *pool_voting_thresholds)¶

Sets the pool voting thresholds in the protocol parameters.

This function sets the pool voting thresholds in the given cardano_protocol_parameters_t object. Pool voting thresholds define the minimum stake pool support required for certain governance actions, ensuring that changes to the protocol or other governance decisions have sufficient backing from stake pools before being accepted.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_pool_voting_thresholds_t* new_pool_voting_thresholds = ...; // Assume new_pool_voting_thresholds is initialized

cardano_error_t result = cardano_protocol_parameters_set_pool_voting_thresholds(protocol_params, new_pool_voting_thresholds);

if (result == CARDANO_SUCCESS)
{
  printf("Pool voting thresholds set successfully.\n");
}
else
{
  printf("Failed to set pool voting thresholds.\n");
}

// Clean up when done
cardano_pool_voting_thresholds_unref(&new_pool_voting_thresholds);

Note

The caller is responsible for managing the lifecycle of the cardano_pool_voting_thresholds_t object. The object must be released by calling cardano_pool_voting_thresholds_unref when it is no longer needed.

Note

Setting proper voting thresholds ensures that governance actions are backed by sufficient stake, maintaining the security and fairness of the system.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_pool_voting_thresholds_t *pool_voting_thresholds¶: [in] A pointer to an initialized cardano_pool_voting_thresholds_t object representing the new pool voting thresholds. This value will replace any existing pool voting thresholds in the protocol parameters.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the pool voting thresholds were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_drep_voting_thresholds(cardano_protocol_parameters_t *protocol_parameters, cardano_drep_voting_thresholds_t *drep_voting_thresholds)¶

Sets the DRep voting thresholds in the protocol parameters.

This function sets the decentralized representative (DRep) voting thresholds in the given cardano_protocol_parameters_t object. DRep voting thresholds define the minimum level of support required from decentralized representatives for specific governance actions to be accepted. These thresholds ensure that governance decisions are made with sufficient backing from the DReps.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_drep_voting_thresholds_t* new_drep_voting_thresholds = ...; // Assume new_drep_voting_thresholds is initialized

cardano_error_t result = cardano_protocol_parameters_set_drep_voting_thresholds(protocol_params, new_drep_voting_thresholds);

if (result == CARDANO_SUCCESS)
{
  printf("DRep voting thresholds set successfully.\n");
}
else
{
  printf("Failed to set DRep voting thresholds.\n");
}

// Clean up when done
cardano_drep_voting_thresholds_unref(&new_drep_voting_thresholds);

Note

The caller is responsible for managing the lifecycle of the cardano_drep_voting_thresholds_t object. The object must be released by calling cardano_drep_voting_thresholds_unref when it is no longer needed.

Note

Setting appropriate DRep voting thresholds ensures that governance decisions are backed by sufficient support from decentralized representatives, promoting the fairness and security of the governance process.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_drep_voting_thresholds_t *drep_voting_thresholds¶: [in] A pointer to an initialized cardano_drep_voting_thresholds_t object representing the new DRep voting thresholds. This value will replace any existing DRep voting thresholds in the protocol parameters.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the DRep voting thresholds were successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_min_committee_size(cardano_protocol_parameters_t *protocol_parameters, uint64_t min_committee_size)¶

Sets the minimum committee size in the protocol parameters.

This function sets the minimum number of members required in a committee for governance actions in the cardano_protocol_parameters_t object. Committees are responsible for making important governance decisions, and defining a minimum size ensures that decisions are made with enough participants, promoting fairness and representation.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_min_committee_size = 5; // Set the minimum committee size to 5 members

cardano_error_t result = cardano_protocol_parameters_set_min_committee_size(protocol_params, new_min_committee_size);

if (result == CARDANO_SUCCESS)
{
  printf("Minimum committee size set successfully.\n");
}
else
{
  printf("Failed to set minimum committee size.\n");
}

Note

Setting a minimum committee size ensures that governance decisions are made with sufficient representation, preventing decisions from being made by too small a group.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t min_committee_size¶: [in] The minimum number of members required in a governance committee.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the minimum committee size was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_committee_term_limit(cardano_protocol_parameters_t *protocol_parameters, uint64_t committee_term_limit)¶

Sets the committee term limit in the protocol parameters.

This function sets the maximum term limit for committee members in the given cardano_protocol_parameters_t object. The term limit defines how long a committee member can serve before they are required to step down or be re-elected. Setting a term limit helps ensure regular turnover and prevents stagnation in governance roles.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_term_limit = 10; // Set the term limit to 10 epochs

cardano_error_t result = cardano_protocol_parameters_set_committee_term_limit(protocol_params, new_term_limit);

if (result == CARDANO_SUCCESS)
{
  printf("Committee term limit set successfully.\n");
}
else
{
  printf("Failed to set committee term limit.\n");
}

Note

Setting a term limit ensures that committee members serve for a limited period, encouraging fresh perspectives in governance.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t committee_term_limit¶: [in] The maximum term limit, in epochs, for a committee member.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the committee term limit was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_governance_action_validity_period(cardano_protocol_parameters_t *protocol_parameters, uint64_t governance_action_validity_period)¶

Sets the governance action validity period in the protocol parameters.

This function sets the validity period for governance actions in the given cardano_protocol_parameters_t object. The governance action validity period specifies the number of epochs during which a governance action is considered valid. After this period, the action will expire if not executed. This ensures that governance actions are timely and relevant.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_validity_period = 5; // Set the governance action validity period to 5 epochs

cardano_error_t result = cardano_protocol_parameters_set_governance_action_validity_period(protocol_params, new_validity_period);

if (result == CARDANO_SUCCESS)
{
  printf("Governance action validity period set successfully.\n");
}
else
{
  printf("Failed to set governance action validity period.\n");
}

Note

Setting a reasonable validity period ensures that governance actions are handled in a timely manner, preventing outdated decisions.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t governance_action_validity_period¶: [in] The validity period, in epochs, for a governance action.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the governance action validity period was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_governance_action_deposit(cardano_protocol_parameters_t *protocol_parameters, uint64_t governance_action_deposit)¶

Sets the governance action deposit amount in the protocol parameters.

This function sets the deposit required for submitting a governance action in the given cardano_protocol_parameters_t object. The deposit serves as collateral to discourage spam submissions and ensure only serious proposals are submitted for governance consideration. If the governance action is successful, the deposit may be refunded; otherwise, it can be forfeited.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_deposit_amount = 5000000; // Set the governance action deposit to 5 ADA (5,000,000 lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_governance_action_deposit(protocol_params, new_deposit_amount);

if (result == CARDANO_SUCCESS)
{
  printf("Governance action deposit set successfully.\n");
}
else
{
  printf("Failed to set governance action deposit.\n");
}

Note

Setting an appropriate deposit amount discourages frivolous or spam submissions while promoting meaningful governance participation.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t governance_action_deposit¶: [in] The deposit amount, in lovelaces, required to submit a governance action.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the governance action deposit was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_drep_deposit(cardano_protocol_parameters_t *protocol_parameters, uint64_t drep_deposit)¶

Sets the DRep deposit amount in the protocol parameters.

This function sets the deposit required for registering a decentralized representative (DRep) in the given cardano_protocol_parameters_t object. The DRep deposit is a collateral mechanism to ensure that only serious participants register as decentralized representatives, contributing to the governance process. If the registration is successful, the deposit may be refunded; otherwise, it may be forfeited.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_drep_deposit = 2000000; // Set the DRep deposit to 2 ADA (2,000,000 lovelaces)

cardano_error_t result = cardano_protocol_parameters_set_drep_deposit(protocol_params, new_drep_deposit);

if (result == CARDANO_SUCCESS)
{
  printf("DRep deposit set successfully.\n");
}
else
{
  printf("Failed to set DRep deposit.\n");
}

Note

Setting a reasonable DRep deposit ensures that only serious candidates participate in governance, helping maintain the integrity of the system.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t drep_deposit¶: [in] The deposit amount, in lovelaces, required to register as a decentralized representative (DRep).

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the DRep deposit was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_drep_inactivity_period(cardano_protocol_parameters_t *protocol_parameters, uint64_t drep_inactivity_period)¶

Sets the DRep inactivity period in the protocol parameters.

This function sets the inactivity period for decentralized representatives (DReps) in the given cardano_protocol_parameters_t object. The inactivity period defines the number of epochs a DRep can remain inactive (i.e., not participate in governance votes) before their registration is considered invalid or they are required to take action to remain active.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
uint64_t new_inactivity_period = 100; // Set the DRep inactivity period to 100 epochs

cardano_error_t result = cardano_protocol_parameters_set_drep_inactivity_period(protocol_params, new_inactivity_period);

if (result == CARDANO_SUCCESS)
{
  printf("DRep inactivity period set successfully.\n");
}
else
{
  printf("Failed to set DRep inactivity period.\n");
}

Note

Setting a reasonable inactivity period ensures that DReps actively participate in governance processes, maintaining the health of the system.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
uint64_t drep_inactivity_period¶: [in] The maximum number of epochs a DRep can remain inactive before their registration is affected.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the DRep inactivity period was successfully set, or an appropriate error code if an error occurred.

cardano_error_t cardano_protocol_parameters_set_ref_script_cost_per_byte(cardano_protocol_parameters_t *protocol_parameters, cardano_unit_interval_t *ref_script_cost_per_byte)¶

Sets the reference script cost per byte in the protocol parameters.

This function sets the cost per byte for storing reference scripts in the given cardano_protocol_parameters_t object. Reference scripts are stored on-chain, and this parameter determines the cost associated with each byte of a reference script, ensuring that resources are properly accounted for in transaction fees.

Usage Example:

cardano_protocol_parameters_t* protocol_params = ...; // Assume protocol_params is initialized
cardano_unit_interval_t* ref_script_cost = ...; // Assume ref_script_cost is initialized

cardano_error_t result = cardano_protocol_parameters_set_ref_script_cost_per_byte(protocol_params, ref_script_cost);

if (result == CARDANO_SUCCESS)
{
  printf("Reference script cost per byte set successfully.\n");
}
else
{
  printf("Failed to set reference script cost per byte.\n");
}

// Clean up the ref_script_cost when no longer needed
cardano_unit_interval_unref(&ref_script_cost);

Note

The caller is responsible for managing the lifecycle of the cardano_unit_interval_t object. The object must be released by calling cardano_unit_interval_unref when it is no longer needed.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [inout] A pointer to an initialized cardano_protocol_parameters_t object. This parameter must not be NULL.
cardano_unit_interval_t *ref_script_cost_per_byte¶: [in] A pointer to an initialized cardano_unit_interval_t object representing the cost per byte of reference scripts.

Returns:¶

cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the reference script cost per byte was successfully set, or an appropriate error code if an error occurred.

void cardano_protocol_parameters_unref(cardano_protocol_parameters_t **protocol_parameters)¶

Decrements the reference count of a cardano_protocol_parameters_t object.

This function is responsible for managing the lifecycle of a cardano_protocol_parameters_t object by decreasing its reference count. When the reference count reaches zero, the protocol_parameters is finalized; its associated resources are released, and its memory is deallocated.

Usage Example:

cardano_protocol_parameters_t* protocol_parameters = cardano_protocol_parameters_new(major, minor);

// Perform operations with the protocol_parameters...

cardano_protocol_parameters_unref(&protocol_parameters);
// At this point, protocol_parameters is NULL and cannot be used.

Note

After calling cardano_protocol_parameters_unref, the pointer to the cardano_protocol_parameters_t object will be set to NULL to prevent its reuse.

Parameters:¶

cardano_protocol_parameters_t **protocol_parameters¶: [inout] A pointer to the pointer of the protocol_parameters object. This double indirection allows the function to set the caller’s pointer to NULL, avoiding dangling pointer issues after the object has been freed.

void cardano_protocol_parameters_ref(cardano_protocol_parameters_t *protocol_parameters)¶

Increases the reference count of the cardano_protocol_parameters_t object.

This function is used to manually increment the reference count of an cardano_protocol_parameters_t object, indicating that another part of the code has taken ownership of it. This ensures the object remains allocated and valid until all owners have released their reference by calling cardano_protocol_parameters_unref.

Usage Example:

// Assuming protocol_parameters is a previously created protocol_parameters object

cardano_protocol_parameters_ref(protocol_parameters);

// Now protocol_parameters can be safely used elsewhere without worrying about premature deallocation

Note

Always ensure that for every call to cardano_protocol_parameters_ref there is a corresponding call to cardano_protocol_parameters_unref to prevent memory leaks.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: A pointer to the cardano_protocol_parameters_t object whose reference count is to be incremented.

size_t cardano_protocol_parameters_refcount(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the current reference count of the cardano_protocol_parameters_t object.

This function returns the number of active references to an cardano_protocol_parameters_t object. It’s useful for debugging purposes or managing the lifecycle of the object in complex scenarios.

Usage Example:

// Assuming protocol_parameters is a previously created protocol_parameters object

size_t ref_count = cardano_protocol_parameters_refcount(protocol_parameters);

printf("Reference count: %zu\n", ref_count);

Warning

This function does not account for transitive references. A transitive reference occurs when an object holds a reference to another object, rather than directly to the cardano_protocol_parameters_t. As such, the reported count may not fully represent the total number of conceptual references in cases where such transitive relationships exist.

Parameters:¶

const cardano_protocol_parameters_t *protocol_parameters¶: A pointer to the cardano_protocol_parameters_t object whose reference count is queried. The object must not be NULL.

Returns:¶

The number of active references to the specified cardano_protocol_parameters_t object. If the object is properly managed (i.e., every cardano_protocol_parameters_ref call is matched with a cardano_protocol_parameters_unref call), this count should reach zero right before the object is deallocated.

void cardano_protocol_parameters_set_last_error(cardano_protocol_parameters_t *protocol_parameters, const char *message)¶

Sets the last error message for a given cardano_protocol_parameters_t object.

Records an error message in the protocol_parameters’s last_error buffer, overwriting any existing message. This is useful for storing descriptive error information that can be later retrieved. The message is truncated if it exceeds the buffer’s capacity.

Note

The error message is limited to 1023 characters, including the null terminator, due to the fixed size of the last_error buffer.

Parameters:¶

cardano_protocol_parameters_t *protocol_parameters¶: [in] A pointer to the cardano_protocol_parameters_t instance whose last error message is to be set. If NULL, the function does nothing.
const char *message¶: [in] A null-terminated string containing the error message. If NULL, the protocol_parameters’s last_error is set to an empty string, indicating no error.

const char *cardano_protocol_parameters_get_last_error(const cardano_protocol_parameters_t *protocol_parameters)¶

Retrieves the last error message recorded for a specific protocol_parameters.

This function returns a pointer to the null-terminated string containing the last error message set by cardano_protocol_parameters_set_last_error for the given protocol_parameters. If no error message has been set, or if the last_error buffer was explicitly cleared, an empty string is returned, indicating no error.

Note

The returned string points to internal storage within the object and must not be modified by the caller. The string remains valid until the next call to cardano_protocol_parameters_set_last_error for the same protocol_parameters, or until the protocol_parameters is deallocated.

Parameters:¶

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

Returns:¶

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