chie_shared/
lib.rs

1//! Shared types, errors, and utilities for CHIE Protocol.
2//!
3//! This crate provides common types and utilities used across all CHIE Protocol components:
4//! - Core protocol types (content, bandwidth proofs, chunks)
5//! - Error types for protocol operations
6//! - Database conversion traits
7//! - Utility functions for common operations
8//! - JSON schema generation (optional)
9//!
10//! # Examples
11//!
12//! ## Creating Content Metadata
13//!
14//! ```
15//! use chie_shared::{ContentMetadataBuilder, ContentCategory, ContentStatus};
16//! use uuid::Uuid;
17//!
18//! let creator_id = Uuid::new_v4();
19//! let metadata = ContentMetadataBuilder::new()
20//!     .cid("QmExampleCID123")
21//!     .title("My 3D Model")
22//!     .description("A high-quality 3D model")
23//!     .category(ContentCategory::ThreeDModels)
24//!     .add_tag("blender")
25//!     .add_tag("game-ready")
26//!     .size_bytes(5 * 1024 * 1024) // 5 MB
27//!     .price(1000)
28//!     .creator_id(creator_id)
29//!     .status(ContentStatus::Active)
30//!     .build()
31//!     .expect("Failed to build metadata");
32//!
33//! assert!(metadata.is_valid());
34//! assert_eq!(metadata.size_mb(), 5.0);
35//! ```
36//!
37//! ## Building a Bandwidth Proof
38//!
39//! ```
40//! use chie_shared::BandwidthProofBuilder;
41//!
42//! let proof = BandwidthProofBuilder::new()
43//!     .content_cid("QmTest123")
44//!     .chunk_index(0)
45//!     .bytes_transferred(262144) // 256 KB
46//!     .provider_peer_id("12D3KooProvider")
47//!     .requester_peer_id("12D3KooRequester")
48//!     .provider_public_key(vec![1u8; 32])
49//!     .requester_public_key(vec![2u8; 32])
50//!     .provider_signature(vec![3u8; 64])
51//!     .requester_signature(vec![4u8; 64])
52//!     .challenge_nonce(vec![5u8; 32])
53//!     .chunk_hash(vec![6u8; 32])
54//!     .timestamps(1000, 1250) // 250ms latency
55//!     .build()
56//!     .expect("Failed to build proof");
57//!
58//! assert!(proof.is_valid());
59//! assert!(proof.meets_quality_threshold());
60//! assert_eq!(proof.bandwidth_bps(), 1048576.0); // ~1 MB/s
61//! ```
62//!
63//! ## Creating a Chunk Request
64//!
65//! ```
66//! use chie_shared::{ChunkRequest, generate_nonce};
67//!
68//! let request = ChunkRequest::new(
69//!     "QmExampleContent",
70//!     0,
71//!     generate_nonce(),
72//!     "12D3KooRequester",
73//!     [1u8; 32],
74//! );
75//!
76//! assert!(request.is_timestamp_valid());
77//! ```
78//!
79//! ## Using Utility Functions
80//!
81//! ```
82//! use chie_shared::{format_bytes, format_points, calculate_demand_multiplier};
83//!
84//! // Format bytes for display
85//! assert_eq!(format_bytes(1_048_576), "1.00 MB");
86//!
87//! // Format points with thousands separator
88//! assert_eq!(format_points(1_234_567), "1,234,567");
89//!
90//! // Calculate reward multiplier based on demand/supply
91//! let multiplier = calculate_demand_multiplier(100, 50);
92//! assert_eq!(multiplier, 3.0); // High demand = 3x multiplier
93//! ```
94//!
95//! ## Working with Cache Statistics
96//!
97//! ```
98//! use chie_shared::CacheStats;
99//!
100//! // Create cache statistics
101//! let stats = CacheStats::new(50, 100, 80, 20);
102//! println!("Hit rate: {:.2}%", stats.hit_rate * 100.0);
103//! println!("Fill: {:.2}%", stats.fill_percentage() * 100.0);
104//! println!("Efficiency: {:.2}", stats.efficiency_score());
105//! ```
106//!
107//! ## Tracking Performance Metrics
108//!
109//! ```
110//! use chie_shared::{OperationStats, BandwidthMetrics};
111//!
112//! // Operation timing statistics
113//! let ops_stats = OperationStats::new(100, 5000.0, 10.0, 200.0);
114//! println!("Average: {:.2}ms", ops_stats.avg_duration_ms);
115//! println!("Throughput: {:.2} ops/sec", ops_stats.ops_per_second());
116//!
117//! // Bandwidth metrics
118//! let bw_metrics = BandwidthMetrics::new(1_000_000, 1000.0, 10, 2_000_000.0);
119//! println!("Average: {:.2} Mbps", bw_metrics.avg_mbps());
120//! println!("Peak: {:.2} Mbps", bw_metrics.peak_mbps());
121//! ```
122//!
123//! ## Managing User Quotas
124//!
125//! ```
126//! use chie_shared::{UserQuota, StorageQuota, BandwidthQuota, RateLimitQuota};
127//!
128//! // Create storage quota
129//! let storage = StorageQuota::new(
130//!     10 * 1024 * 1024 * 1024, // 10 GB total
131//!     5 * 1024 * 1024 * 1024,  // 5 GB used
132//!     1 * 1024 * 1024 * 1024,  // 1 GB reserved
133//! );
134//! println!("Storage available: {} GB", storage.available_bytes() / (1024 * 1024 * 1024));
135//! println!("Utilization: {:.1}%", storage.utilization() * 100.0);
136//!
137//! // Create bandwidth quota (100 GB/month)
138//! let bandwidth = BandwidthQuota::new(
139//!     100 * 1024 * 1024 * 1024, // 100 GB total
140//!     50 * 1024 * 1024 * 1024,  // 50 GB used
141//!     30 * 24 * 60 * 60,        // 30 days in seconds
142//!     chie_shared::now_ms() as u64,
143//! );
144//! println!("Bandwidth remaining: {} GB", bandwidth.remaining_bytes() / (1024 * 1024 * 1024));
145//!
146//! // Create rate limit quota (100 requests/minute)
147//! let rate_limit = RateLimitQuota::new(100, 45, 60, chie_shared::now_ms() as u64);
148//! println!("Requests remaining: {}", rate_limit.remaining_requests());
149//! ```
150//!
151//! ## Batch Operations
152//!
153//! ```
154//! use chie_shared::{BatchProofSubmission, BandwidthProof, BandwidthProofBuilder};
155//!
156//! // Create multiple proofs
157//! let proof1 = BandwidthProofBuilder::new()
158//!     .content_cid("QmTest1")
159//!     .chunk_index(0)
160//!     .bytes_transferred(262144)
161//!     .provider_peer_id("12D3Koo1")
162//!     .requester_peer_id("12D3Koo2")
163//!     .provider_public_key(vec![1u8; 32])
164//!     .requester_public_key(vec![2u8; 32])
165//!     .provider_signature(vec![3u8; 64])
166//!     .requester_signature(vec![4u8; 64])
167//!     .challenge_nonce(vec![5u8; 32])
168//!     .chunk_hash(vec![6u8; 32])
169//!     .timestamps(1000, 1250)
170//!     .build()
171//!     .expect("Failed to build proof");
172//!
173//! // Submit proofs in batch
174//! let batch = BatchProofSubmission::new(vec![proof1], "12D3Koo1");
175//! println!("Batch contains {} proofs", batch.proof_count());
176//! println!("Total bytes: {}", batch.total_bytes_transferred());
177//! ```
178
179pub mod config;
180pub mod constants;
181pub mod conversions;
182pub mod encoding;
183pub mod errors;
184pub mod messages;
185pub mod result;
186#[cfg(feature = "schema")]
187pub mod schema;
188pub mod types;
189pub mod utils;
190
191pub use config::*;
192pub use constants::*;
193pub use conversions::*;
194pub use encoding::*;
195pub use errors::*;
196pub use messages::*;
197pub use result::*;
198#[cfg(feature = "schema")]
199pub use schema::*;
200pub use types::*;
201pub use utils::*;
202
203// Re-export test helpers for use in other crates
204#[cfg(test)]
205pub use types::bandwidth::test_helpers;
chie_shared/lib.rs

chie_shared/
lib.rs
