docs: update READMEs (#685)

Co-authored-by: Mikhail Zabaluev <[email protected]>

Author: 2 people

protocol-units/README.md

@@ -7,5 +7,5 @@ We identify the following protocol unit categories:
 - [Cryptography](./cryptography): Protocol units concerned with cryptographic operations. Cryptography and data structure-related utilities are members of this category.
 - [Execution](./execution): Protocol units concerned with execution. Block executors and related unities are members of this category.
 - [Movement REST service](./movement-rest): Protocol units to support Movement's REST API. `movement-rest` provides additional Movement REST API endpoints. 
-- [Settlement](./settlement): Protocol units concerned with settlement. Movement's multi-commitment rollup and related settlement utilities are members of this category. 
+- [Settlement](./settlement/README.md): Protocol units concerned with settlement, such as Movement's Multi-Commitment Rollup (MCR).
 - [Storage](./storage): Protocol units concerned with storage. `jelly-move`, `move-access-log`, and `mpt-move` are members of this category.

protocol-units/sequencing/README.md

@@ -0,0 +1,3 @@
+ `sequencing`
+
+- [Mempool Sequencer](./memseq/sequencer/README.md): Basic sequencer that orders transactions from a mempool into blocks.

protocol-units/sequencing/memseq/sequencer/README.md

@@ -0,0 +1,5 @@
+`Mempool Sequencer`
+
+The `Memseq` module is responsible for managing a mempool and sequencing transactions into blocks. 
+
+It is intended for use of a centralized sequencer node that manages a mempool.

protocol-units/sequencing/memseq/sequencer/src/lib.rs

@@ -14,6 +14,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
+/// The `Memseq` module is responsible for managing a mempool and sequencing transactions into blocks.
 #[derive(Clone)]
 pub struct Memseq<T: MempoolTransactionOperations> {
 	/// The mempool to get transactions from.
@@ -67,6 +68,7 @@ impl<T: MempoolTransactionOperations> Memseq<T> {
 }
 
 impl Memseq<RocksdbMempool> {
+	/// Attempts to create a new Memseq instance with a RocksDB mempool, given a path, block size, and building time.
 	pub fn try_move_rocks(
 		path: PathBuf,
 		block_size: u32,
@@ -95,6 +97,7 @@ impl<T: MempoolTransactionOperations> Sequencer for Memseq<T> {
 		Ok(())
 	}
 
+	/// Waits for the next block to be built, either when the block size is reached or the building time expires.
 	async fn wait_for_next_block(&self) -> Result<Option<Block>, anyhow::Error> {
 		let mut transactions = Vec::with_capacity(self.block_size as usize);
 
@@ -154,6 +157,7 @@ pub mod test {
 	use mempool_util::MempoolTransaction;
 	use tempfile::tempdir;
 
+	/// Tests that the block is built when the building time expires, even if the block size is not reached.
 	#[tokio::test]
 	async fn test_wait_for_next_block_building_time_expires() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -179,6 +183,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests error propagation when publishing transactions to the mempool.
 	#[tokio::test]
 	async fn test_publish_error_propagation() -> Result<(), anyhow::Error> {
 		let mempool = MockMempool;
@@ -197,6 +202,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests concurrent access to the Memseq instance using spawned tasks.
 	#[tokio::test]
 	async fn test_concurrent_access_spawn() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -221,6 +227,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests concurrent access to the Memseq instance using futures.
 	#[tokio::test]
 	async fn test_concurrent_access_futures() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -247,6 +254,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests the creation of a Memseq instance with a RocksDB mempool and verifies the block size and building time.
 	#[tokio::test]
 	async fn test_try_move_rocks() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -264,6 +272,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests the initialization of the Memseq instance and verifies its fields.
 	#[tokio::test]
 	async fn test_memseq_initialization() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -285,6 +294,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests the with_block_size and with_building_time_ms methods.
 	#[tokio::test]
 	async fn test_memseq_with_methods() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -312,6 +322,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests that no block is built when there are no transactions in the mempool.
 	#[tokio::test]
 	async fn test_wait_for_next_block_no_transactions() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -326,6 +337,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests the basic functionality of the Memseq instance, including publishing transactions and waiting for the next block.
 	#[tokio::test]
 	async fn test_memseq() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -347,6 +359,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests that the Memseq instance respects the block size limit when building blocks.
 	#[tokio::test]
 	async fn test_respects_size() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;
@@ -380,6 +393,7 @@ pub mod test {
 		Ok(())
 	}
 
+	/// Tests that the Memseq instance respects the building time limit when waiting for the next block.
 	#[tokio::test]
 	async fn test_wait_next_block_respects_time() -> Result<(), anyhow::Error> {
 		let dir = tempdir()?;

protocol-units/settlement/README.md

@@ -0,0 +1,3 @@
+# `settlement`
+
+- [MCR](./mcr/README.md) : Multi-Commitment Rollup (MCR) settlement. 

protocol-units/settlement/mcr/README.md

@@ -0,0 +1,15 @@
+# MCR - Multi-Commit Rollup
+
+**MCR** implements a staking-based settlement where validators commit L2-blocks on Layer 1 (L1). 
+
+Validators stake tokens to participate in block validation. They commit to L2-blocks on L1, and the contract on L1 tracks block commitments, epochs, and stake. The contracts also manage validators and custodian staking and unstaking. The contract validates if commitments have reached two-thirds supermajority stake, and rewards or slashes validators based on their actions.
+
+For further details see the [RFC for MCR](https://github.com/movementlabsxyz/rfcs/pull/29) and the [MIP-34](https://github.com/movementlabsxyz/MIP/blob/main/MIP/mip-34).
+
+## Architecture
+
+- [Contracts](./contracts/README.md): Includes settlement contracts for block commitments, staking contracts for validator management, token contracts for custody.
+- **Manager**: Manages block commitments by batching and submitting them, interacts with clients, and processes commitment events (acceptance or rejection) for the settlement system.
+- **Setup**: Prepares local environments or deploys contracts, manages configuration for local and deployment setups, and ensures contract deployment when needed.
+- **Runner**: Orchestrates the setup and execution of configuration tasks, applies setup steps, and logs processes for debugging.
+- **Client**: Handles interaction with the MCR system by posting block commitments, streaming commitment data, and managing Ethereum blockchain interactions.

protocol-units/settlement/mcr/contracts/README.md

@@ -1,5 +1,4 @@
-# MRC
-- **RFC**: [RFC MCR](https://github.com/movementlabsxyz/rfcs/pulls)
+# MCR - L1 contract
 
 This directory contains the implementation of the MRC settlement smart contract. To test the contract, run:
 
@@ -16,14 +15,19 @@ For a given block height, MCR selects the earliest block commitment that matches
 2. Tracking commitments for each block height until one exceeds the supermajority of stake.
 
 ## Proof of Correctness
+
+> To proof: For a given block height, MCR selects the earliest block commitment that matches the supermajority of stake-
+
 The stake is fixed for an epoch, so only commitments for a specific block height are considered, allowing for a straightforward proof.
 
-Let $C$ represent all possible commitments, and $C'$ be an ordered subset of $C$. MCR returns $c_i \in C'$, the earliest commitment matching the supermajority of stake, defined as:
+**Commitment**. Let $v: C \to V$ map a commitment to its validator, where $C$ represent all possible commitments and $V$ is the set of validators. Since commitments are ordered by L1 in the L1-blocks, let $C'$ be an ordered subset of $C$ with $k$ elements (i.e. up to the $k$-th commitment). 
+
+**Stake**. Let $s: V \to \mathbb{N}$ map a validator to their stake and $S(C',i) = \sum_{j = 1}^{i} s(v(c_j))$ the cumulative stake up to the $i$-th commitment. $S$ is non-decreasing as $S(C',i) = S(C',i - 1) + s(v(c_i))$.
+
+We require that 
 
 $$
-\delta(C') = \frac{2}{3} \times \sum_{c \in C'} s(v(c)),
+S(C',i) > \frac{2}{3} TotalStake = \frac{2}{3} \times \sum_{u \in V} s(u),
 $$
 
-where $v: C \to V$ maps a commitment to its validator and $s: V \to \mathbb{N}$ maps a validator to their stake. Define $\sigma'(C', i) = \sum_{j = 0}^{i} s(v(c_j))$, the cumulative stake up to the $i$-th commitment. $\sigma'$ is non-decreasing as $\sigma(C', i) = \sigma(C', i - 1) + s(v(c_i))$.
-
-If $\sigma(C', i) \geq \delta(C')$, then $c_i$ is the earliest commitment where the supermajority is met, since any earlier commitment $c_j$ for $j < i$ would violate the non-decreasing nature of $\sigma'$.
+If $S(C', i)$ satisfies the condition, and $S(C',i-1)$ does not, then $c_i$ is returned by MCR. Due to the non-decreasing nature of $S$ with $i$, $c_i$ is the earliest commitment that can be returned.