Bridging Local and Remote: The cuzk Integration File for Filecoin Proof Generation

Message Overview

In message [msg 3416] of this opencode session, the assistant performs a single, focused action: it writes a new file lib/ffi/cuzk_funcs.go to the Curio codebase. The message itself is terse:

Good. Now I'll write the cuzk integration file for SealCalls — methods that generate vanilla proofs locally and then delegate SNARK to cuzk: [write] /home/theuser/curio/lib/ffi/cuzk_funcs.go Wrote file successfully.

LSP errors detected in other files: ERROR [129:19] cannot use cgo.RegisteredPoStProofStackedDrgWindow32GiBV1_1 (constant unknown with invalid type) as cgo.RegisteredPoStProof value in assignment

Despite its brevity, this message represents a pivotal architectural moment in the session. It is the point at which the abstract plan to integrate a remote GPU proving daemon (cuzk) into Curio's task orchestrator crystallizes into concrete code. The file being created is the bridge between two fundamentally different execution contexts: the local machine, which holds sector data and can generate "vanilla" proofs, and the remote cuzk daemon, which has GPU capacity to perform the computationally intensive SNARK (Succinct Non-interactive Argument of Knowledge) proving step.

The Reasoning and Motivation

To understand why this message was written, one must trace the session's trajectory through the preceding messages. The session had been working on Phase 12 of the cuzk proving pipeline — a split GPU proving API that decouples the GPU worker's critical path from CPU post-processing. After completing Phase 12's documentation and low-memory benchmarking (documented in the chunk summary), the session shifted to a new, ambitious goal: integrating the cuzk proving daemon into Curio's existing task orchestrator.

Messages [msg 3372] through [msg 3415] show a systematic research phase. The assistant read through Curio's task implementations for PoRep (Proof-of-Replication), SnapDeals, WindowPoSt, and WinningPoSt. It examined the harmony task framework to understand Do(), CanAccept(), and TypeDetails() patterns. It studied the SealCalls struct in lib/ffi/sdr_funcs.go and lib/ffi/snap_funcs.go to understand how proofs are currently generated.

The critical insight emerged in [msg 3413], where the assistant analyzed the PoRepSnark method:

The key insight: PoRepSnark does two things: 1. GeneratePoRepVanillaProof — generates vanilla proof (CPU, on the machine that has the sector data) 2. SealCommitPhase2 — runs the SNARK computation (GPU)

For cuzk integration, we need to split this. The vanilla proof generation must still happen locally (it needs sector data), but the SNARK computation goes to cuzk.

This decomposition is the foundational reasoning behind message [msg 3416]. The assistant recognized that the existing proof pipeline conflates two fundamentally different operations: a data-local CPU computation (vanilla proof generation) and a GPU-accelerated cryptographic computation (SNARK proving). The cuzk daemon is designed to handle the latter remotely, but the former must remain local because it requires access to sector data stored on the machine's filesystem.

The motivation, then, is to create a clean separation layer. Rather than modifying the existing PoRepSnark method (which would risk breaking existing local-only workflows), the assistant chose to create new methods on the SealCalls struct that explicitly implement the split: generate vanilla proof locally, then submit to cuzk via gRPC.

How Decisions Were Made

Several architectural decisions are embedded in this single write operation:

Decision 1: New file, not modification of existing files. The assistant chose to create lib/ffi/cuzk_funcs.go rather than adding methods to sdr_funcs.go or snap_funcs.go. This keeps the cuzk integration self-contained and makes it easy to conditionally compile or exclude. It also respects the existing separation of concerns: sdr_funcs.go handles SDR (Seal Data Registration) and PoRep, snap_funcs.go handles SnapDeals, and now cuzk_funcs.go handles the remote proving integration for all proof types.

Decision 2: Methods on SealCalls, not standalone functions. The assistant extended the existing SealCalls struct rather than creating a new service layer. This leverages the struct's existing access to sector storage (via sb.Sectors.storage) and its established patterns for error handling and context propagation. The SealCalls struct already has methods like GeneratePoRepVanillaProof and ReadSnapVanillaProof — the new methods simply wrap these with a gRPC submission step.

Decision 3: Split vanilla generation from SNARK submission. The most important design decision is architectural: vanilla proof generation remains a local, synchronous call, while SNARK computation is offloaded to the remote daemon. This respects the data locality constraint (vanilla proofs need sector data) while enabling GPU offloading. The new methods (presumably named something like PoRepSnarkCuzk and SnapProveCuzk) would call the existing vanilla generation methods internally, then package the result into a gRPC request to the cuzk daemon.

Decision 4: Follow existing naming and signature conventions. By placing the new methods on SealCalls, the assistant ensures they integrate naturally with the existing task implementations. The task's Do() method can call sb.PoRepSnarkCuzk(...) with the same parameters as the existing sb.PoRepSnark(...), minimizing disruption to the calling code.

Assumptions Made

The message and its surrounding context reveal several assumptions:

The cuzk daemon is operational and reachable. The assistant assumes that the cuzk daemon (whose protobuf definitions live in extern/cuzk/cuzk-proto/proto/) is already built, deployed, and listening on a known endpoint. The gRPC client wrapper created in [msg 3407] (lib/cuzk/client.go) assumes a connection can be established.

The protobuf definitions are correct and sufficient. The generated Go stubs (proving.pb.go and proving_grpc.pb.go) were created in [msg 3397]-[msg 3406] and compiled successfully. The assistant assumes these stubs correctly implement the cuzk API and that the SealCalls methods can construct valid requests from vanilla proof data.

Vanilla proof methods are adequate. The assistant assumes that GeneratePoRepVanillaProof and ReadSnapVanillaProof (the methods used in sdr_funcs.go and snap_funcs.go) produce output that can be directly forwarded to the cuzk daemon without transformation. This is a reasonable assumption given that these methods already produce the C1 output that the SNARK step consumes.

The SealCalls struct will have access to a cuzk client. The new methods need a *cuzk.Client instance to make gRPC calls. The assistant implicitly assumes this will be wired in — either as a field on SealCalls, as a parameter to the new methods, or through some other mechanism. The subsequent messages (in chunk 1) show the assistant adding cuzkClient *cuzk.Client fields to the task structs and passing them through.

Mistakes and Incorrect Assumptions

The LSP errors displayed in the message are noteworthy but misleading. They reference a pre-existing issue in lib/ffiselect/ffidirect/ffi-direct.go involving a CGO type mismatch (cannot use cgo.RegisteredPoStProofStackedDrgWindow32GiBV1_1 ... as cgo.RegisteredPoStProof value in assignment). This error is unrelated to the new file — it is a build environment issue where CGO headers for Filecoin's FVM (Filecoin Virtual Machine) are not installed on this development machine. The assistant acknowledges this in the subsequent message ([msg 3418]) with "CGO/FVM errors are expected on this machine (no FVM headers)."

A more subtle potential issue is the assumption that the vanilla proof output format matches what the cuzk daemon expects. The protobuf definitions in cuzk/v1/proving.proto define the gRPC API, and if the vanilla proof data requires any serialization transformation (e.g., JSON to protobuf, or different field naming), the new methods would need to handle that. The assistant's approach of creating a dedicated file suggests awareness that some adaptation logic may be needed, but the exact mapping is not visible in this message.

Another assumption worth examining is that the split between local vanilla proof generation and remote SNARK computation is clean for all proof types. For PoRep, the vanilla proof is generated by GeneratePoRepVanillaProof and the SNARK by SealCommitPhase2. For SnapDeals, the vanilla proof is read from storage via ReadSnapVanillaProof. For WindowPoSt and WinningPoSt, the pattern may differ. The assistant's plan (from the chunk summary) mentions modifying four task types, but the uniformity of the split across all of them is an open question.

Input Knowledge Required

To fully understand this message, a reader needs familiarity with several domains:

Filecoin proof architecture. Filecoin uses a two-phase proof system: a "vanilla proof" (also called C1) that commits to the sector data, and a SNARK (C2) that compresses the vanilla proof into a compact Groth16 proof. The vanilla proof is CPU-bound and data-local; the SNARK is GPU-bound and memory-intensive (the session's earlier work documented ~200 GiB peak memory for the SNARK).

The Curio task orchestrator. Curio is a Filecoin storage miner implementation that uses a "harmony" task framework. Tasks implement interfaces like Do(), CanAccept(), and TypeDetails() to participate in scheduling. The assistant had studied these patterns extensively in the preceding messages.

The SealCalls struct. This is a central abstraction in lib/ffi/ that wraps Filecoin's FFI (Foreign Function Interface) calls. It provides methods like GenerateSDR, TreeRC, PoRepSnark, and ProveUpdate, all of which interact with the underlying Rust/C++ proof generation library.

gRPC and protobuf patterns. The assistant generated Go stubs from protobuf definitions, created a client wrapper, and is now writing methods that use that client. Understanding the gRPC service definition (request/response types) is necessary to imagine what the new methods do.

Output Knowledge Created

This message produces one concrete artifact: the file lib/ffi/cuzk_funcs.go. While we cannot see its contents directly in this message (the write succeeded but the content is not displayed), we can infer its structure from the context:

It defines new methods on the SealCalls struct, such as PoRepSnarkCuzk and SnapProveCuzk.
These methods call the existing vanilla proof generation methods (GeneratePoRepVanillaProof, ReadSnapVanillaProof) locally.
They then construct gRPC requests using the protobuf types from lib/cuzk/ and submit them to the cuzk daemon.
They handle the gRPC response, which presumably contains the final Groth16 proof.
They may include error handling, retry logic, or verification steps. This file is the critical integration layer. Before it existed, proof generation was entirely local: vanilla proof generation and SNARK computation happened on the same machine, requiring both sector data access and GPU capacity. After this file, the SNARK computation can be offloaded to a remote GPU cluster, while the vanilla proof generation remains local. This enables a new deployment architecture where storage-heavy machines (with large disk arrays for sector data) can be separate from computation-heavy machines (with multiple GPUs for SNARK proving).

The Thinking Process

The assistant's thinking process is visible through the chain of research messages leading up to this write operation. The pattern is methodical:

Understand the existing code. Messages [msg 3372]-[msg 3382] read through task implementations, the harmony framework, and the SealCalls methods. The assistant traces the full call chain from task creation to proof generation.
Identify the split point. In [msg 3413], the assistant explicitly articulates the insight that PoRepSnark combines two distinct phases and that only the second phase (SNARK) needs to be offloaded.
Build the infrastructure. Messages [msg 3387]-[msg 3406] add the CuzkConfig to Curio's configuration, generate protobuf stubs, create the gRPC client wrapper, and verify compilation.
Create the integration layer. This is where message [msg 3416] fits. With the infrastructure in place (config, protobuf stubs, client wrapper), the assistant now writes the methods that bridge the local and remote worlds.
Wire into tasks. The subsequent messages (in chunk 1) modify the task implementations to use the new methods. This progression shows a clear architectural vision. The assistant is not writing code ad-hoc; it is constructing a layered integration: configuration → protobuf definitions → gRPC client → SealCalls methods → task modifications. Each layer builds on the previous one, and each is verified (compilation checks) before proceeding.

Conclusion

Message [msg 3416] may appear unremarkable at first glance — a single file write with a brief comment. But in the context of the session's arc, it is the keystone of a significant architectural change. The file lib/ffi/cuzk_funcs.go represents the boundary between local and remote computation, between CPU-bound data access and GPU-accelerated cryptography, between Curio's existing monolithic proof pipeline and a new, distributed proving architecture. The assistant's decision to create new methods on SealCalls rather than modifying existing ones, to keep the integration in a dedicated file, and to preserve the existing vanilla proof generation paths all reflect careful architectural thinking. This message is where the plan becomes code.