Specify difficulty adjustment.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
7 years ago · da7c5d9352
1 changed files with 158 additions and 6 deletions
--- a/protocol/protocol.tex
+++ b/protocol/protocol.tex
@ -122,6 +122,12 @@
 \makeatother
 \newcommand{\typecolon}{\;\hollowcolon\;}

+% We just want one ampersand symbol from boisik.
+\DeclareSymbolFont{bskadd}{U}{bskma}{m}{n}
+\DeclareFontFamily{U}{bskma}{\skewchar\font130 }
+\DeclareFontShape{U}{bskma}{m}{n}{<->bskma10}{}
+\DeclareMathSymbol{\binampersand}{\mathbin}{bskadd}{"EE}
+
 \newcommand{\hairspace}{~\!}

 \newcommand{\hfrac}[2]{\scalebox{0.8}{$\genfrac{}{}{0.5pt}{0}{#1}{#2}$}}
@ -326,6 +332,18 @@
 \newcommand{\squash}{\!\!\!}
 \newcommand{\caseif}{\squash\text{if }}
 \newcommand{\caseotherwise}{\squash\text{otherwise}}
+\newcommand{\sorted}{\mathsf{sorted}}
+\newcommand{\length}{\mathsf{length}}
+\newcommand{\mean}{\mathsf{mean}}
+\newcommand{\median}{\mathsf{median}}
+\newcommand{\clamp}[2]{\mathsf{clamp\,}_{#1}^{#2}}
+\newcommand{\Lower}{\mathsf{lower}}
+\newcommand{\Upper}{\mathsf{upper}}
+\newcommand{\bitlength}{\mathsf{bitlength}}
+\newcommand{\size}{\mathsf{size}}
+\newcommand{\mantissa}{\mathsf{mantissa}}
+\newcommand{\ToCompact}{\mathsf{ToCompact}}
+\newcommand{\ToTarget}{\mathsf{ToTarget}}
 \newcommand{\hexint}[1]{\mathbf{0x{#1}}}
 \newcommand{\dontcare}{\kern -0.06em\raisebox{0.1ex}{\footnotesize{$\times$}}}
 \newcommand{\ascii}[1]{\textbf{``\texttt{#1}"}}
@ -346,11 +364,14 @@
 \newcommand{\setof}[1]{\{{#1}\}}
 \newcommand{\range}[2]{\{{#1}\,..\,{#2}\}}
 \newcommand{\minimum}{\mathsf{min}}
+\newcommand{\maximum}{\mathsf{max}}
 \newcommand{\floor}[1]{\mathsf{floor}\!\left({#1}\right)}
-\newcommand{\ceiling}[1]{\mathsf{ceiling}\!\left({#1}\right)}
+\newcommand{\trunc}[1]{\mathsf{trunc}\!\left({#1}\right)}
+\newcommand{\ceiling}[1]{\mathsf{ceiling}\left({#1}\right)}
 \newcommand{\vsum}[2]{\smashoperator[r]{\sum_{#1}^{#2}}}
 \newcommand{\vxor}[2]{\smashoperator[r]{\bigoplus_{#1}^{#2}}}
 \newcommand{\xor}{\oplus}
+\newcommand{\band}{\binampersand}
 \newcommand{\mult}{\cdot}
 \newcommand{\rightarrowR}{\buildrel{\scriptstyle\mathrm{R}}\over\rightarrow}
 \newcommand{\leftarrowR}{\buildrel{\scriptstyle\mathrm{R}}\over\leftarrow}
@ -503,7 +524,23 @@
 \newcommand{\slowStartPeriod}{\term{slow-start period}}
 \newcommand{\halvingInterval}{\term{halving interval}}

+\newcommand{\PoWLimit}{\mathsf{PoWLimit}}
+\newcommand{\PoWAveragingWindow}{\mathsf{PoWAveragingWindow}}
 \newcommand{\PoWMedianBlockSpan}{\mathsf{PoWMedianBlockSpan}}
+\newcommand{\PoWMaxAdjustDown}{\mathsf{PoWMaxAdjustDown}}
+\newcommand{\PoWMaxAdjustUp}{\mathsf{PoWMaxAdjustUp}}
+\newcommand{\PoWDampingFactor}{\mathsf{PoWDampingFactor}}
+\newcommand{\PoWTargetSpacing}{\mathsf{PoWTargetSpacing}}
+\newcommand{\MeanTarget}{\mathsf{MeanTarget}}
+\newcommand{\MedianTime}{\mathsf{MedianTime}}
+\newcommand{\AveragingWindowTimespan}{\mathsf{AveragingWindowTimespan}}
+\newcommand{\MinActualTimespan}{\mathsf{MinActualTimespan}}
+\newcommand{\MaxActualTimespan}{\mathsf{MaxActualTimespan}}
+\newcommand{\ActualTimespan}{\mathsf{ActualTimespan}}
+\newcommand{\ActualTimespanDamped}{\mathsf{ActualTimespanDamped}}
+\newcommand{\ActualTimespanClamped}{\mathsf{ActualTimespanClamped}}
+\newcommand{\Threshold}{\mathsf{Threshold}}
+\newcommand{\ThresholdBits}{\mathsf{ThresholdBits}}

 \newcommand{\targetThreshold}{\term{target threshold}}
 \newcommand{\targetThresholds}{\term{target thresholds}}
@ -845,6 +882,8 @@ The notation $\typeexp{T}{\ell}$, where $T$ is a type and $\ell$ is an integer,
 means the type of sequences of length $\ell$ with elements in $T$. For example,
 $\bitseq{\ell}$ means the set of sequences of $\ell$ bits.

+The notation $\length(S)$ means the length of (number of elements in) $S$.
+
 The notation $T \subseteq U$ indicates that $T$ is an inclusive subset or subtype of $U$.

 $\byteseqs$ means the set of bit sequences constrained to be of length
@ -882,6 +921,9 @@ concatenating the elements of $S$ viewed as bit sequences. If the
 elements of $S$ are byte sequences, they are converted to bit sequences
 with the \emph{most significant} bit of each byte first.

+The notation $\sorted(S)$ means the sequence formed by sorting the elements
+of $S$.
+
 The notation $\GF{n}$ means the finite field with $n$ elements, and
 $\GFstar{n}$ means its group under multiplication.
 $\GF{n}[z]$ means the ring of polynomials over $z$ with coefficients
@ -897,7 +939,8 @@ $b$ an integer, means the result of raising $a$ to the exponent $b$.
 The notation $a \bmod q$, for $a \typecolon \Nat$ and $q \typecolon \PosInt$,
 means the remainder on dividing $a$ by $q$.

-The notation $a \xor b$ means the bitwise exclusive-or of $a$ and $b$,
+The notation $a \xor b$ means the bitwise-exclusive-or of $a$ and $b$,
+and $a \band b$ means the bitwise-and of $a$ and $b$. These are
 defined either on integers or bit sequences according to context.

 The notation $\vsum{i=1}{\mathrm{N}} a_i$ means the sum of $a_{\allN{}}$.\;
@ -910,16 +953,20 @@ sequences of integers.
 The notation $\floor{x}$ means the largest integer $\leq x$.
 $\ceiling{x}$ means the smallest integer $\geq x$.

+The notation $\bitlength(x)$, for $x \typecolon \Nat$, means the smallest integer
+$\ell$ such that $2^\ell > x$.
+
 The symbol $\bot$ is used to indicate unavailable information or a failed decryption.

 The following integer constants will be instantiated in \crossref{constants}:
 $\MerkleDepth$, $\NOld$, $\NNew$, $\MerkleHashLength$, $\hSigLength$,
 $\PRFOutputLength$, $\NoteCommitRandLength$, $\RandomSeedLength$, $\AuthPrivateLength$,
 $\NoteAddressPreRandLength$, $\MAXMONEY$, $\SlowStartInterval$, $\HalvingInterval$,
-$\MaxBlockSubsidy$, $\NumFounderAddresses$.
+$\MaxBlockSubsidy$, $\NumFounderAddresses$, $\PoWLimit$, $\PoWAveragingWindow$,
+$\PoWMedianBlockSpan$, $\PoWDampingFactor$, $\PoWTargetSpacing$.
 The bit sequence constant $\Uncommitted \typecolon \bitseq{\MerkleHashLength}$
-and the rational constant $\FoundersFraction \typecolon \Rat$ will also be defined
-in that section.
+and the rational constants $\FoundersFraction$, $\PoWMaxAdjustDown$, and
+$\PoWMaxAdjustUp$ will also be defined in that section.


 \nsection{Concepts}
@ -2031,6 +2078,16 @@ Define:
  \item $\MaxBlockSubsidy \typecolon \Nat := 1.25 \mult 10^9$ (\zatoshi)
  \item $\NumFounderAddresses \typecolon \Nat := 48$
  \item $\FoundersFraction \typecolon \Rat := \frac{1}{5}$
+  \item $\PoWLimit \typecolon \Nat := \begin{cases}
+          2^{243} - 1,&\squash\text{for the production network} \\
+          2^{251} - 1,&\squash\text{for the test network}
+        \end{cases}$
+  \item $\PoWAveragingWindow \typecolon \Nat := 17$
+  \item $\PoWMedianBlockSpan \typecolon \Nat := 11$
+  \item $\PoWMaxAdjustDown \typecolon \Rat := \frac{32}{100}$
+  \item $\PoWMaxAdjustUp \typecolon \Rat := \frac{16}{100}$
+  \item $\PoWDampingFactor \typecolon \Nat := 4$
+  \item $\PoWTargetSpacing \typecolon \Nat := 150$ (seconds).
 \end{formulae}


@ -3043,8 +3100,13 @@ started hashing the \header (according to the miner). \\ \hline
 \end{tabularx}
 \end{center}

+Let $\ThresholdBits$ be as defined in \crossref{diffadjustment}, and let $\PoWMedianBlockSpan$
+be the constant defined in \crossref{constants}.
+
 \begin{consensusrules}
  \item The \blockVersionNumber{} \MUST be 4.
+  \item For a \block at \blockHeight $\BlockHeight$, \nBitsField{} \MUST be equal to
+        $\ThresholdBits(\BlockHeight)$.
  \item The \block{} \MUST pass the difficulty filter defined in \crossref{difficulty}.
  \item \solution{} \MUST represent a valid Equihash solution as defined in \crossref{equihash}.
  \item \nTimeField{} \MUST be strictly greater than the median time of the previous
@ -3221,8 +3283,17 @@ ordering of bits in the solution encoding would require bit-reversal

 \nsubsubsection{Difficulty filter} \label{difficulty}

+Let $\ToTarget$ be as defined in \crossref{nbits}.
+
+Difficulty is defined in terms of a \targetThreshold, which is adjusted for each
+\block according to the algorithm defined in \crossref{diffadjustment}.
+
 The difficulty filter is unchanged from \Bitcoin, and is calculated using
 \SHAd on the whole \blockHeader (including $\solutionSize$ and $\solution$).
+The result is interpreted as a 256-bit integer represented in little-endian
+byte order, which \MUST be less than or equal to the \targetThreshold given by
+$\ToTarget(\nBitsField)$.
+

 \nsubsubsection{Difficulty adjustment} \label{diffadjustment}

@ -3231,9 +3302,89 @@ with simplifications and altered parameters, to adjust difficulty to target
 the desired 2.5-minute block time.
 Unlike \Bitcoin, the difficulty adjustment occurs after every block.

-\todo{Describe the algorithm.}
+The constants $\PoWLimit$, $\PoWAveragingWindow$, $\PoWMaxAdjustDown$, $\PoWMaxAdjustUp$,
+$\PoWDampingFactor$, and $\PoWTargetSpacing$ are instantiated in \crossref{constants}.
+
+Let $\ToCompact$ and $\ToTarget$ be as defined in \crossref{nbits}.

+Let $\nTime(\BlockHeight)$ be the value of the $\nTimeField$ field in the \header of the
+\block at \blockHeight $\BlockHeight$.

+Let $\nBits(\BlockHeight)$ be the value of the $\nBitsField$ field in the \header of the
+\block at \blockHeight $\BlockHeight$.
+
+\Blockheader fields are specified in \crossref{blockheader}.
+
+\vspace{1ex}
+\introlist
+Define:
+
+\begin{formulae}
+\hfuzz=10pt
+  \item $\mean(S) := \left( \vsum{i=1}{\length(S)} S_i \right) \raisebox{-0.4ex}{\scalebox{1.4}{/\,}} \length(S)$.
+  \item $\median(S) := \sorted(S)_{\ceiling{\length(S) / 2}}$
+  \item $\clamp{\Lower}{\Upper}(x) := \maximum(\Lower, \minimum(\Upper, x)))$
+  \item $\trunc{x} := \begin{cases}
+          \floor{x},&\caseif x \geq 0 \\
+          -\floor{-x},&\caseotherwise
+        \end{cases}$
+
+  \item $\AveragingWindowTimespan := \PoWAveragingWindow \mult \PoWTargetSpacing$
+  \item $\MinActualTimespan := \floor{\AveragingWindowTimespan \mult (1 - \PoWMaxAdjustUp)}$
+  \item $\MaxActualTimespan := \floor{\AveragingWindowTimespan \mult (1 + \PoWMaxAdjustDown)}$
+  \item $\MedianTime(\BlockHeight) := \median(\listcomp{\nTime(i) \for i \from
+                                              \maximum(0, \BlockHeight - \PoWMedianBlockSpan) \upto \BlockHeight - 1})$
+  \item $\ActualTimespan(\BlockHeight) := \MedianTime(\BlockHeight) - \MedianTime(\BlockHeight - \PoWAveragingWindow)$
+  \item $\ActualTimespanDamped(\BlockHeight) := \AveragingWindowTimespan + \trunc{\scalebox{0.98}{\hfrac{\ActualTimespan(\BlockHeight) - \AveragingWindowTimespan}{\PoWDampingFactor}}}$
+  \item $\ActualTimespanClamped(\BlockHeight) := \clamp{\MinActualTimespan}{\MaxActualTimespan}(\ActualTimespanDamped(\BlockHeight))$
+  \item $\MeanTarget(\BlockHeight) := \begin{cases}
+          \PoWLimit, \hspace{16em}\text{if } \BlockHeight \leq \PoWAveragingWindow \\
+          \mean(\listcomp{\ToTarget(\nBits(i)) \for i \from \BlockHeight - \PoWAveragingWindow \upto \BlockHeight - 1}),\\
+                     \hspace{20.7em}\text{otherwise}
+        \end{cases}$
+\end{formulae}
+
+\vspace{1ex}
+\introlist
+The \targetThreshold for a given \blockHeight $\BlockHeight$ is then calculated as:
+
+\begin{formulae}
+  \item $\Threshold(\BlockHeight) \hspace{0.43em} := \hspace{0.43em} \begin{cases}
+               \PoWLimit, \hspace{16em}\text{if } \BlockHeight = 0 \\
+               \minimum(\PoWLimit, \floor{\hfrac{\MeanTarget(\BlockHeight)}{\AveragingWindowTimespan}}
+                                   \mult \ActualTimespanClamped(\BlockHeight)),\\
+                          \hspace{20.7em}\text{otherwise}
+             \end{cases}$
+  \item $\ThresholdBits(\BlockHeight) := \ToCompact(\Threshold(\BlockHeight))$.
+\end{formulae}
+
+\pnote{
+The convention used for the height parameters to $\MedianTime$, $\ActualTimespan$,
+$\ActualTimespanDamped$, $\ActualTimespanClamped$, $\MeanTarget$, $\Threshold$, and
+$\ThresholdBits$ is that these functions use only information from \blocks \emph{preceding}
+the given \blockHeight.
+}
+
+\introlist
+\nsubsubsection{nBits conversion} \label{nbits}
+
+Deterministic conversions between a \targetThreshold and a ``compact" nBits value are not
+fully defined in the Bitcoin documentation \cite{Bitcoin-nBits}, and so we define them here:
+
+\begin{formulae}[leftmargin=1.5em,label=]
+  \item $\size(x) := \ceiling{\hfrac{\bitlength(x)}{8}}$
+  \item $\mantissa(x) := \floor{x \mult 256^{3 - \size(x)}}$
+  \item $\ToCompact(x) := \begin{cases}
+          \mantissa(x) + 2^{24} \mult \size(x),&\caseif \mantissa(x) < 2^{23} \\
+          \floor{\hfrac{\mantissa(x)}{256}} + 2^{24} \mult (\size(x)+1),&\caseotherwise
+        \end{cases}$
+  \item $\ToTarget(x) := \begin{cases}
+          0,&\caseif x \band 2^{23} = 2^{23} \\
+          (x \band (2^{23}-1)) \mult 256^{\floor{x / 2^{24}} - 3},&\caseotherwise.
+        \end{cases}$
+\end{formulae}
+
+\introlist
 \nsubsection{Calculation of Block Subsidy and Founders' Reward} \label{subsidies}

 \crossref{subsidyconcepts} defines the \blockSubsidy, \minerSubsidy, and \foundersReward.
@ -3860,6 +4011,7 @@ The errors in the proof of Ledger Indistinguishability mentioned in
 \subparagraph{2016.0-beta-1.13}

 \begin{itemize}
+    \item Specify the difficulty adjustment algorithm.
    \item Clarify some definitions of fields in a \blockHeader.
    \item Define $\PRFaddr{}$ in \crossref{keycomponents}.
 \end{itemize}