hydra-tx-0.19.0: Hydra transaction library
Safe HaskellSafe-Inferred
LanguageGHC2021

Hydra.Ledger.Cardano.Evaluate

Description

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

The evaluateTx function simplifies the call to ledger and plutus providing an EvaluationReport using pre-canned ProtocolParameters. This should only be used for testing or benchmarking purpose as the real evaluation parameters are set when the Hydra node starts.

NOTE: The reason this module is here instead of part of `test/` directory is to be used in tx-cost executable.

Synopsis

Evaluate transactions

evaluateTx :: Tx -> UTxO -> Either EvaluationError EvaluationReport Source #

Thin wrapper around evaluateTransactionExecutionUnits, using fixtures from this module for systemStart, eraHistory and pparams.

Additionally, this function checks the overall execution units are not exceeding maxTxExecutionUnits.

evaluateTx' Source #

Arguments

:: ExecutionUnits

Max tx execution units.

-> Tx 
-> UTxO 
-> Either EvaluationError EvaluationReport 

Like evaluateTx, 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.

renderEvaluationReportFailures :: EvaluationReport -> Text Source #

usedExecutionUnits :: EvaluationReport -> ExecutionUnits Source #

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

estimateMinFee :: Tx -> EvaluationReport -> Coin Source #

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 and the units of the EvaluationReport. Note that this function only provides a rough estimate using this modules' pparams and likely under-estimates cost as we have no witnesses on this Tx.

Profile transactions

prepareTxScripts :: Tx -> UTxO -> Either String [ByteString] Source #

Like evaluateTx, but instead of actual evaluation, return the flat-encoded, fully applied scripts for each redeemer to be evaluated externally by uplc. Use input format "flat-namedDeBruijn". This can be used to gather profiling information.

NOTE: This assumes we use Babbage and only PlutusV2 scripts are used.

Fixtures

pparams :: PParams LedgerEra Source #

Current (2023-04-12) mainchain protocol parameters. XXX: Avoid specifiying not required parameters here (e.g. max block units should not matter). XXX: Load and use mainnet parameters from a file which we can easily review to be in sync with mainnet.

maxTxSize :: Natural Source #

maxTxExecutionUnits :: ExecutionUnits Source #

Max transaction execution unit budget of the current pparams.

maxMem :: Natural Source #

Max memory and cpu units of the current pparams.

maxCpu :: Natural Source #

Max memory and cpu units of the current pparams.

epochInfo :: Monad m => EpochInfo m Source #

An artifical EpochInfo comprised by a single never ending (forking) era, with fixed epochSize and slotLength.

eraHistoryWithHorizonAt :: SlotNo -> EraHistory Source #

An era history with a single era which will end at some point.

A "real" EraHistory received from the cardano-node will have the eraEnd at a known or earliest possible end of the current era + a safe zone.

See EraParams for details.

NOTE: This era is using not so realistic epoch sizes of 1 and sets a slot length of 1

eraHistoryWithoutHorizon :: EraHistory Source #

epochSize :: EpochSize Source #

slotLength :: SlotLength Source #

systemStart :: SystemStart Source #

Properties

propTransactionEvaluates :: (Tx, UTxO) -> Property Source #

Expect a given Tx and UTxO to pass evaluation.

propTransactionFailsEvaluation :: (Tx, UTxO) -> Property Source #

Expect a given Tx and UTxO to fail phase 1 or phase 2 evaluation.

Generators

genPointInTime :: Gen (SlotNo, UTCTime) Source #

genValidityBoundsFromContestationPeriod :: ContestationPeriod -> Gen (SlotNo, (SlotNo, UTCTime)) Source #

Parameter here is the contestation period (cp) so we need to generate start (tMin) and end (tMax) tx validity bound such that their difference is not higher than the cp. Returned slots are tx validity bounds

genPointInTimeBefore :: UTCTime -> Gen (SlotNo, UTCTime) Source #

genPointInTimeAfter :: UTCTime -> Gen (SlotNo, UTCTime) Source #

Plutus cost model fixtures

plutusV2CostModel :: CostModel Source #

Current (2023-08-04) mainnet PlutusV2 cost model.