exo_proofs/lib.rs
1// Copyright 2026 Exochain Foundation
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at:
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// SPDX-License-Identifier: Apache-2.0
16
17//! # EXOCHAIN zero-knowledge proof skeleton — **UNAUDITED**.
18//!
19//! ## ⚠️ NOT PRODUCTION CRYPTOGRAPHY
20//!
21//! This crate is a pedagogical / structural implementation demonstrating
22//! the *shape* of a SNARK / STARK / ZKML proof system. It uses blake3
23//! "stand-ins" for elliptic curve points and has not been reviewed by a
24//! cryptographer. **Do not rely on it for any production trust claim.**
25//!
26//! By constitutional rule (EXOCHAIN "never stub" doctrine), every public
27//! entry point refuses to execute unless the opt-in Cargo feature
28//! `unaudited-pedagogical-proofs` is enabled. Callers who accidentally
29//! depend on this crate will fail loudly with
30//! [`error::ProofError::UnauditedImplementation`] instead of silently
31//! trusting a fake proof.
32//!
33//! When a production-hardened proof backend lands, remove the feature
34//! flag and delete the `UnauditedImplementation` variant.
35//!
36//! ## Modules
37//!
38//! - R1CS circuit abstraction (`circuit`)
39//! - SNARK proof generation/verification (`snark`) — skeleton
40//! - STARK proof system (`stark`) — skeleton
41//! - Zero-knowledge ML verification (`zkml`) — skeleton
42//! - Unified proof verifier (`verifier`)
43//!
44//! ## Usage
45//!
46//! ```toml
47//! # Cargo.toml — for tests/demos only
48//! [dependencies]
49//! exo-proofs = { path = "...", features = ["unaudited-pedagogical-proofs"] }
50//! ```
51//!
52//! Without the feature, every call returns `Err(UnauditedImplementation)`.
53//! This is intentional.
54
55#![cfg_attr(test, allow(clippy::expect_used, clippy::unwrap_used))]
56
57#[cfg(not(target_os = "zkvm"))]
58pub mod circuit;
59pub mod envelope;
60pub mod error;
61#[cfg(all(feature = "risc0-verifier", not(target_os = "zkvm")))]
62pub mod riscz;
63#[cfg(not(target_os = "zkvm"))]
64pub mod snark;
65#[cfg(not(target_os = "zkvm"))]
66pub mod stark;
67#[cfg(not(target_os = "zkvm"))]
68pub mod verifier;
69#[cfg(not(target_os = "zkvm"))]
70pub mod zkml;
71
72/// Internal guard used by every public entry point. Returns an error
73/// unless the `unaudited-pedagogical-proofs` feature is enabled.
74#[doc(hidden)]
75#[inline]
76pub fn guard_unaudited(api: &'static str) -> Result<(), error::ProofError> {
77 #[cfg(feature = "unaudited-pedagogical-proofs")]
78 {
79 let _ = api;
80 Ok(())
81 }
82 #[cfg(not(feature = "unaudited-pedagogical-proofs"))]
83 {
84 Err(error::ProofError::UnauditedImplementation { api })
85 }
86}