APIs blockchain en aplicaciones Web3
Qué hace una API blockchain en una aplicación Web3: leer datos de la cadena, enviar transacciones y recibir notificaciones, y por qué hacen falta oráculos.
Revisado por Maurice Sobiera
Una API blockchain es una interfaz web que permite a una aplicación leer datos de blockchain y enviar transacciones sin ejecutar su propio nodo. En una aplicación Web3 se sitúa entre la interfaz de usuario y la cadena. Los contratos inteligentes no pueden llamar por sí mismos a APIs web, así que los datos externos les llegan a través de oráculos.
Este artículo separa las dos direcciones en las que se conectan las APIs y las blockchains, y explica dónde se usa cada una.
¿Qué hace una API blockchain en una aplicación Web3?
Una API blockchain ofrece a una aplicación tres cosas: lee datos de la cadena, envía transacciones y notifica eventos. Sin ella, su backend tendría que ejecutar un nodo, mantenerlo sincronizado y analizar los bloques por su cuenta.
| Tarea | Ejemplo | Cómo funciona |
|---|---|---|
| Leer | Saldo de una dirección, transacciones de un bloque | Una petición a un nodo o a un proveedor de API |
| Escribir | Enviar una transferencia de token | La transacción se firma con una clave privada y después se difunde a la red |
| Notificar | Avisar al backend de que ha llegado un depósito | Un webhook, o consultas periódicas al nodo |
Chaingateway es una de estas APIs. Sus endpoints de wallets, transferencias y webhooks figuran en el archivo OpenAPI. Hay webhooks para Bitcoin, Ethereum, BNB Smart Chain, Polygon, Arbitrum y TRON. Solana no tiene webhooks, así que una aplicación en Solana tiene que consultar periódicamente.
¿Por qué un contrato inteligente no puede llamar a una API web?
Un contrato inteligente no puede llamar a una API web porque cada nodo debe ejecutarlo y llegar al mismo resultado. La documentación de Ethereum indica que incorporar datos externos haría imposible el determinismo: una API de precios podría devolver valores distintos a nodos distintos, y los nodos dejarían de coincidir en el estado de la cadena (ethereum.org: oráculos).
Esto es una propiedad del diseño. No depende del lenguaje de la cadena ni de una API concreta. La consecuencia es que los datos deben llegar a la cadena mediante una transacción antes de que un contrato pueda usarlos.
¿Cómo llegan los datos externos a un contrato inteligente?
Los datos externos llegan a un contrato a través de un oráculo. Un oráculo es una aplicación que obtiene, verifica y transmite información externa a los contratos inteligentes. Un protocolo de préstamos que necesita el precio de un activo, o un contrato que depende de datos meteorológicos o de vuelos, necesita uno.
La documentación de Ethereum describe dos diseños habituales:
- Publicación y suscripción: el oráculo publica un flujo de datos y los contratos lo leen. Encaja con datos que cambian con frecuencia, como los precios de los tokens.
- Petición y respuesta: un contrato solicita datos concretos, y el oráculo responde mediante un callback. Encaja con conjuntos de datos grandes de los que el contrato solo necesita una pequeña parte. Quien hace la petición paga la consulta y el gas del callback.
Un oráculo operado por una sola parte es un punto único de fallo. Si esa parte falla, es hackeada o miente, el contrato actúa con datos erróneos. La misma documentación describe los servicios de oráculos descentralizados, en los que varios participantes se ponen de acuerdo sobre los datos antes de que lleguen al contrato. La descentralización es un espectro, y aun así debe decidir cuánto confía en el oráculo que elija.
¿Qué API necesita para cada tarea?
La respuesta depende de la dirección del flujo de datos.
| Dirección | Problema | Herramienta |
|---|---|---|
| De la cadena a la aplicación | Leer saldos, enviar transferencias, recibir notificaciones de depósitos | API blockchain o su propio nodo |
| Del mundo exterior al contrato | Dar a un contrato un precio, una puntuación o un valor meteorológico | Oráculo |
| Del contrato al mundo exterior | Activar una acción tras un evento en la cadena | Logs de eventos leídos por un servicio, o un oráculo |
Un sistema de pagos usa solo la primera fila. Un usuario paga a una dirección, un webhook llega a su backend y su backend acredita la cuenta en su propia base de datos. No interviene ningún oráculo. Consulte blockchain frente a base de datos para ver cómo repartir el trabajo entre la cadena y su base de datos.
¿Cómo lee una aplicación los eventos de un contrato?
Una aplicación lee los eventos de los contratos a través de logs. Cuando un contrato emite un evento, el nodo lo guarda en el recibo de la transacción. El método eth_getLogs de la API JSON-RPC de Ethereum, que sigue la especificación JSON-RPC 2.0, devuelve los logs que coinciden con un filtro. Es la forma habitual de encontrar transferencias de tokens.
Un filtro para los eventos Transfer de ERC-20 de un token, en un rango de bloques, tiene este aspecto:
{ "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "fromBlock": "0x10d4f00", "toBlock": "0x10d4f0a", "address": "0xTokenContract", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }], "id": 1}El primer topic es el hash de la firma del evento Transfer(address,address,uint256). Los demás topics contienen los argumentos indexados, aquí el remitente y el destinatario. El importe está en el campo data de cada log, como número hexadecimal.
Los rangos de bloques importan. Muchos proveedores limitan el rango o el número de resultados de una llamada a eth_getLogs, así que un escáner tiene que paginar por bloques. Una API blockchain que decodifica esos logs por usted, o que los envía como webhooks, elimina ese código. No cambia, sin embargo, lo que significan los logs: un log de un bloque que después se reorganiza desaparece junto con ese bloque.
¿Cuáles son los límites de las APIs blockchain?
Una API no cambia el funcionamiento de la cadena. Una transacción solo es final cuando la cadena lo indica, y una API puede informar de ella como pendiente o confirmada antes de eso. Considere un depósito liquidado solo cuando hayan pasado las reglas de finalidad de la cadena.
Las entregas de webhooks fallidas no se reintentan automáticamente. Chaingateway las enumera en el endpoint de notificaciones fallidas de cada cadena, por ejemplo GET /api/v2/tron/webhooks/notifications/failed, y usted las reenvía con el endpoint de reintento. Un backend que procesa webhooks también debe ser idempotente, para que una notificación reenviada no acredite una cuenta dos veces.
Una API alojada además añade una dependencia del proveedor. Si necesita acceso directo al protocolo, puede seguir ejecutando un nodo y comunicarse con él mediante JSON-RPC.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.