quilibrium_verkle/
lib.rs

1//! # Quilibrium Verkle Trie
2//!
3//! A Verkle trie implementation with KZG polynomial commitments for the Quilibrium network.
4//!
5//! This crate provides:
6//! - Vector commitment trie data structure with 64-ary branching
7//! - KZG polynomial commitments using BLS48-581 curve
8//! - Cryptographic inclusion proofs (single and multi-key)
9//! - RDF schema-based field mapping for structured data
10//!
11//! ## Features
12//!
13//! ### Verkle Trie
14//! A 64-ary tree structure where each branch node's children are committed using
15//! KZG polynomial commitments. This enables:
16//! - Constant-size commitments (74 bytes) regardless of tree size
17//! - Efficient inclusion proofs with logarithmic proof size
18//! - Cryptographic binding of all data in the tree
19//!
20//! ### KZG Proofs
21//! Generate and verify cryptographic proofs that specific keys exist in the tree
22//! with their associated values, without revealing the entire tree structure.
23//!
24//! ### RDF Schema Support
25//! Map structured records (like name records) to the verkle trie using RDF schemas
26//! defined in Turtle format. This provides:
27//! - Deterministic field ordering
28//! - Type-safe field access
29//! - Schema evolution support
30//!
31//! ## Example: Basic Verkle Trie
32//!
33//! ```rust
34//! use quilibrium_verkle::VectorCommitmentTrie;
35//!
36//! // Initialize BLS library
37//! bls48581::init();
38//!
39//! // Create a new trie
40//! let mut trie = VectorCommitmentTrie::new();
41//!
42//! // Insert key-value pairs
43//! trie.insert(vec![1, 2, 3], vec![4, 5, 6]).unwrap();
44//! trie.insert(vec![1, 2, 4], vec![7, 8, 9]).unwrap();
45//!
46//! // Get the root commitment
47//! let commitment = trie.commit().unwrap();
48//! println!("Root commitment: {}", hex::encode(&commitment));
49//!
50//! // Retrieve a value
51//! let value = trie.get(&[1, 2, 3]);
52//! assert_eq!(value, Some(vec![4, 5, 6]));
53//! ```
54//!
55//! ## Example: Generating and Verifying Proofs
56//!
57//! ```rust
58//! use quilibrium_verkle::VectorCommitmentTrie;
59//!
60//! bls48581::init();
61//!
62//! let mut trie = VectorCommitmentTrie::new();
63//! trie.insert(vec![1], vec![10]).unwrap();
64//! trie.insert(vec![2], vec![20]).unwrap();
65//!
66//! // Generate proof for key [1]
67//! let proof = trie.prove(&[1]).unwrap();
68//! let commitment = trie.commit().unwrap();
69//!
70//! // Verify the proof
71//! let is_valid = proof.verify(&commitment).unwrap();
72//! assert!(is_valid);
73//!
74//! // Extract the proven value
75//! let values = proof.verify_and_extract(&commitment).unwrap();
76//! assert_eq!(values[0], vec![10]);
77//! ```
78//!
79//! ## Example: RDF-Based Field Proofs
80//!
81//! ```rust
82//! use quilibrium_verkle::{VectorCommitmentTrie, RdfMultiprover};
83//!
84//! bls48581::init();
85//!
86//! // RDF schema defining a name record
87//! let schema = r#"
88//! @prefix qcl: <https://types.quilibrium.com/qcl/> .
89//! @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
90//! @prefix name: <https://types.quilibrium.com/schema-repository/name/> .
91//!
92//! name:NameRecord a rdfs:Class .
93//! name:Name a rdfs:Property ;
94//!     rdfs:domain qcl:String ;
95//!     qcl:size 32 ;
96//!     qcl:order 1 .
97//! "#;
98//!
99//! // Create tree and multiprover
100//! let mut tree = VectorCommitmentTrie::new();
101//! let multiprover = RdfMultiprover::new();
102//!
103//! // Insert data at the correct index
104//! tree.insert(vec![1 << 2], b"Alice".to_vec()).unwrap();
105//!
106//! // Generate proof for the "Name" field
107//! let proof = multiprover.prove(schema, &["Name".to_string()], &mut tree).unwrap();
108//! println!("Proof size: {} bytes", proof.to_bytes().unwrap().len());
109//! ```
110
111pub mod node;
112pub mod trie;
113pub mod schema;
114pub mod proof;
115pub mod rdf;
116
117#[cfg(test)]
118mod test_vector;
119
120#[cfg(test)]
121mod rdf_test;
122
123pub use node::{VectorCommitmentNode, VectorCommitmentLeafNode, VectorCommitmentBranchNode};
124pub use trie::VectorCommitmentTrie;
125pub use schema::{RecordSchema, FieldMapping};
126pub use proof::{TraversalProof, TraversalSubProof};
127pub use rdf::{RdfSchemaParser, RdfMultiprover, RdfField, RdfMultiproof};
128
129// Re-export error types for convenience
130pub use error::{VerkleError, Result};
131
132// Re-export bls48581 init function for convenience
133pub use bls48581::init;
134
135/// Error types for the verkle trie
136pub mod error {
137    use thiserror::Error;
138
139    /// Result type alias for verkle operations
140    pub type Result<T> = std::result::Result<T, VerkleError>;
141
142    /// Errors that can occur in verkle trie operations
143    #[derive(Error, Debug)]
144    pub enum VerkleError {
145        #[error("Invalid data: {0}")]
146        InvalidData(String),
147
148        #[error("Cryptographic error: {0}")]
149        CryptoError(String),
150
151        #[error("Serialization error: {0}")]
152        SerializationError(String),
153
154        #[error("I/O error: {0}")]
155        IoError(#[from] std::io::Error),
156    }
157}
quilibrium_verkle/lib.rs

quilibrium_verkle/
lib.rs
