Mapping the Groth16 Frontier: A Deep-Dive Investigation into the SUPRASEAL_C2 Proof Pipeline

Introduction

In the world of decentralized storage, few operations are as computationally demanding—and memory-intensive—as generating a Groth16 zk-SNARK proof for Filecoin's Proof-of-Replication (PoRep) protocol. The SUPRASEAL_C2 system, which handles the second phase of seal commitment for Filecoin sectors, routinely consumes approximately 200 GiB of peak memory during operation. This staggering footprint has motivated a substantial refactoring effort: the "cuzk" project, which aims to replace the monolithic PoRep C2 prover with a pipelined, per-partition synthesis and GPU architecture.

This article examines a pivotal chunk of work within that refactoring effort—a deep-dive investigation that systematically mapped the entire API surface of the Filecoin proof generation pipeline, from the top-level seal_commit_phase2_circuit_proofs entry point in the filecoin-proofs crate, down through the CompoundProof trait abstraction, into the concrete proof implementations (StackedCompound, FallbackPoStCompound, EmptySectorUpdateCompound), and finally into the low-level SuprasealParameters wrapper and the C++ CUDA backend's prove_from_assignments function. The investigation produced ten articles ([msg 0] through [msg 9]) that together form a comprehensive architectural reference for the Phase 2 pipelined proving engine.

The Mission: Understanding the API Surface

The investigation began with a precise user request ([msg 0]): locate six specific Rust source files across the Cargo registry and a local bellperson fork, extract key function signatures, struct definitions, and trait implementations, and understand the visibility (pub vs pub(crate)) of key types. The six targets were carefully chosen to span the entire proof generation stack:

1. seal_commit_phase2_circuit_proofs — the top-level function orchestrating Phase 2 Groth16 proof generation
2. CompoundProof trait — the core abstraction in storage-proofs-core defining how proof systems expose their circuits
3. StackedCompound — the PoRep-specific implementation for stacked DRG graphs
4. FallbackPoStCompound — the Proof-of-Spacetime implementation
5. EmptySectorUpdateCompound — the sector update proof implementation
6. SuprasealParameters — the bridge type in the bellperson fork wrapping C++ Supraseal SRS parameters This was not casual browsing. The developer was building a new proving engine (cuzk) that replaces the monolithic Filecoin prover with a per-partition pipelined architecture. Understanding these APIs was prerequisite knowledge for designing the integration layer.

The Journey: From Permission Failures to Architectural Insight

The investigation unfolded across multiple rounds, each revealing new challenges and insights. The assistant's initial approach in [msg 1] was to use glob patterns—a high-level tool for file matching. This failed because the glob tool could not access ~/.cargo directly due to directory permissions. As documented in [chunk 8.0], the assistant diagnosed the failure and pivoted immediately in [msg 2], switching to bash with find commands, which successfully located all target files.

This pivot is a textbook example of meta-cognitive debugging. The assistant recognized that the glob/read tools had failed, diagnosed the cause as directory permissions, selected an alternative strategy (bash), and adapted the patterns to the new tool's syntax. The success of the bash commands served as post-hoc confirmation of the diagnosis.

With files located, the assistant shifted from discovery to extraction. In [msg 3], it used rg (ripgrep) to find exact line numbers for key functions and wc -l to gauge file sizes—building a mental map of where things were before reading what they said. This is a classic reconnaissance pattern: measure before reading, grep before analyzing, plan before executing.

The core data-gathering phase unfolded in [msg 4] through [msg 8]. The assistant read the seal_commit_phase2_circuit_proofs function body, the CompoundProof trait definition, and all three concrete proof implementations. It also ventured into the bellperson fork to understand SuprasealParameters and the ParameterSource trait, reading supraseal_params.rs, params.rs, ext_supraseal.rs, and prover/supraseal.rs.

The Seam: Identifying the Pipeline Split Point

The most critical architectural insight emerged from reading the bellperson fork's prover module. The assistant discovered two key public functions in prover/supraseal.rs:

1. synthesize_circuits_batch — performs CPU-side synthesis, returning ProvingAssignment vectors, input assignments, and aux assignments.
2. prove_from_assignments — takes pre-synthesized assignments and runs the GPU proving step, calling supraseal_c2::generate_groth16_proof with raw pointers to a, b, c evaluations. These two functions are the architectural seam that the cuzk Phase 2 pipeline exploits. The existing CompoundProof::circuit_proofs default implementation (documented in [msg 9]) calls Self::circuit() in parallel across partitions, batches circuits into groups of MAX_GROTH16_BATCH_SIZE (10), and then calls create_random_proof_batch—which does synthesis and proving together in a monolithic call. The cuzk pipeline intercepts this flow: instead of calling create_random_proof_batch, it calls synthesize_circuits_batch for each partition sequentially (discarding the circuit after synthesis to free memory), accumulates the assignments, and then feeds them to prove_from_assignments in a single GPU batch. This per-partition pipelining reduces peak intermediate memory from approximately 136 GiB to about 13.6 GiB, enabling the pipeline to function on machines with as little as 128 GiB of RAM. The discovery of this seam was the central achievement of the investigation.

Thoroughness: Beyond the Explicit Requirements

A hallmark of this investigation was the assistant's proactive thoroughness. In [msg 8], having already read the primary EmptySectorUpdateCompound (SHA-256 variant), the assistant recognized that a Poseidon hash variant likely existed based on the crate's directory structure and proactively read poseidon/compound.rs. This uncovered that the Poseidon variant has an additional constraint: k must be 0 (single partition only)—a detail that could cause subtle bugs in a SHA-256-only implementation.

Similarly, the assistant read each crate's lib.rs to verify the public API surface. The user had asked about "important types that are pub vs pub(crate)," and the most authoritative source for public API is the crate's root module. This revealed, for example, that storage-proofs-update's gadgets module is pub(crate)—internal only—while EmptySectorUpdateCircuit, EmptySectorUpdateCompound, and the vanilla proof types are all publicly re-exported.

The Synthesis: A Comprehensive Reference Document

The investigation culminated in [msg 9], a comprehensive research report synthesizing all gathered information into a structured reference document. The report is organized into six sections, each corresponding to one of the user's search targets. Rather than presenting information in chronological order (the sequence in which files were discovered), the assistant reorganized it into a logical catalog grouped by API component—a conscious editorial choice prioritizing reference utility over chronological accuracy.

The report documents:

• The complete call chain from seal_commit_phase2_circuit_proofs through StackedCompound::circuit_proofs to the underlying create_random_proof_batch and prove_from_assignments functions.
• The CompoundProof trait's three required methods (generate_public_inputs, circuit, blank_circuit) and its key provided method (circuit_proofs), with its internal logic of parallel circuit construction, batching into groups of 10, and proof serialization/deserialization round-trip.
• The StackedCompound struct with its private partitions field (marked #[allow(dead_code)]) and the StackedCircuit struct with its five optional domain fields.
• The FallbackPoStCompound padding behavior (duplicating the last sector when fewer real sectors than sector_count).
• The two variants of EmptySectorUpdateCompound (SHA-256 and Poseidon) with their respective constraints.
• The SuprasealParameters<E> struct as a thin wrapper around supraseal_c2::SRS, with all ParameterSource methods except get_supraseal_srs being unimplemented!()—revealing that the SupraSeal parameters struct is essentially a token holding the SRS pointer for the C++ backend.

Obstacles Overcome: Tooling Constraints and Workarounds

The investigation was not without obstacles. In [msg 5], the assistant attempted to search for ParameterSource references in the bellperson fork using rg with the --include flag—but ripgrep does not have a --include flag (the correct flag is --glob or -g). The error message confirmed this, and the assistant corrected in subsequent rounds.

More significantly, in [msg 6], the assistant encountered output truncation: grep results were being cut off mid-stream, losing critical information about the SuprasealParameters integration. The assistant recognized this as a truncation problem (not a search error) and pivoted in [msg 7] from shell-based search tools to direct file-reading with the read tool. This switch from pattern-matching (breadth) to targeted reading (depth) reflects a sophisticated understanding of the tooling environment's constraints.

The assistant also navigated the challenge of multiple crate versions. The Cargo registry contained both 19.0.0 and 19.0.1 for most packages. The assistant explicitly chose 19.0.1 as "latest," documenting this decision. While this is a reasonable choice, it carries the implicit assumption that the project's dependency tree actually uses 19.0.1—an assumption that was not independently verified against Cargo.lock.

Input Knowledge and Output Knowledge

To fully understand this investigation, one needs familiarity with Filecoin's proof architecture (PoRep, PoSt, Update proofs), Groth16 zk-SNARK concepts (circuit synthesis, SRS, proving), Rust's cargo ecosystem and module system, and the specific context of the cuzk project's pipelined proving engine. The investigation assumes knowledge of the CompoundProof trait as the central abstraction, the role of SuprasealParameters as a bridge to C++ GPU code, and the distinction between pub and pub(crate) visibility in Rust.

The output knowledge produced is substantial. The investigation produced a complete map of the API surface spanning six major source files, identified the architectural seam for pipelining (synthesize_circuits_batch / prove_from_assignments), documented visibility annotations critical for cross-crate integration, and uncovered variant implementations (Poseidon) that a less thorough investigation might have missed. This knowledge directly feeds into the Phase 2 pipeline implementation, enabling the developer to write integration code with confidence about the interfaces they must call.

Conclusion

This chunk of work represents a masterclass in systematic API reconnaissance. The assistant navigated tooling constraints (permission failures, output truncation, incorrect flags), adapted strategies on the fly, and produced a comprehensive reference document that serves as the foundation for one of the most significant refactoring efforts in the Filecoin proving stack. The identification of synthesize_circuits_batch and prove_from_assignments as the natural split point for pipelining is the key architectural insight that enables the entire Phase 2 design—reducing peak memory from ~200 GiB to ~64-103 GiB and enabling the pipeline to function on commodity hardware.

The investigation also demonstrates a reproducible methodology for exploring unfamiliar codebases: locate files, measure scope, grep for key symbols, read targeted sections, and synthesize findings into a structured reference. This pattern, applied systematically across the Filecoin proof stack, produced the deep understanding necessary to architect a continuous, memory-efficient proving pipeline optimized for heterogeneous cloud rental markets where RAM cost dominates.## References

[1] "The Reconnaissance Message: Mapping Upstream APIs for the cuzk Phase 2 Pipeline" — Analysis of the initial subagent message requesting API reconnaissance across six Filecoin proof source files.

[2] "Reading the Source: Mapping Filecoin's Proof APIs for Pipeline Integration" — Examination of the parallel file-reading phase where the assistant extracted function signatures and trait definitions.

[3] "The Pivot Point: How a Truncated Output Forced a Strategic Tooling Decision in the cuzk Pipeline Investigation" — Analysis of the assistant's switch from grep-based search to direct file reading due to output truncation.

[4] "Tracing the Supraseal Integration: A Systematic Search Through Filecoin's Proof Pipeline" — Documentation of the search for ParameterSource and supraseal references across the bellperson fork.

[5] "Mapping the Groth16 Proving Pipeline: A Systematic Source-Code Reconnaissance" — Analysis of the initial glob-based file discovery strategy and its limitations.

[6] "Tracing the Thread: How a Subagent Navigated Upstream Proof APIs in the cuzk Pipeline" — Examination of targeted ripgrep searches for trait definitions and struct relationships.

[7] "Mapping the Proof Pipeline: A Methodical Reconnaissance of Filecoin's Rust API Surface" — Analysis of the transition from file discovery to content extraction using rg and wc.

[8] "Pivoting Under Constraint: How a Permission Failure Forced a Strategic Tool Switch in an OpenCode Coding Session" — Documentation of the permission failure that forced a switch from glob tools to bash commands.

[9] "The Thoroughness Check: Uncovering Poseidon Variants in the Filecoin Proof Pipeline" — Analysis of the proactive check for Poseidon hash variants of EmptySectorUpdateCompound.

[10] "Mapping the SupraSeal Frontier: A Deep Dive into the Phase 2 cuzk Pipeline API Research" — The comprehensive synthesis report documenting all six API targets and the critical pipeline seam.