Merge pull request #167 from cardano-hydrozoa/gf/spec-update

M2 spec update

Author: GeorgeFlerovsky

specification/backmatter/A-future-work.tex

@@ -62,8 +62,8 @@ \subsection{Eliminate post-dated transactions}%
 
 Currently, Hydrozoa relies on multi-signed post-dated transactions for two features:
 \begin{itemize}
-  \item Refunding a deposit after its deadline (\cref{h:l1-rule-based-transition}).
-  \item Transitioning the head from the multisig regime to the rule-based regime after the multisig regime timeout (\cref{h:l1-rule-based-transition}).
+  \item Refunding a deposit after its deadline (\cref{h:l1-rule-based-fallback}).
+  \item Fallback to the rule-based regime after the multisig regime timeout (\cref{h:l1-rule-based-fallback}).
 \end{itemize}
 These transactions must be multi-signed because they spend utxos from the head's multisig native address.
 However, they are only intended as a fallback when the peers fail to reach a timely consensus on the preferred alternatives. For this reason, the L2 consensus protocol requires them to be post-dated; in this way, they can be multi-signed ahead of time while the peers can still reach a timely consensus.
@@ -87,7 +87,7 @@ \subsection{Eliminate post-dated transactions}%
 \end{split}
 \end{equation*}
 
-This new observer script can classify its spent input as the treasury utxo or a deposit utxo. Then, it can decide whether to allow the rule-based transition or refund by comparing the transaction's time validity lower bound to the datum.
+This new observer script can classify its spent input as the treasury utxo or a deposit utxo. Then, it can decide whether to allow the rule-based fallback or refund by comparing the transaction's time validity lower bound to the datum.
 In other words, it allows a rule-based exit from a state managed by a native script.
 
 \subsection{Fragmented treasury}%
@@ -98,7 +98,7 @@ \subsection{Fragmented treasury}%
 
 Given the somewhat transient nature of state channels and the small numbers, we do not expect this constraint to affect most typical Hydrozoa use cases.
 However, if this becomes a problem, we could explore how to fragment a Hydrozoa head's treasury across multiple utxos.
-Observer scripts are helpful for fragmented treasuries because they facilitate an orderly transition of treasury fragments to the rule-based regime.
+Observer scripts are helpful for fragmented treasuries because they facilitate an orderly fallback of treasury fragments to the rule-based regime.
 
 \section{Hydrozoa network and L2 interoperability}%
 \label{h:hydrozoa-network-l2-interoperability}%

specification/backmatter/B-deterministic-rollout-algorithm.tex

@@ -8,7 +8,7 @@ \chapter{Deterministic rollout algorithm}%
 The Hydrozoa protocol strives to generate L1 transactions deterministically whenever they require consensus from all peers (i.e., in the multisig regime).
 This determinism allows the L2 consensus protocol and block validation procedure to focus on the essential contents of blocks without getting distracted in verifying the minutiae of the blocks' effects expressed as L1 transactions.
 
-This determinism is easy to accomplish for a refund (\cref{h:l1-multisig-refund}) and a transition to the rule-based regime (\cref{h:l1-rule-based-transition}) because each of those transactions has a bounded number of inputs/outputs that are guaranteed to fit within Cardano's transaction size limit.
+This determinism is easy to accomplish for a refund (\cref{h:l1-multisig-refund}) and the fallback to the rule-based regime (\cref{h:l1-rule-based-fallback}) because each of those transactions has a bounded number of inputs/outputs that are guaranteed to fit within Cardano's transaction size limit.
 On the other hand, settlement of a major block on L1 (\cref{h:l1-multisig-settlement}) may require a large number of L2 withdrawals to be paid out on L1, such that one or more rollout transactions may be needed to handle its overflow of L1 outputs.
 Finalization (\cref{h:l1-multisig-finalization}) is also unconstrained in the number of L2 withdrawals it can pay out.
 

specification/chapters/1-L1-multisig-regime.tex

@@ -33,6 +33,15 @@ \section{Utxo state}%
     \T{rolloutUtxos} &::& \T{UtxoSet^{L1}}
   \end{array}\right\}
 \end{equation*}
+
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/1-multisig-regime-utxo-state.pdf}}
+\end{center}
+\caption[Multisig regime utxo state on L1.]{The L1 utxo state of the multisig regime.}
+\label{fig:utxo-state-multisig-regime}
+\end{figure}
+
 Among these utxos, the head's treasury utxo is uniquely identified as the one holding the head's beacon token:
 \begin{enumerate}
   \item The policy ID corresponds to the head's native script (in minting policy form).
@@ -94,6 +103,14 @@ \section{Initialization}%
     \end{equation*}
 \end{itemize}
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/2-initialization-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Initialization tx.]{The Hydrozoa head's peers initialize its treasury utxo with an empty L2 ledger.}
+\label{fig:tx-initialization}
+\end{figure}
+
 \section{Deposit}%
 \label{h:l1-multisig-deposit}%
 
@@ -117,6 +134,14 @@ \section{Deposit}%
 The \code{refundAddress} and \code{refundDatum} fields define the address and datum to which the deposit's funds should be sent on L1 if the deposit is refunded.
 The funds in the deposit must be sufficient to pay for the refund transaction cost and create the refund utxo.
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/3-deposit-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Deposit tx.]{A user places some funds and instructions into a deposit utxo for a Hydrozoa Head.}
+\label{fig:tx-deposit}
+\end{figure}
+
 \section{Refund}%
 \label{h:l1-multisig-refund}%
 
@@ -132,6 +157,14 @@ \section{Refund}%
 The L2 consensus protocol (\cref{h:l2-consensus-on-refunds}) allows peers to obtain multi-signed post-dated refund transactions before posting their deposits on L1.
 It also allows them to immediately refund any deposits that its rules disqualify from being absorbed into the treasury.
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/4-refund-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Refund tx.]{The peers refund the deposit if it isn't absorbed into the treasury before the user's deadline.}
+\label{fig:tx-refund}
+\end{figure}
+
 \section{Settlement}%
 \label{h:l1-multisig-settlement}%
 
@@ -150,6 +183,15 @@ \section{Settlement}%
 It outputs the remaining withdrawals' aggregate funds as a single rollout utxo, sent to the head's native script address without a datum.
 Rollout transactions iteratively pay out more utxos from the rollout utxo, until all withdrawals are settled (\cref{h:l1-multisig-rollout}).
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/5-settlement-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Settlement tx.]{The peers absorb some deposits and pay out some withdrawals from the head's treasury.
+A rollout utxo can be produced to defer payout of some withdrawals for later.}
+\label{fig:tx-settlement}
+\end{figure}
+
 \section{Finalization}%
 \label{h:l1-multisig-finalization}%
 
@@ -164,10 +206,27 @@ \section{Finalization}%
 After the finalization transaction deals with the treasury and immediate/post-dated refund transactions deal with the unabsorbed deposits, no trace of the Hydrozoa head should be left in the L1 ledger.
 Any other utxos that remain at the head's native script address---assumed to be unrelated to the head---can be manually spent by the peers.
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/6-finalization-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Finalization tx.]{The peers pay out all remaining funds from the head's treasury.
+A rollout utxo can be produced to defer the payout of some withdrawals for later.}
+\label{fig:tx-finalization}
+\end{figure}
+
 \section{Rollout}%
 \label{h:l1-multisig-rollout}%
 
 The rollout utxo is spent in a rollout transaction, paying out some more withdrawals, and outputting a new rollout utxo with the aggregate funds of the rest of the withdrawals, if any remain.
 Further rollout transactions spend the shrinking rollout utxo, until all the withdrawals have been paid out (\cref{h:deterministic-rollout-rollouts}).
 
+\begin{figure}[H]
+\begin{center}
+\includegraphics[width=\txDiagramScale\linewidth]{\subfix{../images/tx-diagram/7-rollout-tx.pdf}}
+\end{center}
+\caption[Multisig regime: Rollout tx.]{The peers pay out some withdrawals out of a rollout utxo, possibly leaving some for later payout.}
+\label{fig:tx-rollout}
+\end{figure}
+
 \end{document}