feat: add the implementation of hvlc (hybrid vector logical clock)

Author: ai-chen2050

Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "crates/accumulator",
     "crates/vlc",
     "crates/hlc",
+    "crates/hvlc",
     "crates/cops",
     "crates/vrf",
     "crates/crypto",
@@ -19,7 +20,7 @@ members = [
     "demos/coll_tx",
     "demos/vlc_dag",
     "demos/tee_vlc",
-    "demos/test_vlc_net", 
+    "demos/test_vlc_net",
 ]
 
 [profile.dev]

crates/README.md

@@ -15,6 +15,17 @@ The crates folder of Chronos includes core functional code crates and utility li
 - Each timestamp consists of a wall-clock time and a logical component, allowing for easy comparison and conflict resolution.
 - This crate is an implementation of the [Hybrid Logical Clock](http://www.cse.buffalo.edu/tech-reports/2014-04.pdf).
 
+## [hvlc](./hvlc/)
+
+- This Hybrid Vector Logical Clock (HVLC) crate implements a hybrid vector clock structure that combines physical timestamps with vector clock properties.
+- HVLC uses a BTreeMap to store logical clock values for multiple nodes while maintaining a physical timestamp, enabling efficient tracking of causality and concurrent events in distributed systems.
+- Each clock instance contains:
+  - A mapping table (inner) that records logical clock values for each node ID
+  - A physical timestamp used to provide total ordering when logical clock comparison is insufficient
+- The implementation provides core functionalities like event ordering, clock merging, and base calculation, suitable for scenarios requiring distributed causality tracking.
+- Compared to regular vector clocks, HVLC offers better total ordering support through physical timestamps while maintaining the causal consistency properties of vector clocks. 
+- It can be used to as the [CRDTs](https://crdt.tech/)(Conflict-free Replicated Data Type) algorithm in distributed scenarios for providing total ordering.
+
 ## [accumulator](./accumulator/)
 
 - A simple accumulator application.

crates/hlc/src/lib.rs

@@ -84,6 +84,26 @@ pub struct State<F> {
     now: F,
 }
 
+impl<F: FnMut() -> SystemTime> PartialEq for State<F> {
+    fn eq(&self, other: &Self) -> bool {
+        self.s == other.s
+    }
+}
+
+impl<F: FnMut() -> SystemTime> Eq for State<F> {}
+
+impl<F: FnMut() -> SystemTime> PartialOrd for State<F> {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        self.s.partial_cmp(&other.s)
+    }
+}
+
+impl<F: FnMut() -> SystemTime> Ord for State<F> {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        self.s.cmp(&other.s)
+    }
+}
+
 impl State<()> {
     // Creates a standard hybrid logical clock, using `std::time::SystemTime` as
     // supplier of the physical clock's wall time.
@@ -164,6 +184,15 @@ mod tests {
         HLTimespec::new(s, ns, l)
     }
 
+    #[test]
+    fn hlts_comparing() {
+        let mut hlc = State::new();
+        let hlc_1 = hlc.get_time();
+        let hlc_2 = hlc.get_time();
+        println!("hlc1 {:?}, \nhlc2 {:?}", hlc_1, hlc_2);
+        assert!(hlc_1 < hlc_2);
+    }
+
     #[test]
     fn it_works() {
         // Start with a reference time for tests

crates/hvlc/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "hvlc"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+sha2 = "0.10.8"
+sha3 = "0.10.1"
+rand = "0.8.5"
+rand_distr = "0.4.3"
+bincode = "1.3.3"
+hex = "0.4.3"
+tracing = "0.1.40"
+futures = "0.3.30"
+num_cpus = "1.13.1"
+derive_more = "0.99.17"
+derive-where = "1.2.7"
+serde = { version = "1", features = ["derive"] }
+anyhow = { version = "1.0.79", features = ["backtrace"] }
+tracing-subscriber = "0.3.18"
+secp256k1 = { version = "0.29.0", features = ["rand-std", "serde", "recovery"] }
+tokio = { version = "1.35.1", features = [
+    "net",
+    "time",
+    "sync",
+    "rt",
+    "signal",
+    "macros",
+    "rt-multi-thread",
+    "fs",
+    "process",
+    "io-util",
+] }
+tokio-util = "0.7.10"
+crypto = { path = "../crypto", version = "0.1.0" }