example illustration reward cycle image in spec

shelley/chain-and-ledger/formal-spec/epoch.tex

@@ -53,7 +53,7 @@ \subsection{Overview of the Reward Calculation}
   \item Epoch $e_{i}$ begins.
   \item Epoch $e_{i}$ ends.
     A snapshot is taken of the stake pool performance during epoch $e_{i}$.
-    A snapshot is also taken of the fee pot and the decayed deposit values.
+    A snapshot is also taken of the fee pot.
   \item The snapshots from (D) are stable and the reward calculation can begin.
   \item The reward calculation is finished and an update to the ledger state
     is ready to be applied.
@@ -113,6 +113,118 @@ \subsection{Overview of the Reward Calculation}
   Between E and F a single honest block is enough to ensure a random nonce.
 \end{note}
 
+\subsection{Example Illustration of the Reward Cycle}
+\label{sec:illustration-reward-cycle}
+
+\definecolor{epochColor}{rgb} {1.00,0.50,0.00}
+\definecolor{aliceColor}{rgb} {0.65,0.00,0.00}
+\definecolor{bobColor}{rgb} {0.00,0.50,0.00}
+\definecolor{bob2Color}{rgb} {0.00,0.95,0.00}
+\definecolor{snapshot1}{rgb} {0.00,0.00,0.90}
+\definecolor{snapshot2}{rgb} {0.00,0.60,0.90}
+
+\begin{tikzpicture}
+
+  % Axis
+  \draw [thick] (-0.2,0) -- (13,0);
+  \draw (0,-.2) -- (0, .2);
+  \draw (3,-.2) -- (3, .2);
+  \draw (6,-.2) -- (6, .2);
+  \draw (9,-.2) -- (9, .2);
+  \draw (12,-.2) -- (12, .2);
+  \node[align=center, below, color=epochColor] at (1.5,0.5)
+    {$e_1$};
+  \node[align=center, below, color=epochColor] at (4.5,0.5)
+    {$e_2$};
+  \node[align=center, below, color=epochColor] at (7.5,0.5)
+    {$e_3$};
+  \node[align=center, below, color=epochColor] at (10.5,0.5)
+    {$e_4$};
+
+  % Alice
+  % Alice's circle
+  \draw [aliceColor, fill] (0,3) circle [radius=0.5];
+  \node [white] at (0,3) {Alice};
+  % Alice's delegation line
+  \draw [->,thick, aliceColor] (0.4,2.65) to (2,0.05);
+  \node [aliceColor] at (2.2,2) {delegate to Bob};
+
+  % Bob
+  % Bob's circle
+  \draw [bobColor, fill] (0,-3) circle [radius=0.5];
+  \node [white] at (0,-3) {Bob};
+  % Bob's registration line
+  \draw [->,thick, bobColor] (0.2,-2.50) to (1,-0.05);
+  \node [align=left, below, bobColor] at (-0.5,-0.5) {initial pool \\ registration};
+  % Bob's re-registration line
+  \draw [->,thick, bob2Color] (0.45,-2.65) to (2.90,-0.05);
+  \node [bob2Color] at (2,-2.8) {re-registration};
+  % Bob's cached parameter change
+  \draw [->,thick, bob2Color] (2.9,-0.2) to [out=280, in=180] (3,-2)
+     to [out=0, in=290] (3.1,-0.2);
+
+  % Alice time to re-delegate
+  \draw [decorate, decoration = {brace, mirror, amplitude=10pt}, aliceColor, thick]
+    (3.2,-0.2) to (5.9,-0.2);
+  \node [align=center, below, aliceColor] at (5.1,-0.5)
+    {Alice's opportunity \\ to re-delegate \\ before Bob's new \\ parameters};
+
+  % Bob's blocks
+  % epoch e3
+  \draw [fill=bobColor,bobColor] (6.3,-.1) rectangle (6.5,-.3);
+  \draw [fill=bobColor,bobColor] (6.7,-.1) rectangle (6.9,-.3);
+  \draw [fill=bobColor,bobColor] (7.4,-.1) rectangle (7.6,-.3);
+  \draw [fill=bobColor,bobColor] (8.4,-.1) rectangle (8.6,-.3);
+
+  % epoch e4
+  \draw [fill=bob2Color,bob2Color] (9.9,-.1) rectangle (10.1,-.3);
+  \draw [fill=bob2Color,bob2Color] (10.4,-.1) rectangle (10.6,-.3);
+  \draw [fill=bob2Color,bob2Color] (10.8,-.1) rectangle (11.0,-.3);
+
+  % Snapshots
+  \draw [->,thick, snapshot1] (3,0.3) to [out=90,in=150] (9,0.5)
+     to [out=330,in=180] (10,-1) to [out=0,in=-135] (12,0) ;
+   \node [snapshot1] at (2.7,1.2) {mark};
+   \node [snapshot1] at (6,1.9) {set};
+   \node [snapshot1] at (9,0.9) {go};
+  \draw [fill=bobColor,bobColor] (9.4,-0.5) rectangle (9.6,-0.7);
+
+  \draw [->,thick, snapshot2] (6,0.3) to [out=90,in=150] (12,0.5)
+     to [out=330,in=180] (13,-1);
+   \node [snapshot2] at (5.7,1.2) {mark};
+   \node [snapshot2] at (9,1.9) {set};
+   \node [snapshot2] at (12,0.9) {go};
+  \draw [fill=bob2Color,bob2Color] (12.4,-0.5) rectangle (12.6,-0.7);
+\end{tikzpicture}
+
+Bob registers his stake pool in epoch $e_1$.
+Alice delegates to Bob's stake pool in epoch $e_1$.
+Just before the end of epoch $e_1$, Bob submits a stake pool re-registration,
+changing his pool parameters. The change in parameters is not immediate,
+as shown by the curved arrow around the epoch boundary.
+
+A snapshot is taken on the $e_1$/$e_2$ boundary. It is labeled ``mark'' initially.
+This snapshot includes Alice's delegation to Bob's pool, and Bob's pool parameters
+and listed in the initial pool registration certificate.
+
+If Alice changes her delegation choice any time during epoch $e_2$,
+she will never be effected by Bob's change of parameters.
+
+A new snapshot is taken on the $e_2$/$e_3$ boundary.
+The previous (darker blue) snapshot is now labeled ``set'', and the new one labeled ``mark''.
+The ``set'' snapshot is used for leader election in epoch $e_3$.
+The darker green squares below epoch $e_3$ depict the blocks produced by Bob's pool
+during epoch $e_3$.
+The darker green color indicates that they are associated with Bob's
+initial pool parameters.
+
+On the $e_3$/$e_4$ boundary, the darker blue snapshot is labeled ``go'' and
+the lighter blue snapshot is labeled ``set''.
+A dark green square is placed on the darker blue snapshot to indicate
+that Bob's stake pool performance during epoch $e_3$ will be used with
+the darker blue snapshot for the rewards which will be handed out
+at the beginning of epoch $e_5$.
+
 \subsection{Helper Functions and Accounting Fields}
 \label{sec:stake-dist-helpers}
 
@@ -1281,8 +1393,7 @@ \subsection{Reward Update Calculation}
 
 Note that fees are not explicitly removed from any account:
 the fees come from transactions paying them and are accounted for whenever
-transactions are processed and when the deposit decay value comes from returning
-smaller refunds for deposits than were paid upon depositing.
+transactions are processed.
 
 The $\fun{applyRUpd}$ function does the following:
     \begin{itemize}

shelley/chain-and-ledger/formal-spec/frontmatter.tex

@@ -25,6 +25,7 @@
            set version to 1.0,
            and changed the reward calculation so that $\eta$
              takes $d$ into account.}
+        \change{2021/05/17}{Jared Corduan}{FM (IOHK)}{Added Example Illustration.}
       \end{changelog}
       \clearpage%
 \renewcommand{\thepage}{\arabic{page}}