hydra-node-0.16.0: The Hydra node
Safe HaskellSafe-Inferred
LanguageGHC2021

Hydra.Chain.Direct.State

Description

Contains the a state-ful interface to transaction construction and observation.

It defines the 'ChainStateType tx' to be used in the Direct layer and it's constituents.

Synopsis

Documentation

class HasKnownUTxO a where Source #

A class for accessing the known UTxO' set in a type. This is useful to get all the relevant UTxO for resolving transaction inputs.

Methods

getKnownUTxO :: a -> UTxO Source #

Instances

Instances details
HasKnownUTxO ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ChainContext -> UTxO Source #

HasKnownUTxO ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ChainState -> UTxO Source #

HasKnownUTxO ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ClosedState -> UTxO Source #

HasKnownUTxO InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: InitialState -> UTxO Source #

HasKnownUTxO OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: OpenState -> UTxO Source #

States & transitions

data ChainStateAt Source #

The chain state used by the Hydra.Chain.Direct implementation. It records the actual ChainState paired with a ChainSlot (used to know up to which point to rewind on rollbacks).

Constructors

ChainStateAt 

Fields

Instances

Instances details
Arbitrary ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser ChainStateAt

parseJSONList :: Value -> Parser [ChainStateAt]

omittedField :: Maybe ChainStateAt

ToJSON ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: ChainStateAt -> Value

toEncoding :: ChainStateAt -> Encoding

toJSONList :: [ChainStateAt] -> Value

toEncodingList :: [ChainStateAt] -> Encoding

omitField :: ChainStateAt -> Bool

Generic ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep ChainStateAt :: Type -> Type Source #

Show ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep ChainStateAt Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep ChainStateAt = D1 ('MetaData "ChainStateAt" "Hydra.Chain.Direct.State" "hydra-node-0.16.0-C0XGScKIquG5I6dPp21445" 'False) (C1 ('MetaCons "ChainStateAt" 'PrefixI 'True) (S1 ('MetaSel ('Just "spendableUTxO") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 UTxO) :*: S1 ('MetaSel ('Just "recordedAt") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe ChainPoint))))

chainSlotFromPoint :: ChainPoint -> ChainSlot Source #

Get a generic ChainSlot from a Cardano ChainPoint. Slot 0 is used for the genesis point.

data ChainState Source #

An enumeration of all possible on-chain states of a Hydra Head, where each case stores the relevant information to construct & observe transactions to other states.

Constructors

Idle

The idle state does not contain any head-specific information and exists to be used as a starting and terminal state.

Initial InitialState 
Open OpenState 
Closed ClosedState 

Instances

Instances details
Arbitrary ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser ChainState

parseJSONList :: Value -> Parser [ChainState]

omittedField :: Maybe ChainState

ToJSON ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: ChainState -> Value

toEncoding :: ChainState -> Encoding

toJSONList :: [ChainState] -> Value

toEncodingList :: [ChainState] -> Encoding

omitField :: ChainState -> Bool

Generic ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep ChainState :: Type -> Type Source #

Show ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

HasKnownUTxO ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ChainState -> UTxO Source #

type Rep ChainState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

initialChainState :: ChainStateType Tx Source #

Defines the starting state of the direct chain layer.

data ChainContext Source #

Read-only chain-specific data. This is different to HydraContext as it only contains data known to single peer.

Constructors

ChainContext 

Instances

Instances details
Arbitrary ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser ChainContext

parseJSONList :: Value -> Parser [ChainContext]

omittedField :: Maybe ChainContext

ToJSON ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: ChainContext -> Value

toEncoding :: ChainContext -> Encoding

toJSONList :: [ChainContext] -> Value

toEncodingList :: [ChainContext] -> Encoding

omitField :: ChainContext -> Bool

Generic ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep ChainContext :: Type -> Type Source #

Show ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

HasKnownUTxO ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ChainContext -> UTxO Source #

type Rep ChainContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep ChainContext = D1 ('MetaData "ChainContext" "Hydra.Chain.Direct.State" "hydra-node-0.16.0-C0XGScKIquG5I6dPp21445" 'False) (C1 ('MetaCons "ChainContext" 'PrefixI 'True) ((S1 ('MetaSel ('Just "networkId") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 NetworkId) :*: S1 ('MetaSel ('Just "ownVerificationKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (VerificationKey PaymentKey))) :*: (S1 ('MetaSel ('Just "ownParty") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Party) :*: S1 ('MetaSel ('Just "scriptRegistry") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ScriptRegistry))))

data InitialState Source #

Constructors

InitialState 

Fields

Instances

Instances details
Arbitrary InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser InitialState

parseJSONList :: Value -> Parser [InitialState]

omittedField :: Maybe InitialState

ToJSON InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: InitialState -> Value

toEncoding :: InitialState -> Encoding

toJSONList :: [InitialState] -> Value

toEncodingList :: [InitialState] -> Encoding

omitField :: InitialState -> Bool

Generic InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep InitialState :: Type -> Type Source #

Show InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

HasKnownUTxO InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: InitialState -> UTxO Source #

type Rep InitialState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep InitialState = D1 ('MetaData "InitialState" "Hydra.Chain.Direct.State" "hydra-node-0.16.0-C0XGScKIquG5I6dPp21445" 'False) (C1 ('MetaCons "InitialState" 'PrefixI 'True) ((S1 ('MetaSel ('Just "initialThreadOutput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 InitialThreadOutput) :*: S1 ('MetaSel ('Just "initialInitials") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [(TxIn, TxOut CtxUTxO)])) :*: (S1 ('MetaSel ('Just "initialCommits") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [(TxIn, TxOut CtxUTxO)]) :*: (S1 ('MetaSel ('Just "headId") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 HeadId) :*: S1 ('MetaSel ('Just "seedTxIn") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TxIn)))))

data OpenState Source #

Instances

Instances details
Arbitrary OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser OpenState

parseJSONList :: Value -> Parser [OpenState]

omittedField :: Maybe OpenState

ToJSON OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: OpenState -> Value

toEncoding :: OpenState -> Encoding

toJSONList :: [OpenState] -> Value

toEncodingList :: [OpenState] -> Encoding

omitField :: OpenState -> Bool

Generic OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep OpenState :: Type -> Type Source #

Show OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

HasKnownUTxO OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: OpenState -> UTxO Source #

type Rep OpenState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep OpenState = D1 ('MetaData "OpenState" "Hydra.Chain.Direct.State" "hydra-node-0.16.0-C0XGScKIquG5I6dPp21445" 'False) (C1 ('MetaCons "OpenState" 'PrefixI 'True) ((S1 ('MetaSel ('Just "openThreadOutput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 OpenThreadOutput) :*: S1 ('MetaSel ('Just "headId") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 HeadId)) :*: (S1 ('MetaSel ('Just "seedTxIn") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TxIn) :*: S1 ('MetaSel ('Just "openUtxoHash") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 UTxOHash))))

data ClosedState Source #

Instances

Instances details
Arbitrary ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

FromJSON ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

parseJSON :: Value -> Parser ClosedState

parseJSONList :: Value -> Parser [ClosedState]

omittedField :: Maybe ClosedState

ToJSON ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

toJSON :: ClosedState -> Value

toEncoding :: ClosedState -> Encoding

toJSONList :: [ClosedState] -> Value

toEncodingList :: [ClosedState] -> Encoding

omitField :: ClosedState -> Bool

Generic ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Associated Types

type Rep ClosedState :: Type -> Type Source #

Show ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Eq ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

HasKnownUTxO ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

Methods

getKnownUTxO :: ClosedState -> UTxO Source #

type Rep ClosedState Source # 
Instance details

Defined in Hydra.Chain.Direct.State

type Rep ClosedState = D1 ('MetaData "ClosedState" "Hydra.Chain.Direct.State" "hydra-node-0.16.0-C0XGScKIquG5I6dPp21445" 'False) (C1 ('MetaCons "ClosedState" 'PrefixI 'True) (S1 ('MetaSel ('Just "closedThreadOutput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ClosedThreadOutput) :*: (S1 ('MetaSel ('Just "headId") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 HeadId) :*: S1 ('MetaSel ('Just "seedTxIn") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TxIn))))

Constructing transactions

initialize Source #

Arguments

:: ChainContext 
-> TxIn

Seed input.

-> [OnChainId]

Verification key hashes of all participants.

-> HeadParameters 
-> Tx 

Construct an init transaction given some general ChainContext, the HeadParameters and a seed TxIn which will be spent.

commit Source #

Arguments

:: ChainContext 
-> HeadId 
-> UTxO

Spendable UTxO'

-> UTxO

UTxO' to commit. All outputs are assumed to be owned by public keys.

-> Either (PostTxError Tx) Tx 

Construct a commit transaction based on known, spendable UTxO and some arbitrary UTxOs to commit. This does look for "our initial output" to spend and check the given UTxO' to be compatible. Hence, this function does fail if already committed or if the head is not initializing.

NOTE: This version of commit does only commit outputs which are held by payment keys. For a variant which supports committing scripts, see commit'.

commit' Source #

Arguments

:: ChainContext 
-> HeadId 
-> UTxO

Spendable UTxO'

-> UTxO' (TxOut CtxUTxO, Witness WitCtxTxIn)

UTxO' to commit, along with witnesses to spend them.

-> Either (PostTxError Tx) Tx 

Construct a commit transaction based on known, spendable UTxO and some arbitrary UTxOs to commit. This does look for "our initial output" to spend and check the given UTxO' to be compatible. Hence, this function does fail if already committed or if the head is not initializing.

NOTE: A simpler variant only supporting pubkey outputs is commit.

abort Source #

Arguments

:: ChainContext 
-> TxIn

Seed TxIn

-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> UTxO

Committed UTxOs to reimburse.

-> Either AbortTxError Tx 

Construct a abort transaction based on known, spendable UTxO. This function looks for head, initial and commit outputs to spend and it will fail if we can't find the head output.

collect Source #

Arguments

:: ChainContext 
-> HeadId 
-> HeadParameters 
-> UTxO

UTxO to be used to collect. Should match whatever is recorded in the commit inputs.

-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> Either CollectTxError Tx 

Construct a collect transaction based on known, spendable UTxO. This function looks for head output and commit outputs to spend and it will fail if we can't find the head output.

close Source #

Arguments

:: ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> HeadId 
-> HeadParameters 
-> ConfirmedSnapshot Tx 
-> SlotNo

Tx validity lower bound

-> PointInTime

Tx validity upper bound

-> Either CloseTxError Tx 

Construct a close transaction based on the OpenState and a confirmed snapshot. - SlotNo parameter will be used as the Tx lower bound. - PointInTime parameter will be used as an upper validity bound and will define the start of the contestation period. NB: lower and upper bound slot difference should not exceed contestation period

contest Source #

Arguments

:: ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> HeadId 
-> ContestationPeriod 
-> ConfirmedSnapshot Tx 
-> PointInTime 
-> Either ContestTxError Tx 

Construct a contest transaction based on the ClosedState and a confirmed snapshot. The given PointInTime will be used as an upper validity bound and needs to be before the deadline.

fanout Source #

Arguments

:: ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> TxIn

Seed TxIn

-> UTxO

Snapshot UTxO to fanout

-> SlotNo

Contestation deadline as SlotNo, used to set lower tx validity bound.

-> Either FanoutTxError Tx 

Construct a fanout transaction based on the ClosedState and off-chain agreed UTxO' set to fan out.

Helpers

utxoOfThisHead :: PolicyId -> UTxO -> UTxO Source #

Observing Transitions

IdleState transitions

observeInit :: ChainContext -> [VerificationKey PaymentKey] -> Tx -> Either NotAnInitReason (OnChainTx Tx, InitialState) Source #

Observe an init transition using a InitialState and observeInitTx.

InitialState transitions

observeCollect :: InitialState -> Tx -> Maybe (OnChainTx Tx, OpenState) Source #

Observe an collect transition using a InitialState and observeCollectComTx. This function checks the head id and ignores if not relevant.

OpenState transitions

observeClose :: OpenState -> Tx -> Maybe (OnChainTx Tx, ClosedState) Source #

Observe a close transition using a OpenState and observeCloseTx. This function checks the head id and ignores if not relevant.

Generators

maxGenParties :: Int Source #

Maximum number of parties used in the generators.

maxGenAssets :: Int Source #

Maximum number of assets (ADA or other tokens) used in the generators.

genChainState :: Gen ChainState Source #

Generate a ChainState within known limits above.

genChainStateWithTx :: Gen (ChainContext, ChainState, Tx, ChainTransition) Source #

Generate a ChainContext and ChainState within the known limits above, along with a transaction that results in a transition away from it.

Warning zone

data HydraContext Source #

Define some global context from which generators can pick values for generation. This allows to write fairly independent generators which however still make sense with one another within the context of a head.

For example, one can generate a head's _party_ from that global list, whereas other functions may rely on all parties and thus, we need both generation to be coherent.

Do not use this in production code, but only for generating test data.

Instances

Instances details
Show HydraContext Source # 
Instance details

Defined in Hydra.Chain.Direct.State

genHydraContext :: Int -> Gen HydraContext Source #

Generate a HydraContext for a arbitrary number of parties, bounded by given maximum.

genHydraContextFor :: Int -> Gen HydraContext Source #

Generate a HydraContext for a given number of parties.

deriveChainContexts :: HydraContext -> Gen [ChainContext] Source #

Get all peer-specific ChainContexts from a HydraContext. NOTE: This assumes that HydraContext has same length $sel:ctxVerificationKeys:HydraContext and $sel:ctxHydraSigningKeys:HydraContext. XXX: This is actually a non-monadic function.

pickChainContext :: HydraContext -> Gen ChainContext Source #

Pick one of the participants and derive the peer-specific ChainContext from a HydraContext. NOTE: This assumes that HydraContext has same length $sel:ctxVerificationKeys:HydraContext and $sel:ctxHydraSigningKeys:HydraContext.

genCommits' :: Gen UTxO -> HydraContext -> Tx -> Gen [Tx] Source #

genCommitFor :: VerificationKey PaymentKey -> Gen UTxO Source #

genCommit :: Gen UTxO Source #

Danger zone

unsafeCommit Source #

Arguments

:: HasCallStack 
=> ChainContext 
-> HeadId 
-> UTxO

Spendable UTxO'

-> UTxO

UTxO' to commit. All outputs are assumed to be owned by public keys.

-> Tx 

unsafeAbort Source #

Arguments

:: HasCallStack 
=> ChainContext 
-> TxIn

Seed TxIn

-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> UTxO

Committed UTxOs to reimburse.

-> Tx 

unsafeClose Source #

Arguments

:: HasCallStack 
=> ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> HeadId 
-> HeadParameters 
-> ConfirmedSnapshot Tx 
-> SlotNo

Tx validity lower bound

-> PointInTime

Tx validity upper bound

-> Tx 

unsafeCollect Source #

Arguments

:: ChainContext 
-> HeadId 
-> HeadParameters 
-> UTxO

UTxO to be used to collect. Should match whatever is recorded in the commit inputs.

-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> Tx 

unsafeContest Source #

Arguments

:: HasCallStack 
=> ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> HeadId 
-> ContestationPeriod 
-> ConfirmedSnapshot Tx 
-> PointInTime 
-> Tx 

unsafeFanout Source #

Arguments

:: HasCallStack 
=> ChainContext 
-> UTxO

Spendable UTxO containing head, initial and commit outputs

-> TxIn

Seed TxIn

-> UTxO

Snapshot UTxO to fanout

-> SlotNo

Contestation deadline as SlotNo, used to set lower tx validity bound.

-> Tx 

Orphan instances

IsChainState Tx Source # 
Instance details

Associated Types

type ChainStateType Tx = (c :: Type) Source #