sp1-sdk 6.4.0

//! # Network Client
//!
//! This module provides a client for directly interacting with the network prover service.

use std::{
    result::Result::Ok as StdOk,
    str::FromStr,
    sync::Arc,
    time::{Duration, SystemTime, UNIX_EPOCH},
};

use alloy_primitives::{Address, B256, U256};
use anyhow::{Context, Ok, Result};
use async_trait::async_trait;
use reqwest_middleware::ClientWithMiddleware as HttpClientWithMiddleware;
use serde::{de::DeserializeOwned, Serialize};
use sp1_core_machine::io::SP1Stdin;
use sp1_prover::{HashableKey, SP1VerifyingKey};
use tokio::sync::OnceCell;
use tonic::{transport::Channel, Code};

use super::{
    grpc,
    retry::{self, RetryableRpc, DEFAULT_RETRY_TIMEOUT},
    signer::NetworkSigner,
    utils::{sign_message, Signable},
    NetworkMode, MAINNET_EXPLORER_URL, RESERVED_EXPLORER_URL,
};
use crate::network::proto::{
    artifact::{artifact_store_client::ArtifactStoreClient, ArtifactType, CreateArtifactRequest},
    // Import the clients for both auction and base.
    auction_network::prover_network_client::ProverNetworkClient as AuctionProverNetworkClient,
    // Import auction and base specific types for requests.
    auction_types::{
        CancelRequestRequest as AuctionCancelRequestRequest,
        CancelRequestRequestBody as AuctionCancelRequestRequestBody,
        GetBalanceRequest as AuctionGetBalanceRequest,
        GetFilteredProofRequestsRequest as AuctionGetFilteredProofRequestsRequest,
        GetMarketPricePerPguRequest as AuctionGetMarketPricePerPguRequest,
        GetNonceRequest as AuctionGetNonceRequest, GetProgramRequest as AuctionGetProgramRequest,
        GetProofRequestParamsRequest as AuctionGetProofRequestParamsRequest,
        GetProofRequestStatusRequest as AuctionGetProofRequestStatusRequest,
        GetProversByUptimeRequest as AuctionGetProversByUptimeRequest,
        MessageFormat as AuctionMessageFormat, RequestProofRequest as AuctionRequestProofRequest,
        RequestProofRequestBody as AuctionRequestProofRequestBody,
        TransactionVariant as AuctionTransactionVariant,
    },
    base_network::prover_network_client::ProverNetworkClient as BaseProverNetworkClient,
    base_types::{
        GetBalanceRequest as BaseGetBalanceRequest,
        GetFilteredProofRequestsRequest as BaseGetFilteredProofRequestsRequest,
        GetNonceRequest as BaseGetNonceRequest, GetProgramRequest as BaseGetProgramRequest,
        GetProofRequestDetailsRequest as BaseGetProofRequestDetailsRequest,
        GetProofRequestDetailsResponse as BaseGetProofRequestDetailsResponse,
        GetProofRequestStatusRequest as BaseGetProofRequestStatusRequest,
        MessageFormat as BaseMessageFormat, ProofRequest as BaseProofRequest,
        RequestProofRequest as BaseRequestProofRequest,
        RequestProofRequestBody as BaseRequestProofRequestBody,
    },
    // Import standard types (auction by default for backwards compatibility).
    types::{
        CreateProgramRequest, CreateProgramRequestBody, CreateProgramResponse, FulfillmentStatus,
        FulfillmentStrategy, GetProofRequestDetailsRequest, GetProofRequestDetailsResponse,
        MessageFormat, ProofMode,
    },
    CancelRequestResponse,
    GetBalanceResponse,
    GetFilteredProofRequestsResponse,
    // Import unified switchable response types.
    GetNonceResponse,
    GetProgramResponse,
    GetProofRequestParamsResponse,
    GetProofRequestStatusResponse,
    RequestProofResponse,
};

/// Current market `max_price_per_pgu` returned by [`NetworkClient::get_market_price_per_pgu`].
/// Returned to callers who want the raw market signal; the SDK's own auto-default path
/// uses `GetProofRequestParams.max_price_per_pgu` instead and does not consume this type.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MarketPrice {
    /// Current market price in PROVE wei per PGU.
    pub wei: u128,
    /// Unix timestamp (seconds) the `wei` value applies to. Advances whenever any input
    /// that feeds it moves. Callers do their own staleness check; the SDK does not.
    pub as_of: u64,
}

pub(super) fn parse_fulfillment_status(
    raw_status: i32,
    request_id: B256,
) -> Result<FulfillmentStatus> {
    FulfillmentStatus::try_from(raw_status).with_context(|| {
        format!(
            "unsupported fulfillment status {raw_status} while getting proof request status for request 0x{}",
            hex::encode(request_id)
        )
    })
}

/// A client for interacting with the network.
#[derive(Clone)]
pub struct NetworkClient {
    pub(crate) signer: NetworkSigner,
    pub(crate) http: HttpClientWithMiddleware,
    pub(crate) rpc_url: String,
    pub(crate) network_mode: NetworkMode,
    /// Lazily-established gRPC channel, shared across clones and reused across calls.
    pub(crate) channel: Arc<OnceCell<Channel>>,
}

#[async_trait]
impl RetryableRpc for NetworkClient {
    /// Execute an operation with retries using default timeout.
    async fn with_retry<'a, T, F, Fut>(&'a self, operation: F, operation_name: &str) -> Result<T>
    where
        F: Fn() -> Fut + Send + Sync + 'a,
        Fut: std::future::Future<Output = Result<T>> + Send,
        T: Send,
    {
        self.with_retry_timeout(operation, DEFAULT_RETRY_TIMEOUT, operation_name).await
    }

    /// Execute an operation with retries using the specified timeout.
    async fn with_retry_timeout<'a, T, F, Fut>(
        &'a self,
        operation: F,
        timeout: Duration,
        operation_name: &str,
    ) -> Result<T>
    where
        F: Fn() -> Fut + Send + Sync + 'a,
        Fut: std::future::Future<Output = Result<T>> + Send,
        T: Send,
    {
        retry::retry_operation(operation, Some(timeout), operation_name).await
    }
}

impl NetworkClient {
    /// Creates a new [`NetworkClient`] with the given signer, rpc url, and network mode.
    pub fn new(
        signer: NetworkSigner,
        rpc_url: impl Into<String>,
        network_mode: NetworkMode,
    ) -> Self {
        let client = reqwest::Client::builder()
            .pool_max_idle_per_host(0)
            .pool_idle_timeout(Duration::from_secs(240))
            .build()
            .unwrap();
        Self {
            signer,
            http: client.into(),
            rpc_url: rpc_url.into(),
            network_mode,
            channel: Arc::new(OnceCell::new()),
        }
    }

    /// Get the explorer URL for the current network mode.
    #[must_use]
    pub fn get_explorer_url(&self) -> &'static str {
        match self.network_mode {
            NetworkMode::Mainnet => MAINNET_EXPLORER_URL,
            NetworkMode::Reserved => RESERVED_EXPLORER_URL,
        }
    }

    /// Get the latest nonce for this account's address.
    pub async fn get_nonce(&self) -> Result<u64> {
        let response = self.get_nonce_response().await?;
        Ok(response.nonce())
    }

    /// Get the full nonce response (internal helper).
    async fn get_nonce_response(&self) -> Result<GetNonceResponse> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let res = rpc
                            .get_nonce(AuctionGetNonceRequest {
                                address: self.signer.address().to_vec(),
                            })
                            .await?;
                        Ok(GetNonceResponse::from(res.into_inner()))
                    },
                    "getting nonce",
                )
                .await
            }
            NetworkMode::Reserved => {
                self.with_retry(
                    || async {
                        let mut rpc = self.base_prover_network_client().await?;
                        let res = rpc
                            .get_nonce(BaseGetNonceRequest {
                                address: self.signer.address().to_vec(),
                            })
                            .await?;
                        Ok(GetNonceResponse::from(res.into_inner()))
                    },
                    "getting nonce",
                )
                .await
            }
        }
    }

    /// Get the credit balance of your account.
    ///
    /// # Details
    /// Uses the key that the client was initialized with.
    pub async fn get_balance(&self) -> Result<U256> {
        let response = self.get_balance_response().await?;
        Ok(U256::from_str(response.balance()).unwrap())
    }

    /// Get the full balance response (internal helper).
    async fn get_balance_response(&self) -> Result<GetBalanceResponse> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let res = rpc
                            .get_balance(AuctionGetBalanceRequest {
                                address: self.signer.address().to_vec(),
                            })
                            .await?;
                        Ok(GetBalanceResponse::from(res.into_inner()))
                    },
                    "getting balance",
                )
                .await
            }
            NetworkMode::Reserved => {
                self.with_retry(
                    || async {
                        let mut rpc = self.base_prover_network_client().await?;
                        let res = rpc
                            .get_balance(BaseGetBalanceRequest {
                                address: self.signer.address().to_vec(),
                            })
                            .await?;
                        Ok(GetBalanceResponse::from(res.into_inner()))
                    },
                    "getting balance",
                )
                .await
            }
        }
    }

    /// Get the verifying key hash from a verifying key.
    ///
    /// # Details
    /// The verifying key hash is used to identify a program.
    pub fn get_vk_hash(vk: &SP1VerifyingKey) -> Result<B256> {
        let vk_hash = vk.hash_bytes();
        Ok(B256::from_slice(&vk_hash))
    }

    /// Registers a program with the network if it is not already registered.
    pub async fn register_program(&self, vk: &SP1VerifyingKey, elf: &[u8]) -> Result<B256> {
        let vk_hash = Self::get_vk_hash(vk)?;

        // Try to get the existing program.
        if (self.get_program(vk_hash).await?).is_some() {
            // The program already exists.
            Ok(vk_hash)
        } else {
            // The program doesn't exist, create it.
            self.create_program(vk_hash, vk, elf).await?;
            tracing::info!("Registered program {:?}", vk_hash);
            Ok(vk_hash)
        }
    }

    /// Attempts to get the program on the network.
    ///
    /// # Details
    /// Returns `None` if the program does not exist.
    pub async fn get_program(&self, vk_hash: B256) -> Result<Option<GetProgramResponse>> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        match rpc
                            .get_program(AuctionGetProgramRequest { vk_hash: vk_hash.to_vec() })
                            .await
                        {
                            StdOk(response) => {
                                Ok(Some(GetProgramResponse::from(response.into_inner())))
                            }
                            Err(status) if status.code() == Code::NotFound => Ok(None),
                            Err(e) => Err(e.into()),
                        }
                    },
                    "getting program",
                )
                .await
            }
            NetworkMode::Reserved => {
                self.with_retry(
                    || async {
                        let mut rpc = self.base_prover_network_client().await?;
                        match rpc
                            .get_program(BaseGetProgramRequest { vk_hash: vk_hash.to_vec() })
                            .await
                        {
                            StdOk(response) => {
                                Ok(Some(GetProgramResponse::from(response.into_inner())))
                            }
                            Err(status) if status.code() == Code::NotFound => Ok(None),
                            Err(e) => Err(e.into()),
                        }
                    },
                    "getting program",
                )
                .await
            }
        }
    }

    /// Creates a new program on the network.
    pub async fn create_program(
        &self,
        vk_hash: B256,
        vk: &SP1VerifyingKey,
        elf: &[u8],
    ) -> Result<CreateProgramResponse> {
        // Create the program artifact.
        let program_uri = self.create_artifact_with_content(ArtifactType::Program, &elf).await?;

        // Serialize the verifying key.
        let vk_encoded = bincode::serialize(&vk)?;

        // Send the request.
        self.with_retry(
            || async {
                let mut rpc = self.prover_network_client().await?;
                let nonce = self.get_nonce().await?;
                let request_body = CreateProgramRequestBody {
                    nonce,
                    vk_hash: vk_hash.to_vec(),
                    vk: vk_encoded.clone(),
                    program_uri: program_uri.clone(),
                };

                Ok(rpc
                    .create_program(CreateProgramRequest {
                        format: MessageFormat::Binary.into(),
                        signature: request_body.sign(&self.signer).await?,
                        body: Some(request_body),
                    })
                    .await?
                    .into_inner())
            },
            "creating program",
        )
        .await
    }

    /// Gets the proof request parameters from the network.
    /// This is only available in Mainnet (auction) mode.
    pub async fn get_proof_request_params(
        &self,
        mode: ProofMode,
    ) -> Result<GetProofRequestParamsResponse> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let response = rpc
                            .get_proof_request_params(AuctionGetProofRequestParamsRequest {
                                mode: mode.into(),
                            })
                            .await?
                            .into_inner();
                        Ok(GetProofRequestParamsResponse::from(response))
                    },
                    "getting proof request parameters",
                )
                .await
            }
            NetworkMode::Reserved => Ok(GetProofRequestParamsResponse::Unsupported),
        }
    }

    /// Returns the current market price per prover gas unit, in PROVE wei. Tracks the
    /// network's market signal; callers apply their own buffer before passing it as
    /// `max_price_per_pgu`. Mainnet (auction) mode only.
    pub async fn get_market_price_per_pgu(&self) -> Result<MarketPrice> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let response = rpc
                            .get_market_price_per_pgu(AuctionGetMarketPricePerPguRequest {})
                            .await?
                            .into_inner();
                        let wei = response.price.parse::<u128>().with_context(|| {
                            format!("invalid market_price_per_pgu wei: {:?}", response.price)
                        })?;
                        let as_of = u64::try_from(response.as_of).with_context(|| {
                            format!("invalid market_price as_of: {}", response.as_of)
                        })?;
                        Ok(MarketPrice { wei, as_of })
                    },
                    "getting market price per PGU",
                )
                .await
            }
            NetworkMode::Reserved => {
                Err(anyhow::anyhow!("get_market_price_per_pgu is not supported in Reserved mode"))
            }
        }
    }

    /// Get all the proof requests that meet the filter criteria.
    #[allow(clippy::too_many_arguments)]
    pub async fn get_filtered_proof_requests(
        &self,
        version: Option<String>,
        fulfillment_status: Option<i32>,
        execution_status: Option<i32>,
        minimum_deadline: Option<u64>,
        vk_hash: Option<Vec<u8>>,
        requester: Option<Vec<u8>>,
        fulfiller: Option<Vec<u8>>,
        from: Option<u64>,
        to: Option<u64>,
        limit: Option<u32>,
        page: Option<u32>,
        mode: Option<i32>,
        not_bid_by: Option<Vec<u8>>,
        execute_fail_cause: Option<i32>,
        settlement_status: Option<i32>,
        error: Option<i32>,
    ) -> Result<GetFilteredProofRequestsResponse> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || {
                        let version = version.clone();
                        let vk_hash = vk_hash.clone();
                        let requester = requester.clone();
                        let fulfiller = fulfiller.clone();
                        let not_bid_by = not_bid_by.clone();

                        async move {
                            let mut rpc = self.auction_prover_network_client().await?;
                            let response = rpc
                                .get_filtered_proof_requests(
                                    AuctionGetFilteredProofRequestsRequest {
                                        version,
                                        fulfillment_status,
                                        execution_status,
                                        minimum_deadline,
                                        vk_hash,
                                        requester,
                                        fulfiller,
                                        from,
                                        to,
                                        limit,
                                        page,
                                        mode,
                                        not_bid_by,
                                        execute_fail_cause,
                                        settlement_status,
                                        error,
                                        ..Default::default()
                                    },
                                )
                                .await?
                                .into_inner();
                            Ok(GetFilteredProofRequestsResponse::from(response))
                        }
                    },
                    "getting filtered proof requests",
                )
                .await
            }
            NetworkMode::Reserved => {
                self.with_retry(
                    || {
                        let version = version.clone();
                        let vk_hash = vk_hash.clone();
                        let requester = requester.clone();
                        let fulfiller = fulfiller.clone();
                        let not_bid_by = not_bid_by.clone();

                        async move {
                            let mut rpc = self.base_prover_network_client().await?;
                            let response = rpc
                                .get_filtered_proof_requests(BaseGetFilteredProofRequestsRequest {
                                    version,
                                    fulfillment_status,
                                    execution_status,
                                    minimum_deadline,
                                    vk_hash,
                                    requester,
                                    fulfiller,
                                    from,
                                    to,
                                    limit,
                                    page,
                                    mode,
                                    not_bid_by,
                                    execute_fail_cause,
                                    settlement_status,
                                    error,
                                    ..Default::default()
                                })
                                .await?
                                .into_inner();
                            Ok(GetFilteredProofRequestsResponse::from(response))
                        }
                    },
                    "getting filtered proof requests",
                )
                .await
            }
        }
    }

    /// Get the status of a given proof.
    ///
    /// # Details
    /// If the status is Fulfilled, the proof is also returned.
    pub async fn get_proof_request_status<P: DeserializeOwned>(
        &self,
        request_id: B256,
        timeout: Option<Duration>,
    ) -> Result<(GetProofRequestStatusResponse, Option<P>)> {
        // Get the status.
        let res = match self.network_mode {
            NetworkMode::Mainnet => {
                let auction_response = self
                    .with_retry_timeout(
                        || async {
                            let mut rpc = self.auction_prover_network_client().await?;
                            Ok(rpc
                                .get_proof_request_status(AuctionGetProofRequestStatusRequest {
                                    request_id: request_id.to_vec(),
                                })
                                .await?
                                .into_inner())
                        },
                        timeout.unwrap_or(DEFAULT_RETRY_TIMEOUT),
                        "getting proof request status",
                    )
                    .await?;
                GetProofRequestStatusResponse::from(auction_response)
            }
            NetworkMode::Reserved => {
                let base_response = self
                    .with_retry_timeout(
                        || async {
                            let mut rpc = self.base_prover_network_client().await?;
                            Ok(rpc
                                .get_proof_request_status(BaseGetProofRequestStatusRequest {
                                    request_id: request_id.to_vec(),
                                })
                                .await?
                                .into_inner())
                        },
                        timeout.unwrap_or(DEFAULT_RETRY_TIMEOUT),
                        "getting proof request status",
                    )
                    .await?;
                GetProofRequestStatusResponse::from(base_response)
            }
        };

        let status = parse_fulfillment_status(res.fulfillment_status(), request_id)?;
        let proof = match status {
            FulfillmentStatus::Fulfilled => {
                let proof_uri =
                    res.proof_uri().ok_or_else(|| anyhow::anyhow!("No proof URI provided"))?;
                let proof_bytes = self.download_artifact(proof_uri).await?;
                Some(bincode::deserialize(&proof_bytes).context("Failed to deserialize proof")?)
            }
            _ => None,
        };

        Ok((res, proof))
    }

    /// Get the details of a given proof request.
    pub async fn get_proof_request_details(
        &self,
        request_id: B256,
        timeout: Option<Duration>,
    ) -> Result<GetProofRequestDetailsResponse> {
        let res = match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry_timeout(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        Ok(rpc
                            .get_proof_request_details(GetProofRequestDetailsRequest {
                                request_id: request_id.to_vec(),
                            })
                            .await?
                            .into_inner())
                    },
                    timeout.unwrap_or(DEFAULT_RETRY_TIMEOUT),
                    "getting proof request details",
                )
                .await?
            }
            NetworkMode::Reserved => {
                let response = self
                    .with_retry_timeout(
                        || async {
                            let mut rpc = self.base_prover_network_client().await?;
                            Ok(rpc
                                .get_proof_request_details(BaseGetProofRequestDetailsRequest {
                                    request_id: request_id.to_vec(),
                                })
                                .await?
                                .into_inner())
                        },
                        timeout.unwrap_or(DEFAULT_RETRY_TIMEOUT),
                        "getting proof request details",
                    )
                    .await?;
                Self::convert_base_proof_request_details(response)
            }
        };

        Ok(res)
    }

    fn convert_base_proof_request_details(
        response: BaseGetProofRequestDetailsResponse,
    ) -> GetProofRequestDetailsResponse {
        GetProofRequestDetailsResponse {
            request: response.request.map(|request| {
                let BaseProofRequest {
                    request_id,
                    vk_hash,
                    version,
                    mode,
                    strategy,
                    program_uri,
                    stdin_uri,
                    deadline,
                    cycle_limit,
                    gas_price,
                    fulfillment_status,
                    execution_status,
                    requester,
                    fulfiller,
                    program_name,
                    requester_name,
                    fulfiller_name,
                    created_at,
                    updated_at,
                    fulfilled_at,
                    tx_hash,
                    cycles,
                    public_values_hash,
                    deduction_amount,
                    refund_amount,
                    gas_limit,
                    gas_used,
                    execute_fail_cause,
                    settlement_status,
                    program_public_uri,
                    stdin_public_uri,
                    min_auction_period,
                    whitelist,
                    error,
                    stdin_private,
                } = request;

                crate::network::proto::auction_types::ProofRequest {
                    request_id,
                    vk_hash,
                    version,
                    mode,
                    strategy,
                    program_uri,
                    stdin_uri,
                    deadline,
                    cycle_limit,
                    gas_price,
                    fulfillment_status,
                    execution_status,
                    requester,
                    fulfiller,
                    program_name,
                    requester_name,
                    fulfiller_name,
                    created_at,
                    updated_at,
                    fulfilled_at,
                    tx_hash,
                    cycles,
                    public_values_hash,
                    deduction_amount,
                    refund_amount,
                    gas_limit,
                    gas_used,
                    execute_fail_cause,
                    settlement_status,
                    program_public_uri,
                    stdin_public_uri,
                    min_auction_period,
                    whitelist,
                    base_fee: None,
                    max_price_per_pgu: None,
                    error,
                    is_canceled: false,
                    stdin_private,
                }
            }),
        }
    }

    /// Creates a proof request with the given verifying key hash and stdin.
    ///
    /// # Details
    /// * `vk_hash`: The verifying key hash of the program to prove. Used to identify the program.
    /// * `stdin`: The standard input to provide to the program.
    /// * `mode`: The [`ProofMode`] to use.
    /// * `version`: The version of the SP1 circuits to use.
    /// * `strategy`: The [`FulfillmentStrategy`] to use.
    /// * `timeout_secs`: The timeout for the proof request in seconds.
    /// * `cycle_limit`: The cycle limit for the proof request.
    /// * `gas_limit`: The gas limit for the proof request.
    /// * `min_auction_period`: The minimum auction period for the proof request in seconds.
    /// * `whitelist`: The auction whitelist for the proof request.
    /// * `auctioneer`: The auctioneer for the proof request.
    /// * `executor`: The executor for the proof request.
    /// * `verifier`: The verifier for the proof request.
    /// * `treasury`: The treasury for the proof request.
    /// * `public_values_hash`: The hash of the public values to use for the proof.
    /// * `base_fee`: The base fee to use for the proof request.
    /// * `max_price_per_pgu`: The maximum price per PGU to use for the proof request.
    /// * `domain`: The domain bytes to use for the proof request.
    #[allow(clippy::too_many_arguments)]
    #[allow(unused_variables)]
    pub async fn request_proof(
        &self,
        vk_hash: B256,
        stdin: &SP1Stdin,
        mode: ProofMode,
        version: &str,
        strategy: FulfillmentStrategy,
        timeout_secs: u64,
        cycle_limit: u64,
        gas_limit: u64,
        min_auction_period: u64,
        whitelist: Option<Vec<Address>>,
        auctioneer: Address,
        executor: Address,
        verifier: Address,
        treasury: Address,
        public_values_hash: Option<Vec<u8>>,
        base_fee: u64,
        max_price_per_pgu: u64,
        domain: Vec<u8>,
        private_stdin: bool,
    ) -> Result<RequestProofResponse> {
        // Calculate the deadline.
        let start = SystemTime::now();
        let since_the_epoch = start.duration_since(UNIX_EPOCH).expect("Invalid start time");
        let deadline = since_the_epoch.as_secs() + timeout_secs;

        let stdin_uri = self
            .create_artifact_with_content(
                if private_stdin { ArtifactType::PrivateStdin } else { ArtifactType::Stdin },
                &stdin,
            )
            .await?;

        // Send the request.
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let nonce = self.get_nonce().await?;

                        let whitelist = if let Some(whitelist) = &whitelist {
                            whitelist.iter().map(|addr| addr.to_vec()).collect()
                        } else {
                            let result = rpc
                                .get_provers_by_uptime(AuctionGetProversByUptimeRequest {
                                    high_availability_only: false,
                                })
                                .await?;
                            result.into_inner().provers
                        };

                        let request_body = AuctionRequestProofRequestBody {
                            nonce,
                            version: format!("sp1-{version}"),
                            vk_hash: vk_hash.to_vec(),
                            mode: mode.into(),
                            strategy: strategy.into(),
                            stdin_uri: stdin_uri.clone(),
                            deadline,
                            cycle_limit,
                            gas_limit,
                            min_auction_period,
                            whitelist,
                            domain: domain.clone(),
                            auctioneer: auctioneer.to_vec(),
                            executor: executor.to_vec(),
                            verifier: verifier.to_vec(),
                            treasury: treasury.to_vec(),
                            public_values_hash: public_values_hash.clone(),
                            base_fee: base_fee.to_string(),
                            max_price_per_pgu: max_price_per_pgu.to_string(),
                            variant: AuctionTransactionVariant::RequestVariant.into(),
                            stdin_private: private_stdin,
                        };

                        let request_response = rpc
                            .request_proof(AuctionRequestProofRequest {
                                format: AuctionMessageFormat::Binary.into(),
                                signature: request_body.sign(&self.signer).await?,
                                body: Some(request_body),
                            })
                            .await?
                            .into_inner();

                        Ok(RequestProofResponse::from(request_response))
                    },
                    "requesting proof",
                )
                .await
            }
            NetworkMode::Reserved => {
                self.with_retry(
                    || async {
                        let mut rpc = self.base_prover_network_client().await?;
                        let nonce = self.get_nonce().await?;

                        let request_body = BaseRequestProofRequestBody {
                            nonce,
                            version: format!("sp1-{version}"),
                            vk_hash: vk_hash.to_vec(),
                            mode: mode.into(),
                            strategy: strategy.into(),
                            stdin_uri: stdin_uri.clone(),
                            deadline,
                            cycle_limit,
                            gas_limit,
                            min_auction_period,
                            whitelist: whitelist
                                .clone()
                                .map(|list| list.into_iter().map(|addr| addr.to_vec()).collect())
                                .unwrap_or_default(),
                            stdin_private: private_stdin,
                        };

                        let request_response = rpc
                            .request_proof(BaseRequestProofRequest {
                                format: BaseMessageFormat::Binary.into(),
                                signature: request_body.sign(&self.signer).await?,
                                body: Some(request_body),
                            })
                            .await?
                            .into_inner();

                        Ok(RequestProofResponse::from(request_response))
                    },
                    "requesting proof",
                )
                .await
            }
        }
    }

    // Auction client for operations whose schemas are wire-compatible across network modes.
    pub(crate) async fn prover_network_client(
        &self,
    ) -> Result<AuctionProverNetworkClient<Channel>> {
        // For shared operations, we use the auction client type as it provides the default types.
        // The actual network routing is handled by the RPC URL which is correctly set based on
        // network_mode.
        self.auction_prover_network_client().await
    }

    /// Returns the shared gRPC channel, built at most once.
    ///
    /// `OnceCell` rather than `new()` since `new()` is infallible but `configure_endpoint` isn't.
    /// `connect_lazy` reconnects transparently, so the connection is reused across polls and a
    /// dropped one self-heals on next use.
    async fn channel(&self) -> Result<Channel> {
        self.channel
            .get_or_try_init(|| async {
                tracing::debug!(rpc_url = %self.rpc_url, "establishing gRPC channel");
                Ok(grpc::configure_endpoint(&self.rpc_url)?.connect_lazy())
            })
            .await
            .cloned()
    }

    // Helper methods for runtime proto type selection.
    pub(crate) async fn auction_prover_network_client(
        &self,
    ) -> Result<AuctionProverNetworkClient<Channel>> {
        Ok(AuctionProverNetworkClient::new(self.channel().await?))
    }

    pub(crate) async fn base_prover_network_client(
        &self,
    ) -> Result<BaseProverNetworkClient<Channel>> {
        Ok(BaseProverNetworkClient::new(self.channel().await?))
    }

    pub(crate) async fn artifact_store_client(&self) -> Result<ArtifactStoreClient<Channel>> {
        Ok(ArtifactStoreClient::new(self.channel().await?))
    }

    pub(crate) async fn create_artifact_with_content<T: Serialize + Send + Sync>(
        &self,
        artifact_type: ArtifactType,
        item: &T,
    ) -> Result<String> {
        // Acquire the store inside the retry so a transient channel-connect failure is retried.
        let response = self
            .with_retry(
                || async {
                    let mut store = self.artifact_store_client().await?;
                    let signature =
                        sign_message("create_artifact".as_bytes(), &self.signer).await?;
                    let request =
                        CreateArtifactRequest { artifact_type: artifact_type.into(), signature };
                    Ok(store.create_artifact(request).await?.into_inner())
                },
                "creating artifact",
            )
            .await?;

        let presigned_url = response.artifact_presigned_url;
        let uri = response.artifact_uri;

        // Serialize and compress the content once before retrying uploads.
        // Using compression level 3 for a good balance of speed and compression ratio.
        let serialized = bincode::serialize::<T>(item)?;
        let compressed = zstd::encode_all(&serialized[..], 3)
            .map_err(|e| anyhow::anyhow!("Failed to compress artifact: {e}"))?;

        // Upload the compressed content.
        self.with_retry(
            || async {
                let response =
                    self.http.put(&presigned_url).body(compressed.clone()).send().await?;

                if !response.status().is_success() {
                    return Err(anyhow::anyhow!(
                        "Failed to upload artifact: HTTP {}",
                        response.status()
                    ));
                }
                Ok(())
            },
            "uploading artifact content",
        )
        .await?;

        Ok(uri)
    }

    pub(crate) async fn download_artifact(&self, uri: &str) -> Result<Vec<u8>> {
        self.with_retry(
            || async {
                let response =
                    self.http.get(uri).send().await.context("Failed to download from URI")?;

                if !response.status().is_success() {
                    return Err(anyhow::anyhow!(
                        "Failed to download artifact: HTTP {}",
                        response.status()
                    ));
                }

                Ok(response.bytes().await.context("Failed to read response body")?.to_vec())
            },
            "downloading artifact",
        )
        .await
    }

    /// Cancel a proof request. This is only available in Mainnet (auction) mode.
    pub async fn cancel_request(&self, request_id: B256) -> Result<CancelRequestResponse> {
        match self.network_mode {
            NetworkMode::Mainnet => {
                self.with_retry(
                    || async {
                        let mut rpc = self.auction_prover_network_client().await?;
                        let nonce = self.get_nonce().await?;

                        let request_body = AuctionCancelRequestRequestBody {
                            nonce,
                            request_id: request_id.to_vec(),
                        };

                        let response = rpc
                            .cancel_request(AuctionCancelRequestRequest {
                                format: AuctionMessageFormat::Binary.into(),
                                signature: request_body.sign(&self.signer).await?,
                                body: Some(request_body),
                            })
                            .await?
                            .into_inner();

                        Ok(CancelRequestResponse::from(response))
                    },
                    "cancelling request",
                )
                .await
            }
            NetworkMode::Reserved => Ok(CancelRequestResponse::Unsupported),
        }
    }
}

#[cfg(test)]
mod test {
    use std::{
        convert::Infallible,
        task::{Context, Poll},
        time::Duration,
    };

    use alloy_primitives::B256;
    use tonic::{
        codegen::{http, Body, BoxFuture, Service, StdError},
        server::{Grpc, NamedService, UnaryService},
        transport::Server,
        Request, Response, Status,
    };

    use crate::network::{proto::base_types, signer::NetworkSigner, NetworkMode, RESERVED_RPC_URL};

    use super::parse_fulfillment_status;

    #[derive(Clone)]
    struct ReservedProofDetailsFixture(base_types::GetProofRequestDetailsResponse);

    impl NamedService for ReservedProofDetailsFixture {
        const NAME: &'static str = "network.ProverNetwork";
    }

    impl UnaryService<base_types::GetProofRequestDetailsRequest> for ReservedProofDetailsFixture {
        type Response = base_types::GetProofRequestDetailsResponse;
        type Future = BoxFuture<Response<Self::Response>, Status>;

        fn call(
            &mut self,
            request: Request<base_types::GetProofRequestDetailsRequest>,
        ) -> Self::Future {
            assert_eq!(
                request.into_inner().request_id,
                self.0.request.as_ref().unwrap().request_id
            );
            let response = self.0.clone();
            Box::pin(async move { Ok(Response::new(response)) })
        }
    }

    impl<B> Service<http::Request<B>> for ReservedProofDetailsFixture
    where
        B: Body + Send + 'static,
        B::Error: Into<StdError> + Send + 'static,
    {
        type Response = http::Response<tonic::body::BoxBody>;
        type Error = Infallible;
        type Future = BoxFuture<Self::Response, Self::Error>;

        fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
            Poll::Ready(Ok(()))
        }

        fn call(&mut self, request: http::Request<B>) -> Self::Future {
            assert_eq!(request.uri().path(), "/network.ProverNetwork/GetProofRequestDetails");

            let method = self.clone();
            Box::pin(async move {
                Ok(Grpc::new(tonic::codec::ProstCodec::default()).unary(method, request).await)
            })
        }
    }

    #[test]
    fn test_can_create_network_client_with_0x_bytes() {
        let private_key = hex::encode(alloy_signer_local::PrivateKeySigner::random().to_bytes());
        let signer = NetworkSigner::local(&private_key).unwrap();
        let _ = super::NetworkClient::new(signer, RESERVED_RPC_URL, NetworkMode::Reserved);
    }

    #[test]
    fn fulfillment_status_parser_handles_known_and_unknown_values() {
        let request_id = B256::from([0xab; 32]);

        for raw_status in 0..=6 {
            let status = parse_fulfillment_status(raw_status, request_id).unwrap();
            assert_eq!(status as i32, raw_status);
        }

        let error = parse_fulfillment_status(7, request_id).unwrap_err().to_string();
        assert!(error.contains("unsupported fulfillment status 7"));
        assert!(error.contains(&format!("0x{}", hex::encode(request_id))));
    }

    #[tokio::test]
    async fn reserved_proof_request_details_uses_reserved_schema() {
        let request_id = B256::repeat_byte(0x11);
        let request = base_types::ProofRequest {
            request_id: request_id.to_vec(),
            vk_hash: vec![0x22; 32],
            version: "sp1-v6.3.1".to_string(),
            mode: base_types::ProofMode::Plonk.into(),
            strategy: base_types::FulfillmentStrategy::Reserved.into(),
            program_uri: "programs/test".to_string(),
            stdin_uri: "stdins/test".to_string(),
            deadline: 1_800_000_000,
            cycle_limit: 1_000_000,
            error: base_types::ProofRequestError::ExecutionFailure.into(),
            stdin_private: true,
            ..Default::default()
        };

        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let incoming = futures::stream::unfold(listener, |listener| async move {
            let connection = listener.accept().await.map(|(stream, _)| stream);
            Some((connection, listener))
        });
        let server = tokio::spawn(
            Server::builder()
                .add_service(ReservedProofDetailsFixture(
                    base_types::GetProofRequestDetailsResponse { request: Some(request) },
                ))
                .serve_with_incoming(incoming),
        );

        let private_key = hex::encode(alloy_signer_local::PrivateKeySigner::random().to_bytes());
        let signer = NetworkSigner::local(&private_key).unwrap();
        let client =
            super::NetworkClient::new(signer, format!("http://{address}"), NetworkMode::Reserved);

        let response = client
            .get_proof_request_details(request_id, Some(Duration::from_secs(1)))
            .await
            .unwrap();
        server.abort();

        let request = response.request.unwrap();
        assert_eq!(request.request_id, request_id.as_slice());
        assert_eq!(request.vk_hash, vec![0x22; 32]);
        assert_eq!(request.version, "sp1-v6.3.1");
        assert_eq!(request.mode, base_types::ProofMode::Plonk as i32);
        assert_eq!(request.strategy, base_types::FulfillmentStrategy::Reserved as i32);
        assert_eq!(request.program_uri, "programs/test");
        assert_eq!(request.stdin_uri, "stdins/test");
        assert_eq!(request.deadline, 1_800_000_000);
        assert_eq!(request.cycle_limit, 1_000_000);
        assert_eq!(request.error, base_types::ProofRequestError::ExecutionFailure as i32);
        assert!(request.stdin_private);
        assert_eq!(request.base_fee, None);
        assert_eq!(request.max_price_per_pgu, None);
        assert!(!request.is_canceled);
    }
}