proofs

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 14, 2025 License: GPL-3.0 Imports: 9 Imported by: 0

README

Superblock Proof Pipeline

The proofs package provides essential types and interfaces for integrating zero-knowledge proof generation and verification into the Superblock Construction Protocol (SBCP). It enables the collection of individual rollup proofs from op-succinct instances and coordinates with the superblock-prover to generate final aggregated proofs for L1 submission.

This package is intentionally lightweight to maintain loose coupling with specific prover implementations while providing a robust foundation for proof-enabled superblock publication.

Overview

The proof pipeline orchestrates the following workflow:

flowchart LR
    R1[op_succinct_A]
    R2[op_succinct_B]
    SP[Shared_Publisher]
    PV[superblock_prover]
    L1[L1_Contract]
    R1 -- POST_proofs --> SP
    R2 -- POST_proofs --> SP
    SP -- POST_prove --> PV
    SP -- poll_jobs --> PV
    PV -- proof_ready --> SP
    SP -- proposeL2Output_SB_plus_proof --> L1
    L1 -- OutputProposed_or_receipt --> SP

Package Layout

  • submission.go, status.go, aggregation.go — shared data structures
  • collector/ — collector service interface and in-memory implementation
  • proof_bytes.go — flexible proof byte encoding/decoding
  • prover_types.go — prover job structures and interface
  • prover/http_client.go — HTTP implementation of ProverClient
  • ../proofs_pipeline.go — coordinator-managed pipeline that requests proofs and publishes when ready

Core Components

Collector API

The collector receives per-rollup proofs and tracks readiness for the prover. Key types:

type Submission struct {
    SuperblockNumber uint64
    SuperblockHash   common.Hash
    ChainID          uint32
    L1Head           common.Hash
    Aggregation      AggregationOutputs
    L2StartBlock     uint64
    AggVerifyingKey  json.RawMessage
    Proof            []byte
    ReceivedAt       time.Time
}

type Status struct {
    SuperblockHash   common.Hash
    SuperblockNumber uint64
    Required         []uint32
    Received         map[uint32]time.Time
    State            string // collecting|dispatched|proving|complete|failed
    JobID            string
    Error            string
}

type Collector interface {
    SubmitOpSuccinct(ctx context.Context, s Submission) error
    GetStatus(ctx context.Context, sbHash common.Hash) (Status, error)
    ListSubmissions(ctx context.Context, sbHash common.Hash) ([]Submission, error)
    UpdateStatus(ctx context.Context, sbHash common.Hash, mutate func(*Status)) error
}

collector.NewMemory() provides the in-memory implementation used for local runs and tests.

HTTP endpoints exposed by http/handler.go:

Method Path Description
POST /v1/proofs/op-succinct Submit a Submission payload.
GET /v1/proofs/status/{sbHash} Fetch the current Status for a superblock hash.

AggregationOutputs matches the op-succinct JSON schema and exposes ABIEncode() to produce the 8*32 byte blob required by the prover.

Prover API

The prover client dispatches aggregated jobs to superblock-prover and polls for completion:

type ProverClient interface {
    RequestProof(ctx context.Context, job ProofJobInput) (jobID string, err error)
    GetStatus(ctx context.Context, jobID string) (ProofJobStatus, error)
}

type ProofJobInput struct {
    ProofType string                `json:"proof_type"`
    Input     SuperblockProverInput `json:"input"`
}

type ProofJobStatus struct {
    Status        string `json:"status"`
    Proof         []byte `json:"proof,omitempty"`
    ProvingTimeMS *uint64
    Cycles        *uint64
}

type SuperblockProverInput struct {
    PreviousBatch     SuperblockBatch
    NewBatch          SuperblockBatch
    AggregationProofs []AggregationProofData
}

type SuperblockBatch struct {
    SuperblockNumber            uint64
    ParentSuperblockBatchHash   []int
    RollupSt                    []RollupStateTransition
}

type RollupStateTransition struct {
    RollupConfigHash []int  // bytes32 - Uniquely identifies a rollup
    L2PreRoot        []int  // bytes32 - Pre-execution state root
    L2PostRoot       []int  // bytes32 - Post-execution state root
    L2BlockNumber    []int  // bytes32 - New L2 block number
}

The concrete HTTP implementation lives in prover/http_client.go and satisfies the ProverClient interface. It accepts jobs via POST /proof and polls GET /proof/{request_id} following the contract exposed by the Rust service.

Public Outputs

SuperblockAggregationOutputs mirrors the Solidity struct used as verifier public inputs:

type SuperblockAggregationOutputs struct {
    L1Head           common.Hash
    SuperblockHash   common.Hash
    SuperblockNumber uint64
    RollupOutput     []AggregationOutputsWithChainID
}

type AggregationOutputsWithChainID struct {
    ChainID            uint32
    AggregationOutputs json.RawMessage
}

AggregationOutputsWithChainID embeds each chain’s encoded outputs (json.RawMessage) for later ABI packing.

State Flow: collecting → queued → dispatched → proving → complete | failed

Rate Limiting: Only one proof can be in proving state at a time. Additional ready proofs will be queued in queued state until the current proof completes or fails.

Documentation

Index

Constants

View Source 
const (
	StateCollecting = "collecting"
	StateQueued     = "queued"
	StateDispatched = "dispatched"
	StateProving    = "proving"
	StateComplete   = "complete"
	StateFailed     = "failed"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AggregationOutputs 

type AggregationOutputs struct {
	L1Head           common.Hash    `json:"l1_head"`
	L2PreRoot        common.Hash    `json:"l2_pre_root"`
	L2PostRoot       common.Hash    `json:"l2_post_root"`
	L2BlockNumber    uint64         `json:"l2_block_number"`
	RollupConfigHash common.Hash    `json:"rollup_config_hash"`
	MailboxRoot      common.Hash    `json:"mailbox_root"`
	MultiBlockVKey   common.Hash    `json:"multi_block_vkey"`
	ProverAddress    common.Address `json:"prover_address"`
}

AggregationOutputs sent to superblock prover

func (AggregationOutputs) ABIEncode 

func (a AggregationOutputs) ABIEncode() []byte

ABIEncode encodes AggregationOutputs into the 8*32 byte form expected by the prover.

Encodes all fields: l1Head, l2PreRoot, l2PostRoot, l2BlockNumber, rollupConfigHash, mailboxRoot, multiBlockVKey, proverAddress

type AggregationOutputsWithChainID 

type AggregationOutputsWithChainID struct {
	ChainID            uint32          `json:"chain_id"`
	AggregationOutputs json.RawMessage `json:"aggregation_outputs"`
}

AggregationOutputsWithChainID associates per-rollup outputs with a chain identifier.

type AggregationProofData 

type AggregationProofData struct {
	ChainID            uint32             `json:"chain_id"`
	AggregationOutputs AggregationOutputs `json:"aggregation_outputs"`
	CompressedProof    PublicValueBytes   `json:"compressed_proof"`
	AggVKey            [8]int             `json:"agg_vkey"`
	MailboxInfo        MailboxInfoStruct  `json:"mailbox_info"`
}

AggregationProofData packages per-rollup proof inputs. Must match the Rust AggregationProofData struct in superblock-prover.

type BootInfo 

type BootInfo struct {
	L1Head           string `json:"l1_head"`      // hex string
	L2PreRoot        string `json:"l2_pre_root"`  // hex string
	L2PostRoot       string `json:"l2_post_root"` // hex string
	L2BlockNumber    uint64 `json:"l2_block_number"`
	RollupConfigHash string `json:"rollup_config_hash"` // hex string
}

BootInfo represents boot information for a rollup (mirrors Rust BootInfo).

type MailboxInfoStruct 

type MailboxInfoStruct struct {
	InboxChains  []common.Hash `json:"inbox_chains"`
	OutboxChains []common.Hash `json:"outbox_chains"`
	InboxRoots   []common.Hash `json:"inbox_roots"`
	OutboxRoots  []common.Hash `json:"outbox_roots"`
}

type OpSuccinctAggregationOutputs 

type OpSuccinctAggregationOutputs struct {
	L1Head           common.Hash    `json:"l1Head"`
	L2PreRoot        common.Hash    `json:"l2PreRoot"`
	L2PostRoot       common.Hash    `json:"l2PostRoot"`
	L2BlockNumber    uint64         `json:"l2BlockNumber"`
	RollupConfigHash common.Hash    `json:"rollupConfigHash"`
	MailboxRoot      common.Hash    `json:"mailboxRoot"`
	MultiBlockVKey   common.Hash    `json:"multiBlockVKey"`
	ProverAddress    common.Address `json:"proverAddress"`
}

OpSuccinctAggregationOutputs received from op-succinct

func (OpSuccinctAggregationOutputs) ToAggregationOutputs 

func (o OpSuccinctAggregationOutputs) ToAggregationOutputs() AggregationOutputs

ToAggregationOutputs converts op-succinct format to internal format

type ProofBytes 

type ProofBytes []byte

ProofBytes handles flexible JSON representations of proof payloads.

Accepts either 0x-prefixed hex strings, base64 strings, or arrays of byte values. MarshalJSON always emits a 0x-prefixed hex string for consistency.

func (ProofBytes) Bytes 

func (p ProofBytes) Bytes() []byte

Bytes returns the underlying slice without copying.

func (ProofBytes) Clone 

func (p ProofBytes) Clone() []byte

Clone returns a defensive copy of the underlying slice.

func (ProofBytes) MarshalJSON 

func (p ProofBytes) MarshalJSON() ([]byte, error)

MarshalJSON emits a 0x-prefixed hex string representation.

func (*ProofBytes) UnmarshalJSON 

func (p *ProofBytes) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler, allowing multiple encodings.

type ProofJobInput 

type ProofJobInput struct {
	ProofType string                `json:"proof_type"`
	Input     SuperblockProverInput `json:"input"`
}

ProofJobInput bundles the prover payload and selected proof type.

type ProofJobStatus 

type ProofJobStatus struct {
	Status               string `json:"status"`
	Proof                []byte `json:"proof,omitempty"`
	ProvingTimeMS        *uint64
	Cycles               *uint64
	SuperblockAggOutputs *SuperblockAggOutputs `json:"superblock_agg_outputs,omitempty"`
	Commitment           *string               `json:"commitment"`
}

ProofJobStatus represents the prover's reported state.

type ProverClient 

type ProverClient interface {
	RequestProof(ctx context.Context, job ProofJobInput) (jobID string, err error)
	GetStatus(ctx context.Context, jobID string) (ProofJobStatus, error)
}

type ProverL2Block 

type ProverL2Block struct {
	Slot            uint64   `json:"slot"`
	ChainID         []byte   `json:"chain_id"`
	BlockNumber     uint64   `json:"block_number"`
	BlockHash       []byte   `json:"block_hash"`
	ParentBlockHash []byte   `json:"parent_block_hash"`
	IncludedXTs     [][]byte `json:"included_xts"`
	Block           []byte   `json:"block"`
}

ProverL2Block mirrors the prover-facing L2 block representation.

type ProverSuperblock 

type ProverSuperblock struct {
	Number            uint64          `json:"number"`
	Slot              uint64          `json:"slot"`
	ParentHash        []byte          `json:"parent_hash"`
	Hash              []byte          `json:"hash"`
	MerkleRoot        []byte          `json:"merkle_root"`
	Timestamp         uint64          `json:"timestamp"`
	L2Blocks          []ProverL2Block `json:"l2_blocks"`
	IncludedXTs       [][]byte        `json:"included_xts"`
	L1TransactionHash []byte          `json:"l1_transaction_hash,omitempty"`
}

ProverSuperblock matches the prover's expected Superblock representation.

type PublicValueBytes 

type PublicValueBytes []byte

PublicValueBytes handles public values for the superblock-prover. Unlike ProofBytes, this marshals as an array of integers, not hex string.

func (PublicValueBytes) Bytes 

func (p PublicValueBytes) Bytes() []byte

Bytes returns the underlying slice without copying.

func (PublicValueBytes) MarshalJSON 

func (p PublicValueBytes) MarshalJSON() ([]byte, error)

MarshalJSON emits an array of integers for the superblock-prover.

func (*PublicValueBytes) UnmarshalJSON 

func (p *PublicValueBytes) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler, allowing multiple encodings.

type RollupStateTransition 

type RollupStateTransition struct {
	RollupConfigHash []int `json:"rollup_config_hash"` // bytes32 - Uniquely identifies a rollup
	L2PreRoot        []int `json:"l2_pre_root"`        // bytes32 - Pre-execution state root
	L2PostRoot       []int `json:"l2_post_root"`       // bytes32 - Post-execution state root
	L2BlockNumber    []int `json:"l2_block_number"`    // bytes32 - New L2 block number
}

RollupStateTransition represents state transition information for a single rollup.

type Status 

type Status struct {
	SuperblockHash   common.Hash          `json:"superblock_hash"`
	SuperblockNumber uint64               `json:"superblock_number"`
	Required         []uint32             `json:"required_chain_ids"`
	Received         map[uint32]time.Time `json:"received"`
	State            string               `json:"state"` // collecting|queued|dispatched|proving|complete|failed
	JobID            string               `json:"job_id"`
	Error            string               `json:"error,omitempty"`
}

Status summarizes collection progress and prover job state for a superblock.

type Submission 

type Submission struct {
	SuperblockNumber uint64             `json:"superblock_number"`
	SuperblockHash   common.Hash        `json:"superblock_hash"`
	ChainID          uint32             `json:"chain_id"`
	L1Head           common.Hash        `json:"l1_head"`
	Aggregation      AggregationOutputs `json:"aggregation_outputs"`
	L2StartBlock     uint64             `json:"l2_start_block"`
	AggVerifyingKey  json.RawMessage    `json:"agg_vk"`
	MailboxInfo      MailboxInfoStruct  `json:"mailbox_info"`
	Proof            []byte             `json:"proof,omitempty"`
	ReceivedAt       time.Time          `json:"received_at"`
}

Submission represents a proof payload provided by a single op-succinct instance.

func (*Submission) MailboxInfoToString 

func (s *Submission) MailboxInfoToString() string

type SuperblockAggOutputs 

type SuperblockAggOutputs struct {
	SuperblockNumber          string     `json:"superblock_number"`            // U256 as hex string
	ParentSuperblockBatchHash string     `json:"parent_superblock_batch_hash"` // hex string
	BootInfo                  []BootInfo `json:"boot_info"`
}

SuperblockAggOutputs represents serializable superblock aggregation outputs (mirrors Rust SuperblockAggOutputs).

type SuperblockBatch 

type SuperblockBatch struct {
	SuperblockNumber          uint64                  `json:"superblock_number"`            // uint256 - Sequential superblock number
	ParentSuperblockBatchHash []int                   `json:"parent_superblock_batch_hash"` // bytes32 - Hash of the previous superblock
	RollupSt                  []RollupStateTransition `json:"rollup_st"`                    // RollupStateTransition[] - State transition information about each rollup
}

SuperblockBatch represents a superblock batch structure.

type SuperblockProverInput 

type SuperblockProverInput struct {
	PreviousBatch     SuperblockBatch        `json:"previous_batch"`
	NewBatch          SuperblockBatch        `json:"new_batch"`
	AggregationProofs []AggregationProofData `json:"aggregation_proofs"`
}

SuperblockProverInput mirrors the Rust prover input schema.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.