| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Plutus.Contract.StateMachine
Synopsis
- data StateMachineClient s i = StateMachineClient {
- scInstance :: StateMachineInstance s i
- scChooser :: [OnChainState s i] -> Either SMContractError (OnChainState s i)
- data TxConstraints i o
- data SMContractError
- class AsSMContractError r where
- data StateMachine s i = StateMachine {
- smTransition :: State s -> i -> Maybe (TxConstraints Void Void, State s)
- smFinal :: s -> Bool
- smCheck :: s -> i -> ScriptContext -> Bool
- smThreadToken :: Maybe ThreadToken
- data StateMachineInstance s i = StateMachineInstance {
- stateMachine :: StateMachine s i
- typedValidator :: TypedValidator (StateMachine s i)
- data State s = State {
- stateData :: s
- stateValue :: Value
- newtype OnChainState s i = OnChainState {
- ocsTxOutRef :: TypedScriptTxOutRef (StateMachine s i)
- data WaitingResult t i s
- = Timeout t
- | ContractEnded i
- | Transition i s
- | InitialState s
- data InvalidTransition s i = InvalidTransition {}
- data TransitionResult s i
- = TransitionFailure (InvalidTransition s i)
- | TransitionSuccess s
- data ThreadToken = ThreadToken TxOutRef CurrencySymbol
- mkValidator :: forall s i. ToData s => StateMachine s i -> ValidatorType (StateMachine s i)
- mkStateMachine :: Maybe ThreadToken -> (State s -> i -> Maybe (TxConstraints Void Void, State s)) -> (s -> Bool) -> StateMachine s i
- mkStateMachineClient :: forall state input. StateMachineInstance state input -> StateMachineClient state input
- defaultChooser :: forall state input. [OnChainState state input] -> Either SMContractError (OnChainState state input)
- getStates :: forall s i. (FromData s, ToData s) => StateMachineInstance s i -> Map TxOutRef DecoratedTxOut -> [OnChainState s i]
- runGuardedStep :: forall w a e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) => StateMachineClient state input -> input -> (UnbalancedTx -> state -> state -> Maybe a) -> Contract w schema e (Either a (TransitionResult state input))
- runStep :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) => StateMachineClient state input -> input -> Contract w schema e (TransitionResult state input)
- runInitialise :: forall w e state schema input. (FromData state, ToData state, ToData input, AsSMContractError e) => StateMachineClient state input -> state -> Value -> Contract w schema e state
- runGuardedStepWith :: forall w a e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) => ScriptLookups (StateMachine state input) -> TxConstraints input state -> StateMachineClient state input -> input -> (UnbalancedTx -> state -> state -> Maybe a) -> Contract w schema e (Either a (TransitionResult state input))
- runStepWith :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) => ScriptLookups (StateMachine state input) -> TxConstraints input state -> StateMachineClient state input -> input -> Contract w schema e (TransitionResult state input)
- runInitialiseWith :: forall w e state schema input. (FromData state, ToData state, ToData input, AsSMContractError e) => ScriptLookups (StateMachine state input) -> TxConstraints input state -> StateMachineClient state input -> state -> Value -> Contract w schema e state
- getThreadToken :: AsSMContractError e => Contract w schema e ThreadToken
- getOnChainState :: (AsSMContractError e, FromData state, ToData state) => StateMachineClient state i -> Contract w schema e (Maybe (OnChainState state i, Map TxOutRef DecoratedTxOut))
- getStateData :: OnChainState s i -> s
- waitForUpdate :: forall state i w schema e. (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> Contract w schema e (Maybe (OnChainState state i))
- waitForUpdateUntilSlot :: (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> Slot -> Contract w schema e (WaitingResult Slot i state)
- waitForUpdateUntilTime :: (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> POSIXTime -> Contract w schema e (WaitingResult POSIXTime i state)
- waitForUpdateTimeout :: forall state i t w schema e. (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> Promise w schema e t -> Contract w schema e (Promise w schema e (WaitingResult t i (OnChainState state i)))
- data StateMachineTransition state input = StateMachineTransition {
- smtConstraints :: TxConstraints input state
- smtOldState :: State state
- smtNewState :: State state
- smtLookups :: ScriptLookups (StateMachine state input)
- mkStep :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state) => StateMachineClient state input -> input -> Contract w schema e (Either (InvalidTransition state input) (StateMachineTransition state input))
- data Void
Documentation
To write your contract as a state machine you need
* Two types state and input for the state and inputs of the machine
* A 'SM.StateMachineInstance state input' describing the transitions and
checks of the state machine (this is the on-chain code)
* A 'StateMachineClient state input' with the state machine instance and
an allocation function
In many cases it is enough to define the transition function
t :: (state, Value) -> input -> Maybe (TxConstraints state) and use
mkStateMachine and mkStateMachineClient to get the client.
You can then use runInitialise and runStep to initialise and transition
the state machine. runStep gets the current state from the utxo set and
makes the transition to the next state using the given input and taking care
of all payments.
data StateMachineClient s i Source #
Client-side definition of a state machine.
Constructors
| StateMachineClient | |
Fields
| |
data TxConstraints i o Source #
Restrictions placed on the allocation of funds to outputs of transactions.
Instances
data SMContractError Source #
Instances
class AsSMContractError r where Source #
Minimal complete definition
Methods
_SMContractError :: Prism' r SMContractError Source #
_ChooserError :: Prism' r Text Source #
_UnableToExtractTransition :: Prism' r () Source #
Instances
data StateMachine s i Source #
Specification of a state machine, consisting of a transition function that determines the next state from the current state and an input, and a checking function that checks the validity of the transition in the context of the current transaction.
Constructors
| StateMachine | |
Fields
| |
Instances
| ValidatorTypes (StateMachine s i) Source # | |
Defined in Plutus.Contract.StateMachine.OnChain Associated Types type RedeemerType (StateMachine s i) Source # type DatumType (StateMachine s i) Source # | |
| type RedeemerType (StateMachine s i) Source # | |
Defined in Plutus.Contract.StateMachine.OnChain | |
| type DatumType (StateMachine s i) Source # | |
Defined in Plutus.Contract.StateMachine.OnChain | |
data StateMachineInstance s i Source #
Constructors
| StateMachineInstance | |
Fields
| |
Constructors
| State | |
Fields
| |
Instances
| Eq s => Eq (State s) Source # | |
| Show s => Show (State s) Source # | |
| Generic (State s) Source # | |
| ToJSON s => ToJSON (State s) Source # | |
| FromJSON s => FromJSON (State s) Source # | |
| type Rep (State s) Source # | |
Defined in Plutus.Contract.StateMachine.OnChain type Rep (State s) = D1 ('MetaData "State" "Plutus.Contract.StateMachine.OnChain" "plutus-contract-1.1.0.0-KZTRXOViW1GCXNPMdYqx30" 'False) (C1 ('MetaCons "State" 'PrefixI 'True) (S1 ('MetaSel ('Just "stateData") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 s) :*: S1 ('MetaSel ('Just "stateValue") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Value))) | |
newtype OnChainState s i Source #
Typed representation of the on-chain state of a state machine instance
Constructors
| OnChainState | |
Fields
| |
data WaitingResult t i s Source #
The outcome of waitForUpdateTimeout
Constructors
| Timeout t | The timeout happened before any change of the on-chain state was detected |
| ContractEnded i | The state machine instance ended |
| Transition i s | The state machine instance transitioned to a new state |
| InitialState s | The state machine instance was initialised |
Instances
data InvalidTransition s i Source #
An invalid transition
Constructors
| InvalidTransition | |
Instances
data TransitionResult s i Source #
Result of an attempted transition
Constructors
| TransitionFailure (InvalidTransition s i) | The transition is not allowed |
| TransitionSuccess s | The transition is allowed and results in a new state |
data ThreadToken Source #
Constructors
| ThreadToken TxOutRef CurrencySymbol |
Instances
Constructing the machine instance
mkValidator :: forall s i. ToData s => StateMachine s i -> ValidatorType (StateMachine s i) Source #
Turn a state machine into a validator script.
mkStateMachine :: Maybe ThreadToken -> (State s -> i -> Maybe (TxConstraints Void Void, State s)) -> (s -> Bool) -> StateMachine s i Source #
A state machine that does not perform any additional checks on the
ScriptContext (beyond enforcing the constraints)
Constructing the state machine client
mkStateMachineClient :: forall state input. StateMachineInstance state input -> StateMachineClient state input Source #
A state machine client with the defaultChooser function
defaultChooser :: forall state input. [OnChainState state input] -> Either SMContractError (OnChainState state input) Source #
A state chooser function that fails if confronted with anything other than exactly one output
getStates :: forall s i. (FromData s, ToData s) => StateMachineInstance s i -> Map TxOutRef DecoratedTxOut -> [OnChainState s i] Source #
Running the state machine
Arguments
| :: forall w a e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) | |
| => StateMachineClient state input | The state machine |
| -> input | The input to apply to the state machine |
| -> (UnbalancedTx -> state -> state -> Maybe a) | The guard to check before running the step |
| -> Contract w schema e (Either a (TransitionResult state input)) |
Arguments
| :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) | |
| => StateMachineClient state input | The state machine |
| -> input | The input to apply to the state machine |
| -> Contract w schema e (TransitionResult state input) |
Run one step of a state machine, returning the new state.
Arguments
| :: forall w e state schema input. (FromData state, ToData state, ToData input, AsSMContractError e) | |
| => StateMachineClient state input | The state machine |
| -> state | The initial state |
| -> Value | The value locked by the contract at the beginning |
| -> Contract w schema e state |
Initialise a state machine
Arguments
| :: forall w a e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) | |
| => ScriptLookups (StateMachine state input) | Additional lookups |
| -> TxConstraints input state | Additional constraints |
| -> StateMachineClient state input | The state machine |
| -> input | The input to apply to the state machine |
| -> (UnbalancedTx -> state -> state -> Maybe a) | The guard to check before running the step |
| -> Contract w schema e (Either a (TransitionResult state input)) |
The same as runGuardedStep but we can supply additional constraints and lookups for transaction.
Arguments
| :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state, ToData input) | |
| => ScriptLookups (StateMachine state input) | Additional lookups |
| -> TxConstraints input state | Additional constraints |
| -> StateMachineClient state input | The state machine |
| -> input | The input to apply to the state machine |
| -> Contract w schema e (TransitionResult state input) |
Run one step of a state machine, returning the new state. We can supply additional constraints and lookups for transaction.
Arguments
| :: forall w e state schema input. (FromData state, ToData state, ToData input, AsSMContractError e) | |
| => ScriptLookups (StateMachine state input) | Additional lookups |
| -> TxConstraints input state | Additional constraints |
| -> StateMachineClient state input | The state machine |
| -> state | The initial state |
| -> Value | The value locked by the contract at the beginning |
| -> Contract w schema e state |
Initialise a state machine and supply additional constraints and lookups for transaction.
getThreadToken :: AsSMContractError e => Contract w schema e ThreadToken Source #
Create a thread token. The thread token contains a reference to an unspent output of the wallet,
so it needs to used with mkStateMachine immediately, and the machine must be initialised,
to prevent the output from getting spent in the mean time.
getOnChainState :: (AsSMContractError e, FromData state, ToData state) => StateMachineClient state i -> Contract w schema e (Maybe (OnChainState state i, Map TxOutRef DecoratedTxOut)) Source #
Get the current on-chain state of the state machine instance.
Return Nothing if there is no state on chain.
Throws an SMContractError if the number of outputs at the machine address is greater than one.
getStateData :: OnChainState s i -> s Source #
waitForUpdate :: forall state i w schema e. (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> Contract w schema e (Maybe (OnChainState state i)) Source #
Wait until the on-chain state of the state machine instance has changed,
and return the new state, or return Nothing if the instance has been
terminated. If waitForUpdate is called before the instance has even
started then it returns the first state of the instance as soon as it
has started.
waitForUpdateUntilSlot :: (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> Slot -> Contract w schema e (WaitingResult Slot i state) Source #
Wait for the on-chain state of the state machine instance to change until timeoutSlot,
and return the new state, or return ContractEnded if the instance has been
terminated. If waitForUpdate is called before the instance has even
started then it returns the first state of the instance as soon as it
has started.
waitForUpdateUntilTime :: (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) => StateMachineClient state i -> POSIXTime -> Contract w schema e (WaitingResult POSIXTime i state) Source #
Same as waitForUpdateUntilSlot, but works with POSIXTime instead.
Arguments
| :: forall state i t w schema e. (AsSMContractError e, AsContractError e, FromData state, ToData state, FromData i) | |
| => StateMachineClient state i | The state machine client |
| -> Promise w schema e t | The timeout |
| -> Contract w schema e (Promise w schema e (WaitingResult t i (OnChainState state i))) |
Construct a Promise that waits for an update to the state machine's
on-chain state, or a user-defined timeout (whichever happens first).
Lower-level API
data StateMachineTransition state input Source #
Constraints & lookups needed to transition a state machine instance
Constructors
| StateMachineTransition | |
Fields
| |
mkStep :: forall w e state schema input. (AsSMContractError e, FromData state, ToData state) => StateMachineClient state input -> input -> Contract w schema e (Either (InvalidTransition state input) (StateMachineTransition state input)) Source #
Given a state machine client and an input to apply to
the client's state machine instance, compute the StateMachineTransition
that can produce an actual transaction performing the transition
Re-exports
Uninhabited data type
Since: base-4.8.0.0
Instances
| Eq Void | Since: base-4.8.0.0 |
| Data Void | Since: base-4.8.0.0 |
Defined in Data.Void Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Void -> c Void Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Void Source # toConstr :: Void -> Constr Source # dataTypeOf :: Void -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Void) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Void) Source # gmapT :: (forall b. Data b => b -> b) -> Void -> Void Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Void -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Void -> r Source # gmapQ :: (forall d. Data d => d -> u) -> Void -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> Void -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Void -> m Void Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Void -> m Void Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Void -> m Void Source # | |
| Ord Void | Since: base-4.8.0.0 |
| Read Void | Reading a Since: base-4.8.0.0 |
| Show Void | Since: base-4.8.0.0 |
| Ix Void | Since: base-4.8.0.0 |
Defined in Data.Void | |
| Generic Void | Since: base-4.8.0.0 |
| Semigroup Void | Since: base-4.9.0.0 |
| NFData Void | Since: deepseq-1.4.0.0 |
Defined in Control.DeepSeq | |
| Hashable Void | |
| ToJSON Void | |
| FromJSON Void | |
| Exception Void | Since: base-4.8.0.0 |
Defined in Data.Void Methods toException :: Void -> SomeException Source # fromException :: SomeException -> Maybe Void Source # displayException :: Void -> String Source # | |
| FromCBOR Void | |
| Buildable Void | |
| ToFormKey Void | |
| FromFormKey Void | |
Defined in Web.Internal.FormUrlEncoded | |
| ToHttpApiData Void | |
Defined in Web.Internal.HttpApiData Methods toUrlPiece :: Void -> Text Source # toEncodedUrlPiece :: Void -> Builder Source # toHeader :: Void -> ByteString Source # toQueryParam :: Void -> Text Source # | |
| FromHttpApiData Void | Parsing a |
Defined in Web.Internal.HttpApiData | |
| ShowErrorComponent Void | |
Defined in Text.Megaparsec.Error | |
| NoThunks Void | |
| Pretty Void | Finding a good example for printing something that does not exist is hard, so here is an example of printing a list full of nothing.
|
| Serialise Void | Since: serialise-0.2.4.0 |
| ValidatorTypes Void | |
Defined in Plutus.Script.Utils.Typed | |
| UnsafeFromData Void | |
Defined in PlutusTx.IsData.Class Methods | |
| FromData Void | |
Defined in PlutusTx.IsData.Class Methods fromBuiltinData :: BuiltinData -> Maybe Void Source # | |
| ToData Void | |
Defined in PlutusTx.IsData.Class Methods toBuiltinData :: Void -> BuiltinData Source # | |
| Lift Void | Since: template-haskell-2.15.0.0 |
| PrettyDefaultBy config Void => PrettyBy config Void |
|
| DefaultPrettyBy config Void | |
Defined in Text.PrettyBy.Internal Methods defaultPrettyBy :: config -> Void -> Doc ann Source # defaultPrettyListBy :: config -> [Void] -> Doc ann Source # | |
| FunctorWithIndex Void (V1 :: Type -> Type) | |
| FunctorWithIndex Void (U1 :: Type -> Type) | |
| FunctorWithIndex Void (Proxy :: Type -> Type) | |
| FoldableWithIndex Void (V1 :: Type -> Type) | |
Defined in Control.Lens.Indexed | |
| FoldableWithIndex Void (U1 :: Type -> Type) | |
Defined in Control.Lens.Indexed | |
| FoldableWithIndex Void (Proxy :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods ifoldMap :: Monoid m => (Void -> a -> m) -> Proxy a -> m Source # ifolded :: IndexedFold Void (Proxy a) a Source # ifoldr :: (Void -> a -> b -> b) -> b -> Proxy a -> b Source # ifoldl :: (Void -> b -> a -> b) -> b -> Proxy a -> b Source # ifoldr' :: (Void -> a -> b -> b) -> b -> Proxy a -> b Source # ifoldl' :: (Void -> b -> a -> b) -> b -> Proxy a -> b Source # | |
| TraversableWithIndex Void (V1 :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> V1 a -> f (V1 b) Source # itraversed :: IndexedTraversal Void (V1 a) (V1 b) a b Source # | |
| TraversableWithIndex Void (U1 :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> U1 a -> f (U1 b) Source # itraversed :: IndexedTraversal Void (U1 a) (U1 b) a b Source # | |
| TraversableWithIndex Void (Proxy :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> Proxy a -> f (Proxy b) Source # itraversed :: IndexedTraversal Void (Proxy a) (Proxy b) a b Source # | |
| FunctorWithIndex Void (Const e :: Type -> Type) | |
| FunctorWithIndex Void (Constant e :: Type -> Type) | |
| FoldableWithIndex Void (Const e :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods ifoldMap :: Monoid m => (Void -> a -> m) -> Const e a -> m Source # ifolded :: IndexedFold Void (Const e a) a Source # ifoldr :: (Void -> a -> b -> b) -> b -> Const e a -> b Source # ifoldl :: (Void -> b -> a -> b) -> b -> Const e a -> b Source # ifoldr' :: (Void -> a -> b -> b) -> b -> Const e a -> b Source # ifoldl' :: (Void -> b -> a -> b) -> b -> Const e a -> b Source # | |
| FoldableWithIndex Void (Constant e :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods ifoldMap :: Monoid m => (Void -> a -> m) -> Constant e a -> m Source # ifolded :: IndexedFold Void (Constant e a) a Source # ifoldr :: (Void -> a -> b -> b) -> b -> Constant e a -> b Source # ifoldl :: (Void -> b -> a -> b) -> b -> Constant e a -> b Source # ifoldr' :: (Void -> a -> b -> b) -> b -> Constant e a -> b Source # ifoldl' :: (Void -> b -> a -> b) -> b -> Constant e a -> b Source # | |
| TraversableWithIndex Void (Const e :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> Const e a -> f (Const e b) Source # itraversed :: IndexedTraversal Void (Const e a) (Const e b) a b Source # | |
| TraversableWithIndex Void (Constant e :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> Constant e a -> f (Constant e b) Source # itraversed :: IndexedTraversal Void (Constant e a) (Constant e b) a b Source # | |
| FunctorWithIndex Void (K1 i c :: Type -> Type) | |
| FoldableWithIndex Void (K1 i c :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods ifoldMap :: Monoid m => (Void -> a -> m) -> K1 i c a -> m Source # ifolded :: IndexedFold Void (K1 i c a) a Source # ifoldr :: (Void -> a -> b -> b) -> b -> K1 i c a -> b Source # ifoldl :: (Void -> b -> a -> b) -> b -> K1 i c a -> b Source # ifoldr' :: (Void -> a -> b -> b) -> b -> K1 i c a -> b Source # ifoldl' :: (Void -> b -> a -> b) -> b -> K1 i c a -> b Source # | |
| TraversableWithIndex Void (K1 i c :: Type -> Type) | |
Defined in Control.Lens.Indexed Methods itraverse :: Applicative f => (Void -> a -> f b) -> K1 i c a -> f (K1 i c b) Source # itraversed :: IndexedTraversal Void (K1 i c a) (K1 i c b) a b Source # | |
| type Rep Void | |
| type Code Void | |
Defined in Generics.SOP.Instances | |
| type DatatypeInfoOf Void | |
Defined in Generics.SOP.Instances type DatatypeInfoOf Void = 'ADT "Data.Void" "Void" ('[] :: [ConstructorInfo]) ('[] :: [[StrictnessInfo]]) | |
| type RedeemerType Void | |
Defined in Plutus.Script.Utils.Typed | |
| type DatumType Void | |
Defined in Plutus.Script.Utils.Typed | |