hydra-tx
Safe HaskellSafe-Inferred
LanguageGHC2021

Hydra.Ledger.Cardano.Evaluate

Description

Dependency-injected interface to phase-2 validation of transactions, eg. evaluation of Plutus scripts.

This module provides parameterized evaluation functions that accept protocol parameters, epoch info, and system start as explicit arguments.

NOTE: For convenience wrappers using test fixtures, see Fixtures which re-exports evaluateTx and evaluateTx' for testing/benchmarking purposes.

Synopsis

Evaluate transactions

evaluateTxWith :: SystemStart -> EpochInfo (Either Text) -> PParams LedgerEra -> Tx -> UTxO -> Either EvaluationError EvaluationReport Source #

Evaluate transaction with explicit dependencies.

This is the dependency-injected version, allowing you to provide your own SystemStart, EpochInfo, and PParams instead of using hardcoded test fixtures.

The maximum transaction execution units are read from the provided PParams.

evaluateTxWith' :: SystemStart -> EpochInfo (Either Text) -> PParams LedgerEra -> ExecutionUnits -> Tx -> UTxO -> Either EvaluationError EvaluationReport Source #

Like evaluateTxWith, but with a configurable maximum transaction ExecutionUnits.

checkBudget :: ExecutionUnits -> EvaluationReport -> Either EvaluationError EvaluationReport Source #

Check the budget used by provided EvaluationReport does not exceed given maximum ExecutionUnits.

data EvaluationError Source #

Errors returned by evaluateTx extending the upstream TransactionValidityError with additional cases.

Constructors

TransactionBudgetOverspent 

Fields

TransactionInvalid (TransactionValidityError Era) 
PParamsConversion ProtocolParametersConversionError 

Instances

Instances details
Show EvaluationError Source # 
Instance details

Defined in Hydra.Ledger.Cardano.Evaluate

Methods

showsPrec :: Int -> EvaluationError -> ShowS Source #

show :: EvaluationError -> String Source #

showList :: [EvaluationError] -> ShowS Source #

type EvaluationReport = Map ScriptWitnessIndex (Either ScriptExecutionError ExecutionUnits) Source #

Evaluation result for each of the included scripts. Either they failed evaluation or used a number of ExecutionUnits.

renderEvaluationReport :: EvaluationReport -> Text Source #

Render the EvaluationReport as a pretty multi-line text.

usedExecutionUnits :: EvaluationReport -> ExecutionUnits Source #

Get the total used ExecutionUnits from an EvaluationReport. Useful to further process the result of evaluateTx.

estimateMinFeeWith Source #

Arguments

:: PParams LedgerEra 
-> UTxO

UTxO the transaction's inputs (and reference inputs) resolve against, needed to size the reference scripts it pulls in.

-> Tx 
-> EvaluationReport 
-> Coin 

Estimate minimum fee for given transaction and evaluated redeemers. Instead of using the budgets from the transaction (which are usually set to 0 until balancing), this directly computes the fee from transaction size, the units of the EvaluationReport, and the Conway reference-script charge.

The reference-script term is the ledger's own tierRefScriptFee over the scripts reachable from the given UTxO, so it tracks minFeeRefScriptCostPerByte and the tiering rule exactly. It matters for every Hydra protocol transaction, which supplies its validator by reference from the script registry rather than inline.

NOTE: This still under-estimates slightly, as there are no witnesses on this Tx yet; use the ledger's calcMinFeeTx (as Wallet does) when the actual fee to pay is needed.