cardano-api-1.28.0
Safe HaskellNone
LanguageHaskell2010

Cardano.Api.Fees

Description

Fee calculation

Synopsis

Transaction fees

transactionFee Source #

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.

estimateTransactionFee Source #

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)

evaluateTransactionFee Source #

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

estimateTransactionKeyWitnessCountTxBodyContent BuildTx era → Word Source #

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

evaluateTransactionExecutionUnits ∷ ∀ era mode. EraInMode era mode → SystemStartEraHistory mode → ProtocolParametersUTxO era → TxBody era → Either TransactionValidityIntervalError (Map ScriptWitnessIndex (Either ScriptExecutionError ExecutionUnits)) Source #

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.

data ScriptExecutionError Source #

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.

newtype TransactionValidityIntervalError Source #

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 

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

makeTransactionBodyAutoBalance Source #

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.

data TxBodyErrorAutoBalance Source #

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

Fields

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

Fields

TxBodyErrorNonAdaAssetsUnbalanced Value