qp_wormhole_verifier/

lib.rs

//! Verifier logic for the Wormhole circuit.
//!
//! This module provides the [`WormholeVerifier`] type, which allows for the verification of
//! zero-knowledge proofs generated by the Wormhole circuit.
//!
//! The typical usage flow involves:
//! 1. Initializing the verifier from pre-built circuit data via [`WormholeVerifier::new_from_bytes()`].
//! 2. Deserializing a [`ProofWithPublicInputs`].
//! 3. Verifying the proof using [`WormholeVerifier::verify`].
//!
//! # Example
//!
//! ```ignore
//! use qp_wormhole_verifier::{WormholeVerifier, ProofWithPublicInputs, C, D, F};
//!
//! // Load verifier from pre-serialized bytes
//! let verifier = WormholeVerifier::new_from_bytes(verifier_bytes, common_bytes)?;
//!
//! // Deserialize the proof
//! let proof = ProofWithPublicInputs::<F, C, D>::from_bytes(proof_bytes, &verifier.circuit_data.common)?;
//!
//! // Verify
//! verifier.verify(proof)?;
//! ```
#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(not(feature = "std"))]
use alloc::vec::Vec;
#[cfg(feature = "std")]
use std::vec::Vec;

use anyhow::anyhow;
#[cfg(feature = "std")]
use std::path::Path;

// Re-export types from qp-plonky2-verifier
pub use qp_plonky2_verifier::{
    CircuitConfig, CommonCircuitData, ProofWithPublicInputs, VerifierCircuitData,
    VerifierOnlyCircuitData, C, D, F,
};

use qp_plonky2_verifier::field::types::PrimeField64;
use qp_plonky2_verifier::util::serialization::DefaultGateSerializer;
use tiny_keccak::{Hasher, Keccak};

// Re-export input types from qp-wormhole-inputs
pub use qp_wormhole_inputs::{
    BlockData, BytesDigest, PrivateBatchPublicInputs, PublicBatchPublicInputs, PublicCircuitInputs,
    PublicInputsByAccount, MIN_LEAF_SECURITY_BITS, PUBLIC_INPUTS_FELTS_LEN,
};

/// Parse public inputs from a proof.
pub fn parse_public_inputs(
    proof: &ProofWithPublicInputs<F, C, D>,
) -> anyhow::Result<PublicCircuitInputs> {
    let u64s: Vec<u64> = proof
        .public_inputs
        .iter()
        .map(|f| f.to_canonical_u64())
        .collect();
    PublicCircuitInputs::try_from_u64_slice(&u64s)
}

/// Parse aggregated public inputs from a proof.
pub fn parse_private_batch_public_inputs(
    proof: &ProofWithPublicInputs<F, C, D>,
) -> anyhow::Result<PrivateBatchPublicInputs> {
    let u64s: Vec<u64> = proof
        .public_inputs
        .iter()
        .map(|f| f.to_canonical_u64())
        .collect();
    PrivateBatchPublicInputs::try_from_u64_slice(&u64s)
}

/// Parse public-batch public inputs from a proof.
pub fn parse_public_batch_public_inputs(
    proof: &ProofWithPublicInputs<F, C, D>,
    num_private_batch_proofs: usize,
    num_leaf_proofs: usize,
) -> anyhow::Result<PublicBatchPublicInputs> {
    let u64s: Vec<u64> = proof
        .public_inputs
        .iter()
        .map(|f| f.to_canonical_u64())
        .collect();
    PublicBatchPublicInputs::try_from_u64_slice(&u64s, num_private_batch_proofs, num_leaf_proofs)
}

/// Verifier for Wormhole circuit proofs.
///
/// This struct wraps the circuit verification data and provides methods to verify proofs.
#[derive(Debug)]
pub struct WormholeVerifier {
    pub circuit_data: VerifierCircuitData<F, C, D>,
}

// Keccak-256 commitments to the byte-exact canonical leaf artifacts produced by
// `WormholeCircuit::new(CircuitConfig::standard_recursion_config())` with
// qp-plonky2 1.5.1. The integration tests rebuild the circuit and fail if a
// deliberate circuit change requires these commitments to be updated.
const CANONICAL_LEAF_VERIFIER_KECCAK256: [u8; 32] = [
    0x21, 0x86, 0xb2, 0x0f, 0x20, 0x02, 0x7d, 0xae, 0x1e, 0x16, 0x23, 0xa0, 0x26, 0xe9, 0x0f, 0xf5,
    0x50, 0x04, 0x2b, 0x33, 0x02, 0xfb, 0x1a, 0x01, 0x4e, 0x9a, 0xd5, 0x7b, 0x8a, 0x5b, 0x22, 0xb2,
];
const CANONICAL_LEAF_COMMON_KECCAK256: [u8; 32] = [
    0x84, 0x5d, 0x8f, 0xdf, 0x8f, 0xfe, 0x9f, 0xd5, 0xef, 0x3f, 0x8b, 0xe8, 0x74, 0x11, 0x4b, 0xf1,
    0x57, 0x5d, 0xcf, 0xe2, 0xb0, 0x1d, 0xb4, 0x46, 0x5f, 0x3d, 0x9a, 0x34, 0xf6, 0xb7, 0xb7, 0xe1,
];

/// Maximum size accepted for a serialized verifier artifact, whether loaded
/// from a file or passed as bytes.
///
/// The keccak256 canonicality pin already rejects everything but the
/// byte-exact canonical leaf artifacts, so this cap's only job is to bound
/// the work done BEFORE the pin can fire: the file read's allocation in
/// [`WormholeVerifier::new_from_files`] and the keccak pass over
/// caller-supplied slices in [`WormholeVerifier::new_from_bytes`]. That work
/// is proportional to the cap, so the cap must be tight for the "rejected in
/// O(1)" property to mean anything. The canonical artifacts are a few KB;
/// 1 MiB is ~2–3 orders of magnitude of headroom while keeping the worst
/// pre-pin allocation and hash trivially cheap. (The aggregator crate keeps
/// its own, larger bound for its much larger circuit artifacts.)
pub const MAX_VERIFIER_ARTIFACT_BYTES: u64 = 1024 * 1024;

fn keccak256(input: &[u8]) -> [u8; 32] {
    let mut output = [0u8; 32];
    let mut hasher = Keccak::v256();
    hasher.update(input);
    hasher.finalize(&mut output);
    output
}

/// Read a verifier-artifact file, refusing anything larger than
/// [`MAX_VERIFIER_ARTIFACT_BYTES`] before allocating for its contents.
///
/// Mirrors the aggregator's size-capped reader. Artifact paths are assumed
/// to come from attested CI builds (`wormhole/THREAT_MODEL.md`).
#[cfg(feature = "std")]
fn read_artifact_file(path: &Path) -> anyhow::Result<Vec<u8>> {
    use anyhow::Context as _;

    let metadata = std::fs::metadata(path)
        .with_context(|| format!("failed to stat artifact file {}", path.display()))?;
    let claimed_len = metadata.len();
    if claimed_len > MAX_VERIFIER_ARTIFACT_BYTES {
        return Err(anyhow!(
            "artifact file {} is {} bytes, which exceeds the {} byte limit for \
             verifier artifacts; refusing to load it",
            path.display(),
            claimed_len,
            MAX_VERIFIER_ARTIFACT_BYTES
        ));
    }
    std::fs::read(path).with_context(|| format!("failed to read artifact file {}", path.display()))
}

impl WormholeVerifier {
    /// Creates a new [`WormholeVerifier`] from verifier and common data bytes.
    ///
    /// Inputs larger than [`MAX_VERIFIER_ARTIFACT_BYTES`] are rejected before any
    /// hashing, so the size bound is a property of the loading contract
    /// itself, not just of the file-based wrapper. Within that bound, both
    /// serialized inputs must match the byte-exact canonical Wormhole leaf
    /// artifacts (keccak256 pin). The decoded config and public-input shape
    /// are checked again as defense in depth.
    pub fn new_from_bytes(verifier_bytes: &[u8], common_bytes: &[u8]) -> anyhow::Result<Self> {
        for (label, bytes) in [("verifier-only", verifier_bytes), ("common", common_bytes)] {
            if bytes.len() as u64 > MAX_VERIFIER_ARTIFACT_BYTES {
                return Err(anyhow!(
                    "{} artifact is {} bytes, which exceeds the {} byte limit for \
                     verifier artifacts; refusing to load it",
                    label,
                    bytes.len(),
                    MAX_VERIFIER_ARTIFACT_BYTES
                ));
            }
        }

        let verifier_hash = keccak256(verifier_bytes);
        if verifier_hash != CANONICAL_LEAF_VERIFIER_KECCAK256 {
            return Err(anyhow!(
                "loaded verifier-only artifact does not match the canonical Wormhole leaf circuit (keccak256={:02x?})",
                verifier_hash
            ));
        }

        let common_hash = keccak256(common_bytes);
        if common_hash != CANONICAL_LEAF_COMMON_KECCAK256 {
            return Err(anyhow!(
                "loaded common artifact does not match the canonical Wormhole leaf circuit (keccak256={:02x?})",
                common_hash
            ));
        }

        let verifier_only = VerifierOnlyCircuitData::from_bytes(verifier_bytes.to_vec())
            .map_err(|e| anyhow!("failed to deserialize verifier data: {}", e))?;

        let common = CommonCircuitData::from_bytes(common_bytes.to_vec(), &DefaultGateSerializer)
            .map_err(|e| anyhow!("failed to deserialize common circuit data: {}", e))?;

        Self::ensure_loaded_matches_canonical_leaf_profile(&common)?;

        let circuit_data = VerifierCircuitData {
            verifier_only,
            common,
        };

        Ok(Self { circuit_data })
    }

    fn ensure_loaded_matches_canonical_leaf_profile(
        common: &CommonCircuitData<F, D>,
    ) -> anyhow::Result<()> {
        let expected = CircuitConfig::standard_recursion_config();

        if expected.security_bits < MIN_LEAF_SECURITY_BITS {
            return Err(anyhow!(
                "canonical recursion config provides only {} security bits, below the required minimum of {}",
                expected.security_bits,
                MIN_LEAF_SECURITY_BITS
            ));
        }

        if common.config != expected {
            return Err(anyhow!(
                "loaded verifier circuit config does not match the canonical Wormhole leaf config \
                 (security_bits loaded={}, expected={})",
                common.config.security_bits,
                expected.security_bits
            ));
        }

        if common.num_public_inputs != PUBLIC_INPUTS_FELTS_LEN {
            return Err(anyhow!(
                "loaded verifier common data has {} public inputs, expected {} for the canonical Wormhole leaf circuit",
                common.num_public_inputs,
                PUBLIC_INPUTS_FELTS_LEN
            ));
        }

        Ok(())
    }

    /// Creates a new [`WormholeVerifier`] from a verifier and common data files.
    ///
    /// Both files are read through [`read_artifact_file`] (size-capped). The
    /// keccak256 canonicality pin in [`Self::new_from_bytes`] then rejects any
    /// non-canonical contents. Paths are assumed to come from attested CI
    /// builds (`wormhole/THREAT_MODEL.md`).
    #[cfg(feature = "std")]
    pub fn new_from_files(
        verifier_data_path: &Path,
        common_data_path: &Path,
    ) -> anyhow::Result<Self> {
        let verifier_bytes = read_artifact_file(verifier_data_path)?;
        let common_bytes = read_artifact_file(common_data_path)?;

        Self::new_from_bytes(&verifier_bytes, &common_bytes)
    }

    /// Verify a [`ProofWithPublicInputs`].
    ///
    /// # Errors
    ///
    /// Returns an error if the proof is not valid.
    pub fn verify_ref(&self, proof: &ProofWithPublicInputs<F, C, D>) -> anyhow::Result<()> {
        self.circuit_data
            .verify(proof.clone())
            .map_err(|e| anyhow!("proof verification failed: {}", e))
    }

    /// Verify a [`ProofWithPublicInputs`].
    ///
    /// # Errors
    ///
    /// Returns an error if the proof is not valid.
    pub fn verify(&self, proof: ProofWithPublicInputs<F, C, D>) -> anyhow::Result<()> {
        self.verify_ref(&proof)
    }
}

#[cfg(all(test, feature = "std"))]
mod tests {
    use super::*;

    fn temp_dir(tag: &str) -> std::path::PathBuf {
        let dir = std::env::temp_dir().join(format!(
            "qp-verifier-artifact-test-{}-{}",
            tag,
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        dir
    }

    /// `new_from_bytes` is the public loading contract, so the size bound
    /// must be enforced there — not only in the file wrapper — otherwise a
    /// caller-supplied oversized slice is keccak-hashed in full before the
    /// canonicality pin rejects it.
    #[test]
    fn new_from_bytes_rejects_oversized_slices_before_hashing() {
        let oversized = vec![0u8; MAX_VERIFIER_ARTIFACT_BYTES as usize + 1];

        let err = WormholeVerifier::new_from_bytes(&oversized, b"irrelevant").unwrap_err();
        assert!(
            format!("{err:#}").contains("exceeds the"),
            "oversized verifier bytes must be rejected by the size cap, got: {err:#}"
        );

        let err = WormholeVerifier::new_from_bytes(b"irrelevant", &oversized).unwrap_err();
        assert!(
            format!("{err:#}").contains("exceeds the"),
            "oversized common bytes must be rejected by the size cap, got: {err:#}"
        );
    }

    /// An oversized artifact file must be rejected by a size bound BEFORE its
    /// contents are buffered, not after: `std::fs::read` would otherwise
    /// allocate and read the whole file just so the keccak pin can reject it,
    /// letting an attacker-planted sparse file memory-starve verifier startup
    /// (audit finding: unbounded trusted file reads).
    #[test]
    fn new_from_files_rejects_oversized_artifact_before_reading() {
        let dir = temp_dir("oversized");

        let verifier_path = dir.join("verifier.bin");
        let common_path = dir.join("common.bin");
        // A sparse file claims an enormous length without costing disk space,
        // exactly like an attacker-planted artifact would.
        std::fs::File::create(&verifier_path)
            .unwrap()
            .set_len(MAX_VERIFIER_ARTIFACT_BYTES + 1)
            .unwrap();
        std::fs::write(&common_path, b"irrelevant").unwrap();

        let err = WormholeVerifier::new_from_files(&verifier_path, &common_path).unwrap_err();
        assert!(
            format!("{err:#}").contains("exceeds the"),
            "oversized artifact must be rejected by the size cap, got: {err:#}"
        );

        std::fs::remove_dir_all(&dir).unwrap();
    }
}