Skip to content

Initial draft of the Partial Fanout changes in the spec #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
+180 −55
Open

Initial draft of the Partial Fanout changes in the spec #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3cf76f4
Initial draft of the Partial Fanout changes in the spec
vrom911 Oct 15, 2025
0e7e374
Write clearer about bls
vrom911 Oct 27, 2025
79a5c91
Add limits and BLS papers
vrom911 Nov 3, 2025
269c871
Highlight new changes in RED
vrom911 Nov 3, 2025
e930e7c
Add accumulator to snapshot
vrom911 Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/Hydra/Protocol/Figures/head-protocol-states.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
\path[->] (open) edge [bend left=20] node {$\stClose$} (closed);
\path[->] (open) edge [loop above] node {$\mathsf{increment}$} (open);
\path[->] (open) edge [loop below] node {$\mathsf{decrement}$} (open);
\path[->] (closed) edge [bend left=20] node {$\stFanout$} (final);
\path[->] (closed) edge [bend left=20] node {\textcolor{red}{$\stFanout$ (complete)}} (final);
\path[->] (closed) edge [loop right] node {\textcolor{red}{$\stFanout$ (partial)}} (closed);
\path[->] (closed) edge [loop above] node {$\stContest$} (closed);
\path[->] (initial) edge [bend right=20] node {$\stAbort$} (final);
\end{tikzpicture}
Expand Down
29 changes: 15 additions & 14 deletions src/Hydra/Protocol/Figures/offchain-protocol.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@
$\Uinit \gets \bigcup_{j=1}^{n} U_j$ \;
% $\Out~(\hpSnap,(0,U_0))$ \;
$\hatmL \gets \Uinit$ \;
$\bar{\mc S} \gets \Sno(0, 0, [], \Uinit, \emptyset , \emptyset)$ \;
$\bar{\mc S} \gets \Sno(0, 0, [], \Uinit, \emptyset , \emptyset, \textcolor{red}{\accUTxO(\Uinit)})$ \;
$\hatv, \hats \gets 0$ \;
$\hatmT \gets \emptyset$ \;
$\tx_\omega \gets \bot$ \;
Expand Down Expand Up @@ -129,9 +129,9 @@
$U \gets U_{\mathsf{active}} \applytx \underline{\tx}_{\mathsf{req}}$ \;
$\hats \gets s$ \;
% TODO: DRY message creation
$\eta \gets \combine(U)$ \;
$\eta_\alpha \gets \mathsf{combine}(U_\alpha)$ \;
$\eta_\omega \gets \mathsf{combine}(\mathsf{outputs}(\tx_\omega))$ \;
\textcolor{red}{$\eta \gets \accUTxO(U)$} \;
\textcolor{red}{$\eta_\alpha \gets \accUTxO(U_\alpha)$} \;
\textcolor{red}{$\eta_\omega \gets \accUTxO(\mathsf{outputs}(\tx_\omega))$} \;
$\msSig_i \gets \msSign(\hydraSigningKey, (\cid || v || \hats || \eta || \eta_\alpha || \eta_\omega))$ \;
% TODO: use a seen snapshot to keep track of things easier
$\hatSigma \gets \emptyset$ \;
Expand Down Expand Up @@ -165,17 +165,18 @@
$\msCSig \gets \msComb(\hydraKeys^{setup}, \hatSigma)$ \;

% TODO: DRY message creation
$\eta \gets \combine(\hatmU)$ \;
\textcolor{red}{$A \gets \bar{\mc S}.A$} \;
\textcolor{red}{$\eta \gets \bar{\mc S}.U$} \;

$\eta_\alpha \gets \mathsf{combine}(U_\alpha)$ \;
\textcolor{red}{$\eta_\alpha \gets \bar{\mc S}.U_\alpha$} \;
$U_\omega \gets \mathsf{outputs}(\tx_\omega)$ \;
$\eta_\omega \gets \mathsf{combine}(U_\omega)$ \;
\textcolor{red}{$\eta_\omega \gets \bar{\mc S}.U_\omega$} \;
% NOTE: Implementation differs here and
% below as it stores seen version in seen
% snapshot and uses that to verify
\Req{} $\msVfy(\hydraKeysAgg, (\cid || \hatv || \hats || \eta || \eta_\alpha || \eta_\omega), \msCSig)$ \;
% create confirmed snapshot for later reference
$\bar{\mc S} \gets \Sno(\hatv, \hats, \hatmT, \hatmU, U_\alpha, U_\omega)$ \;
$\bar{\mc S} \gets \Sno(\hatv, \hats, \hatmT, \hatmU, U_\alpha, U_\omega, \bar{\mc S}.A)$ \;
$\bar{\mc S}.\sigma \gets \msCSig$ \;
%$\Out~(\hpSnap,(\bar{\mc S}.s,\bar{\mc S}.U))$ \;
$\forall \tx \in \mT_{\mathsf{req}} : \Out (\hpConf,\tx)$ \;
Expand Down Expand Up @@ -261,9 +262,9 @@
\begin{walgo}{0.6}
% CLOSE from client
\On{$(\hpClose)$ from client}{
$\eta \gets \combine(\bar{\mc S}.U)$ \;
$\eta_\alpha \gets \combine(\bar{\mc S}.U_\alpha$) \;
$\eta_\omega \gets \combine(\bar{\mc S}.U_\omega)$ \;
\textcolor{red}{$\eta \gets \hash(\bar{\mc S}.A)$} \;
\textcolor{red}{$\eta_\alpha \gets \hash(\accUTxO(\bar{\mc S}.U_\alpha))$} \;
\textcolor{red}{$\eta_\omega \gets \hash(\accUTxO(\bar{\mc S}.U_\omega))$} \;
$\xi \gets \bar{\mc S}.\sigma$ \;
% XXX: \hatv needed to distinguish between CloseType redeemer, explain how exactly?
$\PostTx{}~(\mtxClose, \hatv, \bar{\mc S}.v, \bar{\mc S}.s, \eta , \eta_\alpha, \eta_\omega, \xi)$ \;
Expand All @@ -275,9 +276,9 @@
% CLOSE TX
\On{$(\gcChainClose, \eta) \lor (\gcChainContest, s_{c}, \eta)$ from chain}{
\If{$\bar{\mc S}.s > s_{c}$}{
$\eta \gets \combine(\bar{\mc S}.U)$ \;
$\eta_\alpha \gets \combine(\bar{\mc S}.U_\alpha$) \;
$\eta_\omega \gets \combine({\bar{\mc S}.U_\omega})$ \;
\textcolor{red}{$\eta \gets \hash(\bar{\mc S}.A)$} \;
\textcolor{red}{$\eta_\alpha \gets \hash(\accUTxO(\bar{\mc S}.U_\alpha))$} \;
\textcolor{red}{$\eta_\omega \gets \hash(\accUTxO(\bar{\mc S}.U_\omega))$} \;
$\xi \gets \bar{\mc S}.\sigma$ \;
% XXX: \hatv needed to distinguish between CloseType redeemer, explain how exactly?
$\PostTx{}~(\mtxContest, \hatv, \bar{\mc S}.v, \bar{\mc S}.s, \eta , \eta_\alpha, \eta_\omega , \xi)$ \;
Expand Down
35 changes: 27 additions & 8 deletions src/Hydra/Protocol/OffChain.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,16 @@ \section{Off-Chain Protocol}\label{sec:offchain}
full life-cycle of a Hydra head on-chain, this section completes the picture by
defining how the protocol behaves off-chain and notably the relationship between
on- and off-chain semantics. Participants of the protocol are also called Hydra
head members, parties or simply protocol actors. The protocol is specified as a
reactive system that processes three kinds of inputs:
head members, parties or simply protocol actors.

\noindent \textcolor{red}{The off-chain protocol coordinates BLS accumulator operations (see Section~\ref{sec:bls-accumulators})
for partial fanout support. When UTxO sets are too large for single transactions (see Section~\ref{sec:bls-accumulators}
for limits details), the off-chain protocol automatically falls back to partial distribution using
exclusion proofs, ensuring all UTxOs can be distributed across multiple transactions
while maintaining cryptographic integrity.}

The protocol is specified as a reactive system that processes three kinds of inputs:

\begin{enumerate}
\item On-chain protocol transactions as introduced in
Section~\ref{sec:on-chain}, which are posted to the mainchain and can be
Expand All @@ -23,8 +31,7 @@ \section{Off-Chain Protocol}\label{sec:offchain}
\item $\mathtt{decrementTx}$: removes UTxO from an open head
\item $\mathtt{closeTx}$: closes a head
\item $\mathtt{contestTx}$: contests a closed head
% NOTE: fanout not mentioned because not needed in off-chain protocol
% description
\item \textcolor{red}{$\mathtt{fanoutTx}$: distributes UTxOs from a closed head (partial or complete)}
\end{itemize}
Also, a special input when time advanced on chain may be used:
\begin{itemize}
Expand Down Expand Up @@ -136,12 +143,13 @@ \subsection{Variables}
$\bar{\mc S}.U$ & snapshotted UTxO set \\ \hline
$\bar{\mc S}.U_\alpha$ & pending UTxO to increment \\ \hline
$\bar{\mc S}.U_\omega$ & pending UTxO to decrement \\ \hline
\textcolor{red}{$\bar{\mc S}.A$} & \textcolor{red}{BLS accumulator of the UTxO set} \\ \hline
$\bar{\mc S}.\sigma$ & multisignature \\ \hline
\end{tabular}
\end{center}
\end{itemize}

where constructor $\text{snObj}(v, n, T, U, U_\alpha, U_\omega)$ initializes a
where constructor $\text{snObj}(v, n, T, U, U_\alpha, U_\omega, \textcolor{red}{A})$ initializes a
new snapshot object with $\bar{\mathcal{S}}.\sigma = \emptyset$. \\

Additionally, deposit objects are created using
Expand Down Expand Up @@ -184,7 +192,7 @@ \subsubsection{Initializing the head}
$\hatv = 0$, as well as snapshot number $\hats = 0$. No deposit transaction
$\tx_{\alpha} = \bot$ and no decrement transaction $\tx_{\omega} = \bot$ are
pending, and the last confirmed snapshot is initialized accordingly
$\bar{\mc S} \gets \blue{\Sno(0, 0, [], \Uinit, \emptyset, \emptyset)}$.
$\bar{\mc S} \gets \blue{\Sno(0, 0, [], \Uinit, \emptyset, \emptyset, \accUTxO(\Uinit))}$.

\subsubsection{Processing transactions off-chain}

Expand Down Expand Up @@ -280,8 +288,8 @@ \subsubsection{Processing transactions off-chain}
multisignature $\msCSig$ and $\Req$ it to be valid (constructing the signed
message as in $\hpRS$). If everything is fine, the snapshot can be considered
confirmed by creating the snapshot object
$\bar{\mc S} \gets \Sno(\hatv, \hats, \hatmT, \hatmU, U_{\alpha}, \mathsf{outputs}(\tx_{\omega}))$
and storing the multi-signature $\msCSig$ in it for later reference. In case
$\bar{\mc S} \gets \Sno(\hatv, \hats, \hatmT, \hatmU, U_{\alpha}, \mathsf{outputs}(\tx_{\omega}), \textcolor{red}{A})$
where \textcolor{red}{$A = \accUTxO(\hatmU)$ is the accumulator of the UTxO set}, and storing the multi-signature $\msCSig$ in it for later reference. In case
there is a pending decommit, any participant can now submit a \mtxDecrement{}
transaction by providing the just confirmed snapshot with its digests of the
active UTxO set $\eta$ and the to be removed UTxO set $\eta_{\omega}$. If, however, there
Expand All @@ -306,6 +314,16 @@ \subsubsection{Processing transactions off-chain}
is incremented on each \mtxIncrement{} transaction as described in
Section~\ref{sec:increment-tx}

\textcolor{red}{\dparagraph{$\mathtt{fanoutTx}$.}\quad Upon observing a \mtxFanout{}
transaction, the distributed UTxOs are removed from the local state tracking.
If this was a partial fanout (not all UTxOs were distributed), the head remains
in $\stClosed$ state with updated accumulator containing the remaining UTxOs.
If this was a complete fanout (all UTxOs distributed), the head transitions to
$\stFinal$ state. The off-chain protocol must coordinate partial fanout to
ensure proper selection of UTxO subsets and generation of exclusion proofs.
\todo{Add detailed off-chain protocol for partial fanout coordination, including
selection strategy for UTxO subsets.}}

\subsubsection{Closing the head}

\dparagraph{$\hpClose$.}\quad In order to close a head, a client issues the
Expand Down Expand Up @@ -388,6 +406,7 @@ \subsection{Rollbacks and protocol changes}\label{sec:rollbacks}
\input{Hydra/Protocol/Figures/offchain-protocol}

\todo{In figure: $\combine$ on UTxO slightly different than on commits}
\textcolor{red}{\todo{Update off-chain protocol to support partial fanout coordination}}

%%% Local Variables:
%%% mode: latex
Expand Down
Loading
Loading