Merge pull request #92 from joaomlneto/pbft-reference

Add PBFT Reference Implementation, ByzzFuzz Scheduler, Parameterization via YML file

Author: joaomlneto

README.md

@@ -89,35 +89,38 @@ Reference: https://pnpm.io/installation
 
 For other operating systems, please refer to the respective installation instructions.
 
-## Building
+## Benchmark Suite
 
-To install dependencies and build the benchmarking suite, run the following commands:
-
-```
-./gradlew build
-(cd webui && pnpm install)
-```
-
-## Running
-
-To run the benchmarking suite, run the following command:
+To build and run the benchmarking suite, run the following command:
 
 ```
 ./gradlew bootRun
 ```
 
 ## Web Interface
 
-To run the web interface, run the following command:
+The web UI is a simple React application (using NextJS/TypeScript) that allows you to interact with the simulator. It is
+a work in progress, but provides useful insights into the behavior of the protocols.
+
+To build the web interface, run the following command **while the simulator is running**:
 
 ```
-(cd webui && pnpm run kubb:generate && pnpm run dev)
+(cd webui && pnpm install && pnpm run kubb:generate && pnpm run build)
 ```
 
 > [!NOTE]
 > The simulator must be running for `kubb:generate` to succeed.
 
-The UI should then be available at http://localhost:3000.
+The above command will generate the necessary TypeScript bindings for the simulator and build the web interface. You
+only need to run it once.
+
+Then, to start the web server, run the following command:
+
+```
+(cd webui && pnpm run start)
+```
+
+The UI should then be available at http://localhost:3000
 
 ## Running Benchmarks
 
@@ -126,12 +129,14 @@ We currently have the following protocols implemented:
 - ~~[PBFT](simulator/src/main/java/byzzbench/simulator/protocols/pbft/PbftReplica.java): The original PBFT protocol, as
   described in
   the [PBFT paper](https://www.microsoft.com/en-us/research/publication/practical-byzantine-fault-tolerance/);~~
-- [PBFT-Java](simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/PbftReplica.java): A buggy version of
-  PBFT,
-  from the [PBFT-Java repository](https://github.com/caojohnny/pbft-java);
+- [PBFT-Java](simulator/src/main/java/byzzbench/simulator/protocols/pbft_java/PbftReplica.java): A buggy implementation
+  of the PBFT protocol, ported from the [PBFT-Java repository](https://github.com/caojohnny/pbft-java);
 - [Fast-HotStuff](simulator/src/main/java/byzzbench/simulator/protocols/fasthotstuff/FastHotStuffReplica.java): An
   unsuccessful attempt at improving the design of HotStuff, as described in
   the [Fast-HotStuff paper](https://arxiv.org/abs/2010.11454);
+- [XRPL](simulator/src/main/java/byzzbench/simulator/protocols/xrpl/XRPLReplica.java): [XRP Ledger Consensus Protocol](https://xrpl.org/docs/concepts/consensus-protocol/consensus-research.html)
+  implementation;
+- *Your protocol here?* :-)
 
 ## Documentation
 

simulator/build.gradle.kts

@@ -34,6 +34,7 @@ dependencies {
     annotationProcessor("org.projectlombok:lombok")
     testImplementation("org.springframework.boot:spring-boot-starter-test")
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+    implementation("org.springframework.boot:spring-boot-starter-validation")
 
     //implementation("org.springdoc:springdoc-openapi-ui:1.8.0")
     // either API (just documentation) or API + UI (documentation + Swagger UI)

simulator/src/main/java/byzzbench/simulator/ApplicationContextUtils.java

@@ -0,0 +1,20 @@
+package byzzbench.simulator;
+
+import org.springframework.beans.BeansException;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+import org.springframework.stereotype.Component;
+
+@Component
+public class ApplicationContextUtils implements ApplicationContextAware {
+    private static ApplicationContext ctx;
+
+    public static ApplicationContext getApplicationContext() {
+        return ctx;
+    }
+
+    @Override
+    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
+        ctx = applicationContext;
+    }
+}

simulator/src/main/java/byzzbench/simulator/BaseScenario.java

@@ -1,7 +1,11 @@
 package byzzbench.simulator;
 
-import byzzbench.simulator.faults.HealNodeNetworkFault;
-import byzzbench.simulator.faults.IsolateProcessNetworkFault;
+import byzzbench.simulator.config.ByzzBenchConfig;
+import byzzbench.simulator.faults.Fault;
+import byzzbench.simulator.faults.FaultContext;
+import byzzbench.simulator.faults.factories.ByzzFuzzScenarioFaultFactory;
+import byzzbench.simulator.faults.faults.HealNodeNetworkFault;
+import byzzbench.simulator.faults.faults.IsolateProcessNetworkFault;
 import byzzbench.simulator.schedule.Schedule;
 import byzzbench.simulator.scheduler.Scheduler;
 import byzzbench.simulator.state.AgreementPredicate;
@@ -30,98 +34,103 @@ public abstract class BaseScenario implements Scenario {
      */
     @ToString.Exclude
     protected final transient Transport transport;
-
     /**
-     * The scheduler for the scenario.
+     * The timekeeper for the scenario.
      */
-    protected final Scheduler scheduler;
-
+    protected final transient Timekeeper timekeeper;
     /**
-     * Map of node id to the {@link Replica} object.
+     * The scheduler for the scenario.
      */
-    @Getter(onMethod_ = {@Synchronized})
-    @JsonIgnore
-    private final NavigableMap<String, Replica> nodes = new TreeMap<>();
-
+    protected final Scheduler scheduler;
     /**
-     * Map of client id to the {@link Client} object.
+     * Map of node id to the {@link Node} object.
      */
     @Getter(onMethod_ = {@Synchronized})
     @JsonIgnore
-    private final NavigableMap<String, Client> clients = new TreeMap<>();
-
+    private final NavigableMap<String, Node> nodes = new TreeMap<>();
     /**
      * A unique identifier for the scenario.
      */
     private final String id;
-
     /**
      * The invariants that must be satisfied by the scenario at all times.
      */
     private final List<ScenarioPredicate> invariants = List.of(new AgreementPredicate(), new LivenessPredicate());
-
     /**
      * The schedule of events in order of delivery.
      */
     @Getter(onMethod_ = {@Synchronized})
     @JsonIgnore
     private final Schedule schedule = Schedule.builder().scenario(this).build();
-
     /**
      * The observers of this scenario.
      */
     @JsonIgnore
     private final transient List<ScenarioObserver> observers = new java.util.ArrayList<>();
+    /**
+     * The termination condition for the scenario.
+     */
+    protected ScenarioPredicate terminationCondition;
+    /**
+     * Pseudo-random number generator for the scenario.
+     */
+    Random rand;
 
     /**
      * Creates a new scenario with the given unique identifier and scheduler.
      *
-     * @param id The unique identifier for the scenario.
+     * @param id        The unique identifier for the scenario.
      * @param scheduler The scheduler for the scenario.
      */
     protected BaseScenario(String id, Scheduler scheduler) {
         this.id = id;
         this.scheduler = scheduler;
         this.transport = new Transport(this);
+        this.timekeeper = new Timekeeper(this);
         this.setupScenario();
         this.addObserver(new AdobDistributedState());
     }
 
     /**
      * Adds an observer to the scenario.
+     *
      * @param observer The observer to add.
      */
     public void addObserver(ScenarioObserver observer) {
         this.observers.add(observer);
     }
 
     /**
-     * Removes an observer from the scenario.
-     * @param observer The observer to remove.
+     * Removes all registered clients
      */
-    public void removeObserver(ScenarioObserver observer) {
-        this.observers.remove(observer);
+    private void removeAllClients() {
+        this.nodes.entrySet().stream()
+                .filter(entry -> entry.getValue() instanceof Client)
+                .map(Map.Entry::getKey)
+                .forEach(this.nodes::remove);
     }
 
     /**
      * Sets the number of clients in the scenario.
+     *
      * @param numClients The number of clients to set.
      */
     protected void setNumClients(int numClients) {
-        this.clients.clear();
+        this.removeAllClients();
         for (int i = 0; i < numClients; i++) {
             String clientId = String.format("C%d", i);
-            Client client = Client.builder().clientId(clientId).transport(this.transport).build();
+            Client client = Client.builder().id(clientId).scenario(this).build();
             this.addClient(client);
         }
     }
 
     /**
      * Adds a client to the scenario.
+     *
      * @param client The client to add.
      */
     public void addClient(Client client) {
-        this.clients.put(client.getClientId(), client);
+        this.nodes.put(client.getId(), client);
         // notify the observers
         this.observers.forEach(o -> o.onClientAdded(client));
     }
@@ -133,19 +142,23 @@ public void addClient(Client client) {
      */
     public void addNode(Replica replica) {
         // add the node to the list of nodes
-        getNodes().put(replica.getNodeId(), replica);
+        getNodes().put(replica.getId(), replica);
 
         // for each node, add a IsolateNodeFault and a HealNodeFault
-        this.transport.addNetworkFault(new IsolateProcessNetworkFault(replica.getNodeId()));
-        this.transport.addNetworkFault(new HealNodeNetworkFault(replica.getNodeId()));
+        this.transport.addFault(new IsolateProcessNetworkFault(replica.getId()), false);
+        this.transport.addFault(new HealNodeNetworkFault(replica.getId()), false);
 
         // notify the observers
         this.observers.forEach(o -> o.onReplicaAdded(replica));
     }
 
     @Override
-    public synchronized Replica getNode(String replicaId) {
-        return this.getNodes().get(replicaId);
+    public synchronized Replica getNode(String nodeId) {
+        Node node = this.getNodes().get(nodeId);
+        if (!(node instanceof Replica replica)) {
+            throw new IllegalArgumentException("Node with ID " + nodeId + " is not a replica.");
+        }
+        return replica;
     }
 
     /**
@@ -154,8 +167,9 @@ public synchronized Replica getNode(String replicaId) {
     @Override
     public final void setupScenario() {
         this.setup();
-        getClients().values().forEach(Client::initializeClient);
-        getNodes().values().forEach(Replica::initialize);
+        this.getClients().values().forEach(Client::initialize);
+        this.getNodes().values().forEach(Node::initialize);
+        this.scheduler.initializeScenario(this);
     }
 
     public final void loadParameters(JsonNode parameters) {
@@ -170,11 +184,41 @@ public final void loadParameters(JsonNode parameters) {
             this.scheduler.loadParameters(schedulerParameters);
         }
 
+        if (parameters.has("faults")) {
+            System.out.println("Faults: " + parameters.get("faults").toPrettyString());
+            ByzzFuzzScenarioFaultFactory faultFactory = new ByzzFuzzScenarioFaultFactory();
+            List<Fault> faults = faultFactory.generateFaults(new FaultContext(this));
+            faults.forEach(fault -> this.transport.addFault(fault, true));
+        }
+
         this.loadScenarioParameters(parameters);
     }
 
+    public final void loadParameters(ByzzBenchConfig.ScenarioConfig config) {
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+        System.out.println("Loading parameters for scenario: " + config.getId());
+    }
+
     /**
      * Loads the parameters for the scenario from a JSON object.
+     *
      * @param parameters The JSON object containing the parameters for the scenario.
      */
     protected abstract void loadScenarioParameters(JsonNode parameters);
@@ -198,6 +242,7 @@ public final void runScenario() {
 
     /**
      * Checks if the invariants are satisfied by the scenario in its current state.
+     *
      * @return True if the invariants are satisfied, false otherwise.
      */
     @Override
@@ -207,15 +252,53 @@ public final boolean invariantsHold() {
 
     /**
      * Returns the invariants that are not satisfied by the scenario in its current state.
+     *
      * @return The invariants that are not satisfied by the scenario in its current state.
      */
     public final SortedSet<ScenarioPredicate> unsatisfiedInvariants() {
         return this.invariants.stream().filter(invariant -> !invariant.test(this))
                 .collect(Collectors.toCollection(TreeSet::new));
     }
 
+    @Override
+    public boolean isTerminated() {
+        return this.terminationCondition.test(this);
+    }
+
     public final void finalizeSchedule() {
         this.getSchedule().finalizeSchedule(this.unsatisfiedInvariants());
     }
 
+    public void writeToFile() {
+
+    }
+
+    @Override
+    public SortedSet<String> getNodeIds(Node node) {
+        return new TreeSet<>(this.getNodes().keySet());
+    }
+
+    @Override
+    public NavigableMap<String, Client> getClients() {
+        NavigableMap<String, Client> clients = new TreeMap<>();
+        this.getNodes()
+                .values()
+                .stream()
+                .filter(Client.class::isInstance)
+                .map(Client.class::cast)
+                .forEach(client -> clients.put(client.getId(), client));
+        return clients;
+    }
+
+    @Override
+    public NavigableMap<String, Replica> getReplicas() {
+        NavigableMap<String, Replica> replicas = new TreeMap<>();
+        this.getNodes()
+                .values()
+                .stream()
+                .filter(Replica.class::isInstance)
+                .map(Replica.class::cast)
+                .forEach(replica -> replicas.put(replica.getId(), replica));
+        return replicas;
+    }
 }