NEAR Protocol JSON-RPC API 与节点搭建

NEAR 的分片架构与 JSON-RPC 接口

NEAR Protocol 是一个分片的、基于账户的 Layer 1 区块链，采用 Nightshade 风格的分片区块生产模型。与通过 eth_* 方法访问单一状态树的 EVM 链不同，NEAR 的状态被划分到多个分片中，其 JSON-RPC API 通过 status、block、chunk、gas_price、tx、query 和 validators 等方法体现这一点。这意味着现有的 EVM 工具和库无法直接使用；开发者必须适应 NEAR 的方法名和数据结构。

JSON-RPC 2.0 规范定义了请求/响应信封，而 NEAR 的 API 文档详细说明了方法语义。该 API 由 near-core 节点和托管服务商提供，NEAR Indexer Framework 和 NEAR Lake 等索引器服务则提供历史和聚合查询。普通节点能高效地提供近期数据，但历史查询可能需要归档节点。

• NEAR 使用分片状态，因此某些查询需要针对特定分片或分块进行解析。
• 方法名是 NEAR 特有的：status、block、chunk、gas_price、tx、query、validators。
• EVM 工具无法直接适用；需要使用 NEAR SDK 和库。

数据访问层：节点、服务商与索引器

访问 NEAR 数据主要有三种方式：(1) 自托管的 near-core 节点提供 JSON-RPC API，(2) 托管服务商提供相同的 API，(3) 索引器/归档服务用于历史和聚合查询。每种方式都有取舍。自托管节点让你完全掌控并实现数据本地化，但需要大量资源和维护。托管服务商提供便利性和可靠性，但可能有速率限制或费用。索引器服务对于查询超出节点保留窗口的历史数据至关重要。

对大多数开发者而言，托管服务商足以应对近期数据，但如果你需要查询旧区块或运行分析，则需要归档节点或索引器。NEAR 文档提供了 JSON-RPC API 和端点的介绍。

• 自托管节点：完全掌控，需要 Rust 工具链、CPU/内存/磁盘和同步时间。
• 托管服务商：便利，但需检查速率限制和数据保留策略。
• 索引器/归档：用于历史查询、聚合和分析。

关键 JSON-RPC 方法及其返回值

status 方法返回节点身份、链 ID、同步状态以及最新区块高度/哈希。block 和 chunk 按高度或哈希返回区块和分块数据，并支持最终性选项。gas_price 提供费用估算。tx 返回交易状态和收据。query 用于通过只读路径读取账户状态和调用合约视图方法。validators 返回当前验证者集合。

query 方法对于读取账户余额和合约状态尤为重要。根据 NEAR 关于 query 方法的文档，它支持账户和合约状态查询。理解这些方法对于构建可靠的应用程序至关重要。

• status：节点身份、链 ID、同步状态、最新区块高度/哈希。
• block/chunk：按高度/哈希返回区块和分块数据，支持最终性。
• gas_price：费用估算。
• tx：交易状态和收据。
• query：账户状态和合约视图调用。
• validators：当前验证者集合。

# Status: node identity, chain id and sync state
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}' | jq '.result.chain_id, .result.sync_info.latest_block_height'

# Block by finality: pass "final" or "optimistic" to choose the confirmation level
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"block","params":{"finality":"final"}}' | jq '.result.header.height, .result.header.hash'

# query: read account state or call a view method (read-only, no gas)
curl -s -X POST https://rpc.mainnet.near.org \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"query","params":{"request_type":"view_account","finality":"final","account_id":"near"}}' | jq '.result.amount, .result.block_height'

最终性：乐观最终性与最终最终性及其影响

NEAR 区分乐观最终性和最终最终性。当你查询区块或交易时，必须指定所需的最终性。乐观最终性意味着该区块很可能被最终确定，但尚未得到保证；最终最终性意味着该区块不可逆转。这会影响支付确认：对于高价值交易，应等待最终最终性。NEAR 最终性文档对此有详细说明。

选择错误的最终性可能导致对交易成功与否的错误判断。例如，以乐观最终性查询交易可能显示成功，但它仍可能被回滚。对于关键操作，始终使用最终最终性。

• 乐观最终性：区块很可能最终确定，但未获保证。
• 最终最终性：区块不可逆转。
• 支付确认和关键状态变更应使用最终最终性。

运行 NEAR 节点以提供 JSON-RPC API

要运行 NEAR 节点，需要从源码构建 near-core，这需要 Rust 工具链以及可观的 CPU、内存和磁盘资源。节点可以从创世块或从文档化的数据快照进行同步。同步完成后，它会在配置的端口（默认 3030）上暴露 JSON-RPC 端点。

该过程包括克隆 nearcore 仓库、使用 cargo 构建以及配置节点。详细说明可在 NEAR 文档中找到。对于熟悉其他协议的开发者，该设置类似于在其他网络上运行全节点，例如 Aptos 全节点要求与 RPC 设置 或 TON 节点与 RPC API 集成。

• 需要 Rust 工具链和大量硬件资源。
• 从创世块或快照同步（快照以信任换取速度）。
• 默认 JSON-RPC 端口为 3030。

验证 NEAR JSON-RPC 端点

要验证 NEAR JSON-RPC 端点是否在线且诚实，首先调用 status 并确认报告的 chain_id 和最新区块高度。然后按报告的高度调用 block 并确认哈希匹配。最后，对已知账户调用 query 以确认状态读取正常。这可以检测出在线但陈旧的端点。

你可以使用 curl 或 Node.js 脚本执行这些检查。下面是一个可运行的 Node.js 示例，它 POST 调用 status、block 和 query 方法，并打印返回的区块高度和账户余额。

const fetch = require('node-fetch');

async function checkEndpoint(url) {
  const statusRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'status', params: [] })
  });
  const status = await statusRes.json();
  console.log('Chain ID:', status.result.chain_id);
  console.log('Latest block height:', status.result.sync_info.latest_block_height);

  const blockRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'block', params: { finality: 'final' } })
  });
  const block = await blockRes.json();
  console.log('Block hash:', block.result.header.hash);

  const queryRes = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 3, method: 'query', params: { request_type: 'view_account', finality: 'final', account_id: 'example.near' } })
  });
  const query = await queryRes.json();
  console.log('Account balance:', query.result.amount);
}

checkEndpoint('https://rpc.mainnet.near.org');

使用结果表进行可复现的端点验证

为使验证可复现，请为你的端点记录以下指标：报告的 chain_id、T0 和 T1 时的最新高度、使用的最终性以及查询延迟。用你自己的测量值填写下表。此方法不依赖虚构的数字，并允许你客观地比较端点。

• 链 ID：[你的值]
• T0 时的最新高度：[你的值]
• T1 时的最新高度：[你的值]
• 使用的最终性：[乐观/最终]
• 查询延迟（毫秒）：[你的值]

常见故障与故障排除

使用 NEAR JSON-RPC 时，当区块尚未最终确定，你可能会遇到 UNKNOWN_BLOCK 或 'does not exist while viewing' 等错误。在未完全同步的节点上，gas_price 调用可能会失败。在非归档节点上，归档或旧版查询可能会失败。这些问题通常源于最终性选择或节点同步状态。

要进行故障排除，请确保使用正确的最终性参数，检查节点是否已完全同步，并确认你正在查询归档节点以获取历史数据。有关 JSON-RPC 故障排除的通用信息，请参阅 JSON-RPC vs gRPC vs REST。

• UNKNOWN_BLOCK：区块尚未最终确定；使用最终最终性或等待。
• 'does not exist while viewing'：该区块上账户或合约状态不可用。
• gas_price 失败：节点未完全同步。
• 归档查询失败：节点不是归档节点。

自托管节点的取舍与局限

运行自托管 NEAR 节点涉及取舍。分片状态意味着某些查询需要针对特定分片或分块进行解析，这会使数据聚合复杂化。基于快照的同步以信任换取速度，因为你依赖快照提供者。只有当查询量或数据本地化需求超过托管端点时，自托管节点才具有合理性。

对许多开发者而言，托管服务商更具成本效益且更可靠。然而，如果你需要完全控制、自定义索引或对特定分片的低延迟访问，自托管节点可能是必要的。在决定运行节点之前，请仔细考虑你的用例。

• 分片状态：查询可能需要针对特定分片。
• 快照同步：更快，但需要信任快照提供者。
• 自托管：在高查询量或数据本地化需求下具有合理性。

后续步骤与更多资源

要继续了解 NEAR 和其他协议，请探索 OnFinality Learn 中心。有关定价和 API 服务详情，请参阅 RPC 定价 和 API 服务。如果你对其他网络感兴趣，请查看 Polkadot 网络指南 和 Substrate state_getMetadata 与运行时版本。

对于 NEAR 特定开发，请参阅官方 NEAR 文档，并考虑在生产工作负载中使用托管服务商。自托管是满足特定需求的高级用户的一个选项。

• 探索 OnFinality Learn 获取更多协议指南。
• 查看 RPC 定价和 API 服务页面了解托管选项。
• 查阅其他网络的同类指南。