Merge pull request #23 from movementlabsxyz/feat/improve-doc

[protocols] more helpful overview files

Author: apenzk

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "stm32-for-vscode.openOCDPath": false,
+    "stm32-for-vscode.armToolchainPath": false,
+    "spellright.userDictionary": "${workspaceFolder}/.vscode/spellright.dict"
+}

.vscode/spellright.dict

@@ -0,0 +1,3 @@
+Fastconfirmation
+testnet
+unstaking

protocol/README.md

@@ -1,8 +1,34 @@
 # `protocol-units`
-`protocol-units` are used to collect runnable and composable units for interacting with the `ffs` protocol. We store contracts within protocol units, for example. 
+
+`protocol-units` are used to collect runnable and composable units for interacting with the `ffs` protocol. We store contracts within protocol units, for example.
 
 ## Contents
-- **[`mcr`](./mcr/)**: the `MCR` implementation of `ffs` provided prior to the specification of the `fast-confirmations` and `post-confirmations` protocols. It is maintained for legacy purposes.
-- **[`pcp`](./pcp/)**: the Postconfirmations sub-protocol implementation for `ffs`. 
-- **[`fcp`](./fast-confirmations/)**: the fastconfirmations sub-protocol implementation for `ffs`.
-- **[`ffs`](./ffs/)**: the full `ffs` protocol implementation.
+
+- **[`mcr`](./mcr/README.md)**: the `MCR` sub-protocol implementation of `ffs` provided prior to the specification of the `fast-confirmations` and `post-confirmations` protocols. It is maintained for legacy purposes.
+- **[`pcp`](./pcp/README.md)**: the Postconfirmation sub-protocol implementation for `ffs`.
+- **[`fcp`](./fcp/README.md)**: the Fastconfirmation sub-protocol implementation for `ffs`.
+- **[`ffs`](./ffs/README.md)**: the full `ffs` protocol implementation.
+
+## Architecture for each protocol unit
+
+- `cli/` - Command line interface tools
+  - `client/` - CLI tool for users to interact with the protocol (posting commitments, querying state)
+  - `deployer/` - CLI tool for deploying the protocol contracts
+  - `protocol/` - CLI tool for protocol-specific operations
+
+- `clients/` - Protocol client implementations
+  - `eth/` - Ethereum client implementation that handles blockchain interactions
+  - `mock/` - Mock client for testing
+  - `util/` - Shared utilities for clients
+
+- `dlu/` - Deployment and Lifecycle Utilities
+  - `eth/` - Ethereum-specific deployment tools
+    - `contracts/` - Smart contract implementations. Includes settlement contracts for block commitments, staking contracts for validator management, token contracts for custody.
+    - `deployer-core/` - Core deployment logic
+    - `anvil/` - Local testnet configuration
+
+- `manager/` - Protocol management and orchestration. Manages block commitments by batching and submitting them, interacts with clients, and processes commitment events (acceptance or rejection) for the settlement system.
+
+- [`util/`](util/) - Shared utilities
+  - `config/` - Configuration management
+  - `types/` - Common type definitions

protocol/mcr/README.md

@@ -1,15 +1,11 @@
-# MCR - Multi-Commit Rollup
+# MCR (Multi Commit Rollup)
 
-**MCR** implements a staking-based settlement where validators commit L2-blocks on Layer 1 (L1). 
+This directory contains the implementation of the MCR protocol, which handles rollup commitment aggregation.
 
-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.
+## Overview
 
-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).
+**MCR** implements a staking-based settlement where validators commit to a state from L2 on Layer 1 (L1). MCR accepts commitments from all staked attesters and aggregates them into a single confirmation. The contracts on L1 tracks block commitments, epochs, stake and rewards.
 
-## Architecture
+The distinguishing feature to PCP is that there is only one type of actor, which is the attester.
 
-- [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.
+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).

protocol/mcr/dlu/README.md

@@ -1,4 +1,5 @@
 # Deployed Logic Units (DLU)
-DLUs are units of logic that are not generally run within an independent process, but which must be deployed somewhere. Smart contracts are DLU. 
 
-In this directory, we include DLU and the means via which to deploy them to various environments.
+DLUs are units of logic that are not generally run within an independent process, but which must be deployed somewhere. Smart contracts are DLU.
+
+In this directory, we include DLU and the means via which to deploy them to various environments.

protocol/pcp/README.md

@@ -0,0 +1,11 @@
+# PCP (Postconfirmation Protocol)
+
+This directory contains the implementation of the PCP protocol, which handles commitment settlement through postconfirmation.
+
+## Overview
+
+**PCP** implements a staking-based settlement where validators commit to a state from L2 on Layer 1 (L1). PCP accepts commitments from all staked attesters. A specialized attester - the acceptor - aggregates them into a single confirmation, called a postconfirmation. The contracts on L1 tracks block commitments, epochs, stake and rewards.
+
+The distinguishing feature to MCR is that there are two types of actors, which are the attesters and the acceptors.
+
+For further details see the [MIP-37](https://github.com/movementlabsxyz/MIP/blob/main/MIP/mip-37).

sdk/README.md

@@ -1,2 +1,10 @@
 # `sdk`
-The FFS SDK is a set of tools for building FFS services. It is generally the entrypoint for researching and building with FFS. 
+
+The FFS SDK is a set of tools for building FFS services. It is generally the entry point for researching and building with FFS.
+
+## Contents
+
+- **[`cli`](./cli/README.md)**: the SDK cli suite.
+  - **[`ffs`](./cli/ffs/README.md)**: the main FFS command line tool.
+  - **[`ffs-client`](./cli/ffs-client/README.md)**: a client for interacting with FFS.
+  - **[`ffs-dev`](./cli/ffs-dev/README.md)**: a development tool for FFS.

sdk/cli/ffs-client/README.md

@@ -1,2 +1,8 @@
 # `ffs-client`
-The command line tool for interacting with live FFS services.
+
+The command line tool for interacting with live FFS services.
+
+The `ffs-client` relies on the implementation of the following components in each of the sub-protocols in the `[protocol/](../protocol/README.md)` directory:
+
+- `cli/client/` - Command line interface tools for interacting with the protocol
+- `clients/eth/` - Ethereum client implementation that handles blockchain interactions

sdk/cli/ffs-dev/README.md

@@ -1,2 +1,3 @@
 # `ffs-dev`
-The FFS command line tool for those working on active development, typically combines the most FFS command line tools. 
+
+The FFS command line tool for those working on active development, typically combines the most FFS command line tools.

sdk/cli/ffs/README.md

@@ -1,2 +1,3 @@
 # `ffs`
-The main FFS command line tool. This is under specification and development.
+
+The main FFS command line tool.