| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Ledger.Basics
Description
Definition is IsLedger
Normally this is imported from Ouroboros.Consensus.Ledger.Abstract. We pull this out to avoid circular module dependencies.
Synopsis
- type family LedgerCfg (l ∷ StateKind) blk
- data family LedgerState blk (mk ∷ MapKind)
- type TickedLedgerState blk = Ticked LedgerState blk
- data ComputeLedgerEvents
- class (∀ (mk ∷ MapKind). EqMK mk ⇒ Eq (l blk mk), ∀ (mk ∷ MapKind). NoThunksMK mk ⇒ NoThunks (l blk mk), ∀ (mk ∷ MapKind). ShowMK mk ⇒ Show (l blk mk), NoThunks (LedgerCfg l blk), Show (LedgerErr l blk), Eq (LedgerErr l blk), NoThunks (LedgerErr l blk), GetTip (l blk), GetTip (Ticked l blk)) ⇒ IsLedger (l ∷ StateKind) blk where
- type LedgerErr (l ∷ StateKind) blk
- applyChainTickLedgerResult ∷ ComputeLedgerEvents → LedgerCfg l blk → SlotNo → l blk EmptyMK → LedgerResult blk (Ticked l blk DiffMK)
- type family AuxLedgerEvent blk
- applyChainTick ∷ IsLedger l blk ⇒ ComputeLedgerEvents → LedgerCfg l blk → SlotNo → l blk EmptyMK → Ticked l blk DiffMK
- data LedgerResult blk a = LedgerResult {
- lrEvents ∷ [AuxLedgerEvent blk]
- lrResult ∷ !a
- data VoidLedgerEvent
- castLedgerResult ∷ AuxLedgerEvent l ~ AuxLedgerEvent l' ⇒ LedgerResult l a → LedgerResult l' a
- embedLedgerResult ∷ (AuxLedgerEvent l → AuxLedgerEvent l') → LedgerResult l a → LedgerResult l' a
- pureLedgerResult ∷ a → LedgerResult l a
- class GetTip (l ∷ LedgerStateKind) where
- class GetTipSTM (m ∷ Type → Type) l where
- getTipHash ∷ ∀ l (mk ∷ MapKind). GetTip l ⇒ l mk → ChainHash l
- getTipM ∷ (GetTipSTM m l, MonadSTM m) ⇒ l → m (Point l)
- getTipSlot ∷ ∀ l (mk ∷ MapKind). GetTip l ⇒ l mk → WithOrigin SlotNo
- type LedgerConfig blk = LedgerCfg LedgerState blk
- type LedgerError blk = LedgerErr LedgerState blk
The LedgerState definition
type family LedgerCfg (l ∷ StateKind) blk Source #
Static environment required for the ledger
Types that inhabit this family will come from the Ledger code.
Instances
| type LedgerCfg ExtLedgerState blk Source # | |
Defined in Ouroboros.Consensus.Ledger.Extended | |
| type LedgerCfg LedgerState (HardForkBlock xs) Source # | |
| type LedgerCfg LedgerState (DualBlock m a) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual | |
data family LedgerState blk (mk ∷ MapKind) Source #
Ledger state associated with a block
This is the Consensus notion of a Ledger ledger state. Each block type is
associated with one of the Ledger types for the ledger state. Virtually
every concept in this codebase revolves around this type, or the referenced
blk. Whenever we use the type variable l we intend to signal that the
expected instantiation is either a LedgerState or some wrapper over it
(like the ExtLedgerState).
This type is parametrized over mk :: to express the
MapKindLedgerTables contained in such a LedgerState. See LedgerTables for a
more thorough description.
The main operations we can do with a LedgerState are ticking (defined in
IsLedger), and applying a block (defined in
ApplyBlock).
Instances
type TickedLedgerState blk = Ticked LedgerState blk Source #
Definition of a ledger independent of a choice of block
data ComputeLedgerEvents Source #
Whether we tell the ledger layer to compute ledger events
At the moment events are not emitted in any case in the consensus layer (i.e. there is no handler for those events, nor are they traced), so they are not really forced, we always discard them. This behavior does not incur big costs thanks to laziness.
By passing OmitLedgerEvents we tell the Ledger layer to not even
allocate thunks for those events, as we explicitly don't want them.
Constructors
| ComputeLedgerEvents | |
| OmitLedgerEvents |
Instances
| Generic ComputeLedgerEvents Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Basics Associated Types
Methods | |||||
| Show ComputeLedgerEvents Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Basics Methods showsPrec ∷ Int → ComputeLedgerEvents → ShowS # show ∷ ComputeLedgerEvents → String # showList ∷ [ComputeLedgerEvents] → ShowS # | |||||
| Eq ComputeLedgerEvents Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Basics Methods | |||||
| NoThunks ComputeLedgerEvents Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Basics | |||||
| type Rep ComputeLedgerEvents Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Basics | |||||
class (∀ (mk ∷ MapKind). EqMK mk ⇒ Eq (l blk mk), ∀ (mk ∷ MapKind). NoThunksMK mk ⇒ NoThunks (l blk mk), ∀ (mk ∷ MapKind). ShowMK mk ⇒ Show (l blk mk), NoThunks (LedgerCfg l blk), Show (LedgerErr l blk), Eq (LedgerErr l blk), NoThunks (LedgerErr l blk), GetTip (l blk), GetTip (Ticked l blk)) ⇒ IsLedger (l ∷ StateKind) blk where Source #
Associated Types
type LedgerErr (l ∷ StateKind) blk Source #
Errors that can arise when updating the ledger
This is defined here rather than in ApplyBlock, since the type of
these errors does not depend on the type of the block.
Methods
applyChainTickLedgerResult ∷ ComputeLedgerEvents → LedgerCfg l blk → SlotNo → l blk EmptyMK → LedgerResult blk (Ticked l blk DiffMK) Source #
Apply "slot based" state transformations
When a block is applied to the ledger state, a number of things happen purely based on the slot number of that block. For example:
- In Byron, scheduled updates are applied, and the update system state is updated.
- In Shelley, delegation state is updated (on epoch boundaries).
The consensus layer must be able to apply such a "chain tick" function, primarily when validating transactions in the mempool (which, conceptually, live in "some block in the future") or when extracting valid transactions from the mempool to insert into a new block to be produced.
This is not allowed to throw any errors. After all, if this could fail, it would mean a previous block set up the ledger state in such a way that as soon as a certain slot was reached, any block would be invalid.
Ticking a ledger state may not use any data from the LedgerTables,
however it might produce differences in the tables, in particular because
era transitions happen when ticking a ledger state.
PRECONDITION: The slot number must be strictly greater than the slot at the tip of the ledger (except for EBBs, obviously..).
NOTE: applyChainTickLedgerResult should not change the tip of the
underlying ledger state, which should still refer to the most recent
applied block. In other words, we should have:
ledgerTipPoint (applyChainTick cfg slot st) == ledgerTipPoint st
Instances
| LedgerSupportsProtocol blk ⇒ IsLedger ExtLedgerState blk Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Extended Associated Types
Methods applyChainTickLedgerResult ∷ ComputeLedgerEvents → LedgerCfg ExtLedgerState blk → SlotNo → ExtLedgerState blk EmptyMK → LedgerResult blk (Ticked ExtLedgerState blk DiffMK) Source # | |||||
| CanHardFork xs ⇒ IsLedger LedgerState (HardForkBlock xs) Source # | |||||
Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger Associated Types
Methods applyChainTickLedgerResult ∷ ComputeLedgerEvents → LedgerCfg LedgerState (HardForkBlock xs) → SlotNo → LedgerState (HardForkBlock xs) EmptyMK → LedgerResult (HardForkBlock xs) (Ticked LedgerState (HardForkBlock xs) DiffMK) Source # | |||||
| Bridge m a ⇒ IsLedger LedgerState (DualBlock m a) Source # | |||||
Defined in Ouroboros.Consensus.Ledger.Dual Associated Types
Methods applyChainTickLedgerResult ∷ ComputeLedgerEvents → LedgerCfg LedgerState (DualBlock m a) → SlotNo → LedgerState (DualBlock m a) EmptyMK → LedgerResult (DualBlock m a) (Ticked LedgerState (DualBlock m a) DiffMK) Source # | |||||
type family AuxLedgerEvent blk Source #
Event emitted by the ledger
TODO we call this AuxLedgerEvent to differentiate from LedgerEvent in
InspectLedger. When that module is rewritten to make use of ledger
derived events, we may rename this type.
Instances
| type AuxLedgerEvent (HardForkBlock xs) Source # | |
| type AuxLedgerEvent (DualBlock m a) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual | |
applyChainTick ∷ IsLedger l blk ⇒ ComputeLedgerEvents → LedgerCfg l blk → SlotNo → l blk EmptyMK → Ticked l blk DiffMK Source #
Ledger Events
data LedgerResult blk a Source #
The result of invoke a ledger function that does validation
Note: we do not instantiate Applicative or Monad for this type because
those interfaces would typically incur space leaks. We encourage you to
process the events each time you invoke a ledger function.
Constructors
| LedgerResult | |
Fields
| |
Instances
| Functor (LedgerResult blk) Source # | |
Defined in Ouroboros.Consensus.Ledger.Basics Methods fmap ∷ (a → b) → LedgerResult blk a → LedgerResult blk b # (<$) ∷ a → LedgerResult blk b → LedgerResult blk a # | |
| Foldable (LedgerResult blk) Source # | |
Defined in Ouroboros.Consensus.Ledger.Basics Methods fold ∷ Monoid m ⇒ LedgerResult blk m → m # foldMap ∷ Monoid m ⇒ (a → m) → LedgerResult blk a → m # foldMap' ∷ Monoid m ⇒ (a → m) → LedgerResult blk a → m # foldr ∷ (a → b → b) → b → LedgerResult blk a → b # foldr' ∷ (a → b → b) → b → LedgerResult blk a → b # foldl ∷ (b → a → b) → b → LedgerResult blk a → b # foldl' ∷ (b → a → b) → b → LedgerResult blk a → b # foldr1 ∷ (a → a → a) → LedgerResult blk a → a # foldl1 ∷ (a → a → a) → LedgerResult blk a → a # toList ∷ LedgerResult blk a → [a] # null ∷ LedgerResult blk a → Bool # length ∷ LedgerResult blk a → Int # elem ∷ Eq a ⇒ a → LedgerResult blk a → Bool # maximum ∷ Ord a ⇒ LedgerResult blk a → a # minimum ∷ Ord a ⇒ LedgerResult blk a → a # sum ∷ Num a ⇒ LedgerResult blk a → a # product ∷ Num a ⇒ LedgerResult blk a → a # | |
| Traversable (LedgerResult blk) Source # | |
Defined in Ouroboros.Consensus.Ledger.Basics Methods traverse ∷ Applicative f ⇒ (a → f b) → LedgerResult blk a → f (LedgerResult blk b) # sequenceA ∷ Applicative f ⇒ LedgerResult blk (f a) → f (LedgerResult blk a) # mapM ∷ Monad m ⇒ (a → m b) → LedgerResult blk a → m (LedgerResult blk b) # sequence ∷ Monad m ⇒ LedgerResult blk (m a) → m (LedgerResult blk a) # | |
data VoidLedgerEvent Source #
A Void isomorph for explicitly declaring that some ledger has
no events
castLedgerResult ∷ AuxLedgerEvent l ~ AuxLedgerEvent l' ⇒ LedgerResult l a → LedgerResult l' a Source #
embedLedgerResult ∷ (AuxLedgerEvent l → AuxLedgerEvent l') → LedgerResult l a → LedgerResult l' a Source #
pureLedgerResult ∷ a → LedgerResult l a Source #
GetTip
class GetTip (l ∷ LedgerStateKind) where Source #
Methods
getTip ∷ ∀ (mk ∷ MapKind). l mk → Point l Source #
Point of the most recently applied block
Should be GenesisPoint when no blocks have been applied yet
Instances
| CanHardFork xs ⇒ GetTip (LedgerState (HardForkBlock xs)) Source # | |
Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger Methods getTip ∷ ∀ (mk ∷ MapKind). LedgerState (HardForkBlock xs) mk → Point (LedgerState (HardForkBlock xs)) Source # | |
| Bridge m a ⇒ GetTip (LedgerState (DualBlock m a)) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual Methods getTip ∷ ∀ (mk ∷ MapKind). LedgerState (DualBlock m a) mk → Point (LedgerState (DualBlock m a)) Source # | |
| IsLedger LedgerState blk ⇒ GetTip (ExtLedgerState blk) Source # | |
Defined in Ouroboros.Consensus.Ledger.Extended Methods getTip ∷ ∀ (mk ∷ MapKind). ExtLedgerState blk mk → Point (ExtLedgerState blk) Source # | |
| CanHardFork xs ⇒ GetTip (Ticked LedgerState (HardForkBlock xs)) Source # | |
Defined in Ouroboros.Consensus.HardFork.Combinator.Ledger Methods getTip ∷ ∀ (mk ∷ MapKind). Ticked LedgerState (HardForkBlock xs) mk → Point (Ticked LedgerState (HardForkBlock xs)) Source # | |
| Bridge m a ⇒ GetTip (Ticked LedgerState (DualBlock m a)) Source # | |
Defined in Ouroboros.Consensus.Ledger.Dual | |
| IsLedger LedgerState blk ⇒ GetTip (Ticked ExtLedgerState blk) Source # | |
Defined in Ouroboros.Consensus.Ledger.Extended Methods getTip ∷ ∀ (mk ∷ MapKind). Ticked ExtLedgerState blk mk → Point (Ticked ExtLedgerState blk) Source # | |
getTipSlot ∷ ∀ l (mk ∷ MapKind). GetTip l ⇒ l mk → WithOrigin SlotNo Source #
Associated types by block type
type LedgerConfig blk = LedgerCfg LedgerState blk Source #
type LedgerError blk = LedgerErr LedgerState blk Source #