add docs on how to implement new protocols

Author: joaomlneto

README.md

@@ -7,13 +7,6 @@ This is a Gradle monorepo that contains the following modules:
 - `simulator`: The core benchmarking suite. Currently also includes the protocol implementations.
 - `webui`: A web interface for the benchmarking suite.
 
-```
-TODO restructure project later into the following modules:
-- `byzzbench-core`: The core benchmarking suite
-- `byzzbench-webui`: A web interface for the benchmarking suite
-- `byzzbench-protocols`: Implementations of various BFT protocols
-```
-
 ## Prerequisites
 
 For the benchmarking suite to work, you need to have the following installed on your system:
@@ -57,6 +50,10 @@ To run the web interface, run the following command:
 
 The UI should then be available at http://localhost:3000.
 
+## Documentation
+
+- [Implementing new BFT Protocols](docs/implementing-protocols.md)
+
 ## Simulator Structure
 
 ```mermaid

docs/implementing-protocols.md

@@ -0,0 +1,31 @@
+# Implementing new BFT Protocols
+
+This document describes the steps to implement a new BFT protocol in ByzzBench.
+
+A BFT Protocol implementation in ByzzBench consists of the following components:
+
+- A protocol replica that *extends* `Replica<T>`: these are the nodes that run the protocol and communicate with each other
+  via messages. `T` is the type of each of the entries in the commit log (this should be simplified!).
+  - Example: [PBFT-Java Replica](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/PbftReplica.java)
+  - The `Replica` constructor requires a `replicaId`, `nodeIds` (set of all replica IDs in the *cluster*), `transport` (the virtualized network instance) and a `commitLog` (instance where all committed operations from the replica are sent to).
+- A set of protocol message POJOs that *implement* `MessagePayload`: these are the messages that are exchanged between replicas.
+  - They just need to have a `String getType()` method that returns e.g. that it is a `PREPARE` message.
+  - Examples from PBFT-Java: [Checkpoint](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/CheckpointMessage.java), [Commit](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/CommitMessage.java), [NewView](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/NewViewMessage.java), [Phase](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/PhaseMessage.java), [Prepare](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/PrepareMessage.java), [PrePrepare](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/PrePrepareMessage.java), [Reply](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/ReplyMessage.java), [Request](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/RequestMessage.java), [ViewChange](../simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/message/ViewChangeMessage.java)
+
+## Communication and Timeouts
+
+Communication between replicas is done via message-passing through the `Transport`. The `Replica` superclass exposes a few methods:
+
+- `sendMessage`: send a message to a recipient
+- `multicastMessage`: send a message to a set of replicas
+- `broadcastMessage`: send a message to every other replica
+- `broadcastMessageIncludingSelf`: send a message to every replica, including self
+
+Timeouts are implemented via callbacks to a `Runnable`, also handled by the `Transport`:
+
+- `setTimeout(Runnable, timeout)`: Creates a timeout event of `timeout` milliseconds, which will then invoke the `Runnable`. The time is currently being ignored, and is instead triggered just like any other event by the scheduler.
+- `clearAllTimeouts()`: Invalidates all outstanding timeouts for the current replica.
+
+## Commit Log
+
+Each replica has its own instance of a `CommitLog`: an immutable and total ordered sequence of records. This is used to check whether safety invariants of distributed consensus are broken.