Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Synopsis
- data EvaluationError
- data EvaluationContext = EvaluationContext {}
- class AsScriptDecodeError r where
- _ScriptDecodeError ∷ Prism' r ScriptDecodeError
- _CBORDeserialiseError ∷ Prism' r DeserialiseFailureInfo
- _RemainderError ∷ Prism' r ByteString
- _LedgerLanguageNotAvailableError ∷ Prism' r (PlutusLedgerLanguage, MajorProtocolVersion, MajorProtocolVersion)
- _PlutusCoreLanguageNotAvailableError ∷ Prism' r (Version, PlutusLedgerLanguage, MajorProtocolVersion)
- type LogOutput = [Text]
- data VerboseMode
- evaluateScriptRestricting ∷ PlutusLedgerLanguage → MajorProtocolVersion → VerboseMode → EvaluationContext → ExBudget → ScriptForEvaluation → [Data] → (LogOutput, Either EvaluationError ExBudget)
- evaluateScriptCounting ∷ PlutusLedgerLanguage → MajorProtocolVersion → VerboseMode → EvaluationContext → ScriptForEvaluation → [Data] → (LogOutput, Either EvaluationError ExBudget)
- evaluateTerm ∷ ExBudgetMode cost DefaultUni DefaultFun → MajorProtocolVersion → VerboseMode → EvaluationContext → Term NamedDeBruijn DefaultUni DefaultFun () → (Either (CekEvaluationException NamedDeBruijn DefaultUni DefaultFun) (Term NamedDeBruijn DefaultUni DefaultFun ()), cost, [Text])
- mkDynEvaluationContext ∷ MonadError CostModelApplyError m ⇒ PlutusLedgerLanguage → [BuiltinSemanticsVariant DefaultFun] → (MajorProtocolVersion → BuiltinSemanticsVariant DefaultFun) → CostModelParams → m EvaluationContext
- toMachineParameters ∷ MajorProtocolVersion → EvaluationContext → DefaultMachineParameters
- mkTermToEvaluate ∷ MonadError EvaluationError m ⇒ PlutusLedgerLanguage → MajorProtocolVersion → ScriptForEvaluation → [Data] → m (Term NamedDeBruijn DefaultUni DefaultFun ())
- assertWellFormedCostModelParams ∷ MonadError CostModelApplyError m ⇒ CostModelParams → m ()
Documentation
data EvaluationError Source #
Errors that can be thrown when evaluating a Plutus script.
CekError !(CekEvaluationException NamedDeBruijn DefaultUni DefaultFun) | An error from the evaluator itself |
DeBruijnError !FreeVariableError | An error in the pre-evaluation step of converting from de-Bruijn indices |
CodecError !ScriptDecodeError | A deserialisation error TODO: make this error more informative when we have more information about what went wrong |
CostModelParameterMismatch | An error indicating that the cost model parameters didn't match what we expected |
InvalidReturnValue | The script evaluated to a value that is not a valid return value. |
Instances
data EvaluationContext Source #
An opaque type that contains all the static parameters that the evaluator needs to evaluate a script. This is so that they can be computed once and cached, rather than being recomputed on every evaluation.
Different protocol versions may require different bundles of machine parameters, which allows us for
example to tweak the shape of the costing function of a builtin, so that the builtin costs less.
Currently this means that we have to create multiple DefaultMachineParameters
per language
version, which we put into a cache (represented by an association list) in order to avoid costly
recomputation of machine parameters.
In order to get the appropriate DefaultMachineParameters
at validation time we look it up in the
cache using a semantics variant as a key. We compute the semantics variant from the protocol
version using the stored function. Note that the semantics variant depends on the language version
too, but the latter is known statically (because each language version has its own evaluation
context), hence there's no reason to require it to be provided at runtime.
To say it differently, there's a matrix of semantics variants indexed by (LL, PV) pairs and we
cache its particular row corresponding to the statically given LL in an EvaluationContext
.
The reason why we associate a DefaultMachineParameters
with a semantics variant rather than a
protocol version are
- generally there are far more protocol versions than semantics variants supported by a specific language version, so we save on pointless duplication of bundles of machine parameters
- builtins don't know anything about protocol versions, only semantics variants. It is therefore more semantically precise to associate bundles of machine parameters with semantics variants than with protocol versions
EvaluationContext | |
|
Instances
class AsScriptDecodeError r where Source #
_ScriptDecodeError ∷ Prism' r ScriptDecodeError Source #
_CBORDeserialiseError ∷ Prism' r DeserialiseFailureInfo Source #
_RemainderError ∷ Prism' r ByteString Source #
_LedgerLanguageNotAvailableError ∷ Prism' r (PlutusLedgerLanguage, MajorProtocolVersion, MajorProtocolVersion) Source #
_PlutusCoreLanguageNotAvailableError ∷ Prism' r (Version, PlutusLedgerLanguage, MajorProtocolVersion) Source #
Instances
type LogOutput = [Text] Source #
The type of the executed script's accumulated log output: a list of Text
.
It will be an empty list if the VerboseMode
is set to Quiet
.
data VerboseMode Source #
A simple toggle indicating whether or not we should accumulate logs during script execution.
Instances
Eq VerboseMode Source # | |
Defined in PlutusLedgerApi.Common.Eval (==) ∷ VerboseMode → VerboseMode → Bool Source # (/=) ∷ VerboseMode → VerboseMode → Bool Source # |
evaluateScriptRestricting Source #
∷ PlutusLedgerLanguage | The Plutus ledger language of the script under execution. |
→ MajorProtocolVersion | Which major protocol version to run the operation in |
→ VerboseMode | Whether to produce log output |
→ EvaluationContext | Includes the cost model to use for tallying up the execution costs |
→ ExBudget | The resource budget which must not be exceeded during evaluation |
→ ScriptForEvaluation | The script to evaluate |
→ [Data] | The arguments to the script |
→ (LogOutput, Either EvaluationError ExBudget) |
Evaluates a script, with a cost model and a budget that restricts how many resources it can use according to the cost model. Also returns the budget that was actually used.
Can be used to calculate budgets for scripts, but even in this case you must give a limit to guard against scripts that run for a long time or loop.
Note: Parameterized over the LedgerPlutusVersion
since
1. The builtins allowed (during decoding) differ, and
2. The Plutus language versions allowed differ.
evaluateScriptCounting Source #
∷ PlutusLedgerLanguage | The Plutus ledger language of the script under execution. |
→ MajorProtocolVersion | Which major protocol version to run the operation in |
→ VerboseMode | Whether to produce log output |
→ EvaluationContext | Includes the cost model to use for tallying up the execution costs |
→ ScriptForEvaluation | The script to evaluate |
→ [Data] | The arguments to the script |
→ (LogOutput, Either EvaluationError ExBudget) |
Evaluates a script, returning the minimum budget that the script would need
to evaluate successfully. This will take as long as the script takes, if you need to
limit the execution time of the script also, you can use evaluateScriptRestricting
, which
also returns the used budget.
Note: Parameterized over the ledger-plutus-version since the builtins allowed (during decoding) differs.
evaluateTerm ∷ ExBudgetMode cost DefaultUni DefaultFun → MajorProtocolVersion → VerboseMode → EvaluationContext → Term NamedDeBruijn DefaultUni DefaultFun () → (Either (CekEvaluationException NamedDeBruijn DefaultUni DefaultFun) (Term NamedDeBruijn DefaultUni DefaultFun ()), cost, [Text]) Source #
Evaluate a fully-applied term using the CEK machine. Useful for mimicking the behaviour of the on-chain evaluator.
mkDynEvaluationContext ∷ MonadError CostModelApplyError m ⇒ PlutusLedgerLanguage → [BuiltinSemanticsVariant DefaultFun] → (MajorProtocolVersion → BuiltinSemanticsVariant DefaultFun) → CostModelParams → m EvaluationContext Source #
Create an EvaluationContext
given all builtin semantics variants supported by the provided
language version.
The input is a Map
of Text
s to cost integer values (aka CostModelParams
, CostModel
)
See Note [Inlining meanings of builtins].
IMPORTANT: the toSemVar
argument computes the semantics variant for each MajorProtocolVersion
and it must only return semantics variants from the semVars
list, as well as cover ANY
MajorProtocolVersion
, including those that do not exist yet (i.e. toSemVar
must never fail).
IMPORTANT: The evaluation context of every Plutus version must be recreated upon a protocol update with the updated cost model parameters.
∷ MonadError EvaluationError m | |
⇒ PlutusLedgerLanguage | the Plutus ledger language of the script under execution. |
→ MajorProtocolVersion | which major protocol version to run the operation in |
→ ScriptForEvaluation | the script to evaluate |
→ [Data] | the arguments that the script's underlying term will be applied to |
→ m (Term NamedDeBruijn DefaultUni DefaultFun ()) |
Shared helper for the evaluation functions: evaluateScriptCounting
and evaluateScriptRestricting
,
Given a ScriptForEvaluation
:
1) applies the term to a list of Data
arguments (e.g. Datum, Redeemer, ScriptContext
)
2) checks that the applied-term is well-scoped
3) returns the applied-term