introduction.tex

\section{Introduction}

This document gives a specification of the changes
required to implement a both an Allegra-era and a Mary-era ledger. These ledgers share
a specification (and can share an implementation), with the exception of
a difference in one particular type. We abstract over this type and several
functions specific to it, which allows us to write a single specification for both versions of the
ledger, to which we refer as a \emph{ShelleyMA ledger specification}.

All aspects of the ledger not given in this document are as specified
in the Shelley ledger design and implementation~\cite{shelley_spec}.
Only additions and replacements of definitions of Shelley types, functions, rules, and transitions
are given here. Replacements are always given the same name as the
original definition in the Shelley specification, eg. the $\mathsf{UTXO}$ rule in the
Shelley specification is replaced with the $\mathsf{UTXO}$ rule given here.

\subsection{ShelleyMA, Allegra and Mary Eras}

The additional functionality that is introduced in the Allegra and Mary eras
is as follows :

\begin{itemize}
  \item \emph{Allegra} : Timelock scripts replace multi-signature scripts as the native
  ledger-iterpreted script type. This type of script, in addition to the
  clauses of the m-of-n multi-signature language, has constructors that
  allow users to constrain the upper and lower slots of the validity of a
  clause of the script. For example, one may specify that up to a given slot $s$,
  either key $k$ or $k'$ can sign the transaction for the script to be valid,
  whereas from $s$ onwards, only $k$'s signature can make the script valid.

  \item \emph{Mary} : Multi-asset support is added to the Allegra ledger, ie.
  to the Shelley ledger with timelock scripts. This includes changes to
  ledger accounting to accommodate multiple types of assets, as well as
  support for minting and burning of user-defined assets. This approach
  taken here was described initially in \cite{utxo_ma}.
\end{itemize}

Adding both timelock script and multi-asset support is done in a single specification
of the ShelleyMA ledger, as the transition rules are exactly the same for both
Mary and Allegra. The difference between the two is that all accounting is
done in terms of lovelace, ie. $\Coin$, in the Allegra era, whereas the Mary era
replaces the $\Coin$ type with a type the terms of which are bundles of arbitrary assets
(user-defined ones, as well as lovelace), which we call $\Value$.

In this specification, we represent all the places where the $\Coin$ type is used in Allegra,
and the $\Value$ type in Mary using an algebraic structure called a Token algebra. We choose
an abstract but fixed Token algebra $\ValMonoid$ for most of this specification.
See Section \ref{sec:coin-ma} for details.

This
\begin{itemize}
  \item makes this document is a specification for Allegra if $\ValMonoid = \Coin$, and
  \item makes it a specification for Mary if $\ValMonoid = \Value$.
\end{itemize}

Note that this specification is for two distinct eras, but we give only one translations, which is
from Shelley to Mary, see Section \ref{sec:chain}. This is because no changes to
chain or ledger types are required for Allegra.