Running a Sui Full Node: RPC Endpoint Setup and Verification

Sui Full Node Role in the Network Architecture

Sui separates consensus authorities (validators) from full nodes. Validators participate in consensus and execute transactions, but they do not generally serve public RPC traffic. Full nodes replicate the ledger, execute and index transactions, and serve read APIs to clients. This separation is why an operator who wants to serve RPC should run a full node rather than attempt to expose a validator.

A full node can serve the JSON-RPC API directly. When configured as an indexer, it can also back richer query surfaces that require additional indexing work. The Sui full node guide documents the operator workflow for running a node and configuring its interfaces; treat that guide as the authoritative reference for your Sui release.

For network-level context and available endpoints, see the Sui network page. If you prefer not to operate infrastructure, a managed Sui RPC node removes the operational burden, but the verification techniques below still apply to any endpoint you consume.

• Validators: consensus and execution; not public RPC providers.
• Full nodes: replicate ledger, execute and index, serve read APIs.
• Indexer mode: optional, enables richer query surfaces.
• Public RPC exposure: a full node concern, not a validator concern.

Two Decisions When Exposing the RPC Interface

The first decision is which interfaces to enable. The JSON-RPC HTTP interface is the primary surface for read calls. Optionally, a WebSocket or streaming interface can be enabled for subscriptions and event streams. Enabling only what you need reduces attack surface and resource consumption.

The second decision is what to bind those interfaces to. Binding to localhost is the safe default for a private node behind a reverse proxy. Binding to a routable address is only appropriate when a firewall and TLS termination are in place. Exposing the RPC interface directly to the internet without a proxy and TLS is unsafe and is a common cause of node compromise.

These decisions are independent: you can enable HTTP JSON-RPC on localhost while leaving WebSocket disabled, or enable both behind a proxy. Document your chosen surface so that verification steps match your configuration.

• Enable HTTP JSON-RPC for standard read calls.
• Enable WebSocket/streaming only if you need subscriptions.
• Bind to localhost for private nodes behind a proxy.
• Bind to a routable address only with firewall and TLS in place.

Documented Configuration Surface and Release Drift

The node config file contains sections for JSON-RPC and metrics, along with the database path and genesis/network selection. The exact field names and defaults change across Sui releases. An old tutorial may reference fields that no longer exist or that have moved. The operator must reconcile against the current Sui full node guide rather than copying an outdated config.

Genesis and network selection determine which chain the node follows. A mainnet node must use the mainnet genesis; a testnet node uses testnet genesis. Mixing these produces a node that serves the wrong network, which is why chain identity verification is mandatory before serving traffic.

The database path determines disk usage and I/O characteristics. Full sync from genesis can consume significant disk and time. Plan capacity accordingly and monitor disk growth during initial sync.

• Config file: JSON-RPC section, metrics section, database path, genesis/network.
• Field names and defaults vary by Sui release; verify against current docs.
• Genesis selection determines mainnet vs testnet identity.
• Database path affects disk usage and I/O; plan for full sync growth.

Sync Modes and Disk Planning for a Sui Full Node

Sui full nodes support different sync modes that trade off time to first useful checkpoint against disk footprint and I/O. A full sync from genesis replays the entire ledger history and therefore requires the most disk and the longest initial catch-up window. Operators who need a node serving current data quickly may consider a snapshot-based or checkpoint-based sync if their Sui release supports it, but the exact mode names and availability change across releases and must be confirmed against the current Sui full node guide.

Disk planning is not only about the final ledger size. During sync, the node writes checkpoints, transaction effects, and index data, and it may temporarily hold more data than the steady-state footprint. Provision headroom above the expected final size so that compaction, indexing, and future ledger growth do not exhaust the volume. Monitor disk usage continuously during initial sync, because a full disk can stall the node and produce the same stale-checkpoint symptom as a network problem.

I/O characteristics matter as much as raw capacity. A node that is syncing and serving RPC at the same time competes for disk throughput, which can slow both sync and query latency. If you plan to serve production traffic, size the storage for the expected read load in addition to the sync workload, and avoid sharing the volume with unrelated high-I/O processes.

The database path in the config file determines where this data lives. Keep it on a dedicated volume when possible, and document the path so that verification and monitoring steps can reference the correct location. Because field names and defaults drift between releases, re-check the database and sync-related configuration after every upgrade rather than assuming your previous settings still apply.

• Full sync from genesis: maximum disk and longest catch-up.
• Snapshot or checkpoint-based sync: faster to serve current data, if supported by your release.
• Provision headroom above expected final ledger size for compaction and growth.
• Monitor disk usage during initial sync; a full disk can stall the node.
• Separate sync I/O from query I/O when serving production traffic.
• Keep the database path on a dedicated volume and re-check config after upgrades.

Verifying Node Health and Network Identity

Before putting a node in front of traffic, verify it is healthy and serving the right network. Call sui_getLatestCheckpointSequenceNumber to confirm the node is producing checkpoints, and call sui_getChainIdentifier to confirm the network identity. The Sui JSON-RPC references document these methods and their return types.

Confirm the checkpoint number is advancing over time. A node that is still catching up will return stale checkpoints; a node that is stuck will not advance at all. Cross-check the chain identifier against the official Sui mainnet identifier so you do not serve testnet data on a mainnet endpoint.

These checks are cheap and should be part of your deployment gate. If either check fails, do not route traffic to the node.

• sui_getLatestCheckpointSequenceNumber: confirms checkpoint production.
• sui_getChainIdentifier: confirms network identity.
• Checkpoint must advance over successive calls.
• Chain identifier must match the official value for your target network.

Runnable Probe Sequence with curl

The JSON-RPC 2.0 envelope is defined by the JSON-RPC 2.0 specification. A probe is a POST request with a JSON body containing jsonrpc, method, params, and id. The following sequence starts from a node you have already launched with your chosen interface surface, then probes it with curl.

Replace the URL with your node's bound address and port. If you bound to localhost, use http://127.0.0.1:<port>. If you bound behind a proxy, use the proxy URL. The responses confirm the node is reachable and serving the expected methods.

# Probe 1: latest checkpoint sequence number
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"sui_getLatestCheckpointSequenceNumber","params":[]}'

# Probe 2: total transaction blocks
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"sui_getTotalTransactionBlocks","params":[]}'

# Probe 3: chain identifier
curl -s -X POST http://127.0.0.1:9000 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"sui_getChainIdentifier","params":[]}'

Node.js Poller for Checkpoint Growth Rate

A single checkpoint reading is not enough; you need to know whether the checkpoint height is advancing. The following Node.js snippet polls sui_getLatestCheckpointSequenceNumber at a fixed interval and prints the growth rate. Run it against your node's RPC URL.

The script uses the built-in fetch API available in modern Node.js. Adjust the interval and duration to suit your monitoring needs. A growth rate near zero over a sustained window indicates a stalled or still-syncing node.

const RPC_URL = process.env.SUI_RPC_URL || 'http://127.0.0.1:9000';
const INTERVAL_MS = 5000;
const DURATION_MS = 60000;

async function getCheckpoint() {
  const res = await fetch(RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'sui_getLatestCheckpointSequenceNumber',
      params: []
    })
  });
  const json = await res.json();
  if (json.error) throw new Error(JSON.stringify(json.error));
  return Number(json.result);
}

(async () => {
  const start = Date.now();
  let first = await getCheckpoint();
  let last = first;
  console.log(`start checkpoint: ${first}`);
  while (Date.now() - start < DURATION_MS) {
    await new Promise(r => setTimeout(r, INTERVAL_MS));
    last = await getCheckpoint();
    const elapsed = (Date.now() - start) / 1000;
    const rate = (last - first) / elapsed;
    console.log(`checkpoint: ${last} | elapsed: ${elapsed.toFixed(1)}s | rate: ${rate.toFixed(2)} cp/s`);
  }
  console.log(`final checkpoint: ${last}`);
})();

Results Table for Reproducible Verification

Record your verification results in a table so that you can compare across nodes, releases, and time. The table below is a template; fill it with your own measurements. Do not rely on numbers from this article, as they are not measured values.

Use the same probe sequence for each row so that comparisons are meaningful. If you change the Sui version or interface surface, add a new row rather than overwriting the old one.

• Sui version: the release you are running.
• Interfaces enabled: HTTP JSON-RPC, WebSocket, or both.
• Bound address: localhost or routable address and port.
• Public-exposed?: yes/no, and whether a proxy and TLS are in place.
• Chain identifier: the value returned by sui_getChainIdentifier.
• Checkpoint advancing?: yes/no, based on repeated probes.
• Sync lag: difference between your checkpoint and the network tip, if known.

Limitations and Operational Tradeoffs

Full sync from genesis can take a long time and significant disk. A node that is still catching up will return stale checkpoints, which can mislead clients if you route traffic too early. Checkpoint lag is a normal steady-state condition that must be monitored rather than assumed zero.

Exposing the RPC interface without a proxy and TLS is unsafe. Even with a proxy, rate limiting and authentication are your responsibility. A self-run node rarely matches a managed provider on availability or geographic distribution. If your application needs global low-latency reads, a managed endpoint may be more appropriate; see RPC pricing and the API service for options.

For deeper operational topics, see Sui RPC latency, Sui RPC rate limits and compute units, Sui checkpoint stream and ledger service, and Sui archive nodes and historical RPC.

• Full sync: long duration and significant disk usage.
• Stale checkpoints: expected while catching up; do not serve traffic early.
• Checkpoint lag: normal steady state; monitor rather than assume zero.
• Exposure risk: proxy and TLS are mandatory for public endpoints.
• Availability: self-run nodes rarely match managed provider distribution.

Troubleshooting Common Verification Failures

If curl returns a connection refused error, the node is not listening on the address and port you probed. Confirm the bind address in your config and that the node process is running. If you bound to localhost, ensure you are probing from the same host.

If the JSON-RPC response contains an error object, read the error code and message. A method not found error may indicate that the interface is disabled or that the method name changed in your Sui release. Reconcile against the Sui JSON-RPC references.

If the checkpoint number does not advance, the node may be syncing, stalled, or disconnected from peers. Check the node logs and metrics. If the chain identifier does not match your target network, you are running the wrong genesis; stop and reconfigure before serving traffic.

• Connection refused: check bind address, port, and process status.
• Method not found: verify interface enabled and method name for your release.
• Checkpoint not advancing: check sync status, logs, and peer connectivity.
• Chain identifier mismatch: wrong genesis; reconfigure before serving.

Next Steps for Production Readiness

Once verification passes, place the node behind a reverse proxy with TLS and rate limiting. Add monitoring for checkpoint height, sync lag, and resource usage. Alert on stalled checkpoints and disk pressure.

If you need historical data beyond your node's retention, consider an archive node or a managed service. Review the OnFinality Learn hub for related operational guides, and compare managed options on the Sui network page and RPC pricing.

Keep your Sui version current and re-run the verification sequence after each upgrade, since configuration fields and defaults can change between releases.

• Deploy behind a reverse proxy with TLS and rate limiting.
• Monitor checkpoint height, sync lag, and resource usage.
• Alert on stalled checkpoints and disk pressure.
• Re-run verification after every Sui upgrade.