# 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](/tutorials/gravity-sdk-tutorial.md).

***

## 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](/developer-resources/benchmark-guide.md) to benchmark throughput and latency using `gravity_bench`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gravity.xyz/developer-resources/cluster-deployment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.