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.

Required version. Mainnet nodes must run v1.9.1 before 2026-08-18 02:00:00 UTC. See Gravity Mainnet Hardforks.

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:

1. Prepare validator config and identity.

2. Deploy the node package.

3. Fund the validator account.

4. Create a StakePool.

5. Add the StakePool to the validator whitelist through governance.

6. Join the validator set with the node's public identity.

7. Start the node and verify status.

Prerequisites

1. Approval from current governance / operators. The StakePool must be whitelisted before it can join the validator set.

2. A Linux x86-64 host, preferably Ubuntu 24.04 LTS.

3. gravity_node and gravity_cli.

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

4. Mainnet genesis.json and waypoint.txt. Use the canonical mainnet artifacts from gravity-sdk/genesis/mainnet; do not regenerate genesis locally.

5. A fresh validator EVM account. This account owns and operates the StakePool. Do not reuse public test keys for a long-running validator.

6. 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.

See Also

• Run a Gravity Mainnet Public Full Node

• Run a Gravity Mainnet VFN

• Gravity Mainnet (L1)

• Gravity Mainnet (L1) Contracts