protocol-parameters.tex

\section{Protocol Parameters}
\label{sec:protocol-parameters}

\subsection{Updatable Protocol Parameters}
\label{sec:updatable-protocol-parameters}

The Shelley protocol parameters are listed in Figure~\ref{fig:defs:protocol-parameters}.
Some of the Shelley protocol parameters are common to the Byron era,
specifically, the common ones are $\var{a}$, $\var{b}$, $\var{maxTxSize}$, and
$\var{maxHeaderSize}$ (see the document~\cite{byron_ledger_spec}).

The type $\Ppm$ represents the names of the protocol parameters,
and $\mathsf{T_{ppm}}$ is the type of the protocol parameter $\var{ppm}$.
The type $\PParams$ is a finite map containing all the Shelley parameters,
indexed by their names.
We will explain the significance of each parameter as it comes up in
the calculations used in transition rules.
The type $\PParamsUpdate$ is similar to $\PParams$, but is
a partial mapping of the protocol parameters. It is used in the update
system explained in Section~\ref{sec:update}.

The type $\Coin$ is defined as an alias for the integers.
Negative values will not be allowed in UTxO outputs or reward accounts,
and $\Z$ is only chosen over $\N$ for its additive inverses.

Some helper functions are defined in Figure~\ref{fig:defs:protocol-parameters-helpers}.
The $\fun{minfee}$ function calculates the minimum fee that must be paid by a transaction.
This value depends on the protocol parameters and the size of the transaction.

Two time related types are introduced, $\Epoch$ and $\type{Duration}$.
A $\type{Duration}$ is the difference between two slots, as given by $\slotminus{}{}$.

Lastly, there are two functions, $\fun{epoch}$ and $\fun{firstSlot}$ for converting
between epochs and slots and one function $\fun{kesPeriod}$ for getting the cycle of a slot.
Note that $\Slot$ is an abstract type, while the constants are integers.
We use multiplication and division symbols on these distinct types
without being explicit about the types and conversion.

\begin{figure*}[htb]
  \emph{Abstract types}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}lr}
      \var{p} & \Ppm & \text{protocol parameter}\\
      \var{dur} & \Duration & \text{difference between slots}\\
      \var{epoch} & \Epoch & \text{epoch} \\
      \var{kesPeriod} & \KESPeriod & \text{KES period} \\
    \end{array}
  \end{equation*}
  %
  \emph{Derived types}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}l@{\qquad=\qquad}lr}
      \var{pp}
      & \PParams
      & \Ppm \to \mathsf{T_{ppm}}
      & \text{protocol parameters}
      \\
      \var{ppup}
      & \PParamsUpdate
      & \Ppm \mapsto \mathsf{T_{ppm}}
      & \text{protocol parameter update}
      \\
      \var{coin}
      & \Coin
      & \Z
      & \text{unit of value}
      \\
      \var{pv}
      & \ProtVer
      & \N\times\N
      & \text{protocol version}
    \end{array}
  \end{equation*}
  %
  \emph{Protocol Parameters}
  %
  \begin{equation*}
      \begin{array}{r@{~\in~}lr}
        \var{a} \mapsto \Z & \PParams & \text{min fee factor}\\
        \var{b} \mapsto \Z & \PParams & \text{min fee constant}\\
        \var{maxBlockSize} \mapsto \N & \PParams & \text{max block body size}\\
        \var{maxTxSize} \mapsto \N & \PParams & \text{max transaction size}\\
        \var{maxHeaderSize} \mapsto \N & \PParams & \text{max block header size}\\
        \var{poolDeposit} \mapsto \Coin & \PParams & \text{stake pool deposit}\\
        \var{E_{max}} \mapsto \Epoch & \PParams & \text{epoch bound on pool retirement}\\
        \var{n_{opt}} \mapsto \Npos & \PParams & \text{desired number of pools}\\
        \var{a_0} \mapsto \nonnegReals & \PParams & \text{pool influence}\\
        \tau \mapsto \unitInterval & \PParams & \text{treasury expansion}\\
        \rho \mapsto \unitInterval & \PParams & \text{monetary expansion}\\
        \var{d} \mapsto \{0,~1/100,~2/100,~\ldots,~1\} & \PParams & \text{decentralization parameter}\\
        \var{extraEntropy} \mapsto \Seed & \PParams & \text{extra entropy}\\
        \var{pv} \mapsto \ProtVer & \PParams & \text{protocol version}\\
        \var{minUTxOValue} \mapsto \Coin & \PParams & \text{minimum allowed value of a new \TxOut}\\
        \var{minPoolCost} \mapsto \Coin & \PParams & \text{minimum allowed stake pool cost}\\
      \end{array}
  \end{equation*}
  %
  \emph{Accessor Functions}
  %
  \begin{center}
    \fun{a},
    \fun{b},
    \fun{maxBlockSize},
    \fun{maxTxSize},
    \fun{maxHeaderSize},
    \fun{keyDeposit},
    \fun{poolDeposit},
    \fun{emax},
    \fun{nopt},
    \fun{influence},
    \fun{tau},
    \fun{rho},
    \fun{d},
    \fun{extraEntropy},
    \fun{pv},
    \fun{minUTxOValue},
    \fun{minPoolCost}
  \end{center}
  %
  \emph{Abstract Functions}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}lr}
      (\slotminus{}{}) & \Slot \to \Slot \to \Duration
                       & \text{duration between slots}
    \end{array}
  \end{equation*}
  %
  \caption{Definitions Used in Protocol Parameters}
  \label{fig:defs:protocol-parameters}
\end{figure*}

\subsection{Global Constants}
\label{sec:global-constants}

In additon to the updatable protocol parameters defined in
Section~\ref{sec:updatable-protocol-parameters},
there are ten parameters which cannot be changed by the update
system in Section~\ref{sec:update}.
We call these the global constants, as changing these values can only
be done by updating the software, i.e. a soft or a hard fork.
For the software update mechanism, see Section~\ref{sec:software-updates}.

The constants $\SlotsPerEpoch$ and $\SlotsPerKESPeriod$
represent the number of slots in an epoch/KES period (for a brief explanation
of a KES cryptography, see Section \ref{sec:crypto-primitives-shelley}). The KES period is defined
as a duration of slots which determines how often the KES private key must be evolved. The
KES private key must be evolved once at the start of each new KES period.  The duration of the
KES period is determined by $\SlotsPerKESPeriod$.  Any given KES key can be evolved up
to $\MaxKESEvo$-many times before a new operational certificate must be issued.
The constants $\StabilityWindow$ and $\RandomnessStabilisationWindow$ concern the chain stability.
The maximum number of time a KES key can be evolved before a pool operator
must create a new operational certificate is given by $\MaxKESEvo$.
\textbf{Note that if } $\MaxKESEvo$
\textbf{is changed, the KES signature format may have to change as well.}

The constant $\Quorum$ determines the quorum amount needed for votes on the
protocol parameter updates and the application version updates.

The constant $\MaxMajorPV$ provides a mechanism for halting outdated nodes.
Once the major component of the protocol version in the protocol parameters
exceeds this value, every subsequent block is invalid.
See Figures~\ref{fig:funcs:chain-helper} and~\ref{fig:rules:chain}.

The constant $\MaxLovelaceSupply$ gives the total number of lovelace in the system,
which is used in the reward calculation.
It is always equal to the sum of the values in the UTxO, plus the sum of the
values in the reward accounts, plus the deposit pot, plus the fee pot,
plus the treasury and the reserves.

The constant $\ActiveSlotCoeff$ is the value $f$ from the
Praos paper \cite{ouroboros_praos}.

Lastly, $\NetworkId$ determines what network, either mainnet or testnet, is expected.
This value will also appear inside every address, and transactions
containing addresses with an unexpected network ID are rejected.

\begin{figure*}[htb]
  \emph{Global Constants}
  %
  \begin{equation*}
    \begin{array}{r@{~\in~}lr}
      \SlotsPerEpoch & \N & \text{- slots per epoch} \\
      \SlotsPerKESPeriod & \N & \text{- slots per KES period} \\
      \StabilityWindow & \Duration &
      \begin{array}{r}
        \text{- window size for chain growth} \\
        \text{guarantees, see}\text{ in \cite{ouroboros_praos}}
      \end{array} \\
      \RandomnessStabilisationWindow & \Duration &
      \begin{array}{r}
        \text{- duration needed for epoch}\\
        \text{nonce stabilization}\\
      \end{array} \\
      \MaxKESEvo & \N & \text{- maximum KES key evolutions}\\
      \Quorum & \N & \text{- quorum for update system votes}\\
      \MaxMajorPV & \N & \text{- all blocks are invalid after this value}\\
      \MaxLovelaceSupply & \Coin & \text{- total lovelace in the system}\\
      \ActiveSlotCoeff & (0, 1] & \text{ - }f\text{ in \cite{ouroboros_praos}}\\
      \NetworkId & \Network & \text{- the network, mainnet or testnet}\\
    \end{array}
  \end{equation*}
  %
  \caption{Global Constants}
  \label{fig:defs:global-constants}
\end{figure*}

\begin{figure*}[htb]
  \emph{Helper Functions}
  %
  \begin{align*}
    \fun{minfee} & \in \PParams \to \Tx \to \Coin & \text{minimum fee}\\
    \fun{minfee} & ~\var{pp}~\var{tx} =
    (\fun{a}~\var{pp}) \cdot \fun{txSize}~\var{tx} + (\fun{b}~\var{pp})
    \\
    \\
    \fun{epoch} & \in ~ \Slot \to \Epoch & \text{epoch of a slot}
    \\
    \fun{epoch} & ~\var{slot} = \var{slot}~/~\SlotsPerEpoch
    \\
    \\
    \fun{firstSlot} & \in ~ \Epoch \to \Slot
               & \text{first slot of an epoch}
    \\
    \fun{firstSlot} & ~\var{e} = \var{e}~\cdot~\SlotsPerEpoch
    \\
    \\
    \fun{kesPeriod} & \in ~ \Slot \to \KESPeriod & \text{KES period of a slot}
    \\
    \fun{kesPeriod} & ~\var{slot} = \var{slot}~/~\SlotsPerKESPeriod
  \end{align*}
  %
  \caption{Helper functions for the Protocol Parameters}
  \label{fig:defs:protocol-parameters-helpers}
\end{figure*}

\clearpage