test: Improve coverage (#10)

* test: improve coverage session scope_config storage_stream

* test: cover gaps security correctness critical

* test: overflow during additions id-collapse safety

* fix: handle large number edge cases in ID generation, timestamps, and round limits (#12)

- Updated README to correct the link for the Hashgraph-like Consensus Protocol RFC.
- Enhanced session handling by enforcing maximum vote count based on expected voters, ensuring robust error handling for overflow scenarios.

---------

Co-authored-by: Ekaterina Broslavskaya <seemenkina@gmail.com>

Author: romanzac

.gitignore

@@ -1,3 +1,6 @@
 /target
 /.vscode
 /.idea
+/.claude
+/docs
+CLAUDE.md

README.md

@@ -17,7 +17,7 @@ Perfect for group governance, voting systems, or any scenario where you need dis
 - **Event-driven** - Subscribe to consensus outcomes via a broadcast event bus
 - **Cryptographic integrity** - Votes are signed with secp256k1 and chained in a hashgraph structure
 
-Based on the [Hashgraph-like Consensus Protocol RFC](https://github.com/vacp2p/rfc-index/blob/main/vac/raw/consensus-hashgraphlike.md).
+Based on the [Hashgraph-like Consensus Protocol RFC](https://lip.logos.co/ift-ts/raw/consensus-hashgraphlike.html).
 
 ## Installation
 
@@ -88,10 +88,10 @@ Scope (group / channel)
 
 ### Network Types
 
-| Type | Rounds | Behavior |
-|------|--------|----------|
-| **Gossipsub** (default) | Fixed 2 rounds | Round 1 = proposal broadcast, Round 2 = all votes |
-| **P2P** | Dynamic `ceil(2n/3)` | Each vote advances the round by one |
+| Type                    | Rounds               | Behavior                                          |
+| ----------------------- | -------------------- | ------------------------------------------------- |
+| **Gossipsub** (default) | Fixed 2 rounds       | Round 1 = proposal broadcast, Round 2 = all votes |
+| **P2P**                 | Dynamic `ceil(2n/3)` | Each vote advances the round by one               |
 
 ## API Reference
 
@@ -270,12 +270,12 @@ pub trait ConsensusEventBus<Scope> {
 
 The `utils` module provides low-level helpers:
 
-| Function | Description |
-|----------|-------------|
-| `validate_proposal()` | Validate a proposal and its votes |
-| `validate_vote()` | Verify a vote's signature and structure |
-| `validate_vote_chain()` | Ensure parent/received hash chains are correct |
-| `has_sufficient_votes()` | Quick threshold check (count-based) |
+| Function                       | Description                                                              |
+| ------------------------------ | ------------------------------------------------------------------------ |
+| `validate_proposal()`          | Validate a proposal and its votes                                        |
+| `validate_vote()`              | Verify a vote's signature and structure                                  |
+| `validate_vote_chain()`        | Ensure parent/received hash chains are correct                           |
+| `has_sufficient_votes()`       | Quick threshold check (count-based)                                      |
 | `calculate_consensus_result()` | Determine result from collected votes using threshold and liveness rules |
 
 ## Building

src/session.rs

@@ -264,6 +264,13 @@ impl ConsensusSession {
             }
         }
 
+        // Each distinct voter can vote at most once, so the batch size
+        // is bounded by expected_voters_count (u32). Reject early if violated.
+        if votes.len() > self.proposal.expected_voters_count as usize {
+            self.state = ConsensusState::Failed;
+            return Err(ConsensusError::MaxRoundsExceeded);
+        }
+
         validate_vote_chain(&votes)?;
         for vote in &votes {
             validate_vote(vote, expiration_timestamp, creation_time)?;
@@ -287,6 +294,12 @@ impl ConsensusSession {
     /// - For P2P: Calculates `(current_round - 1) + vote_count`.
     /// - For Gossipsub: Moves to Round 2 if `vote_count > 0`.
     fn check_round_limit(&mut self, vote_count: usize) -> Result<(), ConsensusError> {
+        // vote_count cannot exceed expected_voters_count (u32); reject if it does
+        if vote_count > self.proposal.expected_voters_count as usize {
+            self.state = ConsensusState::Failed;
+            return Err(ConsensusError::MaxRoundsExceeded);
+        }
+
         // Determine the value to compare against the limit based on configuration
         let projected_value = if self.config.use_gossipsub_rounds {
             // Gossipsub Logic:
@@ -303,6 +316,7 @@ impl ConsensusSession {
             // RFC Section 2.5.3: Round increments per vote.
             // Current existing votes = round - 1.
             // Projected total = Existing votes + New votes.
+            // vote_count is bounded by expected_voters_count (u32), safe to cast
             let current_votes = self.proposal.round.saturating_sub(1);
             current_votes.saturating_add(vote_count as u32)
         };
@@ -336,6 +350,7 @@ impl ConsensusSession {
         } else {
             // RFC Section 2.5.3: P2P
             // Round increments for every vote added.
+            // vote_count is bounded by expected_voters_count (u32), safe to cast
             self.proposal.round = self.proposal.round.saturating_add(vote_count as u32);
         }
     }
@@ -381,11 +396,13 @@ impl ConsensusSession {
 
 #[cfg(test)]
 mod tests {
+    use std::time::Duration;
+
     use alloy::signers::local::PrivateKeySigner;
 
     use crate::{
         error::ConsensusError,
-        session::{ConsensusConfig, ConsensusSession},
+        session::{ConsensusConfig, ConsensusSession, ConsensusState},
         types::CreateProposalRequest,
         utils::build_vote,
     };
@@ -489,4 +506,170 @@ mod tests {
         let err = session.add_vote(vote5).unwrap_err();
         assert!(matches!(err, ConsensusError::MaxRoundsExceeded));
     }
+
+    #[test]
+    fn consensus_config_builder_and_getters_cover_edges() {
+        let cfg = ConsensusConfig::gossipsub()
+            .with_threshold(0.75)
+            .unwrap()
+            .with_timeout(Duration::from_secs(42))
+            .unwrap()
+            .with_liveness_criteria(false);
+
+        assert_eq!(cfg.consensus_threshold(), 0.75);
+        assert_eq!(cfg.consensus_timeout(), Duration::from_secs(42));
+        assert!(!cfg.liveness_criteria());
+
+        let err = ConsensusConfig::gossipsub()
+            .with_threshold(1.1)
+            .unwrap_err();
+        assert!(matches!(err, ConsensusError::InvalidConsensusThreshold));
+
+        let err = ConsensusConfig::gossipsub()
+            .with_timeout(Duration::from_secs(0))
+            .unwrap_err();
+        assert!(matches!(err, ConsensusError::InvalidTimeout));
+
+        // Covers max_round_limit branch when P2P-like mode uses explicit max_rounds (non-zero).
+        let explicit = ConsensusConfig::new(2.0 / 3.0, Duration::from_secs(60), 7, false, true);
+        assert_eq!(explicit.max_round_limit(100), 7);
+    }
+
+    #[tokio::test]
+    async fn add_vote_rejects_non_active_and_reports_reached_when_finalized() {
+        let signer = PrivateKeySigner::random();
+        let request = CreateProposalRequest::new(
+            "Test".into(),
+            "".into(),
+            signer.address().as_slice().to_vec(),
+            3,
+            60,
+            true,
+        )
+        .unwrap();
+        let proposal = request.into_proposal().unwrap();
+
+        // Failed sessions reject new votes.
+        let mut failed_session =
+            ConsensusSession::new(proposal.clone(), ConsensusConfig::gossipsub());
+        failed_session.state = ConsensusState::Failed;
+        let vote = build_vote(&failed_session.proposal, true, signer.clone())
+            .await
+            .unwrap();
+        let err = failed_session.add_vote(vote).unwrap_err();
+        assert!(matches!(err, ConsensusError::SessionNotActive));
+
+        // Finalized sessions return existing transition/result.
+        let mut finalized_session = ConsensusSession::new(proposal, ConsensusConfig::gossipsub());
+        finalized_session.state = ConsensusState::ConsensusReached(true);
+        let vote = build_vote(&finalized_session.proposal, true, signer)
+            .await
+            .unwrap();
+        let transition = finalized_session.add_vote(vote).unwrap();
+        assert!(matches!(
+            transition,
+            crate::types::SessionTransition::ConsensusReached(true)
+        ));
+    }
+
+    #[tokio::test]
+    async fn initialize_with_votes_non_active_duplicate_and_zero_votes_paths() {
+        let signer = PrivateKeySigner::random();
+        let request = CreateProposalRequest::new(
+            "Test".into(),
+            "".into(),
+            signer.address().as_slice().to_vec(),
+            4,
+            60,
+            true,
+        )
+        .unwrap();
+        let proposal = request.into_proposal().unwrap();
+
+        // Non-active sessions reject initialization.
+        let mut inactive = ConsensusSession::new(proposal.clone(), ConsensusConfig::gossipsub());
+        inactive.state = ConsensusState::Failed;
+        let err = inactive
+            .initialize_with_votes(vec![], proposal.expiration_timestamp, proposal.timestamp)
+            .unwrap_err();
+        assert!(matches!(err, ConsensusError::SessionNotActive));
+
+        // Duplicate owners are rejected before chain/signature checks.
+        let mut dup_session = ConsensusSession::new(proposal.clone(), ConsensusConfig::gossipsub());
+        let vote1 = build_vote(&dup_session.proposal, true, signer.clone())
+            .await
+            .unwrap();
+        let vote2 = build_vote(&dup_session.proposal, false, signer)
+            .await
+            .unwrap();
+        let err = dup_session
+            .initialize_with_votes(
+                vec![vote1, vote2],
+                proposal.expiration_timestamp,
+                proposal.timestamp,
+            )
+            .unwrap_err();
+        assert!(matches!(err, ConsensusError::DuplicateVote));
+
+        // Explicitly exercise gossipsub projected round branch where vote_count == 0.
+        let mut zero_votes = ConsensusSession::new(proposal, ConsensusConfig::gossipsub());
+        zero_votes.check_round_limit(0).unwrap();
+    }
+
+    #[test]
+    fn p2p_round_limit_should_reject_effectively_huge_vote_count() {
+        if usize::BITS <= 32 {
+            return;
+        }
+
+        let signer = PrivateKeySigner::random();
+        let request = CreateProposalRequest::new(
+            "TruncationTest".into(),
+            vec![],
+            signer.address().as_slice().to_vec(),
+            1,
+            60,
+            true,
+        )
+        .unwrap();
+
+        let proposal = request.into_proposal().unwrap();
+        let mut session = ConsensusSession::new(proposal, ConsensusConfig::p2p());
+
+        let wrapped_vote_count = (u32::MAX as usize) + 1;
+
+        // Desired behavior: an effectively huge batch must be rejected by round-limit checks.
+        let result = session.check_round_limit(wrapped_vote_count);
+        assert!(
+            result.is_err(),
+            "effectively huge vote_count should not pass round-limit checks"
+        );
+    }
+
+    #[test]
+    fn p2p_update_round_should_advance_for_max_u32_vote_count() {
+        let signer = PrivateKeySigner::random();
+        let request = CreateProposalRequest::new(
+            "RoundUpdateMax".into(),
+            vec![],
+            signer.address().as_slice().to_vec(),
+            u32::MAX,
+            60,
+            true,
+        )
+        .unwrap();
+
+        let proposal = request.into_proposal().unwrap();
+        let mut session = ConsensusSession::new(proposal, ConsensusConfig::p2p());
+        let starting_round = session.proposal.round;
+
+        // vote_count at the u32 boundary should still advance the round via saturating_add
+        session.update_round(u32::MAX as usize);
+
+        assert!(
+            session.proposal.round > starting_round,
+            "round should advance when max u32 vote_count is applied"
+        );
+        assert_eq!(session.proposal.round, u32::MAX);
+    }
 }

src/types.rs

@@ -94,8 +94,37 @@ impl CreateProposalRequest {
             expected_voters_count: self.expected_voters_count,
             round: 1,
             timestamp: now,
-            expiration_timestamp: now + self.expiration_timestamp,
+            expiration_timestamp: now.saturating_add(self.expiration_timestamp),
             liveness_criteria_yes: self.liveness_criteria_yes,
         })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::CreateProposalRequest;
+
+    #[test]
+    fn into_proposal_should_not_overflow_expiration_timestamp() {
+        let request = CreateProposalRequest::new(
+            "overflow-check".to_string(),
+            vec![],
+            vec![1u8; 20],
+            1,
+            u64::MAX,
+            true,
+        )
+        .expect("request should be valid");
+
+        // Desired behavior: proposal creation should not panic on overflow-prone input,
+        // and expiration should never be earlier than creation timestamp.
+        let proposal = request
+            .into_proposal()
+            .expect("proposal creation should handle large expiration safely");
+
+        assert!(
+            proposal.expiration_timestamp >= proposal.timestamp,
+            "expiration must not overflow below creation timestamp"
+        );
+    }
+}

src/utils.rs

@@ -20,10 +20,18 @@ use crate::{
 
 const SIGNATURE_LENGTH: usize = 65;
 
+/// Fold a 128-bit value into 32 bits via XOR so every bit contributes.
+fn fold_u128_to_u32(n: u128) -> u32 {
+    ((n >> 96) as u32) ^ ((n >> 64) as u32) ^ ((n >> 32) as u32) ^ (n as u32)
+}
+
 /// Generate a unique 32-bit ID from a UUID.
+///
+/// Uses XOR folding so all 128 bits of the UUID contribute to the result,
+/// avoiding collisions from simple truncation.
 pub fn generate_id() -> u32 {
     let uuid = Uuid::new_v4();
-    uuid.as_u128() as u32
+    fold_u128_to_u32(uuid.as_u128())
 }
 
 /// Compute the hash of a vote for signing and validation.
@@ -377,3 +385,32 @@ pub fn has_sufficient_votes(
     let required_votes = calculate_required_votes(expected_voters, consensus_threshold);
     total_votes >= required_votes
 }
+
+#[cfg(test)]
+mod tests {
+    use uuid::Uuid;
+
+    use super::fold_u128_to_u32;
+
+    #[test]
+    fn id_generation_should_not_collapse_distinct_128bit_values() {
+        let low = 0xDEADBEEFu32;
+        let high_a = 0x00000001u128;
+        let high_b = 0xABCDEF01u128;
+
+        let value_a = (high_a << 32) | (low as u128);
+        let value_b = (high_b << 32) | (low as u128);
+
+        let uuid_a = Uuid::from_u128(value_a);
+        let uuid_b = Uuid::from_u128(value_b);
+
+        let id_a = fold_u128_to_u32(uuid_a.as_u128());
+        let id_b = fold_u128_to_u32(uuid_b.as_u128());
+
+        // Desired behavior: distinct 128-bit values should remain distinct after conversion.
+        assert_ne!(
+            id_a, id_b,
+            "distinct 128-bit values should not collapse to the same 32-bit id"
+        );
+    }
+}