stealth_lib/lib.rs
1//! # stealth-lib
2//!
3//! ZK-friendly cryptographic primitives for Rust.
4//!
5//! This library provides cryptographic primitives designed for use in zero-knowledge
6//! proof systems like Tornado Cash, Semaphore, and similar applications.
7//!
8//! ## Features
9//!
10//! - **MiMC Hash**: Efficient hash function designed for ZK circuits
11//! - **Merkle Tree**: MiMC-based tree with proof generation and verification
12//! - **No unsafe code**: `#![deny(unsafe_code)]`
13//! - **`no_std` support**: Optional, for WASM/embedded targets
14//!
15//! ## Quick Start
16//!
17//! ```
18//! use stealth_lib::{MerkleTree, MerkleProof};
19//!
20//! // Create a Merkle tree with 20 levels (can hold ~1M leaves)
21//! let mut tree = MerkleTree::new(20).unwrap();
22//!
23//! // Insert some leaves
24//! let idx = tree.insert(12345).unwrap();
25//!
26//! // Generate and verify a proof
27//! let proof = tree.prove(idx).unwrap();
28//! let root = tree.root().unwrap();
29//! assert!(proof.verify(root, &tree.hasher()));
30//! ```
31//!
32//! ## Security Model
33//!
34//! **Designed for**: Zero-knowledge proof circuits (Tornado Cash, Semaphore, etc.)
35//!
36//! **Guarantees**:
37//! - Collision resistance of MiMC (computational)
38//! - Correct Merkle proofs for membership verification
39//!
40//! **Non-Goals / Explicit Exclusions**:
41//! - ❌ Constant-time execution (vulnerable to timing side-channels)
42//! - ❌ General-purpose cryptographic primitives
43//! - ❌ Professional security audit (pending)
44//!
45//! For general-purpose cryptography, use established crates like `ring`, `sha2`,
46//! `ed25519-dalek`, etc.
47//!
48//! ## Feature Flags
49//!
50//! | Feature | Default | Description |
51//! |---------|---------|-------------|
52//! | `std` | ✅ | Enable standard library support |
53//! | `serde` | ❌ | Enable serde serialization |
54//! | `borsh` | ❌ | Enable borsh serialization |
55//! | `experimental` | ❌ | ⚠️ Educational code only, NOT for production |
56
57#![cfg_attr(not(feature = "std"), no_std)]
58#![deny(unsafe_code)]
59#![warn(missing_docs)]
60#![warn(clippy::all)]
61
62#[cfg(not(feature = "std"))]
63extern crate alloc;
64
65// Core modules
66pub mod error;
67pub mod hash;
68pub mod merkle;
69pub mod encoding;
70
71// Experimental/educational modules (feature-gated)
72#[cfg(feature = "experimental")]
73pub mod experimental;
74
75// Legacy modules (deprecated, will be removed in 2.0)
76#[deprecated(since = "1.0.0", note = "Use hash::mimc::MimcHasher instead")]
77pub mod hasher;
78#[deprecated(since = "1.0.0", note = "Use merkle::MerkleTree instead")]
79pub mod merkle_tree;
80#[deprecated(since = "1.0.0", note = "Use error module instead")]
81pub mod utils;
82
83// Public API re-exports
84pub use error::{Error, Result};
85pub use hash::MimcHasher;
86pub use merkle::{MerkleProof, MerkleTree};
87
88// Backwards compatibility type alias
89#[deprecated(since = "1.0.0", note = "Renamed to Error")]
90#[allow(missing_docs)]
91pub type SolanaError = Error;