Merge pull request #10 from axialabsresearch/v0.1.0-core-protocol-refactoring

V0.1.0 core protocol refactoring

Author: 0xTnxl

.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --all-features
+          args: --all-features --lib --bins --tests --benches
 
       - name: Check formatting
         uses: actions-rs/cargo@v1

src/error.rs

@@ -44,6 +44,7 @@ The error system implements several key components:
 
 1. **Core Error Type**
    ```rust
+   use frost_protocol::finality::FinalityError;
    pub enum Error {
        Message(String),
        State(String),

src/lib.rs

@@ -265,5 +265,5 @@ pub use routing::MessageRouter;
 pub type Result<T> = std::result::Result<T, Error>;
 pub use error::Error;
 
-mod error;
+pub mod error;
 

src/state/error.rs

@@ -41,36 +41,60 @@ The error system implements several key components:
 
 1. **Error Severity**
    ```rust
+   use frost_protocol::state::error::ErrorSeverity;
+
    pub enum ErrorSeverity {
        Warning,
        Error,
        Critical,
    }
+
+   // Example usage:
+   # fn main() {
+   let severity = ErrorSeverity::Warning;
+   assert!(severity < ErrorSeverity::Error);
+   assert!(severity < ErrorSeverity::Critical);
+   # }
    ```
-   - Severity levels
-   - Comparison logic
-   - Recovery guidance
-   - Operation handling
 
 2. **State Errors**
    ```rust
+   use frost_protocol::state::{error::StateError, BlockRef, ChainId};
+
    pub enum StateError {
        InvalidTransition(String),
        InvalidProof(String),
        ProofVerificationFailed(String),
        InvalidBlockRef(String),
-       RootMismatch { ... },
+       RootMismatch {
+           block_ref: BlockRef,
+           expected: String,
+           actual: String,
+       },
        ChainSpecific(String),
        Internal(String),
    }
+
+   // Example usage:
+   # fn main() {
+   let block_ref = BlockRef::new(
+       ChainId::new("ethereum"),
+       1000,
+       [0; 32]
+   );
+   let error = StateError::RootMismatch {
+       block_ref,
+       expected: "0x123...".to_string(),
+       actual: "0x456...".to_string(),
+   };
+   # }
    ```
-   - Error types
-   - Error messages
-   - Error context
-   - Recovery options
 
 3. **Proof Errors**
    ```rust
+   use frost_protocol::state::error::{ProofError, ProofErrorCategory, ErrorSeverity, ChainErrorContext, RetryGuidance};
+   use std::time::Duration;
+
    pub struct ProofError {
        category: ProofErrorCategory,
        severity: ErrorSeverity,
@@ -79,11 +103,27 @@ The error system implements several key components:
        retry: RetryGuidance,
        cause: Option<Box<ProofError>>,
    }
+
+   // Example usage:
+   # fn main() {
+   let error = ProofError::new(
+       ProofErrorCategory::Validation,
+       ErrorSeverity::Error,
+       "Invalid proof format"
+   )
+   .with_context(ChainErrorContext {
+       chain_id: "ethereum".to_string(),
+       block_number: 1000,
+       metadata: None,
+   })
+   .with_retry(RetryGuidance {
+       retryable: true,
+       retry_after: Some(Duration::from_secs(60)),
+       max_retries: Some(3),
+       alternatives: vec!["Try different proof type".to_string()],
+   });
+   # }
    ```
-   - Error categorization
-   - Severity tracking
-   - Context management
-   - Retry handling
 
 ## Features
 

src/state/mod.rs

@@ -40,11 +40,26 @@ The state system consists of several key components:
 
 1. **State Transition**
    ```rust
+   use frost_protocol::state::{BlockId, StateTransition};
+   
    pub struct StateTransition {
        source: BlockId,
        target: BlockId,
        state_data: Vec<u8>,
    }
+
+   // Example usage:
+   # fn main() {
+   let source = BlockId::Number(1000);
+   let target = BlockId::Number(1001);
+   let data = vec![1, 2, 3];
+   let transition = StateTransition::new(
+       frost_protocol::state::ChainId::new("ethereum"),
+       source,
+       target,
+       data
+   );
+   # }
    ```
    - State changes
    - Transition validation
@@ -53,10 +68,32 @@ The state system consists of several key components:
 
 2. **State Proof**
    ```rust
+   use frost_protocol::state::{StateTransition, StateProof, proof::ProofData};
+   use std::time::SystemTime;
+
    pub struct StateProof {
        transition: StateTransition,
        proof: ProofData,
    }
+
+   // Example usage:
+   # fn main() {
+   let transition = StateTransition::new(
+       frost_protocol::state::ChainId::new("ethereum"),
+       BlockId::Number(1000),
+       BlockId::Number(1001),
+       vec![1, 2, 3]
+   );
+   let proof_data = ProofData {
+       proof_type: frost_protocol::state::proof::ProofType::Basic,
+       data: vec![1, 2, 3],
+       metadata: None,
+       generated_at: SystemTime::now(),
+       expires_at: None,
+       version: 1,
+   };
+   let proof = StateProof::new(transition, proof_data);
+   # }
    ```
    - Proof generation
    - Verification
@@ -65,11 +102,23 @@ The state system consists of several key components:
 
 3. **State Types**
    ```rust
+   use frost_protocol::state::BlockId;
+
    pub enum BlockId {
        Hash([u8; 32]),
        Number(u64),
        Composite { number: u64, hash: [u8; 32] },
    }
+
+   // Example usage:
+   # fn main() {
+   let block_by_number = BlockId::Number(1000);
+   let block_by_hash = BlockId::Hash([0; 32]);
+   let block_composite = BlockId::Composite {
+       number: 1000,
+       hash: [0; 32],
+   };
+   # }
    ```
    - Block identification
    - Chain references
@@ -207,26 +256,38 @@ mod tests {
 
     #[test]
     fn test_state_transition_validation() {
+        let chain_id = ChainId::new("test-chain");
         let source = BlockId::Composite {
             number: 1,
-            hash: [0; 32],
+            hash: [0; 32],  // Source hash all zeros
         };
         let target = BlockId::Composite {
-            number: 1,
-            hash: [0; 32],
+            number: 2,
+            hash: [1; 32],  // Target hash all ones
         };
 
         let transition = StateTransition::new(
+            chain_id.clone(),
             source,
             target,
             vec![1, 2, 3],
         );
         assert!(transition.validate());
 
+        // Create invalid transition with same hash (will fail validation)
+        let invalid_source = BlockId::Composite {
+            number: 1,
+            hash: [0; 32],
+        };
+        let invalid_target = BlockId::Composite {
+            number: 2,  // Valid height difference
+            hash: [0; 32],  // Same hash as source - should fail validation
+        };
         let invalid_transition = StateTransition::new(
-            BlockId::Number(0),
-            BlockId::Number(0),
-            vec![],
+            chain_id,
+            invalid_source,
+            invalid_target,
+            vec![1],  // Valid data
         );
         assert!(!invalid_transition.validate());
     }

src/state/proof.rs

@@ -41,6 +41,10 @@ The proof system implements several key components:
 
 1. **Proof Data**
    ```rust
+   use frost_protocol::state::proof::{ProofData, ProofType};
+   use std::time::SystemTime;
+   use serde_json::json;
+
    pub struct ProofData {
        pub proof_type: ProofType,
        pub data: Vec<u8>,
@@ -49,37 +53,103 @@ The proof system implements several key components:
        pub expires_at: Option<SystemTime>,
        pub version: u32,
    }
+
+   // Example usage:
+   # fn main() {
+   let proof_data = ProofData {
+       proof_type: ProofType::Basic,
+       data: vec![1, 2, 3],
+       metadata: Some(json!({
+           "chain": "ethereum",
+           "block": 1000
+       })),
+       generated_at: SystemTime::now(),
+       expires_at: None,
+       version: 1,
+   };
+   # }
    ```
-   - Proof content
-   - Metadata handling
-   - Time tracking
-   - Version control
 
 2. **State Proof**
    ```rust
+   use frost_protocol::state::{
+       proof::{StateProof, ProofData, ProofType, VerificationResult},
+       StateTransition,
+       ChainId,
+       BlockId,
+   };
+   use std::time::SystemTime;
+
    pub struct StateProof {
        pub transition: StateTransition,
        pub proof: ProofData,
        pub verification_history: Vec<VerificationResult>,
    }
+
+   // Example usage:
+   # fn main() {
+   let transition = StateTransition::new(
+       ChainId::new("ethereum"),
+       BlockId::Number(1000),
+       BlockId::Number(1001),
+       vec![1, 2, 3],
+   );
+
+   let proof_data = ProofData {
+       proof_type: ProofType::Basic,
+       data: vec![1, 2, 3],
+       metadata: None,
+       generated_at: SystemTime::now(),
+       expires_at: None,
+       version: 1,
+   };
+
+   let proof = StateProof::new(transition, proof_data);
+   # }
    ```
-   - Transition binding
-   - Proof storage
-   - History tracking
-   - Result management
 
 3. **Proof Registry**
    ```rust
+   use frost_protocol::state::proof::{ProofRegistry, ProofType, VerificationResult};
+   use dashmap::DashMap;
+   use std::sync::Arc;
+
    pub struct ProofRegistry {
        generators: DashMap<ProofType, Arc<dyn ProofGenerator>>,
        verifiers: DashMap<ProofType, Arc<dyn ProofVerifier>>,
        verification_cache: DashMap<String, VerificationResult>,
    }
+
+   // Example usage:
+   # fn main() {
+   let registry = ProofRegistry::new();
+   
+   // Register a custom generator
+   struct BasicGenerator;
+   impl ProofGenerator for BasicGenerator {
+       fn proof_type(&self) -> ProofType {
+           ProofType::Basic
+       }
+
+       async fn generate_proof(
+           &self,
+           transition: &StateTransition,
+           _context: Option<&serde_json::Value>,
+       ) -> Result<ProofData, StateError> {
+           Ok(ProofData {
+               proof_type: ProofType::Basic,
+               data: vec![1, 2, 3],
+               metadata: None,
+               generated_at: SystemTime::now(),
+               expires_at: None,
+               version: 1,
+           })
+       }
+   }
+
+   registry.register_generator(Arc::new(BasicGenerator));
+   # }
    ```
-   - Generator management
-   - Verifier management
-   - Cache handling
-   - Concurrent access
 
 ## Features