# Validator Cluster Deployment Guide

Gravity SDK makes it straightforward to spin up your own EVM-compatible chain with the same [AptosBFT](https://aptos.dev/en/network/blockchain/bft-consensus) 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](https://docs.gravity.xyz/tutorials/gravity-sdk-tutorial).

***

## 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

```bash
git clone --branch gravity-testnet-v1.0.0 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:

```bash
make BINARY=gravity_node MODE=quick-release
```

Refer to [gravity-sdk/readme.md](https://github.com/Galxe/gravity-sdk/blob/main/readme.md) for full build options.

### 3. Setup Configuration

```bash
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

```bash
make init
```

This generates `identity.yaml` for each validator node.

### 5. Generate Genesis (New Networks Only)

```bash
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

```bash
make deploy_start
```

Your cluster is now running. Useful commands:

```bash
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](https://docs.gravity.xyz/developer-resources/benchmark-guide) to benchmark throughput and latency using `gravity_bench`.