Safe Haskell	None
Language	Haskell2010

Plutus.Trace.Emulator

Contents

Constructing Traces
- Inspecting the chain state
- Inspecting the agent states
Throwing errors
Running traces
Interpreter

Synopsis

data Emulator
type EmulatorTrace = Eff EmulatorEffects
type EmulatorEffects = StartContract ': BaseEmulatorEffects
type BaseEmulatorEffects = [RunContract, Assert, Waiting, EmulatorControl, EmulatedWalletAPI, LogMsg String, Error EmulatorRuntimeError]
data EmulatorErr
- = WalletErr WalletAPIError
- | ChainIndexErr ChainIndexError
- | AssertionErr AssertionError
- | InstanceErr EmulatorRuntimeError
- | ExitWasNeverCalled
data ContractHandle w s e = ContractHandle {
- chContract :: Contract w s e ()
- chInstanceId :: ContractInstanceId
- chInstanceTag :: ContractInstanceTag
- chNetworkId :: NetworkId
}
data ContractInstanceTag
type ContractConstraints s = (Forall (Output s) Unconstrained1, Forall (Input s) Unconstrained1, AllUniqueLabels (Input s), AllUniqueLabels (Output s), Forall (Input s) FromJSON, Forall (Input s) ToJSON, Forall (Output s) FromJSON, Forall (Output s) ToJSON)
assert :: forall effs. Member Assert effs => String -> (EmulatorState -> Bool) -> Eff effs ()
activateContract :: forall (contract :: Type -> Row Type -> Type -> Type -> Type) (s :: Row Type) e w a. (IsContract contract, ContractConstraints s, Show e, FromJSON e, ToJSON e, ToJSON w, Monoid w, FromJSON w) => forall effs. Member StartContract effs => Wallet -> contract w s e a -> ContractInstanceTag -> Eff effs (ContractHandle w s e)
activateContractWallet :: forall contract w s e effs. (IsContract contract, ContractConstraints s, Show e, ToJSON e, FromJSON e, ToJSON w, FromJSON w, Member StartContract effs, Monoid w) => Wallet -> contract w s e () -> Eff effs (ContractHandle w s e)
walletInstanceTag :: Wallet -> ContractInstanceTag
callEndpoint :: forall l ep w s e effs. (ToJSON ep, ContractConstraints s, HasEndpoint l ep s, Member RunContract effs) => ContractHandle w s e -> ep -> Eff effs ()
getContractState :: forall w (s :: Row Type) e. (ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => forall effs. Member RunContract effs => ContractHandle w s e -> Eff effs (ContractInstanceState w s e ())
observableState :: forall w s e effs. (Member RunContract effs, ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => ContractHandle w s e -> Eff effs w
activeEndpoints :: forall w s e effs. (Member RunContract effs, ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => ContractHandle w s e -> Eff effs [ActiveEndpoint]
liftWallet :: forall a. forall effs. Member EmulatedWalletAPI effs => Wallet -> Eff ('(:) WalletEffect ('(:) (Error WalletAPIError) ('(:) (LogMsg Text) ('(:) (LogMsg RequestHandlerLogMsg) ('[] :: [Type -> Type]))))) a -> Eff effs a
payToWallet :: forall effs. Member EmulatedWalletAPI effs => Wallet -> Wallet -> Value -> Eff effs TxId
nextSlot :: Member Waiting effs => Eff effs Slot
waitUntilSlot :: forall effs. Member Waiting effs => Slot -> Eff effs Slot
waitUntilTime :: Member Waiting effs => POSIXTime -> Eff effs POSIXTime
waitNSlots :: forall effs. Member Waiting effs => Natural -> Eff effs Slot
waitNMilliSeconds :: forall effs. Member Waiting effs => DiffMilliSeconds -> Eff effs Slot
freezeContractInstance :: forall effs. Member EmulatorControl effs => ContractInstanceId -> Eff effs ()
thawContractInstance :: forall effs. Member EmulatorControl effs => ContractInstanceId -> Eff effs ()
setSigningProcess :: forall effs. Member EmulatorControl effs => Wallet -> Maybe SigningProcess -> Eff effs ()
chainState :: forall effs. Member EmulatorControl effs => Eff effs ChainState
getSlotConfig :: forall effs. Member EmulatorControl effs => Eff effs SlotConfig
chainNewestFirst :: Lens' ChainState Blockchain
txPool :: Lens' ChainState TxPool
index :: Lens' ChainState UtxoIndex
chainCurrentSlot :: Lens' ChainState Slot
agentState :: forall effs. Member EmulatorControl effs => Wallet -> Eff effs WalletState
ownPaymentPrivateKey :: WalletState -> PaymentPrivateKey
nodeClient :: Lens' WalletState NodeClientState
signingProcess :: Lens' WalletState (Maybe SigningProcess)
throwError :: forall e (effs :: [Type -> Type]) a. Member (Error e) effs => e -> Eff effs a
data EmulatorRuntimeError
- = ThreadIdNotFound ContractInstanceId
- | InstanceIdNotFound Wallet
- | EmulatorJSONDecodingError String Value
- | GenericError String
- | EmulatedWalletError WalletAPIError
- | AssertionError String
data EmulatorConfig = EmulatorConfig {
- _initialChainState :: InitialChainState
- _params :: Params
}
initialChainState :: Lens' EmulatorConfig InitialChainState
params :: Lens' EmulatorConfig Params
runEmulatorStream :: forall effs a. EmulatorConfig -> EmulatorTrace a -> Stream (Of (LogMessage EmulatorEvent)) (Eff effs) (Either EmulatorErr a, EmulatorState)
data TraceConfig = TraceConfig {
- traceConfigShowEvent :: LogMessage EmulatorEvent -> Maybe String
- traceConfigOutputHandle :: Handle
- traceConfigMinLogLevel :: LogLevel
}
traceConfigShowEventExample :: LogMessage EmulatorEvent -> Maybe String
runEmulatorTrace :: TraceConfig -> EmulatorConfig -> EmulatorTrace a -> ([LogMessage EmulatorEvent], Either EmulatorErr a, EmulatorState)
evalEmulatorTrace :: TraceConfig -> EmulatorConfig -> EmulatorTrace a -> Either EmulatorErr a
data PrintEffect r where
- PrintLn :: String -> PrintEffect ()
runEmulatorTraceEff :: forall effs. Member PrintEffect effs => TraceConfig -> EmulatorConfig -> EmulatorTrace () -> Eff effs ()
runEmulatorTraceIO :: EmulatorTrace () -> IO ()
runEmulatorTraceIO' :: TraceConfig -> EmulatorConfig -> EmulatorTrace () -> IO ()
interpretEmulatorTrace :: forall effs a. (Member MultiAgentEffect effs, Member MultiAgentControlEffect effs, Member (Error EmulatorRuntimeError) effs, Member ChainControlEffect effs, Member (LogMsg EmulatorEvent') effs, Member (State EmulatorState) effs) => EmulatorConfig -> EmulatorTrace a -> Eff effs (Maybe a)

Documentation

data Emulator Source #

type EmulatorTrace = Eff EmulatorEffects Source #

type EmulatorEffects = StartContract ': BaseEmulatorEffects Source #

type BaseEmulatorEffects = [RunContract, Assert, Waiting, EmulatorControl, EmulatedWalletAPI, LogMsg String, Error EmulatorRuntimeError] Source #

data EmulatorErr Source #

Constructors

WalletErr WalletAPIError
ChainIndexErr ChainIndexError
AssertionErr AssertionError
InstanceErr EmulatorRuntimeError
ExitWasNeverCalled

Instances

Instances details

Show EmulatorErr Source #
Instance details Defined in Wallet.Emulator.Stream Methods showsPrec :: Int -> EmulatorErr -> ShowS Source # show :: EmulatorErr -> String Source # showList :: [EmulatorErr] -> ShowS Source #

data ContractHandle w s e Source #

A reference to a running contract in the emulator.

Constructors

ContractHandle
Fields chContract :: Contract w s e () chInstanceId :: ContractInstanceId chInstanceTag :: ContractInstanceTag chNetworkId :: NetworkId

data ContractInstanceTag Source #

A user-defined tag for a contract instance. Used to find the instance's log messages in the emulator log.

Instances

Instances details

Eq ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods (==) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source # (/=) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source #
Ord ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods compare :: ContractInstanceTag -> ContractInstanceTag -> Ordering Source # (<) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source # (<=) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source # (>) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source # (>=) :: ContractInstanceTag -> ContractInstanceTag -> Bool Source # max :: ContractInstanceTag -> ContractInstanceTag -> ContractInstanceTag Source # min :: ContractInstanceTag -> ContractInstanceTag -> ContractInstanceTag Source #
Show ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods showsPrec :: Int -> ContractInstanceTag -> ShowS Source # show :: ContractInstanceTag -> String Source # showList :: [ContractInstanceTag] -> ShowS Source #
IsString ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods fromString :: String -> ContractInstanceTag Source #
Generic ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Associated Types type Rep ContractInstanceTag :: Type -> Type Source # Methods from :: ContractInstanceTag -> Rep ContractInstanceTag x Source # to :: Rep ContractInstanceTag x -> ContractInstanceTag Source #
FromJSON ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods parseJSON :: Value -> Parser ContractInstanceTag parseJSONList :: Value -> Parser [ContractInstanceTag]
ToJSON ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods toJSON :: ContractInstanceTag -> Value toEncoding :: ContractInstanceTag -> Encoding toJSONList :: [ContractInstanceTag] -> Value toEncodingList :: [ContractInstanceTag] -> Encoding
Pretty ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods pretty :: ContractInstanceTag -> Doc ann prettyList :: [ContractInstanceTag] -> Doc ann
type Rep ContractInstanceTag Source #
Instance details Defined in Plutus.Trace.Emulator.Types type Rep ContractInstanceTag = D1 ('MetaData "ContractInstanceTag" "Plutus.Trace.Emulator.Types" "plutus-contract-1.2.0.0-FH8LC9wh7UV4Nmv68NHXrC" 'False) (C1 ('MetaCons "ContractInstanceTag" 'PrefixI 'True) (S1 ('MetaSel ('Just "unContractInstanceTag") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text) :*: S1 ('MetaSel ('Just "shortContractInstanceTag") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))

type ContractConstraints s = (Forall (Output s) Unconstrained1, Forall (Input s) Unconstrained1, AllUniqueLabels (Input s), AllUniqueLabels (Output s), Forall (Input s) FromJSON, Forall (Input s) ToJSON, Forall (Output s) FromJSON, Forall (Output s) ToJSON) Source #

Constructing Traces

assert :: forall effs. Member Assert effs => String -> (EmulatorState -> Bool) -> Eff effs () Source #

activateContract :: forall (contract :: Type -> Row Type -> Type -> Type -> Type) (s :: Row Type) e w a. (IsContract contract, ContractConstraints s, Show e, FromJSON e, ToJSON e, ToJSON w, Monoid w, FromJSON w) => forall effs. Member StartContract effs => Wallet -> contract w s e a -> ContractInstanceTag -> Eff effs (ContractHandle w s e) Source #

activateContractWallet :: forall contract w s e effs. (IsContract contract, ContractConstraints s, Show e, ToJSON e, FromJSON e, ToJSON w, FromJSON w, Member StartContract effs, Monoid w) => Wallet -> contract w s e () -> Eff effs (ContractHandle w s e) Source #

Like activateContract, but using walletInstanceTag for the tag.

walletInstanceTag :: Wallet -> ContractInstanceTag Source #

The ContractInstanceTag for the contract instance of a wallet. See note [Wallet contract instances]

callEndpoint :: forall l ep w s e effs. (ToJSON ep, ContractConstraints s, HasEndpoint l ep s, Member RunContract effs) => ContractHandle w s e -> ep -> Eff effs () Source #

Call an endpoint on a contract instance.

getContractState :: forall w (s :: Row Type) e. (ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => forall effs. Member RunContract effs => ContractHandle w s e -> Eff effs (ContractInstanceState w s e ()) Source #

observableState :: forall w s e effs. (Member RunContract effs, ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => ContractHandle w s e -> Eff effs w Source #

Get the observable state w of a contract instance.

activeEndpoints :: forall w s e effs. (Member RunContract effs, ContractConstraints s, FromJSON e, FromJSON w, ToJSON w) => ContractHandle w s e -> Eff effs [ActiveEndpoint] Source #

Get the active endpoints of a contract instance.

liftWallet :: forall a. forall effs. Member EmulatedWalletAPI effs => Wallet -> Eff ('(:) WalletEffect ('(:) (Error WalletAPIError) ('(:) (LogMsg Text) ('(:) (LogMsg RequestHandlerLogMsg) ('[] :: [Type -> Type]))))) a -> Eff effs a Source #

payToWallet :: forall effs. Member EmulatedWalletAPI effs => Wallet -> Wallet -> Value -> Eff effs TxId Source #

Make a payment from one wallet to another

nextSlot :: Member Waiting effs => Eff effs Slot Source #

Wait until the beginning of the next slot, returning the new slot number.

waitUntilSlot :: forall effs. Member Waiting effs => Slot -> Eff effs Slot Source #

waitUntilTime :: Member Waiting effs => POSIXTime -> Eff effs POSIXTime Source #

Wait until the slot where the given time falls into and return latest time we know has passed.

waitNSlots :: forall effs. Member Waiting effs => Natural -> Eff effs Slot Source #

Wait for a number of slots

waitNMilliSeconds :: forall effs. Member Waiting effs => DiffMilliSeconds -> Eff effs Slot Source #

Convert the given n milliseconds to a number of slots to wait.

Note: Currently, if n < length of a slot, then waitNMilliSeconds has no effect.

freezeContractInstance :: forall effs. Member EmulatorControl effs => ContractInstanceId -> Eff effs () Source #

thawContractInstance :: forall effs. Member EmulatorControl effs => ContractInstanceId -> Eff effs () Source #

Inspecting the chain state

setSigningProcess :: forall effs. Member EmulatorControl effs => Wallet -> Maybe SigningProcess -> Eff effs () Source #

chainState :: forall effs. Member EmulatorControl effs => Eff effs ChainState Source #

getSlotConfig :: forall effs. Member EmulatorControl effs => Eff effs SlotConfig Source #

chainNewestFirst :: Lens' ChainState Blockchain #

txPool :: Lens' ChainState TxPool #

index :: Lens' ChainState UtxoIndex #

chainCurrentSlot :: Lens' ChainState Slot #

Inspecting the agent states

agentState :: forall effs. Member EmulatorControl effs => Wallet -> Eff effs WalletState Source #

ownPaymentPrivateKey :: WalletState -> PaymentPrivateKey Source #

nodeClient :: Lens' WalletState NodeClientState Source #

signingProcess :: Lens' WalletState (Maybe SigningProcess) Source #

Throwing errors

throwError :: forall e (effs :: [Type -> Type]) a. Member (Error e) effs => e -> Eff effs a #

data EmulatorRuntimeError Source #

Constructors

ThreadIdNotFound ContractInstanceId
InstanceIdNotFound Wallet
EmulatorJSONDecodingError String Value
GenericError String
EmulatedWalletError WalletAPIError
AssertionError String

Instances

Instances details

Eq EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods (==) :: EmulatorRuntimeError -> EmulatorRuntimeError -> Bool Source # (/=) :: EmulatorRuntimeError -> EmulatorRuntimeError -> Bool Source #
Show EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods showsPrec :: Int -> EmulatorRuntimeError -> ShowS Source # show :: EmulatorRuntimeError -> String Source # showList :: [EmulatorRuntimeError] -> ShowS Source #
Generic EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Associated Types type Rep EmulatorRuntimeError :: Type -> Type Source # Methods from :: EmulatorRuntimeError -> Rep EmulatorRuntimeError x Source # to :: Rep EmulatorRuntimeError x -> EmulatorRuntimeError Source #
FromJSON EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods parseJSON :: Value -> Parser EmulatorRuntimeError parseJSONList :: Value -> Parser [EmulatorRuntimeError]
ToJSON EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods toJSON :: EmulatorRuntimeError -> Value toEncoding :: EmulatorRuntimeError -> Encoding toJSONList :: [EmulatorRuntimeError] -> Value toEncodingList :: [EmulatorRuntimeError] -> Encoding
Pretty EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types Methods pretty :: EmulatorRuntimeError -> Doc ann prettyList :: [EmulatorRuntimeError] -> Doc ann
type Rep EmulatorRuntimeError Source #
Instance details Defined in Plutus.Trace.Emulator.Types type Rep EmulatorRuntimeError = D1 ('MetaData "EmulatorRuntimeError" "Plutus.Trace.Emulator.Types" "plutus-contract-1.2.0.0-FH8LC9wh7UV4Nmv68NHXrC" 'False) ((C1 ('MetaCons "ThreadIdNotFound" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ContractInstanceId)) :+: (C1 ('MetaCons "InstanceIdNotFound" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Wallet)) :+: C1 ('MetaCons "EmulatorJSONDecodingError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Value)))) :+: (C1 ('MetaCons "GenericError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)) :+: (C1 ('MetaCons "EmulatedWalletError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 WalletAPIError)) :+: C1 ('MetaCons "AssertionError" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))

Running traces

data EmulatorConfig Source #

Constructors

EmulatorConfig
Fields _initialChainState :: InitialChainState State of the blockchain at the beginning of the simulation. Can be given as a map of funds to wallets, or as a block of transactions. _params :: Params Set the protocol parameters, network ID and slot configuration for the emulator.

Instances

Instances details

Eq EmulatorConfig Source #
Instance details Defined in Wallet.Emulator.Stream Methods (==) :: EmulatorConfig -> EmulatorConfig -> Bool Source # (/=) :: EmulatorConfig -> EmulatorConfig -> Bool Source #
Show EmulatorConfig Source #
Instance details Defined in Wallet.Emulator.Stream Methods showsPrec :: Int -> EmulatorConfig -> ShowS Source # show :: EmulatorConfig -> String Source # showList :: [EmulatorConfig] -> ShowS Source #
Default EmulatorConfig Source #
Instance details Defined in Wallet.Emulator.Stream Methods def :: EmulatorConfig

initialChainState :: Lens' EmulatorConfig InitialChainState Source #

params :: Lens' EmulatorConfig Params Source #

runEmulatorStream :: forall effs a. EmulatorConfig -> EmulatorTrace a -> Stream (Of (LogMessage EmulatorEvent)) (Eff effs) (Either EmulatorErr a, EmulatorState) Source #

Run a 'Trace Emulator', streaming the log messages as they arrive

data TraceConfig Source #

Options for how to set up and print the trace.

Constructors

TraceConfig
Fields traceConfigShowEvent :: LogMessage EmulatorEvent -> Maybe String Function to decide how to print the particular events. traceConfigOutputHandle :: Handle Where to print the outputs to. Default: `stdout` traceConfigMinLogLevel :: LogLevel

Instances

Instances details

Default TraceConfig Source #
Instance details Defined in Plutus.Trace.Emulator Methods def :: TraceConfig

traceConfigShowEventExample :: LogMessage EmulatorEvent -> Maybe String Source #

Some example of how to configure the traceConfigShowEvent.

runEmulatorTrace :: TraceConfig -> EmulatorConfig -> EmulatorTrace a -> ([LogMessage EmulatorEvent], Either EmulatorErr a, EmulatorState) Source #

Run an emulator trace to completion, returning a tuple of the final state of the emulator, the events, and any error, if any.

evalEmulatorTrace :: TraceConfig -> EmulatorConfig -> EmulatorTrace a -> Either EmulatorErr a Source #

data PrintEffect r where Source #

A very simple effect for interpreting the output printing done by the trace printing functions:

runEmulatorTraceEff
runEmulatorTraceIO
runEmulatorTraceIOWithConfig

Constructors

PrintLn :: String -> PrintEffect ()

runEmulatorTraceEff :: forall effs. Member PrintEffect effs => TraceConfig -> EmulatorConfig -> EmulatorTrace () -> Eff effs () Source #

Run the emulator trace returning an effect that can be evaluated by interpreting the PrintEffects.

runEmulatorTraceIO :: EmulatorTrace () -> IO () Source #

Runs the trace with runEmulatorTrace, with default configuration that prints a selection of events to stdout.

Example:

>>> runEmulatorTraceIO (void $ Trace.waitNSlots 1)

runEmulatorTraceIO' :: TraceConfig -> EmulatorConfig -> EmulatorTrace () -> IO () Source #

Deprecated: Renamed to runEmulatorTraceIOWithConfig

Interpreter

interpretEmulatorTrace :: forall effs a. (Member MultiAgentEffect effs, Member MultiAgentControlEffect effs, Member (Error EmulatorRuntimeError) effs, Member ChainControlEffect effs, Member (LogMsg EmulatorEvent') effs, Member (State EmulatorState) effs) => EmulatorConfig -> EmulatorTrace a -> Eff effs (Maybe a) Source #

Interpret a 'Trace Emulator' action in the multi agent and emulated blockchain effects.