cardano-api-1.28.0

Cardano.Api.Fees

Description

Fee calculation

Synopsis

# Transaction fees

Arguments

 ∷ ∀ era. IsShelleyBasedEra era ⇒ Natural The fixed tx fee → Natural The tx fee per byte → Tx era → Lovelace

Deprecated: Use evaluateTransactionFee instead

For a concrete fully-constructed transaction, determine the minimum fee that it needs to pay.

This function is simple, but if you are doing input selection then you probably want to consider estimateTransactionFee.

Arguments

 ∷ ∀ era. IsShelleyBasedEra era ⇒ NetworkId → Natural The fixed tx fee → Natural The tx fee per byte → Tx era → Int The number of extra UTxO transaction inputs → Int The number of extra transaction outputs → Int The number of extra Shelley key witnesses → Int The number of extra Byron key witnesses → Lovelace

This can estimate what the transaction fee will be, based on a starting base transaction, plus the numbers of the additional components of the transaction that may be added.

So for example with wallet coin selection, the base transaction should contain all the things not subject to coin selection (such as script inputs, metadata, withdrawals, certs etc)

Arguments

 ∷ ∀ era. IsShelleyBasedEra era ⇒ ProtocolParameters → TxBody era → Word The number of Shelley key witnesses → Word The number of Byron key witnesses → Lovelace

Compute the transaction fee for a proposed transaction, with the assumption that there will be the given number of key witnesses (i.e. signatures).

TODO: we need separate args for Shelley vs Byron key sigs

Give an approximate count of the number of key witnesses (i.e. signatures) a transaction will need.

This is an estimate not a precise count in that it can over-estimate: it makes conservative assumptions such as all inputs are from distinct addresses, but in principle multiple inputs can use the same address and we only need a witness per address.

Similarly there can be overlap between the regular and collateral inputs, but we conservatively assume they are distinct.

TODO: it is worth us considering a more precise count that relies on the UTxO to resolve which inputs are for distinct addresses, and also to count the number of Shelley vs Byron style witnesses.

# Script execution units

Compute the ExecutionUnits needed for each script in the transaction.

This works by running all the scripts and counting how many execution units are actually used.

The different possible reasons that executing a script can fail, as reported by evaluateTransactionExecutionUnits.

The first three of these are about failures before we even get to execute the script, and two are the result of execution.

Constructors

 ScriptErrorMissingTxIn TxIn The script depends on a TxIn that has not been provided in the given UTxO subset. The given UTxO must cover all the inputs the transaction references. ScriptErrorTxInWithoutDatum TxIn The TxIn the script is spending does not have a ScriptDatum. All inputs guarded by Plutus scripts need to have been created with a ScriptDatum. ScriptErrorWrongDatum (Hash ScriptData) The ScriptDatum provided does not match the one from the UTxO. This means the wrong ScriptDatum value has been provided. ScriptErrorEvaluationFailed EvaluationError The script evaluation failed. This usually means it evaluated to an error value. This is not a case of running out of execution units (which is not possible for evaluateTransactionExecutionUnits since the whole point of it is to discover how many execution units are needed). ScriptErrorExecutionUnitsOverflow The execution units overflowed a 64bit word. Congratulations if you encounter this error. With the current style of cost model this would need a script to run for over 7 months, which is somewhat more than the expected maximum of a few milliseconds.

#### Instances

Instances details
 Source # Instance detailsDefined in Cardano.Api.Fees Methods Source # Instance detailsDefined in Cardano.Api.Fees Methods

The transaction validity interval is too far into the future.

Transactions with Plutus scripts need to have a validity interval that is not so far in the future that we cannot reliably determine the UTC time corresponding to the validity interval expressed in slot numbers.

This is because the Plutus scripts get given the transaction validity interval in UTC time, so that they are not sensitive to slot lengths.

If either end of the validity interval is beyond the so called "time horizon" then the consensus algorithm is not able to reliably determine the relationship between slots and time. This is this situation in which this error is reported. For the Cardano mainnet the time horizon is 36 hours beyond the current time. This effectively means we cannot submit check or submit transactions that use Plutus scripts that have the end of their validity interval more than 36 hours into the future.

Constructors

 TransactionValidityIntervalError PastHorizonException

#### Instances

Instances details
 Source # Instance detailsDefined in Cardano.Api.Fees Source # Instance detailsDefined in Cardano.Api.Fees Methods

# Transaction balance

evaluateTransactionBalance ∷ ∀ era. IsShelleyBasedEra era ⇒ ProtocolParametersSet PoolIdUTxO era → TxBody era → TxOutValue era Source #

Compute the total balance of the proposed transaction. Ultimately a valid transaction must be fully balanced: that is have a total value of zero.

Finding the (non-zero) balance of partially constructed transaction is useful for adjusting a transaction to be fully balanced.

# Automated transaction building

Arguments

 ∷ ∀ era mode. IsShelleyBasedEra era ⇒ EraInMode era mode → SystemStart → EraHistory mode → ProtocolParameters → Set PoolId The set of registered stake pools → UTxO era Just the transaction inputs, not the entire UTxO. → TxBodyContent BuildTx era → AddressInEra era Change address → Maybe Word Override key witnesses → Either TxBodyErrorAutoBalance (TxBody era)

This is much like makeTransactionBody but with greater automation to calculate suitable values for several things.

In particular:

• It calculates the correct script ExecutionUnits (ignoring the provided values, which can thus be zero).
• It calculates the transaction fees, based on the script ExecutionUnits, the current ProtocolParameters, and an estimate of the number of key witnesses (i.e. signatures). There is an override for the number of key witnesses.
• It accepts a change address, calculates the balance of the transaction and puts the excess change into the change output.
• It also checks that the balance is positive and the change is above the minimum threshold.

To do this it needs more information than makeTransactionBody, all of which can be queried from a local node.

The possible errors that can arise from makeTransactionBodyAutoBalance.

Constructors

 TxBodyError TxBodyError The same errors that can arise from makeTransactionBody. TxBodyScriptExecutionError [(ScriptWitnessIndex, ScriptExecutionError)] One or more of the scripts fails to execute correctly. TxBodyScriptBadScriptValidity One or more of the scripts were expected to fail validation, but none did. TxBodyErrorAssetBalanceWrong Value The balance of the non-ada assets is not zero. The Value here is that residual non-zero balance. The makeTransactionBodyAutoBalance function only automatically balances ada, not other assets. TxBodyErrorAdaBalanceNegative Lovelace There is not enough ada to cover both the outputs and the fees. The transaction should be changed to provide more input ada, or otherwise adjusted to need less (e.g. outputs, script etc). TxBodyErrorAdaBalanceTooSmall Offending TxOut FieldsTxOutInAnyEraMinimum UTxOLovelaceTx balanceLovelace TxBodyErrorByronEraNotSupported makeTransactionBodyAutoBalance does not yet support the Byron era. TxBodyErrorMissingParamMinUTxO The ProtocolParameters must provide the value for the min utxo parameter, for eras that use this parameter. TxBodyErrorMissingParamCostPerWord The ProtocolParameters must provide the value for the cost per word parameter, for eras that use this parameter. TxBodyErrorValidityInterval TransactionValidityIntervalError The transaction validity interval is too far into the future. See TransactionValidityIntervalError for details. TxBodyErrorMinUTxONotMet Offending TxOut FieldsTxOutInAnyEraMinimum UTxOLovelace TxBodyErrorNonAdaAssetsUnbalanced Value

#### Instances

Instances details
 Source # Instance detailsDefined in Cardano.Api.Fees Methods Source # Instance detailsDefined in Cardano.Api.Fees Methods