API de eventos de contratos inteligentes: leer, filtrar y suscribirse

Registros de eventos pasando a través de un filtro hacia dos rutas

Una API de eventos de contratos inteligentes permite a su aplicación averiguar qué hizo un contrato sin tener que escanear cada transacción por sí misma. Consulta logs pasados por dirección de contrato y firma de evento, y luego se suscribe a los nuevos a medida que llegan los bloques. Puede hacer ambas cosas a través de RPC de nodo en bruto, mediante una biblioteca como ethers.js, o a través de una API alojada que decodifica los logs y se los envía como webhooks. Esta guía explica cómo funciona cada camino, dónde falla cada uno y cómo elegir.

TL;DR

Un evento de contrato es una entrada de log escrita cuando se mina una transacción. Su aplicación la lee después. El propio contrato no puede leerla.
Los eventos pasados provienen de una consulta de logs (eth_getLogs o queryFilter). Los eventos en vivo provienen de una suscripción o un webhook. Las suscripciones de nodo no reproducen el historial.
Solo los parámetros indexados pueden usarse como filtros. La decodificación requiere el ABI del contrato.
Las suscripciones WebSocket mueren con la conexión y pueden descartarse si procesa demasiado lento. Los webhooks con una cola y manejadores idempotentes sobreviven mejor a los reinicios.
Una API alojada elimina el trabajo del nodo, el ABI y la reconexión. Eso es lo que hace Chaingateway para eventos de pagos y tokens.

Tabla de Contenidos

Qué es un evento de contrato inteligente
Qué hay dentro de un log de evento
Lectura de eventos pasados
Suscripción a nuevos eventos
Reorgs y confirmaciones
Webhooks, WebSockets o sondeo
Configuración del monitoreo de eventos paso a paso
Eventos entre cadenas
Construirlo usted mismo o usar una API alojada
Nuestra perspectiva
Obtener eventos sin ejecutar nodos
Preguntas frecuentes
Fuentes

Qué es un evento de contrato inteligente

Los eventos son cómo un contrato habla con el mundo exterior. Según ethereum.org, los eventos permiten que un contrato se comunique con un frontend u otras aplicaciones suscritas, que pueden procesar la información registrada después de que la transacción es validada y añadida a un bloque.

Siguen tres consecuencias, y explican la mayor parte de la confusión en los resultados de búsqueda:

Los eventos son salida, no almacenamiento que se pueda consultar desde Solidity. El código del contrato escribe logs pero no puede leerlos de vuelta. Por eso los hilos que preguntan cómo un contrato puede acceder a eventos pasados siempre terminan con “hágalo off-chain”.
Los eventos aparecen solo después de la inclusión. No hay log para una transacción que aún está en el mempool.
Los eventos son baratos de emitir y baratos de buscar, por eso los eventos Transfer y Approval de ERC-20, los mints de NFT y los swaps de DEX se rastrean todos a través de logs y no mediante lecturas de estado.

Una API de eventos de contratos inteligentes es cualquier cosa que dé a su backend acceso estructurado a esos logs: el JSON-RPC de un nodo, una biblioteca que lo envuelve, un indexador, o un servicio alojado que le envía webhooks.

Qué hay dentro de un log de evento

Para filtrar o decodificar logs correctamente, necesita conocer su estructura. Según la especificación ABI de Solidity, un log contiene la dirección del contrato, hasta cuatro topics y un segmento de datos. Los eventos anónimos omiten el hash de la firma del evento.

Para un evento normal:

Topic 0 es el hash Keccak-256 de la firma del evento, por ejemplo Transfer(address,address,uint256).
Topics 1 a 3 contienen los parámetros indexados.
Data contiene los parámetros no indexados, codificados en ABI.

El ABI separa los parámetros en indexados, almacenados como topics hash para un filtrado eficiente, y no indexados, almacenados como datos binarios en el log.

Hay una trampa que merece la pena conocer. La misma especificación (en la edición v0.8.3) señala que los parámetros indexados de longitud dinámica, como strings y arrays de bytes, se almacenan como un hash Keccak de una codificación especial en lugar de como el valor. No puede recuperar el string original del log. Solo puede comprobar si un valor candidato coincide.

Un ejemplo concreto: Transfer ERC-20

Un log de transferencia de token tiene el topic 0 para la firma Transfer, la dirección del remitente en el topic 1, la del destinatario en el topic 2 y la cantidad en el campo data. Si quiere cada depósito en una dirección de cliente, filtra por topic 0 y topic 2. Lo recorremos en detalle en nuestra guía del evento ERC-20 Transfer.

Campos del log de transferencia ERC-20 y filtro de depósito

Lectura de eventos pasados

Las lecturas históricas son una consulta, no una suscripción. El método JSON-RPC estándar es eth_getLogs. Acepta un objeto filtro con un rango de bloques, una dirección de contrato opcional y un array opcional de topics. La referencia de Coinbase Developer Documentation para eth_getLogs muestra la estructura: fromBlock, toBlock y topics, y señala que un hash de bloque puede sustituir al rango.

Las librerías envuelven esto. En ethers.js, contract.queryFilter(event, fromBlock, toBlock) devuelve los eventos coincidentes, y la documentación de contratos de ethers v5 indica que solo los parámetros indexados pueden filtrarse. Un parámetro dejado a null coincide con cualquier valor.

Reglas prácticas para consultas históricas:

Siempre limite el rango. Muchos proveedores limitan la amplitud de bloques o el número de resultados por llamada. Recorra los rangos en trozos (por ejemplo, unos pocos miles de bloques cada vez) y reduzca el trozo a la mitad cuando reciba un error.
Filtre por dirección y topic 0 como mínimo. Las consultas de logs sin filtrar son la forma más rápida de alcanzar un límite de tasa.
Almacene el último bloque que procesó. Este punto de control es lo que le permite reanudar tras un fallo sin huecos ni duplicados.
Decodifique con el ABI correcto. Si solo tiene el topic 0, puede buscar la firma del evento, pero un contrato proxy puede emitir eventos definidos en su implementación, así que use el ABI de la implementación.

Si quiere un repaso sobre cómo hablar con nodos directamente, nuestra guía JSON-RPC con ejemplos en PHP, Python y JavaScript cubre el formato de la petición.

Suscripción a nuevos eventos

La parte en vivo funciona de manera diferente, y aquí es donde fallan muchas primeras implementaciones.

La documentación de eventos en tiempo real de go-ethereum explica que las suscripciones utilizan conexiones WebSocket o IPC persistentes, normalmente a través de eth_subscribe, y transmiten eventos a medida que el nodo los procesa. Dos límites son importantes:

Sin repetición. Las notificaciones de suscripción cubren eventos actuales, no pasados. Si su proceso estuvo inactivo durante diez minutos, la suscripción no le entrega lo que se perdió. Usted rellena los huecos con una consulta de logs.
Acoplamiento de conexión. Las suscripciones están vinculadas a una conexión. Cuando esta se cierra, se cierran todas sus suscripciones.

La misma página añade que los nodos almacenan en búfer las notificaciones, y si su cliente no puede procesarlas lo suficientemente rápido, la conexión puede cerrarse una vez que el búfer alcanza un límite (el ejemplo de Geth es 10.000). Un manejador lento que realiza escrituras en base de datos en línea es exactamente cómo ocurre eso.

El patrón que aguanta

Combine ambos mecanismos:

Al iniciar, lea su bloque de punto de control (checkpoint).
Rellene desde el punto de control hasta la cabeza actual con eth_getLogs, en trozos (chunks).
Abra la suscripción, y desduplique por hash de transacción más índice de log.
Entregue cada evento a una cola y acuse recibo inmediatamente. Procéselo en un trabajador (worker).
Al desconectar, vuelva al paso 1.

Esto se mantiene correcto incluso cuando la conexión se cae, lo cual ocurrirá.

Reorgs y confirmaciones

Un log que vio en el último bloque puede desaparecer si la cadena se reorganiza. Para cualquier cosa que implique dinero, no acredite al usuario en el primer avistamiento. Espere una profundidad de confirmación que se adapte a la cadena y al importe, y gestione la marca “removed” (eliminado) que los nodos estilo Ethereum adjuntan a los logs de bloques huérfanos. Guarde el ID del evento procesado, y haga su manejador idempotente para que un evento repetido o corregido no pueda acreditar dos veces.

Rama de evento huérfano junto a la cadena confirmada

Webhooks, WebSockets o sondeo (polling)

Los tres pueden entregar eventos. Difieren en quién mantiene la conexión y quién asume los modos de fallo.

Enfoque	Cómo funciona	Fortaleza	Debilidad
Sondeo (Polling)	Su código llama a `eth_getLogs` con un temporizador desde el último punto de control	Simple, sin estado, fácil de reanudar	La latencia es igual a su intervalo, y cuesta peticiones
Suscripción WebSocket	Conexión persistente que transmite logs desde un nodo	Latencia más baja	Muere con la conexión, sin repetición, límites de búfer
Webhook	Un servicio vigila la cadena y envía un HTTP POST a su endpoint	No hay conexión de larga duración que mantener, funciona con serverless	Necesita un endpoint público, comprobaciones de firma y gestión de duplicados

El sondeo sirve para trabajos de back-office de bajo volumen. Los WebSockets se adaptan a un panel de control (dashboard) o bot que debe reaccionar dentro de un bloque y puede tolerar huecos. Los webhooks encajan en flujos de pago, donde quiere un empujón (push) fiable por evento y una cola de trabajadores detrás. Nuestra publicación sobre el patrón ingestar, encolar, distribuir (fan out) para webhooks frente a WebSockets repasa los compromisos con más profundidad.

Gestión adecuada de la entrega de webhooks

Sea lo que sea lo que envíe el webhook, construya el receptor de la misma manera:

Verifique la firma antes de analizar el cuerpo.
Devuelva un 2xx rápidamente y procese de forma asíncrona.
Haga que los manejadores sean idempotentes, claveados por hash de transacción e índice de log.
Espere reintentos y entregas fuera de orden.
Registre los fallos para poder reconciliarlos con una consulta de logs más tarde.

El comportamiento de reintento es un tema de diseño por derecho propio. Para un análisis más profundo sobre el diseño en torno a reintentos y notificaciones perdidas, consulte este artículo sobre gestión de reintentos de webhooks de pago.

Configuración del monitoreo de eventos paso a paso

Aquí tiene una ruta mínima para un único contrato EVM, independientemente de la herramienta que utilice.

Obtenga el ABI. Desde el código fuente del contrato verificado o desde su propia salida de compilación. Sin él verá temas en bruto y datos hexadecimales.
Seleccione los eventos. Liste las firmas que le interesan, como Transfer, Approval o su propio OrderPaid.
Defina los filtros. Dirección del contrato, tema 0 y cualquier parámetro indexado, como el destinatario. Recuerde que solo se pueden filtrar valores indexados.
Realice el backfill. Consulte desde el bloque de despliegue, o desde su fecha de inicio de negocio, en bloques.
Pase a producción. Suscríbase mediante WebSocket, o registre un webhook.
Decodifique y normalice. Convierta las cantidades hexadecimales usando los decimales del token, y almacene el número de bloque, hash de transacción, índice de log y dirección del contrato.
Espere la finalidad. Marque los eventos como pendientes, luego como confirmados.
Monitoree el monitor. Alerte cuando no llegue ningún evento durante más tiempo que el intervalo normal de la cadena, o cuando su punto de control se quede atrás de la cabeza.

Eventos entre cadenas

El modelo EVM de temas y datos decodificados con ABI se aplica a Ethereum, Polygon, BNB Chain y Arbitrum, por lo que un decodificador funciona en todos ellos con diferentes endpoints RPC y reglas de confirmación. Otras redes no comparten el modelo. Bitcoin no tiene logs de contrato en absoluto, así que vigila direcciones y transacciones. Tron y Solana tienen sus propios formatos y APIs. Algunas pilas estilo Cosmos difieren de nuevo: Tendermint v0.36 descontinuó su API de streaming heredada en favor de una API de log de eventos que los clientes consultan mediante long-polling con cursores.

La consecuencia práctica es que un producto multi-cadena termina manteniendo un adaptador por familia de red, cada uno con su propio código de reconexión, decodificación y finalidad. Esa es la parte que la mayoría de los equipos subestiman. Para un mapa de las opciones, consulte nuestra comparación de seis tipos de APIs blockchain y el explicador sobre API blockchain versus ejecutar un nodo.

Constrúyalo usted mismo o use una API alojada

Ejecutar su propia pila implica un nodo (o un endpoint RPC de pago), un escáner de logs, un registro de ABIs, un manejador de reorganizaciones, una cola y una configuración de alertas. Eso es razonable si los eventos son su producto principal o necesita indexación personalizada en miles de contratos.

Es menos razonable si los eventos son un medio para un fin, como acreditar un depósito o confirmar un pedido. En ese caso quiere eventos decodificados entregados a un endpoint que controle, y nada más que operar.

Nuestra perspectiva

La mayoría de los errores de manejo de eventos que vemos no tratan sobre la lectura de logs. Tratan sobre lo que sucede a su alrededor: una notificación perdida durante un despliegue, un crédito duplicado tras un reintento, una conversión de decimales que era incorrecta para un token, una conexión que murió silenciosamente durante la noche.

Así que construimos en torno a tres creencias. Primero, la aplicación debe recibir datos decodificados y estructurados, no temas sin procesar que tenga que interpretar. Segundo, el envío (push) supera al sondeo (poll) para pagos, siempre que cada mensaje esté firmado y pueda verificarse. Tercero, un desarrollador no debería tener que ejecutar nodos ni mantener endpoints específicos de cadena sincronizados solo para saber que ha llegado un pago.

Por eso Chaingateway expone una única API REST en Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain y Arbitrum, con datos de transacción predecodificados, estimación automática de gas y peticiones firmadas con HMAC. Los webhooks se sitúan encima, para que su gestor reciba el evento y su equipo mantenga la atención en el producto. Elija lo que elija, mantenga el punto de control (checkpoint), la clave de idempotencia y la regla de confirmación. Esos tres deciden si sus números son correctos.

— Bitblade

Obtener eventos sin ejecutar nodos

Si su objetivo son eventos de pagos y tokens en una aplicación, nuestros Webhooks de Chaingateway entregan notificaciones de blockchain en tiempo real a su endpoint, y la API de Blockchain le proporciona datos de transacción decodificados, carteras, transferencias y estimaciones de comisiones a través de una única interfaz. Los planes comienzan en 49 € al mes para Plus, con Pro a 99 €, Premium a 249 € y Enterprise a 499 € al mes. La facturación anual es de 490 €, 990 €, 2.490 € y 4.990 € respectivamente. Consulte la página de precios para ver lo que incluye cada nivel. Para un ejemplo específico de cadena, lea sobre webhooks de Polygon sin sondeo.

Preguntas frecuentes

¿Puede un contrato inteligente leer sus propios eventos pasados?

No. Los contratos pueden emitir logs pero no pueden acceder a ellos después, por lo que los datos de eventos están destinados a consumidores fuera de la cadena (off-chain). Si su contrato necesita datos históricos en la cadena, almacene el valor en el estado del contrato, a un coste de gas mayor.

¿Cómo obtengo los eventos que me perdí mientras mi servicio estaba fuera de línea?

Ejecute una consulta de logs desde su último bloque procesado hasta la cabeza actual. Las suscripciones a nodos solo envían eventos actuales, por lo que reconectar no reproduce nada. Almacene un punto de control (checkpoint) después de cada bloque procesado y desduplique por hash de transacción e índice de log.

¿Por qué no puedo filtrar por un parámetro en mi evento?

Solo los parámetros indexados se almacenan como temas (topics), y solo los temas pueden filtrarse. Los valores no indexados se encuentran en el campo data, por lo que debe obtener los logs y filtrarlos en su propio código. Si controla el contrato, marque los campos por los que buscará como indexados, hasta tres por evento.

¿Debo usar webhooks o WebSockets para notificaciones de pagos?

Para pagos, los webhooks con una cola suelen ser más fáciles de operar, porque no mantiene una conexión que puede caerse. Use WebSockets cuando la reacción en sub-segundo importe y pueda rellenar lagunas. En ambos casos, procese eventos de forma idempotente y espere suficientes confirmaciones antes de acreditar fondos.