Skip to content
Permalink
Browse files

Merge pull request #514 from input-output-hk/edsko/ledger-view-docs

Update docs for LedgerView
  • Loading branch information...
kantp committed May 15, 2019
2 parents ed7879a + 96c7098 commit fabb7e2b098a3576c50139e7ff67b416c9cd43d3
@@ -51,6 +51,7 @@ import Data.FingerTree (Measured (measure))
import qualified Data.IntMap.Strict as IntMap
import Data.Map (Map)
import qualified Data.Map.Strict as Map
import Data.Maybe (mapMaybe)
import Data.Proxy
import Data.Set (Set)
import qualified Data.Set as Set
@@ -435,10 +436,27 @@ instance (PBftCrypto c, SimpleBlockCrypto c')
=> ProtocolLedgerView (SimpleBlock (ExtNodeConfig (PBftLedgerView c) (PBft c)) c') where
protocolLedgerView (EncNodeConfig _ pbftParams) _ls = pbftParams

-- | Praos needs a ledger that can give it the "active stake distribution"
--
-- TODO: Currently our mock ledger does not do this, and just assumes that all
-- the leaders have equal stake at all times. In a way this is not wrong: it
-- is just a different instantiation of the same consensus algorithm (see
-- documentation of 'LedgerView'). Ideally we'd change this however, but it
-- may not be worth it; it would be a bit of work, and after we have integrated
-- the Shelley rules, we'll have a proper instance anyway.
instance ( PraosCrypto c, SimpleBlockCrypto c')
=> ProtocolLedgerView (SimpleBlock (ExtNodeConfig AddrDist (Praos c)) c') where
protocolLedgerView (EncNodeConfig _ addrDist) (SimpleLedgerState u _) =
relativeStakes $ totalStakes addrDist u
protocolLedgerView (EncNodeConfig _ addrDist) _ =
equalStakeDistr addrDist
where
equalStakeDistr :: AddrDist -> StakeDist
equalStakeDistr = IntMap.fromList
. mapMaybe (nodeStake . snd)
. Map.toList

nodeStake :: NodeId -> Maybe (Int, Rational)
nodeStake (RelayId _) = Nothing
nodeStake (CoreId i) = Just (i, 1)

instance (PraosCrypto c, SimpleBlockCrypto c')
=> ProtocolLedgerView (SimpleBlock (WithLeaderSchedule (Praos c)) c') where
@@ -90,6 +90,44 @@ class ( Show (ChainState p)
type family IsLeader p :: *

-- | Projection of the ledger state the Ouroboros protocol needs access to
--
-- The 'LedgerView' is a summary of the state of the ledger that the consensus
-- algorithm requires to do its job. Under certain circumstances the consensus
-- algorithm may require the 'LedgerView' for slots in the past (before the
-- current tip of the chain) or in the (near) future (beyond the tip of the
-- current chain, without having seen those future blocks yet).
--
-- This puts limitations on what the 'LedgerView' can be. For example, it
-- cannot be the "current stake distribution", since it is of course
-- impossible to compute the current stake distibution for a slot in the
-- future. This means that for a consensus algorithm that requires the
-- stake distribution such as Praos, the 'LedgerView' for a particular slot
-- must be the "stake distribution for the purpose of leader selection".
-- This "relevant" stake distribution /can/ be computed for slots in the
-- (near) future because it is based on historical stake, not current.
--
-- A somewhat unfortunate consequence of this is that some decisions that
-- ought to live in the consensus layer (such as the decision precisely which
-- historical stake to sample to determine the relevant stake distribution)
-- instead live in the ledger layer. It is difficult to disentangle this,
-- because the ledger may indeed /depend/ on those sampling decisions (for
-- example, reward calculations /must/ be based on that same stake
-- distribution).
--
-- There are also some /advantages/ to moving these sorts of decisions to the
-- ledger layer. It means that the consensus algorithm can continue to
-- function without modifications if we decide that the stake distribution for
-- leader selection should be based on something else instead (for example,
-- for some bespoke version of the blockchain we may wish to use a committee
-- instead of a decentralized blockchain). Having sampling decisions in the
-- ledger layer rather than the consensus layer means that these decisions can
-- be made without modifying the consensus algorithm.
--
-- Note that for the specific case of Praos, whilst the ledger layer provides
-- the relevant stake distribution, the precise leader election must still live
-- in the consensus layer since that depends on the computation (and sampling)
-- of entropy, which is done consensus side, not ledger side (the reward
-- calculation does not depend on this).
type family LedgerView p :: *

-- | Validation errors

0 comments on commit fabb7e2

Please sign in to comment.
You can’t perform that action at this time.