Sui 归档节点与历史 RPC：检查点、纪元与查询过去状态

什么是 Sui 归档节点以及如何访问历史状态？

Sui 归档节点是一个保留所有历史检查点和状态的全节点，允许您在任何时间点查询网络的过去状态。与仅保留最新状态并修剪旧数据的标准全节点不同，归档节点存储自创世以来的每个检查点。您可以通过 Sui 的 JSON-RPC API（如 sui_getCheckpoint 和带历史版本的 sui_getObject）访问这些历史数据，或者运行自己的归档节点。本指南解释了机制，并展示了如何可靠地查询过去状态。

Sui 的数据模型与基于 EVM 的链有根本不同。Sui 使用对象和检查点，而不是区块和交易。检查点是验证者已达成一致的交易序列，作为最终性的点。纪元是基于时间的时期，在此期间验证者集合是固定的。理解这些概念是处理历史数据的关键。

• 对象：状态的基本单位，由地址拥有或共享。每个对象都有一个版本号，每次被修改时递增。
• 检查点：已经认证并提交的一批交易。检查点从创世（序列号 0）开始按顺序编号。
• 纪元：一段时间（例如 24 小时），在此期间验证者集合是固定的。纪元边界由特殊检查点标记。
• 全节点：仅存储最新状态和有限的历史（例如最近的检查点）以节省磁盘空间。
• 归档节点：保留所有历史检查点和状态，支持查询任何过去的检查点或对象版本。

Sui 如何存储历史数据：检查点、纪元与对象版本

Sui 的共识产生一系列检查点。每个检查点包含交易列表和产生的状态更改。状态由对象组成，每个对象具有唯一的 ID 和版本号。当对象被修改时，其版本递增。全节点在其数据库中保留每个对象的最新版本，但可能会修剪旧版本和检查点以管理磁盘使用。

另一方面，归档节点存储每个检查点和每个对象的每个版本。这允许您查询特定历史版本的对象状态，或检索特定检查点范围内发生的事件。Sui 文档中的 Sui 归档数据 说明，归档节点对于需要审计过去状态或提供历史查询的应用程序至关重要。

纪元边界很重要，因为它们影响验证者集合和 gas 参数。您可以按序列号或纪元查询检查点。例如，sui_getCheckpoint 接受检查点 ID 或序列号，您也可以使用 sui_getCheckpoints 分页遍历范围内的检查点。

• 检查点序列号是从 0 开始的单调递增整数。
• 每个纪元有开始和结束检查点。纪元的第一个检查点通常用于标记纪元更改。
• 对象版本是每个对象独立的，每次写入时递增。您可以使用 sui_getObject 的 version 参数查询特定版本。
• 事件按检查点索引，可以使用 suix_queryEvents 和检查点范围过滤器进行查询。

全节点与归档节点：可以使用哪些 RPC 方法？

全节点和归档节点之间的关键区别在于保留期限。全节点通常只保留最新的检查点和少数最近的检查点，而归档节点保留所有。这会影响哪些 RPC 调用成功。例如，在全节点上使用旧的序列号调用 sui_getCheckpoint 可能会返回错误，如果该检查点已被修剪。类似地，如果全节点不再有旧版本，查询旧版本的对象可能会失败。

Sui 文档中的 Sui 全节点配置 描述了 checkpoint-pruning 和 object-pruning 配置选项。默认情况下，全节点会修剪旧数据，但您可以配置它们保留更多数据，或通过禁用修剪来运行归档节点。

当您使用 RPC 提供商时，历史数据的可用性取决于他们是否运行归档节点。一些提供商提供具有完整历史数据的归档端点，而其他提供商仅提供全节点访问。始终检查提供商的文档以了解保留策略。

• 全节点 RPC：适用于当前状态查询、近期交易和实时订阅。历史查询仅限于短窗口（例如最近 100 个检查点）。
• 归档节点 RPC：支持查询任何检查点、对象版本或历史事件。非常适合分析、审计和回填。
• 提供商支持：因提供商而异。一些提供商将归档端点作为高级功能提供。请参阅 Sui RPC 指南 选择端点。

运行自己的 Sui 归档节点：存储与配置

如果您希望运行自己的归档节点，则需要配置 Sui 全节点以禁用修剪。Sui 文档提供了 fullnode.yaml 配置文件，您可以在其中将 checkpoint-pruning 和 object-pruning 设置为 false。这将导致节点保留所有历史数据。

存储需求很大：归档节点存储所有历史检查点和对象版本，数据集随着网络活动持续增长。确切大小因提供商、保留策略和时间点而异，因此请将任何数字视为提供商记录的，而不是固定常量，并对照官方来源或您自己的节点磁盘使用情况进行验证。

运行归档节点还需要更多的 CPU 和内存来处理历史数据查询。您应确保基础设施满足推荐规格，这些规格在 Sui 全节点配置 指南中有记录。

• 在节点配置中将 checkpoint-pruning 和 object-pruning 设置为 false。
• 定期监控磁盘使用情况；归档节点持续增长。
• 考虑使用快照来更快地引导节点，但请注意，除非是归档快照，否则快照可能不包含完整历史。
• 对于托管选项，请参阅 OnFinality 的 API 服务 或其他提供归档节点的提供商。

使用 @mysten/sui.js 查询历史状态：可运行示例

以下 Node.js 脚本演示了如何使用官方 @mysten/sui.js SDK 查询历史数据。它连接到 Sui RPC 端点（替换为您的归档端点），按序列号获取检查点，检索特定版本的对象，并查询检查点范围内的事件。

在运行之前，安装 SDK：npm install @mysten/sui.js。该脚本假定您有一个支持归档的端点。如果没有，您可以使用支持归档数据的公共端点（例如，来自提供归档访问的提供商）。

脚本输出检查点详细信息、对象内容和事件。这是一种可重现的方法，用于验证您的端点是否提供历史数据。

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

// 替换为您的归档端点 URL
const RPC_URL = 'https://your-archive-endpoint.example.com';
const client = new SuiClient({ url: RPC_URL });

async function main() {
  // 1. 按序列号获取检查点（例如 1000）
  const checkpointSeq = 1000;
  const checkpoint = await client.getCheckpoint({ id: checkpointSeq });
  console.log('Checkpoint:', checkpoint);

  // 2. 获取特定版本的对象（替换为真实对象 ID 和版本）
  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. 查询检查点范围内的事件（例如从 1000 到 1010）
  const events = await client.queryEvents({
    query: { Checkpoint: { checkpoint: checkpointSeq } },
    limit: 10
  });
  console.log('Events:', events.data);
}

main().catch(console.error);

预期输出与验证

当您运行脚本时，您应该看到打印的检查点对象，其中包含 sequenceNumber、timestampMs、epoch 和 transactions 等字段。如果版本存在，对象查询将返回对象内容；如果不存在，将抛出错误，指示对象版本不可用。事件查询将返回该检查点中发生的事件列表。

要验证您的端点是否真正是归档节点，请尝试查询很久以前的检查点（例如序列号 1）和不是最新的对象版本。如果这些成功，则您的端点具有历史数据。如果它们失败并出现类似 Checkpoint not found 或 Object version not found 的错误，则端点可能是历史有限的全节点。

确切的输出形状遵循 Sui JSON-RPC 模式。例如，检查点对象看起来像：{ sequenceNumber: 1000, timestampMs: 1690000000000, epoch: 5, transactions: [...], ... }。

• 检查点序列号是整数；使用 sui_getCheckpoint 和序列号。
• 对象版本是整数；使用 sui_getObject 和 version 参数。
• 事件作为 Event 对象数组返回，包含 id、type 和 data 字段。

查询历史数据时的常见失败与修复

在使用历史 RPC 时，您可能会遇到由于修剪或错误使用导致的错误。以下是常见问题及解决方法。

错误：'Checkpoint not found' – 这意味着检查点序列号超出了节点的保留期限。如果您使用全节点，请切换到归档端点。如果您运行自己的节点，请确保禁用修剪。

错误：'Object version not found' – 与上述类似，节点可能没有历史版本。使用归档节点或查询最新版本。

错误：'Rate limit exceeded' – 历史查询可能很重。检查提供商的速率限制，并考虑批量请求。请参阅 Sui RPC 速率限制和计算单位 获取指导。

错误：'Timeout' – 大型查询可能需要时间。增加客户端超时或分页结果。请参阅 Sui RPC 超时和重试。

• 始终检查提供商的文档以了解保留策略。
• 如果需要范围，使用 sui_getCheckpoints 分页遍历检查点。
• 对于事件查询，使用 suix_queryEvents 和检查点范围过滤器以避免超时。

决策指南：全节点 RPC 与归档 RPC

在全节点和归档节点之间选择取决于您的用例。如果您只需要当前状态、近期交易或实时订阅，全节点就足够了，并且更具成本效益。如果您需要分析历史趋势、审计过去状态或向用户提供历史数据，则需要归档节点。

下表总结了权衡。请注意，提供商特定的可用性和成本各不相同；始终与您的提供商核实。

• 使用全节点 RPC 用于：实时 dApp、钱包余额、近期活动和事件订阅。
• 使用归档 RPC 用于：历史分析、回测、合规性和数据服务。
• 成本：由于存储和计算，归档节点更昂贵。定价因提供商而异；请参阅 RPC 定价 了解 OnFinality 的模型。
• 保留：全节点可能仅保留最后几个检查点；归档节点保留所有。

后续步骤与进一步阅读

既然您了解了 Sui 归档节点和历史 RPC，您可以探索更高级的主题。有关端点选择，请参阅 Sui RPC 指南。要优化查询，请阅读 Sui RPC 延迟和性能 和 Sui RPC 超时和重试。如果您在 Sui 上构建，请查看 Sui 网络概述 和 OnFinality Learn 中心 获取更多教程。

要深入了解 Sui 的数据模型，请参阅官方 Sui 归档数据文档 和 Sui 全节点配置指南。

• 探索 Sui RPC 速率限制和计算单位 以管理您的使用。
• 考虑使用 OnFinality 的 API 服务 获取托管归档节点。
• 查看 RPC 定价 页面了解成本详情。