Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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
- class HasKnownUTxO a where
- getKnownUTxO :: a -> UTxO
- data ChainStateAt = ChainStateAt {
- chainState :: ChainState
- recordedAt :: Maybe ChainPoint
- previous :: Maybe ChainStateAt
- chainSlotFromPoint :: ChainPoint -> ChainSlot
- data ChainTransition
- data ChainState
- data ChainContext = ChainContext {
- networkId :: NetworkId
- peerVerificationKeys :: [VerificationKey PaymentKey]
- ownVerificationKey :: VerificationKey PaymentKey
- ownParty :: Party
- otherParties :: [Party]
- scriptRegistry :: ScriptRegistry
- contestationPeriod :: ContestationPeriod
- allVerificationKeys :: ChainContext -> [VerificationKey PaymentKey]
- data InitialState = InitialState {}
- data OpenState = OpenState {
- openThreadOutput :: OpenThreadOutput
- headId :: HeadId
- seedTxIn :: TxIn
- openUtxoHash :: UTxOHash
- data ClosedState = ClosedState {
- closedThreadOutput :: ClosedThreadOutput
- headId :: HeadId
- seedTxIn :: TxIn
- initialize :: ChainContext -> HeadParameters -> TxIn -> Tx
- commit :: ChainContext -> InitialState -> UTxO' (TxOut CtxUTxO) -> Either (PostTxError Tx) Tx
- commit' :: ChainContext -> InitialState -> UTxO' (TxOut CtxUTxO, Witness WitCtxTxIn) -> Either (PostTxError Tx) Tx
- ownInitial :: ChainContext -> InitialState -> Maybe (TxIn, TxOut CtxUTxO, Hash PaymentKey)
- hasMatchingPT :: InitialState -> Hash PaymentKey -> Value -> Bool
- rejectByronAddress :: UTxO -> Either (PostTxError Tx) ()
- rejectReferenceScripts :: UTxO -> Either (PostTxError Tx) ()
- rejectMoreThanMainnetLimit :: NetworkId -> UTxO -> Either (PostTxError Tx) ()
- abort :: HasCallStack => ChainContext -> InitialState -> UTxO -> Tx
- collect :: ChainContext -> InitialState -> Tx
- close :: ChainContext -> OpenState -> ConfirmedSnapshot Tx -> SlotNo -> PointInTime -> Tx
- contest :: ChainContext -> ClosedState -> ConfirmedSnapshot Tx -> PointInTime -> Tx
- fanout :: ChainContext -> ClosedState -> UTxO -> SlotNo -> Tx
- observeSomeTx :: ChainContext -> ChainState -> Tx -> Maybe (OnChainTx Tx, ChainState)
- observeInit :: ChainContext -> Tx -> Either NotAnInitReason (OnChainTx Tx, InitialState)
- observeCommit :: ChainContext -> InitialState -> Tx -> Maybe (OnChainTx Tx, InitialState)
- observeCollect :: InitialState -> Tx -> Maybe (OnChainTx Tx, OpenState)
- observeAbort :: InitialState -> Tx -> Maybe (OnChainTx Tx)
- observeClose :: OpenState -> Tx -> Maybe (OnChainTx Tx, ClosedState)
- observeContest :: ClosedState -> Tx -> Maybe (OnChainTx Tx, ClosedState)
- observeFanout :: ClosedState -> Tx -> Maybe (OnChainTx Tx)
- maxGenParties :: Int
- maxGenAssets :: Int
- genChainState :: Gen ChainState
- genChainStateWithTx :: Gen (ChainContext, ChainState, Tx, ChainTransition)
- data HydraContext = HydraContext {
- ctxVerificationKeys :: [VerificationKey PaymentKey]
- ctxHydraSigningKeys :: [SigningKey HydraKey]
- ctxNetworkId :: NetworkId
- ctxContestationPeriod :: ContestationPeriod
- ctxScriptRegistry :: ScriptRegistry
- ctxParties :: HydraContext -> [Party]
- ctxHeadParameters :: HydraContext -> HeadParameters
- genHydraContext :: Int -> Gen HydraContext
- genHydraContextFor :: Int -> Gen HydraContext
- deriveChainContexts :: HydraContext -> Gen [ChainContext]
- pickChainContext :: HydraContext -> Gen ChainContext
- genStInitial :: HydraContext -> Gen (ChainContext, InitialState)
- genInitTx :: HydraContext -> Gen Tx
- genCommits :: HydraContext -> Tx -> Gen [Tx]
- genCommits' :: Gen UTxO -> HydraContext -> Tx -> Gen [Tx]
- genCommit :: Gen UTxO
- genCollectComTx :: Gen (ChainContext, [UTxO], InitialState, Tx)
- genCloseTx :: Int -> Gen (ChainContext, OpenState, Tx, ConfirmedSnapshot Tx)
- genContestTx :: Gen (HydraContext, PointInTime, ClosedState, Tx)
- genFanoutTx :: Int -> Int -> Gen (HydraContext, ClosedState, Tx)
- getContestationDeadline :: ClosedState -> UTCTime
- genStOpen :: HydraContext -> Gen (UTxO, OpenState)
- genStClosed :: HydraContext -> UTxO -> Gen (SnapshotNumber, UTxO, ClosedState)
- unsafeCommit :: HasCallStack => ChainContext -> InitialState -> UTxO -> Tx
- unsafeObserveInit :: HasCallStack => ChainContext -> Tx -> InitialState
- unsafeObserveInitAndCommits :: HasCallStack => ChainContext -> Tx -> [Tx] -> ([UTxO], InitialState)
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
HasKnownUTxO ChainContext Source # | |
Defined in Hydra.Chain.Direct.State Methods getKnownUTxO :: ChainContext -> UTxO Source # | |
HasKnownUTxO ChainState Source # | |
Defined in Hydra.Chain.Direct.State Methods getKnownUTxO :: ChainState -> UTxO Source # | |
HasKnownUTxO ClosedState Source # | |
Defined in Hydra.Chain.Direct.State Methods getKnownUTxO :: ClosedState -> UTxO Source # | |
HasKnownUTxO InitialState Source # | |
Defined in Hydra.Chain.Direct.State Methods getKnownUTxO :: InitialState -> UTxO Source # | |
HasKnownUTxO OpenState Source # | |
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
chainSlotFromPoint :: ChainPoint -> ChainSlot Source #
Get a generic ChainSlot
from a Cardano ChainPoint
. Slot 0 is used for
the genesis point.
data ChainTransition Source #
A definition of all transitions between ChainState
s. Enumerable and
bounded to be used as labels for checking coverage.
Instances
Bounded ChainTransition Source # | |
Defined in Hydra.Chain.Direct.State | |
Enum ChainTransition Source # | |
Defined in Hydra.Chain.Direct.State Methods succ :: ChainTransition -> ChainTransition Source # pred :: ChainTransition -> ChainTransition Source # toEnum :: Int -> ChainTransition Source # fromEnum :: ChainTransition -> Int Source # enumFrom :: ChainTransition -> [ChainTransition] Source # enumFromThen :: ChainTransition -> ChainTransition -> [ChainTransition] Source # enumFromTo :: ChainTransition -> ChainTransition -> [ChainTransition] Source # enumFromThenTo :: ChainTransition -> ChainTransition -> ChainTransition -> [ChainTransition] Source # | |
Show ChainTransition Source # | |
Defined in Hydra.Chain.Direct.State | |
Eq ChainTransition Source # | |
Defined in Hydra.Chain.Direct.State Methods (==) :: ChainTransition -> ChainTransition -> Bool Source # (/=) :: ChainTransition -> ChainTransition -> Bool Source # |
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
data ChainContext Source #
Read-only chain-specific data. This is different to HydraContext
as it
only contains data known to single peer.
Constructors
ChainContext | |
Fields
|
Instances
allVerificationKeys :: ChainContext -> [VerificationKey PaymentKey] Source #
Get all cardano verification keys available in the chain context.
data InitialState Source #
Constructors
InitialState | |
Fields
|
Instances
Constructors
OpenState | |
Fields
|
Instances
data ClosedState Source #
Constructors
ClosedState | |
Fields
|
Instances
Constructing transactions
Arguments
:: ChainContext | |
-> HeadParameters | |
-> TxIn | Seed input. |
-> Tx |
Construct an init transaction given some general ChainContext
, the
HeadParameters
and a seed TxIn
which will be spent.
commit :: ChainContext -> InitialState -> UTxO' (TxOut CtxUTxO) -> Either (PostTxError Tx) Tx Source #
Construct a commit transaction based on the InitialState
. 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.
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' :: ChainContext -> InitialState -> UTxO' (TxOut CtxUTxO, Witness WitCtxTxIn) -> Either (PostTxError Tx) Tx Source #
Construct a commit transaction base on the InitialState
and some
arbitrary UTxOs to commit.
NOTE: A simpler variant only supporting pubkey outputs is commit
.
ownInitial :: ChainContext -> InitialState -> Maybe (TxIn, TxOut CtxUTxO, Hash PaymentKey) Source #
hasMatchingPT :: InitialState -> Hash PaymentKey -> Value -> Bool Source #
rejectByronAddress :: UTxO -> Either (PostTxError Tx) () Source #
rejectReferenceScripts :: UTxO -> Either (PostTxError Tx) () Source #
rejectMoreThanMainnetLimit :: NetworkId -> UTxO -> Either (PostTxError Tx) () Source #
Arguments
:: HasCallStack | |
=> ChainContext | |
-> InitialState | |
-> UTxO | Committed UTxOs to reimburse. |
-> Tx |
Construct a collect transaction based on the InitialState
. This will
reimburse all the already committed outputs.
collect :: ChainContext -> InitialState -> Tx Source #
Construct a collect transaction based on the InitialState
. This will know
collect all the committed outputs.
Arguments
:: ChainContext | |
-> OpenState | |
-> ConfirmedSnapshot Tx | |
-> SlotNo |
|
-> PointInTime |
|
-> 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 :: ChainContext -> ClosedState -> ConfirmedSnapshot Tx -> PointInTime -> Tx Source #
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.
Arguments
:: ChainContext | |
-> ClosedState | |
-> UTxO | |
-> SlotNo | Contestation deadline as SlotNo, used to set lower tx validity bound. |
-> Tx |
Construct a fanout transaction based on the ClosedState
and off-chain
agreed UTxO'
set to fan out.
Observing Transitions
observeSomeTx :: ChainContext -> ChainState -> Tx -> Maybe (OnChainTx Tx, ChainState) Source #
Observe a transition without knowing the starting or ending state. This
function should try to observe all relevant transitions given some
ChainState
.
IdleState transitions
observeInit :: ChainContext -> Tx -> Either NotAnInitReason (OnChainTx Tx, InitialState) Source #
Observe an init transition using a InitialState
and observeInitTx
.
InitialState transitions
observeCommit :: ChainContext -> InitialState -> Tx -> Maybe (OnChainTx Tx, InitialState) Source #
Observe an commit transition using a InitialState
and observeCommitTx
.
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.
observeAbort :: InitialState -> Tx -> Maybe (OnChainTx Tx) Source #
Observe an abort transition using a InitialState
and observeAbortTx
.
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.
ClosedState transitions
observeContest :: ClosedState -> Tx -> Maybe (OnChainTx Tx, ClosedState) Source #
Observe a fanout transition using a ClosedState
and observeContestTx
.
This function checks the head id and ignores if not relevant.
observeFanout :: ClosedState -> Tx -> Maybe (OnChainTx Tx) Source #
Observe a fanout transition using a ClosedState
and observeFanoutTx
.
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.
Constructors
HydraContext | |
Fields
|
Instances
Show HydraContext Source # | |
Defined in Hydra.Chain.Direct.State |
ctxParties :: HydraContext -> [Party] Source #
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 ChainContext
s 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
.
genStInitial :: HydraContext -> Gen (ChainContext, InitialState) Source #
genInitTx :: HydraContext -> Gen Tx Source #
genCommits :: HydraContext -> Tx -> Gen [Tx] Source #
genCommits' :: Gen UTxO -> HydraContext -> Tx -> Gen [Tx] Source #
genCollectComTx :: Gen (ChainContext, [UTxO], InitialState, Tx) Source #
genCloseTx :: Int -> Gen (ChainContext, OpenState, Tx, ConfirmedSnapshot Tx) Source #
genContestTx :: Gen (HydraContext, PointInTime, ClosedState, Tx) Source #
genFanoutTx :: Int -> Int -> Gen (HydraContext, ClosedState, Tx) Source #
getContestationDeadline :: ClosedState -> UTCTime Source #
genStOpen :: HydraContext -> Gen (UTxO, OpenState) Source #
genStClosed :: HydraContext -> UTxO -> Gen (SnapshotNumber, UTxO, ClosedState) Source #
Danger zone
unsafeCommit :: HasCallStack => ChainContext -> InitialState -> UTxO -> Tx Source #
unsafeObserveInit :: HasCallStack => ChainContext -> Tx -> InitialState Source #
unsafeObserveInitAndCommits :: HasCallStack => ChainContext -> Tx -> [Tx] -> ([UTxO], InitialState) Source #
Orphan instances
IsChainState Tx Source # | |
Associated Types type ChainStateType Tx = (c :: Type) Source # Methods |