cardano-api-8.36.1.1: The cardano api
Safe HaskellNone
LanguageHaskell2010

Cardano.Api.Fees

Description

Fee calculation

Synopsis

Transaction fees

transactionFee Source #

Arguments

:: ShelleyBasedEra era 
-> Lovelace

The fixed tx fee

-> Lovelace

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

:: ShelleyBasedEra era 
-> NetworkId 
-> Lovelace

The fixed tx fee

-> Lovelace

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

:: forall era. ShelleyBasedEra era 
-> PParams (ShelleyLedgerEra era) 
-> 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

estimateTransactionKeyWitnessCount :: TxBodyContent 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 :: forall era. CardanoEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> TxBody era -> Either TransactionValidityError (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 [Text]

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.

ScriptErrorNotPlutusWitnessedTxIn ScriptWitnessIndex ScriptHash

An attempt was made to spend a key witnessed tx input with a script witness.

ScriptErrorRedeemerPointsToUnknownScriptHash ScriptWitnessIndex

The redeemer pointer points to a script hash that does not exist in the transaction nor in the UTxO as a reference script"

ScriptErrorMissingScript RdmrPtr ResolvablePointers

A redeemer pointer points to a script that does not exist.

ScriptErrorMissingCostModel Language

A cost model was missing for a language which was used.

data TransactionValidityError Source #

Constructors

TransactionValidityIntervalError PastHorizonException

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.

TransactionValidityTranslationError (TranslationError StandardCrypto) 
TransactionValidityCostModelError (Map AnyPlutusScriptVersion CostModel) String 

Transaction balance

evaluateTransactionBalance :: forall era. ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> Set PoolId -> Map StakeCredential Lovelace -> Map (Credential DRepRole StandardCrypto) Lovelace -> UTxO 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

:: forall era. ShelleyBasedEra era 
-> SystemStart 
-> LedgerEpochInfo 
-> LedgerProtocolParameters era 
-> Set PoolId

The set of registered stake pools, that are being unregistered in this transaction.

-> Map StakeCredential Lovelace

Map of all deposits for stake credentials that are being unregistered in this transaction

-> Map (Credential DRepRole StandardCrypto) Lovelace

Map of all deposits for drep credentials that are being unregistered in this transaction

-> UTxO era

Just the transaction inputs, not the entire UTxO.

-> TxBodyContent BuildTx era 
-> AddressInEra era

Change address

-> Maybe Word

Override key witnesses

-> Either TxBodyErrorAutoBalance (BalancedTxBody 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 BalancedTxBody era Source #

Constructors

BalancedTxBody 

Fields

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.

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.

TxBodyErrorValidityInterval TransactionValidityError

The transaction validity interval is too far into the future. See TransactionValidityIntervalError for details.

TxBodyErrorMinUTxONotMet

Offending TxOut

Fields

TxBodyErrorNonAdaAssetsUnbalanced Value 
TxBodyErrorScriptWitnessIndexMissingFromExecUnitsMap ScriptWitnessIndex (Map ScriptWitnessIndex ExecutionUnits) 

Minimum UTxO calculation

Internal helpers

data ResolvablePointers where Source #

Constructors

ResolvablePointers :: (Era (ShelleyLedgerEra era), Show (TxCert (ShelleyLedgerEra era))) => ShelleyBasedEra era -> Map RdmrPtr (ScriptPurpose (ShelleyLedgerEra era), Maybe (PlutusScriptBytes, Language), ScriptHash StandardCrypto) -> ResolvablePointers