Sui Archive Nodes and Historical RPC: Checkpoints, Epochs, and Querying Past State

What Is a Sui Archive Node and How Do You Access Historical State?

A Sui archive node is a full node that retains all historical checkpoints and state, allowing you to query the network's past state at any point in time. Unlike a standard full node, which prunes old data and only keeps the latest state, an archive node stores every checkpoint since genesis. You can access this historical data through Sui's JSON-RPC API using methods like sui_getCheckpoint and sui_getObject with historical versions, or by running your own archive node. This guide explains the mechanism and shows you how to query past state reliably.

Sui's data model is fundamentally different from EVM-based chains. Instead of blocks and transactions, Sui uses objects and checkpoints. A checkpoint is a sequence of transactions that have been agreed upon by validators, and it serves as a point of finality. Epochs are time-based periods during which the validator set is fixed. Understanding these concepts is key to working with historical data.

• Object: The basic unit of state, owned by an address or shared. Every object has a version number that increments each time it is mutated.
• Checkpoint: A batch of transactions that have been certified and committed. Checkpoints are numbered sequentially from genesis (sequence number 0).
• Epoch: A period of time (e.g., 24 hours) during which the validator set is fixed. Epoch boundaries are marked by special checkpoints.
• Full node: Stores only the latest state and a limited history (e.g., recent checkpoints) to save disk space.
• Archive node: Retains all historical checkpoints and state, enabling queries to any past checkpoint or object version.

How Sui Stores Historical Data: Checkpoints, Epochs, and Object Versions

Sui's consensus produces a sequence of checkpoints. Each checkpoint contains a list of transactions and the resulting state changes. The state is composed of objects, each with a unique ID and a version number. When an object is mutated, its version increments. The full node keeps the latest version of each object in its database, but it may prune older versions and checkpoints to manage disk usage.

Archive nodes, on the other hand, store every checkpoint and every version of every object. This allows you to query the state of an object at a specific historical version or to retrieve events that occurred in a specific checkpoint range. The Sui documentation on Sui Archive Data explains that archive nodes are essential for applications that need to audit past state or serve historical queries.

Epoch boundaries are important because they affect validator sets and gas parameters. You can query checkpoints by sequence number or by epoch. For example, sui_getCheckpoint accepts a checkpoint ID or sequence number, and you can also use sui_getCheckpoints to paginate through checkpoints in a range.

• Checkpoint sequence numbers are monotonically increasing integers starting from 0.
• Each epoch has a start and end checkpoint. The first checkpoint of an epoch is often used to mark the epoch change.
• Object versions are per-object and increment on each write. You can query a specific version using sui_getObject with the version parameter.
• Events are indexed by checkpoint and can be queried using suix_queryEvents with a checkpoint range filter.

Full Node vs Archive Node: What RPC Methods Can You Use?

The key difference between a full node and an archive node is the retention horizon. A full node typically keeps only the latest checkpoint and a few recent ones, while an archive node retains all. This affects which RPC calls succeed. For example, calling sui_getCheckpoint with an old sequence number on a full node may return an error if that checkpoint has been pruned. Similarly, querying an object at an old version may fail if the full node no longer has that version.

The Sui documentation on Sui Full Node Configuration describes the checkpoint-pruning and object-pruning configuration options. By default, full nodes prune old data, but you can configure them to retain more or run an archive node by disabling pruning.

When you use an RPC provider, the availability of historical data depends on whether they run archive nodes. Some providers offer archive endpoints with full historical data, while others only provide full node access. Always check the provider's documentation for retention policies.

• Full node RPC: Suitable for current state queries, recent transactions, and live subscriptions. Historical queries are limited to a short window (e.g., last 100 checkpoints).
• Archive node RPC: Supports queries to any checkpoint, object version, or event in history. Ideal for analytics, audits, and backfilling.
• Provider support: Varies by provider. Some offer archive endpoints as a premium feature. See the Sui RPC guidance for selecting an endpoint.

Running Your Own Sui Archive Node: Storage and Configuration

If you prefer to run your own archive node, you need to configure your Sui full node to disable pruning. The Sui documentation provides a fullnode.yaml configuration file where you can set checkpoint-pruning and object-pruning to false. This will cause the node to retain all historical data.

Storage needs are significant: an archive node stores all historical checkpoints and object versions, and the dataset grows continuously with network activity. The exact size varies by provider, retention policy, and point in time, so treat any figure as provider-documented rather than a fixed constant, and verify against official sources or your own node's disk usage.

Running an archive node also requires more CPU and memory to handle queries on historical data. You should ensure your infrastructure meets the recommended specifications, which are documented in the Sui Full Node Configuration guide.

• Set checkpoint-pruning and object-pruning to false in your node config.
• Monitor disk usage regularly; archive nodes grow continuously.
• Consider using snapshots to bootstrap your node faster, but note that snapshots may not include full history unless they are archive snapshots.
• For managed options, see OnFinality's API service or other providers that offer archive nodes.

Querying Historical State with @mysten/sui.js: A Runnable Example

The following Node.js script demonstrates how to query historical data using the official @mysten/sui.js SDK. It connects to a Sui RPC endpoint (replace with your archive endpoint), fetches a checkpoint by sequence number, retrieves an object at a specific version, and queries events over a checkpoint range.

Before running, install the SDK: npm install @mysten/sui.js. The script assumes you have an archive-capable endpoint. If you don't have one, you can use a public endpoint that supports archive data (e.g., from a provider that offers archive access).

The script outputs the checkpoint details, object content, and events. This is a reproducible method to verify that your endpoint provides historical data.

// queryHistorical.js
import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client';

// Replace with your archive endpoint URL
const RPC_URL = 'https://your-archive-endpoint.example.com';
const client = new SuiClient({ url: RPC_URL });

async function main() {
  // 1. Fetch a checkpoint by sequence number (e.g., 1000)
  const checkpointSeq = 1000;
  const checkpoint = await client.getCheckpoint({ id: checkpointSeq });
  console.log('Checkpoint:', checkpoint);

  // 2. Fetch an object at a specific version (replace with a real object ID and version)
  const objectId = '0x...';
  const version = 1;
  try {
    const object = await client.getObject({
      id: objectId,
      options: { showContent: true },
      version: version
    });
    console.log('Object at version', version, ':', object);
  } catch (e) {
    console.error('Object query failed (may be pruned):', e.message);
  }

  // 3. Query events in a checkpoint range (e.g., from 1000 to 1010)
  const events = await client.queryEvents({
    query: { Checkpoint: { checkpoint: checkpointSeq } },
    limit: 10
  });
  console.log('Events:', events.data);
}

main().catch(console.error);

Expected Output and Verification

When you run the script, you should see the checkpoint object printed, which includes fields like sequenceNumber, timestampMs, epoch, and transactions. The object query will return the object's content if the version exists; if not, it will throw an error indicating the object version is not available. The events query will return a list of events that occurred in that checkpoint.

To verify that your endpoint is truly an archive node, try querying a checkpoint from a long time ago (e.g., sequence number 1) and an object version that is not the latest. If these succeed, your endpoint has historical data. If they fail with an error like Checkpoint not found or Object version not found, the endpoint is likely a full node with limited history.

The exact output shape follows the Sui JSON-RPC schema. For example, a checkpoint object looks like: { sequenceNumber: 1000, timestampMs: 1690000000000, epoch: 5, transactions: [...], ... }.

• Checkpoint sequence numbers are integers; use sui_getCheckpoint with the sequence number.
• Object versions are integers; use sui_getObject with the version parameter.
• Events are returned as an array of Event objects with id, type, and data fields.

Common Failures and Fixes When Querying Historical Data

When working with historical RPC, you may encounter errors due to pruning or incorrect usage. Here are common issues and how to resolve them.

Error: 'Checkpoint not found' – This means the checkpoint sequence number is beyond the node's retention horizon. If you are using a full node, switch to an archive endpoint. If you are running your own node, ensure pruning is disabled.

Error: 'Object version not found' – Similar to above, the node may not have the historical version. Use an archive node or query the latest version.

Error: 'Rate limit exceeded' – Historical queries can be heavy. Check your provider's rate limits and consider batching requests. See Sui RPC rate limits and compute units for guidance.

Error: 'Timeout' – Large queries may take time. Increase your client timeout or paginate results. See Sui RPC timeouts and retries.

• Always check the provider's documentation for retention policies.
• Use sui_getCheckpoints to paginate through checkpoints if you need a range.
• For event queries, use suix_queryEvents with a checkpoint range filter to avoid timeouts.

Decision Guide: Full Node RPC vs Archive RPC

Choosing between a full node and an archive node depends on your use case. If you only need current state, recent transactions, or live subscriptions, a full node is sufficient and more cost-effective. If you need to analyze historical trends, audit past state, or serve historical data to users, you need an archive node.

The table below summarizes the tradeoffs. Note that provider-specific availability and costs vary; always check with your provider.

• Use full node RPC for: live dApps, wallet balances, recent activity, and event subscriptions.
• Use archive RPC for: historical analytics, backtesting, compliance, and data services.
• Cost: Archive nodes are more expensive due to storage and compute. Pricing varies by provider; see RPC pricing for OnFinality's model.
• Retention: Full nodes may retain only the last few checkpoints; archive nodes retain all.

Next Steps and Further Reading

Now that you understand Sui archive nodes and historical RPC, you can explore more advanced topics. For endpoint selection, see the Sui RPC guidance. To optimize your queries, read about Sui RPC latency and performance and Sui RPC timeouts and retries. If you are building on Sui, check the Sui network overview and the OnFinality Learn hub for more tutorials.

For a deeper dive into Sui's data model, refer to the official Sui Archive Data documentation and the Sui Full Node Configuration guide.

• Explore Sui RPC rate limits and compute units to manage your usage.
• Consider using OnFinality's API service for managed archive nodes.
• Check the RPC pricing page for cost details.