Cardano as L1 blockchain

Sugar Rush — Gummiworm’s first proof-of-concept usecase — uses its own domain-specific L2 ledger, but it currently targets Cardano as the L1 blockchain.

Constants for Cardano/EUTXO

We use these constants for CIP-67 token prefixes and top-level metadata tags:

const HYDR: number = 4937
const HMRW: number = 4679
const VOTE: number = 8683

State

A Gummiworm head’s L1 state depends on whether the head is in the multisig or rules-based regime.

Multisig regime state

While a head is in the multisig regime, its L1 state on Cardano consists of these utxos:

All these utxos are held under a native script that requires signatures from all head peers and a quorum of coil peers. Each utxo (except deposits) holds a beacon token minted by the head’s native script, where the token name is the CIP-67 prefix (indicated in the table) concatenated with the head’s unique 28-byte nonce (defined at initialization). The multisig treasury’s beacon token name is the head’s ID.

The multisig treasury utxo contains all the funds that Gummiworm holds to back the L2 ledger state. It also contains some excess ADA (“equity”) that Gummiworm uses to pay L1 fees for its settlement, finalization, and rollout transactions.

The multisig regime utxo witnesses the fact that the Gummiworm head is still in the multisig regime — i.e., consensus still operates. It contains the head’s serialized native script and sufficient ADA to ensure that the head can always fall back into the rules-based regime.

Users place deposit utxos under Gummiworm’s control to be absorbed into the treasury. Each deposit utxo specifies:

• (By hash) the L2 state to be introduced into the L2 ledger if the deposit is absorbed.
• (By datum) refund instructions to ensure that the depositor can recover the deposit if it isn’t absorbed by a set deadline.

The rollout utxos are created by settlement, finalization, and rollout transactions to facilitate remitting payouts from the treasury. They briefly exist until spent by rollout transactions.

If Gummiworm’s consensus fails, the L1 utxo composition updates to facilitate the orderly evacuation of treasury funds. The multisig regime utxo is spent, and the unabsorbed deposits are refunded.

Rule-based regime state

While a head is in the rules-based regime, its L1 state on Cardano consists of these utxos:

Each utxo (except deposits) holds a beacon token minted by the head’s native script, where the token name is the CIP-67 prefix (indicated in the table) concatenated with the head’s unique 28-byte nonce (defined at initialization).

The rule-based treasury utxo is held under the Gummiworm treasury script, which is Plutus-based and universal for all heads. It contains the funds that Gummiworm holds to back the L2 ledger state with which the head fell back into the multisig regime. This treasury utxo has an “unresolved” datum during dispute resolution, and a “resolved” datum afterward.

The ballot box utxos are created by the fallback transaction for the head peers and the public to vote on the latest compatible evacuation commitment during dispute resolution. The dispute ends when all ballot boxes are merged, and their prevailing evacuation commitment and VOTE tokens are merged into the rule-based treasury.

The deposit and rollout utxos may be briefly left over from the multisig regime until they are spent by the refund and rollout transactions, respectively.

Deposits and refunds

Users place deposit utxos under Gummiworm’s control to fund L2 actions. Each deposit utxo’s lifecycle ends in one of two ways:

• Absorbed by a settlement transaction into the multisig treasury.
• Returned to the depositor by a refund transaction, if the head fails to absorb it by a deadline.

Deposit transaction

A user’s deposit transaction targeting a head identified by headId must:

1. Reference the head’s multisig regime utxo. This ensures that the deposit transaction will automatically roll back if the head’s initialization transaction rolls back.

2. Produce a deposit utxo at the head’s native script address:

   • The deposit utxo must contain the deposit request’s deposit fee and the total value of the L2 payload’s utxos.

   • The deposit utxo datum must specify the refund start time, refund address, and refund datum.

   • Set the refundStart to the deposit request’s validity end time, plus the “refund start offset”, which is the sum of the submission, maturity, absorption, and silence duration parameters.

   • The total value of the L2 payload’s utxos must be sufficient to cover the refund transaction’s fee and produce the refund utxo.

   type DepositUtxoDatum = {
     refundInstructions: RefundInstructions,
   }
    
   type RefundInstructions = {
     address: ShelleyAddress,
     mbDatum: Datum | null,
     refundStart: PosixTime, // Aligned to slot
   }

3. Set the deposit transaction’s validity end time to the deposit request’s validity end time, plus Gummiworm’s submission duration parameter.

4. Set this map at the {HYDR}.deposit.{headId} metadata path (HYDR integer constant is defined here):

   • depositIx: Int — the output index of the deposit utxo intended for headId in this deposit transaction.
   • depositFee: Lovelace — the deposit request’s deposit fee. This is distinct from the deposit transaction’s fee (which goes to Cardano). Instead, the “deposit fee” means the ADA will go into the head’s equity (i.e. not credit to the user on L2) when the head absorbs the deposit. This value can be zero if the L2 ledger rules allow it.
   • l2PayloadHash: Hash32 — the Blake2b-256 hash of the deposit request’s L2 payload.

Deposit transactions may target several heads by producing multiple deposit utxos as outputs, but each output must be exclusive to a single head. Gummiworm checks that each depositUtxoIx is not duplicated across different head IDs in the transaction metadata.

Refund transaction

A refund transaction descends from a deposit transaction and allows the depositor to recover the deposit, starting from the refund start time defined in the deposit’s utxo datum. The refund start time is deferred to give the head a chance to absorb the deposit.

The refund transaction must:

1. Spend the deposit utxo.
2. Produce a single output at the deposit’s refund address, with the refund datum, and containing the deposit’s funds minus the refund transaction fee.
3. Set its validity start time to the refund start time specified in the deposit’s utxo datum.
4. Set the empty map at the {HYDR}.refund.{headId} metadata path.

Command helper types

Gummiworm’s RegisterDeposit command carries a few L1-specific fields whose inner structure depends on the L1 blockchain. For Cardano, these are:

• DepositId — the Cardano L1 utxo reference (transaction ID + output index) of the deposit utxo.
• Destination — a Cardano address paired with an optional datum, used for refund destinations.
• Value — the Cardano native-asset model: a list of (asset, quantity) pairs, where each asset is either Ada or a native token identified by policy ID and asset name.

type DepositId = {
  transaction_id: Hash32,
  index: number,
}
 
type Destination = {
  address: ShelleyAddress,
  datum: Datum | null,
}
 
// Bech32-encoded
type ShelleyAddress = string
 
type Datum =
  | { tag: "Hash", hash: Hash32 }
  | { tag: "Inline", inline: ByteString }
 
// Collection of L1 asset values
type Value = {
  assets: AssetValue[],
}
 
type AssetValue = {
  asset: AssetId,
  value: number,
}
 
type AssetId =
  | { tag: "Ada" }
  | { tag: "NativeToken", policyId: Hash28, assetName: ByteString }
 
type Hash28 = ByteString

Multisig regime effects

While the head operates in the multisig regime, peers produce L1 effects via multisigned transactions:

• Initialization sets up the head’s L1 state.
• Finalization gracefully winds it down.
• Fallback transitions the head to the rule-based regime if consensus fails.
• Settlement transactions chain together to absorb deposits and remit payouts over the head’s lifetime, with rollout transactions extending each settlement’s payout capacity.

Initialization transaction

The initialization transaction is negotiated and multisigned by the head and coil peers before the Gummiworm consensus protocol begins. It can do anything, but it must:

1. Spend the head’s seed utxo. Its Blake2b-224 hash is the head’s unique 28-byte nonce.

2. Mint the head’s HYDR and HRMW beacon tokens (one each).

3. Produce the multisig treasury utxo at the head’s native script address, with the HYDR token, the funds backing the initial L2 ledger state, and the initial equity provided by the head peers.

4. Produce the multisig regime utxo at the head’s native script address, with the HMRW token, the head’s serialized native script, and sufficient ADA to ensure the head can always fall back into the rules-based regime.

5. Set this map at the {HYDR}.initialization.{headId} metadata path:

   • multisigTreasuryIx: Int — the output index of the head’s multisig treasury utxo.
   • multisigRegimeIx: Int — the output index of the head’s multisig regime utxo.
   • seedIx: Int — the input index of the seed utxo.

Finalization transaction

The finalization transaction winds down Gummiworm’s L1 state and gracefully terminates the consensus protocol. It must:

1. Spend the head’s multisig treasury and regime utxos.
2. Burn the head’s HYDR and HRMW tokens.
3. Distribute the funds from the equity and fallback contingency compartments in the multisig treasury and multisig regime utxos to the head peers. Equity is distributed based on the peers’ initial equity contributions.
4. Remit the main compartment’s funds from the multisig treasury per the latest evacuation map, producing a rollout output if the individual payouts do not fit within the finalization transaction.
5. Set the empty map at the {HYDR}.finalization.{headId} metadata path.

Fallback transaction

A fallback transaction descends from an initialization or settlement transaction and allows anyone to transition the head to the rules-based regime, starting from its fallback start time. The fallback start time is deferred to give the head a chance to multisign the next block’s settlement or finalization transaction, which will supersede this fallback transaction.

The fallback transaction must:

1. Spend the head’s multisig treasury and regime utxos.

2. Burn the head’s HRMW token, but not the HYDR token.

3. Mint a VOTE token for each head peer, plus one for the default vote’s ballot box.

4. Produce the head’s rule-based treasury utxo at the treasury script address (Plutus-based and universal for all heads), with an “unresolved” treasury datum, and the funds backing the L2 ledger state of the spent multisig treasury.

5. Produce an ADA-only collateral utxo for each head peer, which must hold the sum of these:

   • Sufficient ADA to satisfy script collateral requirements for the vote and tally transactions.
   • Sufficient ADA to pay one vote transaction fee.
   • The head peer’s share of the remaining equity, calculated based on the head peer’s initial equity contribution.

6. Produce a ballot box for the default vote, which is set to the evacuation commitment of the spent multisig treasury utxo.

7. Produce an exclusive ballot box for each head peer.

8. Produce zero or more public ballot boxes, according to Gummiworm’s n-public-ballot-boxes parameter.

9. Set its validity start time to the refund start time specified in the deposit’s utxo datum.

10. Set the empty map at the {HYDR}.fallback.{headId} metadata path.

Settlement transaction

A settlement transaction absorbs deposits, remits payouts, and supersedes the previous fallback transaction. It must:

1. Spend the multisig treasury utxo and reproduce it as a continuing output:

   • Increment the major version.
   • Add the funds absorbed from the deposits — deposit fees into the equity compartment and the rest into the main compartment.
   • Remove the remitted payouts from the main compartment.

2. Reference the multisig regime utxo to access the head’s native script.

3. Spend the deposits that the head peers decided to absorb in the block brief.

4. Remit the payouts that the head peers decided to remit in the block brief, producing a rollout output if the individual payouts do not fit within the settlement transaction.

5. Set the empty map at the {HYDR}.settlement.{headId} metadata path.

Rollout transaction

Rollout transactions support settlement and finalization transactions by expanding the number of payouts that can be remitted beyond Cardano’s transaction size and output limit.

A rollout transaction must:

1. Spend a rollout utxo produced by a previous settlement, finalization, or rollout transaction.
2. Remit the payouts associated with the rollout input, producing a smaller rollout output if the individual payouts cannot fit into the rollout transaction.
3. Set the empty map at the {HYDR}.rollout.{headId} metadata path.

Multisig effect submission

The preceding diagrams isolate individual transactions. The following diagrams show:

• How effects compose across an entire head’s lifetime.
• How peers resubmit them after L1 rollbacks.
• How the head transitions to the rule-based regime if a spine effect fails to land in time.

Settlement and rollout sequence

Each settlement transaction may connect to a chain of rollout transactions via the rollout UTXOs it produces and each rollout subsequently spends. Each settlement transaction also connects to the next via the treasury UTXO it produces.

Multisig effect tree

Consider a head’s entire lifetime in the multisig regime. The full tree of multisig effects consists of:

• A spine that starts with initialization, contains some settlements, and ends with finalization.
• Each initialization and settlement is paired with a fallback.
• Rollout chains can branch from each settlement and finalization.

Effect ID indexing and resubmission

Each transaction in the tree carries an effect ID — a (major, link) pair, where major is the effect’s major block version number. Spine transactions have link 0 — initialization at (0,0), settlement N at (N,0), finalization at (M,0). Rollout transactions share their parent spine node’s major number, with links 1, 2, 3,… along the chain. Fallback transactions have no effect ID because there is exactly one per initialization or settlement.

Peers submit effects to Cardano as they are produced and hard-confirmed by slow consensus. If a subsequent query of the Cardano ledger reveals treasury or rollout UTXOs that should already have been spent, peers can calculate exactly which transactions to resubmit. Each resubmission range begins at a transaction that has at least one unspent input observed by the query, and extends through all of that transaction’s successors in the tree. For example:

• If the rollout UTXO feeding rollout (N,k) is unspent, then (N,k) is the head of a resubmission range that extends only to the end of that rollout chain.

  

• If the treasury UTXO produced by settlement (N,0) is unspent, then settlement (N+1,0) is the head of a resubmission range that continues along the spine through finalization, including any rollout chains branching from each spine node in that range.

  

The goal is for Cardano to eventually confirm the entire tree — absorbing all deposits, producing all payouts, and leaving the latest treasury UTXO onchain.

Submitting competing fallbacks

Each non-init spine effect — settlement or finalization — competes against the fallback that was multisigned in the preceding block brief. Both target the same multisig treasury and regime utxos as inputs. The spine effect is preferred: if it lands on Cardano within its validity window, it spends those inputs and supersedes the competing fallback, continuing the head’s lifecycle in the multisig regime.

Peers submit the spine effect first. If its validity expires without landing, peers must submit the competing fallback as soon as it becomes valid — which transitions the head to the rule-based regime. Otherwise, the spine effect’s own paired fallback becomes the competing fallback for the next block’s spine effect.

A silence duration separates the spine effect’s validity end from the competing fallback’s validity start. Neither is valid during silence, which guarantees that exactly one of the two effects can execute at any given time.

Rule-based regime

When consensus fails, the head transitions to the rule-based regime via the fallback transaction. From there, the head’s funds are evacuated according to programmed rules, without coordination among the head peers:

• Vote and tally transactions resolve a dispute over the prevailing evacuation commitment.
• Resolve and evacuation transactions then remit the treasury funds.
• Deinit cleans up the last trace of the head.

Vote transaction

Before the dispute resolution deadline, vote transactions can be submitted to update the ballot box utxos. A vote transaction must:

1. Spend a single ballot box utxo.
2. If the ballot box is exclusive to a head peer, only update its evacuation commitment if the ballot box is empty and the transaction is signed by the head peer.
3. If the ballot box is public, only update its evacuation commitment if it supersedes the previous evacuation commitment in the ballot box (if any), or if the ballot box is empty.
4. Set the empty map at the {HYDR}.vote.{headId} metadata path.

Tally transaction

Tally transactions merge two adjacent ballot boxes at a time. A tally transaction must:

1. Spend two adjacent ballot box utxos.
2. If the transaction’s validity start is earlier than the dispute resolution deadline, both ballot boxes must be non-empty and non-public.
3. Produce a single ballot box containing both ballot boxes’ VOTE tokens, and the evacuation commitment that is not superseded by any others among the input ballot boxes.
4. Set the empty map at the {HYDR}.tally.{headId} metadata path.

Resolve transaction

The resolve transaction ends the dispute and enables evacuation. It must:

1. Update the rule-based treasury utxo as a continuing output.
2. Spend a single ballot box containing all the VOTE tokens produced by the fallback transaction.
3. The input treasury’s datum must be “unresolved.”
4. The output treasury’s datum must be “resolved” with the evacuation commitment of the ballot box.
5. Set the empty map at the {HYDR}.resolve.{headId} metadata path.

Evacuation transaction

Evacuation transactions remit payouts from the rule-based treasury. They use KZG proofs instead of transaction multisignatures for authorization, meaning that they can be drafted and submitted by anyone, without coordinating with the head or coil peers.

An evacuation transaction must:

1. Update the rule-based treasury as a continuing output:

   • Remove the funds remitted as payouts.
   • Update the evacuation commitment to exclude the corresponding payout entries.

2. Include a KZG membership proof for the payouts in the redeemer.

3. Set the empty map at the {HYDR}.evacuation.{headId} metadata path.

Deinit transaction

The deinit transaction cleans up the last trace of the head, after all funds have been evacuated. It must:

1. Spend the rule-based treasury, which must contain an empty evacuation commitment.
2. Burn the HYDR and all the VOTE tokens.
3. Set the empty map at the {HYDR}.deinit.{headId} metadata path.