Benchmark Reproduction Guide

Step-by-step guide to reproducing the Gravity EVM benchmark and collecting throughput and latency data using gravity_bench.

Overview

• Goal: Continuously stress Gravity's RPC endpoints and measure throughput (TPS) and latency.

• Repository: https://github.com/Galxe/gravity_bench

• What the tool does:

  • Deploys the required ERC20 contracts.

  • Prepares a large pool of accounts/addresses.

  • Concurrently sends transactions to one or more RPC endpoints.

Prerequisites

1. A gravity_node binary built in release mode — benchmark results are only meaningful when the node is compiled with optimizations. Refer to gravity-sdk/readme.md for full build instructions. The recommended command is:

   make BINARY=gravity_node MODE=quick-release

2. A running Gravity EVM cluster (refer to: Validator Cluster Deployment Guide):

   • Code: https://github.com/Galxe/gravity-sdk (see releases for tagged versions)

     • Note: example cluster configurations are available at: https://github.com/Galxe/gravity-sdk/tree/main/cluster/example

   • chain_id: 1337 (example)

   • nodes1: http://127.0.0.1:8545 (example Validator1)

   • nodes2: http://127.0.0.1:8546 (example Validator2)

   • nodes3: http://127.0.0.1:8547 (example Validator3)

3. A funded EOA for use as faucet + deployer:

   • You must provide this account's private key in the config file.

   • The account needs sufficient native token balance to:

     • Fund a large number of test accounts (directly or via cascading faucet mode).

     • Pay gas for contract deployment.

   A test faucet account is pre-funded in genesis.toml, with private key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80, corresponding to address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266. The following configuration must be present in genesis.toml to give this address a balance:

   [genesis.faucet]
   address = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
   private_key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
   balance = "1000000000000000000000000"   # 1M ETH

System Dependencies (Ubuntu)

Install all required build and runtime packages in one step:

sudo apt update && sudo apt install -y \
  build-essential clang pkg-config libssl-dev git curl \
  libudev-dev libusb-1.0-0-dev \
  python3 python-is-python3 python3-pip python3-venv \
  nodejs npm

python-is-python3 creates the python command alias required by gravity_bench's internal scripts. libudev-dev / libusb-1.0-0-dev prevent common build errors when compiling hidapi.

Environment Setup

1. Clone the repository

   git clone https://github.com/Galxe/gravity_bench.git
   cd gravity_bench

2. Run the initialization script

The script will:

• Check and install missing tools (Rust, Node.js, Python)

• Create a Python virtual environment

• Install Python and Node dependencies

• Clone the contract repositories required for benchmarking

Recommended (keep the environment active in the current shell):

source setup.sh

⚠️ On Ubuntu, if you see Failed to create Python virtual environment, first run:

sudo apt install python3-venv

Then re-run source setup.sh.

Alternative (requires manual environment activation):

bash setup.sh
# Then manually activate the environment:
source venv/bin/activate
source ~/.cargo/env  # only needed if the script installed Rust

Configuration

1. Create a local config file

   cp bench_config.template bench_config.toml

2. Edit bench_config.toml

Key fields to review:

• nodes: one or more RPC endpoints

• target_tps: target benchmark TPS; recommended not to exceed 9k on a 3-node cluster

• [faucet].private_key: private key of the funded faucet/deployer account

• [accounts].num_accounts: number of benchmark accounts; 100k recommended

• [performance]: concurrency and pool configuration

Configuration constraints — violating these will cause an assertion failure on startup:

• accounts.num_accounts ≥ target_tps

• performance.num_senders ≤ accounts.num_accounts

Example (abbreviated):

# Gravity Bench Configuration File

# Uniswap configuration file path (generated by deployment)
contract_config_path = "deploy.json"

# Target sending rate
target_tps = 9000

# RPC endpoints, replace with your chain_id and addresses
nodes = [
    { rpc_url = "http://127.0.0.1:8545", chain_id = 1337 },
    { rpc_url = "http://127.0.0.1:8546", chain_id = 1337 },
    { rpc_url = "http://127.0.0.1:8547", chain_id = 1337 },
]

num_tokens = 1
enable_swap_token = false

# Address pool type: "random" (default) or "weighted" (hot/normal/long-tail distribution)
address_pool_type = "random"

[faucet]
# Private key (replace with your real key)
private_key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"

# Faucet Level:
# - 10 enables cascade mode: 1 -> 10 -> 100 (amplification chain)
# - 0 disables cascading
faucet_level = 10

# Wait between faucet distribution levels (increase if you see insufficient funds)
wait_duration_secs = 1

# Target ETH balance per funded account (in wei)
fauce_eth_balance = "1000000000000000000000"

[accounts]
num_accounts = 100000

[performance]
# Number of concurrent transaction sending tasks inside TxnConsumer
num_senders = 600

# Max in-memory pool size inside the consumer
max_pool_size = 100000

# Benchmark duration in seconds (0 = run indefinitely)
duration_secs = 0

# Sampling strategy: integer = sample every N txns, or "full" to check all pending
sampling = 20

Running the Benchmark

First Run (includes faucet distribution + contract deployment)

For the first run (or when you want to re-initialize accounts/contracts):

cargo run --release -- --config bench_config.toml

This step will:

• Distribute funds to test accounts using the faucet private key.

• Deploy the required contracts.

• Generate (or update) deploy.json, referenced by contract_config_path.

Subsequent Runs (reuse existing state)

Once contracts are deployed and deploy.json exists, use recovery mode:

cargo run --release -- --config bench_config.toml --recover

Diagnostics

Verify an RPC endpoint is reachable and get its chain_id:

curl -s http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'
# expect 0x539 for chainId 1337

Check a faucet account balance:

curl -s http://127.0.0.1:8545 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266","latest"]}'

Troubleshooting

Symptom	Fix
Build error: libudev.pc / hidapi / pkg-config not found	sudo apt install -y libudev-dev libusb-1.0-0-dev pkg-config
python: command not found	sudo apt install -y python-is-python3
ModuleNotFoundError: No module named 'web3'	Ensure you're in the gravity_bench directory and run source setup.sh again
SolcError or missing Uniswap/OpenZeppelin contracts	Remove contracts/ and node_modules/ then re-run source setup.sh
insufficient funds for gas * price + value	Increase faucet.wait_duration_secs in bench_config.toml; for a local cluster, restart all nodes to reset state
assertion failed: accounts.num_accounts >= target_tps	Increase accounts.num_accounts to be ≥ target_tps
Connection refused / wrong network	Verify rpc_url is correct and the cluster is running; confirm chain_id matches the value returned by eth_chainId

Visualization

For Grafana / Prometheus deployment and dashboard import, refer to:

• Grafana / Prometheus deployment guide coming soon.