An execution environment for blockchains.
Grug consists of the following Rust crates:
| crate | description |
|---|---|
| app | state machine transition logics and Tendermint ABCI implementation |
| crypto | cryptography functionalities |
| db/disk | an on-disk, persisted DB backend |
| db/memory | an in-memory, temporary DB backend; used for testing |
| macros | macros for reducing boilerplates in contract developments |
| jellyfish-merkle | Jellyfish Merkle Tree (JMT) implementation |
| storage | an ergonomic API for interacting with key-value stores |
| types | types, traits, and helper functions |
| vm/rust | a VM that runs native Rust codes; used for testing |
| vm/wasm | a VM that runs Wasm byte codes |
| wasm | an ergonomic API for building Wasm modules |
Additionally, there are grug-testing which provides testing utilities, and grug-std, a "meta package", which re-exports contents from the above crates, for the convenience of contract developers.
At the heart of the project is the grug_app::App type. Fundamentally, a blockchain is a state machine that consists of 1) the state, typically represented by a key-value database, and 2) the state transition rule, which typically involves a virtual machine that runs smart contracts. Therefore, our App takes two generics, representing the DB and the VM, respectively:
struct App<DB, VM> {
db: DB,
vm: PhantomData<VM>,
}Here, DB must implement the grug_types::Db trait, while VM must implement the grug_types::Vm trait.
We will ship two Db and two Vm implementations, for different use cases:
| use case | implementation |
|---|---|
| production node | App<DiskDb, WasmVm> |
| testing | App<MemDb, RustVm> |
The below diagram shows the dependency relations between the crates:
Prerequisites:
Install the grug command line software:
just installRun tests:
just testLint the code:
just lintCompile and optimize smart contracts:
just optimizeThe developer tooling we use for this project is listed below. Finding the right tools is important for productivity but can take time. We hope you will find this useful:
| tool | Rust | TypeScript |
|---|---|---|
| package manager | cargo | pnpm |
| bundler | cargo build | tsup |
| tester | cargo test | vitest |
| linter | cargo clippy | biome |
| formatter | cargo fmt | biome |
| documentation | cargo doc | typedoc |
TODO
TBD