PlutusCore.Evaluation.Machine.Exception

plutus-core-1.60.0.0: Language library for Plutus Core

Safe Haskell	Safe-Inferred
Language	Haskell2010

Description

The exceptions that an abstract machine can throw.

Synopsis

newtype UnliftingError = MkUnliftingError {
- unUnliftingError :: Text

Instances

Instances details

IsString UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods fromString :: String -> UnliftingError #
Monoid UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods mempty :: UnliftingError # mappend :: UnliftingError -> UnliftingError -> UnliftingError # mconcat :: [UnliftingError] -> UnliftingError #
Semigroup UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods (<>) :: UnliftingError -> UnliftingError -> UnliftingError # sconcat :: NonEmpty UnliftingError -> UnliftingError # stimes :: Integral b => b -> UnliftingError -> UnliftingError #
Show UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods showsPrec :: Int -> UnliftingError -> ShowS # show :: UnliftingError -> String # showList :: [UnliftingError] -> ShowS #
NFData UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods rnf :: UnliftingError -> () #
Eq UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods (==) :: UnliftingError -> UnliftingError -> Bool # (/=) :: UnliftingError -> UnliftingError -> Bool #
Pretty UnliftingError #
Instance details Defined in PlutusCore.Builtin.Result Methods pretty :: UnliftingError -> Doc ann # prettyList :: [UnliftingError] -> Doc ann #

data BuiltinError #

The type of errors that readKnown and makeKnown can return.

Constructors

BuiltinUnliftingEvaluationError UnliftingEvaluationError
BuiltinEvaluationFailure

Instances

Instances details

Show BuiltinError #
Instance details Defined in PlutusCore.Builtin.Result Methods showsPrec :: Int -> BuiltinError -> ShowS # show :: BuiltinError -> String # showList :: [BuiltinError] -> ShowS #
Eq BuiltinError #
Instance details Defined in PlutusCore.Builtin.Result Methods (==) :: BuiltinError -> BuiltinError -> Bool # (/=) :: BuiltinError -> BuiltinError -> Bool #
Pretty BuiltinError #
Instance details Defined in PlutusCore.Builtin.Result Methods pretty :: BuiltinError -> Doc ann # prettyList :: [BuiltinError] -> Doc ann #
MonadError BuiltinError BuiltinResult #	`throwError` puts every operational unlifting error into the `BuiltinFailure` logs. This is to compensate for the historical lack of error message content in operational errors (structural ones don't have this problem) in our evaluators (the CK and CEK machines). It would be better to fix the underlying issue and allow operational evaluation errors to carry some form of content, but for now we just fix the symptom in order for the end user to see the error message that they are supposed to see. The fix even makes some sense: what we do here is we emulate logging when the thrown unlifting error is an operational one, i.e. this is similar to what some builtins do manually (like when a crypto builtin fails and puts info about the failure into the logs).
Instance details Defined in PlutusCore.Builtin.Result Methods throwError :: BuiltinError -> BuiltinResult a # catchError :: BuiltinResult a -> (BuiltinError -> BuiltinResult a) -> BuiltinResult a #

data MachineError fun #

Errors which can occur during a run of an abstract machine.

Constructors

NonPolymorphicInstantiationMachineError	An attempt to reduce a not immediately reducible type instantiation.
NonWrapUnwrappedMachineError	An attempt to unwrap a not wrapped term.
NonFunctionalApplicationMachineError	An attempt to reduce a not immediately reducible application.
OpenTermEvaluatedMachineError	An attempt to evaluate an open term.
UnliftingMachineError UnliftingError	An attempt to compute a constant application resulted in `UnliftingError`.
BuiltinTermArgumentExpectedMachineError	A builtin expected a term argument, but something else was received.
UnexpectedBuiltinTermArgumentMachineError	A builtin received a term argument when something else was expected
NonConstrScrutinizedMachineError	An attempt to scrutinize a non-constr.
MissingCaseBranchMachineError Word64	An attempt to go into a non-existent case branch.
PanicMachineError String	A GHC exception was thrown.

Instances

Instances details

Functor MachineError #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Methods fmap :: (a -> b) -> MachineError a -> MachineError b # (<$) :: a -> MachineError b -> MachineError a #
(HasPrettyDefaults config ~ 'True, Pretty fun) => PrettyBy config (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Methods prettyBy :: config -> MachineError fun -> Doc ann # prettyListBy :: config -> [MachineError fun] -> Doc ann #
Generic (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Associated Types type Rep (MachineError fun) :: Type -> Type # Methods from :: MachineError fun -> Rep (MachineError fun) x # to :: Rep (MachineError fun) x -> MachineError fun #
Show (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Methods showsPrec :: Int -> MachineError fun -> ShowS # show :: MachineError fun -> String # showList :: [MachineError fun] -> ShowS #
NFData (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Methods rnf :: MachineError fun -> () #
Eq (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception Methods (==) :: MachineError fun -> MachineError fun -> Bool # (/=) :: MachineError fun -> MachineError fun -> Bool #
BuiltinErrorToEvaluationError (MachineError fun) CekUserError #
Instance details Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods builtinErrorToEvaluationError :: BuiltinError -> EvaluationError (MachineError fun) CekUserError #
ThrowableBuiltins uni fun => MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) #
Instance details Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods throwError :: CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a # catchError :: CekM uni fun s a -> (CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a) -> CekM uni fun s a #
type Rep (MachineError fun) #
Instance details Defined in PlutusCore.Evaluation.Machine.Exception type Rep (MachineError fun) = D1 ('MetaData "MachineError" "PlutusCore.Evaluation.Machine.Exception" "plutus-core-1.60.0.0-inplace" 'False) (((C1 ('MetaCons "NonPolymorphicInstantiationMachineError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "NonWrapUnwrappedMachineError" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "NonFunctionalApplicationMachineError" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "OpenTermEvaluatedMachineError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "UnliftingMachineError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 UnliftingError))))) :+: ((C1 ('MetaCons "BuiltinTermArgumentExpectedMachineError" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "UnexpectedBuiltinTermArgumentMachineError" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "NonConstrScrutinizedMachineError" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "MissingCaseBranchMachineError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64)) :+: C1 ('MetaCons "PanicMachineError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String))))))

data EvaluationError structural operational #

The type of errors that can occur during evaluation. There are two kinds of errors:

Structural ones -- these are errors that are indicative of the _structure_ of the program being wrong. For example, a free variable was encountered during evaluation, a non-function was applied to an argument or tailList was applied to a non-list.
Operational ones -- these are errors that are indicative of the _logic_ of the program being wrong. For example, error was executed, tailList was applied to an empty list or evaluation ran out of gas.

On the chain both of these are just regular failures and we don't distinguish between them there: if a script fails, it fails, it doesn't matter what the reason was. However in the tests it does matter why the failure occurred: a structural error may indicate that the test was written incorrectly while an operational error may be entirely expected.

In other words, structural errors are "runtime type errors" and operational errors are regular runtime errors. Which means that evaluating an (erased) well-typed program should never produce a structural error, only an operational one. This creates a sort of "runtime type system" for UPLC and it would be great to stick to it and enforce in tests etc, but we currently don't.

Constructors

StructuralError !structural
OperationalError !operational

Instances

Instances details

Bifoldable EvaluationError #
Instance details Defined in PlutusCore.Evaluation.Error Methods bifold :: Monoid m => EvaluationError m m -> m # bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> EvaluationError a b -> m # bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> EvaluationError a b -> c # bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> EvaluationError a b -> c #
Bifunctor EvaluationError #
Instance details Defined in PlutusCore.Evaluation.Error Methods bimap :: (a -> b) -> (c -> d) -> EvaluationError a c -> EvaluationError b d # first :: (a -> b) -> EvaluationError a c -> EvaluationError b c # second :: (b -> c) -> EvaluationError a b -> EvaluationError a c #
Bitraversable EvaluationError #
Instance details Defined in PlutusCore.Evaluation.Error Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> EvaluationError a b -> f (EvaluationError c d) #
(HasPrettyDefaults config ~ 'True, PrettyBy config structural, Pretty operational) => PrettyBy config (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Methods prettyBy :: config -> EvaluationError structural operational -> Doc ann # prettyListBy :: config -> [EvaluationError structural operational] -> Doc ann #
Functor (EvaluationError structural) #
Instance details Defined in PlutusCore.Evaluation.Error Methods fmap :: (a -> b) -> EvaluationError structural a -> EvaluationError structural b # (<$) :: a -> EvaluationError structural b -> EvaluationError structural a #
Generic (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Associated Types type Rep (EvaluationError structural operational) :: Type -> Type # Methods from :: EvaluationError structural operational -> Rep (EvaluationError structural operational) x # to :: Rep (EvaluationError structural operational) x -> EvaluationError structural operational #
(Show structural, Show operational) => Show (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Methods showsPrec :: Int -> EvaluationError structural operational -> ShowS # show :: EvaluationError structural operational -> String # showList :: [EvaluationError structural operational] -> ShowS #
(NFData structural, NFData operational) => NFData (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Methods rnf :: EvaluationError structural operational -> () #
(Eq structural, Eq operational) => Eq (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Methods (==) :: EvaluationError structural operational -> EvaluationError structural operational -> Bool # (/=) :: EvaluationError structural operational -> EvaluationError structural operational -> Bool #
(Pretty structural, Pretty operational) => Pretty (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error Methods pretty :: EvaluationError structural operational -> Doc ann # prettyList :: [EvaluationError structural operational] -> Doc ann #
ThrowableBuiltins uni fun => MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) #
Instance details Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods throwError :: CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a # catchError :: CekM uni fun s a -> (CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a) -> CekM uni fun s a #
type Rep (EvaluationError structural operational) #
Instance details Defined in PlutusCore.Evaluation.Error type Rep (EvaluationError structural operational) = D1 ('MetaData "EvaluationError" "PlutusCore.Evaluation.Error" "plutus-core-1.60.0.0-inplace" 'False) (C1 ('MetaCons "StructuralError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 structural)) :+: C1 ('MetaCons "OperationalError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 operational)))

data ErrorWithCause err cause #

An error and (optionally) what caused it.

Constructors

ErrorWithCause
Fields _ewcError :: !err _ewcCause :: !(Maybe cause)

Instances

Instances details

Bifunctor ErrorWithCause #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods bimap :: (a -> b) -> (c -> d) -> ErrorWithCause a c -> ErrorWithCause b d # first :: (a -> b) -> ErrorWithCause a c -> ErrorWithCause b c # second :: (b -> c) -> ErrorWithCause a b -> ErrorWithCause a c #
(PrettyBy config cause, PrettyBy config err) => PrettyBy config (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods prettyBy :: config -> ErrorWithCause err cause -> Doc ann # prettyListBy :: config -> [ErrorWithCause err cause] -> Doc ann #
Foldable (ErrorWithCause err) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods fold :: Monoid m => ErrorWithCause err m -> m # foldMap :: Monoid m => (a -> m) -> ErrorWithCause err a -> m # foldMap' :: Monoid m => (a -> m) -> ErrorWithCause err a -> m # foldr :: (a -> b -> b) -> b -> ErrorWithCause err a -> b # foldr' :: (a -> b -> b) -> b -> ErrorWithCause err a -> b # foldl :: (b -> a -> b) -> b -> ErrorWithCause err a -> b # foldl' :: (b -> a -> b) -> b -> ErrorWithCause err a -> b # foldr1 :: (a -> a -> a) -> ErrorWithCause err a -> a # foldl1 :: (a -> a -> a) -> ErrorWithCause err a -> a # toList :: ErrorWithCause err a -> [a] # null :: ErrorWithCause err a -> Bool # length :: ErrorWithCause err a -> Int # elem :: Eq a => a -> ErrorWithCause err a -> Bool # maximum :: Ord a => ErrorWithCause err a -> a # minimum :: Ord a => ErrorWithCause err a -> a # sum :: Num a => ErrorWithCause err a -> a # product :: Num a => ErrorWithCause err a -> a #
Traversable (ErrorWithCause err) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods traverse :: Applicative f => (a -> f b) -> ErrorWithCause err a -> f (ErrorWithCause err b) # sequenceA :: Applicative f => ErrorWithCause err (f a) -> f (ErrorWithCause err a) # mapM :: Monad m => (a -> m b) -> ErrorWithCause err a -> m (ErrorWithCause err b) # sequence :: Monad m => ErrorWithCause err (m a) -> m (ErrorWithCause err a) #
Functor (ErrorWithCause err) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods fmap :: (a -> b) -> ErrorWithCause err a -> ErrorWithCause err b # (<$) :: a -> ErrorWithCause err b -> ErrorWithCause err a #
(PrettyPlc cause, PrettyPlc err, Typeable cause, Typeable err) => Exception (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods toException :: ErrorWithCause err cause -> SomeException # fromException :: SomeException -> Maybe (ErrorWithCause err cause) # displayException :: ErrorWithCause err cause -> String #
Generic (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Associated Types type Rep (ErrorWithCause err cause) :: Type -> Type # Methods from :: ErrorWithCause err cause -> Rep (ErrorWithCause err cause) x # to :: Rep (ErrorWithCause err cause) x -> ErrorWithCause err cause #
(PrettyPlc cause, PrettyPlc err) => Show (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods showsPrec :: Int -> ErrorWithCause err cause -> ShowS # show :: ErrorWithCause err cause -> String # showList :: [ErrorWithCause err cause] -> ShowS #
(NFData err, NFData cause) => NFData (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods rnf :: ErrorWithCause err cause -> () #
(Eq err, Eq cause) => Eq (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods (==) :: ErrorWithCause err cause -> ErrorWithCause err cause -> Bool # (/=) :: ErrorWithCause err cause -> ErrorWithCause err cause -> Bool #
(Pretty err, Pretty cause) => Pretty (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause Methods pretty :: ErrorWithCause err cause -> Doc ann # prettyList :: [ErrorWithCause err cause] -> Doc ann #
ThrowableBuiltins uni fun => MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) #
Instance details Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods throwError :: CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a # catchError :: CekM uni fun s a -> (CekEvaluationException NamedDeBruijn uni fun -> CekM uni fun s a) -> CekM uni fun s a #
type Rep (ErrorWithCause err cause) #
Instance details Defined in PlutusCore.Evaluation.ErrorWithCause type Rep (ErrorWithCause err cause) = D1 ('MetaData "ErrorWithCause" "PlutusCore.Evaluation.ErrorWithCause" "plutus-core-1.60.0.0-inplace" 'False) (C1 ('MetaCons "ErrorWithCause" 'PrefixI 'True) (S1 ('MetaSel ('Just "_ewcError") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 err) :*: S1 ('MetaSel ('Just "_ewcCause") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Maybe cause))))

type EvaluationException structural operational = ErrorWithCause (EvaluationError structural operational) #

notAConstant :: BuiltinError #

throwErrorWithCause :: MonadError (ErrorWithCause e cause) m => e -> cause -> m x #

splitStructuralOperational :: Either (EvaluationException structural operational term) a -> Either (ErrorWithCause structural term) (EvaluationResult a) #

Preserve the contents of an StructuralError as a Left and turn an OperationalError into a Right EvaluationFailure (thus erasing the content of the error in the latter case).

unsafeSplitStructuralOperational :: (PrettyPlc structural, PrettyPlc term, Typeable structural, Typeable term) => Either (EvaluationException structural operational term) a -> EvaluationResult a #

Throw on a StructuralError and turn an OperationalError into an EvaluationFailure (thus erasing the content of the error in the latter case).

class BuiltinErrorToEvaluationError structural operational #

Minimal complete definition

builtinErrorToEvaluationError

Instances

Instances details

BuiltinErrorToEvaluationError (MachineError fun) CekUserError #
Instance details Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal Methods builtinErrorToEvaluationError :: BuiltinError -> EvaluationError (MachineError fun) CekUserError #

builtinErrorToEvaluationError :: BuiltinErrorToEvaluationError structural operational => BuiltinError -> EvaluationError structural operational #

throwBuiltinErrorWithCause :: (MonadError (EvaluationException structural operational cause) m, BuiltinErrorToEvaluationError structural operational) => cause -> BuiltinError -> m void #

Attach a cause to a BuiltinError and throw that. Note that an evaluator might require the cause to be computed lazily for best performance on the happy path, hence this function must not force its first argument. TODO: wrap cause in Lazy once we have it.