Validator Cluster Deployment Guide

Deploy a local multi-validator Gravity EVM cluster using Gravity SDK in minutes — the fastest way to run a high-performance, EVM-compatible chain from scratch.

Gravity SDK makes it straightforward to spin up your own EVM-compatible chain with the same AptosBFT consensus and parallel execution engine that powers the Gravity L1. Whether you want to run a local devnet for development, benchmark raw throughput, or evaluate the technology, this guide walks you through a complete cluster deployment in five steps.

For a deeper dive into the SDK architecture and how to build production-grade chains, see Build Your Own 100k+ TPS Chain Using Gravity SDK.

---

Prerequisites

Ensure you have the following installed:

• Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Foundry (for genesis contract deployment): curl -L https://foundry.paradigm.xyz | bash then foundryup

• Python 3: For parsing configurations.

• envsubst: Usually part of the gettext package (sudo apt install gettext on Ubuntu).

Quick Start (4-Node Cluster)

1. Clone the Repository

git clone https://github.com/Galxe/gravity-sdk.git
cd gravity-sdk

2. Build the Node Binary

Benchmark results are only meaningful when the node is compiled with optimizations:

make BINARY=gravity_node MODE=quick-release

Refer to gravity-sdk/readme.md for full build options.

3. Setup Configuration

cd cluster
cp genesis.toml.example genesis.toml    # Genesis / validator config
cp cluster.toml.example cluster.toml    # Node deployment config

The default configuration sets up 4 nodes on localhost. Edit genesis.toml to customize validators, stake amounts, and network parameters. Edit cluster.toml to adjust ports or the path to your binary.

4. Initialize Node Keys

make init

This generates identity.yaml for each validator node.

5. Generate Genesis (New Networks Only)

make genesis

Outputs ./output/genesis.json and ./output/waypoint.txt.

Note: genesis.sh clones gravity_chain_core_contracts into external/ on first run but does not auto-update it. To update manually: cd external/gravity_chain_core_contracts && git pull origin main

6. Deploy and Start

make deploy_start

Your cluster is now running. Useful commands:

make status   # Show PID, status, and current block number
make stop     # Gracefully stop all nodes

---

Configuration Reference

genesis.toml (New Networks Only)

Section	Description
[genesis]	Core genesis parameters (chain ID, epoch interval, etc.)
[genesis.faucet]	Pre-funded faucet account for testing
[genesis.validator_config]	Validator bond limits and restrictions
[[genesis_validators]]	Genesis validator list with addresses and stake

Key validator fields:

• address — Validator's ETH address (required)

• stake_amount — Initial stake in Wei (required)

• voting_power — Initial voting power (must be ≥ stake_amount)

cluster.toml (Node Deployment)

Section	Description
[cluster]	Cluster name and base directory
[build]	Path to the gravity_node binary
[genesis_source]	Paths to genesis.json and waypoint.txt
[[nodes]]	Node definitions with ports and roles
[faucet_init]	Optional faucet initialization config

Node roles:

• genesis — Included in the genesis validator set

• validator — Validator that joins via on-chain transaction

• vfn — Full node using on-chain discovery

---

Makefile Reference

Target	Description
make genesis	Generate genesis.json + waypoint.txt
make init	Generate node identity keys
make deploy	Prepare runtime environment for each node
make start	Start all nodes
make stop	Stop all nodes
make status	Check cluster status
make faucet	Initialize faucet accounts
make clean	Remove generated artifacts
make deploy_start	Deploy and start (convenience)
make restart	Stop, deploy, and start

---

Next Steps

Once your cluster is running, follow the Benchmark Reproduction Guide to benchmark throughput and latency using gravity_bench.