transactions.tex

\section{Transactions}
\label{sec:transactions}

This section outlines the changes that are needed to the transaction
structure to enable phase-2 scripts to validate
the minting of tokens, spending outputs, verifying certificates, and
verifying withdrawals.
%
Figure \ref{fig:defs:utxo-shelley-1} gives the modified transaction types and helper functions.
We make the following changes and additions:

\begin{itemize}
  \item $\ScriptIntegrityHash$ is the type of a hash of script execution
  related data. It is the hash of $\fun{txrdmrs}$ and relevant protocol parameters.

  \item $\ScriptPhOne$ is the type of phase-1 scripts.

  \item $\ScriptPhTwo$ is the type of phase-2 scripts.

  \item $\Data$ is a type for communicating data to script.  It is kept abstract here.

  \item $\Script$ is the type of all scripts, both phase-1 and phase-2.

  \item $\IsValid$ is a tag that indicates that a transaction
  expects that all its phase-2 scripts will be validated.
  This tag is added by the block creator when
  constructing a block, and its correctness is verified as part of the script execution.

  \item $\Datum$ is a type alias for the $\Data$ type, used to signify that
  terms of this type are intended to be used strictly as datum objects.

  \item $\Redeemer$ is also a type alias for the $\Data$ type, used to signify that
  terms of this type are intended to be used strictly as redeemers.

  \item $\TxOut$ is the type of transaction outputs. These are extended to include
  an optional hash of a datum. Note that \emph{any} output can
  optionally include such a hash, even though only phase-2 scripts
  can actually use the hash value. Since it is in general impossible for the ledger implementation to
  know at the time of transaction creation whether or not an output belongs to a phase-2
  script, we simply allow any output to contain a hash of a datum.

  \item $\Tag$ lets us differentiate what a script
  can validate, i.e. \\
  \begin{tabular}{l@{~to validate~}l}
  $\mathsf{Spend}$ & spending a script UTxO entry; \\
  $\mathsf{Mint}$ & minting tokens; \\
  $\mathsf{Cert}$  & certificates with script credentials; and  \\
  $\mathsf{Rewrd}$ & reward withdrawals from script addresses.
  \end{tabular}

  \item $\RdmrPtr$ is a pair of a tag and an index. This type is
  used to index the Plutus redeemers that are included in a transaction, as discussed
  below.

\end{itemize}

We add the following helper functions:

\begin{itemize}
  \item $\fun{language}$ selects the language of a phase-2 script, and $\Nothing$ in case
  the script is phase-1.
  \item $\fun{hashData}$ hashes a value of type $\Data$.
  \item $\fun{hashScriptIntegrity}$ hashes the protocol parameters and data relevant to script execution.
  In particular, the redeemer structure, and the datum objects.
\end{itemize}

\begin{figure*}[htb]
  \emph{Abstract types}
  %
  \begin{equation*}
    \begin{array}{l@{\quad\quad\quad\quad}r}
      \ScriptIntegrityHash & \text{Script data hash}\\
      \ScriptPlutus & \text{Plutus core scripts} \\
      \Data & \text{Generic script data}
    \end{array}
  \end{equation*}
  %
  \emph{Script types}
  %
  \begin{equation*}
    \begin{array}{l@{\qquad=\qquad}lr}
      \ScriptPhTwo & \ScriptPlutus \\
      \Script & \ScriptPhOne \uniondistinct \ScriptPhTwo \\
      \IsValid & \Bool \\
      \Datum & \Data \\
      \Redeemer & \Data
    \end{array}
  \end{equation*}
%
  \emph{Derived types}
  %
  \begin{equation*}
    \begin{array}{l@{\qquad=\qquad}lr}
      \ValidityInterval
      & \Slot^? \times \Slot^?
      \\
      \TxOut
      & \Addr \times \Value \times \hldiff{\DataHash^?}
      \\
      \Tag
      & \{\mathsf{Spend},~\mathsf{Mint},~\mathsf{Cert},~\mathsf{Rewrd}\}
      \\
      \RdmrPtr
      & \Tag \times \Ix
    \end{array}
  \end{equation*}
  %
  \emph{Helper Functions}
  %
  \begin{align*}
    \fun{language}& : \Script \to \Language^?\\
    \fun{hashData}& : \Data \to \DataHash
    \nextdef
    \fun{getCoin}& : \TxOut \to \Coin \\
    \fun{getCoin}&~\hldiff{{(\_, \var{v}, \_)}}  = \fun{valueToCoin}~{v}
  \end{align*}
  %
  \begin{align*}
  &\fun{hashScriptIntegrity} : \PParams \to \powerset{\Language} \to (\RdmrPtr \mapsto \Redeemer \times \ExUnits) \\
  &~~~~ \to (\DataHash \mapsto \Datum) \to \ScriptIntegrityHash^? \\
  &\fun{hashScriptIntegrity}~{pp}~{langs}~{rdmrs}~{dats} =  \\
                    &~~~~ \begin{cases}
                          \Nothing & rdmrs = \emptyset \land langs = \emptyset \land dats = \emptyset \\
                          \fun{hash} (rdmrs, dats, \{ \fun{getLanguageView}~pp~l \mid l \in langs \}) & \text{otherwise}
                        \end{cases}
  \end{align*}
  \caption{Definitions for Transactions}
  \label{fig:defs:utxo-shelley-1}
\end{figure*}


\begin{figure*}[htb]
  \emph{Transaction Types}
  %
  \begin{equation*}
    \begin{array}{r@{~~}l@{~~}l@{\qquad}l}
      \TxWitness =
       & (\VKey \mapsto \Sig) & \fun{txwitsVKey} & \text{VKey signatures}\\
       & \times ~(\ScriptHash \mapsto \Script)  & \fun{txscripts} & \text{All scripts}\\
       & \times~ \hldiff{(\DataHash \mapsto \Datum)} & \hldiff{\fun{txdats}} & \text{All datum objects}\\
       & \times ~\hldiff{(\RdmrPtr \mapsto \Redeemer \times \ExUnits)}& \hldiff{\fun{txrdmrs}}& \text{Redeemers/budget}
    \end{array}
  \end{equation*}
  %
  \begin{equation*}
    \begin{array}{r@{~~}l@{~~}l@{\qquad}l}
      \TxBody =
      & \powerset{\TxIn} & \fun{txins}& \text{Inputs}\\
      & \times ~\hldiff{\powerset{\TxIn}} & \hldiff{\fun{collateral}} & \text{Collateral inputs}\\
      & \times ~(\Ix \mapsto \TxOut) & \fun{txouts}& \text{Outputs}\\
      & \times~ \seqof{\DCert} & \fun{txcerts}& \text{Certificates}\\
       & \times ~\Value  & \fun{mint} &\text{A minted value}\\
       & \times ~\Coin & \fun{txfee} &\text{Total fee}\\
       & \times ~\ValidityInterval & \fun{txvldt} & \text{Validity interval}\\
       & \times~ \Wdrl  & \fun{txwdrls} &\text{Reward withdrawals}\\
       & \times ~\Update^?  & \fun{txUpdates} & \text{Update proposals}\\
       & \times ~\hldiff{\powerset{\KeyHash}} & \hldiff{\fun{reqSignerHashes}} & \text{Hashes of VKeys passed to scripts}\\
       & \times ~\hldiff{\ScriptIntegrityHash^?} & \hldiff{\fun{scriptIntegrityHash}} & \text{Hash of script-related data}\\
       & \times ~\AuxiliaryDataHash^? & \fun{txADhash} & \text{Auxiliary data hash}\\
       & \times ~\hldiff{\Network^?} & \hldiff{\fun{txnetworkid}} & \text{Tx network ID}\\
    \end{array}
  \end{equation*}
  %
  \begin{equation*}
    \begin{array}{r@{~~}l@{~~}l@{\qquad}l}
      \Tx =
      & \TxBody & \fun{txbody} & \text{Body}\\
      & \times ~\TxWitness & \fun{txwits} & \text{Witnesses}\\
      & \times ~\hldiff{\IsValid} & \hldiff{\fun{isValid}}&\text{Validation tag}\\
      & \times ~\AuxiliaryData^? & \fun{auxiliaryData}&\text{Auxiliary data}\\
    \end{array}
  \end{equation*}
  \caption{Definitions for transactions, cont.}
  \label{fig:defs:utxo-shelley-2}
\end{figure*}

\textbf{Auxiliary Data. } The auxiliary data in an Alonzo transaction has the same structure as
in a ShelleyMA transaction, but can additionally contain phase-2 scripts.

\subsection{Witnessing}
Figure \ref{fig:defs:utxo-shelley-2} defines the witness type, $\TxWitness$.  This contains everything
in a transaction that is needed for witnessing, namely:

\begin{itemize}
  \item VKey signatures;
  \item a map of scripts indexed by their hashes, including phase-2 scripts;
  \item a map of terms of type $\Datum$ indexed by their hashes, containing all required datum objects
  as well as any optional ones that are posted for communication; and
  \item a map of a pair of a $\Redeemer$ object and an $\ExUnits$ value indexed by $\RdmrPtr$,
  containing the redeemers and execution units budgets.
\end{itemize}

Note that there is a difference between the way scripts and datum objects are included in
a transaction (as a set) versus how redeemers are included
(as an indexed structure).

\begin{description}
\item
  [Hash reference (script/datum object):]
  Scripts and datum objects are referred to explicitly via their hashes,
  which are included in the $\UTxO$ or the transaction. Thus, they can be
  looked up in the transaction without any key in the data structure.

  \item[No hash reference (redeemers):] For redeemers,
  we use a reverse pointer approach and
  index the redeemer by a pointer to the item for which it will be used.
  For details on how a script finds its redeemer, see Section~\ref{sec:scripts-inputs}.
\end{description}

\subsection{Transactions}
\label{sec:transctions}
We have also made the following changes to
the body of the transaction:

\begin{itemize}
  \item The new field $\fun{collateral}$ is used to specify the \emph{collateral inputs}
    that are collected (into the fee pot) to cover a percentage of
    transaction fees (usually $100$ percent or more)
    \emph{in case the transaction contains failing phase-2 scripts}. They are not collected otherwise.
    The purpose of the collateral is to cover the resource use costs
    incurred by block producers running scripts that do not validate.

    Collateral inputs behave like regular inputs, except that they
    must be VKey locked and can only contain Ada. See \ref{fig:functions:utxo}.

    It is permitted to use the same inputs as both collateral and a regular inputs, as exactly
    one set of inputs is ever collected: collateral ones in the case of script failure, and regular inputs
    in the case when all scripts validate.

  \item There is a new field called $\fun{reqSignerHashes}$ that is used to specify a set of hashes
  of keys that must sign the transaction in addition to the signatures required to validate
  spending from VKey addresses, checking certificate validity, and validating reward withdrawals.
  This field is there to allow users to add signatures that
  \begin{itemize}
    \item cannot be stripped from a transaction without invalidating it in phase 1 (ie. the
    validation phase where fees are not collected for the validation work done)
    \item are not attached to any validation being done in phase 1, such as VKey output spending
  \end{itemize}

  This is a field where users can add signatures that a phase-2 script requires internally -
  the transaction and the ledger are otherwise unaware of what signatures are expected by these scripts.

  \item We include a hash of some script-related data, specifically the redeemers and protocol parameters,
    with accessor $\fun{scriptIntegrityHash}$.

  \item We include the ID of the network on which the transaction lives, $\fun{txnetworkid}$.
  This is in addition to the network ID's already included in the reward and output addresses.
\end{itemize}

A complete transaction is comprised of:

\begin{enumerate}
  \item the transaction body,
  \item all the information that is needed to witness transactions,
  \item the $\IsValid$ tag, which indicates whether all scripts
  that are executed during the script execution phase validate.
  The correctness of the tag is verified as part of the ledger rules, and the block is
  deemed to be invalid if it is applied incorrectly.
  It can be used to re-apply blocks without script re-validation.
  Since this tag is not part of the body, i.e. it is not signed, the block producer can
  (and must) choose the correct value.
  \item any auxiliary data.
\end{enumerate}
\begin{note}
  In the implementation the $\IsValid$ tag is part of a user-submitted
  transaction, but it is ignored and re-computed by the block
  producer.
\end{note}
\subsection{Additional Role of Signatures on TxBody}

The transaction body and the UTxO must uniquely determine all the data
that can influence on-chain transfer of value.
This is so that the signatures can ensure that this data is not tampered with.
As before, a transaction that does not include the correct signatures is completely invalid.
Thus, all data that influences script validation outcomes must also be determined by the body.

Scripts and datum objects whose hashes are specified on-chain do not require to be
signed when included in a transaction. That is, script hashes locking UTxOs (as well as
with the datum hashes these UTxOs contain), and also the posted
certificates, minting policies, and reward addresses do not need to be signed.
The optional datum objects, however, could be stripped from the transaction without making
it invalid. The optional datums are stored in the same map the required ones, so,
for this reason, we do include all datum objects in the script integrity hash calculation.
%
The hash of the indexed redeemer structure and the protocol parameters that are used by
script interpreters are included in the body of the transaction, as these are composed
by the transaction author rather than
fixed via a hash on the ledger. In the future, other parts of the ledger
state may also need to be included in this hash, if they are passed as
arguments to a new script interpreter.

\subsection{Data required for script validation.}
\label{sec:script-data}

The body of the transaction, alongside the witness data, are required for script validation.
Script validation should not depend on the auxiliary data in any way. Script validation
may require certain optional datums to be posted. For this reason, we include optional
datums in the part of the transaction (the witnesses) which scripts do see.
Any metadata that a user wants to expose to a transaction can be included in the
redeemer, whose purpose is to contain all user-supplied data relevant to validation.

For more about what scripts do and do not inspect, see Section~\ref{sec:txinfo}.