plutus-pab-1.2.0.0
Safe HaskellNone
LanguageHaskell2010

Plutus.PAB.Core

Synopsis

Documentation

type PABEffects t env = '[ContractStore t, ContractEffect t, ContractDefinition t, LogMsg (PABMultiAgentMsg t), TimeEffect, Reader (PABEnvironment t env), Error PABError, IO] Source #

Effects that are available in PABActions.

type PABAction t env a = Eff (PABEffects t env) a Source #

Actions that are run by the PAB.

data EffectHandlers t env Source #

Effect handlers for running the PAB.

Constructors

EffectHandlers 

Fields

runPAB :: forall t env a. Timeout -> Timeout -> EffectHandlers t env -> PABAction t env a -> IO (Either PABError a) Source #

Top-level entry point. Run a PABAction, using the EffectHandlers to deal with logs, startup and shutdown, contract requests and communication with external services.

runPAB' :: forall t env a. PABEnvironment t env -> PABAction t env a -> IO (Either PABError a) Source #

Run a PABAction in the context of the given environment. TODO: Clean it up so there is less duplication of the above.

data PABEnvironment t env Source #

Shared data that is needed by all PAB threads.

Constructors

PABEnvironment 

Fields

Contracts and instances

reportContractState :: forall t effs. (Member (ContractStore t) effs, PABContract t) => ContractInstanceId -> Eff effs (PartiallyDecodedResponse PABReq) Source #

Report the state of a running contract.

activateContract :: forall t env. PABContract t => Wallet -> ContractDef t -> PABAction t env ContractInstanceId Source #

Start a new instance of a contract

activateContract' :: forall t env. PABContract t => ContractInstanceState t -> ContractInstanceId -> Wallet -> ContractDef t -> PABAction t env ContractInstanceId Source #

Start a new instance of a contract, with a given state. Note that we skip running the effects that push the state into the contract store, because we assume that if you're providing the state, it's already present in the store.

callEndpointOnInstance :: forall t env a. ToJSON a => ContractInstanceId -> String -> a -> PABAction t env (Maybe NotificationError) Source #

Call a named endpoint on a contract instance. Waits if the endpoint is not available.

callEndpointOnInstance' :: forall t env a. ToJSON a => ContractInstanceId -> String -> a -> PABAction t env (Maybe NotificationError) Source #

Call a named endpoint on a contract instance. Fails immediately if the endpoint is not available.

payToAddress :: Params -> ContractInstanceId -> Wallet -> Address -> Value -> PABAction t env CardanoTx Source #

Make a payment.

payToPaymentPublicKey :: Params -> ContractInstanceId -> Wallet -> PaymentPubKeyHash -> Value -> PABAction t env CardanoTx Source #

Make a payment to a payment public key.

Agent threads

type ContractInstanceEffects t env effs = ContractEffect t ': (ContractStore t ': (WalletEffect ': (ChainIndexQueryEffect ': (NodeClientEffect ': (UUIDEffect ': (LogMsg TxBalanceMsg ': (LogMsg RequestHandlerLogMsg ': (LogMsg (ContractInstanceMsg t) ': (LogObserve (LogMessage Text) ': (LogMsg Text ': (Error PABError ': (TimeEffect ': (Reader BlockchainEnv ': (Reader InstancesState ': (Reader (PABEnvironment t env) ': (Reader Wallet ': effs)))))))))))))))) Source #

Effects available to contract instances with access to external services.

handleAgentThread :: forall t env a. Wallet -> Maybe ContractInstanceId -> Eff (ContractInstanceEffects t env '[IO]) a -> PABAction t env a Source #

Handle an action with ContractInstanceEffects in the context of a wallet.

stopInstance :: forall t env. ContractInstanceId -> PABAction t env () Source #

Stop the instance.

removeInstance :: forall t env. ContractInstanceId -> PABAction t env () Source #

Delete the instance from the InstancesState of the PABEnvironment and from InMemInstances / Beam db.

instanceActivity :: forall t env. ContractInstanceId -> PABAction t env Activity Source #

The Activity of the instance.

Querying the state

instanceState :: forall t env. Wallet -> ContractInstanceId -> PABAction t env (State t) Source #

Get the current state of the contract instance.

instanceStateInternal :: forall t env. ContractInstanceId -> PABAction t env InstanceState Source #

The InstanceState for the instance. Throws a ContractInstanceNotFound error if the instance does not exist.

observableState :: forall t env. ContractInstanceId -> PABAction t env (STM Value) Source #

An STM transaction that returns the observable state of the contract instance.

waitForState :: forall t env a. (Value -> Maybe a) -> ContractInstanceId -> PABAction t env a Source #

Wait until the observable state of the instance matches a predicate.

waitForInstanceState :: forall t env. (InstanceState -> STM (Maybe ContractActivityStatus)) -> ContractInstanceId -> PABAction t env ContractActivityStatus Source #

Wait until the instance state of the instance satisfies a predicate and returns the activity status

waitForInstanceStateWithResult :: forall t env. ContractInstanceId -> PABAction t env ContractActivityStatus Source #

Wait until the instance state is updated with a response form an invoked endpoint. Note that the waiting is performed only when a contract is expected to end with a Done status, i.e., no open endpoints available after invocation.

waitForTxStatusChange :: forall t env. TxId -> PABAction t env TxStatus Source #

Wait for the transaction to be confirmed on the blockchain.

waitForTxOutStatusChange :: forall t env. TxOutRef -> PABAction t env TxOutStatus Source #

Wait for the transaction output to be confirmed on the blockchain.

activeEndpoints :: forall t env. ContractInstanceId -> PABAction t env (STM [OpenEndpoint]) Source #

The list of endpoints that are currently open

waitForEndpoint :: forall t env. ContractInstanceId -> String -> PABAction t env () Source #

Wait until the endpoint becomes active.

yieldedExportTxs :: forall t env. ContractInstanceId -> PABAction t env [ExportTx] Source #

Get exported transactions waiting to be balanced, signed and submitted by an external client.

currentSlot :: forall t env. PABAction t env (STM Slot) Source #

waitUntilSlot :: forall t env. Slot -> PABAction t env () Source #

Wait until the target slot number has been reached relative to the current slot.

waitNSlots :: forall t env. Int -> PABAction t env () Source #

Wait for a certain number of slots relative to the current slot.

activeContracts :: forall t env. PABAction t env (Set ContractInstanceId) Source #

The set of all active contracts.

finalResult :: forall t env. ContractInstanceId -> PABAction t env (STM (Maybe Value)) Source #

The final result of the instance (waits until it is available)

waitUntilFinished :: forall t env. ContractInstanceId -> PABAction t env (Maybe Value) Source #

Wait until the contract is done, then return the error (if any)

valueAt :: Wallet -> PABAction t env Value Source #

The value in a wallet.

TODO: Change from Wallet to Address (see SCP-2208).

askUserEnv :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Eff effs env Source #

Read the env from the environment

askBlockchainEnv :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Eff effs BlockchainEnv Source #

Read the BlockchainEnv from the environment

askInstancesState :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Eff effs InstancesState Source #

Read the InstancesState from the environment

instancesWithStatuses :: forall t env. PABAction t env (Map ContractInstanceId ContractActivityStatus) Source #

Run PAB effects in separate threads

newtype PABRunner t env Source #

A handler for PABAction types.

Constructors

PABRunner 

Fields

pabRunner :: forall t env. PABAction t env (PABRunner t env) Source #

Get a PABRunner that uses the current environment.

Effect handlers

handleMappedReader :: forall f g effs. Member (Reader f) effs => (f -> g) -> Reader g ~> Eff effs Source #

handleUserEnvReader :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Reader env ~> Eff effs Source #

handleBlockchainEnvReader :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Reader BlockchainEnv ~> Eff effs Source #

handleInstancesStateReader :: forall t env effs. Member (Reader (PABEnvironment t env)) effs => Reader InstancesState ~> Eff effs Source #

timed :: forall e effs. (Member (LogMsg (EmulatorTimeEvent e)) effs, Member TimeEffect effs) => LogMsg e ~> Eff effs Source #

Annotate log messages with the current slot number.