ouroboros-consensus-0.1.0.2: Consensus layer for the Ouroboros blockchain protocol
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Consensus.Protocol.Abstract

Synopsis

Abstract definition of the Ouroboros protocol

data family ConsensusConfig p ∷ Type Source #

Static configuration required to run the consensus protocol

Every method in the ConsensusProtocol class takes the consensus configuration as a parameter, so having this as a data family rather than a type family resolves most ambiguity.

Defined out of the class so that protocols can define this type without having to define the entire protocol at the same time (or indeed in the same module).

Instances

Instances details
Generic (ConsensusConfig (ModChainSel p s)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.ModChainSel

Associated Types

type Rep (ConsensusConfig (ModChainSel p s)) ∷ TypeType Source #

Generic (ConsensusConfig (Bft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.BFT

Associated Types

type Rep (ConsensusConfig (Bft c)) ∷ TypeType Source #

Generic (ConsensusConfig (HardForkProtocol xs)) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Basics

Associated Types

type Rep (ConsensusConfig (HardForkProtocol xs)) ∷ TypeType Source #

Generic (ConsensusConfig (PBft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.PBFT

Associated Types

type Rep (ConsensusConfig (PBft c)) ∷ TypeType Source #

ConsensusProtocol p ⇒ NoThunks (ConsensusConfig (ModChainSel p s)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.ModChainSel

Methods

noThunks ∷ Context → ConsensusConfig (ModChainSel p s) → IO (Maybe ThunkInfo) #

wNoThunks ∷ Context → ConsensusConfig (ModChainSel p s) → IO (Maybe ThunkInfo) #

showTypeOfProxy (ConsensusConfig (ModChainSel p s)) → String #

BftCrypto c ⇒ NoThunks (ConsensusConfig (Bft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.BFT

Methods

noThunks ∷ Context → ConsensusConfig (Bft c) → IO (Maybe ThunkInfo) #

wNoThunks ∷ Context → ConsensusConfig (Bft c) → IO (Maybe ThunkInfo) #

showTypeOfProxy (ConsensusConfig (Bft c)) → String #

CanHardFork xs ⇒ NoThunks (ConsensusConfig (HardForkProtocol xs)) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Basics

Methods

noThunks ∷ Context → ConsensusConfig (HardForkProtocol xs) → IO (Maybe ThunkInfo) #

wNoThunks ∷ Context → ConsensusConfig (HardForkProtocol xs) → IO (Maybe ThunkInfo) #

showTypeOfProxy (ConsensusConfig (HardForkProtocol xs)) → String #

NoThunks (ConsensusConfig (PBft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.PBFT

Methods

noThunks ∷ Context → ConsensusConfig (PBft c) → IO (Maybe ThunkInfo) #

wNoThunks ∷ Context → ConsensusConfig (PBft c) → IO (Maybe ThunkInfo) #

showTypeOfProxy (ConsensusConfig (PBft c)) → String #

type Rep (ConsensusConfig (ModChainSel p s)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.ModChainSel

type Rep (ConsensusConfig (ModChainSel p s)) = D1 ('MetaData "ConsensusConfig" "Ouroboros.Consensus.Protocol.ModChainSel" "ouroboros-consensus-0.1.0.2-inplace" 'True) (C1 ('MetaCons "McsConsensusConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "mcsConfigP") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ConsensusConfig p))))
type Rep (ConsensusConfig (Bft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.BFT

type Rep (ConsensusConfig (Bft c)) = D1 ('MetaData "ConsensusConfig" "Ouroboros.Consensus.Protocol.BFT" "ouroboros-consensus-0.1.0.2-inplace" 'False) (C1 ('MetaCons "BftConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "bftParams") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 BftParams) :*: (S1 ('MetaSel ('Just "bftSignKey") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (SignKeyDSIGN (BftDSIGN c))) :*: S1 ('MetaSel ('Just "bftVerKeys") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Map NodeId (VerKeyDSIGN (BftDSIGN c)))))))
type Rep (ConsensusConfig (HardForkProtocol xs)) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Basics

type Rep (ConsensusConfig (HardForkProtocol xs)) = D1 ('MetaData "ConsensusConfig" "Ouroboros.Consensus.HardFork.Combinator.Basics" "ouroboros-consensus-0.1.0.2-inplace" 'False) (C1 ('MetaCons "HardForkConsensusConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "hardForkConsensusConfigK") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 SecurityParam) :*: (S1 ('MetaSel ('Just "hardForkConsensusConfigShape") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Shape xs)) :*: S1 ('MetaSel ('Just "hardForkConsensusConfigPerEra") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (PerEraConsensusConfig xs)))))
type Rep (ConsensusConfig (PBft c)) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.PBFT

type Rep (ConsensusConfig (PBft c)) = D1 ('MetaData "ConsensusConfig" "Ouroboros.Consensus.Protocol.PBFT" "ouroboros-consensus-0.1.0.2-inplace" 'True) (C1 ('MetaCons "PBftConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "pbftParams") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PBftParams)))
data ConsensusConfig (Bft c) Source #

(Static) node configuration

Instance details

Defined in Ouroboros.Consensus.Protocol.BFT

data ConsensusConfig (Bft c) = BftConfig {}
data ConsensusConfig (HardForkProtocol xs) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Basics

newtype ConsensusConfig (PBft c) Source #

(Static) node configuration

Instance details

Defined in Ouroboros.Consensus.Protocol.PBFT

newtype ConsensusConfig (ModChainSel p s) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.ModChainSel

class (Show (ChainDepState p), Show (ValidationErr p), Show (SelectView p), Show (LedgerView p), Eq (ChainDepState p), Eq (ValidationErr p), Ord (SelectView p), NoThunks (ConsensusConfig p), NoThunks (ChainDepState p), NoThunks (ValidationErr p), NoThunks (SelectView p), Typeable p) ⇒ ConsensusProtocol p where Source #

The (open) universe of Ouroboros protocols

This class encodes the part that is independent from any particular block representation.

Associated Types

type ChainDepState p ∷ Type Source #

Protocol-specific state

NOTE: This chain is blockchain dependent, i.e., updated when new blocks come in (more precisely, new headers), and subject to rollback.

type IsLeader p ∷ Type Source #

Evidence that a node is the leader

type CanBeLeader p ∷ Type Source #

Evidence that we can be a leader

type SelectView p ∷ Type Source #

View on a header required for chain selection

Chain selection is implemented by the chain database, which takes care of two things independent of a choice of consensus protocol: we never switch to chains that fork off more than k blocks ago, and we never adopt an invalid chain. The actual comparison of chains however depends on the chain selection protocol. We define chain selection (which is itself a partial order) in terms of a totally ordered select view on the headers at the tips of those chains: chain A is strictly preferred over chain B whenever A's select view is greater than B's select view. When the select view on A and B is the same, the chains are considered to be incomparable (neither chain is preferred over the other).

type LedgerView p ∷ Type Source #

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 ValidationErr p ∷ Type Source #

Validation errors

type ValidateView p ∷ Type Source #

View on a header required to validate it

Methods

checkIsLeaderHasCallStackConsensusConfig p → CanBeLeader p → SlotNoTicked (ChainDepState p) → Maybe (IsLeader p) Source #

Check if a node is the leader

tickChainDepStateConsensusConfig p → Ticked (LedgerView p) → SlotNoChainDepState p → Ticked (ChainDepState p) Source #

Tick the ChainDepState

We pass the ticked LedgerView to tickChainDepState. Functions that take a ticked ChainDepState are not separately passed a ticked ledger view; protocols that require it, can include it in their ticked ChainDepState type.

updateChainDepStateHasCallStackConsensusConfig p → ValidateView p → SlotNoTicked (ChainDepState p) → Except (ValidationErr p) (ChainDepState p) Source #

Apply a header

reupdateChainDepStateHasCallStackConsensusConfig p → ValidateView p → SlotNoTicked (ChainDepState p) → ChainDepState p Source #

Re-apply a header to the same ChainDepState we have been able to successfully apply to before.

Since a header can only be applied to a single, specific, ChainDepState, if we apply a previously applied header again it will be applied in the very same ChainDepState, and therefore can't possibly fail.

It is worth noting that since we already know that the header is valid w.r.t. the provided ChainDepState, no validation checks should be performed.

protocolSecurityParamConsensusConfig p → SecurityParam Source #

We require that protocols support a k security parameter

Instances

Instances details
BftCrypto c ⇒ ConsensusProtocol (Bft c) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.BFT

Associated Types

type ChainDepState (Bft c) Source #

type IsLeader (Bft c) Source #

type CanBeLeader (Bft c) Source #

type SelectView (Bft c) Source #

type LedgerView (Bft c) Source #

type ValidationErr (Bft c) Source #

type ValidateView (Bft c) Source #

CanHardFork xs ⇒ ConsensusProtocol (HardForkProtocol xs) Source # 
Instance details

Defined in Ouroboros.Consensus.HardFork.Combinator.Protocol

PBftCrypto c ⇒ ConsensusProtocol (PBft c) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.PBFT

(ConsensusProtocol p, Ord s, Show s, Typeable s, NoThunks s) ⇒ ConsensusProtocol (ModChainSel p s) Source # 
Instance details

Defined in Ouroboros.Consensus.Protocol.ModChainSel

preferCandidate Source #

Arguments

ConsensusProtocol p 
⇒ proxy p 
SelectView p

Tip of our chain

SelectView p

Tip of the candidate

Bool 

Compare a candidate chain to our own

If both chains are equally preferable, the Ouroboros class of consensus protocols always sticks with the current chain.

Convenience re-exports

newtype SecurityParam Source #

Protocol security parameter

We interpret this as the number of rollbacks we support.

i.e., k == 0: we can't roll back at all k == 1: we can roll back at most one block, etc

NOTE: This talks about the number of blocks we can roll back, not the number of slots.

Constructors

SecurityParam 

Fields

Instances

Instances details
Eq SecurityParam Source # 
Instance details

Defined in Ouroboros.Consensus.Config.SecurityParam

Show SecurityParam Source # 
Instance details

Defined in Ouroboros.Consensus.Config.SecurityParam

Generic SecurityParam Source # 
Instance details

Defined in Ouroboros.Consensus.Config.SecurityParam

Associated Types

type Rep SecurityParamTypeType Source #

NoThunks SecurityParam Source # 
Instance details

Defined in Ouroboros.Consensus.Config.SecurityParam

Methods

noThunks ∷ Context → SecurityParamIO (Maybe ThunkInfo) #

wNoThunks ∷ Context → SecurityParamIO (Maybe ThunkInfo) #

showTypeOfProxy SecurityParamString #

type Rep SecurityParam Source # 
Instance details

Defined in Ouroboros.Consensus.Config.SecurityParam

type Rep SecurityParam = D1 ('MetaData "SecurityParam" "Ouroboros.Consensus.Config.SecurityParam" "ouroboros-consensus-0.1.0.2-inplace" 'True) (C1 ('MetaCons "SecurityParam" 'PrefixI 'True) (S1 ('MetaSel ('Just "maxRollbacks") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64)))