risc0_zkvm/host/client/prove/

opts.rs

// Copyright 2025 RISC Zero, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Module containing the [ProverOpts] struct and related functionality.

#[cfg(feature = "prove")]
use anyhow::Result;
use risc0_circuit_recursion::control_id::ALLOWED_CONTROL_IDS;
use risc0_zkp::core::digest::Digest;
use serde::{Deserialize, Serialize};

use crate::receipt::DEFAULT_MAX_PO2;

/// Options to configure a [Prover][super::Prover].
#[derive(Clone, Debug, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ProverOpts {
    /// Identifier of the hash function to use for the STARK proving protocol.
    pub hashfn: String,

    /// When false, only prove execution sessions that end in a successful
    /// [crate::ExitCode] (i.e. `Halted(0)` or `Paused(0)`).
    /// When set to true, any completed execution session will be proven, including indicated
    /// errors (e.g. `Halted(1)`) and sessions ending in `Fault`.
    pub prove_guest_errors: bool,

    /// Kind of receipt to be generated by the prover.
    pub receipt_kind: ReceiptKind,

    /// List of control IDs to enable for recursion proving.
    ///
    /// This list is used to construct the control root, which commits to the set of recursion
    /// programs that are allowed to run and is a key field in the
    /// [SuccinctReceiptVerifierParameters][crate::SuccinctReceiptVerifierParameters].
    pub control_ids: Vec<Digest>,

    /// Maximum cycle count, as a power of two (po2) that these prover options support.
    pub(crate) max_segment_po2: usize,

    /// Whether or not dev-mode is enabled. If enabled, fake receipts may be generated, and fake
    /// receipts will verify successfully.
    pub(crate) dev_mode: bool,
}

/// An enumeration of receipt kinds that can be requested to be generated.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub enum ReceiptKind {
    /// Request that a [CompositeReceipt][crate::CompositeReceipt] be generated.
    ///
    /// Composite receipts are made up of a receipt for every segment in a zkVM execution, and
    /// every assumption. They are linear in size with respect to the execution length.
    Composite,

    /// Request that a [SuccinctReceipt][crate::SuccinctReceipt] be generated.
    ///
    /// Succinct receipts are constant in size, with respect to the execution length.
    ///
    Succinct,

    /// Request that a [Groth16Receipt][crate::Groth16Receipt] be generated.
    ///
    /// Groth16 receipts are proven using Groth16, are constant in size, and are the smallest
    /// available receipt format. A Groth16 receipt can be serialized to a few hundred bytes.
    Groth16,
}

impl Default for ProverOpts {
    /// Return [ProverOpts] that are intended to work for most applications.
    ///
    /// Proof generated with these options may be linear in size with the execution length, but
    /// can be compressed using the [Prover::compress][super::Prover::compress] methods.
    fn default() -> Self {
        Self {
            hashfn: "poseidon2".to_string(),
            prove_guest_errors: false,
            receipt_kind: ReceiptKind::Composite,
            control_ids: ALLOWED_CONTROL_IDS.to_vec(),
            max_segment_po2: DEFAULT_MAX_PO2,
            dev_mode: crate::is_dev_mode_enabled_via_environment(),
        }
    }
}

impl ProverOpts {
    /// Construct a [ProverOpts] ready to prove segments with up to the given max cycle count as a
    /// power of two (po2). All fields are equal to the default expect where they need to be
    /// adjusted to support a larger po2.
    ///
    /// NOTE: If the po2 used to prove is greater than the targeted verifier supports,
    /// [DEFAULT_MAX_PO2] by default, receipts will be rejected by the verifier.
    #[stability::unstable]
    pub fn from_max_po2(po2_max: usize) -> Self {
        Self {
            hashfn: "poseidon2".to_string(),
            prove_guest_errors: false,
            receipt_kind: ReceiptKind::Composite,
            control_ids: crate::receipt::succinct::allowed_control_ids("poseidon2", po2_max)
                .unwrap()
                .collect(),
            max_segment_po2: po2_max,
            dev_mode: crate::is_dev_mode_enabled_via_environment(),
        }
    }

    /// Construct a verifier context that will accept receipts with control any of the default
    /// control ID associated with cycle counts of all supported powers of two (po2).
    #[stability::unstable]
    pub fn all_po2s() -> Self {
        Self::from_max_po2(risc0_zkp::MAX_CYCLES_PO2)
    }

    /// Choose the fastest prover options. Receipt will be linear in length of the execution,
    ///
    /// This is an alias for [ProverOpts::composite].
    pub fn fast() -> Self {
        Self::composite()
    }

    /// Choose the prover that generates composite receipts, linear in the length of the execution,
    /// and supports compression via recursion.
    pub fn composite() -> Self {
        Self {
            hashfn: "poseidon2".to_string(),
            prove_guest_errors: false,
            receipt_kind: ReceiptKind::Composite,
            control_ids: ALLOWED_CONTROL_IDS.to_vec(),
            max_segment_po2: DEFAULT_MAX_PO2,
            dev_mode: crate::is_dev_mode_enabled_via_environment(),
        }
    }

    /// Choose the prover that generates succinct receipts, which are constant size in the length
    /// of execution.
    pub fn succinct() -> Self {
        Self {
            hashfn: "poseidon2".to_string(),
            prove_guest_errors: false,
            receipt_kind: ReceiptKind::Succinct,
            control_ids: ALLOWED_CONTROL_IDS.to_vec(),
            max_segment_po2: DEFAULT_MAX_PO2,
            dev_mode: crate::is_dev_mode_enabled_via_environment(),
        }
    }

    /// Choose the prover that generates Groth16 receipts which are constant size in the length of
    /// the execution and small enough to verify on blockchains, like Ethereum.
    ///
    /// Only supported with Docker installed.
    pub fn groth16() -> Self {
        Self {
            hashfn: "poseidon2".to_string(),
            prove_guest_errors: false,
            receipt_kind: ReceiptKind::Groth16,
            control_ids: ALLOWED_CONTROL_IDS.to_vec(),
            max_segment_po2: DEFAULT_MAX_PO2,
            dev_mode: crate::is_dev_mode_enabled_via_environment(),
        }
    }

    /// Return [ProverOpts] with the hashfn set to the given value.
    pub fn with_hashfn(self, hashfn: String) -> Self {
        Self {
            hashfn: hashfn.to_owned(),
            ..self
        }
    }

    /// Return [ProverOpts] with prove_guest_errors set to the given value.
    pub fn with_prove_guest_errors(self, prove_guest_errors: bool) -> Self {
        Self {
            prove_guest_errors,
            ..self
        }
    }

    /// Return [ProverOpts] with the receipt_kind set to the given value.
    pub fn with_receipt_kind(self, receipt_kind: ReceiptKind) -> Self {
        Self {
            receipt_kind,
            ..self
        }
    }

    /// Return [ProverOpts] with the control_ids set to the given value.
    pub fn with_control_ids(self, control_ids: Vec<Digest>) -> Self {
        Self {
            control_ids,
            ..self
        }
    }

    /// Return [ProverOpts] with the max_segment_po2 set to the given value.
    #[stability::unstable]
    pub fn with_segment_po2_max(self, max_segment_po2: usize) -> Self {
        Self {
            max_segment_po2,
            ..self
        }
    }

    /// Return [ProverOpts] with dev_mode enabled or disabled.
    pub fn with_dev_mode(self, dev_mode: bool) -> Self {
        if cfg!(feature = "disable-dev-mode") && dev_mode {
            panic!("zkVM: Inconsistent settings -- please resolve. \
                The RISC0_DEV_MODE environment variable is set but dev mode has been disabled by feature flag.");
        }
        Self { dev_mode, ..self }
    }

    /// Returns `true` if dev-mode is enabled.
    pub fn dev_mode(&self) -> bool {
        self.dev_mode
    }

    #[cfg(feature = "prove")]
    pub(crate) fn hash_suite(
        &self,
    ) -> Result<risc0_zkp::core::hash::HashSuite<risc0_zkp::field::baby_bear::BabyBear>> {
        risc0_zkp::core::hash::hash_suite_from_name(&self.hashfn)
            .ok_or_else(|| anyhow::anyhow!("unsupported hash suite: {}", self.hashfn))
    }
}