Safe Haskell	None
Language	Haskell2010

Plutus.PAB.Core.ContractInstance.STM

Contents

State of all running contract instances

Synopsis

data BlockchainEnv = BlockchainEnv {
- beRollbackHistory :: Maybe Int
- beCurrentSlot :: TVar Slot
- beLastSyncedBlockSlot :: TVar Slot
- beLastSyncedBlockNo :: TVar BlockNumber
- beTxChanges :: Either ( TVar ( UtxoIndex TxIdState )) ( IORef TCSIndex )
- beTxOutChanges :: TVar ( UtxoIndex TxOutBalance )
- beParams :: Params
}
emptyBlockchainEnv :: Maybe Int -> Params -> STM BlockchainEnv
awaitSlot :: Slot -> BlockchainEnv -> STM Slot
awaitTime :: POSIXTime -> BlockchainEnv -> STM POSIXTime
awaitEndpointResponse :: Request ActiveEndpoint -> InstanceState -> STM (EndpointValue Value )
waitForTxStatusChange :: TxStatus -> TxId -> BlockchainEnv -> STM TxStatus
updateTxChangesR :: Either ( TVar ( UtxoIndex TxIdState )) ( IORef TCSIndex ) -> ( TCSIndex -> IO TCSIndex ) -> IO ()
waitForTxOutStatusChange :: TxOutStatus -> TxOutRef -> BlockchainEnv -> STM TxOutStatus
currentSlot :: BlockchainEnv -> STM Slot
lastSyncedBlockSlot :: BlockchainEnv -> STM Slot
data InstanceState = InstanceState {
- issEndpoints :: TVar ( Map (RequestID, IterationID ) OpenEndpoint )
- issStatus :: TVar Activity
- issObservableState :: TVar ( Maybe Value )
- issStop :: TMVar ()
- issTxOutRefs :: TVar ( Map (RequestID, IterationID ) OpenTxOutSpentRequest )
- issAddressRefs :: TVar ( Map (RequestID, IterationID ) OpenTxOutProducedRequest )
- issYieldedExportTxs :: TVar [ ExportTx ]
}
emptyInstanceState :: STM InstanceState
data OpenEndpoint = OpenEndpoint {
- oepName :: ActiveEndpoint
- oepResponse :: TMVar (EndpointValue Value )
}
data OpenTxOutProducedRequest = OpenTxOutProducedRequest {
- otxAddress :: CardanoAddress
- otxProducingTxns :: TMVar ( NonEmpty ChainIndexTx )
}
data OpenTxOutSpentRequest = OpenTxOutSpentRequest {
- osrOutRef :: TxOutRef
- osrSpendingTx :: TMVar ChainIndexTx
}
clearEndpoints :: InstanceState -> STM ()
addEndpoint :: Request ActiveEndpoint -> InstanceState -> STM ()
addUtxoSpentReq :: Request TxOutRef -> InstanceState -> STM ()
waitForUtxoSpent :: Request TxOutRef -> InstanceState -> STM ChainIndexTx
addUtxoProducedReq :: Request CardanoAddress -> InstanceState -> STM ()
waitForUtxoProduced :: Request CardanoAddress -> InstanceState -> STM ( NonEmpty ChainIndexTx )
setActivity :: Activity -> InstanceState -> STM ()
setObservableState :: Value -> InstanceState -> STM ()
openEndpoints :: InstanceState -> STM ( Map (RequestID, IterationID ) OpenEndpoint )
callEndpoint :: OpenEndpoint -> EndpointValue Value -> STM ()
finalResult :: InstanceState -> STM ( Maybe Value )
data Activity
- = Active
- | Stopped
- | Done ( Maybe Value )
data InstancesState
emptyInstancesState :: IO InstancesState
insertInstance :: ContractInstanceId -> InstanceState -> InstancesState -> IO ()
removeInstance :: ContractInstanceId -> InstancesState -> IO ()
callEndpointOnInstance :: InstancesState -> EndpointDescription -> Value -> ContractInstanceId -> IO ( STM ( Maybe NotificationError))
callEndpointOnInstanceTimeout :: TMVar () -> InstancesState -> EndpointDescription -> Value -> ContractInstanceId -> IO ( STM ( Maybe NotificationError))
observableContractState :: InstanceState -> STM Value
yieldedExportTxs :: InstanceState -> STM [ ExportTx ]
instanceState :: ContractInstanceId -> InstancesState -> IO ( Maybe InstanceState )
instanceIDs :: InstancesState -> IO ( Set ContractInstanceId )
instancesWithStatuses :: InstancesState -> IO ( STM ( Map ContractInstanceId ContractActivityStatus))
instancesClientEnv :: InstancesState -> IO ( STM InstanceClientEnv )
data InstanceClientEnv = InstanceClientEnv {
- ceUtxoSpentRequests :: Map TxOutRef [ OpenTxOutSpentRequest ]
- ceUtxoProducedRequests :: Map CardanoAddress [ OpenTxOutProducedRequest ]
}

Documentation

data BlockchainEnv Source #

Data about the blockchain that contract instances may be interested in.

Constructors

BlockchainEnv

Fields

beRollbackHistory :: Maybe Int

How much history do we retain in the environment. Zero signifies no trimming is done.
beCurrentSlot :: TVar Slot

Actual current slot
beLastSyncedBlockSlot :: TVar Slot

Slot of the last synced block from startNodeClient
beLastSyncedBlockNo :: TVar BlockNumber

Last synced block number from startNodeClient .
beTxChanges :: Either ( TVar ( UtxoIndex TxIdState )) ( IORef TCSIndex )

Map holding metadata which determines the status of transactions.
beTxOutChanges :: TVar ( UtxoIndex TxOutBalance )

Map holding metadata which determines the status of transaction outputs.
beParams :: Params

The set of parameters, like protocol parameters and slot configuration.

emptyBlockchainEnv :: Maybe Int -> Params -> STM BlockchainEnv Source #

Initialise an empty BlockchainEnv value

awaitSlot :: Slot -> BlockchainEnv -> STM Slot Source #

Wait until the current slot is greater than or equal to the target slot, then return the current slot.

awaitTime :: POSIXTime -> BlockchainEnv -> STM POSIXTime Source #

Wait until the current time is greater than or equal to the target time, then return the current time.

awaitEndpointResponse :: Request ActiveEndpoint -> InstanceState -> STM (EndpointValue Value ) Source #

Wait for an endpoint response.

waitForTxStatusChange :: TxStatus -> TxId -> BlockchainEnv -> STM TxStatus Source #

Wait for the status of a transaction to change.

updateTxChangesR :: Either ( TVar ( UtxoIndex TxIdState )) ( IORef TCSIndex ) -> ( TCSIndex -> IO TCSIndex ) -> IO () Source #

waitForTxOutStatusChange :: TxOutStatus -> TxOutRef -> BlockchainEnv -> STM TxOutStatus Source #

Wait for the status of a transaction output to change.

currentSlot :: BlockchainEnv -> STM Slot Source #

The current slot number

lastSyncedBlockSlot :: BlockchainEnv -> STM Slot Source #

data InstanceState Source #

The state of an active contract instance.

Constructors

InstanceState

Fields

issEndpoints :: TVar ( Map (RequestID, IterationID ) OpenEndpoint )

Open endpoints that can be responded to.
issStatus :: TVar Activity

Whether the instance is still running.
issObservableState :: TVar ( Maybe Value )

Serialised observable state of the contract instance (if available)
issStop :: TMVar ()

Stop the instance if a value is written into the TMVar.
issTxOutRefs :: TVar ( Map (RequestID, IterationID ) OpenTxOutSpentRequest )
issAddressRefs :: TVar ( Map (RequestID, IterationID ) OpenTxOutProducedRequest )
issYieldedExportTxs :: TVar [ ExportTx ]

Partial tx that needs to be balanced, signed and submitted by an external agent.

emptyInstanceState :: STM InstanceState Source #

An InstanceState value with empty fields

data OpenEndpoint Source #

An open endpoint that can be responded to.

Constructors

OpenEndpoint
Fields oepName :: ActiveEndpoint Name of the endpoint oepResponse :: TMVar (EndpointValue Value ) A place to write the response to.

data OpenTxOutProducedRequest Source #

Constructors

OpenTxOutProducedRequest
Fields otxAddress :: CardanoAddress `Address` that the contract instance is watching (TODO: Should be ViewAddress -- SCP-2628) otxProducingTxns :: TMVar ( NonEmpty ChainIndexTx ) A place to write the producing transactions to

data OpenTxOutSpentRequest Source #

A TxOutRef that a contract instance is watching

Constructors

OpenTxOutSpentRequest
Fields osrOutRef :: TxOutRef The `TxOutRef` that the instance is watching osrSpendingTx :: TMVar ChainIndexTx A place to write the spending transaction to

clearEndpoints :: InstanceState -> STM () Source #

Empty the list of open enpoints that can be called on the instance

addEndpoint :: Request ActiveEndpoint -> InstanceState -> STM () Source #

Add an active endpoint to the instance's list of active endpoints.

addUtxoSpentReq :: Request TxOutRef -> InstanceState -> STM () Source #

Add a new OpenTxOutSpentRequest to the instance's list of utxo spent requests

waitForUtxoSpent :: Request TxOutRef -> InstanceState -> STM ChainIndexTx Source #

addUtxoProducedReq :: Request CardanoAddress -> InstanceState -> STM () Source #

Add a new OpenTxOutProducedRequest to the instance's list of utxo produced requests

waitForUtxoProduced :: Request CardanoAddress -> InstanceState -> STM ( NonEmpty ChainIndexTx ) Source #

setActivity :: Activity -> InstanceState -> STM () Source #

Set the Activity of the instance

setObservableState :: Value -> InstanceState -> STM () Source #

Write a new value into the contract instance's observable state.

openEndpoints :: InstanceState -> STM ( Map (RequestID, IterationID ) OpenEndpoint ) Source #

The list of all endpoints that can be called on the instance

callEndpoint :: OpenEndpoint -> EndpointValue Value -> STM () Source #

Call an endpoint with a JSON value.

finalResult :: InstanceState -> STM ( Maybe Value ) Source #

Return the final state of the contract when it is finished (possibly an error)

data Activity Source #

Whether the contract instance is still waiting for an event.

Constructors

Active
Stopped	Instance was stopped before all requests were handled
Done ( Maybe Value )	Instance finished, possibly with an error

Instances

Instances details

Eq Activity Source #
Instance details Defined in Plutus.PAB.Core.ContractInstance.STM Methods (==) :: Activity -> Activity -> Bool Source # (/=) :: Activity -> Activity -> Bool Source #
Show Activity Source #
Instance details Defined in Plutus.PAB.Core.ContractInstance.STM Methods showsPrec :: Int -> Activity -> ShowS Source # show :: Activity -> String Source # showList :: [ Activity ] -> ShowS Source #

State of all running contract instances

data InstancesState Source #

State of all contract instances that are currently running

emptyInstancesState :: IO InstancesState Source #

Initialise the InstancesState with an empty value

insertInstance :: ContractInstanceId -> InstanceState -> InstancesState -> IO () Source #

Insert an InstanceState value into the InstancesState

removeInstance :: ContractInstanceId -> InstancesState -> IO () Source #

Delete an instance from the InstancesState

callEndpointOnInstance :: InstancesState -> EndpointDescription -> Value -> ContractInstanceId -> IO ( STM ( Maybe NotificationError)) Source #

Call an endpoint on a contract instance. Fail immediately if the endpoint is not active.

callEndpointOnInstanceTimeout :: TMVar () -> InstancesState -> EndpointDescription -> Value -> ContractInstanceId -> IO ( STM ( Maybe NotificationError)) Source #

Call an endpoint on a contract instance. If the endpoint is not active, wait until the TMVar is filled, then fail. (if the endpoint becomes active in the meantime it will be called)

observableContractState :: InstanceState -> STM Value Source #

Get the observable state of the contract instance. Blocks if the state is not available yet.

yieldedExportTxs :: InstanceState -> STM [ ExportTx ] Source #

The list of all partial txs that need to be balanced on the instance.

instanceState :: ContractInstanceId -> InstancesState -> IO ( Maybe InstanceState ) Source #

The InstanceState of the contract instance. Retries if the state can't be found in the map.

instanceIDs :: InstancesState -> IO ( Set ContractInstanceId ) Source #

The IDs of all contract instances

instancesWithStatuses :: InstancesState -> IO ( STM ( Map ContractInstanceId ContractActivityStatus)) Source #

The IDs of contract instances with their statuses

instancesClientEnv :: InstancesState -> IO ( STM InstanceClientEnv ) Source #

data InstanceClientEnv Source #

Events that the contract instances are waiting for, indexed by keys that are readily available in the node client (ie. that can be produced from just a block without any additional information)

Constructors

InstanceClientEnv
Fields ceUtxoSpentRequests :: Map TxOutRef [ OpenTxOutSpentRequest ] ceUtxoProducedRequests :: Map CardanoAddress [ OpenTxOutProducedRequest ]

Instances

Instances details

Semigroup InstanceClientEnv Source #
Instance details Defined in Plutus.PAB.Core.ContractInstance.STM Methods (<>) :: InstanceClientEnv -> InstanceClientEnv -> InstanceClientEnv Source # sconcat :: NonEmpty InstanceClientEnv -> InstanceClientEnv Source # stimes :: Integral b => b -> InstanceClientEnv -> InstanceClientEnv Source #
Monoid InstanceClientEnv Source #
Instance details Defined in Plutus.PAB.Core.ContractInstance.STM Methods mempty :: InstanceClientEnv Source # mappend :: InstanceClientEnv -> InstanceClientEnv -> InstanceClientEnv Source # mconcat :: [ InstanceClientEnv ] -> InstanceClientEnv Source #