Logo

hydra-heads

UnofficialPreliminary, reverse-engineered version published by the tx3 team for testing and exploration. It is not endorsed by the original protocol authors. Do not use in mainnet. • v0.0.0

About this Protocol

Cardano L1 transactions that drive a Hydra Head through its lifecycle

Parties

The participants involved in this protocol's transactions.

commitscriptµCommit validator address; locks a participant's committed UTxOs between `commit` and `collectCom`/`abort`.
participantA head participant wallet that submits L1 txs and signs snapshots.
headscriptµHead validator address; locks the head state UTxO carrying the ST token.
initialscriptµInitial validator address; locks each participant's PT between `init` and `commit`/`abort`.
depositscriptµDeposit validator address; locks UTxOs queued for an incremental commit.

Environment

Configuration values required to execute this protocol's transactions.

commit_script_refCIP-31 reference script UTxO for the µCommit validator on this network./$defs/UtxoRef
deposit_script_refCIP-31 reference script UTxO for the µDeposit validator on this network./$defs/UtxoRef
head_script_refCIP-31 reference script UTxO for the µHead validator on this network./$defs/UtxoRef
initial_script_refCIP-31 reference script UTxO for the µInitial validator on this network./$defs/UtxoRef
st_token_nameState Thread token name minted by the HeadPolicy (protocol-wide constant)./$defs/Bytes

Transactions

The transactions defined in this protocol, with their parameters, inputs, and outputs.

fanout

Finalize a Closed head past its deadline: burn ST + PTs and materialize the L2 UTxO set on L1.

Diagram

fanoutdeadline_slotfanout_lovelacefanout_recipientfinal_snapshot_numberfinal_utxo_hashhead_idhead_policy_refhead_refpt_count headscript fanout_recipient participant head_in output 1 output 2

Parameters

deadline_slotIntSlot at or after which the validator accepts the fanout (≥ contestation deadline).
fanout_lovelaceIntLovelace materialized back onto L1 from the final snapshot.
fanout_recipientBytesAddress receiving the consolidated fanout output.
final_snapshot_numberIntFinal snapshot number being materialized.
final_utxo_hashBytesFinal Merkle root of the L2 UTxO set being materialized.
head_idBytesHeadPolicy currency symbol of the head being finalized.
head_policy_refUtxoRefReference script UTxO carrying the HeadPolicy minting policy.
head_refUtxoRefThe µHead state UTxO (in `Closed`) being consumed.
pt_countIntNumber of participation tokens to burn alongside the ST.

Inputs

head_inheadscriptscript

Outputs

fanout_recipientnono
participantnono

contest

Post a newer snapshot during the contestation window to override the closed state.

Diagram

contestcontestercontestersdeadlinehead_idhead_out_lovelacehead_refparamspt_countsignaturesnapshot_numberutxo_hash headscript headscript participant head_in head_out output 2

Parameters

contesterBytesVkey hash of the participant posting this contest.
contestersList<Bytes>Updated contester list (existing entries with `contester` appended).
deadlineIntPOSIX-ms contestation deadline carried over (unchanged by contest).
head_idBytesHeadPolicy currency symbol of the target head.
head_out_lovelaceIntLovelace pinned on the new µHead `Closed` output.
head_refUtxoRefThe µHead state UTxO (in `Closed`) being consumed.
paramsObjectHead parameters carried over from the `Closed` datum.
pt_countIntNumber of participation tokens accompanying the ST on the head output.
signatureBytesMulti-party signature over the newer snapshot.
snapshot_numberIntNewer snapshot number being asserted.
utxo_hashBytesMerkle root of the newer snapshot's UTxO set.

Inputs

head_inheadscriptscript

Outputs

headscriptyesno
participantnono

init

Open a new Hydra head: consume a seed UTxO and mint ST + one PT per participant.

Diagram

initcontestation_periodhead_idhead_policy_refhead_utxo_lovelaceinitial_utxo_lovelaceparticipantspartiespt_countseed_ref participant headscript initialscript participant source seed head initial output 3

Parameters

contestation_periodIntContestation period in milliseconds, baked into the head parameters.
head_idBytesCurrency symbol of the HeadPolicy for this head (== head identifier).
head_policy_refUtxoRefReference script UTxO carrying the HeadPolicy minting policy.
head_utxo_lovelaceIntLovelace pinned on the µHead state UTxO (min-UTxO from protocol params).
initial_utxo_lovelaceIntLovelace pinned on the µInitial PT bucket UTxO.
participantsList<Bytes>Cardano vkey hashes of the L1 participants.
partiesList<Bytes>Hydra signing keys (vkey-style) for L2 multi-sig.
pt_countIntNumber of participation tokens to mint; must equal `participants` length.
seed_refUtxoRefSeed UTxO consumed to make the HeadPolicy currency symbol unique.

Inputs

sourceparticipantwallet
seedparticipantwallet

Outputs

headscriptyesno
initialscriptyesno
participantnono

recover

Reclaim a µDeposit UTxO after its deadline has passed.

Diagram

recoverdeposit_refrefund_lovelace depositscript participant deposit_in output 1

Parameters

deposit_refUtxoRefThe µDeposit UTxO being reclaimed.
refund_lovelaceIntLovelace value carried by the deposit, refunded to the depositor.

Inputs

deposit_indepositscriptscript

Outputs

participantnono

decrement

Release funds from the head onto L1 without closing it (incremental decommit).

Diagram

decrementhead_idhead_out_lovelacehead_refnew_snapshot_numbernew_utxo_hashparamspt_countrelease_recipientreleased_lovelacesignature headscript headscript participant release_recipient head_in head_out output 3 released

Parameters

head_idBytesHeadPolicy currency symbol of the target head.
head_out_lovelaceIntLovelace pinned on the new µHead `Open` output.
head_refUtxoRefThe µHead state UTxO (in `Open`) being consumed.
new_snapshot_numberIntNew snapshot number after the decommit.
new_utxo_hashBytesNew Merkle root of the committed UTxO set.
paramsObjectHead parameters carried over from the previous `Open` datum.
pt_countIntNumber of participation tokens accompanying the ST on the head output.
release_recipientBytesL1 address receiving the released funds.
released_lovelaceIntLovelace amount being released back to L1.
signatureBytesMulti-party signature over the new snapshot.

Inputs

head_inheadscriptscript

Outputs

headscriptyesno
release_recipientnono
participantnono

deposit

Lock new funds at µDeposit for an incremental commit, awaiting an L2 snapshot.

Diagram

depositdeadlinedeposit_cbordeposit_lovelacedeposit_utxo_lovelacehead_id participant depositscript participant source deposit_out output 2

Parameters

deadlineIntPOSIX-ms deadline after which the depositor may `recover` the funds.
deposit_cborBytesCanonical CBOR encoding of the L1 UTxOs being deposited.
deposit_lovelaceIntAda value of the bundle being deposited.
deposit_utxo_lovelaceIntMin-UTxO lovelace required on the produced µDeposit output.
head_idBytesHeadPolicy currency symbol of the target head.

Inputs

sourceparticipantwallet

Outputs

depositscriptyesno
participantnono

commit

Move a participant's PT from µInitial to µCommit, locking the funds they want inside the head.

Diagram

commitcommit_utxo_lovelacecommitted_cborcommitted_lovelacehead_idinitial_pt_refnew_commit_ref_idxnew_commit_ref_txparty initialscript participant commitscript participant pt_in funds commit_out output 2

Parameters

commit_utxo_lovelaceIntMin-UTxO lovelace required on the produced µCommit output.
committed_cborBytesCanonical CBOR encoding of the L1 UTxOs being committed.
committed_lovelaceIntAda value of the bundle being committed.
head_idBytesHeadPolicy currency symbol identifying the target head.
initial_pt_refUtxoRefThe µInitial UTxO carrying this participant's PT.
new_commit_ref_idxIntOutput index of the µCommit UTxO this commit will produce.
new_commit_ref_txBytesTx hash of the µCommit UTxO this commit will produce (self-reference for the redeemer).
partyBytesHydra party (signing key) committing the funds.

Inputs

pt_ininitialscriptscript
fundsparticipantwallet

Outputs

commitscriptyesno
participantnono

increment

Pull an L2-confirmed deposit into the head, bumping snapshot number and utxo hash.

Diagram

incrementdeposit_refhead_idhead_out_lovelacehead_refnew_snapshot_numbernew_utxo_hashparamspt_countpulled_lovelacesignature depositscript headscript headscript participant deposit_in head_in head_out output 2

Parameters

deposit_refUtxoRefThe µDeposit UTxO being absorbed into the head.
head_idBytesHeadPolicy currency symbol of the target head.
head_out_lovelaceIntLovelace pinned on the new µHead `Open` output, excluding the pulled amount.
head_refUtxoRefThe µHead state UTxO (in `Open`) being consumed.
new_snapshot_numberIntNew snapshot number after absorbing the deposit.
new_utxo_hashBytesNew Merkle root of the committed UTxO set.
paramsObjectHead parameters carried over from the previous `Open` datum.
pt_countIntNumber of participation tokens accompanying the ST on the head output.
pulled_lovelaceIntLovelace pulled in from the deposit.
signatureBytesMulti-party signature over the new snapshot.

Inputs

head_inheadscriptscript
deposit_indepositscriptscript

Outputs

headscriptyesno
participantnono

collect_com

Aggregate every µCommit UTxO into the head; transition Initial → Open.

Diagram

collect_comcommit_refhead_idhead_out_lovelacehead_refinitial_utxo_hashparamspt_count commitscript headscript headscript participant commit_in head_in head_out output 2

Parameters

commit_refUtxoRefA µCommit UTxO being absorbed into the head.
head_idBytesHeadPolicy currency symbol of the head being opened.
head_out_lovelaceIntLovelace pinned on the new µHead `Open` output.
head_refUtxoRefThe µHead state UTxO (in `Initial`) being consumed.
initial_utxo_hashBytesMerkle root of the initial committed UTxO set.
paramsObjectHead parameters carried over from the `Initial` datum.
pt_countIntNumber of participation tokens accompanying the ST on the head output.

Inputs

head_inheadscriptscript
commit_incommitscriptscript

Outputs

headscriptyesno
participantnono

close

Publish a confirmed snapshot to L1, transitioning the head Open → Closed.

Diagram

closedeadlinehead_idhead_out_lovelacehead_refinitial_contestersparamspt_countsignaturesnapshot_numberutxo_hash headscript headscript participant head_in head_out output 2

Parameters

deadlineIntPOSIX-ms contestation deadline (T_final = now + contestation_period).
head_idBytesHeadPolicy currency symbol of the target head.
head_out_lovelaceIntLovelace pinned on the new µHead `Closed` output.
head_refUtxoRefThe µHead state UTxO (in `Open`) being consumed.
initial_contestersList<Bytes>Initial contester set written into the `Closed` datum (typically empty).
paramsObjectHead parameters carried over from the `Open` datum.
pt_countIntNumber of participation tokens accompanying the ST on the head output.
signatureBytesMulti-party signature over the snapshot.
snapshot_numberIntSnapshot number being posted on close.
utxo_hashBytesMerkle root of the snapshot's UTxO set.

Inputs

head_inheadscriptscript

Outputs

headscriptyesno
participantnono

abort

Cancel an `Initial` head: burn ST + PTs, refund pending µCommit funds.

Diagram

abortcommit_refhead_idhead_policy_refhead_refinitial_refpt_burn_countrefund_lovelacerefund_recipient commitscript headscript initialscript participant refund_recipient commit_in head_in initial_in output 2 output 1

Parameters

commit_refUtxoRefA pending µCommit UTxO to refund.
head_idBytesHeadPolicy currency symbol of the head being aborted.
head_policy_refUtxoRefReference script UTxO carrying the HeadPolicy minting policy.
head_refUtxoRefThe µHead state UTxO (in `Initial`) being consumed.
initial_refUtxoRefA µInitial PT UTxO whose token will be burned.
pt_burn_countIntNumber of participation tokens to burn alongside the ST.
refund_lovelaceIntLovelace refunded back to the committing party.
refund_recipientBytesAddress receiving the refunded committed funds.

Inputs

head_inheadscriptscript
commit_incommitscriptscript
initial_ininitialscriptscript

Outputs

refund_recipientnono
participantnono

Profiles

Pre-configured sets of environment and party values for different deployment targets.

preview
commit_script_ref0x86288ee01e76589955d4a5cc4d7fe105bec1a3c4d14a1b48fc134dd20add66c4env
deposit_script_ref0x86288ee01e76589955d4a5cc4d7fe105bec1a3c4d14a1b48fc134dd20add66c4env
head_script_ref0x86288ee01e76589955d4a5cc4d7fe105bec1a3c4d14a1b48fc134dd20add66c4env
initial_script_ref0x86288ee01e76589955d4a5cc4d7fe105bec1a3c4d14a1b48fc134dd20add66c4env
st_token_name0x4879647261486561645631env
preprod
commit_script_ref0x16f275a5338119d7f65fadaa495ec07541eb19524509f3c40f8b1b7854298e46env
deposit_script_ref0x16f275a5338119d7f65fadaa495ec07541eb19524509f3c40f8b1b7854298e46env
head_script_ref0x16f275a5338119d7f65fadaa495ec07541eb19524509f3c40f8b1b7854298e46env
initial_script_ref0x16f275a5338119d7f65fadaa495ec07541eb19524509f3c40f8b1b7854298e46env
st_token_name0x4879647261486561645631env
mainnet
commit_script_ref0xa864514b20d560777e9b31e7d54391df4cf5a7958d174dc7f67ee27c45539da2env
deposit_script_ref0xa864514b20d560777e9b31e7d54391df4cf5a7958d174dc7f67ee27c45539da2env
head_script_ref0xa864514b20d560777e9b31e7d54391df4cf5a7958d174dc7f67ee27c45539da2env
initial_script_ref0xa864514b20d560777e9b31e7d54391df4cf5a7958d174dc7f67ee27c45539da2env
st_token_name0x4879647261486561645631env
Back to all Protocols