¿Cómo se utiliza un directorio estilo Chainlist para encontrar redes RPC y endpoints compatibles?

Un directorio estilo Chainlist es una tabla de búsqueda para dos cosas que los desarrolladores necesitan constantemente: el ID de cadena de una red y uno o más endpoints RPC que hablan JSON-RPC para esa cadena. Cuando agregas una red personalizada a MetaMask, configuras un cliente viem o apuntas un indexador backend a una nueva cadena, realmente estás preguntando "¿cuál es el ID de cadena y a qué URL llamo?". Los directorios responden esa pregunta en un navegador en lugar de en documentos dispersos.

Esta página explica cómo se organizan esos directorios, cómo leer los metadatos que exponen, cómo verificar un endpoint antes de depender de él y cuándo una entrada de directorio público ya no es la herramienta adecuada para el trabajo.

Recomendación rápida: entrada de directorio vs endpoint gestionado

Usa una entrada de directorio público cuando estés explorando una cadena, probando una integración de billetera o escribiendo un script único. Usa una API RPC gestionada o un nodo dedicado cuando el endpoint esté en una ruta de solicitud de la que dependan usuarios reales.

La línea divisoria no es "mainnet vs testnet", sino si una solicitud fallida rompe algo que le importa a un usuario. Si una conexión caída significa una transacción fallida para un usuario que paga, una lista de directorio es la abstracción incorrecta.

Si ya pasaste la etapa de exploración, ve a redes RPC compatibles para ver qué cadenas están disponibles a través de un endpoint gestionado, y a precios de RPC para entender cómo se mide el uso.

Qué almacena realmente un directorio estilo Chainlist

Una entrada de directorio son metadatos estructurados, no solo una URL. Los campos que importan para la integración son consistentes en la mayoría de los directorios porque se asignan a los parámetros wallet_addEthereumChain de EIP-3085 que las billeteras ya entienden.

Un directorio es tan bueno como su última actualización. Los endpoints se retiran, los límites de tasa cambian y las cadenas se bifurcan. Trata cualquier listado como un punto de partida para la verificación, no como una garantía.

Cómo verificar un endpoint antes de confiar en él

La verificación es una breve secuencia de llamadas JSON-RPC. Ejecútalas contra cualquier endpoint que obtengas de un directorio antes de conectarlo a una aplicación.

# 1. Confirm the chain ID matches what the directory claims
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. Confirm the node is synced by comparing block height to a known source
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 3. Confirm the methods you actually need are supported
curl -s -X POST https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"latest"}]}'

El paso 3 es el que la gente omite. Un endpoint puede devolver un eth_chainId válido y aún rechazar eth_getLogs, debug_traceTransaction o consultas de archivo. Prueba los métodos exactos que llama tu aplicación, no solo el handshake.

Si estás configurando una billetera en lugar de un backend, los mismos datos van en un objeto de configuración de red:

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x38',
    chainName: 'BNB Smart Chain Mainnet',
    nativeCurrency: { name: 'BNB Chain Native Token', symbol: 'BNB', decimals: 18 },
    rpcUrls: ['https://bnb.api.onfinality.io/public'],
    blockExplorerUrls: ['https://bscscan.com'],
  }],
});

Mantén el ID de cadena, el símbolo, los decimales y la URL del explorador consistentes con la fuente que verificaste. Mezclar valores de dos directorios diferentes es una causa común de errores de "red incorrecta".

Leer correctamente una entrada de directorio

Cuando abras un listado, procésalo en este orden:

1. Coincide primero el ID de cadena. Los nombres son ambiguos: varias redes comparten nombres similares. El ID numérico es la fuente de verdad.
2. Verifica el transporte del endpoint. Algunas entradas son solo HTTP, otras exponen WebSocket, otras exponen ambos. Si tu aplicación necesita suscripciones en vivo, confirma el soporte de ws antes de comprometerte.
3. Anota cuántos endpoints se listan. Un solo endpoint es un único punto de fallo. Si el directorio lista varios, es una pista de que los mantenedores esperan rotación.
4. Revisa el enlace del explorador. Un explorador funcional es tu herramienta de depuración más rápida cuando una transacción se comporta de manera inesperada.
5. Busca una contraparte de testnet. Si estás construyendo, querrás una entrada de testnet con la misma estructura para poder ensayar despliegues.

Para cadenas donde necesitas un endpoint estable en todos los entornos, OnFinality expone endpoints de mainnet y testnet a través de la misma superficie de API, por lo que tu código de cliente no cambia entre ellos. Consulta BNB Chain y BNB Chain Testnet para ver un ejemplo de ese emparejamiento.

Cuando un endpoint listado falla

Los endpoints públicos fallan de maneras predecibles. Relaciona el síntoma con la causa antes de empezar a cambiar código.

La mayoría de estos no son errores en tu código. Son señales de que se le está pidiendo a un endpoint público compartido que haga trabajo de producción. La solución suele ser mover ese tráfico a un endpoint con capacidad definida y una ruta de soporte.

Directorio público vs API RPC gestionada vs nodo dedicado

Estas tres opciones se sitúan en un espectro que va de "gratuito y compartido" a "aislado y operado para ti". La elección correcta depende de cuánto de tu producto depende del endpoint.

OnFinality proporciona tanto un servicio de API RPC gestionado como nodos dedicados, para que puedas empezar en infraestructura compartida y mover cadenas específicas a nodos aislados a medida que crece la carga. La guía de selección de proveedor detalla los criterios de evaluación con más profundidad.

Una ruta de migración práctica

No tienes que moverlo todo a la vez. Un enfoque por etapas mantiene el riesgo bajo:

1. Inventario. Enumera cada cadena que toca tu aplicación y los métodos que llama. Anota cuáles necesitan datos de archivo, trazas o WebSocket.
2. Clasifica. Marca cada cadena como "exploración", "lectura de producción" o "escritura de producción". Solo las dos últimas necesitan infraestructura gestionada.
3. Prueba piloto con una cadena. Mueve una sola cadena de producción a un endpoint gestionado, mantén el público como respaldo y compara las tasas de error durante una semana.
4. Agrega conmutación por error. Configura un endpoint secundario para que una caída de un solo proveedor no derribe tu aplicación.
5. Expande. Mueve las cadenas de producción restantes una vez que el patrón piloto esté probado.

Mantén la entrada del directorio como documentación. Es útil para incorporar nuevos desarrolladores incluso después de que dejes de usar sus endpoints en producción.

Puntos clave

• Un directorio estilo Chainlist mapea IDs de cadena a endpoints RPC y los metadatos que las billeteras necesitan para agregar una red.
• Siempre verifica un endpoint con eth_chainId, eth_blockNumber y los métodos específicos que llama tu aplicación antes de confiar en él.
• Los endpoints de directorios públicos son suficientes para exploración y prototipos, pero carecen de garantías de capacidad para tráfico de producción.
• Relaciona el síntoma con la causa cuando un endpoint falla: la mayoría de los fallos son problemas de capacidad o soporte de métodos, no errores de código.
• Las API RPC gestionadas y los nodos dedicados te dan capacidad definida, visibilidad de uso y una ruta de soporte cuando el endpoint está en una ruta de solicitud crítica.
• Mantén el ID de cadena, el símbolo, los decimales y la URL del explorador consistentes en cada configuración que escribas.

Preguntas frecuentes

¿Un directorio estilo Chainlist es lo mismo que un proveedor de RPC?

No. Un directorio es una lista de referencia de endpoints aportados por varios operadores. Un proveedor de RPC opera los nodos detrás de un endpoint y ofrece capacidad, monitoreo y soporte. Los directorios te ayudan a descubrir endpoints; los proveedores te ayudan a ejecutarlos en producción.

¿Puedo usar un endpoint público de un directorio en producción?

Técnicamente sí, pero es riesgoso. Los endpoints públicos suelen ser compartidos y tener límite de tasa, sin garantías de disponibilidad o soporte de métodos. Para cualquier cosa orientada al usuario, usa un endpoint gestionado con capacidad definida y un respaldo.

¿Por qué un endpoint devuelve un ID de cadena válido pero falla en otras llamadas?

El ID de cadena es una llamada barata que casi cualquier nodo puede responder. Métodos como eth_getLogs, debug_traceTransaction o consultas de archivo requieren más recursos y pueden estar deshabilitados o limitados en nodos compartidos. Siempre prueba los métodos que tu aplicación realmente usa.

¿Cómo agrego una red a una billetera usando datos de un directorio?

Usa el método wallet_addEthereumChain con el ID de cadena, el nombre de la cadena, la moneda nativa, la URL RPC y la URL del explorador de la entrada del directorio. Verifica primero el ID de cadena, ya que los nombres pueden ser ambiguos.

¿Qué debo hacer cuando un endpoint listado empieza a devolver errores 429?

Eso generalmente significa que alcanzaste un límite de tasa compartido. Reduce el volumen de ráfaga si es posible, agrega un endpoint de respaldo y considera mover ese tráfico a una API RPC gestionada o a un nodo dedicado donde la capacidad esté definida.

¿OnFinality admite múltiples cadenas a través de una sola API?

OnFinality proporciona acceso a la API RPC en una variedad de redes. Consulta la página de redes RPC compatibles para ver la lista actual y precios de RPC para saber cómo se estructura el uso.