From 031de7ceca3e62c10268db1c4a168b840d1c06b3 Mon Sep 17 00:00:00 2001 From: Edsko de Vries Date: Mon, 19 Oct 2020 11:46:48 +0200 Subject: [PATCH] Minor corrections --- .../docs/report/chapters/consensus.tex | 25 ++++++++------ .../docs/report/chapters/intro.tex | 2 +- .../docs/report/chapters/ledger.tex | 6 ++-- .../docs/report/chapters/overview.tex | 34 ++++++++----------- 4 files changed, 33 insertions(+), 34 deletions(-) diff --git a/ouroboros-consensus/docs/report/chapters/consensus.tex b/ouroboros-consensus/docs/report/chapters/consensus.tex index f2563025e70..647b6bb97ad 100644 --- a/ouroboros-consensus/docs/report/chapters/consensus.tex +++ b/ouroboros-consensus/docs/report/chapters/consensus.tex @@ -33,11 +33,12 @@ \subsection{Overview} The consensus layer keeps the last $k$ blocks as a \emph{chain fragment} in memory (\cref{in-memory}); the rest of the chain is stored on disk. Similarly, -we keep a chain fragment in memory for every (upstream) node whose chain we are -following and whose blocks we may wish to adopt (\cref{header-body}). Before the -introduction of the hard fork combinator chain selection used to be given these -fragments to compare; as we will discuss in \cref{simplifying-chain-selection}, -however, this does not scale so well to hybrid chains. +we keep a chain fragment of \emph{headers} in memory for every (upstream) node +whose chain we are following and whose blocks we may wish to adopt +(\cref{header-body}). Before the introduction of the hard fork combinator chain +selection used to be given these fragments to compare; as we will discuss in +\cref{simplifying-chain-selection}, however, this does not scale so well to +hybrid chains. It turns out, however, that it suffices to look only at the block at the very tip of the chain\footnote{This does give rise to the question of what to do when @@ -58,10 +59,11 @@ \subsection{Overview} \subsection{Interface} \label{chain-selection:interface} -\todo{Why separate class?} We model chain selection as its own class\footnote{Here and elsewhere we elide superclass constraints that are not relevant to the discussion.}, separate from -the full consensus algorithm (\cref{class:ConsensusProtocol}) +the full consensus algorithm (\cref{class:ConsensusProtocol}); this will allow +us to more easily override this aspect of a consensus protocol when needed; see +\cref{consensus:override-leader-schedule}. \begin{lstlisting} class (..) => ChainSelection p where @@ -80,11 +82,11 @@ \subsection{Interface} \end{lstlisting} As mentioned in \cref{chain-selection:overview}, chain selection will only look -at the blocks at the tip of the ledger. Since we are defining consensus +at the headers at the tip of the ledger. Since we are defining consensus protocols independent from a concrete choice of ledger, however -(\cref{decouple-consensus-ledger}), we cannot use a concrete block type. -Instead, we merely say that the chain selection requires \emph{some} view -on blocks that it needs to make its decisions: +(\cref{decouple-consensus-ledger}), we cannot use a concrete block or header +type. Instead, we merely say that the chain selection requires \emph{some} view +on headers that it needs to make its decisions: \begin{lstlisting} type family SelectView p :: Type @@ -614,3 +616,4 @@ \subsection{Relation to the paper} \cite{cryptoeprint:2018:378} \section{Combinator: Override the leader schedule} +\label{consensus:override-leader-schedule} diff --git a/ouroboros-consensus/docs/report/chapters/intro.tex b/ouroboros-consensus/docs/report/chapters/intro.tex index 196484cfea3..b5227eb33a1 100644 --- a/ouroboros-consensus/docs/report/chapters/intro.tex +++ b/ouroboros-consensus/docs/report/chapters/intro.tex @@ -18,7 +18,7 @@ \chapter{Introduction} it is not aware of the presence of multiple competing chains or the roll backs required when switching from one chain to another. -The consensus layer meanwhile mediates between these two layers. It includes a +The consensus layer mediates between these two layers. It includes a bespoke storage layer that provides efficient access to the current ledger state as well as both (recent) \emph{past} ledger states (required in order to be able to validate and switch to competing chains) as well as (views on near) diff --git a/ouroboros-consensus/docs/report/chapters/ledger.tex b/ouroboros-consensus/docs/report/chapters/ledger.tex index e8d30ca446d..f80a2feeee0 100644 --- a/ouroboros-consensus/docs/report/chapters/ledger.tex +++ b/ouroboros-consensus/docs/report/chapters/ledger.tex @@ -197,7 +197,7 @@ \subsection{Introduction} Not all is lost, however. The stake distribution used by the Shelley ledger for the sake of the leadership check \emph{is not the \emph{current} stake distribution}, but the stake distribution as it was at a specific point in the -past. Moreover, the same stake distribution is then used for all leadership +past. Moreover, that same stake distribution is then used for all leadership checks in a given period of time.\footnote{The exact details of precisely \emph{how} the chain is split is not relevant to the consensus layer, and is determined by the ledger layer.} In the depiction below, the stake distribution @@ -306,8 +306,8 @@ \subsection{Ledger view} means that in the worst case scenario, with the intersection $k$ blocks back, we need to be able to evaluate $k + 1$ headers in order to adopt the alternative chain. However, the range of a forecast is based on \emph{slots}, not blocks; -since not every slot may be contain a block\todo{We should discuss that -somewhere}, the range needs to be sufficient to \emph{guarantee} to contain at +since not every slot may be contain a block\todo{We should discuss the block/slot +dichotomy somewhere}, the range needs to be sufficient to \emph{guarantee} to contain at least $k + 1$ blocks\footnote{Due to a bug, this is not the case for Shelley, where the effective maximum rollback is in fact $k - 1$; see \cref{shelley:forecasting}).}; we will come back to this in diff --git a/ouroboros-consensus/docs/report/chapters/overview.tex b/ouroboros-consensus/docs/report/chapters/overview.tex index 6bac7b71a6e..a02d213f94b 100644 --- a/ouroboros-consensus/docs/report/chapters/overview.tex +++ b/ouroboros-consensus/docs/report/chapters/overview.tex @@ -58,15 +58,11 @@ \subsection{Ledger} the consensus layer is responsible to the leadership check (\cref{consensus-responsibilities}), and when we need to decide if we should be producing a block in a particular slot, we need to know the ledger state at that -slot (even though we don't have a block for that slot \emph{yet}). +slot (even though we don't have a block for that slot \emph{yet}). It is also +required in the mempool; see \cref{mempool}. \section{Design Goals} -\begin{itemize} -\item Support for forecasting -\item Compositionality (HFC) -\end{itemize} - \subsection{Multiple consensus protocols} \label{multiple-consensus-protocols} @@ -86,10 +82,10 @@ \subsection{Support for multiple ledgers} For much the same reason that we must support multiple consensus protocols, we also have to support multiple ledgers. Indeed, we expect more changes in ledger than in consensus protocol; currently the Cardano block chain starts with a -Byron ledger and then transitions to a Shelley ledger; but further changes to +Byron ledger and then transitions to a Shelley ledger, but further changes to the ledger have already been planned (some intermediate ledgers currently code-named Allegra and Mary, as well as larger updates to Goguen, Basho and -Voltaire), but we all of the ledgers (Shelley up to including Voltaire) to all +Voltaire). All of the ledgers (Shelley up to including Voltaire) use the Praos consensus algorithm (potentially extended with the genesis chain selection rule, see \cref{future:genesis}). @@ -108,10 +104,10 @@ \subsection{Testability} The consensus layer is a critical component of the Cardano Node, the software that runs the Cardano blockchain. Since the blockchain is used to run the Ada cryptocurrency, it is of the utmost importance that this node is reliable; -network downtime or, worse, corruption of the blockchain cannot be tolerated. As -such the it is subject to much stricter correctness criteria than most software, -and must be tested thoroughly. To make this possible, we have to design for -testability. +network downtime or, worse, corruption of the blockchain, cannot be tolerated. +As such the consensus layer is subject to much stricter correctness criteria +than most software, and must be tested thoroughly. To make this possible, we +have to design for testability. \begin{itemize} \item We must be able to simulate various kinds of failures (disk @@ -190,13 +186,13 @@ \subsection{Adaptability and Maintainability} \subsection{Composability} \label{composability} -The consensus layer is a pretty complex piece of software; at the time we are -writing this techical report, the consensus layer consists of roughly 100,000 -lines of code. It is therefore important that we split it into into small -components that can be understood and modified independently from the rest of -the system. Abstraction, discussed in \cref{adaptability}, is one technique to -do that, but by no means the only. One other technique that we make heavy use of -is composability. We will list two examples here: +The consensus layer is a complex piece of software; at the time we are writing +this techical report, it consists of roughly 100,000 lines of code. It is +therefore important that we split it into into small components that can be +understood and modified independently from the rest of the system. Abstraction, +discussed in \cref{adaptability}, is one technique to do that, but by no means +the only. One other technique that we make heavy use of is composability. We +will list two examples here: \begin{itemize} \item As discussed in \cref{multiple-consensus-protocols} and