Reading the Source: How One File Read Shaped the cuzk Integration Architecture

The message is deceptively simple. In message 3412, the assistant issues a single read tool call targeting /home/theuser/curio/lib/ffi/sdr_funcs.go, accompanied by a brief but revealing reasoning comment:

Let me first understand how PoRepSnark gets the vanilla proof data — I need to understand what gets sent to cuzk.

This is not a casual glance at code. It is a deliberate, architecturally significant read operation that sits at the intersection of two major efforts: the multi-phase optimization of the SUPRASEAL_C2 Groth16 proof generation pipeline, and the integration of the resulting cuzk proving daemon into Curio's production task orchestrator. The message captures a moment of focused understanding — the instant when infrastructure meets existing architecture, and the design of the integration begins to take shape.

The file being read, lib/ffi/sdr_funcs.go, contains the SealCalls struct — the primary interface through which Curio's Go task layer invokes Filecoin proof generation. The specific function of interest is PoRepSnark, which performs the full Groth16 SNARK computation for Proof-of-Replication (PoRep) sectors. By reading this function, the assistant seeks to answer a fundamental question: what data flows from the local task to the remote proving daemon?

The Broader Context: Remote Proving for Memory-Constrained Environments

To understand why this read matters, one must appreciate the broader effort it serves. The cuzk integration is the culmination of a long optimization campaign documented across Phases 10 through 12 of the session. The SUPRASEAL_C2 Groth16 proof generation pipeline for Filecoin PoRep had been identified as consuming approximately 200 GiB of peak memory — a prohibitive requirement for many deployment scenarios, particularly in heterogeneous cloud environments where GPU-equipped nodes may be scarce or expensive.

Through Phases 10 and 11, the team developed and benchmarked memory-bandwidth interventions, identifying DDR5 memory contention as the primary bottleneck. Phase 12 introduced a split GPU proving API that decoupled the critical GPU worker path from CPU post-processing, along with memory backpressure mechanisms including early deallocation of NTT evaluation vectors and channel capacity auto-scaling. The result was a stable proving pipeline capable of sustaining 37.7 seconds per proof at pw=12 without out-of-memory errors.

Now, in Segment 33, the focus shifts from optimizing the proving pipeline itself to integrating it into Curio's production task orchestrator. The goal is to allow Curio nodes to offload SNARK computation to a remote cuzk daemon, bypassing the need for local GPU resources and high-memory provisioning. This is particularly important for deployments where some nodes have GPUs and others do not — the daemon can run on dedicated GPU hardware while task workers operate on cheaper, memory-constrained nodes.

The integration pattern is clear: local tasks will generate "vanilla proofs" (which require access to sector data on local storage) and then delegate the computationally intensive SNARK compression to the cuzk daemon via gRPC. But before this pattern can be implemented, the assistant must understand exactly what data the existing PoRepSnark function produces and consumes.## What the Read Revealed

The function PoRepSnark at line 360 of sdr_funcs.go has a clear structure. It begins by calling GeneratePoRepVanillaProof on the storage backend, passing the sector reference, sealed and unsealed CIDs, ticket, and seed. The vanilla proof — a set of raw commitments and Merkle paths produced by the SDR (Stacked Depth Robust) graph computation — is then fed into the SNARK compression step that produces the final Groth16 proof.

This two-phase structure is critical for the integration design. The vanilla proof generation requires access to the sector's sealed and unsealed data on local storage. It reads actual sector files, computes Merkle proofs, and produces intermediate commitments. This phase is I/O-bound and storage-local — it cannot be meaningfully offloaded to a remote daemon without streaming large amounts of sector data over the network.

The SNARK phase, however, is purely computational. It takes the vanilla proof bytes and performs the Groth16 prover computation: multi-scalar multiplication (MSM), number-theoretic transform (NTT), and the various polynomial commitments that constitute the final proof. This is the phase that consumes ~200 GiB of memory and requires GPU acceleration. It is the natural candidate for remote offloading.

The read thus confirms a clean architectural boundary: the vanilla proof is the unit of transfer between local and remote. The local task generates it, serializes it, and sends it to the cuzk daemon via gRPC. The daemon performs the SNARK and returns the final proof bytes. This boundary is already implicit in the existing code — PoRepSnark is itself a composition of two phases — but the integration makes it explicit and remote.

Input Knowledge Required

To understand this message and its significance, one needs substantial context from the broader session. The reader must know that:

• Curio is a Filecoin storage provider node that manages sector lifecycle tasks including sealing, proving, and post.
• PoRep (Proof-of-Replication) is the mechanism by which storage providers prove they are storing unique copies of data.
• Groth16 is the zero-knowledge proving system used by Filecoin for SNARK compression of PoRep proofs.
• SUPRASEAL_C2 is the specific implementation of the Groth16 prover used in production, known for its high memory footprint (~200 GiB).
• The cuzk daemon is a remote proving service developed in the earlier phases of this session, implementing the optimized split-API pipeline.
• Vanilla proofs are intermediate proof representations — the output of the SDR graph computation — that are then compressed into final Groth16 proofs via SNARK. Without this context, the read appears trivial: the assistant is simply looking at a function signature. But with this context, it becomes a pivotal architectural decision point.

The Thinking Process Visible in the Reasoning

The assistant's comment — "Let me first understand how PoRepSnark gets the vanilla proof data — I need to understand what gets sent to cuzk" — reveals a methodical, architecture-first approach. The assistant is not diving into implementation details prematurely. Instead, it is establishing the data contract between two systems: the local task worker and the remote proving daemon.

The phrasing "what gets sent to cuzk" is particularly telling. It frames the problem in terms of data boundaries and interfaces. The assistant is thinking about the integration as a communication protocol: what data crosses the wire, in what format, and with what semantics. This is the hallmark of good systems design — defining the interface before implementing either side.

The read is also sequential in the assistant's broader workflow. Looking at the surrounding messages, the assistant has already:

1. Read the task implementations (PoRep, Snap Prove, WdPost, WinningPost) to understand Do/CanAccept patterns.
2. Read the harmony task framework to understand scheduling and resource accounting.
3. Read lib/ffi to understand the current proof execution flow.
4. Added the CuzkConfig struct to the Curio configuration types.
5. Generated the Go gRPC client code from the protobuf definitions.
6. Created the lib/cuzk/client.go wrapper. Now, before wiring the client into the task implementations, the assistant pauses to verify its understanding of the data flow. This is a deliberate quality gate: the assistant is checking its assumptions against the actual code before committing to the integration pattern.## Assumptions Embedded in the Read The assistant makes several assumptions in this message, most of which are well-founded but worth examining:
7. The vanilla proof is the correct unit of transfer. The assistant assumes that the boundary between vanilla proof generation and SNARK compression is the right place to split the computation between local and remote. This is a reasonable assumption given the existing code structure, but it has implications: the vanilla proof itself can be large (potentially megabytes), and serializing it for gRPC transport adds overhead. An alternative design might have streamed sector data directly to the daemon, bypassing the vanilla proof intermediate representation entirely. The assistant implicitly rejects this alternative by accepting the existing boundary.
8. The SealCalls struct is the right abstraction to extend. The assistant assumes that the integration should work through the existing SealCalls methods rather than creating a completely separate path. This is consistent with the earlier decision to add PoRepSnarkCuzk and similar methods to SealCalls, as seen in the lib/ffi/cuzk_funcs.go file mentioned in the chunk summaries. This preserves the existing task lifecycle while adding a remote path.
9. gRPC is the right transport. The assistant has already generated protobuf stubs and created a gRPC client. This assumption is validated by the existing infrastructure — Curio already uses gRPC for other internal communication, and the cuzk daemon exposes a gRPC API. However, it means the integration inherits gRPC's latency and serialization characteristics.
10. The remote daemon can handle the workload without local resource accounting. The integration design zeros out GPU/RAM costs in TypeDetails() when cuzk is enabled, relying on the daemon's queue for backpressure via CanAccept(). This assumes the daemon is always reachable and has capacity — a reasonable assumption for a cluster deployment but worth noting as a potential failure mode.

Potential Mistakes and Incorrect Assumptions

While the assistant's approach is sound, there are subtle pitfalls worth considering:

The vanilla proof format may not be stable across versions. The GeneratePoRepVanillaProof function returns raw bytes whose structure is determined by the Filecoin proof specification. If the protocol evolves, the serialization format may change, and both the local task and the remote daemon must be updated in lockstep. The integration does not include a version negotiation mechanism, which could lead to silent failures if versions diverge.

Latency of gRPC for large vanilla proofs. The vanilla proof for a 32 GiB sector can be several megabytes. Serializing this to protobuf, transmitting over gRPC, and deserializing on the daemon adds non-trivial latency. The assistant does not appear to have benchmarked this overhead, though it may be small compared to the ~37-second SNARK computation time.

Error handling across the network boundary. The existing PoRepSnark function returns errors from local computation. When the SNARK is performed remotely, network errors, daemon crashes, and queue timeouts introduce new failure modes. The integration must handle these gracefully, potentially falling back to local computation. The assistant's design appears to treat the remote daemon as always-available, with CanAccept() as the only backpressure mechanism.

Output Knowledge Created by This Message

This message, while appearing to be a simple read operation, creates several forms of output knowledge:

1. Confirmation of the data boundary. The assistant now knows definitively that the vanilla proof is the correct intermediate representation to transmit to the remote daemon. This is not stated explicitly in the message but is the logical conclusion of reading the function.
2. Validation of the integration pattern. The existing PoRepSnark function's two-phase structure validates the design decision to split vanilla proof generation (local) from SNARK compression (remote). The assistant can proceed with confidence that the pattern is architecturally sound.
3. A reference point for the other task types. The same two-phase pattern applies to SnapDeals (ProveUpdate) and proofshare tasks. Understanding PoRepSnark provides a template for the other integrations. The assistant will later apply the same logic to computeProof, computePoRep, and computeSnap in the proofshare and SnapDeals tasks.
4. Documentation of the architectural decision. While not captured in a separate document, the reasoning in this message — "I need to understand what gets sent to cuzk" — documents the design rationale. Future readers of the conversation can trace the integration back to this moment of understanding.

The Broader Significance

This message exemplifies a pattern that recurs throughout the opencode session: the assistant alternates between reading and writing, between understanding and implementing. Each read operation is purposeful, driven by a specific question that must be answered before proceeding. The reads are not exploratory — they are targeted, informed by the assistant's growing mental model of the codebase.

In this case, the read is the last piece of research before the implementation sprint. In the messages immediately following (not shown in the subject message but visible in the surrounding context), the assistant proceeds to wire the cuzk client into the PoRep, SnapDeals, and proofshare task implementations. The read of PoRepSnark provides the final piece of confidence needed to execute that integration.

For a reader studying this session, message 3412 is a quiet but crucial moment. It is the point where the assistant transitions from "I know the architecture" to "I have verified the architecture against the code." It is a reminder that good systems design is not just about writing code — it is about reading the right code at the right time, with the right questions in mind.