bankai_types/
proofs.rs

1//! Core proof types for Bankai
2//!
3//! This module defines the fundamental proof types used throughout the Bankai ecosystem,
4//! including MMR (Merkle Mountain Range) proofs and hashing function specifications.
5//!
6//! All types in this module work in `no_std` environments, making them suitable for
7//! use in ZK circuits, smart contracts, and other constrained environments.
8
9extern crate alloc;
10use alloc::string::String;
11use alloc::vec::Vec;
12
13#[cfg(feature = "serde")]
14use serde::{Deserialize, Serialize};
15#[cfg(feature = "utoipa")]
16use utoipa::ToSchema;
17
18/// MMR (Merkle Mountain Range) proof for header inclusion
19///
20/// Proves that a specific blockchain header is committed in a verified MMR.
21/// The MMR roots are established by STWO zero-knowledge proofs in Bankai blocks.
22///
23/// # Fields
24///
25/// - `network_id` - Identifies which chain (0 = beacon, 1 = execution)
26/// - `block_number` - Block number of the header being proven
27/// - `hashing_function` - Hash function used for MMR (Keccak or Poseidon)
28/// - `header_hash` - Hash of the header being proven
29/// - `root` - MMR root hash (must match the root in verified Bankai block)
30/// - `elements_index` - Position of this element in the MMR
31/// - `elements_count` - Total number of elements in the MMR
32/// - `path` - Merkle path for verification (sibling hashes)
33/// - `peaks` - MMR peak hashes for the current MMR state
34#[derive(Debug, Clone)]
35#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
36#[cfg_attr(feature = "utoipa", derive(ToSchema))]
37pub struct MmrProofDto {
38    pub network_id: u64,
39    pub block_number: u64,
40    pub hashing_function: HashingFunctionDto,
41    pub header_hash: String,
42    pub root: String,
43    pub elements_index: u64,
44    pub elements_count: u64,
45    pub path: Vec<String>,
46    pub peaks: Vec<String>,
47}
48
49/// Request for an MMR proof
50///
51/// Used to request a proof that a specific header is committed in the MMR.
52#[derive(Debug, Clone)]
53#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
54#[cfg_attr(feature = "utoipa", derive(ToSchema))]
55pub struct MmrProofRequestDto {
56    pub network_id: u64,
57    pub block_number: u64,
58    pub hashing_function: HashingFunctionDto,
59    pub header_hash: String, // 0x…32
60}
61
62/// Hashing function used for MMR construction
63///
64/// Different hash functions can be used depending on the target environment:
65/// - **Keccak**: Standard Ethereum hash, efficient in EVM environments
66/// - **Poseidon**: ZK-friendly hash, efficient in zero-knowledge circuits
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
69#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
70#[cfg_attr(feature = "utoipa", derive(ToSchema))]
71pub enum HashingFunctionDto {
72    /// Keccak-256 hash function (Ethereum standard)
73    Keccak,
74    /// Poseidon hash function (ZK-friendly)
75    Poseidon,
76}
77
78/// STWO zero-knowledge proof for a Bankai block
79///
80/// Contains the cryptographic proof that establishes trust in the MMR roots.
81/// This is the foundation of Bankai's stateless light client architecture.
82#[cfg(feature = "api")]
83#[derive(Debug, Clone)]
84#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
85#[cfg_attr(feature = "utoipa", derive(ToSchema))]
86pub struct BankaiBlockProofDto {
87    /// Bankai block number this proof corresponds to
88    pub block_number: u64,
89    /// STWO proof data (JSON serialized)
90    #[cfg_attr(feature = "utoipa", schema(value_type = Object))]
91    pub proof: serde_json::Value,
92}
93
94/// Complete light client proof bundle
95///
96/// Contains everything needed for stateless verification:
97/// - STWO proof establishing trust in MMR roots
98/// - MMR proofs for specific headers
99///
100/// This is a self-contained proof that can be verified without any prior state.
101#[cfg(feature = "api")]
102#[derive(Debug, Clone)]
103#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
104#[cfg_attr(feature = "utoipa", derive(ToSchema))]
105pub struct LightClientProofDto {
106    /// The STWO block proof establishing MMR root trust
107    pub block_proof: BankaiBlockProofDto,
108    /// MMR inclusion proofs for requested headers
109    pub mmr_proofs: Vec<MmrProofDto>,
110}
111
112/// Request for a complete light client proof
113///
114/// Used to request a self-contained proof bundle for specific headers.
115#[cfg(feature = "api")]
116#[derive(Debug, Clone)]
117#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
118#[cfg_attr(feature = "utoipa", derive(ToSchema))]
119pub struct LightClientProofRequestDto {
120    /// Which Bankai block to use (None = latest)
121    pub bankai_block_number: Option<u64>,
122    /// Hash function for MMR proofs
123    pub hashing_function: HashingFunctionDto,
124    /// Headers to prove
125    pub requested_headers: Vec<HeaderRequestDto>,
126}
127
128/// Request for a specific header proof
129#[cfg(feature = "api")]
130#[derive(Debug, Clone)]
131#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
132#[cfg_attr(feature = "utoipa", derive(ToSchema))]
133pub struct HeaderRequestDto {
134    /// Network ID (0 = beacon, 1 = execution)
135    pub network_id: u64,
136    /// Header hash to prove
137    pub header_hash: String,
138}
bankai_types/proofs.rs

bankai_types/
proofs.rs
