Tracing the Feature Flag Chain: How `cuda-supraseal` Propagates Through Filecoin's Proof Pipeline

Introduction

In the midst of a deep-dive investigation into the SUPRASEAL_C2 Groth16 proof generation pipeline for Filecoin PoRep, a single bash command at message index 66 represents a critical juncture in the exploration. The investigator, having traced the prover dispatch logic from Curio's Go task layer through Rust FFI into bellperson's Rust internals, now needs to confirm how the cuda-supraseal feature flag propagates from the top-level filecoin-proofs crate down to bellperson, where it controls whether the native GPU prover or the supraseal C++ prover is compiled. This message is the capstone of a feature-flag tracing effort that began several messages earlier, and it provides the final confirmation that the architectural picture assembled so far is correct.

The Message

The assistant executes a targeted grep against the filecoin-proofs-18.1.0 crate's Cargo.toml:

grep -n "feature\|supraseal\|cuda\|opencl" /home/theuser/.cargo/registry/src/index.crates.io-6f17d22bba15001f/filecoin-proofs-18.1.0/Cargo.toml 2>&1 | head -30

The output reveals the feature flag definitions:

51:default-features = false
55:features = [
59:default-features = false
63:default-features = false
101:features = [
114:default-features = false
118:default-features = false
122:default-features = false
126:default-features = false
146:[features]
150:cuda = [
151:    "storage-proofs-core/cuda",
152:    "storage-proofs-porep/cuda",
153:    "storage-proofs-post/cuda",
154:    "storage-proofs-update/cuda",
155:    "bellperson/cuda",
156:    "filecoin-hashers/cuda",
158:cuda-supraseal = [
159:    "...

The output is truncated by head -30, but the critical structure is already visible: the cuda feature enables GPU acceleration across all sub-crates including bellperson/cuda, while the cuda-supraseal feature (line 158) provides an alternative path that presumably enables bellperson/cuda-supraseal instead.

Why This Message Was Written: The Reasoning and Motivation

This message did not emerge from a vacuum. It is the direct result of a systematic investigation that began with understanding how Curio schedules proof tasks, moved through the Rust FFI boundary in filecoin-ffi, and arrived at the critical dispatch point in bellperson's groth16/prover/mod.rs. In message 50, the investigator discovered the pivotal code:

#[cfg(not(feature = "cuda-supraseal"))]
mod native;
#[cfg(feature = "cuda-supraseal")]
mod supraseal;

This conditional compilation block is the entire mechanism by which Filecoin's proof pipeline selects between the standard GPU prover (which uses ec-gpu-gen for NTT and MSM on GPU) and the supraseal C++ prover. When the cuda-supraseal feature is enabled, the entire native prover module is excluded from compilation, and the supraseal module takes over. When it is not enabled, the native prover compiles in, which itself conditionally uses GPU acceleration via the cuda or opencl features.

However, the investigator had only seen this dispatch logic in bellperson-0.26.0. The critical missing piece was: how does the cuda-supraseal feature get enabled in the first place? The feature is defined in bellperson's own Cargo.toml (message 48 confirmed cuda-supraseal = ["supraseal-c2"]), but it must be activated by a higher-level crate. The chain of feature propagation needed to be traced upward through filecoin-proofs and filecoin-proofs-api to understand the full build-time decision tree.

Message 66 is the moment this chain is traced to its source. The investigator had already checked filecoin-proofs-api-18.1.0 (message 65) and found that it defines cuda-supraseal to propagate to filecoin-proofs-v1/cuda-supraseal and storage-proofs-core/cuda-supraseal. Now message 66 checks filecoin-proofs-18.1.0 itself, which is the crate that directly depends on bellperson. The grep confirms that filecoin-proofs defines both cuda and cuda-supraseal feature flags, and the cuda flag explicitly enables bellperson/cuda (line 155). The cuda-supraseal flag (line 158, truncated) would correspondingly enable bellperson/cuda-supraseal.

This is the "smoking gun" that completes the feature flag propagation chain: filecoin-proofs-api → filecoin-proofs → bellperson, with the cuda-supraseal feature at each level selecting the supraseal prover instead of the native GPU prover.## How Decisions Were Made

The decision to run this particular grep command was shaped by the investigator's systematic methodology. Having already examined the bellperson prover dispatch logic (messages 50-52), the supraseal prover implementation (messages 52-54), and the GPU fallback mechanisms in the native prover (messages 55-61), the investigator understood the "what" and "how" of proof generation. But understanding the "why" — why a particular build would use supraseal versus native GPU — required tracing the feature flag chain upward.

The investigator had already attempted to check filecoin-proofs-api-19.0.0 in message 62, but that version was not present in the local Cargo registry cache. Rather than giving up, they pivoted to filecoin-proofs-api-18.1.0 (message 65), which was cached and functionally equivalent for the feature structure analysis. This pragmatic decision-making — working with available cached versions rather than requiring exact version matches — demonstrates an understanding that Cargo feature flag structures are relatively stable across minor versions in this ecosystem.

The decision to use head -30 to truncate output is also notable. The investigator knew from the earlier filecoin-proofs-api check that the feature definitions would appear near line 150 of the Cargo.toml, and that the first 30 lines of grep output would capture the [features] section and the beginning of the cuda and cuda-supraseal definitions. This was a targeted, efficient query — not a broad exploration, but a focused confirmation of a specific hypothesis.

Assumptions Made

Several assumptions underpin this message. The most significant is that filecoin-proofs-18.1.0 has the same feature flag structure as the version actually used in the Curio build (which depends on filecoin-proofs-api-19.0.0). The investigator explicitly acknowledges this by noting "The v19 is not cached yet. Let me check v18.1.0 which is effectively the same feature structure." This assumption is reasonable given the stability of Cargo feature flag schemas in production crates, but it is an assumption nonetheless. A future version could theoretically restructure its features, though this is unlikely for a well-established pattern.

Another assumption is that the cuda-supraseal feature at the filecoin-proofs level propagates to bellperson/cuda-supraseal in the same way that cuda propagates to bellperson/cuda. The grep output confirms cuda explicitly enables bellperson/cuda (line 155), and the truncated cuda-supraseal definition at line 158 likely mirrors this pattern. The investigator does not need to see the full definition to infer this, given the consistent naming conventions observed across all layers.

Input Knowledge Required

To fully understand this message, one needs substantial context from the preceding investigation. The reader must know:

The bellperson prover dispatch mechanism: That groth16/prover/mod.rs uses #[cfg(feature = "cuda-supraseal")] to choose between mod native and mod supraseal. Without this, the grep output is just a list of feature flags with no significance.
The difference between native and supraseal provers: The native prover uses ec-gpu-gen for NTT and MSM operations, optionally accelerated via GPU when the cuda or opencl features are enabled. The supraseal prover delegates to external C++ code via the supraseal-c2 crate, bypassing bellperson's own GPU kernels entirely.
The Cargo feature propagation pattern: That filecoin-proofs-api → filecoin-proofs → bellperson forms a dependency chain where each layer re-exports feature flags. The cuda-supraseal feature at the API level must be explicitly forwarded through each intermediate crate to reach bellperson.
The version situation: That v19 is not cached locally, so v18.1.0 is used as a proxy. This is a practical constraint of working in a development environment where not all dependency versions are pre-fetched.
The overall investigation goal: That the investigator is mapping the complete call chain from Curio's Go task scheduler through Rust FFI into C++/CUDA kernels, with a particular focus on the ~200 GiB peak memory footprint of SUPRASEAL_C2 proof generation.## Mistakes and Incorrect Assumptions While the grep command itself is correct and the output is accurate, there is a subtle limitation in the analysis. The investigator assumes that the cuda-supraseal feature at the filecoin-proofs level propagates to bellperson/cuda-supraseal in the same straightforward manner as cuda propagates to bellperson/cuda. However, the grep output is truncated at 30 lines, and the full cuda-supraseal definition is not visible. The output shows 158:cuda-supraseal = [ followed by 159: "... — the actual list of sub-features is cut off. This truncation is a minor methodological risk. The investigator is inferring the structure of cuda-supraseal based on the pattern established by cuda. While this inference is almost certainly correct — the naming conventions are consistent, and the bellperson Cargo.toml explicitly defines cuda-supraseal = ["supraseal-c2"] — it is still an inference rather than a direct observation. A more thorough approach would have been to run the grep without head -30 (or with a larger limit) to capture the complete feature definition. Alternatively, the investigator could have used sed -n '146,170p' to extract just the [features] section in full. Another potential blind spot is the assumption that the feature flag chain is the only mechanism for selecting the prover. In practice, there may also be runtime configuration, environment variables, or dynamic library loading that affects which prover is used. The BELLMAN_NO_GPU environment variable, which the investigator noted in earlier messages (e.g., message 55's grep for BELLMAN_NO_GPU), is one such runtime override. The feature flags control compile-time selection, but runtime conditions can further influence behavior. The investigator's focus on the compile-time chain is appropriate for understanding the static architecture, but a complete picture would also account for runtime dispatch.

Output Knowledge Created

This message produces concrete, verifiable knowledge about the Filecoin proof system's build configuration. Specifically, it confirms:

The filecoin-proofs crate defines both cuda and cuda-supraseal feature flags in its [features] section (line 146+). This means the choice between native GPU proving and supraseal proving is made at the filecoin-proofs level, not at the bellperson level directly.
The cuda feature explicitly enables bellperson/cuda (line 155). This is the path for standard GPU-accelerated proof generation using bellperson's own GPU kernels via ec-gpu-gen.
The cuda-supraseal feature exists and follows the same pattern (line 158), though its full definition is truncated. Based on the consistent naming and the earlier finding that bellperson defines cuda-supraseal = ["supraseal-c2"], the propagation chain is: filecoin-proofs-api → filecoin-proofs → bellperson → supraseal-c2.
The feature flag chain is complete and consistent across all three layers (API, proofs, bellperson). There is no gap or inconsistency that would prevent cuda-supraseal from reaching bellperson. This knowledge is critical for the broader investigation because it establishes that the SUPRASEAL_C2 pipeline is a compile-time alternative to the native GPU prover, not a runtime plugin or an additional layer. This has profound implications for the architecture documents being produced: any optimization or modification to the supraseal path requires recompilation of the entire dependency chain, not just a configuration change.

The Thinking Process Visible in Reasoning Parts

The investigator's reasoning, visible through the sequence of commands and file reads across messages 37-66, follows a clear pattern of top-down decomposition followed by bottom-up confirmation.

The top-down phase (messages 37-50) started at the Curio task layer, where resource requirements for proof tasks were found (e.g., Ram: 50 << 30 for SnapDeals ProveTask in message 38). This led to the Rust FFI boundary in filecoin-ffi (message 46-47), then into bellperson's prover dispatch logic (messages 50-51). At each step, the investigator followed the code path that would be taken during actual proof generation.

The bottom-up confirmation phase (messages 62-66) then traced the feature flag chain in the reverse direction: starting from bellperson's Cargo.toml (message 48), moving up to filecoin-proofs-api (message 65), and finally to filecoin-proofs (message 66). This bidirectional approach — tracing execution flow downward and configuration flow upward — is a hallmark of thorough systems analysis. It ensures that the understanding is consistent from both perspectives.

The investigator also demonstrates hypothesis-driven exploration. Rather than randomly searching for keywords, each grep command targets a specific question raised by previous findings. The question "how does cuda-supraseal get enabled?" emerged directly from discovering the #[cfg(feature = "cuda-supraseal")] dispatch in bellperson. The investigator then systematically traced the feature upward through the dependency graph until reaching the top-level crate that would be configured by the build system.

Broader Significance

This message, while seemingly mundane — a single grep command on a Cargo.toml file — is actually the keystone of a much larger architectural understanding. The feature flag chain it confirms is the mechanism by which Filecoin's proof pipeline selects between two fundamentally different proving strategies: the flexible, CPU-or-GPU native prover, and the specialized, GPU-only supraseal prover that achieves higher throughput at the cost of ~200 GiB peak memory.

For the documents being produced in this investigation — particularly the background reference document mapping the full call chain and the optimization proposals — this confirmation is essential. It means that any proposed optimization to the supraseal path (such as Sequential Partition Synthesis to reduce peak memory) must be implemented within the supraseal C++ codebase or its Rust bindings, not in bellperson's native prover. It also means that the two proving paths can coexist in the same binary only if both feature flags are compiled in, which has implications for deployment strategies.

Conclusion

Message 66 is a masterclass in targeted investigation. A single, well-crafted grep command, informed by a systematic top-down and bottom-up analysis, confirms the complete feature flag propagation chain for Filecoin's proof generation pipeline. The message demonstrates the power of hypothesis-driven exploration: each command answers a specific question raised by previous findings, and the results build cumulatively toward a comprehensive understanding.

The investigator's willingness to work with cached dependency versions (v18.1.0 instead of v19.0.0) and to make reasonable inferences from truncated output reflects practical engineering judgment. The minor risk of incomplete information from the head -30 truncation is acknowledged, but the consistency of the pattern across all observed layers makes the inference robust.

In the context of the broader investigation into SUPRASEAL_C2's ~200 GiB memory footprint, this message provides the final link in the configuration chain. The feature flag architecture is now fully mapped, the dispatch logic is understood, and the investigator can proceed to deeper analysis of the supraseal C++ codebase itself, armed with the knowledge of exactly how the system decides which prover to use.

Tracing the Feature Flag Chain: How cuda-supraseal Propagates Through Filecoin's Proof Pipeline