The Pivot Point: Patching Bellperson into the cuzk Workspace

Message 420 in the opencode session reads simply:

[assistant] [edit] /home/theuser/curio/extern/cuzk/Cargo.toml Edit applied successfully.

On its surface, this is one of the most mundane messages in the entire conversation — a file-editing operation confirming that a Cargo.toml was modified. Yet this message represents a critical inflection point in the cuzk proving engine project. It is the moment when weeks of architectural analysis, design documentation, and upstream code archaeology crystallize into a single, irreversible action: patching the dependency graph to replace the upstream bellperson crate with a local fork. Understanding why this edit matters, and what it enables, requires tracing the long chain of reasoning that led to it.

The Context: Phase 2 of the cuzk Proving Engine

The cuzk project is a pipelined SNARK proving daemon for Filecoin, designed to overcome the architectural limitations of the existing proof generation pipeline. Phase 0 had already built the gRPC daemon, priority scheduler, and end-to-end proving pipeline. Phase 1 implemented support for all four Filecoin proof types (WinningPoSt, WindowPoSt, SnapDeals, and PoRep C2) and added multi-GPU worker pool support. But Phase 1 still used the existing monolithic proving API — each proof request called filecoin-proofs-api::seal_commit_phase2() or equivalent, which performed both CPU synthesis and GPU proving as a single, indivisible operation.

The goal of Phase 2 is to split this monolithic operation into two phases that can be pipelined independently: CPU-intensive circuit synthesis (which can run on any thread) and GPU-intensive proving (which must run on a GPU worker). This split enables the daemon to pre-synthesize circuits during idle CPU time, queue them for GPU processing, and dramatically improve throughput by keeping both CPU and GPU busy simultaneously.

The Discovery: Bellperson Already Has the Split Internally

The assistant's analysis of bellperson's internals, conducted across messages 400–419, revealed a crucial fact: the synthesis/GPU split already exists inside bellperson. The function synthesize_circuits_batch() performs all constraint-system synthesis and returns a ProvingAssignment struct containing the a/b/c vectors. The GPU-phase code lives in create_proof_batch_priority_inner(), which takes those assignments and runs the multi-exponentiation and NTT operations on the GPU. The split is already there — it just isn't exposed as a public API.

This discovery was the key insight that shaped the entire Phase 2 strategy. Rather than rewriting bellperson's internals, the assistant could simply make existing internal APIs public and add a thin wrapper function. This "minimal fork" philosophy — exposing rather than rewriting — minimizes risk, preserves compatibility, and dramatically reduces the implementation burden.

The Fork: Creating extern/bellperson/

The assistant created the fork by copying the upstream bellperson 0.26.0 source into extern/bellperson/ ([msg 410]), then applied four targeted edits:

  1. Cargo.toml: Changed the package version to 0.26.0-cuzk.1 and added a [workspace] table so the fork could be used as a path dependency ([msg 413]).
  2. src/groth16/prover/mod.rs: Made the supraseal module pub (instead of private), made ProvingAssignment and all its fields pub, and made synthesize_circuits_batch() pub ([msg 414], [msg 415]).
  3. src/groth16/prover/supraseal.rs: Added a new pub fn prove_from_assignments() function that extracts the GPU-phase code from create_proof_batch_priority_inner() ([msg 416], [msg 417]).
  4. src/groth16/mod.rs: Added re-exports for the new public types ([msg 418]). These changes amount to roughly 130 lines — a remarkably small diff for the capability it unlocks.

The Problem: Cargo's Patch Mechanism

With the fork created, the assistant faced a classic Rust workspace problem: how to make all downstream dependencies use the local fork instead of the upstream crate from crates.io. The cuzk workspace depends on filecoin-proofs-api, which transitively depends on bellperson 0.26.0 through filecoin-proofs and storage-proofs-core. Without intervention, cargo build would fetch the upstream bellperson from crates.io, ignoring the local fork entirely.

Cargo provides the [patch.crates-io] mechanism for exactly this scenario. Adding a [patch.crates-io] section to the workspace's Cargo.toml tells Cargo to substitute the specified local version whenever any dependency in the workspace requests the upstream crate. This is the standard approach for using a modified fork without changing every downstream dependency declaration.

Message 420: The Edit Itself

Message 420 is the assistant applying this patch configuration. The edit adds something like the following to /home/theuser/curio/extern/cuzk/Cargo.toml:

[patch.crates-io]
bellperson = { path = "../extern/bellperson" }

This single addition is the bridge between the fork and the workspace. Without it, the fork is just a directory of source code — unused, uncompiled, irrelevant. With it, every crate in the workspace that depends on bellperson will transparently use the modified fork instead.

The Assumption That Nearly Failed

The assistant made a critical assumption about Cargo's version matching semantics. The fork's Cargo.toml was initially set to version 0.26.0-cuzk.1 ([msg 413]). In semantic versioning (semver), 0.26.0-cuzk.1 is a pre-release version — the -cuzk.1 suffix makes it a lower version than 0.26.0. When downstream dependencies specify bellperson = "0.26.0", Cargo's semver resolution requires an exact match for the 0.26.0 part. A pre-release like 0.26.0-cuzk.1 does not satisfy =0.26.0 unless the dependency explicitly opts into pre-releases.

This is why the first compilation attempt in message 421 produced the warning:

Patch 'bellperson v0.26.0-cuzk.1 (...)' was not used in the crate graph. Check that the patched package version and available features are compatible with the dependency requirements.

The patch was silently ignored because Cargo couldn't reconcile the version mismatch. The assistant diagnosed this correctly in message 422 and fixed it by reverting the version to plain 0.26.0 — exactly matching the upstream version. This is a subtle but critical detail: for [patch.crates-io] to work, the patched version must be semver-compatible with the version requested by dependencies. Using an exact version match is the safest approach.

Input Knowledge Required

To understand this message, one needs:

  1. Rust's dependency resolution and patching mechanism: How [patch.crates-io] works, the role of Cargo.lock, and the semver matching rules that determine whether a patch is applied.
  2. The cuzk workspace structure: That extern/cuzk/Cargo.toml is the workspace root, that it uses [workspace.dependencies] to share dependency specifications, and that downstream crates like cuzk-core and cuzk-server inherit bellperson transitively through filecoin-proofs-api.
  3. Bellperson's internal architecture: That the synthesis and GPU phases are already separated internally, that ProvingAssignment holds the intermediate state, and that exposing these APIs requires only visibility changes, not logic changes.
  4. The Phase 2 pipeline design: That the pipelined prover will call synthesize_circuits_batch() on CPU threads and prove_from_assignments() on GPU workers, with the ProvingAssignment struct as the unit of transfer between phases.
  5. The Filecoin proof generation stack: How filecoin-proofs-api → filecoin-proofs → storage-proofs-core → bellperson forms the call chain, and why modifying bellperson at the bottom of this chain is sufficient to split the pipeline at every level above.

Output Knowledge Created

This message produces:

  1. A patched dependency graph: The workspace's Cargo.toml now contains a [patch.crates-io] section that redirects bellperson to the local fork. This is the enabling change that allows all subsequent Phase 2 implementation work.
  2. A validated fork strategy: The approach of forking only bellperson (rather than also forking storage-proofs-core, filecoin-proofs, and filecoin-proofs-api) is confirmed to be viable. The patch mechanism works, and the fork compiles.
  3. A lesson in Cargo versioning: The initial version mismatch was caught and corrected. The final fork uses version 0.26.0 — identical to upstream — which satisfies all dependency requirements.
  4. A foundation for the pipelined prover: With the fork patched in, the next steps (messages 424+) can begin implementing the actual pipeline logic in cuzk-core, calling the newly exposed APIs.

The Broader Significance

Message 420 is, in many ways, the most important message in the Phase 2 implementation sequence. It is the point where design becomes reality — where all the analysis, documentation, and planning translate into a concrete change that alters the behavior of the entire build system. The edit itself is trivial (a few lines of TOML), but the reasoning behind it is anything but.

The assistant had to understand: