迁移弃用的 Solana RPC 方法：getConfirmedBlock 和旧版 getConfirmed API 调用

直接回答：用规范方法和显式承诺级别替换 getConfirmed*

如果您的 Solana 客户端代码调用了 getConfirmedBlock、getConfirmedSignaturesForAddress2、getConfirmedTransaction 或 getConfirmedSlot，您必须迁移到规范的方法系列——getBlock、getSignaturesForAddress、getTransaction 和 getSlot——并传递显式的承诺级别（通常为 'confirmed'）以保留原始数据语义。旧版方法正在从当前的 Solana（Agave）版本中移除，移除后它们会返回 JSON-RPC -32601 "Method not found" 错误。迁移不仅仅是重命名：您还必须处理响应形状的差异（例如，版本化事务的 maxSupportedTransactionVersion），并验证您的 RPC 提供商是否仍然暴露旧版方法，因为某些中继已禁用它们。

本指南基于官方 Solana RPC 文档 以及截至发布参考时最新的弃用/移除列表。移除状态因链软件版本和提供商而异，因此请始终根据您的目标端点和 Solana JSON-RPC 方法参考 进行验证，而不是假设固定的全局日期。

• 旧版方法等同于当前系列，但内置了 'confirmed' 承诺语义。
• 较新的版本将这些方法合并为一个系列，该系列接受承诺参数。
• 一旦方法被移除，旧调用方将遇到 'Method not found' 错误。
• 迁移需要映射每个方法并添加显式承诺。
• 始终针对您的提供商进行测试；有些提供商可能在链软件移除之前就禁用了旧版方法。

为什么移除 getConfirmed* 方法

历史上，Solana 提供了并行的 'confirmed' 变体——getConfirmedBlock、getConfirmedSignaturesForAddress2、getConfirmedTransaction、getConfirmedSlot——它们等同于当前的 getBlock、getSignaturesForAddress、getTransaction 和 getSlot，但基于较旧的区块承诺语义。在 finalized/confirmed/processed 承诺模型和统一的 blockstore API 之前，这些方法提供了一种查询已达到特定确认级别的数据的方式。

随着协议的发展，承诺模型被统一：现在每个相关方法都接受一个 commitment 参数（或使用默认值）来指定您想要 processed、confirmed 还是 finalized 数据。冗余的后缀方法变得不必要并被弃用。当前的 Agave 版本正在移除它们，如官方 Solana RPC 'Removed RPC Methods' 列表 中所述。移除是更广泛清理的一部分，跟踪于 GitHub Issue #2859（独立来源）。

对于集成商来说，实际影响是，一旦方法被移除，针对旧 getConfirmed* 批次编写的代码将因 -32601 错误而中断。解决方法是切换到规范方法并显式传递 commitment: 'confirmed'（或适当的级别）以保持相同的数据语义。

• 旧方法等同于当前方法，但硬编码了 'confirmed' 承诺。
• 统一的承诺模型使冗余方法变得不必要。
• 移除正在当前的 Agave 版本中进行；请针对您的目标进行验证。
• 移除后，调用将返回 'Method not found' JSON-RPC 错误。

精确的方法映射和语义保留

下表显示了您必须应用的精确映射。关键是通过在方法接受的地方传递 commitment: 'confirmed' 来保留原始的 'confirmed' 语义。对于 getBlock，默认承诺是 'confirmed'，但显式指定更安全。

对于事务确认逻辑（例如，'我的已确认事务是否已上链？'），请使用 getSignatureStatuses 配合 searchTransactionHistory，或使用带承诺的 getTransaction。细微差别：processed 表示事务已被领导者接受，confirmed 表示区块已被投票，finalized 表示区块不可逆。选择与您的业务阈值匹配的承诺——对于大多数应用程序，confirmed 就足够了，但对于不可逆操作（例如，金融结算），请使用 finalized。

• 始终传递 commitment: 'confirmed' 以保留原始语义。
• 对于 getBlock，您可能需要 maxSupportedTransactionVersion 以避免版本化事务出错。
• 使用 getSignatureStatuses 或 getTransaction 进行确认状态检查。
• 理解 processed、confirmed 和 finalized 之间的区别，以选择正确的承诺。

实际迁移风险及处理方法

响应形状差异是最常见的陷阱。较旧的 getConfirmedBlock 可能以不同于现代 getBlock 的编码返回区块数据。例如，现代 getBlock 要求设置 maxSupportedTransactionVersion，如果区块包含版本化事务；否则会返回错误。此外，transactionDetails 和 rewards 参数会影响响应结构。始终防御性地解析响应。

提供商级别的差异：某些 RPC 提供商可能在链软件移除之前就禁用了旧版方法。这是中继配置的选择。始终检查提供商的文档或使用探针进行测试。OnFinality 的 API 服务 和 Solana RPC 端点 可能有特定策略；请与您的端点验证。

优雅的功能检测：实现一个探针，调用旧版方法并捕获 -32601 错误。如果失败，则路由到规范方法。这确保了您的代码在移除前后都能正常工作。

• 响应形状不同：处理 maxSupportedTransactionVersion 和 transactionDetails。
• 提供商可能禁用旧版方法；使用探针进行测试。
• 实现功能检测以优雅地回退。
• 使用防御性解析以避免意外字段导致崩溃。

可复现的迁移清单和代码示例

使用以下清单迁移您的代码库。然后针对您的端点运行下面的 Node.js 示例以验证行为。

迁移清单

1. 识别所有对 getConfirmedBlock、getConfirmedSignaturesForAddress2、getConfirmedTransaction、getConfirmedSlot 和旧版 getSignaturesForAddress 的调用。
2. 将每个调用替换为映射表中的规范方法。
3. 为每个调用添加 commitment: 'confirmed'（或您想要的级别）。
4. 对于 getBlock，添加 maxSupportedTransactionVersion: 0（或您支持的最高版本）以避免版本化事务错误。
5. 更新响应解析以处理新字段（例如，blockHeight、blockTime 可能为 null）。
6. 针对仍支持旧版方法的 devnet 或 testnet 端点进行测试，以比较响应。
7. 实现功能检测，以便在旧版方法不可用时回退到规范方法。
8. 部署并监控 -32601 错误。

• 预期输出：'Legacy method error: Method not found'（如果已移除），然后是已确认的插槽、区块高度、签名数量和事务状态。
• 在下面的结果表中填写您端点的行为。

// Node.js example using @solana/web3.js
const { Connection, clusterApiUrl } = require('@solana/web3.js');

// Replace with your endpoint
const endpoint = process.env.RPC_URL || clusterApiUrl('devnet');
const connection = new Connection(endpoint, 'confirmed');

async function probeLegacyMethod() {
  try {
    // Probe with a known slot (e.g., 0) - this will likely fail on modern nodes
    await connection.getConfirmedBlock(0);
    console.log('Legacy method available');
  } catch (err) {
    console.log('Legacy method error:', err.message);
  }
}

async function canonicalCalls() {
  // Get latest confirmed slot
  const slot = await connection.getSlot('confirmed');
  console.log('Confirmed slot:', slot);

  // Get block with maxSupportedTransactionVersion
  const block = await connection.getBlock(slot, {
    commitment: 'confirmed',
    maxSupportedTransactionVersion: 0
  });
  console.log('Block height:', block.blockHeight);

  // Get signatures for an address (example address)
  const address = 'Vote111111111111111111111111111111111111111';
  const signatures = await connection.getSignaturesForAddress(address, {
    limit: 1,
    commitment: 'confirmed'
  });
  console.log('Signatures count:', signatures.length);

  // Get transaction status for a signature (if any)
  if (signatures.length > 0) {
    const sig = signatures[0].signature;
    const status = await connection.getSignatureStatus(sig, { searchTransactionHistory: true });
    console.log('Transaction status:', status.value?.confirmationStatus);
  }
}

probeLegacyMethod().then(canonicalCalls).catch(console.error);

您环境的结果表

记录针对您的端点的探针和规范调用的结果。这有助于您为团队记录行为并验证迁移。

常见错误的失败/修复清单

迁移时，您可能会遇到特定错误。使用此清单进行诊断和修复。

• 错误 -32601 Method not found：旧版方法已被移除或禁用。切换到规范方法。
• 错误 -32602 Invalid params：您可能缺少必需的参数，例如 getBlock 的 maxSupportedTransactionVersion。请添加它。
• 错误 -32007 Slot skipped：您请求的插槽不可用（例如，由于跳过）。请使用其他插槽或优雅地处理错误。
• 错误 -32004 Block not available：区块尚未确认。请等待并重试，或使用较低的承诺。
• 版本化事务解析错误：确保将 maxSupportedTransactionVersion 设置为包含区块中事务版本的值。

• 始终检查确切的错误代码和消息。
• 有关处理瞬时错误，请参阅 Solana RPC 超时和重试 指南。
• 如果遇到速率限制，请参阅 Solana 速率限制和 429 错误。

迁移的限制和权衡

迁移很简单，但也有权衡。规范方法更灵活，但它们要求您明确承诺，如果您忘记传递它，可能会导致细微的错误。此外，响应形状并不完全相同；您可能需要更新数据解析逻辑。例如，getBlock 返回的 blockHeight 字段对于较旧的区块可能为 null，而 getTransaction 返回的 meta 对象如果事务被修剪则可能为 null。

另一个限制是并非所有提供商都支持相同的方法集。有些可能仍然为了向后兼容而暴露旧版方法，但这并不保证。始终在您的环境中进行测试。官方 Solana 文档和 Solana JSON-RPC 方法参考 是方法可用性的权威来源。

最后，移除时间表不是固定的；它取决于您目标链软件版本。截至本文日期（2026-09-06），弃用列表是最新的，但您应该根据节点的版本和提供商文档进行验证。

• 规范方法需要显式承诺；忘记它可能会默认使用 'finalized'，这可能不符合您的需求。
• 响应形状不同；更新解析逻辑。
• 提供商支持各不相同；使用探针进行测试。
• 移除时间表因版本而异；请与您的提供商验证。

后续步骤和进一步阅读

迁移后，通过查看相关最佳实践确保您的代码健壮。要更深入地了解 Solana 的数据模型，请参阅 Solana 版本化事务和 getBlock 解析。如果您要查询历史数据，通过 RPC 查询 Solana 历史数据 指南是必不可少的。

对于操作问题，请查看 Solana RPC 超时和重试 和 Solana 速率限制和 429 错误。如果您是 Solana RPC 的新手，请从 Solana JSON-RPC 方法（RPC 助手） 和 OnFinality 学习中心 开始。有关端点选择和定价，请参阅 RPC 定价 和 API 服务。

最后，始终参考官方 Solana RPC 文档 以获取最新的方法列表和弃用状态。

• 查看官方 Solana RPC 文档以获取最新的弃用列表。
• 使用 RPC 助手探索方法参数和示例。
• 在部署到主网之前，先在 devnet 上测试您的迁移。