plutus-ledger-api-1.0.0.1: Interface to the Plutus ledger for the Cardano ledger.
Safe Haskell None
Language Haskell2010

Plutus.ApiCommon

Description

Common types and functions used across all the ledger API modules.

Synopsis

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

Constructors

PlutusV1
PlutusV2

Instances

Instances details
Eq LedgerPlutusVersion Source #
Instance details

Defined in Plutus.ApiCommon

Methods

(==) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source #

(/=) :: LedgerPlutusVersion -> LedgerPlutusVersion -> Bool Source #

Ord LedgerPlutusVersion Source #
Instance details

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

Fields

Instances

Instances details
Eq ProtocolVersion Source #
Instance details

Defined in Plutus.ApiCommon

Methods

(==) :: ProtocolVersion -> ProtocolVersion -> Bool Source #

(/=) :: ProtocolVersion -> ProtocolVersion -> Bool Source #

Ord ProtocolVersion Source #
Instance details

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 #
Instance details

Defined in Plutus.ApiCommon

Methods

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

show :: ProtocolVersion -> String Source #

showList :: [ ProtocolVersion ] -> ShowS Source #

Pretty ProtocolVersion Source #
Instance details

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

Instances details
Eq EvaluationError Source #
Instance details

Defined in Plutus.ApiCommon

Methods

(==) :: EvaluationError -> EvaluationError -> Bool Source #

(/=) :: EvaluationError -> EvaluationError -> Bool Source #

Show EvaluationError Source #
Instance details

Defined in Plutus.ApiCommon

Methods

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

show :: EvaluationError -> String Source #

showList :: [ EvaluationError ] -> ShowS Source #

Pretty EvaluationError Source #
Instance details

Defined in Plutus.ApiCommon

Methods

pretty :: EvaluationError -> Doc ann Source #

prettyList :: [ EvaluationError ] -> Doc ann Source #

type LogOutput = [ Text ] Source #

The type of log output: just a list of Text .

data VerboseMode Source #

A simple toggle indicating whether or not we should produce logs.

Constructors

Verbose
Quiet

Instances

Instances details
Eq VerboseMode Source #
Instance details

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 #

toMachineParameters :: ProtocolVersion -> EvaluationContext -> DefaultMachineParameters 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

Fields

Instances

Instances details
Generic EvaluationContext Source #
Instance details

Defined in Plutus.ApiCommon

Associated Types

type Rep EvaluationContext :: Type -> Type Source #

Methods

from :: EvaluationContext -> Rep EvaluationContext x Source #

to :: Rep EvaluationContext x -> EvaluationContext Source #

NFData EvaluationContext Source #
Instance details

Defined in Plutus.ApiCommon

Methods

rnf :: EvaluationContext -> () Source #

NoThunks EvaluationContext Source #
Instance details

Defined in Plutus.ApiCommon

Methods

noThunks :: Context -> EvaluationContext -> IO ( Maybe ThunkInfo ) Source #

wNoThunks :: Context -> EvaluationContext -> IO ( Maybe ThunkInfo ) Source #

showTypeOf :: Proxy EvaluationContext -> String Source #

type Rep EvaluationContext Source #
Instance details

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.