Safe Haskell | None |
---|---|
Language | Haskell2010 |
Fee calculation
Synopsis
- transactionFee ∷ ∀ era. IsSophieBasedEra era ⇒ Natural → Natural → Tx era → Entropic
- estimateTransactionFee ∷ ∀ era. IsSophieBasedEra era ⇒ NetworkId → Natural → Natural → Tx era → Int → Int → Int → Int → Entropic
- evaluateTransactionFee ∷ ∀ era. IsSophieBasedEra era ⇒ ProtocolParameters → TxBody era → Word → Word → Entropic
- estimateTransactionKeyWitnessCount ∷ TxBodyContent BuildTx era → Word
- evaluateTransactionExecutionUnits ∷ ∀ era mode. EraInMode era mode → SystemStart → EraHistory mode → ProtocolParameters → UTxO era → TxBody era → Either TransactionValidityIntervalError (Map ScriptWitnessIndex (Either ScriptExecutionError ExecutionUnits))
- data ScriptExecutionError
- newtype TransactionValidityIntervalError = TransactionValidityIntervalError PastHorizonException
- evaluateTransactionBalance ∷ ∀ era. IsSophieBasedEra era ⇒ ProtocolParameters → Set PoolId → UTxO era → TxBody era → TxOutValue era
- makeTransactionBodyAutoBalance ∷ ∀ era mode. IsSophieBasedEra era ⇒ EraInMode era mode → SystemStart → EraHistory mode → ProtocolParameters → Set PoolId → UTxO era → TxBodyContent BuildTx era → AddressInEra era → Maybe Word → Either TxBodyErrorAutoBalance (BalancedTxBody era)
- data BalancedTxBody era = BalancedTxBody (TxBody era) (TxOut era) Entropic
- data TxBodyErrorAutoBalance
- = TxBodyError TxBodyError
- | TxBodyScriptExecutionError [(ScriptWitnessIndex, ScriptExecutionError)]
- | TxBodyScriptBadScriptValidity
- | TxBodyErrorAssetBalanceWrong Value
- | TxBodyErrorBccBalanceNegative Entropic
- | TxBodyErrorBccBalanceTooSmall TxOutInAnyEra Entropic Entropic
- | TxBodyErrorColeEraNotSupported
- | TxBodyErrorMissingParamMinUTxO
- | TxBodyErrorMissingParamCostPerWord
- | TxBodyErrorValidityInterval TransactionValidityIntervalError
- | TxBodyErrorMinUTxONotMet TxOutInAnyEra Entropic
- | TxBodyErrorMinUTxOMissingPParams MinimumUTxOError
- | TxBodyErrorNonBccAssetsUnbalanced Value
- calculateMinimumUTxO ∷ SophieBasedEra era → TxOut era → ProtocolParameters → Either MinimumUTxOError Value
- data MinimumUTxOError
Transaction fees
∷ ∀ era. IsSophieBasedEra era | |
⇒ Natural | The fixed tx fee |
→ Natural | The tx fee per byte |
→ Tx era | |
→ Entropic |
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 #
∷ ∀ era. IsSophieBasedEra 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 Sophie key witnesses |
→ Int | The number of extra Cole key witnesses |
→ Entropic |
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 #
∷ ∀ era. IsSophieBasedEra era | |
⇒ ProtocolParameters | |
→ TxBody era | |
→ Word | The number of Sophie key witnesses |
→ Word | The number of Cole key witnesses |
→ Entropic |
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 Sophie vs Cole 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 Sophie vs Cole style witnesses.
Script execution units
evaluateTransactionExecutionUnits ∷ ∀ era mode. EraInMode era mode → SystemStart → EraHistory mode → ProtocolParameters → UTxO 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.
ScriptErrorMissingTxIn TxIn | The script depends on a |
ScriptErrorTxInWithoutDatum TxIn | The |
ScriptErrorWrongDatum (Hash ScriptData) | The |
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 |
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. |
ScriptErrorNotZerepochWitnessedTxIn ScriptWitnessIndex | An attempt was made to spend a key witnessed tx input with a script witness. |
Instances
Show ScriptExecutionError Source # | |
Defined in Bcc.Api.Fees | |
Error ScriptExecutionError Source # | |
Defined in Bcc.Api.Fees |
newtype TransactionValidityIntervalError Source #
The transaction validity interval is too far into the future.
Transactions with Zerepoch 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 Zerepoch 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 Bcc mainnet the time horizon is 36 hours beyond the current time. This effectively means we cannot submit check or submit transactions that use Zerepoch scripts that have the end of their validity interval more than 36 hours into the future.
TransactionValidityIntervalError PastHorizonException |
Instances
Transaction balance
evaluateTransactionBalance ∷ ∀ era. IsSophieBasedEra era ⇒ ProtocolParameters → Set PoolId → 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 #
∷ ∀ era mode. IsSophieBasedEra 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 |
→ 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 #
data TxBodyErrorAutoBalance Source #
The possible errors that can arise from makeTransactionBodyAutoBalance
.
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. |
TxBodyErrorAssetBalanceWrong Value | The balance of the non-bcc assets is not zero. The |
TxBodyErrorBccBalanceNegative Entropic | There is not enough bcc to cover both the outputs and the fees. The transaction should be changed to provide more input bcc, or otherwise adjusted to need less (e.g. outputs, script etc). |
TxBodyErrorBccBalanceTooSmall | Offending TxOut |
| |
TxBodyErrorColeEraNotSupported |
|
TxBodyErrorMissingParamMinUTxO | The |
TxBodyErrorMissingParamCostPerWord | The |
TxBodyErrorValidityInterval TransactionValidityIntervalError | The transaction validity interval is too far into the future.
See |
TxBodyErrorMinUTxONotMet | Offending TxOut |
| |
TxBodyErrorMinUTxOMissingPParams MinimumUTxOError | |
TxBodyErrorNonBccAssetsUnbalanced Value |
Instances
Show TxBodyErrorAutoBalance Source # | |
Defined in Bcc.Api.Fees | |
Error TxBodyErrorAutoBalance Source # | |
Defined in Bcc.Api.Fees |
Minimum UTxO calculation
calculateMinimumUTxO ∷ SophieBasedEra era → TxOut era → ProtocolParameters → Either MinimumUTxOError Value Source #
data MinimumUTxOError Source #
Instances
Show MinimumUTxOError Source # | |
Defined in Bcc.Api.Fees | |
Error MinimumUTxOError Source # | |
Defined in Bcc.Api.Fees |