Registros de eventos

¿Qué son los registros de eventos en el mundo cripto?

Los registros de eventos son datos estructurados que crean los contratos inteligentes durante la ejecución de transacciones en una blockchain.

Permiten que un contrato inteligente publique información que pueden encontrar y procesar wallets, aplicaciones descentralizadas, exploradores de blockchain, plataformas de análisis y otros sistemas off-chain.

En Ethereum y otras redes basadas en la EVM, los desarrolladores suelen crear registros de eventos declarando un evento en Solidity y utilizando la palabra clave emit cuando se produce una acción relevante.

Por ejemplo, un contrato de tokens puede emitir un evento cuando se transfieren, acuñan, queman o autorizan tokens para su gasto.

Un protocolo de finanzas descentralizadas puede emitir registros cuando un usuario deposita garantías, pide cripto prestado, devuelve una deuda, recibe recompensas o cierra una posición.

La documentación oficial de Solidity sobre eventos explica que los eventos son una abstracción basada en la funcionalidad de registro de la EVM.

Los registros de eventos normalmente no controlan el estado del contrato ni ejecutan lógica de negocio adicional una vez emitidos.

En su lugar, proporcionan un registro eficiente que el software externo puede utilizar para entender qué ocurrió durante una transacción.

Por ello, los registros de eventos son un vínculo importante entre los contratos inteligentes on-chain y las aplicaciones off-chain que muestran la actividad de la blockchain a los usuarios.

Cómo funcionan los registros de eventos

Un registro de evento se crea mientras Ethereum Virtual Machine procesa una ruta de ejecución satisfactoria dentro de una transacción.

El contrato inteligente primero declara un evento con un nombre y una lista de parámetros.

A continuación, el contrato emite ese evento cuando su código llega a la instrucción correspondiente.

El compilador de Solidity convierte la emisión del evento en una de las operaciones de registro de la EVM.

El registro resultante contiene la dirección del contrato que lo ha emitido, una lista de topics consultables y un campo de datos con información codificada adicional.

El registro pasa a formar parte del recibo de la transacción cuando esta se incluye en un bloque.

Las aplicaciones pueden recuperar el registro a través de un nodo de Ethereum, un proveedor RPC, un explorador de blockchain o un indexador especializado.

La guía de Ethereum sobre el registro de eventos de contratos inteligentes explica que las aplicaciones descentralizadas pueden escuchar los eventos emitidos y realizar acciones off-chain cuando aparecen.

Si la transacción se revierte, también se eliminan del resultado final los registros creados durante la ejecución revertida.

Esto significa que un registro mostrado durante una simulación o un seguimiento de ejecución podría no aparecer en el recibo confirmado si la llamada general falla.

Eventos y registros de eventos

Un evento es una declaración definida por el desarrollador que describe la información que puede publicar un contrato.

Un registro de evento es el registro real que se crea cuando el contrato emite ese evento durante una transacción.

Por ejemplo, un contrato puede definir un evento Transfer en su código fuente.

Cada transferencia completada puede crear un registro independiente a partir de esa definición.

El evento actúa como una plantilla, mientras que cada registro es una ocurrencia de esa plantilla.

Una transacción puede no crear ningún registro, crear uno o generar muchos.

Una transacción que interactúe con varios contratos inteligentes puede producir registros de cada contrato que participe en la ejecución.

Las aplicaciones utilizan la Application Binary Interface del contrato, o ABI, para relacionar los registros sin procesar con las declaraciones de eventos y descodificar los valores.

¿Qué información se almacena en un registro de evento?

Un registro de eventos EVM contiene la dirección del contrato emisor, entre cero y cuatro topics y un campo de datos de longitud variable.

La dirección emisora identifica el contrato cuya ejecución ha creado el registro.

Los topics contienen valores diseñados para facilitar el filtrado y las búsquedas.

El campo de datos almacena los parámetros del evento que no se hayan marcado como indexados.

Las interfaces RPC habituales también devuelven metadatos de la transacción y del bloque junto con los registros.

Estos metadatos pueden incluir el hash de la transacción, el índice de la transacción, el hash del bloque, el número del bloque y el índice del registro.

El índice del registro identifica su posición entre los demás registros del mismo bloque.

Por lo general, las aplicaciones deberían utilizar una combinación del ID de la cadena, el hash del bloque, el hash de la transacción y el índice del registro para crear un identificador único.

Utilizar solo el nombre del evento o el hash de la transacción puede no ser suficiente, ya que una transacción puede emitir varias veces el mismo evento.

¿Qué son los topics de los eventos?

Los topics son valores de 32 bytes que se colocan en una sección especial y consultable de un registro EVM.

Permiten que una aplicación filtre el historial de la blockchain sin tener que descodificar por separado cada campo de datos de evento.

Un evento estándar de Solidity no anónimo puede tener hasta cuatro topics.

El primer topic suele identificar el tipo de evento, mientras que hasta tres topics adicionales representan parámetros marcados como indexados.

Los topics están ordenados, por lo que filtrar por un valor en la segunda posición no equivale a buscar el mismo valor en la tercera.

La documentación oficial de Ethereum JSON-RPC para eth_getLogs explica que los filtros por topics dependen del orden y pueden incluir valores alternativos para una misma posición.

Los topics son especialmente útiles para buscar eventos relacionados con la dirección de una wallet, un identificador de token, un mercado, una propuesta u otro valor que se consulte con frecuencia.

Una mala elección de parámetros indexados puede dificultar o encarecer las búsquedas de datos históricos de una aplicación.

¿Qué es el topic 0?

El topic 0 suele contener el hash Keccak-256 de la firma canónica del evento.

La firma canónica combina el nombre del evento con los tipos ordenados de sus parámetros.

Los nombres de los parámetros y la palabra clave indexed no se incluyen en el hash de la firma del evento.

Por ejemplo, un evento llamado Transfer cuyos parámetros sean address, address y uint256 tiene una firma de evento predecible.

Las aplicaciones pueden comparar el topic 0 con hashes de firma conocidos para identificar el evento representado por un registro sin procesar.

Cambiar el nombre del evento o el orden y los tipos de sus parámetros genera una firma de evento diferente.

Por tanto, dos eventos con el mismo nombre, pero tipos de parámetros distintos, tienen valores diferentes en el topic 0.

La especificación ABI de Solidity para eventos describe cómo se codifican la firma del evento y sus argumentos en los topics y los datos.

Parámetros de eventos indexados

Un parámetro indexado es un argumento del evento que se almacena en un topic para que los sistemas externos puedan filtrarlo con eficiencia.

Solidity permite hasta tres parámetros indexados en un evento normal no anónimo.

La posición restante del topic se reserva para la firma del evento.

Las direcciones, los números enteros, los valores booleanos y otros datos que caben en una palabra de 32 bytes pueden almacenarse directamente en un topic mediante una codificación compatible con ABI.

Los valores dinámicos, como cadenas, matrices de bytes, matrices dinámicas y estructuras complejas, se tratan de otra manera.

Cuando se indexa un valor dinámico, el topic almacena un hash Keccak-256 de su valor codificado, en lugar del valor original legible.

Una aplicación puede filtrar por ese hash si ya conoce el valor que quiere encontrar.

Sin embargo, no puede recuperar únicamente a partir del hash una cadena o matriz de bytes original que desconozca.

A veces, los desarrolladores incluyen la misma información dos veces: colocan una versión con hash en un parámetro indexado y una versión legible en un parámetro no indexado.

Este diseño mejora la capacidad de búsqueda y, al mismo tiempo, conserva el valor original para su descodificación.

Parámetros de eventos no indexados

Los parámetros que no llevan la palabra clave indexed se almacenan en el campo de datos del registro.

Estos valores se codifican según las reglas ABI de Ethereum.

La ABI es necesaria porque los datos sin procesar del registro no etiquetan cada valor con un nombre y un tipo legibles.

Una aplicación necesita la definición correcta del evento para descodificar los datos de forma fiable.

Los parámetros no indexados pueden contener valores más grandes o complejos que los topics individuales.

Son adecuados para cantidades, valores de configuración detallados, matrices, cadenas y otros datos que no requieren filtrado directo por topics.

Normalmente, las aplicaciones no pueden pedir a eth_getLogs que filtre por un valor arbitrario dentro del campo de datos.

Primero deben recuperar los registros usando la dirección del contrato y los topics; después pueden descodificar e inspeccionar los datos localmente.

Eventos anónimos

Un evento de Solidity se puede declarar como anónimo.

Un evento anónimo no coloca automáticamente el hash de su firma en el topic 0.

Así, las cuatro posiciones de topics pueden utilizarse para parámetros indexados.

Sin embargo, al eliminar el topic de la firma resulta más difícil para el software externo identificar automáticamente el tipo de evento.

Puede ser difícil distinguir entre distintos eventos anónimos si tienen estructuras similares de topics y datos.

Los eventos anónimos pueden ser adecuados para diseños especializados de bajo nivel, pero los eventos normales de aplicaciones suelen ser más fáciles de indexar y descodificar cuando no son anónimos.

Los desarrolladores solo deberían utilizar eventos anónimos si el topic indexado adicional ofrece una ventaja clara que compense la menor facilidad para identificar el evento.

Opcodes de registro de la EVM

La EVM proporciona cinco opcodes de registro, denominados LOG0 a LOG4.

El número de cada nombre de opcode representa la cantidad de topics que incluye el registro.

LOG0 crea un registro sin topics, mientras que LOG4 crea uno con cuatro topics.

Cada operación de registro también lee un rango seleccionado de la memoria de la EVM y lo almacena como campo de datos del registro.

Los eventos de Solidity se compilan en estas instrucciones de registro de bajo nivel.

El entorno de ejecución añade la dirección del contrato al registro; no se proporciona como un parámetro normal del evento.

Las operaciones de registro consumen gas en función de factores como el número de topics y la cantidad de datos registrados.

La referencia oficial de opcodes de Ethereum enumera las instrucciones de registro de la EVM y sus costes de ejecución.

Registros de eventos y recibos de transacción

Un recibo de transacción es el registro de ejecución que se genera después de que una transacción se incluya en un bloque.

El recibo contiene información como el estado de ejecución, el consumo acumulado de gas, un filtro bloom de logs y los registros emitidos por la transacción.

Las respuestas RPC pueden añadir otros campos útiles, como la dirección de creación del contrato, el precio efectivo del gas y el gas utilizado por la transacción individual.

La matriz de registros conserva el orden en el que se emitieron los eventos durante la ejecución.

Una transacción satisfactoria puede tener una matriz de registros vacía si ningún contrato ha emitido un evento.

Normalmente, una transacción fallida no conserva registros de eventos, porque sus cambios de estado y sus registros se han revertido.

Las aplicaciones deberían comprobar el estado del recibo en lugar de considerar que la existencia de un hash de transacción demuestra que la ejecución se ha completado correctamente.

El método Ethereum JSON-RPC para recibos de transacción describe los campos del recibo que devuelve un cliente de ejecución.

Registros de eventos y recibos de bloque

Los recibos de transacción se comprometen criptográficamente mediante la raíz de recibos del bloque.

Este compromiso permite a los participantes de la blockchain verificar que los recibos pertenecen a un historial de bloques concreto.

Cada recibo contiene los registros generados por su transacción.

Con el formato actual de bloque de ejecución, la cabecera del bloque también incluye un filtro bloom que resume las direcciones y los topics de los registros de las transacciones de ese bloque.

El filtro bloom ayuda al cliente a determinar si un bloque podría contener registros que coincidan con una consulta.

Una coincidencia positiva del filtro bloom no demuestra que exista un registro coincidente, ya que estos filtros pueden generar falsos positivos.

Una coincidencia negativa indica que la dirección o el topic buscado no aparece en ese filtro.

Las aplicaciones siguen necesitando los registros reales de los recibos para confirmar los valores exactos de los eventos.

Registros de eventos y almacenamiento de contratos

Los registros de eventos y el almacenamiento de los contratos inteligentes tienen funciones diferentes.

El almacenamiento de un contrato contiene datos persistentes que la ejecución futura de contratos inteligentes puede leer directamente.

Los registros de eventos están diseñados principalmente para su observación externa e indexación histórica.

Los contratos de Solidity no pueden leer directamente registros de eventos históricos, incluidos los emitidos por el propio contrato.

La referencia de eventos de Solidity indica que los datos de registros y eventos no son accesibles desde dentro de los contratos.

Un contrato nunca debería depender de un evento anterior como única fuente de datos necesarios para futuras decisiones on-chain.

Si la lógica futura del contrato necesita un valor, normalmente ese valor debería almacenarse en el estado del contrato o proporcionarse mediante un mecanismo verificable.

Los registros suelen ser más baratos que el almacenamiento persistente para la información destinada únicamente a usuarios off-chain.

Sin embargo, utilizar un registro en lugar del almacenamiento cambia lo que los contratos inteligentes pueden verificar o recuperar posteriormente.

Registros de eventos y datos devueltos por funciones

Los datos devueltos por una función se envían a quien la llama directamente durante la ejecución del contrato.

Los registros de eventos se almacenan en los recibos de transacción para recuperarlos posteriormente desde sistemas off-chain.

Una transacción que cambia el estado no proporciona a una interfaz de usuario datos devueltos con el mismo formato histórico práctico que un registro de evento.

Las aplicaciones suelen utilizar recibos y eventos para conocer el resultado de una transacción enviada.

Las llamadas de solo lectura pueden devolver valores sin crear registros de eventos ni modificar el estado de la blockchain.

Los desarrolladores deberían utilizar los valores devueltos para la comunicación inmediata de llamadas a contratos y los eventos para notificaciones off-chain duraderas.

Un evento no debe tratarse como la respuesta directa de una función, ya que varios contratos pueden emitir registros durante una misma transacción.

Cómo consultan los registros de eventos las aplicaciones

Las aplicaciones suelen consultar los registros de eventos históricos mediante el método JSON-RPC eth_getLogs.

Una consulta puede especificar el bloque inicial y final, la dirección del contrato, el hash del bloque y los filtros por topics.

El método devuelve una matriz con los registros que coinciden con el filtro.

Una consulta acotada suele ser más fiable y eficiente que solicitar todos los registros de un rango de bloques muy amplio.

Los proveedores RPC pueden limitar los rangos de bloques, el tamaño de las respuestas, el tiempo de las solicitudes o la frecuencia de las consultas.

Las aplicaciones deberían dividir las búsquedas históricas grandes en rangos de bloques más pequeños y guardar su progreso.

También deberían volver a intentar las solicitudes fallidas con una espera progresiva controlada, en lugar de suponer que una respuesta vacía o fallida demuestra que no existen eventos.

Utilizar el filtro blockHash definido por EIP-234 puede ayudar a una aplicación a solicitar registros de un bloque concreto.

Consultas periódicas y suscripciones a eventos

Una aplicación puede detectar nuevos registros de eventos mediante consultas periódicas o suscripciones.

Las consultas periódicas preguntan repetidamente a un nodo por los registros o los cambios en filtros a lo largo del tiempo.

Una suscripción mantiene abierta una conexión activa para que el nodo pueda enviar notificaciones de nuevos registros a medida que llegan bloques.

Las suscripciones pueden ofrecer actualizaciones más rápidas, pero la conexión puede interrumpirse o perder información durante una caída del servicio.

Las consultas periódicas pueden ser más fáciles de recuperar, ya que la aplicación puede volver a solicitar un rango de bloques conocido.

Un sistema de producción sólido suele combinar suscripciones en directo con una conciliación periódica basada en bloques.

Así, la aplicación puede detectar registros que se hayan perdido durante interrupciones de red o reinicios de nodos.

La documentación oficial de la API Ethereum JSON-RPC describe métodos de filtro para recuperar registros aparecidos desde una consulta anterior.

Registros de eventos y reorganizaciones de la cadena

Una reorganización de la cadena se produce cuando un bloque que antes se consideraba parte de la cadena activa se sustituye por un historial de bloques diferente.

Los registros del bloque sustituido dejan de formar parte de la blockchain canónica.

Una aplicación que haya reaccionado inmediatamente a esos registros quizá tenga que revertir los cambios correspondientes en su base de datos local.

Algunas respuestas de suscripción RPC pueden indicar que un registro notificado anteriormente se ha eliminado debido a una reorganización.

Sin embargo, las desconexiones de red pueden impedir que una aplicación reciba la notificación de eliminación.

Los indexadores fiables siguen los hashes de los bloques y las relaciones entre bloques padre para detectar de forma independiente los bloques sustituidos.

La justificación del filtrado de registros basado en el hash del bloque explica por qué las aplicaciones deben gestionar cuidadosamente las reorganizaciones y los fallos de conexión.

Los sistemas financieros normalmente deberían esperar a alcanzar un nivel adecuado de confirmaciones o finalidad antes de tratar un evento como irreversible.

El umbral necesario depende de la cadena, el valor de la aplicación y las consecuencias de actuar demasiado pronto.

Registros de eventos y finalidad

Un evento recién emitido puede aparecer en un bloque propuesto antes de que ese bloque alcance un nivel de finalidad más sólido en el consenso.

Las aplicaciones pueden consultar registros mediante etiquetas de bloque como latest, safe o finalized, si el cliente conectado las admite.

La etiqueta latest proporciona información más rápida, pero puede incluir bloques con mayor riesgo de reorganización.

La etiqueta finalized ofrece más confianza, aunque introduce un retraso adicional.

Una interfaz de cartera puede aceptar eventos latest para mostrarlos, mientras que un bridge o una transferencia financiera de gran importe puede requerir confirmaciones más sólidas.

Las aplicaciones deberían elegir su política de confirmación en función del riesgo económico, en lugar de aplicar la misma regla a todos los eventos.

Registros de eventos en contratos de tokens

Los estándares de tokens utilizan registros de eventos para que las transferencias y autorizaciones sean visibles para las wallets y los sistemas de datos de blockchain.

Un token fungible suele emitir un evento Transfer cuando se transfieren activos entre direcciones.

También puede emitir un evento Approval cuando un titular modifica la autorización de gasto de otra dirección.

Los contratos NFT suelen emitir eventos de transferencia y autorización que incluyen identificadores de tokens.

Los contratos multitoken pueden emitir eventos de transferencia individual y por lotes.

Las estructuras de eventos estandarizadas permiten que las herramientas externas sean compatibles con muchos contratos de tokens mediante la misma lógica de descodificación.

Sin embargo, un token puede emitir eventos engañosos o incumplir un estándar.

Un evento por sí solo no demuestra que un contrato sea legítimo, tenga valor o sea seguro.

Registros de eventos en las finanzas descentralizadas

Los protocolos de finanzas descentralizadas utilizan registros de eventos para describir acciones financieras complejas.

Entre los ejemplos habituales se encuentran depósitos, retiradas, intercambios, préstamos, reembolsos, liquidaciones, actualizaciones de intereses, reclamaciones de recompensas y cambios de gobernanza.

Una interfaz de usuario puede supervisar estos eventos para actualizar saldos e historiales de transacciones.

Un sistema de análisis puede agregarlos para calcular el volumen, la liquidez, la actividad de préstamos o los ingresos del protocolo.

Un servicio de supervisión de riesgos puede vigilar eventos de liquidación o garantías para detectar posiciones sometidas a tensión.

Como una transacción DeFi puede llamar a varios contratos, el recibo puede contener numerosos registros relacionados.

Las aplicaciones deben tener en cuenta la dirección emisora y el orden de los registros, en lugar de descodificar cada firma de evento conocida como si procediera del contrato principal del protocolo.

Registros de eventos en wallets y exploradores de blockchain

Las wallets utilizan registros de eventos para crear historiales legibles a partir de transacciones sin procesar de contratos inteligentes.

Una transferencia de tokens puede no aparecer como un movimiento directo de activo nativo en los campos básicos de la transacción.

La wallet puede descodificar el evento Transfer del contrato del token para mostrar el activo, el remitente, el destinatario y la cantidad.

Los exploradores de blockchain también descodifican registros mediante ABI de contratos verificados y firmas de eventos conocidas.

Cuando no se dispone del código fuente o de la información ABI, un explorador puede mostrar topics y datos sin procesar.

Una etiqueta descodificada debe considerarse una interpretación del registro sin procesar, no una garantía independiente de la intención del contrato.

Los usuarios deberían verificar la dirección del contrato emisor antes de confiar en la descripción de un evento.

Registros de eventos e indexadores de blockchain

Un indexador de blockchain lee bloques y recibos y almacena los datos de eventos seleccionados en una base de datos fácil de consultar.

Los indexadores facilitan responder a preguntas difíciles de resolver mediante solicitudes RPC directas.

Por ejemplo, permiten recuperar todas las transferencias de tokens de una wallet, calcular la actividad de un protocolo a lo largo del tiempo o seguir todas las posiciones abiertas en un mercado de préstamos.

Un indexador suele comenzar en un bloque seleccionado y procesa los nuevos bloques en orden.

Descodifica los registros pertinentes, crea registros en la base de datos y guarda la información de los bloques necesaria para gestionar reorganizaciones.

Los indexadores deberían poder reanudar el procesamiento tras un fallo sin saltarse ni duplicar eventos.

También deberían volver a procesar los datos históricos cuando cambien el esquema de descodificación o la lógica de la aplicación.

La documentación de Ethereum sobre datos y análisis explica cómo los sistemas de datos de blockchain trabajan con registros, recibos, trazas y otra información de ejecución.

Registros de eventos y automatización off-chain

Los servicios off-chain pueden escuchar registros de eventos y activar acciones fuera de la blockchain.

Un servicio puede enviar una notificación después de un depósito, actualizar una base de datos interna tras una operación o iniciar otro flujo de trabajo después de una votación de gobernanza.

El registro por sí solo no obliga al servicio off-chain a actuar.

El servicio debe permanecer conectado, recibir el evento, validarlo y decidir qué hacer.

La automatización off-chain debería verificar el ID de la cadena, la dirección del contrato, el estado del bloque y los valores descodificados antes de realizar acciones sensibles.

También debería ser idempotente; es decir, procesar dos veces el mismo evento no debe generar un resultado duplicado e incorrecto.

Esta protección es importante porque los reintentos, las reconexiones y las reorganizaciones pueden hacer que se observe el mismo registro más de una vez.

¿Pueden los contratos inteligentes leer registros de eventos?

Los contratos inteligentes no pueden buscar directamente registros de eventos históricos mediante la ejecución normal de la EVM.

Los registros están diseñados para aplicaciones externas, no para ser estado legible por contratos.

Un contrato que necesite información de un evento anterior debe recibirla mediante otro mecanismo.

Entre los mecanismos posibles se encuentran el almacenamiento del contrato, una prueba criptográfica, un oráculo o un protocolo de mensajería entre cadenas.

Antes de utilizar la información proporcionada, el contrato debe verificar que sea fiable.

Esta limitación impide que los contratos inteligentes consideren automáticamente como datos on-chain válidos una respuesta RPC off-chain.

¿Se pueden modificar los registros de eventos?

Un registro confirmado no se puede editar de forma independiente respecto a la transacción y el bloque que lo han generado.

Modificar el registro exigiría sustituir o invalidar el historial de la blockchain que contiene ese recibo.

Una reorganización puede eliminar un registro del historial activo antes de que se alcance una finalidad más sólida.

Una nueva transacción puede emitir un evento corrector o de reversión, pero no elimina el registro canónico anterior.

Las aplicaciones deberían conservar los eventos históricos y representar las correcciones como registros posteriores, en lugar de reescribir silenciosamente los datos originales de la blockchain.

¿Se pueden falsificar los registros de eventos?

Cualquier contrato inteligente puede definir y emitir un evento con un nombre y una firma conocidos.

Por tanto, un contrato malicioso puede emitir un evento Transfer parecido al de un contrato de tokens legítimo.

La firma del evento por sí sola no identifica el activo ni demuestra que se haya producido un cambio real de saldo en un contrato de confianza.

Las aplicaciones deben verificar la dirección del contrato emisor y entender el código y el estado de ese contrato.

Un token fraudulento también puede emitir valores engañosos o generar eventos que parezcan mostrar que una wallet inactiva ha recibido un activo.

Las wallets y los exploradores deberían evitar tratar todas las firmas de eventos conocidas como igualmente fiables.

Los usuarios no deberían interactuar con un token solo porque aparezca una transferencia inesperada en el historial de transacciones.

Registros de eventos y seguridad de los contratos inteligentes

El diseño de eventos forma parte de la seguridad de los contratos inteligentes, ya que los sistemas de supervisión dependen de registros precisos.

Las acciones administrativas importantes deberían emitir eventos claros cuando cambien los permisos, las comisiones, las direcciones de los oráculos, las implementaciones de actualización o los ajustes de emergencia.

La ausencia de eventos puede dificultar que los usuarios y los equipos de seguridad detecten cambios peligrosos.

Los valores incorrectos de un evento pueden hacer que los sistemas off-chain muestren un resultado que no coincide con el estado del contrato.

Un contrato debería emitir un evento solo después de que se hayan completado correctamente las comprobaciones y los cambios de estado correspondientes.

Los desarrolladores deberían probar que cada ruta de ejecución importante emita el registro previsto exactamente una vez.

También deberían comprobar que las transacciones revertidas no dejen registros finales engañosos.

Un evento no debe sustituir a la aplicación de permisos y reglas de saldo dentro del código del contrato.

Costes de gas de los registros de eventos

Emitir un evento consume gas, ya que la EVM debe procesar la instrucción de registro y añadir información al recibo de la transacción.

Por lo general, cuantos más topics y más grandes sean los campos de datos, mayor será el coste del registro.

Por tanto, un evento con varios valores grandes puede costar más que uno mínimo.

Los registros suelen ser menos caros que guardar la misma información en el almacenamiento persistente del contrato.

Sin embargo, los registros innecesarios siguen aumentando el coste de las transacciones para los usuarios y el tamaño del historial de la blockchain.

Los desarrolladores deberían emitir información que responda a una necesidad real de indexación, supervisión, auditoría o interfaz de usuario.

Deberían evitar duplicar todos los cálculos internos en eventos independientes cuando los sistemas externos no necesiten esa información.

La optimización de gas no debería eliminar la transparencia esencial para supervisar la actividad del protocolo de forma segura.

Buenas prácticas para diseñar eventos

Los nombres de los eventos deberían describir claramente la acción que se ha producido.

Los nombres de los parámetros deberían ser lo bastante específicos para que los desarrolladores y analistas entiendan su significado.

Conviene considerar como parámetros indexados los valores que los usuarios busquen con frecuencia.

Entre los valores indexados habituales se encuentran las direcciones de cuentas, los identificadores de tokens, los identificadores de mercados y los identificadores de propuestas.

Las cantidades y los valores de configuración detallados normalmente pueden permanecer en el campo de datos si no se necesitan para el filtrado directo.

Los desarrolladores deberían evitar indexar valores dinámicos, salvo que el filtrado mediante hash resulte específicamente útil.

Cada evento debería incluir contexto suficiente para poder interpretarlo sin depender de supuestos frágiles sobre el orden de las transacciones.

Los contratos compatibles con varios activos o mercados deberían incluir el identificador correspondiente del activo o del mercado.

Cuando resulte útil para la supervisión, los eventos de actualización deberían identificar tanto el valor anterior como el nuevo.

Las declaraciones de eventos deberían permanecer estables cuando las aplicaciones externas dependan de su firma y de la disposición de sus parámetros.

Buenas prácticas para leer registros de eventos

Las aplicaciones deberían filtrar tanto por la dirección esperada del contrato como por la firma del evento esperada.

Deberían descodificar los registros mediante la versión ABI correcta para la implementación del contrato activa en ese bloque.

Los contratos actualizables pueden cambiar los eventos disponibles después de actualizar una implementación.

Los indexadores deberían almacenar el hash del bloque, el número del bloque, el hash de la transacción, el índice de la transacción y el índice del registro.

Deberían procesar los registros en el orden canónico de los bloques y permitir deshacer cambios después de una reorganización.

Las consultas históricas grandes deberían dividirse en rangos de bloques manejables.

Las aplicaciones deberían distinguir entre una respuesta realmente vacía y una solicitud fallida, truncada o limitada por frecuencia.

Las acciones financieras deberían esperar al nivel de confirmación apropiado para su valor y riesgo.

Cuando la precisión sea especialmente importante, las aplicaciones deberían comparar los valores derivados de eventos con el estado del contrato.

Registros de eventos en redes de capa 2

Las redes de capa 2 basadas en la EVM suelen utilizar registros de eventos con estructuras similares a las de Ethereum.

Los desarrolladores pueden utilizar a menudo eventos de Solidity, topics, ABI y consultas JSON-RPC conocidas.

Sin embargo, las redes de capa 2 pueden tener tiempos de bloque, reglas de confirmación, secuenciadores, estructuras de comisiones y procesos de liquidación final distintos.

Es posible que un registro confirmado por un secuenciador de capa 2 todavía no haya alcanzado su estado de liquidación más sólido en Ethereum.

Los eventos relacionados con un bridge pueden aparecer en las redes de origen y destino en distintas fases de una transferencia.

Las aplicaciones deben seguir la cadena correcta y no tratar eventos de redes separadas como un único historial compartido de registros.

Una misma dirección de contrato o firma de evento puede representar contratos y activos diferentes en distintas cadenas.

Registros de eventos en transferencias entre cadenas

Los sistemas entre cadenas suelen utilizar eventos para indicar que se han bloqueado, quemado, liberado o acuñado activos.

Un relayer off-chain o un protocolo de la cadena de destino puede observar el evento de la cadena de origen antes de continuar con el proceso de transferencia.

La acción en la cadena de destino debe verificar el evento de origen mediante el sistema de pruebas o validadores del bridge.

Ver un registro a través de un proveedor RPC normal no basta para que un contrato inteligente sin confianza pueda demostrar que el evento es válido.

Los bridges también deben tener en cuenta las reorganizaciones y la finalidad de la cadena de origen.

Un bridge que actúe demasiado rápido puede procesar un evento que después se elimine del historial canónico de origen.

Los usuarios deberían entender que un evento emitido por un bridge puede señalar el inicio de una transferencia, no su finalización definitiva.

Ejemplo de un registro de evento

Supongamos que un usuario transfiere 500 unidades de un token fungible a otra wallet.

El usuario envía una transacción que llama a la función transfer del contrato del token.

El contrato comprueba el saldo del remitente y actualiza los saldos del remitente y del destinatario.

A continuación, el contrato emite un evento Transfer que contiene las direcciones del remitente y el destinatario, así como la cantidad transferida.

Las direcciones del remitente y el destinatario pueden almacenarse como topics indexados, mientras que la cantidad se codifica mediante ABI en el campo de datos.

El hash de la firma del evento aparece en el topic 0.

Cuando la transacción se incluye en un bloque, el registro aparece en el recibo de la transacción.

Una wallet recupera y descodifica el registro para mostrar el movimiento del token en un historial de transacciones legible.

Un indexador también registra el evento para que los usuarios puedan buscar todas las transferencias relacionadas con cualquiera de las direcciones.

Este ejemplo muestra cómo un único registro conecta la ejecución del contrato con wallets, exploradores y análisis de blockchain.

Errores habituales con los registros de eventos

Un error habitual es suponer que otro contrato inteligente puede leer un evento.

Otro es considerar que una firma de evento conocida demuestra que el contrato emisor es legítimo.

Un tercer error es descodificar un registro sin comprobar la dirección del contrato.

Un cuarto error es suponer que se puede recuperar directamente una cadena indexada a partir del hash de su topic.

Un quinto error es utilizar únicamente el hash de la transacción como identificador de un registro.

Un sexto error es no gestionar las reorganizaciones de la cadena.

Un séptimo error es procesar dos veces el mismo registro después de un reintento RPC o de reiniciar la aplicación.

Un octavo error es consultar un rango de bloques extremadamente amplio y tratar una solicitud agotada como si el resultado estuviera vacío.

Un noveno error es depender únicamente de eventos cuando la lógica futura de un contrato inteligente requiere que los mismos datos estén en el almacenamiento.

Un décimo error es suponer que un evento descodificado correctamente demuestra que todos los cambios de estado previstos se han producido como debían.

Preguntas frecuentes

¿Qué son los registros de eventos en el mundo cripto?

Son registros estructurados emitidos por contratos inteligentes para describir acciones que han tenido lugar durante la ejecución de transacciones en una blockchain.

¿Dónde se almacenan los registros de eventos de Ethereum?

Se incluyen en los recibos de transacción, que quedan comprometidos como parte del historial de ejecución del bloque.

¿Cuál es la diferencia entre un evento y un registro?

Un evento es una declaración del código de un contrato inteligente, mientras que un registro es el dato que se crea cuando se emite ese evento.

¿Pueden los contratos inteligentes leer registros de eventos antiguos?

No. Los contratos inteligentes no pueden buscar ni leer directamente registros históricos mediante la ejecución normal de la EVM.

¿Qué es el topic 0 en un registro de eventos de Ethereum?

Normalmente, el topic 0 contiene el hash Keccak-256 del nombre del evento y de los tipos canónicos de sus parámetros.

¿Cuántos topics puede tener un registro de evento?

Un registro EVM puede tener hasta cuatro topics. En un evento normal de Solidity, suele reservarse uno para la firma del evento.

¿Qué significa indexed en un evento de Solidity?

Un parámetro indexado se almacena en un topic para que las aplicaciones externas puedan filtrar registros por ese valor.

¿Se pueden indexar cadenas en los registros de eventos?

Sí, pero una cadena indexada se representa mediante un hash Keccak-256, no mediante la cadena original legible.

¿Qué ocurre con los registros de eventos cuando se revierte una transacción?

Los registros generados durante la ejecución revertida se eliminan del resultado final de la transacción.

¿Los registros de eventos consumen gas?

Sí. Emitir un registro consume gas, en parte según sus topics y el tamaño de sus datos.

¿Puede un registro de evento demostrar que un token es legítimo?

No. Cualquier contrato puede emitir un evento conocido, por lo que los usuarios deben verificar el contrato emisor y su estado real.

¿Cómo pueden recuperar registros de eventos los desarrolladores?

Pueden hacerlo mediante métodos como eth_getLogs, consultas de recibos, filtros, suscripciones, exploradores de blockchain o servicios de indexación.

¿Puede una reorganización de la blockchain eliminar un registro de evento?

Sí. Un registro de un bloque sustituido se elimina del historial canónico de la cadena.

¿Son iguales los registros de eventos en todas las cadenas EVM?

La estructura básica suele ser similar, pero los ID de cadena, contratos, historiales de bloques, finalidad y comportamiento RPC pueden variar.

¿Son más baratos los registros de eventos que el almacenamiento de contratos?

Los registros suelen ser más baratos para información histórica off-chain, pero no pueden sustituir al almacenamiento que debe leer la ejecución futura de contratos inteligentes.

¿Por qué utilizan registros de eventos las wallets?

Las wallets los utilizan para identificar transferencias de tokens, autorizaciones, intercambios y otras acciones de contratos inteligentes que no se deducen claramente solo de los campos básicos de la transacción.

Conclusión

Los registros de eventos son datos estructurados que conectan la ejecución de contratos inteligentes con wallets, aplicaciones descentralizadas, exploradores de blockchain, sistemas de análisis y otros servicios off-chain.

Se crean mediante instrucciones de registro de la EVM y se almacenan en los recibos de transacción cuando la ejecución se completa correctamente.

Un registro contiene la dirección del contrato emisor, topics consultables y datos de evento codificados mediante ABI.

Normalmente, el topic 0 identifica la firma del evento, mientras que los parámetros indexados ofrecen opciones adicionales de filtrado.

Los parámetros no indexados se almacenan en el campo de datos y requieren la ABI correcta para descodificarse.

Los registros de eventos se diferencian del almacenamiento de contratos porque los contratos inteligentes no pueden leer directamente los registros históricos.

También se diferencian de los datos devueltos por funciones, ya que están diseñados para permanecer disponibles para su procesamiento histórico off-chain.

Las aplicaciones pueden recuperar registros mediante filtros JSON-RPC, suscripciones, recibos de transacción, exploradores de blockchain e indexadores especializados.

Los sistemas fiables deben gestionar el procesamiento duplicado, las limitaciones RPC, las reorganizaciones de la cadena, las actualizaciones de contratos y los distintos niveles de confirmación.

Los usuarios deben recordar que un nombre de evento conocido no demuestra que el contrato emisor sea de confianza ni que un token sea legítimo.

Los desarrolladores deberían diseñar eventos con nombres claros, parámetros indexados útiles, contexto suficiente y esquemas estables.

Entender los registros de eventos ayuda a usuarios y desarrolladores de cripto a interpretar con mayor precisión las transferencias de tokens, la actividad DeFi, los cambios de contratos inteligentes, los recibos de transacción y los datos de aplicaciones on-chain.