Welcome to Coracle, a consensus algorithm simulator for heterogeneous networks.

An install script can be found in scripts/install.sh. The general process is as follows:

Start off by installing OPAM/OCaml, here's some helpful links:

• https://opam.ocaml.org/doc/Install.html
• https://github.com/realworldocaml/book/wiki/Installation-Instructions

Using OPAM we can get the project dependencies:

opam update
opam upgrade
opam install cstruct ipaddr lwt sexplib cmdline yojson

And then compile from source as follows:

git clone https://github.com/heidi-ann/coracle
cd coracle

ocaml setup.ml -configure
ocaml setup.ml -build
ocaml setup.ml -install

Now to setup the node web server:

brew install npm
npm install express serve-favicon morgan cookie-parser node-uuid debug jade serve-index moment
cd coracle/web
mkdir requests
PORT=3000 node ./bin/www

Replacing brew with your package manager of course. Setting up supervisor can allow the server to auto update when files change.

An update script can be found in scripts/update.sh.

We currently support two interfaces: command line implementation and simulation.

Run an consensus algorithm as follows:

./coracle_unix.byte 1 --max=5

This instance will bind locally to port 5001 (5000+id) and will try to communicate with other instances at ports 5000 to 5004 (5000 to 5000+max-1).

Ran a simulation as follows:

./coracle_sim.byte -n 5

This will ran a simualator with 5 nodes.

Please send any comments, questions or bugs to GitHub issue tracker:

https://github.com/consensus-oracle/coracle/issues

This code is released under the MIT License, see the LICENSE file for full details.

Coracle clipart courtesy of FCIT for non-commercial use only

This project is in the early development stages and we plan to have the first prototype release ready for SIGCOMM '15 on 17th Aug 2015. Contributions are welcome, these are best make via pull requests and using Github issues to mark that your working on a particular issues or features.

The current codebase is structured as follows:

• lib/ - common functionality used by all consensus implementations
  • common.ml(i) - simple useful functions for use throughout
  • io.ml(i) - type definitions for protocol and frontend interface
  • numbergen.ml(i) - generator for random numbers within a given distribution
  • protocol.ml(i) - module sig for general consensus algorithms
• raft/ - pure raft consensus implementation
  • election.ml(i) - raft election code
  • election_io.ml(i) - raft election interface, packets and timeouts
  • event.ml(i) - main eval loop for raft protocol
  • raft.ml(i) - wrapping raft consensus ready for the CONSENSUS sig
  • rpcs.ml(i) - raft RPC representations as records plus serialize/deserialize
  • state.ml(i) - raft internal state and operators
• unix/ - unix frontend for consensus protocols
  • client.ml(i) - empty
  • coracle_unix.ml(i) - parsing command line arguments for unix interface
  • id.ml(i) - handling node ID's
  • io_handlers.ml(i) - main body of unix interface
• sim/ - simulation frontend for coracle
  • coracle_sim.ml(i) - parsing command line arguments for simulation interface
  • events.ml(i) - handling events and their applications
  • parameters.ml(i) - type sig for simulation parameters
  • simulator.ml(i) - simulators main loop
  • states.ml(i) - handling multiple node state
• scripts/ deployment scripts for demo server
  • install.sh - script to install coracle on demo server
  • update.sh - script to pull code/library updates
• sample_config.json - sample coracle_sim configuration in JSON
• _oasis - configuration file for the OASIS build system
• _tags, myocamlbuild.ml, setup.ml - files auto generated by OASIS, included so that OASIS is not a project dependency
• META, *.mlylib, *.mllib, *.mlpack - files auto generated by OASIS during packing

• Simple prototype JS frontend
  • user selectes between raft and vrr, number of nodes, number of secs to simulate and main timeout parameter
  • intermediate service runs OCaml simulator process with parameters expressed in JSON
  • OCaml simulator process terminates returning simulation stats in JSON
  • stats are displayed to the user
• Abstract over Consensus algorithms
• Parsing simulation config in JSON
• Terminating simulation at specified time
• Server side parameter validation of configurations from JSON
• Client side parameter validation of configurations from JSON
• Advanced setting section for each protocol, hidden by default
• Random seed field, default is randomly generated by JS but value can be changed
• Setup coracle on demo on Azure

This week focuses on supporting clients and VRR.

• Remove redundency in parsing logic between the JSON and command line interfaces
• Adding protocol specific parameters

• Support AppendEntries

• Implement basic VRR (assuming access to persistent storage)

• Allow random seed to be set by JSON/command line interface

• Adding tabs (or similar) to make more space on the page e.g. seperate 'parmeters' and 'results' tabs and seperate 'general', 'raft' and 'vrr' tabs within the 'parameters page'
• Change JSON file naming from UUID to date,time,seed

• Add web demo setup instruction to Readme
• add web/ and other file change to file overview in Readme

This week focuses on supporting inputting heterozygous networks and supporting clients.

• Support for simulated node failure
• Adding support for client and client based events

• Support Client Interation

• Ability to store and query hetrozengous networks, later labelled with parameters like node failure rates, link direction, link latency, probability of packet loss, bandwidth etc..
• Support for simulating clients
• Support for basic client workload

• Allow the user to select between a set of sample network topologies
• Allow the user to draw static network topologies and label it
• Basic client support
  • parameter to set number of clients
  • parameter to set regularly of client requires

This week focuses on presenting simulation results.

• Return results as graphs instead of just a table of stats

This week focuses on getting demo ready.

• Try using mutable event queue

• Support for Read-only Comamnds
• Configurable hearbeat interval and heartbeat timer

• Allow simulated/random/uniform client workloads

• Provide some specific example workloads
• Allow the user to run multi simulations at once

• Adding Travis-CI support
• Choose and implement a logging solution throughout code base, syslog compatible
• add coracle to OPAM
• add copyright/license notice to each file header
• add ocaml 4.02.2 support (fix inconsistent interface error)
• Register coracle domain
• Test demo server and possiblity add use multiple machines/processes for load balancing

• Support for other consensus protocols such as original Paxos, Zab or EPaxos
• Dynamic membership implementation for Raft and VRR plus abiliy to test in simulation
• MirageOS frontend
• Complete JS implementation using js_of_ocaml
• Support for non-ocaml consensus protocols
• Support for simulating dynamic network topologies
• Split this code into 3 or 4 seperate repositories
• Unix frontend
  • Decople server id and port/host address
  • Support for config files, with a subset of logcabin's options.
  • Support for state machines as a seperate process (or even on an separate host), comms via sockets/pipes/ other IPCs
  • Proper client side executable with suuport for an application as a separate process
  • Really support for persistent storage, with write-ahead logging
  • Add a download configuration option, which provides the current configuration as a JSON file and reference to github issue tracker.
  • Add a reset button to reset feilds to original values
• method to generate a random workload and then reuse it for other simulations
• Allow multiple simulation configuration per run, so instead of one Raft configuration and one VRR configuration, the user can upto 5 configurations. This could be used to run