Safe Haskell | None |
---|---|
Language | Haskell2010 |
Cardano.Api.Fees
Description
Fee calculation
Synopsis
- transactionFee :: ShelleyBasedEra era -> Lovelace -> Lovelace -> Tx era -> Lovelace
- estimateTransactionFee :: ShelleyBasedEra era -> NetworkId -> Lovelace -> Lovelace -> Tx era -> Int -> Int -> Int -> Int -> Lovelace
- evaluateTransactionFee :: forall era. ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> TxBody era -> Word -> Word -> Lovelace
- estimateTransactionKeyWitnessCount :: TxBodyContent BuildTx era -> Word
- evaluateTransactionExecutionUnits :: forall era. CardanoEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> TxBody era -> Either TransactionValidityError (Map ScriptWitnessIndex (Either ScriptExecutionError ExecutionUnits))
- data ScriptExecutionError
- = ScriptErrorMissingTxIn TxIn
- | ScriptErrorTxInWithoutDatum TxIn
- | ScriptErrorWrongDatum (Hash ScriptData)
- | ScriptErrorEvaluationFailed EvaluationError [Text]
- | ScriptErrorExecutionUnitsOverflow
- | ScriptErrorNotPlutusWitnessedTxIn ScriptWitnessIndex ScriptHash
- | ScriptErrorRedeemerPointsToUnknownScriptHash ScriptWitnessIndex
- | ScriptErrorMissingScript RdmrPtr ResolvablePointers
- | ScriptErrorMissingCostModel Language
- data TransactionValidityError
- = TransactionValidityIntervalError PastHorizonException
- | TransactionValidityTranslationError (TranslationError StandardCrypto)
- | TransactionValidityCostModelError (Map AnyPlutusScriptVersion CostModel) String
- evaluateTransactionBalance :: forall era. ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> Set PoolId -> Map StakeCredential Lovelace -> Map (Credential DRepRole StandardCrypto) Lovelace -> UTxO era -> TxBody era -> TxOutValue era
- makeTransactionBodyAutoBalance :: forall era. ShelleyBasedEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> Set PoolId -> Map StakeCredential Lovelace -> Map (Credential DRepRole StandardCrypto) Lovelace -> UTxO era -> TxBodyContent BuildTx era -> AddressInEra era -> Maybe Word -> Either TxBodyErrorAutoBalance (BalancedTxBody era)
- data BalancedTxBody era = BalancedTxBody (TxBodyContent BuildTx era) (TxBody era) (TxOut CtxTx era) Lovelace
- data TxBodyErrorAutoBalance
- = TxBodyError TxBodyError
- | TxBodyScriptExecutionError [(ScriptWitnessIndex, ScriptExecutionError)]
- | TxBodyScriptBadScriptValidity
- | TxBodyErrorAdaBalanceNegative Lovelace
- | TxBodyErrorAdaBalanceTooSmall TxOutInAnyEra Lovelace Lovelace
- | TxBodyErrorByronEraNotSupported
- | TxBodyErrorMissingParamMinUTxO
- | TxBodyErrorValidityInterval TransactionValidityError
- | TxBodyErrorMinUTxONotMet TxOutInAnyEra Lovelace
- | TxBodyErrorNonAdaAssetsUnbalanced Value
- | TxBodyErrorScriptWitnessIndexMissingFromExecUnitsMap ScriptWitnessIndex (Map ScriptWitnessIndex ExecutionUnits)
- calculateMinimumUTxO :: ShelleyBasedEra era -> TxOut CtxTx era -> PParams (ShelleyLedgerEra era) -> Lovelace
- mapTxScriptWitnesses :: forall era. (forall witctx. ScriptWitnessIndex -> ScriptWitness witctx era -> Either TxBodyErrorAutoBalance (ScriptWitness witctx era)) -> TxBodyContent BuildTx era -> Either TxBodyErrorAutoBalance (TxBodyContent BuildTx era)
- data ResolvablePointers where
- ResolvablePointers :: (Era (ShelleyLedgerEra era), Show (TxCert (ShelleyLedgerEra era))) => ShelleyBasedEra era -> Map RdmrPtr (ScriptPurpose (ShelleyLedgerEra era), Maybe (PlutusScriptBytes, Language), ScriptHash StandardCrypto) -> ResolvablePointers
Transaction fees
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 |
ScriptErrorTxInWithoutDatum TxIn | The |
ScriptErrorWrongDatum (Hash ScriptData) | The |
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 |
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. |
Instances
Show ScriptExecutionError Source # | |
Defined in Cardano.Api.Fees | |
Error ScriptExecutionError Source # | |
Defined in Cardano.Api.Fees Methods prettyError :: ScriptExecutionError -> Doc ann Source # |
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 |
Instances
Show TransactionValidityError Source # | |
Defined in Cardano.Api.Fees | |
Error TransactionValidityError Source # | |
Defined in Cardano.Api.Fees Methods prettyError :: TransactionValidityError -> Doc ann Source # |
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 |
-> 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 currentProtocolParameters
, 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 | |
data TxBodyErrorAutoBalance Source #
The possible errors that can arise from makeTransactionBodyAutoBalance
.
Constructors
TxBodyError TxBodyError | The same errors that can arise from |
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 |
|
TxBodyErrorMissingParamMinUTxO | The |
TxBodyErrorValidityInterval TransactionValidityError | The transaction validity interval is too far into the future.
See |
TxBodyErrorMinUTxONotMet | Offending TxOut |
Fields
| |
TxBodyErrorNonAdaAssetsUnbalanced Value | |
TxBodyErrorScriptWitnessIndexMissingFromExecUnitsMap ScriptWitnessIndex (Map ScriptWitnessIndex ExecutionUnits) |
Instances
Show TxBodyErrorAutoBalance Source # | |
Defined in Cardano.Api.Fees | |
Error TxBodyErrorAutoBalance Source # | |
Defined in Cardano.Api.Fees Methods prettyError :: TxBodyErrorAutoBalance -> Doc ann Source # |
Minimum UTxO calculation
calculateMinimumUTxO :: ShelleyBasedEra era -> TxOut CtxTx era -> PParams (ShelleyLedgerEra era) -> Lovelace Source #
Internal helpers
mapTxScriptWitnesses :: forall era. (forall witctx. ScriptWitnessIndex -> ScriptWitness witctx era -> Either TxBodyErrorAutoBalance (ScriptWitness witctx era)) -> TxBodyContent BuildTx era -> Either TxBodyErrorAutoBalance (TxBodyContent BuildTx era) Source #
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 |
Instances
Show ResolvablePointers Source # | |
Defined in Cardano.Api.Fees |