docs: add repository description documents

.gitignore

@@ -3,3 +3,6 @@
 
 # ide
 .vscode
+
+# lint
+.protolint.yaml

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "hetu"
+name = "chronos"
 version = "0.1.0"
 edition = "2021"
 
@@ -9,10 +9,6 @@ members = [
     "crates/accumulator",
     "crates/vlc",
     "crates/cops",
-    "tools/replication-control",
-    "tools/replication-control-messages",
-    "tools/kademlia-control-messages",
-    "zchronod/zchronod",
     "demos/test_conflict",
     "demos/coll-tx",
     "demos/vlc-dag"
@@ -29,9 +25,7 @@ async-trait = "0.1.74"
 axum = "0.7.1"
 borsh = { version = "1.2.0", features = ["derive"] }
 ethnum = "1.5.0"
-kademlia-control-messages = { version = "0.1.0", path = "tools/kademlia-control-messages" }
 rand = "0.8.5"
-replication-control-messages = { version = "0.1.0", path = "tools/replication-control-messages" }
 secp256k1 = { version = "0.28.0", features = [
     "hashes",
     "rand",
@@ -41,6 +35,6 @@ tokio = { version = "1.33.0", features = ["full"] }
 tokio-util = "0.7.10"
 
 [lib]
-name = "test"
+name = "chronos"
 path = "src/lib.rs"
 

README.md

@@ -1,9 +1,41 @@
-# Hetu
+# Chronos
 
-This is the developing prototype of Hetu, a general-propose message-passing framework which consider causality as first class citizen.
+## Overview
 
-Project layout:
+The chronos is a novel logical clock system designed for open networks with Byzantine participants, offering improved fault tolerance and performance. It introduces a customizable validator abstraction and has been successfully applied to develop decentralized applications with minimal overhead.
 
-* `src/` the shared core definitions, including multiplex-enabled transport abstraction, Tokio-integration helpers, cryptography-related types, etc.
-* `docs/` high-level design documents
-* `tools/` scripts for testing and benchmarking
+This repository is the developing prototype of Hetu chronos, a general-propose message-passing framework which consider causality as first class citizen.
+
+## Layout & Toc
+
+Chronos organization layout is as follows:
+
+* `crates/` the common dependences and core functional crates.
+* `demos/` some use cases of applied the Chronos and proposals.
+* `docs/` design and applied documents for demonstrating thoughts.
+* `src/` the source codebase of shared definitions.
+
+## Building
+
+```sh
+git clone https://github.com/hetu-project/chronos.git
+
+cd chronos
+
+cargo build
+```
+
+## Contributing
+
+We welcome all contributions! There are many ways to contribute to the project, including but not limited to:
+
+- Cloning code repo and opening a [PR](https://github.com/hetu-project/chronos/pulls).
+- Submitting feature requests or [bugs](https://github.com/hetu-project/chronos/issues).
+- Improving our product or contribution [documentation](./docs/).
+- Contributing [use cases](./demos/) to a feature request.
+
+## Contact
+
+- [Open an Issue](https://github.com/hetu-project/chronos/issues)
+- [Hetu Protocol](https://github.com/hetu-project#hetu-key-research)
+- [Follow us on Twitter](https://x.com/hetu_protocol)

crates/README.md

@@ -0,0 +1,22 @@
+# Core Functional Crates
+
+The crates folder of Chronos includes core functional code crates and utility libraries, etc.
+
+## [vlc](./vlc/)
+
+- This verifiable logical clock crate implements a verifiable logical clock construct. 
+- The clock can be used in a peer-to-peer network to order events. 
+- Any node in the network can verify the correctness of the clock.
+
+## [accumulator](./accumulator/)
+
+- A simple accumulator application.
+- Each accumulator node maintains a set of strings. Upon receiving a string from a client, the node adds the string to its state, and broadcast the new state to other nodes in the network. 
+- All nodes eventually converge to the same state, by merging received states into their own states.
+
+## [cops](./cops/)
+
+- A causally consistent data store inspired by [COPS](https://www.cs.cmu.edu/~dga/papers/cops-sosp2011.pdf).
+- The data store maintains a set of key-value pairs. 
+- It provides causal consistency to clients.
+

demos/README.md

@@ -1,3 +1,34 @@
-## demos
+# Demos
 
 The demos folder of VLC includes code and document collections, including usage examples, design plans, integration, etc.
+
+## [VLC-Dag](./vlc-dag/)
+
+A vlc-dag application. The vlc-dag use case demo is base on the simple accumulator application. 
+
+Please reference on [crates/accumulator](../crates/accumulator/). But add new features as follow:
+
+* Defined the vertex and edge of the event & clock propagation dag.
+* Support the LMDB to persistence storage for now，
+* Maybe time-series db,like influxDB, or related postgre more suitable.
+* Support increment state sync with peers using p2p communication protocol.
+
+So we can use the vertex and edge from db to reconstruct clock propagation dag.
+
+## [Randomness](./Randomness/)
+
+This use case demo is mainly consist of two proposals.
+
+#### VLC & BLS Proposal
+Randomness serves a vital role in nearly every aspect of current society，the idea is to intergrate the ablility of logical clocks into random generator. To generate verifiable, fair random numbers, the proposal integrates BLS.
+
+#### VLC & VRF Proposal
+Randomness serves a vital role in nearly every aspect of current society，the idea is to intergrate the ablility of logical clocks into random generator. To generate verifiable, fair random numbers, the proposal integrates VRF.
+
+## [Test-Conflict](./test_conflict/)
+
+This use case domo is designed to detect software version conflict by applied vector clock.
+
+## [Coll-Tx](./coll-tx/)
+
+The coll-tx demo is about collecting simple utxo transaction with cops and vlc. 

docs/README.md

@@ -0,0 +1,8 @@
+# Document warehouse
+
+This document warehouse mainly consist of following parts:
+
+## Applied specification
+  - [vlc and application brief description](./applied/vlc%20and%20application%20brief%20description.md)
+## Design Documents 
+  - [Concurrent Stateful Apps with Sessions](./design/Concurrent%20Stateful%20Apps%20with%20Sessions.md)libraries

docs/applied/vlc and application brief description.md

@@ -0,0 +1,73 @@
+# vlc and application brief description
+
+# Prerequisites
+
+## **Lamport clock**
+
+The Lamport clock is a logical clock used to `order events` in a distributed system. It provides a way to capture the "`happens-before`" relationship between events, which is essential for understanding `causality`.
+
+<center><img src="../public/img/lamport-clock.png" alt="lamport" width="750" height="400"></center>
+
+### Examples
+
+Consider two processes, P1 and P2:
+
+- P1 starts with a clock value of 1, performs an event (clock becomes 2), and sends a message to P2 with the timestamp 2.
+- P2 receives the message with timestamp 2, and updates its clock to `max(current clock, 2) + 1` (e.g., if P2's current clock was 1, it becomes 3).
+
+### Conclusions
+
+- `Cannot capture concurrent events` (events that are not causally related).
+    - As shown in the above picture, `events a and b`
+- It constructs `fail to work` in an open network with `Byzantine participants`.
+
+## **Vector clock**
+
+Vector clocks are an `extension of Lamport clocks` that provide more detailed information about the causality of events. Each process `maintains a vector of clock values`, one for each process in the system.
+
+<center><img src="../public/img/vector-clock.png" alt="vector-clock" width="750" height="400"></center>
+
+### Examples
+
+Consider two processes, P1 and P2:
+
+- P1's vector clock is initially `[0, 0]`. It performs an event, updating to `[1, 0]`, and sends a message to P2.
+- P2's vector clock is `[0, 0]`. Upon receiving the message with vector clock `[1, 0]`, it updates to `[1, 1]` (assuming it performs an event after receiving).
+
+### Conclusions
+
+- It constructs `fail to work` in an open network with `Byzantine participants`.
+
+# VLC (Verifiable Logical Clock)
+
+Without reliable logical clocks, systems and applications `are forced to use expensive BFT SMR` protocols which `enforces total order` of requests, `even though` their application semantics may `only require partial ordering` guarantees.
+
+## Chrono overview
+
+So, vlc (verifiable logical clock) is construct atop on vector clock, and add the verifiable proof feature. The chrono is as a concrete instance of VLC. More detail could read the paper of [`Building a Verifiable Logical Clock for P2P Networks`](https://arxiv.org/pdf/2405.13349)
+
+<center><img src="../public/img/chronos-overview.png" alt="chronos-overview" width="750" height="400"></center>
+
+## Validator backends
+
+<center><img src="../public/img/chronos-validator-backends.png" alt="lamport" width="750" height="400"></center>
+
+# Applications & use cases
+
+Two use cases, `causally Consistent Data Store` and `mutual exclusion`, are introduced in detail in [paper](https://arxiv.org/pdf/2405.13349).
+
+## Regular logical clock use case
+
+Regular logical clock have been applied in many scenarios. As follows:
+
+- Weakly consistent storage systems
+    - `Cops: causally Consistent Data Store`
+- Causally ordered broadcast
+    - [Reference: vlc + p2p combined](https://github.com/NagaraTech/hetu-docs/blob/main/Zeb/vlc.md) 
+- Deadlock detection
+    - `Mutual exclusion` of shared resources in a distributed system
+    - Bakery algorithm
+- Distributed snapshots
+- Distributed system debugging.
+
+For sure, the verifiable logical clock is an enhanced version of a regular logical clock that can do everything a regular clock can do.