TON 节点与 RPC API：连接 The Open Network

TON 架构与分片链模型

TON 不是一条单一的线性链。它由一条主链（masterchain）组成，用于存储协议状态和验证者信息，外加一条或多条工作链（workchain），每条工作链还可以进一步划分为分片链（shardchain）。这意味着当你查询一个账户时，节点必须解析该账户位于哪个分片和工作链中。地址携带工作链 ID，对于分片还携带分片前缀，因此心智模型是许多条链，而不是一条链。

这种分片设计正是 TON 节点和 API 与 EVM JSON-RPC 端点不同的原因。通用的 EVM 端点可以为任意地址回答 eth_getBalance，无需分片解析，因为只有一条规范链。在 TON 中，节点必须首先确定正确的分片，而分片信息编码在地址中。TON 网络页面概述了这些组件。

异步执行模型进一步使 TON 与众不同。交易是消息，可以触发其他消息，执行可能跨越多个区块。不存在返回复杂交互最终状态的同步回执。相反，你通过轮询相关账户的交易历史来观察确认。TON 文档中关于消息与交易的内容详细解释了这一模型。

• 主链（Masterchain）：存储协议状态、验证者集合和配置。
• 工作链（Workchains）：拥有自己规则的独立链；至少存在一条用于智能合约的工作链。
• 分片链（Shardchains）：工作链的细分，并行处理账户。
• 地址格式：工作链 ID + 账户哈希，有时带有用于内部路由的分片前缀。

节点角色：验证者、全节点与 Liteserver

验证者通过参与共识来保护网络。验证者必须质押 TON、保持资格并管理密钥。运行验证者与提供 API 查询是两项独立的运维工作。相比之下，全节点同步链，并可以通过 liteserver 协议提供查询。启用 liteserver 的节点暴露一个二进制 TCP 接口，客户端可以用它请求区块、账户状态和 run 方法。

TON 文档中关于运行全节点的内容描述了设置过程和 liteserver 配置。对于大多数应用开发者来说，不需要运行全节点；相反，他们连接到一个封装了 liteserver 的 HTTP API。这种关注点分离意味着你可以选择提供商提供的托管端点，而不必自己运营基础设施。

如果你确实要运营节点，节点故障排除指南涵盖了同步停滞和端口配置等常见问题。关键要点是 liteserver 协议是二进制且特定于提供商的，因此除基础设施团队外，直接集成很少见。

• 验证者：需要质押、密钥管理和资格；保护共识。
• 全节点：同步链，并可启用 liteserver 进行查询。
• Liteserver：用于直接节点查询的二进制 TCP 协议。
• HTTP API：围绕 liteserver 的 JSON over HTTP 封装，被大多数应用使用。

API 层：Liteserver、HTTP 封装与索引器 API

实际中有三种 API 层。第一，基于 TCP 的 liteserver 协议是自托管节点直接暴露的接口。它高效但是二进制且不可读。第二，HTTP API 封装层以 JSON over HTTP 与 liteserver 通信；这是大多数应用集成的对象。TON Center 及类似服务提供 v2 和 v3 HTTP API。第三，索引器或浏览器 API 提供历史和聚合查询，通常对交易和消息有额外索引。

v3 HTTP API 是新项目当前推荐的接口。它暴露了 run 方法执行、账户状态、交易历史、区块查询和发送 BOC（bag of cells）等方法。带密钥的请求使用 API key 请求头以获得更高的速率限制。v2 API 是旧版，新项目应避免使用。关于协议风格的比较，请参阅 JSON-RPC vs gRPC vs REST。

选择端点时，要考虑是否需要历史深度。由索引器支持的 API 可以提供深层历史，但仅支持 liteserver 的端点可能只保留最近的区块。访问历史区块链数据一文讨论了归档要求。对于 TON 专用端点，TON RPC 端点页面列出了托管选项。

• Liteserver：二进制 TCP，直接节点访问，特定于提供商。
• HTTP API v3：JSON over HTTP，推荐用于新集成。
• HTTP API v2：旧版，新项目应避免。
• 索引器 API：历史和聚合查询，可能需要归档节点。

实用集成接口：v3 HTTP API 方法

v3 HTTP API 暴露了一组覆盖常见集成需求的方法。对于账户状态，你可以调用 getAddressInformation 或 getAccountState 来获取余额、状态和代码哈希。对于 run 方法执行，runGetMethod 允许你调用智能合约的 get 方法而无需发送交易。对于交易历史，getTransactions 返回账户的交易列表。对于区块查询，getBlockHeader 和 getMasterchainInfo 提供区块元数据。对于发送消息，sendBoc 接受 base64 编码的 BOC。

带密钥的请求使用 API key 请求头，通常是 X-API-Key，用于认证并获得更高的速率限制。没有密钥时，公共端点可能会施加严格限制。确切的请求头名称和速率限制因提供商而异，因此请查阅提供商的文档。OnFinality 的 API 服务提供支持 API key 的托管 TON 端点。

构造请求时，注意地址格式。API 可能同时接受用户友好格式和原始格式，但某些方法要求特定格式。在发送请求前始终验证地址，以避免错误。

• getMasterchainInfo：返回最新主链区块 seqno 和分片。
• getAddressInformation：返回账户余额、状态和代码。
• runGetMethod：在合约上执行 get 方法。
• getTransactions：返回账户的交易历史。
• sendBoc：广播已签名的外部消息。

TON 中的地址格式与消息语义

TON 地址通常有两种表示形式：用户友好格式（base64url）和原始格式（workchain:hash）。用户友好格式包含校验和与标志，在显示和输入时更安全。原始格式是 64 位工作链 ID 后跟 256 位账户哈希，通常写作 workchain:hex_hash。在两者之间转换需要谨慎，因为用户友好格式使用特定标签和校验和来编码工作链和哈希。

TON 中的转账是异步消息。外部入消息（external-in message）发起一笔交易，该交易可能产生发往其他账户的内部消息。不存在返回最终结果的同步回执。相反，你必须轮询目标账户的交易历史，以确认消息已被处理。这与 EVM 链有根本区别，在 EVM 中交易回执在挖矿后立即返回。

TON 文档中关于消息与交易的内容提供了该模型的权威解释。集成时，设计你的应用以处理异步确认，例如轮询目标地址的 getTransactions，直到预期交易出现。

• 用户友好地址：带校验和的 base64url，例如 EQD...。
• 原始地址：workchain:hash，例如 0:abc...。
• 外部入消息：从链外发起一笔交易。
• 内部消息：在账户之间发送，可能触发进一步交易。
• 确认：通过轮询交易历史观察，而非同步回执。

使用主链信息验证端点存活

在深入集成之前，验证你选择的端点是否正在提供实时数据。像 getMasterchainInfo 这样的轻量方法返回最新主链区块 seqno。如果 seqno 随时间推进，则端点正在同步并提供当前数据。你还可以读取账户状态，并确认最后交易时间是最近的。

以下 curl 示例从 TON HTTP API 端点查询主链头部信息。将 YOUR_API_KEY 和基础 URL 替换为你的提供商详情。响应包含 seqno，你可以跨调用比较以确认存活。

如需更彻底的检查，查询一个活跃账户的状态和一个 run 方法结果。下一节提供了一个 Node.js 示例，可完成全部三项检查。

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://toncenter.com/api/v3/masterchainInfo" | jq '.result.last.seqno'

可运行的 Node.js 示例：主链、账户状态与 Run 方法

这个 Node.js 脚本从 TON HTTP API 端点查询主链头部、账户状态和 run 方法结果。它使用内置的 fetch API（Node.js 18+）。将 YOUR_API_KEY 和基础 URL 替换为你的提供商详情。脚本会打印主链 seqno、账户状态和方法结果。

该示例还对比了用户友好地址与其原始形式。你可以使用 @ton/core 等库在两者之间转换，但为了演示，我们展示两个字符串。原始形式通过解码 base64url 并提取工作链和哈希从用户友好形式派生。

运行脚本并观察输出。如果主链 seqno 是一个大数字且账户状态为 active，则端点正在提供实时数据。如果 run 方法返回结果，则合约可调用。

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://toncenter.com/api/v3';
const USER_FRIENDLY = 'EQD...'; // replace with a real address
const RAW = '0:...'; // replace with the raw form

async function main() {
  const headers = { 'X-API-Key': API_KEY };

  // 1. Masterchain info
  const mc = await fetch(`${BASE_URL}/masterchainInfo`, { headers }).then(r => r.json());
  console.log('Masterchain seqno:', mc.result.last.seqno);

  // 2. Account state (user-friendly)
  const state = await fetch(`${BASE_URL}/addressInformation?address=${USER_FRIENDLY}`, { headers }).then(r => r.json());
  console.log('Account status:', state.result.status);
  console.log('Balance (nanotons):', state.result.balance);

  // 3. Run-method (raw address)
  const run = await fetch(`${BASE_URL}/runGetMethod?address=${RAW}&method=seqno`, { headers }).then(r => r.json());
  console.log('Run-method result:', run.result.stack);
}

main().catch(console.error);

针对你的端点的可复现结果表

为了系统地验证端点，请用你的观察结果填写下表。使用上述方法。该表帮助你比较提供商并发现不一致。记录端点 URL、调用的方法、预期字段、观察值以及任何备注（如延迟或错误）。

对于每个方法，至少调用两次并间隔短暂延迟，以查看值是否推进。对于 getMasterchainInfo，seqno 应该增加。对于 getAddressInformation，如果账户活跃，余额可能变化。对于 runGetMethod，对于确定性方法，结果应该一致。

这种方法是可复现的，不依赖捏造的基准。它是一种由读者验证的方法：你针对自己的端点进行测量并记录结果。

• 方法：getMasterchainInfo | 预期字段：result.last.seqno | 观察值：[填写] | 备注：[填写]
• 方法：getAddressInformation | 预期字段：result.status | 观察值：[填写] | 备注：[填写]
• 方法：runGetMethod | 预期字段：result.stack | 观察值：[填写] | 备注：[填写]
• 方法：getTransactions | 预期字段：result.length | 观察值：[填写] | 备注：[填写]

TON 节点与 API 集成的局限性与权衡

liteserver 协议是二进制且特定于提供商的，因此大多数团队使用 HTTP 封装层，而不是直接与之通信。这增加了对封装层可用性和速率限制的依赖。v2 API 是旧版，新项目应避免使用，转而使用 v3。历史深度取决于端点的索引器；深层历史可能需要支持归档的提供商，如归档节点 vs 全节点中所讨论。

在公共端点上，要获得有意义的速率限制需要 API key。没有密钥时，你可能会遇到限流。TON 的异步消息模型意味着“交易成功”必须从交易历史中推导，而不是来自同步回执。这给习惯 EVM 风格回执的开发者带来了集成复杂性。

最后，地址转换错误可能导致资金损失或查询失败。始终验证地址，并使用经过充分测试的库进行转换。Bittensor RPC 节点指南提供了另一个生态系统中节点集成模式的比较。

• Liteserver：二进制、特定于提供商，很少直接集成。
• v2 API：旧版，新项目应避免。
• 历史深度：取决于索引器；深层历史需要归档提供商。
• API key：获得更高速率限制所必需。
• 异步模型：通过轮询确认，而非同步回执。

TON API 集成常见问题排查

如果 getMasterchainInfo 返回过时的 seqno，端点可能未同步或受到速率限制。检查你的 API key 并尝试另一个端点。如果 runGetMethod 失败，确保地址格式正确且方法名正确。某些方法需要参数；在请求体中作为数组传递。

如果 sendBoc 返回错误，验证 BOC 是否正确进行 base64 编码并签名。外部消息必须具有有效的签名和序列号。如果交易未出现在 getTransactions 中，消息可能尚未被处理；等待并再次轮询。节点故障排除指南涵盖了节点侧问题。

对于速率限制错误，降低请求频率或升级到更高层级。OnFinality 的 RPC 定价页面列出了可用方案。始终使用指数退避处理 HTTP 429 响应。

• Seqno 过时：检查同步状态和 API key。
• Run 方法失败：验证地址格式和方法名。
• SendBoc 错误：检查 BOC 编码和签名。
• 交易缺失：延迟后再次轮询。
• 速率限制：使用 API key 并对 429 进行退避。

TON 集成的后续步骤

要向前推进，请从支持 v3 API 且具有足够历史深度的提供商处选择托管的 TON 端点。TON RPC 端点页面列出了选项。如果你需要运行自己的节点，请遵循全节点指南并启用 liteserver。

对于应用开发，从 v3 HTTP API 开始，并使用上面的可运行示例验证连接性。实现轮询以确认交易，并处理异步消息流。浏览 OnFinality Learn 中心获取更多区块链集成指南。

最后，考虑你的归档需求。如果你需要深层历史，请选择支持归档的提供商。访问历史区块链数据一文解释了其中的权衡。通过这些步骤，你可以可靠地将 TON 集成到你的应用中。

• 选择支持 v3 API 和 API key 的托管端点。
• 如果需要直接 liteserver 访问，请运行自己的节点。
• 实现轮询以进行异步确认。
• 为深层历史选择归档提供商。
• 参考 OnFinality Learn 获取更多集成指南。