Run a Gravity Mainnet Validator (Invite Only)

Run an invite-only Gravity Mainnet (L1) validator. Validator onboarding is currently invite-only. Covers validator node deployment, StakePool creation, governance whitelisting, validator join, status

This guide walks approved operators through adding a validator to Gravity Mainnet (L1, Chain ID 127001). A validator participates in AptosBFT consensus and must be backed by a StakePool that has been approved through governance.

Validator onboarding is currently invite-only. If you only need a node for reads, writes, or indexing, run a Public Full Node instead.

Placeholders. Commands below use <YOUR_...> placeholders. Replace each value before running. Never paste private keys into shared shells or commit generated node identities.

Network Role

Validators connect to each other on the validator network and optionally expose VFN-network endpoints for VFNs:

validator set --validator net--> consensus
validator --VFN net--> VFN --public net--> PFN / RPC

The onboarding flow is:

Prepare validator config and identity.
Deploy the node package.
Fund the validator account.
Create a StakePool.
Add the StakePool to the validator whitelist through governance.
Join the validator set with the node's public identity.
Start the node and verify status.

Prerequisites

Approval from current governance / operators. The StakePool must be whitelisted before it can join the validator set.
A Linux x86-64 host, preferably Ubuntu 24.04 LTS.

gravity_node and gravity_cli.

git clone https://github.com/Galxe/gravity-sdk.git
cd gravity-sdk
RUSTFLAGS="--cfg tokio_unstable" \
  cargo build --profile quick-release -p gravity_node -p gravity_cli

Mainnet genesis.json and waypoint.txt. Use the canonical mainnet artifacts from gravity-sdk/genesis/mainnet; do not regenerate genesis locally.
A fresh validator EVM account. This account owns and operates the StakePool. Do not reuse public test keys for a long-running validator.
System contract addresses for staking, validator management, and governance. See the mainnet contract reference for current addresses.

1. Write `cluster-validator.toml`

Download the canonical mainnet artifacts where the config below expects them:

mkdir -p <YOUR_GRAVITY_SDK_PATH>/cluster/output
curl -fsSL https://raw.githubusercontent.com/Galxe/gravity-sdk/main/genesis/mainnet/genesis.json \
  -o <YOUR_GRAVITY_SDK_PATH>/cluster/output/genesis.json
curl -fsSL https://raw.githubusercontent.com/Galxe/gravity-sdk/main/genesis/mainnet/waypoint.txt \
  -o <YOUR_GRAVITY_SDK_PATH>/cluster/output/waypoint.txt

Create a config such as:

[cluster]
name = "<YOUR_VALIDATOR_CLUSTER_NAME>"
base_dir = "<YOUR_DEPLOY_BASE_DIR>"

[genesis_source]
genesis_path = "./output/genesis.json"
waypoint_path = "./output/waypoint.txt"

[relayer]
relayer_rpc_url = "<YOUR_L1_RPC_URL>"

[[nodes]]
id = "validator-1"
role = "validator"
source = { bin_path = "../target/quick-release/gravity_node" }
identity = { source = "file" }
host = "<YOUR_VALIDATOR_HOST>"

# Deploy directory, not the database directory.
# deploy.sh renders storage to <YOUR_DEPLOY_BASE_DIR>/validator-1/data
# and reth to <YOUR_DEPLOY_BASE_DIR>/validator-1/data/reth.
data_dir = "<YOUR_DEPLOY_BASE_DIR>/validator-1"

validator_port = 6180
vfn_port = 6190
rpc_port = 8545
metrics_port = 9001
inspection_port = 10001
https_port = 11001
authrpc_port = 8661
reth_p2p_port = 12024
txpool_max_account_slots = 64

If identity is stored in a secret manager, pin a fixed version rather than latest:

identity = {
  source = "gcp_secret",
  secret = "projects/<YOUR_PROJECT>/secrets/<YOUR_SECRET>/versions/1",
}

2. Generate Identity and Deploy

cd <YOUR_GRAVITY_SDK_PATH>/cluster
just init cluster-validator.toml
just deploy cluster-validator.toml

Expected layout:

<YOUR_DEPLOY_BASE_DIR>/validator-1/config/
<YOUR_DEPLOY_BASE_DIR>/validator-1/data/
<YOUR_DEPLOY_BASE_DIR>/validator-1/script/start.sh
<YOUR_DEPLOY_BASE_DIR>/validator-1/script/stop.sh

The public identity used during validator join is written to:

<YOUR_GRAVITY_SDK_PATH>/cluster/output/validator-1/config/identity.public.yaml

3. Optional: Warm Start the Databases

To reduce cold-sync time, copy only chain databases from an existing RPC/PFN you control:

cd <YOUR_EXISTING_NODE_DATA_DIR>
tar -cf - consensus_db quorumstoreDB reth | \
  ssh <YOUR_TARGET_HOST> \
    "mkdir -p <YOUR_DEPLOY_BASE_DIR>/validator-1/data && \
     cd <YOUR_DEPLOY_BASE_DIR>/validator-1/data && tar -xf -"

Do not copy another node's secure_storage.json. It contains safety-rules owner and consensus-key state. Reusing it can produce errors such as:

The validator is not in the validator set. Address not in set: <OLD_OWNER_ACCOUNT>

4. Fund the Validator Account

Set common variables:

export RPC_URL="https://mainnet-rpc.gravity.xyz"
export VALIDATOR_ADDRESS="<YOUR_VALIDATOR_EVM_ADDRESS>"
export STAKE_AMOUNT="<YOUR_STAKE_AMOUNT>"
export STAKING_ADDRESS="<STAKING_CONTRACT_ADDRESS>"
export VALIDATOR_MANAGER_ADDRESS="<VALIDATOR_MANAGER_CONTRACT_ADDRESS>"
export GOVERNANCE_ADDRESS="<GOVERNANCE_CONTRACT_ADDRESS>"

Fund the validator account with enough balance for stake and gas:

cast balance "$VALIDATOR_ADDRESS" --rpc-url "$RPC_URL"

The validator account must sign StakePool and validator lifecycle operations. Use your normal secure signing workflow. If gravity_cli prompts for a key on stdin, ensure the signer is the StakePool operator.

5. Create a StakePool

Use the validator account to create a StakePool:

gravity_cli stake create \
  --rpc-url "$RPC_URL" \
  --stake-amount "$STAKE_AMOUNT" \
  --lockup-duration <YOUR_LOCKUP_SECONDS> \
  --gas-limit <YOUR_GAS_LIMIT>

Record the created pool:

export STAKE_POOL="<YOUR_STAKE_POOL_ADDRESS>"

Verify:

gravity_cli stake get \
  --rpc-url "$RPC_URL" \
  --owner "$VALIDATOR_ADDRESS"

cast call "$STAKING_ADDRESS" \
  "isPool(address)(bool)" "$STAKE_POOL" \
  --rpc-url "$RPC_URL"

If the chain enforces a minimum lockup duration, do not set the lockup exactly at the minimum. Add a buffer so timestamp drift does not trigger LockupDurationTooShort.

6. Whitelist the StakePool

The whitelist target is the StakePool address, not the validator EOA:

ValidatorManagement.setValidatorPoolAllowed(address stakePool, bool allowed)

This call must go through governance. Direct calls from an EOA are expected to revert.

Create calldata:

export ALLOW_CALL=$(cast calldata \
  "setValidatorPoolAllowed(address,bool)" \
  "$STAKE_POOL" true)

Create, vote, resolve, and execute the proposal according to the current governance process:

cast send "$GOVERNANCE_ADDRESS" \
  "createProposal(address,address[],bytes[],string)(uint64)" \
  "<YOUR_PROPOSER_POOL>" \
  "[$VALIDATOR_MANAGER_ADDRESS]" \
  "[$ALLOW_CALL]" \
  "add-validator-whitelist-validator-1" \
  --rpc-url "$RPC_URL" \
  --private-key <YOUR_PROPOSER_PRIVATE_KEY>

export PROPOSAL_ID="<YOUR_PROPOSAL_ID>"

cast send "$GOVERNANCE_ADDRESS" \
  "vote(address,uint64,uint128,bool)" \
  "<YOUR_PROPOSER_POOL>" "$PROPOSAL_ID" \
  340282366920938463463374607431768211455 true \
  --rpc-url "$RPC_URL" \
  --private-key <YOUR_PROPOSER_PRIVATE_KEY>

cast send "$GOVERNANCE_ADDRESS" \
  "resolve(uint64)" "$PROPOSAL_ID" \
  --rpc-url "$RPC_URL" \
  --private-key <YOUR_PROPOSER_PRIVATE_KEY>

cast send "$GOVERNANCE_ADDRESS" \
  "execute(uint64,address[],bytes[])" \
  "$PROPOSAL_ID" \
  "[$VALIDATOR_MANAGER_ADDRESS]" \
  "[$ALLOW_CALL]" \
  --rpc-url "$RPC_URL" \
  --private-key <YOUR_GOVERNANCE_EXECUTOR_PRIVATE_KEY>

Confirm the pool is allowed:

cast call "$VALIDATOR_MANAGER_ADDRESS" \
  "isValidatorPoolAllowed(address)(bool)" "$STAKE_POOL" \
  --rpc-url "$RPC_URL"

7. Join the Validator Set

Read the node's public identity:

export CONSENSUS_PUBLIC_KEY=$(yq -r '.consensus_public_key' \
  <YOUR_GRAVITY_SDK_PATH>/cluster/output/validator-1/config/identity.public.yaml)
export CONSENSUS_POP=$(yq -r '.consensus_pop' \
  <YOUR_GRAVITY_SDK_PATH>/cluster/output/validator-1/config/identity.public.yaml)
export NETWORK_PUBLIC_KEY=$(yq -r '.network_public_key' \
  <YOUR_GRAVITY_SDK_PATH>/cluster/output/validator-1/config/identity.public.yaml)

Join:

gravity_cli validator join \
  --rpc-url "$RPC_URL" \
  --stake-pool "$STAKE_POOL" \
  --consensus-public-key "$CONSENSUS_PUBLIC_KEY" \
  --consensus-pop "$CONSENSUS_POP" \
  --network-public-key "$NETWORK_PUBLIC_KEY" \
  --validator-network-address "/dns/<YOUR_VALIDATOR_HOST>/tcp/6180" \
  --fullnode-network-address "/dns/<YOUR_VALIDATOR_HOST>/tcp/6190" \
  --moniker "validator-1" \
  --gas-limit <YOUR_GAS_LIMIT>

The signer must be the StakePool operator.

8. Start and Verify

bash <YOUR_DEPLOY_BASE_DIR>/validator-1/script/start.sh

Check validator set and epoch status:

gravity_cli validator list --rpc-url "$RPC_URL"
gravity_cli epoch status --rpc-url "$RPC_URL"

cast call "$VALIDATOR_MANAGER_ADDRESS" \
  "getValidatorStatus(address)(uint8)" "$STAKE_POOL" \
  --rpc-url "$RPC_URL"

Status values:

Value

Status

0

INACTIVE

1

PENDING_ACTIVE

2

ACTIVE

3

PENDING_INACTIVE

After joining, a validator usually enters PENDING_ACTIVE and becomes ACTIVE after an epoch transition.

You can also check node health:

gravity_cli status --rpc-url "$RPC_URL"
curl -s http://127.0.0.1:8545 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Leave the Validator Set

To leave:

gravity_cli validator leave \
  --rpc-url "$RPC_URL" \
  --stake-pool "$STAKE_POOL" \
  --gas-limit <YOUR_GAS_LIMIT>

If the validator is ACTIVE, it becomes PENDING_INACTIVE and exits after the next epoch transition. If it is still PENDING_ACTIVE, it can become INACTIVE immediately.

Verify:

gravity_cli validator list --rpc-url "$RPC_URL"

Troubleshooting

Symptom

Cause / fix

isValidatorPoolAllowed returns false

The governance whitelist proposal has not executed, or it targeted the wrong StakePool.

LockupDurationTooShort

Increase the lockup duration above the minimum with a buffer.

Validator remains PENDING_ACTIVE

Activation normally happens at the next epoch transition. Check gravity_cli epoch status.

Address not in set: <OLD_OWNER_ACCOUNT>

Another node's secure_storage.json was copied. Remove it and regenerate/redeploy with the correct identity.

Node paths do not point to <node>/data

data_dir should be the deploy directory, not the database directory.