README
¶
Gordian
Gordian is a modular, Byzantine-fault-tolerant consensus engine.
A consensus engine is a replicated state machine -- a participant in a distributed system where the participants agree on initial state, actions to apply, and resulting state.
Gordian allows each participant to have a different voting power. This effectively enables Gordian to be the consensus layer in a proof of stake system.
Because Gordian uses an implementation of the Tendermint® consensus algorithm[^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.
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 gcosmos for an example Driver integrating with the Cosmos SDK.
Outside of the driver, Gordian currently provides a networking layer using libp2p, a storage layer using SQLite, Ed25519 signing keys for validators, and some simple hashing schemes using BLAKE2b.
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 if you can provide a C ABI.
Refer to the _docs directory for more technical details.
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
Full demo with gcosmos
We recommend the earlier mentioned 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.
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.
License
The Gordian source code is available under the Apache 2.0 license.
Copyright (c) 2024 Strangelove Crypto, Inc.
[^1]: Tendermint is a registered trademark of All in Bits, Inc. and is used here for identification purposes only.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
Package gassert (Gordian assert) provides functionality around assertions at runtime.
|
Package gassert (Gordian assert) provides functionality around assertions at runtime. |
|
cmd/generate-nodebug
Command generate-nodebug processes a *_debug.go file to automatically and consistently generate a *_nodebug.go file, with functions that have matching signatures.
|
Command generate-nodebug processes a *_debug.go file to automatically and consistently generate a *_nodebug.go file, with functions that have matching signatures. |
|
gasserttest
Package gasserttest contains helpers for tests involving gassert.
|
Package gasserttest contains helpers for tests involving gassert. |
|
gcosmos
module
|
|
|
Package gcrypto contains cryptographic primitives for the Gordian engine.
|
Package gcrypto contains cryptographic primitives for the Gordian engine. |
|
gblsminsig
Package gblsminsig wraps github.com/supranational/blst/bindings/go to provide a gcrypto.PubKey implementation backed by BLS keys, where the BLS keys have minimized signatures.
|
Package gblsminsig wraps github.com/supranational/blst/bindings/go to provide a gcrypto.PubKey implementation backed by BLS keys, where the BLS keys have minimized signatures. |
|
gcryptotest
Code generated by go generate; DO NOT EDIT.
|
Code generated by go generate; DO NOT EDIT. |
|
Package gdriver and its subpackages provide useful types for writing Gordian drivers.
|
Package gdriver and its subpackages provide useful types for writing Gordian drivers. |
|
Package gerasure contains generalized interfaces for erasure coding and decoding.
|
Package gerasure contains generalized interfaces for erasure coding and decoding. |
|
gerasuretest
Package gerasuretest contains compliance tests for erasure coding encoders and reconstructors.
|
Package gerasuretest contains compliance tests for erasure coding encoders and reconstructors. |
|
gereedsolomon
Package gereedsolomon provides Reed-Solomon implementations of the gerasure interfaces, by wrapping the github.com/klauspost/reedsolomon package.
|
Package gereedsolomon provides Reed-Solomon implementations of the gerasure interfaces, by wrapping the github.com/klauspost/reedsolomon package. |
|
Package gexchange contains generalized types for the interactions between a p2p layer and a consensus engine.
|
Package gexchange contains generalized types for the interactions between a p2p layer and a consensus engine. |
|
Package gnetdag (Gordian NETwork Directed Acyclic Graph) contains types for determining directional flow of network traffic.
|
Package gnetdag (Gordian NETwork Directed Acyclic Graph) contains types for determining directional flow of network traffic. |
|
Package gwatchdog provides a Watchdog type that periodically communicates with subsystems that have opted in to the watchdog.
|
Package gwatchdog provides a Watchdog type that periodically communicates with subsystems that have opted in to the watchdog. |
|
internal
|
|
|
gchan
Package gchan contains helpers for common operations with channels.
|
Package gchan contains helpers for common operations with channels. |
|
tm
|
|
|
tmcodec
Package tmcodec contains types for marshalling and unmarshalling consensus messages, without being coupled to any particular serialization scheme.
|
Package tmcodec contains types for marshalling and unmarshalling consensus messages, without being coupled to any particular serialization scheme. |
|
tmcodec/tmjson
Package tmjson contains types satisfying the tmcodec interfaces that serializing to and deserialize from JSON.
|
Package tmjson contains types satisfying the tmcodec interfaces that serializing to and deserialize from JSON. |
|
tmconsensus
Package tmconsensus contains low-level consensus primitives.
|
Package tmconsensus contains low-level consensus primitives. |
|
tmconsensus/tmconsensustest
Package tmconsensustest contains utilities helpful for interacting with tmconsensus types in tests.
|
Package tmconsensustest contains utilities helpful for interacting with tmconsensus types in tests. |
|
tmdebug
Package tmdebug contains utilities useful for debugging components of Gordian's tm package tree.
|
Package tmdebug contains utilities useful for debugging components of Gordian's tm package tree. |
|
tmdriver
Package tmdriver contains types for the driver to interact with the consensus engine.
|
Package tmdriver contains types for the driver to interact with the consensus engine. |
|
tmengine
Package tmengine contains the Engine and its supporting types which are used to actually create a consensus engine.
|
Package tmengine contains the Engine and its supporting types which are used to actually create a consensus engine. |
|
tmengine/internal/tmeil
Package tmeil is shorthand for tmengine internal link.
|
Package tmeil is shorthand for tmengine internal link. |
|
tmengine/internal/tmemetrics
Package tmemetrics contains the internals for tmengine metrics.
|
Package tmemetrics contains the internals for tmengine metrics. |
|
tmengine/internal/tmmirror/internal/tmi
Package tmi is the internal package for tmmirror.
|
Package tmi is the internal package for tmmirror. |
|
tmengine/tmelink
Package tmelink contains types used by the internals of the github.com/gordian-engine/gordian/tm/tmengine.Engine that need to be exposed outside of the tmengine package.
|
Package tmelink contains types used by the internals of the github.com/gordian-engine/gordian/tm/tmengine.Engine that need to be exposed outside of the tmengine package. |
|
tmengine/tmelink/tmelinktest
Package tmelinktest contains helpers for tests involving the tmelink package.
|
Package tmelinktest contains helpers for tests involving the tmelink package. |
|
tmengine/tmenginetest
Package tmenginetest contains types useful for tests involving the tmengine package.
|
Package tmenginetest contains types useful for tests involving the tmengine package. |
|
tmgossip
Package tmgossip defines the gossip Strategy that the github.com/gordian-engine/gordian/tm/tmengine.Engine uses to push state updates to the peer-to-peer network.
|
Package tmgossip defines the gossip Strategy that the github.com/gordian-engine/gordian/tm/tmengine.Engine uses to push state updates to the peer-to-peer network. |
|
tmgossip/tmgossiptest
Package tmgossiptest contains implementations of github.com/gordian-engine/gordian/tm/tmgossip.Strategy that are useful to tests that require gossip strategies.
|
Package tmgossiptest contains implementations of github.com/gordian-engine/gordian/tm/tmgossip.Strategy that are useful to tests that require gossip strategies. |
|
tmintegration
Package tmintegration defines integration tests around consensus engines, using user-specified network and store definitions.
|
Package tmintegration defines integration tests around consensus engines, using user-specified network and store definitions. |
|
tmp2p
Package tmp2p contains high-level interfaces for the peer-to-peer layer for [tmengine].
|
Package tmp2p contains high-level interfaces for the peer-to-peer layer for [tmengine]. |
|
tmp2p/tmlibp2p
Package tmlibp2p contains implementations of the tmp2p interfaces using github.com/libp2p/go-libp2p.
|
Package tmlibp2p contains implementations of the tmp2p interfaces using github.com/libp2p/go-libp2p. |
|
tmp2p/tmlibp2p/tmlibp2ptest
Package tmlibp2ptest provides the Network type that is useful for tests that need to instantiate a Gordian peer-to-peer network backed by tmlibp2p.
|
Package tmlibp2ptest provides the Network type that is useful for tests that need to instantiate a Gordian peer-to-peer network backed by tmlibp2p. |
|
tmp2p/tmp2ptest
Package tmp2ptest contains compliance tests for tmp2p implementations, and it also provides some other types that are useful in tests.
|
Package tmp2ptest contains compliance tests for tmp2p implementations, and it also provides some other types that are useful in tests. |
|
tmstore
Package tmstore contains the store interfaces for the gordian/tm tree.
|
Package tmstore contains the store interfaces for the gordian/tm tree. |
|
tmstore/tmmemstore
Package tmmemstore contains in-memory implementations of stores defined in tmstore.
|
Package tmmemstore contains in-memory implementations of stores defined in tmstore. |
|
tmstore/tmstoretest
Package tmstoretest contains the compliance tests for implementations of the tmstore interfaces.
|
Package tmstoretest contains the compliance tests for implementations of the tmstore interfaces. |
|
tmsqlite
module
|