kontor-crypto 0.1.2

Kontor Proof-of-Retrievability system for decentralized storage
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! Kontor Proof-of-Retrievability (PoR) library
//!
//! This library provides a unified Proof-of-Retrievability system using Nova recursive SNARKs.
//! It supports both single-file and multi-file proofs through a consistent API.
//!
//! ## Main Components
//!
//! - [`api`]: High-level unified API for single and multi-file proofs
//! - [`merkle`]: Merkle tree implementation with Poseidon hashing
//! - [`erasure`]: Reed-Solomon erasure coding for fault tolerance
//! - [`circuit`]: Unified Nova circuit supporting dynamic numbers of files
//! - [`ledger`]: File ledger for multi-file aggregation
//! - [`config`]: Centralized configuration constants
//!
//! ## Error Handling
//!
//! This library uses `Result` types for robust error handling. Core functions return
//! `Result<T, KontorPoRError>` to provide detailed error information:
//!
//! - `prepare_file()` returns `Result<(PreparedFile, FileMetadata), KontorPoRError>`
//! - `reconstruct_file()` returns `Result<Vec<u8>, KontorPoRError>`
//! - `build_tree()` returns `Result<(MerkleTree, F), KontorPoRError>`
//! - `get_padded_proof_for_leaf()` returns `Result<CircuitMerkleProof, KontorPoRError>`
//!
//! ## Quick Start
//!
//! ### Basic Usage
//! ```rust,no_run
//! use kontor_crypto::{api::{self, PorSystem}, FileLedger, KontorPoRError};
//!
//! // 1. Prepare file with Reed-Solomon erasure coding (fixed 31-byte symbols)
//! let data = b"Hello, world! This is test data for Nova PoR.";
//! let (prepared, metadata) = api::prepare_file(data, "test.dat")?;
//!
//! // 2. Create ledger and add the file
//! let mut ledger = FileLedger::new();
//! ledger.add_file(
//!     metadata.file_id.clone(),
//!     metadata.root,
//!     api::tree_depth_from_metadata(&metadata)
//! )?;
//!
//! // 3. Create PorSystem and generate proof
//! let system = PorSystem::new(&ledger);
//! let challenge = api::Challenge::new(metadata.clone(), 1000, 3, api::FieldElement::from(42u64), String::from("node_1"));
//! let proof = system.prove(vec![&prepared], &[challenge.clone()])?;
//!
//! // 4. Verify the proof
//! let is_valid = system.verify(&proof, &[challenge])?;
//! assert!(is_valid);
//! # Ok::<(), KontorPoRError>(())
//! ```
//!
//! ### Multi-File Proof
//! ```rust,no_run
//! use kontor_crypto::{api::{self, PorSystem}, FileLedger, KontorPoRError};
//!
//! // 1. Prepare multiple files
//! let (prepared1, metadata1) = api::prepare_file(b"File 1 content", "file1.dat")?;
//! let (prepared2, metadata2) = api::prepare_file(b"File 2 content", "file2.dat")?;
//!
//! // 2. Build ledger
//! let mut ledger = FileLedger::new();
//! ledger.add_file(metadata1.file_id.clone(), metadata1.root, api::tree_depth_from_metadata(&metadata1))?;
//! ledger.add_file(metadata2.file_id.clone(), metadata2.root, api::tree_depth_from_metadata(&metadata2))?;
//!
//! // 3. Create challenges and prove (different seeds supported for multi-batch aggregation)
//! let system = PorSystem::new(&ledger);
//! let challenges = vec![
//!     api::Challenge::new(metadata1.clone(), 1000, 2, api::FieldElement::from(42u64), String::from("node_1")),
//!     api::Challenge::new(metadata2.clone(), 1001, 2, api::FieldElement::from(43u64), String::from("node_1")),
//! ];
//!
//! let files = vec![&prepared1, &prepared2];
//! let proof = system.prove(files, &challenges)?;
//! let is_valid = system.verify(&proof, &challenges)?;
//! assert!(is_valid);
//! # Ok::<(), KontorPoRError>(())
//! ```

pub mod api;
pub mod circuit;
pub mod circuit_safety;
pub mod config;
pub mod erasure;
pub mod error;
pub mod ledger;
pub mod merkle;
pub mod params;
pub mod poseidon;
pub mod utils;

// Re-export commonly used types and functions for convenience
pub use api::{prepare_file, reconstruct_file, tree_depth_from_metadata, PorSystem};
pub use api::{Challenge, FieldElement, FileMetadata, PorParams, PreparedFile, Proof};
pub use circuit::{CircuitWitness, FileProofWitness, PorCircuit};
pub use error::{KontorPoRError, Result};
pub use ledger::FileLedger;
pub use merkle::{
    build_tree, build_tree_from_leaves, get_leaf_hash, get_padded_proof_for_leaf, hash_leaf_data,
    hash_node, verify_merkle_proof_in_place, CircuitMerkleProof, MerkleTree,
};
pub use utils::{derive_index_from_bits, leaf_to_bytes31};