{-# LANGUAGE CPP #-}
{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric #-}
#if __GLASGOW_HASKELL__ < 900
{-# LANGUAGE DataKinds #-}
#endif
{-# LANGUAGE DeriveTraversable #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE QuantifiedConstraints #-}
{-# LANGUAGE RankNTypes #-}
{-# LANGUAGE StandaloneKindSignatures #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE TypeOperators #-}

-- | Definition is 'IsLedger'
--
-- Normally this is imported from "Ouroboros.Consensus.Ledger.Abstract". We
-- pull this out to avoid circular module dependencies.
module Ouroboros.Consensus.Ledger.Basics (
    -- * The 'LedgerState' definition
    LedgerCfg
  , LedgerState
  , TickedLedgerState
    -- * Definition of a ledger independent of a choice of block
  , ComputeLedgerEvents (..)
  , IsLedger (..)
  , applyChainTick
    -- * Ledger Events
  , LedgerResult (..)
  , VoidLedgerEvent
  , castLedgerResult
  , embedLedgerResult
  , pureLedgerResult
    -- * GetTip
  , GetTip (..)
  , GetTipSTM (..)
  , getTipHash
  , getTipM
  , getTipSlot
    -- * Associated types by block type
  , LedgerConfig
  , LedgerError
    -- * Re-exports
  , module Ouroboros.Consensus.Ledger.Tables
  ) where

import           Data.Kind (Constraint, Type)
import           GHC.Generics
import           Ouroboros.Consensus.Block.Abstract
import           Ouroboros.Consensus.Ledger.Tables
import           Ouroboros.Consensus.Ticked
import           Ouroboros.Consensus.Util.IOLike

{-------------------------------------------------------------------------------
  Tip
-------------------------------------------------------------------------------}

type GetTip :: LedgerStateKind -> Constraint
class GetTip l where
  -- | Point of the most recently applied block
  --
  -- Should be 'GenesisPoint' when no blocks have been applied yet
  getTip :: forall mk. l mk -> Point l

getTipHash :: GetTip l => l mk -> ChainHash l
getTipHash :: forall (l :: LedgerStateKind) (mk :: MapKind).
GetTip l =>
l mk -> ChainHash l
getTipHash = Point l -> ChainHash l
forall {k} (block :: k). Point block -> ChainHash block
pointHash (Point l -> ChainHash l)
-> (l mk -> Point l) -> l mk -> ChainHash l
forall b c a. (b -> c) -> (a -> b) -> a -> c
. l mk -> Point l
forall (mk :: MapKind). l mk -> Point l
forall (l :: LedgerStateKind) (mk :: MapKind).
GetTip l =>
l mk -> Point l
getTip

getTipSlot :: GetTip l => l mk -> WithOrigin SlotNo
getTipSlot :: forall (l :: LedgerStateKind) (mk :: MapKind).
GetTip l =>
l mk -> WithOrigin SlotNo
getTipSlot = Point l -> WithOrigin SlotNo
forall {k} (block :: k). Point block -> WithOrigin SlotNo
pointSlot (Point l -> WithOrigin SlotNo)
-> (l mk -> Point l) -> l mk -> WithOrigin SlotNo
forall b c a. (b -> c) -> (a -> b) -> a -> c
. l mk -> Point l
forall (mk :: MapKind). l mk -> Point l
forall (l :: LedgerStateKind) (mk :: MapKind).
GetTip l =>
l mk -> Point l
getTip

type GetTipSTM :: (Type -> Type) -> Type -> Constraint
class GetTipSTM m l where
  getTipSTM :: l -> STM m (Point l)

getTipM :: (GetTipSTM m l, MonadSTM m) => l -> m (Point l)
getTipM :: forall (m :: * -> *) l.
(GetTipSTM m l, MonadSTM m) =>
l -> m (Point l)
getTipM = STM m (Point l) -> m (Point l)
forall a. HasCallStack => STM m a -> m a
forall (m :: * -> *) a.
(MonadSTM m, HasCallStack) =>
STM m a -> m a
atomically (STM m (Point l) -> m (Point l))
-> (l -> STM m (Point l)) -> l -> m (Point l)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. l -> STM m (Point l)
forall (m :: * -> *) l. GetTipSTM m l => l -> STM m (Point l)
getTipSTM

{-------------------------------------------------------------------------------
  Events directly from the ledger
-------------------------------------------------------------------------------}

-- | A 'Data.Void.Void' isomorph for explicitly declaring that some ledger has
-- no events
type VoidLedgerEvent :: LedgerStateKind -> Type
data VoidLedgerEvent l

-- | 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.
data LedgerResult l a = LedgerResult
  { forall (l :: LedgerStateKind) a.
LedgerResult l a -> [AuxLedgerEvent l]
lrEvents :: [AuxLedgerEvent l]
  , forall (l :: LedgerStateKind) a. LedgerResult l a -> a
lrResult :: !a
  }
  deriving ((forall m. Monoid m => LedgerResult l m -> m)
-> (forall m a. Monoid m => (a -> m) -> LedgerResult l a -> m)
-> (forall m a. Monoid m => (a -> m) -> LedgerResult l a -> m)
-> (forall a b. (a -> b -> b) -> b -> LedgerResult l a -> b)
-> (forall a b. (a -> b -> b) -> b -> LedgerResult l a -> b)
-> (forall b a. (b -> a -> b) -> b -> LedgerResult l a -> b)
-> (forall b a. (b -> a -> b) -> b -> LedgerResult l a -> b)
-> (forall a. (a -> a -> a) -> LedgerResult l a -> a)
-> (forall a. (a -> a -> a) -> LedgerResult l a -> a)
-> (forall a. LedgerResult l a -> [a])
-> (forall a. LedgerResult l a -> Bool)
-> (forall a. LedgerResult l a -> Int)
-> (forall a. Eq a => a -> LedgerResult l a -> Bool)
-> (forall a. Ord a => LedgerResult l a -> a)
-> (forall a. Ord a => LedgerResult l a -> a)
-> (forall a. Num a => LedgerResult l a -> a)
-> (forall a. Num a => LedgerResult l a -> a)
-> Foldable (LedgerResult l)
forall a. Eq a => a -> LedgerResult l a -> Bool
forall a. Num a => LedgerResult l a -> a
forall a. Ord a => LedgerResult l a -> a
forall m. Monoid m => LedgerResult l m -> m
forall a. LedgerResult l a -> Bool
forall a. LedgerResult l a -> Int
forall a. LedgerResult l a -> [a]
forall a. (a -> a -> a) -> LedgerResult l a -> a
forall m a. Monoid m => (a -> m) -> LedgerResult l a -> m
forall b a. (b -> a -> b) -> b -> LedgerResult l a -> b
forall a b. (a -> b -> b) -> b -> LedgerResult l a -> b
forall (t :: * -> *).
(forall m. Monoid m => t m -> m)
-> (forall m a. Monoid m => (a -> m) -> t a -> m)
-> (forall m a. Monoid m => (a -> m) -> t a -> m)
-> (forall a b. (a -> b -> b) -> b -> t a -> b)
-> (forall a b. (a -> b -> b) -> b -> t a -> b)
-> (forall b a. (b -> a -> b) -> b -> t a -> b)
-> (forall b a. (b -> a -> b) -> b -> t a -> b)
-> (forall a. (a -> a -> a) -> t a -> a)
-> (forall a. (a -> a -> a) -> t a -> a)
-> (forall a. t a -> [a])
-> (forall a. t a -> Bool)
-> (forall a. t a -> Int)
-> (forall a. Eq a => a -> t a -> Bool)
-> (forall a. Ord a => t a -> a)
-> (forall a. Ord a => t a -> a)
-> (forall a. Num a => t a -> a)
-> (forall a. Num a => t a -> a)
-> Foldable t
forall (l :: LedgerStateKind) a.
Eq a =>
a -> LedgerResult l a -> Bool
forall (l :: LedgerStateKind) a. Num a => LedgerResult l a -> a
forall (l :: LedgerStateKind) a. Ord a => LedgerResult l a -> a
forall (l :: LedgerStateKind) m. Monoid m => LedgerResult l m -> m
forall (l :: LedgerStateKind) a. LedgerResult l a -> Bool
forall (l :: LedgerStateKind) a. LedgerResult l a -> Int
forall (l :: LedgerStateKind) a. LedgerResult l a -> [a]
forall (l :: LedgerStateKind) a.
(a -> a -> a) -> LedgerResult l a -> a
forall (l :: LedgerStateKind) m a.
Monoid m =>
(a -> m) -> LedgerResult l a -> m
forall (l :: LedgerStateKind) b a.
(b -> a -> b) -> b -> LedgerResult l a -> b
forall (l :: LedgerStateKind) a b.
(a -> b -> b) -> b -> LedgerResult l a -> b
$cfold :: forall (l :: LedgerStateKind) m. Monoid m => LedgerResult l m -> m
fold :: forall m. Monoid m => LedgerResult l m -> m
$cfoldMap :: forall (l :: LedgerStateKind) m a.
Monoid m =>
(a -> m) -> LedgerResult l a -> m
foldMap :: forall m a. Monoid m => (a -> m) -> LedgerResult l a -> m
$cfoldMap' :: forall (l :: LedgerStateKind) m a.
Monoid m =>
(a -> m) -> LedgerResult l a -> m
foldMap' :: forall m a. Monoid m => (a -> m) -> LedgerResult l a -> m
$cfoldr :: forall (l :: LedgerStateKind) a b.
(a -> b -> b) -> b -> LedgerResult l a -> b
foldr :: forall a b. (a -> b -> b) -> b -> LedgerResult l a -> b
$cfoldr' :: forall (l :: LedgerStateKind) a b.
(a -> b -> b) -> b -> LedgerResult l a -> b
foldr' :: forall a b. (a -> b -> b) -> b -> LedgerResult l a -> b
$cfoldl :: forall (l :: LedgerStateKind) b a.
(b -> a -> b) -> b -> LedgerResult l a -> b
foldl :: forall b a. (b -> a -> b) -> b -> LedgerResult l a -> b
$cfoldl' :: forall (l :: LedgerStateKind) b a.
(b -> a -> b) -> b -> LedgerResult l a -> b
foldl' :: forall b a. (b -> a -> b) -> b -> LedgerResult l a -> b
$cfoldr1 :: forall (l :: LedgerStateKind) a.
(a -> a -> a) -> LedgerResult l a -> a
foldr1 :: forall a. (a -> a -> a) -> LedgerResult l a -> a
$cfoldl1 :: forall (l :: LedgerStateKind) a.
(a -> a -> a) -> LedgerResult l a -> a
foldl1 :: forall a. (a -> a -> a) -> LedgerResult l a -> a
$ctoList :: forall (l :: LedgerStateKind) a. LedgerResult l a -> [a]
toList :: forall a. LedgerResult l a -> [a]
$cnull :: forall (l :: LedgerStateKind) a. LedgerResult l a -> Bool
null :: forall a. LedgerResult l a -> Bool
$clength :: forall (l :: LedgerStateKind) a. LedgerResult l a -> Int
length :: forall a. LedgerResult l a -> Int
$celem :: forall (l :: LedgerStateKind) a.
Eq a =>
a -> LedgerResult l a -> Bool
elem :: forall a. Eq a => a -> LedgerResult l a -> Bool
$cmaximum :: forall (l :: LedgerStateKind) a. Ord a => LedgerResult l a -> a
maximum :: forall a. Ord a => LedgerResult l a -> a
$cminimum :: forall (l :: LedgerStateKind) a. Ord a => LedgerResult l a -> a
minimum :: forall a. Ord a => LedgerResult l a -> a
$csum :: forall (l :: LedgerStateKind) a. Num a => LedgerResult l a -> a
sum :: forall a. Num a => LedgerResult l a -> a
$cproduct :: forall (l :: LedgerStateKind) a. Num a => LedgerResult l a -> a
product :: forall a. Num a => LedgerResult l a -> a
Foldable, (forall a b. (a -> b) -> LedgerResult l a -> LedgerResult l b)
-> (forall a b. a -> LedgerResult l b -> LedgerResult l a)
-> Functor (LedgerResult l)
forall a b. a -> LedgerResult l b -> LedgerResult l a
forall a b. (a -> b) -> LedgerResult l a -> LedgerResult l b
forall (f :: * -> *).
(forall a b. (a -> b) -> f a -> f b)
-> (forall a b. a -> f b -> f a) -> Functor f
forall (l :: LedgerStateKind) a b.
a -> LedgerResult l b -> LedgerResult l a
forall (l :: LedgerStateKind) a b.
(a -> b) -> LedgerResult l a -> LedgerResult l b
$cfmap :: forall (l :: LedgerStateKind) a b.
(a -> b) -> LedgerResult l a -> LedgerResult l b
fmap :: forall a b. (a -> b) -> LedgerResult l a -> LedgerResult l b
$c<$ :: forall (l :: LedgerStateKind) a b.
a -> LedgerResult l b -> LedgerResult l a
<$ :: forall a b. a -> LedgerResult l b -> LedgerResult l a
Functor, Functor (LedgerResult l)
Foldable (LedgerResult l)
(Functor (LedgerResult l), Foldable (LedgerResult l)) =>
(forall (f :: * -> *) a b.
 Applicative f =>
 (a -> f b) -> LedgerResult l a -> f (LedgerResult l b))
-> (forall (f :: * -> *) a.
    Applicative f =>
    LedgerResult l (f a) -> f (LedgerResult l a))
-> (forall (m :: * -> *) a b.
    Monad m =>
    (a -> m b) -> LedgerResult l a -> m (LedgerResult l b))
-> (forall (m :: * -> *) a.
    Monad m =>
    LedgerResult l (m a) -> m (LedgerResult l a))
-> Traversable (LedgerResult l)
forall (t :: * -> *).
(Functor t, Foldable t) =>
(forall (f :: * -> *) a b.
 Applicative f =>
 (a -> f b) -> t a -> f (t b))
-> (forall (f :: * -> *) a. Applicative f => t (f a) -> f (t a))
-> (forall (m :: * -> *) a b.
    Monad m =>
    (a -> m b) -> t a -> m (t b))
-> (forall (m :: * -> *) a. Monad m => t (m a) -> m (t a))
-> Traversable t
forall (m :: * -> *) a.
Monad m =>
LedgerResult l (m a) -> m (LedgerResult l a)
forall (f :: * -> *) a.
Applicative f =>
LedgerResult l (f a) -> f (LedgerResult l a)
forall (m :: * -> *) a b.
Monad m =>
(a -> m b) -> LedgerResult l a -> m (LedgerResult l b)
forall (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> LedgerResult l a -> f (LedgerResult l b)
forall (l :: LedgerStateKind). Functor (LedgerResult l)
forall (l :: LedgerStateKind). Foldable (LedgerResult l)
forall (l :: LedgerStateKind) (m :: * -> *) a.
Monad m =>
LedgerResult l (m a) -> m (LedgerResult l a)
forall (l :: LedgerStateKind) (f :: * -> *) a.
Applicative f =>
LedgerResult l (f a) -> f (LedgerResult l a)
forall (l :: LedgerStateKind) (m :: * -> *) a b.
Monad m =>
(a -> m b) -> LedgerResult l a -> m (LedgerResult l b)
forall (l :: LedgerStateKind) (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> LedgerResult l a -> f (LedgerResult l b)
$ctraverse :: forall (l :: LedgerStateKind) (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> LedgerResult l a -> f (LedgerResult l b)
traverse :: forall (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> LedgerResult l a -> f (LedgerResult l b)
$csequenceA :: forall (l :: LedgerStateKind) (f :: * -> *) a.
Applicative f =>
LedgerResult l (f a) -> f (LedgerResult l a)
sequenceA :: forall (f :: * -> *) a.
Applicative f =>
LedgerResult l (f a) -> f (LedgerResult l a)
$cmapM :: forall (l :: LedgerStateKind) (m :: * -> *) a b.
Monad m =>
(a -> m b) -> LedgerResult l a -> m (LedgerResult l b)
mapM :: forall (m :: * -> *) a b.
Monad m =>
(a -> m b) -> LedgerResult l a -> m (LedgerResult l b)
$csequence :: forall (l :: LedgerStateKind) (m :: * -> *) a.
Monad m =>
LedgerResult l (m a) -> m (LedgerResult l a)
sequence :: forall (m :: * -> *) a.
Monad m =>
LedgerResult l (m a) -> m (LedgerResult l a)
Traversable)

castLedgerResult ::
     (AuxLedgerEvent l ~ AuxLedgerEvent l')
  => LedgerResult l  a
  -> LedgerResult l' a
castLedgerResult :: forall (l :: LedgerStateKind) (l' :: LedgerStateKind) a.
(AuxLedgerEvent l ~ AuxLedgerEvent l') =>
LedgerResult l a -> LedgerResult l' a
castLedgerResult (LedgerResult [AuxLedgerEvent l]
x0 a
x1) = [AuxLedgerEvent l'] -> a -> LedgerResult l' a
forall (l :: LedgerStateKind) a.
[AuxLedgerEvent l] -> a -> LedgerResult l a
LedgerResult [AuxLedgerEvent l]
[AuxLedgerEvent l']
x0 a
x1

embedLedgerResult ::
     (AuxLedgerEvent l -> AuxLedgerEvent l')
  -> LedgerResult l  a
  -> LedgerResult l' a
embedLedgerResult :: forall (l :: LedgerStateKind) (l' :: LedgerStateKind) a.
(AuxLedgerEvent l -> AuxLedgerEvent l')
-> LedgerResult l a -> LedgerResult l' a
embedLedgerResult AuxLedgerEvent l -> AuxLedgerEvent l'
inj LedgerResult l a
lr = LedgerResult l a
lr{lrEvents = inj `map` lrEvents lr}

pureLedgerResult :: a -> LedgerResult l a
pureLedgerResult :: forall a (l :: LedgerStateKind). a -> LedgerResult l a
pureLedgerResult a
a = LedgerResult {
    lrEvents :: [AuxLedgerEvent l]
lrEvents = [AuxLedgerEvent l]
forall a. Monoid a => a
mempty
  , lrResult :: a
lrResult = a
a
  }

{-------------------------------------------------------------------------------
  Definition of a ledger independent of a choice of block
-------------------------------------------------------------------------------}

-- | Static environment required for the ledger
--
-- Types that inhabit this family will come from the Ledger code.
type LedgerCfg :: LedgerStateKind -> Type
type family LedgerCfg l :: Type

-- | 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.
data ComputeLedgerEvents = ComputeLedgerEvents | OmitLedgerEvents
  deriving (ComputeLedgerEvents -> ComputeLedgerEvents -> Bool
(ComputeLedgerEvents -> ComputeLedgerEvents -> Bool)
-> (ComputeLedgerEvents -> ComputeLedgerEvents -> Bool)
-> Eq ComputeLedgerEvents
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: ComputeLedgerEvents -> ComputeLedgerEvents -> Bool
== :: ComputeLedgerEvents -> ComputeLedgerEvents -> Bool
$c/= :: ComputeLedgerEvents -> ComputeLedgerEvents -> Bool
/= :: ComputeLedgerEvents -> ComputeLedgerEvents -> Bool
Eq, Int -> ComputeLedgerEvents -> ShowS
[ComputeLedgerEvents] -> ShowS
ComputeLedgerEvents -> String
(Int -> ComputeLedgerEvents -> ShowS)
-> (ComputeLedgerEvents -> String)
-> ([ComputeLedgerEvents] -> ShowS)
-> Show ComputeLedgerEvents
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> ComputeLedgerEvents -> ShowS
showsPrec :: Int -> ComputeLedgerEvents -> ShowS
$cshow :: ComputeLedgerEvents -> String
show :: ComputeLedgerEvents -> String
$cshowList :: [ComputeLedgerEvents] -> ShowS
showList :: [ComputeLedgerEvents] -> ShowS
Show, (forall x. ComputeLedgerEvents -> Rep ComputeLedgerEvents x)
-> (forall x. Rep ComputeLedgerEvents x -> ComputeLedgerEvents)
-> Generic ComputeLedgerEvents
forall x. Rep ComputeLedgerEvents x -> ComputeLedgerEvents
forall x. ComputeLedgerEvents -> Rep ComputeLedgerEvents x
forall a.
(forall x. a -> Rep a x) -> (forall x. Rep a x -> a) -> Generic a
$cfrom :: forall x. ComputeLedgerEvents -> Rep ComputeLedgerEvents x
from :: forall x. ComputeLedgerEvents -> Rep ComputeLedgerEvents x
$cto :: forall x. Rep ComputeLedgerEvents x -> ComputeLedgerEvents
to :: forall x. Rep ComputeLedgerEvents x -> ComputeLedgerEvents
Generic, Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo)
Proxy ComputeLedgerEvents -> String
(Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo))
-> (Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo))
-> (Proxy ComputeLedgerEvents -> String)
-> NoThunks ComputeLedgerEvents
forall a.
(Context -> a -> IO (Maybe ThunkInfo))
-> (Context -> a -> IO (Maybe ThunkInfo))
-> (Proxy a -> String)
-> NoThunks a
$cnoThunks :: Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo)
noThunks :: Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo)
$cwNoThunks :: Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo)
wNoThunks :: Context -> ComputeLedgerEvents -> IO (Maybe ThunkInfo)
$cshowTypeOf :: Proxy ComputeLedgerEvents -> String
showTypeOf :: Proxy ComputeLedgerEvents -> String
NoThunks)

type IsLedger :: LedgerStateKind -> Constraint
class ( -- Requirements on the ledger state itself
        forall mk. EqMK mk       => Eq       (l mk)
      , forall mk. NoThunksMK mk => NoThunks (l mk)
      , forall mk. ShowMK mk     => Show     (l mk)
        -- Requirements on 'LedgerCfg'
      , NoThunks (LedgerCfg l)
        -- Requirements on 'LedgerErr'
      , Show     (LedgerErr l)
      , Eq       (LedgerErr l)
      , NoThunks (LedgerErr l)
        -- Get the tip
        --
        -- See comment for 'applyChainTickLedgerResult' about the tip of the
        -- ticked ledger.
      , GetTip          l
      , GetTip (Ticked l)
      ) => IsLedger l where
  -- | 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.
  type family LedgerErr l :: Type

  -- | 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.
  type family AuxLedgerEvent l :: Type

  -- | 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:
  --
  -- prop> ledgerTipPoint (applyChainTick cfg slot st) == ledgerTipPoint st
  applyChainTickLedgerResult ::
       ComputeLedgerEvents
    -> LedgerCfg l
    -> SlotNo
    -> l EmptyMK
    -> LedgerResult l (Ticked l DiffMK)

-- | 'lrResult' after 'applyChainTickLedgerResult'
applyChainTick ::
     IsLedger l
  => ComputeLedgerEvents
  -> LedgerCfg l
  -> SlotNo
  -> l EmptyMK
  -> Ticked l DiffMK
applyChainTick :: forall (l :: LedgerStateKind).
IsLedger l =>
ComputeLedgerEvents
-> LedgerCfg l -> SlotNo -> l EmptyMK -> Ticked l DiffMK
applyChainTick = LedgerResult l (Ticked l DiffMK) -> Ticked l DiffMK
forall (l :: LedgerStateKind) a. LedgerResult l a -> a
lrResult (LedgerResult l (Ticked l DiffMK) -> Ticked l DiffMK)
-> (ComputeLedgerEvents
    -> LedgerCfg l
    -> SlotNo
    -> l EmptyMK
    -> LedgerResult l (Ticked l DiffMK))
-> ComputeLedgerEvents
-> LedgerCfg l
-> SlotNo
-> l EmptyMK
-> Ticked l DiffMK
forall y z x0 x1 x2 x3.
(y -> z)
-> (x0 -> x1 -> x2 -> x3 -> y) -> x0 -> x1 -> x2 -> x3 -> z
...: ComputeLedgerEvents
-> LedgerCfg l
-> SlotNo
-> l EmptyMK
-> LedgerResult l (Ticked l DiffMK)
forall (l :: LedgerStateKind).
IsLedger l =>
ComputeLedgerEvents
-> LedgerCfg l
-> SlotNo
-> l EmptyMK
-> LedgerResult l (Ticked l DiffMK)
applyChainTickLedgerResult

{-------------------------------------------------------------------------------
  Link block to its ledger
-------------------------------------------------------------------------------}

-- | 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 'Ouroboros.Consensus.Ledger.Extended.ExtLedgerState').
--
-- This type is parametrized over @mk :: 'MapKind'@ to express the
-- 'LedgerTables' 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
-- 'Ouroboros.Consensus.Ledger.Abstract.ApplyBlock').
type LedgerState :: Type -> LedgerStateKind
data family LedgerState blk mk
type TickedLedgerState blk = Ticked (LedgerState blk)

type instance HeaderHash (LedgerState blk) = HeaderHash blk

instance StandardHash blk => StandardHash (LedgerState blk)

type LedgerConfig      blk    = LedgerCfg (LedgerState blk)
type LedgerError       blk    = LedgerErr (LedgerState blk)