Run a Gravity Testnet Public Full Node

Run a Gravity Longevity Testnet (L1) Public Full Node. Covers binaries, testnet genesis artifacts, the public-network seed, deployment, database warm start, and sync verification for a PFN/RPC endpoin

This guide walks you through running a Public Full Node (PFN) on Gravity Longevity Testnet (L1, Chain ID 7771625). A PFN syncs from an upstream public or VFN seed and can serve EVM JSON-RPC for your applications, indexers, or internal services.

A PFN does not participate in consensus, does not hold validator stake, and does not require an invite. If you only need occasional reads or writes, you can use the public endpoint at https://testnet-rpc.gravity.xyz instead.

Required version. Longevity Testnet nodes must run v1.10.0-pre (or newer) to follow the live tip after Gamma. See Gravity Longevity Testnet Hardforks.

Placeholders. Commands below use <YOUR_...> placeholders. Replace each value before running. Never commit private keys, generated identities, or node databases to version control.

Network Role

Gravity L1 separates node traffic into validator, VFN, and public networks. A PFN uses the public network and syncs outward from upstream infrastructure:

validators --VFN net--> VFN --public net--> PFN / RPC --> app or indexer

Use a PFN when you want:

• a private or high-throughput JSON-RPC endpoint on testnet;

• a node close to your backend or indexer;

• independent chain data for analytics or monitoring;

• no validator-set or governance operations.

Prerequisites

1. A Linux x86-64 host. Production-like nodes are built and run on Ubuntu 24.04 LTS. Build on the same OS family that you deploy to.

2. gravity_node and gravity_cli. Build from source:

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

   The binaries land in target/quick-release/. You can also download the v1.10.0-pre release assets (gravity_node, gravity_cli). For gravity_cli command usage, see the Gravity CLI Skill.

3. Testnet genesis.json and waypoint.txt. These artifacts pin the exact chain you are joining. Download the canonical files from gravity-sdk/genesis/testnet; do not regenerate genesis locally for the public testnet.

4. An upstream public-network seed. For the seed you need its peer_id, host, public port, and network_public_key. The current public testnet PFN seed is listed below.

5. SSD/NVMe storage. Chain data grows with uptime. Budget well above the current chain size.

1. Prepare Genesis Artifacts

Place the canonical testnet artifacts where your cluster config references them:

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

<YOUR_GRAVITY_SDK_PATH>/cluster/output/genesis.json
<YOUR_GRAVITY_SDK_PATH>/cluster/output/waypoint.txt

If the artifacts live elsewhere, you can point to absolute paths in genesis_source:

[genesis_source]
genesis_path = "<YOUR_TESTNET_ARTIFACT_DIR>/genesis.json"
waypoint_path = "<YOUR_TESTNET_ARTIFACT_DIR>/waypoint.txt"

The genesis.json and waypoint.txt must match each other. A wrong pair can start a node on a different chain identity and prevent it from syncing testnet.

Confirm the downloaded genesis includes the live hardfork fields (pragueTime, alphaTime, betaTime, osakaTime, gammaTime). See Longevity Testnet Hardforks.

2. Gather Seed Information

Current Testnet PFN Connectivity

Node	Host	JSON-RPC endpoint	Public-network seed port	Peer ID	Network public key
testnet-rpc-p2p-1	testnet-rpc-p2p-1.gravity.xyz	https://testnet-rpc.gravity.xyz	6195	e7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433	86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a

For normal JSON-RPC traffic, prefer the aggregate endpoint:

https://testnet-rpc.gravity.xyz

Before using the PFN host as an upstream seed, verify from your node host that the public-network port is reachable:

nc -vz testnet-rpc-p2p-1.gravity.xyz 6195

Use the current public testnet PFN seed directly in local-pfn.toml.

seeds = [
  { peer_id = "e7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433", role = "PreferredUpstream", address = "/dns/testnet-rpc-p2p-1.gravity.xyz/tcp/6195/noise-ik/86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a/handshake/0" },
]

For an explicit PFN seed, fill these values from the upstream node's public identity:

Value	Meaning
<YOUR_UPSTREAM_PEER_ID>	Upstream sidecar account_address.
<YOUR_UPSTREAM_HOST>	DNS name or IP address of the upstream public listener.
<YOUR_UPSTREAM_PUBLIC_PORT>	Public-network port exposed by the upstream node.
<YOUR_UPSTREAM_NETWORK_PUBLIC_KEY>	Upstream sidecar network_public_key.

Prefer explicit seed entries over seeds = [{ from = "<id>" }] for a standalone PFN config. The { from = ... } form only works when the seed node is also defined in the same TOML file.

3. Write local-pfn.toml

Create a config such as:

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

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

[[nodes]]
id = "local-pfn"
role = "pfn"
source = { bin_path = "../target/quick-release/gravity_node" }
identity = { source = "file" }

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

host = "127.0.0.1"
# Example local public-network port for this PFN. If other nodes should sync
# from this node, expose and publish the chosen public listener.
public_port = 6195
rpc_port = 8545
metrics_port = 9001
inspection_port = 10001
authrpc_port = 8661
reth_p2p_port = 12024
txpool_max_account_slots = 64
prune_transactionlookup_distance = 10064

seeds = [
  { peer_id = "e7ddaced105af1c4381ca670cea01b0a8e3006c7e360a4f4e40e79fe06c29433", role = "PreferredUpstream", address = "/dns/testnet-rpc-p2p-1.gravity.xyz/tcp/6195/noise-ik/86d3bd6c81fb6994bdbe8df40da28acf44433138cb09ad491c4d98637abd817a/handshake/0" },
]

Port choices can be changed if you run multiple nodes on one host. Keep the RPC port private unless you intentionally expose it behind your own gateway, authentication, rate limiting, and monitoring.

prune_transactionlookup_distance = 10064 starts reth with --full --prune.transactionlookup.distance 10064. This keeps recent transaction-hash lookup data while allowing older transaction lookup indexes to be pruned. Use a value greater than or equal to 10064 for production-like PFN/RPC nodes.

Use transaction-lookup pruning when you want lower execution database growth and do not need arbitrary old eth_getTransactionByHash lookups from this node.

If you omit prune_transactionlookup_distance, the generated PFN reth config uses archive-style storage for transaction lookups and keeps historical lookup indexes instead of pruning them. That is simpler for indexers or debugging flows that need old transaction hashes, but it uses more disk over time.

Do not set prune_transactionlookup_distance = 0 to disable pruning. A distance of 0 is still a pruning mode and can prune transaction lookup data aggressively. To run without transaction-lookup pruning, leave the field out.

The example above generates and stores identity files locally. In production-like environments, you can also load the node identity from a secret manager. For example:

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

Pin a fixed secret version instead of latest when you want reproducible deployments and safer rollbacks.

4. Generate Identity and Deploy

From the SDK cluster directory:

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

Expected layout:

<YOUR_DEPLOY_BASE_DIR>/local-pfn/config/
<YOUR_DEPLOY_BASE_DIR>/local-pfn/data/
<YOUR_DEPLOY_BASE_DIR>/local-pfn/script/start.sh
<YOUR_DEPLOY_BASE_DIR>/local-pfn/script/stop.sh

If the package is generated on a build host, copy it to the runtime host while preserving the node directory layout.

5. Optional: Warm Start From a Snapshot or Existing Node

A new PFN can sync from genesis, but that may take a long time on an established testnet.

Option A: Download the Public Testnet Data Snapshot

Gravity publishes daily Longevity Testnet PFN data snapshots in the public bucket. List available dates:

curl -s 'https://storage.googleapis.com/storage/v1/b/gravity-public-bucket/o?prefix=gravity-testnet-data/&fields=items(name,size,updated)' \
  | jq -r '.items[]?.name' | sort

Pick the latest date and download it. For example, use 2026-09-01 for gravity-testnet-data/2026-09-01.tar:

SNAPSHOT_DATE=2026-09-01   # or a newer date from the list above
curl -L --fail --continue-at - \
  "https://storage.googleapis.com/gravity-public-bucket/gravity-testnet-data/${SNAPSHOT_DATE}.tar" \
  -o "/tmp/${SNAPSHOT_DATE}.tar"

Before the first start, replace the generated empty data directory with the snapshot data:

tar -xf "/tmp/${SNAPSHOT_DATE}.tar" \
  -C <YOUR_DEPLOY_BASE_DIR>/local-pfn/data

After extraction, the data directory should contain the snapshot databases while preserving the node directory layout:

<YOUR_DEPLOY_BASE_DIR>/local-pfn/data/consensus_db/
<YOUR_DEPLOY_BASE_DIR>/local-pfn/data/quorumstoreDB/
<YOUR_DEPLOY_BASE_DIR>/local-pfn/data/reth/

Option B: Copy From an Existing Node You Control

If you already run a trusted RPC/PFN, you can copy only the chain databases from that node:

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

Do not copy rand_db or secure_storage.json from another node. Those files carry node-specific randomness or safety state and should not be reused.

6. Start the Node

bash <YOUR_DEPLOY_BASE_DIR>/local-pfn/script/start.sh

Check the logs under the node directory:

tail -n 200 <YOUR_DEPLOY_BASE_DIR>/local-pfn/consensus_log/pfn.log
ls -lh <YOUR_DEPLOY_BASE_DIR>/local-pfn/execution_logs

7. Verify Sync

Confirm that your local node is on the testnet chain:

curl -s http://127.0.0.1:8545 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

The expected result is 0x7695e9, which is decimal 7771625.

Query your local node:

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

Compare it with the public chain head:

curl -s https://testnet-rpc.gravity.xyz \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

When the two heights are close and your local height keeps advancing, the node is caught up. Gravity has BFT-final blocks: once a block is returned by your node, there is no EVM-style reorg to wait for.

Troubleshooting

Symptom	Cause / fix
seeds: from=<id>: missing host or public_port in cluster.toml	Use an explicit peer_id / address seed, or define the seed node in the same TOML.
Node stays at a low height	Re-check seed peer_id, host, port, network public key, genesis.json, and waypoint.txt.
eth_chainId is not 0x7695e9	The node is not using the canonical testnet genesis or RPC target. Re-check genesis_source and the public RPC URL.
net_peerCount returns 0	Usually expected. Gravity syncs through AptosBFT/VFN/public networks, not EVM devp2p gossip. Watch block height instead.
RPC unavailable	Confirm rpc_port is free, the process is running, and logs exist under the deploy directory.
Database paths look nested incorrectly	data_dir should be the deploy directory. Storage is rendered to $data_dir/data.

See Also

• Gravity Longevity Testnet (L1)

• Gravity Longevity Testnet Hardforks

• Run a Gravity Testnet Public Full Node With Docker

• Run a Gravity Mainnet Public Full Node

• Node Providers