Safe Haskell | None |
---|---|
Language | Haskell2010 |
Plutus.ApiCommon
Description
Common types and functions used across all the ledger API modules.
Synopsis
- type SerializedScript = ShortByteString
- data LedgerPlutusVersion
- data ProtocolVersion = ProtocolVersion { }
- builtinsIntroducedIn :: Map ( LedgerPlutusVersion , ProtocolVersion ) ( Set DefaultFun )
- builtinsAvailableIn :: LedgerPlutusVersion -> ProtocolVersion -> Set DefaultFun
- newtype ScriptForExecution = ScriptForExecution ( Program NamedDeBruijn DefaultUni DefaultFun ())
- scriptCBORDecoder :: LedgerPlutusVersion -> ProtocolVersion -> Decoder s ScriptForExecution
- isScriptWellFormed :: LedgerPlutusVersion -> ProtocolVersion -> SerializedScript -> Bool
- data EvaluationError
- type LogOutput = [ Text ]
- data VerboseMode
- mkTermToEvaluate :: MonadError EvaluationError m => LedgerPlutusVersion -> ProtocolVersion -> SerializedScript -> [ Data ] -> m ( Term NamedDeBruijn DefaultUni DefaultFun ())
- unliftingModeIn :: ProtocolVersion -> UnliftingMode
- type DefaultMachineParameters = MachineParameters CekMachineCosts CekValue DefaultUni DefaultFun
- toMachineParameters :: ProtocolVersion -> EvaluationContext -> DefaultMachineParameters
- mkMachineParametersFor :: MonadError CostModelApplyError m => UnliftingMode -> CostModelParams -> m DefaultMachineParameters
- data EvaluationContext = EvaluationContext { }
- mkEvaluationContext :: MonadError CostModelApplyError m => CostModelParams -> m EvaluationContext
- assertWellFormedCostModelParams :: MonadError CostModelApplyError m => CostModelParams -> m ()
- evaluateScriptRestricting :: LedgerPlutusVersion -> ProtocolVersion -> VerboseMode -> EvaluationContext -> ExBudget -> SerializedScript -> [ Data ] -> ( LogOutput , Either EvaluationError ExBudget )
- evaluateScriptCounting :: LedgerPlutusVersion -> ProtocolVersion -> VerboseMode -> EvaluationContext -> SerializedScript -> [ Data ] -> ( LogOutput , Either EvaluationError ExBudget )
Documentation
type SerializedScript = ShortByteString Source #
Scripts to the ledger are serialised bytestrings.
data LedgerPlutusVersion Source #
The plutus language version as seen from the ledger's side. Note: the ordering of constructors matters for deriving Ord
Instances
Eq LedgerPlutusVersion Source # | |
Defined in Plutus.ApiCommon Methods (==) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # (/=) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # |
|
Ord LedgerPlutusVersion Source # | |
Defined in Plutus.ApiCommon Methods compare :: LedgerPlutusVersion -> LedgerPlutusVersion -> Ordering Source # (<) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # (<=) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # (>) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # (>=) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source # max :: LedgerPlutusVersion -> LedgerPlutusVersion -> LedgerPlutusVersion Source # min :: LedgerPlutusVersion -> LedgerPlutusVersion -> LedgerPlutusVersion Source # |
data ProtocolVersion Source #
This represents the Cardano protocol version, with its major and minor components. This relies on careful understanding between us and the ledger as to what this means.
Constructors
ProtocolVersion | |
Instances
Eq ProtocolVersion Source # | |
Defined in Plutus.ApiCommon Methods (==) :: ProtocolVersion -> ProtocolVersion -> Bool Source # (/=) :: ProtocolVersion -> ProtocolVersion -> Bool Source # |
|
Ord ProtocolVersion Source # | |
Defined in Plutus.ApiCommon Methods compare :: ProtocolVersion -> ProtocolVersion -> Ordering Source # (<) :: ProtocolVersion -> ProtocolVersion -> Bool Source # (<=) :: ProtocolVersion -> ProtocolVersion -> Bool Source # (>) :: ProtocolVersion -> ProtocolVersion -> Bool Source # (>=) :: ProtocolVersion -> ProtocolVersion -> Bool Source # max :: ProtocolVersion -> ProtocolVersion -> ProtocolVersion Source # min :: ProtocolVersion -> ProtocolVersion -> ProtocolVersion Source # |
|
Show ProtocolVersion Source # | |
Defined in Plutus.ApiCommon |
|
Pretty ProtocolVersion Source # | |
Defined in Plutus.ApiCommon Methods pretty :: ProtocolVersion -> Doc ann Source # prettyList :: [ ProtocolVersion ] -> Doc ann Source # |
builtinsIntroducedIn :: Map ( LedgerPlutusVersion , ProtocolVersion ) ( Set DefaultFun ) Source #
A map indicating which builtin functions were introduced in which
ProtocolVersion
. Each builtin function should appear at most once.
This *must* be updated when new builtins are added. See Note [New builtins and protocol versions]
builtinsAvailableIn :: LedgerPlutusVersion -> ProtocolVersion -> Set DefaultFun Source #
Which builtin functions are available in the given
ProtocolVersion
?
See Note [New builtins and protocol versions]
newtype ScriptForExecution Source #
A variant of
Script
with a specialized decoder.
Constructors
ScriptForExecution ( Program NamedDeBruijn DefaultUni DefaultFun ()) |
scriptCBORDecoder :: LedgerPlutusVersion -> ProtocolVersion -> Decoder s ScriptForExecution Source #
This decoder decodes the names directly into
NamedDeBruijn
s rather than
DeBruijn
s.
This is needed because the CEK machine expects
NameDeBruijn
s, but there are obviously no names in the serialized form of a
Script
.
Rather than traversing the term and inserting fake names after deserializing, this lets us do at the same time as deserializing.
isScriptWellFormed :: LedgerPlutusVersion -> ProtocolVersion -> SerializedScript -> Bool Source #
Check if a
Script
is "valid" according to a protocol version. At the moment this means "deserialises correctly", which in particular
implies that it is (almost certainly) an encoded script and the script does not mention any builtins unavailable in the given protocol version.
Note: Parameterized over the ledger-plutus-version since the builtins allowed (during decoding) differs.
data EvaluationError Source #
Errors that can be thrown when evaluating a Plutus script.
Constructors
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 DeserialiseFailure |
A serialisation error |
IncompatibleVersionError ( Version ()) |
An error indicating a version tag that we don't support 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 |
Instances
Eq EvaluationError Source # | |
Defined in Plutus.ApiCommon Methods (==) :: EvaluationError -> EvaluationError -> Bool Source # (/=) :: EvaluationError -> EvaluationError -> Bool Source # |
|
Show EvaluationError Source # | |
Defined in Plutus.ApiCommon |
|
Pretty EvaluationError Source # | |
Defined in Plutus.ApiCommon Methods pretty :: EvaluationError -> Doc ann Source # prettyList :: [ EvaluationError ] -> Doc ann Source # |
data VerboseMode Source #
A simple toggle indicating whether or not we should produce logs.
Instances
Eq VerboseMode Source # | |
Defined in Plutus.ApiCommon Methods (==) :: VerboseMode -> VerboseMode -> Bool Source # (/=) :: VerboseMode -> VerboseMode -> Bool Source # |
mkTermToEvaluate :: MonadError EvaluationError m => LedgerPlutusVersion -> ProtocolVersion -> SerializedScript -> [ Data ] -> m ( Term NamedDeBruijn DefaultUni DefaultFun ()) Source #
Shared helper for the evaluation functions, deserializes the
SerializedScript
, applies it to its arguments, puts fakenamedebruijns, and scope-checks it.
unliftingModeIn :: ProtocolVersion -> UnliftingMode Source #
Which unlifting mode should we use in the given
ProtocolVersion
so as to correctly construct the machine's parameters
type DefaultMachineParameters = MachineParameters CekMachineCosts CekValue DefaultUni DefaultFun Source #
mkMachineParametersFor :: MonadError CostModelApplyError m => UnliftingMode -> CostModelParams -> m DefaultMachineParameters Source #
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 recomputed on every evaluation.
There are two sets of parameters: one is with immediate unlifting and the other one is with deferred unlifting. We have to keep both of them, because depending on the language version either one has to be used or the other. We also compile them separately due to all the inlining and optimization that need to happen for things to be efficient.
Constructors
EvaluationContext | |
Instances
Generic EvaluationContext Source # | |
Defined in Plutus.ApiCommon Methods from :: EvaluationContext -> Rep EvaluationContext x Source # to :: Rep EvaluationContext x -> EvaluationContext Source # |
|
NFData EvaluationContext Source # | |
Defined in Plutus.ApiCommon Methods rnf :: EvaluationContext -> () Source # |
|
NoThunks EvaluationContext Source # | |
Defined in Plutus.ApiCommon |
|
type Rep EvaluationContext Source # | |
Defined in Plutus.ApiCommon
type
Rep
EvaluationContext
=
D1
('
MetaData
"EvaluationContext" "Plutus.ApiCommon" "plutus-ledger-api-1.0.0.1-GlUFhIIE0LJGuJDDdHh5lQ" '
False
) (
C1
('
MetaCons
"EvaluationContext" '
PrefixI
'
True
) (
S1
('
MetaSel
('
Just
"machineParametersImmediate") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedStrict
) (
Rec0
DefaultMachineParameters
)
:*:
S1
('
MetaSel
('
Just
"machineParametersDeferred") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedStrict
) (
Rec0
DefaultMachineParameters
)))
|
mkEvaluationContext :: MonadError CostModelApplyError m => CostModelParams -> m EvaluationContext Source #
Build the
EvaluationContext
.
The input is a
Map
of strings to cost integer values (aka
CostModelParams
,
CostModel
)
See Note [Inlining meanings of builtins].
assertWellFormedCostModelParams :: MonadError CostModelApplyError m => CostModelParams -> m () Source #
Comparably expensive to
mkEvaluationContext
, so it should only be used sparingly.
evaluateScriptRestricting Source #
Arguments
:: LedgerPlutusVersion | |
-> ProtocolVersion | |
-> VerboseMode |
Whether to produce log output |
-> EvaluationContext |
The cost model that should already be synced to the most recent cost-model-params coming from the current protocol |
-> ExBudget |
The resource budget which must not be exceeded during evaluation |
-> SerializedScript |
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 ledger-plutus-version since the builtins allowed (during decoding) differs.
evaluateScriptCounting Source #
Arguments
:: LedgerPlutusVersion | |
-> ProtocolVersion | |
-> VerboseMode |
Whether to produce log output |
-> EvaluationContext |
The cost model that should already be synced to the most recent cost-model-params coming from the current protocol |
-> SerializedScript |
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.