feat(network): add structured failure traces to fail fulfillment#231
Open
fakedev9999 wants to merge 1 commit into
Open
feat(network): add structured failure traces to fail fulfillment#231fakedev9999 wants to merge 1 commit into
fakedev9999 wants to merge 1 commit into
Conversation
…Trace helper Producer-side support so the open-source sp1-cluster fulfiller can ship a structured, sanitized failure trace to SPN, wire-compatible with network-services PR #1191 (succinctlabs/network-services#1191). - proto: FailFulfillmentRequestBody.error_trace = 4 (additive, optional bytes; same field number/shape as network-services) - port the canonical ErrorTrace authoring/sanitization module from #1191: from_cluster_extra_data (real string task_type + integer), finalize (redact secrets, bound sizes, drop-if-useless), to_wire_bytes; regex-free sanitizer - regenerate committed proto types (types.rs) The error_trace module is intentionally byte-identical (modulo this repo's rustfmt) to network-services so the two non-synced proto repos stay consistent.
0xernesto
approved these changes
Jun 18, 2026
0xernesto
left a comment
Contributor
There was a problem hiding this comment.
Looks like you need to add error_trace: None to make CI pass
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an optional structured failure trace field to
FailFulfillmentRequestBodyso open-source prover clusters can send useful failure context when reporting failed fulfillments.This is the producer-side wire contract for network-services PR #1191. The field number intentionally matches the receive-side proto there:
FailFulfillmentRequestBody.error_trace = 4The field carries bounded, sanitized UTF-8 JSON bytes. Consumers may omit it when no useful context is available.
Why
External prover operators run the open-source
sp1-clusterfulfiller, which depends on this repo'sspn-network-types. Today that fulfiller can reduce cluster failure details to a coarseProofRequestError, but it has no wire field for the original structured context. As a result, mainnet SPN requests can end up with opaque failures likeUnknown Error.This PR gives the fulfiller a compatible field and helper for constructing the trace from cluster
extra_data.What Changed
optional bytes error_trace = 4toFailFulfillmentRequestBody.spn_network_types::error_trace, including:ErrorTrace::from_cluster_extra_data(...)task_typeis serialized as a string enum name, for example:{"proving_failure":{"reason":"GPU OOM","task_type":"ProveShard"}}Scope
This PR only adds the wire contract and producer-side helper in
network.The follow-up
sp1-clusterPR will:networkrevbin/fulfillerto convertproof_requests.extra_dataintoerror_tracefail_fulfillmentThe receive/store side is handled separately in network-services PR #1191.
Validation
cargo build --features networkcargo test -p spn-network-types error_trace --lib→ 44 passedcargo +nightly fmt --check→ cleancargo clippy --features network -D warnings→ cleangit diff --check→ clean