kontor_crypto/
lib.rs

1//! Kontor Proof-of-Retrievability (PoR) library
2//!
3//! This library provides a unified Proof-of-Retrievability system using Nova recursive SNARKs.
4//! It supports both single-file and multi-file proofs through a consistent API.
5//!
6//! ## Main Components
7//!
8//! - [`api`]: High-level unified API for single and multi-file proofs
9//! - [`merkle`]: Merkle tree implementation with Poseidon hashing
10//! - [`erasure`]: Reed-Solomon erasure coding for fault tolerance
11//! - [`circuit`]: Unified Nova circuit supporting dynamic numbers of files
12//! - [`ledger`]: File ledger for multi-file aggregation
13//! - [`config`]: Centralized configuration constants
14//!
15//! ## Error Handling
16//!
17//! This library uses `Result` types for robust error handling. Core functions return
18//! `Result<T, KontorPoRError>` to provide detailed error information:
19//!
20//! - `prepare_file()` returns `Result<(PreparedFile, FileMetadata), KontorPoRError>`
21//! - `reconstruct_file()` returns `Result<Vec<u8>, KontorPoRError>`
22//! - `build_tree()` returns `Result<(MerkleTree, F), KontorPoRError>`
23//! - `get_padded_proof_for_leaf()` returns `Result<CircuitMerkleProof, KontorPoRError>`
24//!
25//! ## Quick Start
26//!
27//! ### Basic Usage
28//! ```rust,no_run
29//! use kontor_crypto::{api::{self, PorSystem}, FileLedger, KontorPoRError};
30//!
31//! // 1. Prepare file with Reed-Solomon erasure coding (fixed 31-byte symbols)
32//! //    Deterministic nonce ensures unique file_id (e.g., user_id + timestamp)
33//! let data = b"Hello, world! This is test data for Nova PoR.";
34//! let nonce = b"user_alice_1704067200";
35//! let (prepared, metadata) = api::prepare_file(data, "test.dat", nonce)?;
36//!
37//! // 2. Create ledger and add the file
38//! let mut ledger = FileLedger::new();
39//! ledger.add_file(&metadata)?;
40//!
41//! // 3. Create PorSystem and generate proof
42//! let system = PorSystem::new(&ledger);
43//! let challenge = api::Challenge::new(metadata.clone(), 1000, 3, api::FieldElement::from(42u64), String::from("node_1"));
44//! let proof = system.prove(vec![&prepared], &[challenge.clone()])?;
45//!
46//! // 4. Verify the proof
47//! let is_valid = system.verify(&proof, &[challenge])?;
48//! assert!(is_valid);
49//! # Ok::<(), KontorPoRError>(())
50//! ```
51//!
52//! ### Multi-File Proof
53//! ```rust,no_run
54//! use kontor_crypto::{api::{self, PorSystem}, FileLedger, KontorPoRError};
55//!
56//! // 1. Prepare multiple files (deterministic nonces ensure unique file_ids)
57//! let (prepared1, metadata1) = api::prepare_file(b"File 1 content", "file1.dat", b"upload_001")?;
58//! let (prepared2, metadata2) = api::prepare_file(b"File 2 content", "file2.dat", b"upload_002")?;
59//!
60//! // 2. Build ledger
61//! let mut ledger = FileLedger::new();
62//! ledger.add_file(&metadata1)?;
63//! ledger.add_file(&metadata2)?;
64//!
65//! // 3. Create challenges and prove (different seeds supported for multi-batch aggregation)
66//! let system = PorSystem::new(&ledger);
67//! let challenges = vec![
68//!     api::Challenge::new(metadata1.clone(), 1000, 2, api::FieldElement::from(42u64), String::from("node_1")),
69//!     api::Challenge::new(metadata2.clone(), 1001, 2, api::FieldElement::from(43u64), String::from("node_1")),
70//! ];
71//!
72//! let files = vec![&prepared1, &prepared2];
73//! let proof = system.prove(files, &challenges)?;
74//! let is_valid = system.verify(&proof, &challenges)?;
75//! assert!(is_valid);
76//! # Ok::<(), KontorPoRError>(())
77//! ```
78
79pub mod api;
80pub mod circuit;
81pub mod circuit_safety;
82pub mod config;
83pub mod erasure;
84pub mod error;
85pub mod ledger;
86pub mod merkle;
87pub mod metrics;
88pub mod params;
89pub mod poseidon;
90pub mod utils;
91
92// Re-export commonly used types and functions for convenience
93pub use api::{prepare_file, reconstruct_file, tree_depth_from_metadata, PorSystem};
94pub use api::{Challenge, FieldElement, FileMetadata, PorParams, PreparedFile, Proof};
95pub use circuit::{CircuitWitness, FileProofWitness, PorCircuit};
96pub use error::{KontorPoRError, Result};
97pub use ledger::{FileDescriptor, FileLedger};
98pub use merkle::{
99    build_tree, build_tree_from_leaves, get_leaf_hash, get_padded_proof_for_leaf, hash_leaf_data,
100    hash_node, verify_merkle_proof_in_place, CircuitMerkleProof, MerkleTree,
101};
102pub use utils::{derive_index_from_bits, field_from_uniform_bytes, leaf_to_bytes31};
kontor_crypto/lib.rs

kontor_crypto/
lib.rs
