Network APIs

This document outlines the methods, APIs, and protocol specifications required for a node to interact with the Succinct Prover Network to run a prover service.

Core Services

ProverNetwork Service

The ProverNetwork service is the primary interface for node operations on the network. It handles proof requests, account management, program management, and payments.

Service definition: proto/network.proto

Proof Request Methods

Method	Description	Auth Required
RequestProof	Creates a new proof request	Yes
FulfillProof	Fulfills a proof request with the generated proof	Yes - Assigned fulfiller only
ExecuteProof	Executes a proof request	Yes - Execution oracle only
FailFulfillment	Reports failure in fulfilling a request	Yes - Assigned fulfiller only
FailExecution	Reports failure in executing a request	Yes - Execution oracle only
GetProofRequestStatus	Retrieves the current status of a proof request	No
GetProofRequestDetails	Retrieves detailed information about a proof request	No
GetFilteredProofRequests	Retrieves proof requests that match filter criteria	No

Account Management Methods

Method	Description	Auth Required
GetNonce	Retrieves the current nonce for an account	No
GetFilteredDelegations	Retrieves delegations for an account	No
AddDelegation	Adds a delegation to an account	Yes - Account owner only
RemoveDelegation	Removes a delegation from an account	Yes - Account owner only
TerminateDelegation	Terminates a delegation	Yes - Delegate only
AcceptDelegation	Accepts a delegation	Yes - Delegate only
SetAccountName	Sets the name for an account	Yes - Account owner only
GetAccountName	Retrieves the name of an account	No
GetTermsSignature	Checks if account has signed terms	No
SetTermsSignature	Sets terms signature status for account	Yes - Account owner only
GetAccount	Retrieves all information about an account	No
GetOwner	Gets the owner of an account	No

Program Management Methods

Method	Description	Auth Required
GetProgram	Retrieves metadata about a program	No
CreateProgram	Creates a new program	Yes
SetProgramName	Sets the name for a program	Yes - Program owner only

Payment Methods

Method	Description	Auth Required
GetBalance	Retrieves the available balance of an account	No
GetFilteredBalanceLogs	Retrieves balance logs that match filter criteria	No

ArtifactStore Service

The ArtifactStore service manages the creation and storage of artifacts such as programs, input data, and proofs.

Service definition: proto/artifact.proto

Method	Description	Auth Required
CreateArtifact	Creates an artifact that can be used for proof requests	Yes

Verifier Service

The Verifier service provides verification for generated proofs.

Service definition: proto/verifier.proto

Method	Description	Auth Required
VerifyProof	Verifies a proof against a verification key	No

Node Implementation

Node Components

A prover node in the Succinct Prover Network consists of the following core components:

Implementation: crates/node/src/lib.rs

1. Context (NodeContext): Maintains shared state and provides access to:

   • Network client for API interactions
   • Signer for authentication
   • Metrics for monitoring

2. Bidder (NodeBidder): Responsible for:

   • Monitoring available proof requests
   • Evaluating capability to fulfill requests
   • Submitting bids on suitable requests
   • Determining appropriate bid amounts

3. Prover (NodeProver): Responsible for:

   • Fetching assigned proof requests
   • Downloading program and input artifacts
   • Generating zero-knowledge proofs
   • Submitting proofs to fulfill requests
   • Reporting failures when unable to fulfill

4. Monitor (NodeMonitor): Responsible for:

   • Collecting system metrics
   • Tracking node performance
   • Monitoring resource utilization

Request Lifecycle

The lifecycle of a proof request in the Succinct Prover Network follows these stages:

1. Request Creation: A client submits a proof request via RequestProof
2. Bidding Phase: Nodes bid on the request via BidRequest
3. Assignment: The network assigns the request to a winning bidder
4. Proof Generation: The assigned node generates the proof
5. Fulfillment: The node submits the proof via FulfillProof
6. Verification: The proof is verified via VerifyProof
7. Execution: The proof is executed via ExecuteProof
8. Completion: The request is marked as completed

Authentication and Security

Authentication implementation: crates/types/network/src/lib.rs

All authenticated requests to the Succinct Prover Network follow this pattern:

1. The client constructs a request body containing the required fields
2. The client signs the serialized request body using its private key
3. The client wraps the body and signature in a request object
4. The server verifies the signature against the sender's address
5. The server processes the request if authentication succeeds

Protocol Flow

Running a Prover Node

Implementation: crates/node/src/serial.rs

1. Node Initialization:

   • Initialize network client connection to the prover network
   • Set up a cryptographic signer with the node's private key
   • Configure bidding parameters (bid amount, throughput)
   • Configure proving parameters based on hardware capabilities
   • Initialize monitoring systems

2. Bidding Process:

   • Check for already assigned requests
   • If no assigned requests, search for unassigned requests
   • Filter requests based on version, deadline, and capabilities
   • Calculate if there's enough time to fulfill the request
   • Submit a bid with signature

3. Proving Process:

   • Monitor for assigned requests
   • Download program and stdin artifacts
   • Generate proof using appropriate proving mode
   • Track metrics (cycles, proving time)
   • Submit fulfilled proof to the network
   • Handle failures and report them properly

4. Monitoring:

   • Record node metrics (fulfillments, cycles, proving time)
   • Monitor system resources (CPU, RAM, disk)
   • Monitor GPU metrics if available

Artifact Management

Implementation: crates/artifacts/src/lib.rs

1. Creating Artifacts:

   • Request artifact creation via CreateArtifact
   • Receive a presigned URL for uploading
   • Upload the artifact data to the provided URL
   • Reference the artifact by its URI in proof requests

2. Downloading Artifacts:

   • Parse artifact ID from the provided URI
   • Download the artifact from the URI
   • Deserialize the artifact based on its type
   • Use the artifact for proving

Error Handling

Implementations: crates/utils/src/error.rs and crates/rpc/src/retry.rs

1. Failure Scenarios:

   • Proving failure: Report via FailFulfillment
   • Execution failure: Handled by execution oracle
   • Unreachable requests: Track unexecutable requests
   • System resource exhaustion: Monitor and report

2. Retry Mechanisms:

   • Network requests should use a retry mechanism with backoff
   • Proving operations should implement panic recovery
   • Implement monitoring for unexecutable requests

Key Data Structures

Implementation: crates/types/network/src/network.rs

Proof Modes

Value	Description
Core	Basic proof mode
Compressed	Compressed proof mode
Plonk	Plonk proof system
Groth16	Groth16 proof system

Fulfillment Status

Value	Description
Requested	Request has been created and auction has started, ready to be bid on
Assigned	Auction finished, assigned to the winning prover
Fulfilled	Proof has been successfully submitted and verified
Unfulfillable	Request cannot be fulfilled

Execution Status

Value	Description
Unexecuted	Waiting for execution
Executed	Successfully executed
Unexecutable	Cannot be executed

In addition to these statuses, each request also had a deadline. If this deadline has passed, it will be ignored by all agents in the network.

If the Fulfillment Status is not Fulfilled by the time the deadline has been reached, Requesters will not be charged and should retry the request, and provers will be slashed. :::

Visual Diagrams