hydra-tx
Safe HaskellSafe-Inferred
LanguageGHC2021

Hydra.Tx.Accumulator

Synopsis

Documentation

data HydraAccumulator Source #

Instances

Instances details
Show HydraAccumulator Source #

Shows only the element map: the derived instance would force the cached commitment, so showing head state in logs or test output would compute a BLS commitment as a side effect.

Instance details

Defined in Hydra.Tx.Accumulator

Eq HydraAccumulator Source # 
Instance details

Defined in Hydra.Tx.Accumulator

getAccumulatorHash :: HydraAccumulator -> ByteString Source #

Get a blake2b-256 hash of the accumulator commitment (compressed G1 point).

This is a pure function that returns a 32-byte deterministic hash of the compressed G1 accumulator commitment. It is what gets signed by all parties in the multi-signature and stored as accumulatorHash in on-chain datums.

Hashing the compressed G1 point (rather than the serialized map) binds the signed hash to the exact G1 point stored in accumulatorCommitment, allowing the on-chain validator to verify their consistency.

The result is cached inside HydraAccumulator as a lazy thunk and computed at most once per value, regardless of how many times this function is called.

getAccumulatorCommitment :: HydraAccumulator -> BuiltinBLS12_381_G1_Element Source #

computeG1CommitmentBytes :: Accumulator -> ByteString Source #

Compute the compressed G1 commitment for an accumulator through the rust-accumulator FFI (divide-and-conquer FFT polynomial expansion and a Pippenger multi-scalar multiplication), which is orders of magnitude faster than expanding the polynomial in Haskell. Bit-for-bit equal to the PlutusTx reference path; see the equivalence properties and golden values in Hydra.Tx.AccumulatorSpec.

accumulatorSize :: HydraAccumulator -> Int Source #

Number of UTxOs tracked by the accumulator.

maxAccumulatorSize :: Int Source #

Maximum accumulator size, re-exported from KZGTrustedSetup for convenience.

buildFromUTxO Source #

Arguments

:: forall tx. IsTx tx 
=> UTxOType tx

The UTxO set to build the accumulator from

-> HydraAccumulator

The resulting accumulator containing one element per TxOut

Build an accumulator from a UTxO by serializing each individual TxOut.

This is the CORRECT way to build an accumulator for partial fanout proofs. Each TxOut becomes a separate element in the accumulator, allowing you to later prove that a subset of TxOuts was part of the original set.

The serialization matches how hashTxOuts works on-chain: Each element = Builtins.serialiseData (toBuiltinData plutusTxOut)

Example usage: > -- Build accumulator from the full UTxO set > let fullAcc = buildFromUTxO Tx utxo > > -- Later, prove a subset exists > let crs = crsG1Points (requiredCRSPointCount fullAcc) > result <- createMembershipProofFromUTxO Tx subsetUTxO fullAcc crs

This approach allows proving that 2 out of 5 UTxOs are part of the original set, which is essential for partial fanout functionality.

buildFromSnapshotUTxOs Source #

Arguments

:: forall tx. IsTx tx 
=> UTxOType tx

The main snapshot UTxO set

-> Maybe (UTxOType tx)

UTxOs to be committed (if any)

-> Maybe (UTxOType tx)

UTxOs to be decommitted (if any)

-> HydraAccumulator

The resulting accumulator containing all UTxOs

Build an accumulator from snapshot UTxOs, including commit and decommit UTxOs.

Combines all UTxOs that could potentially be fanned out — main snapshot, commit, and decommit — and delegates to buildFromUTxO on the merged set. Merging via UTxO union keeps the same canonical TxIn-sorted element order used by every other accumulator call site (computeFullFanoutUTxO, partialFanout staleness check, emitNextFanoutStep), so the commitment stored in the snapshot and all downstream proofs are built from the same element set by construction.

Note: the underlying HydraAccumulator is a Map keyed by element bytes, so insertion order is irrelevant for the commitment value; the merge is done here for explicit consistency with the rest of the fanout code paths.

applyUTxODelta Source #

Arguments

:: forall tx. IsTx tx 
=> HydraAccumulator

Accumulator built from the previous combined UTxO set

-> UTxOType tx

The previous combined UTxO set

-> UTxOType tx

The new combined UTxO set

-> HydraAccumulator 

Update an accumulator from one snapshot's combined UTxO set to the next by adding and removing only the changed outputs, avoiding the per-output serialization and hashing of a full rebuild. Extensionally equal to buildFromUTxO on the new set (see the property in Hydra.Tx.AccumulatorSpec): the underlying map tracks element multiplicity and the TxIn-keyed set difference removes exactly one occurrence per consumed input. Falls back to a full rebuild if a removed element is missing or has lower multiplicity than the removals require, which would indicate the given accumulator was not built from the given previous UTxO set.

CRS (Common Reference String)

crsG2Points :: Int -> [Point2] Source #

Returns the first n G2 powers of tau from the EIP-4844 trusted setup. Used as the on-chain CRS for verifying membership proofs: [G2, τ·G2, ..., τ^(n-1)·G2].

crsG1Points :: Int -> [Point1] Source #

Returns the first n G1 powers of tau from the EIP-4844 trusted setup. Used as the off-chain CRS for building accumulator commitments and membership proofs: [G1, τ·G1, ..., τ^(n-1)·G1].

requiredCRSPointCount :: HydraAccumulator -> Int Source #

Returns the number of G1 CRS points required for this accumulator. An n-element accumulator polynomial has degree n, so needs n+1 G1 points [G1, τ·G1, ..., τⁿ·G1] to compute the commitment A(τ)·G1 and proofs. n is the total element count including duplicates (sum of all counts).

defaultItems :: Int Source #

Number of G2 points published in the on-chain CRS UTxO datum.

This is the deployed G2 CRS length. It directly caps the largest subset that can be verified in a single fanout / partial-fanout pairing check: a subset of N elements yields a polynomial of degree N (one (X - sᵢ) factor per element), and the on-chain MSM to evaluate P_S(τ)·G2 needs N+1 G2 points. With defaultItems = 30 the deployed batch limit is therefore 29.

The trusted-setup file embeds 65 G2 points (see maxFanoutBatchSize); only the first defaultItems are written into the CRS UTxO at script-registry publication time (see buildScriptPublishingTxs). Raising defaultItems requires re-publishing the CRS UTxO and is bounded above by KZGTrustedSetup.maxFanoutBatchSize + 1.

Membership proofs for partial fanout

createMembershipProof Source #

Arguments

:: [Element]

The subset of elements to prove membership of (e.g., UTxOs being fanned out)

-> HydraAccumulator

The full accumulator from the confirmed snapshot

-> [Point1]

Common Reference String (CRS) for the cryptographic proof

-> Either Text ByteString

Returns the compressed proof point, or an error if elements are missing or CRS is too short

Create a membership proof for a subset of UTxO elements.

This function uses getPolyCommitOverG1 from haskell-accumulator's Bindings module: https://github.com/cardano-scaling/haskell-accumulator/blob/main/haskell-accumulator/lib/Bindings.hs

Given a subset of elements and the full accumulator, it: 1. Removes the subset elements from the accumulator 2. Computes a polynomial commitment over G1 for the remaining elements 3. Returns the proof as a compressed G1 point

createMembershipProofFromUTxO Source #

Arguments

:: forall tx. IsTx tx 
=> UTxOType tx

The subset of UTxO to prove membership of (e.g., UTxOs being fanned out)

-> HydraAccumulator

The full accumulator from the confirmed snapshot (built with buildFromUTxO)

-> [Point1]

Common Reference String (CRS) for the cryptographic proof

-> Either Text ByteString

Returns the compressed proof point, or an error if elements are missing or CRS is too short

Create a membership proof from a UTxO subset.

This function extracts individual TxOut elements from the subset UTxO and proves they exist in the full accumulator. The full accumulator must be built using buildFromUTxO for this to work correctly.

The proof is verified on-chain via e(commitment_G1, G2) = e(proof_G1, P_S(τ)·G2).

createCRSG2Datum :: Int -> TxOutDatum ctx Source #