From cc0c7a5bbb5f802ee01e6be777280c6e7304ad78 Mon Sep 17 00:00:00 2001 From: Mark Rushakoff Date: Thu, 24 Oct 2024 14:08:28 -0400 Subject: [PATCH] docs: rewrite README --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d38e2e6..99bf520 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,68 @@ Gordian is a modular, [Byzantine-fault-tolerant](https://en.wikipedia.org/wiki/B A consensus engine is a [replicated state machine](https://en.wikipedia.org/wiki/State_machine_replication) -- a participant in a distributed system where the participants agree on initial state, actions to apply, and resulting state. -Almost anything that a chain developer would need to tune is able to be modified in Gordian: +Gordian allows each participant to have a different voting power. +This effectively enables Gordian to be the consensus layer in a [proof of stake](https://en.wikipedia.org/wiki/Proof_of_stake) system. -- storage layer -- p2p networking and gossiping -- hashing algorithms -- cryptographic key types and how signatures are calculated +Because Gordian uses an implementation of [the Tendermint® consensus algorithm](https://arxiv.org/abs/1807.04938)[^1], +systems backed by Gordian can tolerate failure or malicious behavior from participants constituting +up to, but less than, 1/3 of the total voting power. + +## Who should use Gordian? + +Gordian was primarily written to support blockchain use cases, +but it should fit in any distributed system requiring peers to agree on state. + +## How do I use Gordian? + +Gordian is a modular system written in [Go](https://go.dev/). + +The Gordian core Engine is designed to accept messages from the network +and replay a filtered set of those messages to a state machine. +The state machine consults a user-provided "driver" to track state changes +and determine what data to propose to other network participants. + +The core Gordian repository (the one you are looking at now) does **not** provide a Driver. +See [https://github.com/gordian-engine/gcosmos](gcosmos) for an example Driver integrating with the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk). + +Outside of the driver, Gordian currently provides a networking layer using [libp2p](https://libp2p.io/), +a storage layer using [SQLite](https://www.sqlite.org/), +Ed25519 signing keys for validators, +and some simple hashing schemes using [BLAKE2b](https://www.blake2.net/). + +We have carefully designed the internal APIs to make it as easy as possible to swap out any of those implementations +(and to test that they comply with expectations within the consensus engine). + +While it is easiest to integrate Go code with Gordian, +it should be straightforward to write a shim layer in Go such that +you can run an external process and have the core engine communicate with your component. +There is also the option of [CGo](https://pkg.go.dev/cmd/cgo) if you can provide a C ABI. + + + +## Why would I use Gordian? + +Most other consensus engines tend to have strong opinions about the way these subsystems work. +As a result, when teams run into bottlenecks, they are usually stuck looking for small performance gains +in the underlying framework. +Gordian makes it easy to swap out parts of the consensus engine, +whether you are making one small tweak to a standard component or writing one from scratch. +Whether it's a short experiment or code you've benchmarked and you are taking to production, +you can relax knowing that you can safely maintain one small library, +instead of forking the entire consensus engine. ## Try it out -Clone the repository and `cd` into it. +### Full demo with gcosmos + +We recommend the earlier mentioned [https://github.com/gordian-engine/gcosmos](gcosmos) repository +for a full-featured demo involving Gordian integrating with the Cosmos SDK. + +### Lightweight demo + +Clone the Gordian repository and `cd` into it. Make sure you have [the most recent version of Go installed](https://go.dev/dl/). Run `./demo-echo.bash start 4` to start a local network of 4 validators, running a toy application where the network participants agree on the current height and round. + +[^1]: Tendermint is a registered trademark of All in Bits, Inc.