chie-shared

Shared types, errors, and utilities for the CHIE Protocol.

Overview

This crate provides common types and utilities used across all CHIE Protocol components including the coordinator server, P2P nodes, desktop client, and web applications.

Features

Core Protocol Types: ContentMetadata, BandwidthProof, ChunkRequest/Response
Error Types: Comprehensive error handling with ProtocolError, VerificationError, RewardError
Database Conversions: Traits for converting between domain types and database models
Utility Functions: Formatting, validation, calculations, and more
JSON Schema Generation: Optional schema generation for API documentation (enable schema feature)
Constants: Protocol-wide constants for timeouts, limits, and thresholds

Usage

Add this to your Cargo.toml:

[dependencies]
chie-shared = { path = "../chie-shared" }

Enable JSON schema generation:

[dependencies]
chie-shared = { path = "../chie-shared", features = ["schema"] }

Examples

Creating Content Metadata

use chie_shared::{ContentMetadataBuilder, ContentCategory, ContentStatus};
use uuid::Uuid;

let creator_id = Uuid::new_v4();
let metadata = ContentMetadataBuilder::new()
    .cid("QmExampleCID123")
    .title("My 3D Model")
    .description("A high-quality 3D model")
    .category(ContentCategory::ThreeDModels)
    .add_tag("blender")
    .add_tag("game-ready")
    .size_bytes(5 * 1024 * 1024) // 5 MB
    .price(1000)
    .creator_id(creator_id)
    .status(ContentStatus::Active)
    .build()
    .expect("Failed to build metadata");

assert!(metadata.is_valid());
assert_eq!(metadata.size_mb(), 5.0);

Building a Bandwidth Proof

use chie_shared::BandwidthProofBuilder;

let proof = BandwidthProofBuilder::new()
    .content_cid("QmTest123")
    .chunk_index(0)
    .bytes_transferred(262144) // 256 KB
    .provider_peer_id("12D3KooProvider")
    .requester_peer_id("12D3KooRequester")
    .provider_public_key(vec![1u8; 32])
    .requester_public_key(vec![2u8; 32])
    .provider_signature(vec![3u8; 64])
    .requester_signature(vec![4u8; 64])
    .challenge_nonce(vec![5u8; 32])
    .chunk_hash(vec![6u8; 32])
    .timestamps(1000, 1250) // 250ms latency
    .build()
    .expect("Failed to build proof");

assert!(proof.is_valid());
assert!(proof.meets_quality_threshold());

Using Utility Functions

use chie_shared::{format_bytes, format_points, calculate_demand_multiplier};

// Format bytes for display
assert_eq!(format_bytes(1_048_576), "1.00 MB");

// Format points with thousands separator
assert_eq!(format_points(1_234_567), "1,234,567");

// Calculate reward multiplier based on demand/supply
let multiplier = calculate_demand_multiplier(100, 50);
assert_eq!(multiplier, 3.0); // High demand = 3x multiplier

Module Structure

types: Core protocol types (ContentMetadata, BandwidthProof, etc.)
errors: Error types for all protocol operations
conversions: Database conversion traits and helpers
utils: Utility functions for formatting, validation, calculations
constants: Protocol-wide constants
schema: JSON schema generation (feature-gated)

Testing

Run tests:

cargo test

Run property-based tests:

cargo test --test proptests

Run benchmarks:

cargo bench

Performance

All core types are optimized for fast serialization/deserialization, minimal allocations, and efficient validation. See benches/ for detailed performance metrics.

License

See LICENSE file in the project root.

chie-shared 0.1.0