Migración de métodos RPC obsoletos de Solana: getConfirmedBlock y llamadas API getConfirmed heredadas

Respuesta directa: Reemplace getConfirmed* con métodos canónicos y compromiso explícito

Si su código de cliente de Solana llama a getConfirmedBlock, getConfirmedSignaturesForAddress2, getConfirmedTransaction o getConfirmedSlot, debe migrar a la familia de métodos canónicos (getBlock, getSignaturesForAddress, getTransaction y getSlot) y pasar un compromiso explícito (generalmente 'confirmed') para preservar la semántica de datos original. Los métodos heredados se están eliminando de las versiones actuales de Solana (Agave), y después de la eliminación devuelven un error JSON-RPC -32601 "Method not found". La migración no es solo un cambio de nombre: también debe manejar las diferencias en la forma de la respuesta (por ejemplo, maxSupportedTransactionVersion para transacciones versionadas) y verificar que su proveedor de RPC aún exponga los métodos heredados, ya que algunos relays los deshabilitan.

Esta guía se basa en la documentación oficial de RPC de Solana y en la lista de obsolescencia/eliminación vigente a la fecha de la referencia publicada. El estado de eliminación varía según la versión del software de la cadena y el proveedor, por lo que siempre verifique contra su endpoint de destino y la referencia de métodos JSON-RPC de Solana en lugar de asumir una fecha global fija.

• Los métodos heredados eran equivalentes a la familia actual pero con semántica de compromiso 'confirmed' incorporada.
• Las versiones más recientes los consolidan en una sola familia que toma un argumento de compromiso.
• Los llamadores antiguos reciben 'Method not found' una vez que el método se elimina.
• La migración requiere mapear cada método y agregar compromiso explícito.
• Siempre pruebe contra su proveedor; algunos pueden deshabilitar los métodos heredados incluso antes de la eliminación del software de la cadena.

Por qué se están eliminando los métodos getConfirmed*

Históricamente, Solana ofrecía variantes paralelas 'confirmed' (getConfirmedBlock, getConfirmedSignaturesForAddress2, getConfirmedTransaction, getConfirmedSlot) que eran equivalentes a los actuales getBlock, getSignaturesForAddress, getTransaction y getSlot, pero estaban basadas en semánticas de compromiso de bloque más antiguas. Antes del modelo de compromiso finalizado/confirmado/procesado y la API unificada de blockstore, estos métodos proporcionaban una forma de consultar datos que habían alcanzado un nivel de confirmación específico.

A medida que el protocolo evolucionó, el modelo de compromiso se unificó: cada método relevante ahora acepta un parámetro commitment (o usa un valor predeterminado) para especificar si desea datos processed, confirmed o finalized. Los métodos redundantes con sufijo se volvieron innecesarios y fueron obsoletos. Las versiones actuales de Agave los están eliminando, como se documenta en la lista oficial de 'Métodos RPC eliminados' de Solana. La eliminación es parte de una limpieza más amplia rastreada en GitHub Issue #2859 (fuente independiente).

Para los integradores, el impacto práctico es que el código escrito contra el lote antiguo getConfirmed* se romperá con un error -32601 una vez que el método se elimine. La solución es cambiar a los métodos canónicos y pasar explícitamente commitment: 'confirmed' (o el nivel apropiado) para mantener la misma semántica de datos.

• Los métodos antiguos eran equivalentes a los actuales pero con compromiso 'confirmed' codificado.
• El modelo de compromiso unificado hizo innecesarios los métodos redundantes.
• La eliminación está ocurriendo en las versiones actuales de Agave; verifique contra su objetivo.
• Después de la eliminación, las llamadas devuelven el error JSON-RPC 'Method not found'.

Mapeo exacto de métodos y preservación de semántica

La tabla a continuación muestra el mapeo exacto que debe aplicar. La clave es preservar la semántica original de 'confirmed' pasando commitment: 'confirmed' donde el método lo acepte. Para getBlock, el compromiso predeterminado es 'confirmed', pero es más seguro ser explícito.

Para la lógica de confirmación de transacciones (por ejemplo, '¿mi transacción confirmada llegó?'), use getSignatureStatuses con searchTransactionHistory o getTransaction con un compromiso. El matiz: processed significa que la transacción fue aceptada por el líder, confirmed significa que el bloque fue votado, y finalized significa que el bloque es irreversible. Elija el compromiso que coincida con su umbral comercial; para la mayoría de las aplicaciones, confirmed es suficiente, pero para trabajo irreversible (por ejemplo, liquidaciones financieras) use finalized.

• Siempre pase commitment: 'confirmed' para preservar la semántica original.
• Para getBlock, es posible que necesite maxSupportedTransactionVersion para evitar errores con transacciones versionadas.
• Use getSignatureStatuses o getTransaction para verificar el estado de confirmación.
• Comprenda la diferencia entre procesado, confirmado y finalizado para elegir el compromiso correcto.

Riesgos prácticos de migración y cómo manejarlos

Las diferencias en la forma de la respuesta son el error más común. El getConfirmedBlock más antiguo puede devolver datos de bloque en una codificación diferente a la del getBlock moderno. Por ejemplo, el getBlock moderno requiere que se establezca maxSupportedTransactionVersion si el bloque contiene transacciones versionadas; de lo contrario, devuelve un error. Además, los parámetros transactionDetails y rewards afectan la estructura de la respuesta. Siempre analice la respuesta de manera defensiva.

Diferencias a nivel de proveedor: algunos proveedores de RPC pueden deshabilitar los métodos heredados incluso antes de la eliminación del software de la cadena. Esto es una elección de configuración del relay. Siempre consulte la documentación de su proveedor o pruebe con una sonda. El servicio API de OnFinality y los endpoints RPC de Solana pueden tener políticas específicas; verifique con su endpoint.

Detección de características elegante: implemente una sonda que llame al método heredado y capture el error -32601. Si falla, enrute al método canónico. Esto asegura que su código funcione tanto antes como después de la eliminación.

• Las formas de respuesta difieren: maneje maxSupportedTransactionVersion y transactionDetails.
• Los proveedores pueden deshabilitar los métodos heredados; pruebe con una sonda.
• Implemente detección de características para retroceder elegantemente.
• Use análisis defensivo para evitar fallos en campos inesperados.

Lista de verificación de migración reproducible y ejemplo de código

Use la siguiente lista de verificación para migrar su código. Luego ejecute el ejemplo de Node.js a continuación contra su endpoint para verificar el comportamiento.

Lista de verificación de migración

1. Identifique todas las llamadas a getConfirmedBlock, getConfirmedSignaturesForAddress2, getConfirmedTransaction, getConfirmedSlot y getSignaturesForAddress heredado.
2. Reemplace cada una con el método canónico de la tabla de mapeo.
3. Agregue commitment: 'confirmed' (o su nivel deseado) a cada llamada.
4. Para getBlock, agregue maxSupportedTransactionVersion: 0 (o la versión más alta que soporte) para evitar errores de transacciones versionadas.
5. Actualice el análisis de la respuesta para manejar nuevos campos (por ejemplo, blockHeight, blockTime pueden ser nulos).
6. Pruebe contra un endpoint de devnet o testnet que aún soporte métodos heredados para comparar respuestas.
7. Implemente detección de características para retroceder a métodos canónicos si los métodos heredados no están disponibles.
8. Implemente y monitoree errores -32601.

• Salida esperada: 'Legacy method error: Method not found' (si se elimina), luego slot confirmado, altura de bloque, número de firmas y estado de transacción.
• Complete la tabla de resultados a continuación con el comportamiento de su endpoint.

// 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);

Tabla de resultados para su entorno

Registre los resultados de la sonda y las llamadas canónicas contra su endpoint. Esto le ayuda a documentar el comportamiento para su equipo y verificar la migración.

Lista de verificación de fallos/correcciones para errores comunes

Al migrar, puede encontrar errores específicos. Use esta lista de verificación para diagnosticarlos y corregirlos.

• Error -32601 Method not found: El método heredado se elimina o deshabilita. Cambie al método canónico.
• Error -32602 Invalid params: Puede estar faltando parámetros requeridos como maxSupportedTransactionVersion para getBlock. Agrégalo.
• Error -32007 Slot skipped: El slot solicitado no está disponible (por ejemplo, debido a omisión). Use un slot diferente o maneje el error con elegancia.
• Error -32004 Block not available: El bloque aún no está confirmado. Espere y reintente, o use un compromiso más bajo.
• Errores de análisis de transacciones versionadas: Asegúrese de establecer maxSupportedTransactionVersion a un valor que incluya la versión de las transacciones en el bloque.

• Siempre verifique el código de error exacto y el mensaje.
• Consulte la guía de tiempos de espera y reintentos de RPC de Solana para manejar errores transitorios.
• Si encuentra límites de velocidad, consulte límites de velocidad de Solana y errores 429.

Limitaciones y compensaciones de la migración

La migración es sencilla pero tiene compensaciones. Los métodos canónicos son más flexibles, pero requieren que sea explícito sobre el compromiso, lo que puede llevar a errores sutiles si olvida pasarlo. Además, las formas de respuesta no son idénticas; es posible que deba actualizar su lógica de análisis de datos. Por ejemplo, getBlock devuelve un campo blockHeight que puede ser nulo para bloques antiguos, y getTransaction devuelve un objeto meta que puede ser nulo si la transacción fue podada.

Otra limitación es que no todos los proveedores soportan el mismo conjunto de métodos. Algunos pueden aún exponer métodos heredados para compatibilidad hacia atrás, pero esto no está garantizado. Siempre pruebe en su entorno. La documentación oficial de Solana y la referencia de métodos JSON-RPC de Solana son las fuentes autorizadas para la disponibilidad de métodos.

Finalmente, el cronograma de eliminación no es fijo; depende de la versión del software de la cadena que tenga como objetivo. A la fecha de este artículo (2026-09-06), la lista de obsolescencia está vigente, pero debe verificar contra la versión de su nodo y la documentación del proveedor.

• Los métodos canónicos requieren compromiso explícito; olvidarlo predetermina a 'finalized' para algunos métodos, lo que puede no coincidir con sus necesidades.
• Las formas de respuesta difieren; actualice la lógica de análisis.
• El soporte del proveedor varía; pruebe con una sonda.
• El cronograma de eliminación varía según la versión; verifique con su proveedor.

Próximos pasos y lecturas adicionales

Después de migrar, asegúrese de que su código sea robusto revisando las mejores prácticas relacionadas. Para una comprensión más profunda del modelo de datos de Solana, consulte Transacciones versionadas de Solana y análisis de getBlock. Si está consultando datos históricos, la guía Consulta de datos históricos de Solana a través de RPC es esencial.

Para preocupaciones operativas, revise tiempos de espera y reintentos de RPC de Solana y límites de velocidad de Solana y errores 429. Si es nuevo en RPC de Solana, comience con Métodos JSON-RPC de Solana (Asistente de RPC) y el centro de aprendizaje de OnFinality. Para selección de endpoints y precios, consulte precios de RPC y el servicio API.

Finalmente, siempre consulte la documentación oficial de RPC de Solana para obtener la lista de métodos más actualizada y el estado de obsolescencia.

• Revise los documentos oficiales de RPC de Solana para obtener la lista de obsolescencia más reciente.
• Use el Asistente de RPC para explorar parámetros de métodos y ejemplos.
• Pruebe su migración en devnet antes de implementar en mainnet.