Logs de eventos

O que são logs de eventos em cripto?

Logs de eventos são registros estruturados criados por contratos inteligentes durante a execução de transações na blockchain.

Eles permitem que um contrato inteligente publique informações que carteiras, aplicativos descentralizados, exploradores de blockchain, plataformas de análise e outros sistemas off-chain podem localizar e processar.

Na Ethereum e em outras redes baseadas na EVM, os desenvolvedores geralmente criam logs de eventos declarando um evento em Solidity e usando a palavra-chave emit quando uma ação relevante ocorre.

Por exemplo, um contrato de token pode emitir um evento quando tokens são transferidos, emitidos, queimados ou aprovados para uso.

Um protocolo de finanças descentralizadas pode emitir logs quando um usuário deposita colateral, toma cripto emprestado, paga uma dívida, recebe recompensas ou fecha uma posição.

A documentação oficial da Solidity sobre eventos explica que eventos são uma abstração criada sobre a funcionalidade de logging da EVM.

Os logs de eventos normalmente não controlam o estado do contrato nem executam lógica de negócios adicional depois de emitidos.

Em vez disso, eles fornecem um registro eficiente que softwares externos podem usar para entender o que aconteceu durante uma transação.

Isso faz dos logs de eventos uma ligação importante entre contratos inteligentes on-chain e os aplicativos off-chain que exibem a atividade da blockchain aos usuários.

Como funcionam os logs de eventos

Um log de evento é criado enquanto a Ethereum Virtual Machine processa um caminho de execução bem-sucedido dentro de uma transação.

Primeiro, o contrato inteligente declara um evento com um nome e uma lista de parâmetros.

Em seguida, o contrato emite esse evento quando o código chega à instrução correspondente.

O compilador Solidity converte a emissão do evento em uma das operações de logging da EVM.

O log resultante contém o endereço do contrato que o emitiu, uma lista de topics pesquisáveis e um campo de dados com informações codificadas adicionais.

Depois que a transação é incluída em um bloco, o log passa a fazer parte do recibo da transação.

Os aplicativos podem recuperar o log por meio de um nó da Ethereum, um provedor RPC, um explorador de blockchain ou um indexador especializado.

O guia da Ethereum sobre logging de eventos de contratos inteligentes explica que aplicativos descentralizados podem monitorar eventos emitidos e realizar ações off-chain quando eles aparecem.

Se a transação for revertida, os logs criados durante a execução revertida também serão removidos do resultado final da transação.

Isso significa que um log exibido durante uma simulação ou em um rastreamento de execução pode não aparecer no recibo confirmado quando a chamada inteira falha.

Eventos vs. logs de eventos

Um evento é a declaração definida pelo desenvolvedor que descreve quais informações um contrato pode publicar.

Um log de evento é o registro efetivo criado quando o contrato emite esse evento durante uma transação.

Por exemplo, um contrato pode definir um evento Transfer no código-fonte.

Cada transferência concluída pode criar um log separado com base nessa definição de evento.

O evento funciona como um modelo, enquanto cada log representa uma ocorrência registrada desse modelo.

Uma única transação pode não gerar logs, gerar um log ou gerar vários logs.

Uma transação que interage com vários contratos inteligentes pode produzir logs de cada contrato envolvido na execução.

Os aplicativos usam a Application Binary Interface (ABI) do contrato para associar logs brutos às declarações de eventos e decodificar os valores.

Quais informações são armazenadas em um log de evento?

Um log de evento da EVM contém o endereço do contrato emissor, de zero a quatro topics e um campo de dados de tamanho variável.

O endereço emissor identifica o contrato cuja execução criou o log.

Os topics contêm valores projetados para filtragem e pesquisa eficientes.

O campo de dados armazena os parâmetros do evento que não foram marcados como indexed.

As interfaces RPC comuns também retornam metadados da transação e do bloco junto com os logs.

Esses metadados podem incluir o hash da transação, o índice da transação, o hash do bloco, o número do bloco e o índice do log.

O índice do log identifica sua posição entre os outros logs do mesmo bloco.

Em geral, os aplicativos devem combinar chain ID, hash do bloco, hash da transação e índice do log ao criar um identificador de registro único.

Usar apenas o nome do evento ou o hash da transação pode ser insuficiente, pois uma única transação pode emitir várias vezes o mesmo evento.

O que são event topics?

Topics são valores de 32 bytes colocados em uma parte pesquisável especial de um log da EVM.

Eles permitem que um aplicativo filtre o histórico da blockchain sem decodificar individualmente todos os campos de dados dos eventos.

Um evento padrão da Solidity, não anônimo, pode usar até quatro topics.

O primeiro topic normalmente identifica o tipo de evento, enquanto até três topics adicionais representam parâmetros marcados como indexed.

A ordem dos topics importa: filtrar um valor na segunda posição é diferente de filtrar o mesmo valor na terceira posição.

A documentação oficial da Ethereum sobre eth_getLogs em JSON-RPC explica que os filtros de topics dependem da ordem e podem incluir valores alternativos para a mesma posição.

Os topics são especialmente úteis para pesquisar eventos relacionados a um endereço de carteira, identificador de token, mercado, proposta ou outro valor consultado com frequência.

Uma escolha inadequada de parâmetros indexed pode tornar os dados históricos de um aplicativo difíceis ou caros de pesquisar.

O que é o Topic 0?

O Topic 0 normalmente contém o hash Keccak-256 da assinatura canônica do evento.

A assinatura canônica combina o nome do evento com os tipos ordenados dos parâmetros.

Os nomes dos parâmetros e a palavra-chave indexed não são incluídos no hash da assinatura do evento.

Por exemplo, um evento declarado com o nome Transfer e os tipos de parâmetro address, address e uint256 tem uma assinatura de evento previsível.

Os aplicativos podem comparar o Topic 0 com hashes de assinatura conhecidos para identificar o evento representado por um log bruto.

Alterar o nome do evento ou a ordem e os tipos dos parâmetros cria uma assinatura de evento diferente.

Assim, dois eventos com o mesmo nome, mas tipos de parâmetro diferentes, têm valores distintos de Topic 0.

A especificação da ABI da Solidity para eventos descreve como a assinatura e os argumentos do evento são codificados em topics e dados.

Parâmetros indexed de eventos

Um parâmetro indexed é um argumento de evento armazenado em um topic para que sistemas externos possam filtrá-lo com eficiência.

A Solidity permite até três parâmetros indexed em um evento normal não anônimo.

A posição restante do topic é reservada para a assinatura do evento.

Endereços, números inteiros, valores booleanos e outros valores que cabem em uma palavra de 32 bytes podem ser armazenados diretamente em um topic usando uma codificação compatível com ABI.

Valores dinâmicos, como strings, arrays de bytes, arrays dinâmicos e estruturas complexas, são tratados de outra forma.

Quando um valor dinâmico é indexed, o topic armazena um hash Keccak-256 do valor codificado, em vez do valor original legível.

Um aplicativo pode filtrar esse hash quando já sabe qual valor quer encontrar.

No entanto, não é possível recuperar somente a partir do hash uma string ou um array de bytes original desconhecido.

Às vezes, desenvolvedores incluem a mesma informação duas vezes: uma versão em hash em um parâmetro indexed e uma versão legível em um parâmetro não indexed.

Esse design melhora a facilidade de pesquisa e preserva o valor original para decodificação.

Parâmetros não indexed de eventos

Os parâmetros sem a palavra-chave indexed são armazenados no campo de dados do log.

Esses valores são codificados de acordo com as regras da ABI da Ethereum.

A ABI é necessária porque os dados brutos do log não identificam cada valor com um nome e tipo legíveis por humanos.

Para decodificar os dados com confiabilidade, o aplicativo precisa da definição correta do evento.

Parâmetros não indexed podem conter valores maiores ou mais complexos do que os topics individuais.

Eles são adequados para valores, configurações detalhadas, arrays, strings e outras informações que não precisam de filtragem direta por topic.

Normalmente, os aplicativos não podem pedir ao eth_getLogs que filtre com base em um valor arbitrário dentro do campo de dados.

Primeiro, precisam recuperar os logs usando o endereço do contrato e os topics; depois, podem decodificar e inspecionar os dados localmente.

Eventos anônimos

Um evento da Solidity pode ser declarado como anônimo.

Um evento anônimo não coloca automaticamente o hash de sua assinatura no Topic 0.

Isso permite usar as quatro posições de topics para parâmetros indexed.

No entanto, a ausência do topic de assinatura dificulta a identificação automática do tipo de evento por softwares externos.

Pode ser difícil distinguir eventos anônimos diferentes quando eles usam estruturas semelhantes de topics e dados.

Eventos anônimos podem ser adequados a designs especializados de baixo nível, mas eventos comuns de aplicativos geralmente são mais fáceis de indexar e decodificar quando não são anônimos.

Desenvolvedores devem usar eventos anônimos somente quando o topic indexed adicional oferecer um benefício claro que compense a dificuldade de identificação do evento.

Opcodes de logging da EVM

A EVM oferece cinco opcodes de logging, chamados LOG0 a LOG4.

O número no nome de cada opcode representa a quantidade de topics incluídos no log.

LOG0 cria um log sem topics, enquanto LOG4 cria um log com quatro topics.

Cada operação de logging também lê uma área selecionada da memória da EVM e a armazena como campo de dados do log.

Eventos da Solidity são compilados nessas instruções de logging de nível mais baixo.

O endereço do contrato é associado ao log pelo ambiente de execução, e não fornecido como um parâmetro normal do evento.

Operações de logging consomem gas com base em fatores como o número de topics e a quantidade de dados registrados.

A referência oficial de opcodes da Ethereum lista as instruções de logging da EVM e seus custos de execução.

Logs de eventos e recibos de transações

Um recibo de transação é o registro de execução produzido depois que uma transação é incluída em um bloco.

O recibo contém informações como status da execução, uso cumulativo de gas, um logs bloom e os logs emitidos pela transação.

Respostas RPC podem adicionar outros campos úteis, como o endereço de criação do contrato, o preço efetivo do gas e o gas usado pela transação individual.

O array de logs preserva a ordem em que os eventos foram emitidos durante a execução.

Uma transação bem-sucedida pode ter um array de logs vazio quando nenhum contrato emitiu um evento.

Uma transação malsucedida normalmente não tem logs de eventos preservados, pois suas alterações de estado e logs foram revertidos.

Os aplicativos devem verificar o status do recibo, em vez de tratar a existência de um hash de transação como prova de que a execução foi bem-sucedida.

O método JSON-RPC da Ethereum para recibos de transações descreve os campos de recibo retornados por um cliente de execução.

Logs de eventos e recibos de blocos

Os recibos de transações são comprometidos criptograficamente por meio da receipts root do bloco.

Esse compromisso permite que os participantes da blockchain verifiquem se os recibos pertencem ao histórico de um bloco específico.

Cada recibo contém os logs produzidos por sua transação.

No formato atual dos blocos de execução, o cabeçalho do bloco também inclui um bloom filter que resume os endereços e topics dos logs das transações daquele bloco.

O bloom filter ajuda um cliente a determinar se um bloco pode conter logs correspondentes a uma consulta.

Uma correspondência positiva no bloom filter não comprova que existe um log correspondente, pois esses filtros podem gerar falsos positivos.

Uma correspondência negativa indica que o endereço ou topic pesquisado não aparece nesse filtro.

Para confirmar os valores exatos dos eventos, os aplicativos ainda precisam dos logs dos recibos efetivos.

Logs de eventos vs. armazenamento de contratos

Logs de eventos e armazenamento de contratos inteligentes têm finalidades diferentes.

O armazenamento de contratos contém dados persistentes que execuções futuras de contratos inteligentes podem ler diretamente.

Os logs de eventos foram projetados principalmente para observação externa e indexação histórica.

Contratos em Solidity não podem ler diretamente logs de eventos históricos, inclusive logs emitidos pelo próprio contrato.

A referência da Solidity sobre eventos afirma que dados de logs e eventos não são acessíveis de dentro de contratos.

Um contrato nunca deve depender de um evento anterior como única fonte de dados necessária para decisões on-chain futuras.

Se uma lógica futura do contrato precisar de um valor, normalmente esse valor deverá ser armazenado no estado do contrato ou fornecido por um mecanismo verificável.

Para informações destinadas apenas a usuários off-chain, os logs geralmente custam menos do que o armazenamento persistente.

No entanto, usar um log em vez do armazenamento muda o que contratos inteligentes poderão verificar ou recuperar posteriormente.

Logs de eventos vs. dados retornados por funções

Os dados retornados por uma função são enviados ao chamador imediato durante a execução do contrato.

Os logs de eventos são armazenados nos recibos de transações para recuperação off-chain posterior.

Uma transação que altera o estado não fornece dados retornados a uma interface de usuário no mesmo formato histórico conveniente de um log de evento.

Os aplicativos geralmente dependem de recibos e eventos para saber o resultado de uma transação enviada.

Chamadas somente para leitura podem retornar valores sem criar logs de eventos nem alterar o estado da blockchain.

Desenvolvedores devem usar valores retornados para comunicação imediata entre chamadas de contratos e eventos para notificações off-chain duradouras.

Um evento não deve ser tratado como resposta direta de uma função, pois vários contratos podem emitir logs durante uma única transação.

Como os aplicativos consultam logs de eventos

Os aplicativos geralmente consultam logs históricos por meio do método JSON-RPC eth_getLogs.

Uma consulta pode especificar bloco inicial, bloco final, endereço do contrato, hash do bloco e filtros de topics.

O método retorna um array com os logs que correspondem ao filtro.

Uma consulta restrita costuma ser mais confiável e eficiente do que solicitar todos os logs de uma faixa muito ampla de blocos.

Provedores de RPC podem impor limites a intervalos de blocos, tamanho das respostas, tempo das solicitações ou frequência das consultas.

Os aplicativos devem dividir pesquisas históricas grandes em intervalos menores de blocos e salvar o progresso.

Também devem repetir solicitações com falha usando intervalos controlados, em vez de presumir que uma resposta vazia ou com falha comprova que não existem eventos.

O uso do filtro blockHash definido pela EIP-234 pode ajudar um aplicativo a solicitar logs de um bloco exato.

Consultas periódicas e assinaturas de eventos

Um aplicativo pode descobrir novos logs de eventos por meio de consultas periódicas ou assinaturas.

As consultas periódicas solicitam repetidamente a um nó logs ou alterações de filtros ao longo do tempo.

Uma assinatura mantém uma conexão ativa para que o nó possa enviar notificações de novos logs à medida que os blocos chegam.

As assinaturas podem fornecer atualizações mais rápidas, mas a conexão pode cair ou perder informações durante uma interrupção.

As consultas periódicas podem ser mais fáceis de recuperar, pois o aplicativo pode solicitar novamente um intervalo de blocos conhecido.

Um sistema robusto de produção costuma combinar assinaturas em tempo real com conciliação periódica baseada em blocos.

Essa abordagem permite que o aplicativo detecte logs perdidos durante interrupções de rede ou reinicializações de nós.

A documentação oficial da API JSON-RPC da Ethereum descreve métodos de filtro para recuperar logs que apareceram desde uma consulta anterior.

Logs de eventos e reorganizações da blockchain

Uma reorganização ocorre quando um bloco considerado anteriormente parte da cadeia ativa é substituído por outro histórico de blocos.

Os logs do bloco substituído deixam de fazer parte da blockchain canônica.

Um aplicativo que tenha reagido imediatamente a esses logs talvez precise reverter as alterações feitas em seu banco de dados local.

Algumas respostas de assinatura RPC podem indicar que um log informado anteriormente foi removido devido a uma reorganização.

No entanto, desconexões de rede podem impedir que o aplicativo receba a notificação de remoção.

Indexadores confiáveis acompanham os hashes dos blocos e as relações com os blocos anteriores para detectar de forma independente blocos substituídos.

A justificativa da filtragem de logs por hash de bloco explica por que os aplicativos precisam lidar com cuidado com reorganizações e falhas de conexão.

Sistemas financeiros normalmente devem aguardar um número adequado de confirmações ou um nível de finalidade antes de tratar um evento como irreversível.

O nível necessário depende da blockchain, do valor da aplicação e das consequências de agir cedo demais.

Logs de eventos e finalidade

Um evento recém-emitido pode aparecer em um bloco proposto antes que esse bloco alcance uma finalidade de consenso mais forte.

Os aplicativos podem consultar logs usando tags de bloco como latest, safe ou finalized, quando o cliente conectado oferecer suporte a elas.

A tag latest fornece informações mais rapidamente, mas pode incluir blocos com maior risco de reorganização.

A tag finalized oferece mais confiança, mas introduz um atraso adicional.

Uma interface de portfólio pode aceitar eventos latest para exibição, enquanto uma bridge ou transferência financeira de grande valor pode exigir confirmações mais robustas.

Os aplicativos devem escolher a política de confirmações com base no risco econômico, em vez de aplicar a mesma regra a todos os eventos.

Logs de eventos em contratos de tokens

Padrões de tokens usam logs de eventos para tornar transferências e aprovações visíveis a carteiras e sistemas de dados blockchain.

Um token fungível geralmente emite um evento Transfer quando o valor passa entre endereços.

Ele também pode emitir um evento Approval quando um titular altera a permissão de gasto de outro endereço.

Contratos de NFT geralmente emitem eventos de transferência e aprovação que contêm identificadores de tokens.

Contratos de mult tokens podem emitir eventos de transferência única e de transferência em lote.

Estruturas padronizadas de eventos permitem que ferramentas externas ofereçam suporte a muitos contratos de tokens usando a mesma lógica de decodificação.

No entanto, um token pode emitir eventos enganosos ou não seguir corretamente um padrão.

Um evento, por si só, não comprova que um contrato é legítimo, valioso ou seguro.

Logs de eventos em finanças descentralizadas

Protocolos de finanças descentralizadas usam logs de eventos para descrever ações financeiras complexas.

Entre os exemplos comuns estão depósitos, saques, swaps, empréstimos, pagamentos, liquidações, atualizações de juros, resgates de recompensas e alterações de governança.

Uma interface de usuário pode monitorar esses eventos para atualizar saldos e históricos de transações.

Um sistema de análise pode agregá-los para calcular volume, liquidez, atividade de empréstimos ou receita do protocolo.

Um serviço de monitoramento de risco pode acompanhar eventos de liquidação ou colateral para detectar posições sob pressão.

Como uma transação DeFi pode chamar vários contratos, o recibo pode conter muitos logs relacionados.

Os aplicativos devem considerar o endereço emissor e a ordem dos logs, em vez de decodificar todo evento conhecido como se tivesse vindo do contrato principal do protocolo.

Logs de eventos em carteiras e exploradores de blockchain

Carteiras usam logs de eventos para criar históricos legíveis a partir de transações brutas de contratos inteligentes.

Uma transferência de token pode não aparecer como uma movimentação direta de ativo nativo nos campos básicos da transação.

A carteira pode decodificar o evento Transfer do contrato do token para exibir o ativo, o remetente, o destinatário e o valor.

Exploradores de blockchain também decodificam logs usando ABIs de contratos verificados e assinaturas de eventos conhecidas.

Quando o código-fonte ou as informações da ABI não estão disponíveis, o explorador pode exibir valores brutos de topics e dados.

Um rótulo decodificado deve ser tratado como uma interpretação do log bruto, e não como uma garantia independente da intenção do contrato.

Os usuários devem verificar o endereço do contrato emissor antes de confiar na descrição de um evento.

Logs de eventos e indexadores de blockchain

Um indexador de blockchain lê blocos e recibos e armazena dados de eventos selecionados em um banco de dados otimizado para consultas.

Os indexadores facilitam responder a perguntas difíceis de resolver por meio de solicitações RPC diretas.

Entre os exemplos estão recuperar todas as transferências de tokens de uma carteira, calcular a atividade de um protocolo ao longo do tempo ou acompanhar todas as posições abertas em um mercado de empréstimos.

Um indexador geralmente começa em um bloco escolhido e processa novos blocos em ordem.

Ele decodifica os logs relevantes, cria registros no banco de dados e armazena as informações dos blocos necessárias para lidar com reorganizações.

Os indexadores devem conseguir retomar o processamento após uma falha sem pular ou duplicar eventos.

Também devem reprocessar dados históricos quando o esquema de decodificação ou a lógica do aplicativo muda.

A documentação da Ethereum sobre dados e análises explica como os sistemas de dados blockchain trabalham com logs, recibos, rastreamentos e outras informações de execução.

Logs de eventos e automação off-chain

Serviços off-chain podem monitorar logs de eventos e acionar ações fora da blockchain.

Um serviço pode enviar uma notificação após um depósito, atualizar um banco de dados interno após uma negociação ou iniciar outro fluxo de trabalho após uma votação de governança.

O log, por si só, não obriga o serviço off-chain a agir.

O serviço precisa permanecer online, receber o evento, validá-lo e decidir o que fazer.

A automação off-chain deve verificar o chain ID, o endereço do contrato, o status do bloco e os valores decodificados antes de realizar uma ação sensível.

Ela também deve ser idempotente, ou seja, processar o mesmo evento duas vezes não deve criar um resultado duplicado incorreto.

Essa proteção é importante porque novas tentativas, reconexões e reorganizações podem fazer com que o mesmo log seja observado mais de uma vez.

Contratos inteligentes podem ler logs de eventos?

Contratos inteligentes não podem pesquisar diretamente logs históricos de eventos durante a execução normal da EVM.

Os logs foram projetados para aplicativos externos, e não como estado legível por contratos.

Um contrato que precisa de informações de um evento anterior deve recebê-las por outro mecanismo.

Entre os mecanismos possíveis estão o armazenamento do contrato, uma prova criptográfica, um oráculo ou um protocolo de mensagens cross-chain.

O contrato precisa verificar se as informações fornecidas são confiáveis antes de usá-las.

Essa limitação impede que contratos inteligentes tratem automaticamente uma resposta RPC off-chain como dados on-chain válidos.

É possível alterar logs de eventos?

Um log confirmado não pode ser editado independentemente da transação e do bloco que o produziram.

Alterar o log exigiria substituir ou invalidar o histórico da blockchain que contém aquele recibo.

Uma reorganização pode remover um log do histórico ativo antes que uma finalidade mais forte seja alcançada.

Uma nova transação pode emitir um evento corretivo ou reverso, mas não apaga o log canônico anterior.

Os aplicativos devem preservar eventos históricos e registrar correções como entradas posteriores, em vez de reescrever silenciosamente os dados originais da blockchain.

É possível falsificar logs de eventos?

Qualquer contrato inteligente pode definir e emitir um evento com nome e assinatura conhecidos.

Por isso, um contrato malicioso pode emitir um evento Transfer semelhante ao de um contrato de token legítimo.

A assinatura do evento, por si só, não identifica o ativo nem comprova que houve uma alteração real de saldo em um contrato confiável.

Os aplicativos precisam verificar o endereço do contrato emissor e compreender o código e o estado desse contrato.

Um token fraudulento também pode emitir valores enganosos ou criar eventos que façam uma carteira inativa parecer ter recebido um ativo.

Carteiras e exploradores devem evitar tratar todas as assinaturas de eventos conhecidas como igualmente confiáveis.

Os usuários não devem interagir com um token apenas porque um evento de transferência inesperado aparece no histórico de transações.

Logs de eventos e segurança de contratos inteligentes

O design de eventos faz parte da segurança dos contratos inteligentes, pois sistemas de monitoramento dependem de logs precisos.

Ações administrativas importantes devem emitir eventos claros quando permissões, taxas, endereços de oráculos, implementações de atualização ou configurações de emergência forem alterados.

A ausência de eventos pode dificultar a detecção de alterações perigosas por usuários e equipes de segurança.

Valores incorretos em eventos podem fazer sistemas off-chain exibir um resultado diferente do estado do contrato.

Um contrato só deve emitir um evento depois que as verificações e as alterações de estado relacionadas forem concluídas com sucesso.

Desenvolvedores devem testar se cada caminho de execução importante emite o log esperado exatamente uma vez.

Também devem testar se transações revertidas não deixam logs finais enganosos.

Um evento não deve substituir a aplicação de regras de permissões e saldos no código do contrato.

Custos de gas dos logs de eventos

Emitir um evento consome gas porque a EVM precisa processar a instrução de logging e adicionar informações ao recibo da transação.

Mais topics e campos de dados maiores geralmente aumentam o custo do logging.

Por isso, um evento com vários valores grandes pode custar mais do que um evento mínimo.

Os logs costumam custar menos do que armazenar as mesmas informações no armazenamento persistente do contrato.

No entanto, logs desnecessários ainda aumentam os custos das transações para os usuários e o tamanho do histórico da blockchain.

Desenvolvedores devem emitir informações que atendam a uma necessidade real de indexação, monitoramento, auditoria ou interface de usuário.

Devem evitar copiar todos os cálculos internos para eventos separados quando sistemas externos não precisarem deles.

A otimização de gas não deve remover a transparência essencial para monitorar com segurança a atividade de um protocolo.

Boas práticas para criar eventos

Os nomes dos eventos devem descrever claramente a ação ocorrida.

Os nomes dos parâmetros devem ser específicos o suficiente para que desenvolvedores e analistas entendam seu significado.

Valores pesquisados com frequência pelos usuários devem ser considerados para parâmetros indexed.

Entre os valores indexed comuns estão endereços de contas, identificadores de tokens, identificadores de mercados e identificadores de propostas.

Valores e configurações detalhadas geralmente podem permanecer no campo de dados quando a filtragem direta não for necessária.

Desenvolvedores devem evitar indexar valores dinâmicos, a menos que a filtragem por hash seja especificamente útil.

Cada evento deve incluir contexto suficiente para ser interpretado sem depender de suposições frágeis sobre a ordem das transações.

Contratos compatíveis com vários ativos ou mercados devem incluir o identificador correspondente do ativo ou do mercado.

Eventos de atualização devem identificar tanto o valor antigo quanto o novo quando essa informação ajudar no monitoramento.

As declarações de eventos devem permanecer estáveis quando aplicativos externos dependerem de sua assinatura e da disposição dos parâmetros.

Boas práticas para ler logs de eventos

Os aplicativos devem filtrar pelo endereço esperado do contrato e pela assinatura esperada do evento.

Devem decodificar logs com a versão correta da ABI para a implementação do contrato ativa naquele bloco.

Contratos atualizáveis podem alterar os eventos disponíveis após uma atualização de implementação.

Indexadores devem armazenar hash do bloco, número do bloco, hash da transação, índice da transação e índice do log.

Devem processar logs na ordem canônica dos blocos e oferecer suporte à reversão após uma reorganização.

Consultas históricas extensas devem ser divididas em intervalos de blocos gerenciáveis.

Os aplicativos devem diferenciar uma resposta realmente vazia de uma solicitação com falha, truncada ou limitada por frequência.

Ações financeiras devem aguardar um nível de confirmação adequado ao valor e ao risco envolvidos.

Quando a precisão for especialmente importante, os aplicativos devem comparar valores derivados dos eventos com o estado do contrato.

Logs de eventos em redes Layer 2

Redes Layer 2 baseadas na EVM geralmente usam logs de eventos com estruturas semelhantes às dos logs da Ethereum.

Desenvolvedores costumam poder usar eventos Solidity, topics, ABIs e consultas JSON-RPC conhecidos.

No entanto, sistemas Layer 2 podem ter tempos de bloco, regras de confirmação, sequenciadores, estruturas de taxas e processos de liquidação final diferentes.

Um log confirmado por um sequenciador de Layer 2 talvez ainda não tenha alcançado seu status de liquidação mais forte na Ethereum.

Eventos relacionados a bridges podem aparecer tanto na rede de origem quanto na rede de destino em diferentes etapas de uma transferência.

Os aplicativos precisam acompanhar a rede correta e não devem tratar eventos de redes separadas como um único histórico de logs compartilhado.

O mesmo endereço de contrato ou assinatura de evento pode representar contratos e ativos diferentes em redes diferentes.

Logs de eventos em transferências cross-chain

Sistemas cross-chain costumam usar eventos para sinalizar que ativos foram bloqueados, queimados, liberados ou emitidos.

Um relayer off-chain ou protocolo da rede de destino pode observar o evento da rede de origem antes de dar continuidade à transferência.

A ação no destino precisa verificar o evento de origem por meio do sistema de provas ou validadores da bridge.

Simplesmente ver um log por meio de um provedor RPC comum não basta para que um contrato inteligente trustless comprove a validade do evento.

As bridges também precisam considerar reorganizações e finalidade da rede de origem.

Uma bridge que aja rápido demais pode processar um evento posteriormente removido do histórico canônico da rede de origem.

Os usuários devem entender que um evento emitido por uma bridge pode representar o início de uma transferência, e não sua conclusão final.

Exemplo de log de evento

Suponha que um usuário transfira 500 unidades de um token fungível para outra carteira.

O usuário envia uma transação que chama a função transfer do contrato do token.

O contrato verifica o saldo do remetente e atualiza os saldos do remetente e do destinatário.

Em seguida, o contrato emite um evento Transfer contendo o endereço do remetente, o endereço do destinatário e o valor transferido.

Os endereços do remetente e do destinatário podem ser armazenados como topics indexed, enquanto o valor é codificado segundo a ABI no campo de dados.

O hash da assinatura do evento aparece no Topic 0.

Depois que a transação é incluída em um bloco, o log aparece no recibo da transação.

Uma carteira recupera e decodifica o log para exibir a movimentação do token em um histórico de transações legível.

Um indexador também registra o evento para que usuários possam pesquisar todas as transferências relacionadas a qualquer um dos endereços.

Esse exemplo mostra como um log de evento conecta a execução de contratos a carteiras, exploradores e análises de blockchain.

Erros comuns com logs de eventos

Um erro comum é presumir que outro contrato inteligente pode ler um evento.

Outro erro é tratar uma assinatura de evento conhecida como prova de que o contrato emissor é legítimo.

Um terceiro erro é decodificar um log sem verificar o endereço do contrato.

Um quarto erro é presumir que uma string indexed pode ser recuperada diretamente de seu hash de topic.

Um quinto erro é usar somente o hash da transação como identificador de um log.

Um sexto erro é não lidar com reorganizações da blockchain.

Um sétimo erro é processar o mesmo log duas vezes após uma nova tentativa RPC ou reinicialização do aplicativo.

Um oitavo erro é consultar um intervalo de blocos extremamente grande e tratar uma solicitação expirada como resultado vazio.

Um nono erro é depender apenas de eventos quando a lógica futura do contrato inteligente precisa dos mesmos dados no armazenamento.

Um décimo erro é presumir que um evento decodificado com sucesso comprova que todas as alterações de estado pretendidas ocorreram corretamente.

Perguntas frequentes

O que são logs de eventos em cripto?

Logs de eventos são registros estruturados emitidos por contratos inteligentes para descrever ações ocorridas durante a execução de transações na blockchain.

Onde os logs de eventos da Ethereum são armazenados?

Os logs de eventos da Ethereum são incluídos nos recibos de transações, que são comprometidos como parte do histórico de execução do bloco.

Qual é a diferença entre um evento e um log?

Um evento é uma declaração no código de um contrato inteligente, enquanto um log é o registro efetivo criado quando esse evento é emitido.

Contratos inteligentes podem ler logs de eventos antigos?

Não. Contratos inteligentes não podem pesquisar nem ler diretamente logs históricos durante a execução normal da EVM.

O que é o Topic 0 em um log de evento da Ethereum?

O Topic 0 normalmente contém o hash Keccak-256 do nome do evento e dos tipos canônicos de seus parâmetros.

Quantos topics um log de evento pode ter?

Um log da EVM pode ter até quatro topics. Em geral, um evento normal da Solidity reserva um deles para a assinatura do evento.

O que significa indexed em um evento da Solidity?

Um parâmetro indexed é armazenado em um topic para que aplicativos externos possam filtrar logs com base nesse valor.

É possível indexar strings em logs de eventos?

Sim, mas uma string indexed é representada por um hash Keccak-256, e não pela string original legível.

O que acontece com os logs de eventos quando uma transação é revertida?

Os logs produzidos durante a execução revertida são removidos do resultado final da transação.

Logs de eventos custam gas?

Sim. Emitir um log consome gas, em parte conforme a quantidade de topics e o tamanho dos dados.

Um log de evento pode comprovar que um token é legítimo?

Não. Qualquer contrato pode emitir um evento conhecido, então os usuários precisam verificar o contrato emissor e seu estado efetivo.

Como desenvolvedores podem recuperar logs de eventos?

Desenvolvedores podem recuperar logs por meio de métodos como eth_getLogs, consultas de recibos, filtros, assinaturas, exploradores de blockchain ou serviços de indexação.

Uma reorganização da blockchain pode remover um log de evento?

Sim. Um log de um bloco substituído é removido do histórico canônico da blockchain.

Os logs de eventos são iguais em todas as blockchains EVM?

A estrutura básica costuma ser semelhante, mas chain IDs, contratos, histórico de blocos, finalidade e comportamento RPC podem variar.

Logs de eventos são mais baratos do que o armazenamento de contratos?

Os logs costumam ser mais baratos para informações históricas off-chain, mas não substituem dados de armazenamento que execuções futuras de contratos inteligentes precisam ler.

Por que as carteiras usam logs de eventos?

As carteiras usam logs de eventos para identificar transferências de tokens, aprovações, swaps e outras ações de contratos inteligentes que não ficam claras apenas pelos campos básicos da transação.

Conclusão

Logs de eventos são registros estruturados que conectam a execução de contratos inteligentes a carteiras, aplicativos descentralizados, exploradores de blockchain, sistemas de análise e outros serviços off-chain.

Eles são criados por meio de instruções de logging da EVM e armazenados nos recibos de transações após uma execução bem-sucedida.

Um log contém o endereço do contrato emissor, topics pesquisáveis e dados do evento codificados segundo a ABI.

O Topic 0 normalmente identifica a assinatura do evento, enquanto parâmetros indexed oferecem opções adicionais de filtragem.

Parâmetros não indexed são armazenados no campo de dados e exigem a ABI correta para decodificação.

Logs de eventos são diferentes do armazenamento de contratos porque contratos inteligentes não podem ler diretamente logs históricos.

Também são diferentes dos dados retornados por funções, pois os logs foram projetados para permanecer disponíveis para processamento histórico off-chain.

Os aplicativos podem recuperar logs por meio de filtros JSON-RPC, assinaturas, recibos de transações, exploradores de blockchain e indexadores especializados.

Sistemas confiáveis precisam lidar com processamento duplicado, limitações de RPC, reorganizações da blockchain, atualizações de contratos e diferentes níveis de confirmação.

Os usuários devem lembrar que um nome de evento conhecido não comprova que o contrato emissor é confiável ou que um token é legítimo.

Desenvolvedores devem criar eventos com nomes claros, parâmetros indexed úteis, contexto suficiente e esquemas estáveis.

Entender os logs de eventos ajuda usuários e desenvolvedores de cripto a interpretar com mais precisão transferências de tokens, atividade DeFi, alterações em contratos inteligentes, recibos de transações e dados de aplicativos on-chain.