Introduction

A fast, lightweight Ethereum consensus client

Highly optimized, parallel by design and written in Rust. Run a beacon node, a validator client, or both, from a single binary.

Quick start Download GitHub

What makes Grandine different

Parallel by design A highly optimized state transition function, with every CPU core at work. Light on memory About 5 GB on a healthy Mainnet, thanks to structural sharing. Archive node coming soon The best historical data serving performance among consensus clients. Embedded in Nethermind Native Engine API calls with no HTTP or JSON, for the highest performance. One binary, three modes Beacon node, validator client, or both together. Audited Reviewed by Matter Labs and X41 D-Sec, and tested by Antithesis.

Note: No audit makes software risk free. Protect validator keys with the approach you trust, for example a remote signer such as Web3Signer.

Performance

Grandine was built from the start for speed: a highly optimized state transition function, and every CPU core put to work.

The speed comes from optimizations at every layer:

  • An optimized state transition function. The state transition function applies each block and epoch to the beacon state, and it is the hottest code path in a consensus client. Grandine optimizes it with micro-optimizations throughout and with parallelism.
  • Parallel verification. Signatures are verified in batches, and blocks, attestations, aggregates, blob sidecars and data columns are validated in parallel.
  • A lock-free fork choice. A single thread applies verified results to the fork choice store, while the Beacon API and the validator client read recent snapshots. Readers never wait for the writer, and the writer never waits for them.
  • No state copies. Beacon states use structural sharing: a new state shares every unchanged part with its parent instead of copying it. Block processing avoids the cost of cloning full states, and hundreds of unfinalized states cost little more memory than one.
  • Heavy work kept off the network path. Block production, data column recovery and other CPU-heavy jobs run on dedicated executors, separate from the async runtime that serves peers and APIs.

How Grandine works and Performance and memory tuning explain these mechanisms in more detail.

About Grandine

Grandine is an Ethereum consensus client written in Rust. It follows the beacon chain, takes part in consensus through its standalone or built-in validator client, and serves the standard Beacon Node API. Grandine is built by the Grandine core team and is open source under the GNU General Public License, version 3. The source is on GitHub.

This book is for node operators: home stakers, staking providers, infrastructure teams and anyone who wants to run a beacon node. It explains how to install Grandine, connect it to an execution client, run validators safely and keep the node healthy.

Supported networks

Grandine connects to Ethereum Mainnet and to the Sepolia and Hoodi testnets out of the box. It still accepts Holesky, which has reached its end of life. It can also join devnets and other custom networks from a configuration directory. See Supported networks.

How to use this book

If you are new to Grandine, read the pages in this order:

  1. System requirements: check that your machine is big enough.
  2. How Grandine works: the beacon node, validator client and execution client, and how they fit together.
  3. Installation overview: pick a binary, a Docker image or a source build.
  4. Quick start: run an execution client and Grandine on the Hoodi testnet.
  5. Running as a service: run Grandine under systemd or Docker Compose.
  6. Becoming a validator: add validator keys once the node is synced.

Tip: Practice on the Hoodi testnet before you run validators on Mainnet. Testnet ether has no value, so mistakes there cost nothing.

Later sections cover the beacon node in depth (Running a beacon node, Checkpoint sync, Storage and database), validator operations (Validator client, Slashing protection), the APIs (Beacon Node API), monitoring (Metrics, Logging) and reference material (Command line reference, Troubleshooting, FAQ).

Getting help

The fastest way to reach the team and other operators is the Grandine Discord. Report bugs on GitHub. See Support.