Função fallback

O que é uma função fallback?

Uma função fallback é uma função especial da Solidity que processa chamadas externas que não correspondem a nenhuma outra função definida por um contrato inteligente.

Ela funciona como a opção final de roteamento de chamadas do contrato quando a Solidity não consegue identificar uma função comum com base nos dados da transação fornecidos.

A função fallback também pode ser executada quando uma chamada não contém dados e o contrato não tem uma função receive separada.

Ela é amplamente usada em aplicações de criptomoedas, incluindo contratos inteligentes atualizáveis, sistemas de proxy, carteiras modulares, contratos de pagamento e roteadores de chamadas personalizados.

De acordo com a documentação oficial da Solidity, um contrato pode conter no máximo uma função fallback.

A função fallback deve ter visibilidade external, pois foi projetada para responder a chamadas recebidas de fora do contrato.

Ela pode ser payable quando o contrato precisa aceitar criptomoeda nativa por meio de uma chamada não correspondente a outra função.

Quando usada em sua forma avançada, ela também pode inspecionar todos os dados da transação e retornar dados brutos de resposta.

A função fallback não é um manipulador geral de erros para todas as operações malsucedidas de um contrato inteligente.

Ela é executada somente sob condições específicas de roteamento de chamadas definidas pela Solidity e pela Ethereum Virtual Machine.

Por que ela é chamada de função fallback?

A palavra fallback descreve uma ação alternativa usada quando a ação preferencial ou esperada não está disponível.

Quando um usuário chama uma função normal de um contrato inteligente, a Solidity tenta primeiro corresponder os dados da transação fornecidos a uma das funções declaradas no contrato.

Se não houver correspondência, o contrato recorre à função fallback.

Esse comportamento permite que os desenvolvedores definam o que deve acontecer quando uma carteira, um contrato inteligente ou uma aplicação envia uma chamada não compatível.

A função fallback pode rejeitar a chamada, aceitar um pagamento, registrar um evento, retornar dados ou encaminhar a chamada para outro contrato.

Se o contrato não tiver uma função fallback adequada, a chamada não compatível normalmente será revertida.

Quando uma função fallback é chamada?

Uma função fallback é chamada quando uma chamada externa chega a um contrato inteligente e nenhuma função normal corresponde ao seletor de função fornecido.

Ela também é chamada quando a chamada contém calldata vazia e o contrato não define uma função receive.

Uma chamada com dados pode chegar à função fallback, transferindo ou não criptomoeda nativa.

A função fallback deve ser payable quando a chamada inclui um valor diferente de zero em criptomoeda.

Uma função fallback nonpayable rejeita uma chamada não correspondente que tente transferir valor.

Quando o contrato define uma função receive, uma chamada com dados vazios é direcionada a ela.

Assim, as responsabilidades da função fallback variam conforme o contrato também contenha ou não uma função receive.

Como funciona o roteamento de funções em contratos inteligentes

As chamadas externas a contratos inteligentes geralmente contêm dados de transação codificados, conhecidos como calldata.

Os quatro primeiros bytes de uma chamada de função padrão contêm um seletor de função.

A especificação ABI da Solidity define o seletor como os quatro primeiros bytes do hash Keccak-256 da assinatura canônica de uma função.

Uma assinatura canônica combina o nome da função com os tipos de seus parâmetros.

A Solidity compara o seletor recebido com os seletores das funções públicas e externas do contrato.

Quando há um seletor correspondente, a função correspondente processa a chamada.

Quando não há um seletor correspondente, a Solidity encaminha a chamada à função fallback, se houver uma disponível.

Em geral, uma calldata com menos de quatro bytes não consegue identificar uma função comum da Solidity e, por isso, pode chegar à função fallback.

Uma calldata vazia segue uma regra de roteamento separada, que dá prioridade à função receive.

Função fallback vs. função receive

A função fallback e a função receive são pontos de entrada distintos da Solidity, com finalidades diferentes.

A função receive foi projetada especificamente para chamadas com calldata vazia.

A função fallback processa principalmente chamadas com dados que não correspondem a uma função declarada.

A função receive é sempre payable, pois sua finalidade principal é aceitar criptomoeda nativa.

A função fallback só é payable quando o desenvolvedor permite explicitamente que ela aceite valor.

Quando um contrato define as duas funções, uma transferência com dados vazios é direcionada à função receive.

Uma chamada com dados que não correspondem a uma função é direcionada à função fallback.

Quando o contrato não tem uma função receive, uma função fallback payable pode processar uma transferência com dados vazios.

As orientações atuais da Solidity sobre o recebimento de criptomoedas recomendam definir uma função receive quando houver uma função fallback payable.

Essa separação ajuda a diferenciar um pagamento intencional de uma chamada de função codificada incorretamente.

Função fallback vs. função normal

Uma função normal da Solidity tem um nome declarado e, em geral, seu próprio seletor de função.

As aplicações podem chamar uma função normal por meio de uma interface de contrato conhecida.

A função fallback não tem um nome comum que possa ser chamado.

Ela não tem um seletor próprio que os usuários possam chamar diretamente.

Em vez disso, processa chamadas que não correspondem à interface normal do contrato.

Um contrato pode conter várias funções normais, mas apenas uma função fallback.

Em geral, as funções normais devem conter a lógica de negócios principal de uma aplicação descentralizada.

A função fallback deve ter uma finalidade restrita e claramente documentada, a menos que seja usada intencionalmente como roteador de proxy.

Função fallback vs. tratamento de erros

A função fallback não é executada sempre que outra função de contrato inteligente falha.

Se a calldata corresponder a uma função normal e essa função for revertida posteriormente, a função fallback não será chamada.

Se uma função correspondente rejeitar um pagamento por não ser payable, a Solidity não redirecionará o pagamento para a função fallback.

Se o seletor de função estiver correto, mas os argumentos estiverem malformados, a chamada correspondente normalmente será revertida durante a decodificação.

Uma falha em uma condição obrigatória, verificação aritmética, regra de controle de acesso, chamada externa ou erro personalizado também não ativa a função fallback.

Os desenvolvedores devem tratar essas falhas usando o tratamento normal de erros, verificações de valores de retorno, erros personalizados ou a lógica try-and-catch aplicável.

A função fallback processa chamadas não correspondentes, e não falhas dentro de chamadas correspondentes.

O que é uma função fallback payable?

Uma função fallback payable pode aceitar criptomoeda nativa anexada a uma chamada externa não correspondente.

O valor enviado com a chamada fica disponível no campo de valor da transação.

O endereço do remetente também fica disponível para a função fallback.

Quando há gas suficiente, uma função fallback payable pode atualizar o estado, emitir um evento, encaminhar a chamada ou executar outra ação permitida.

Tornar uma função fallback payable cria responsabilidades financeiras para o contrato.

O contrato pode precisar de contabilidade confiável de saldos, saques controlados, procedimentos de emergência e proteção contra reentrância.

Em geral, um contrato que não foi projetado para manter criptomoedas deve rejeitar pagamentos inesperados.

A capacidade de receber pagamentos só deve ser incluída quando servir a uma finalidade definida pelo protocolo.

O que é uma função fallback nonpayable?

Uma função fallback nonpayable pode processar chamadas não correspondentes que não transferem criptomoeda nativa.

Uma chamada não correspondente com valor diferente de zero será revertida se a função fallback não for payable.

Esse modelo é útil quando um contrato precisa de roteamento ou registro personalizados, mas não deve aceitar fundos.

Uma função fallback nonpayable também pode rejeitar explicitamente seletores de função não compatíveis.

Rejeitar chamadas desconhecidas pode ajudar usuários e aplicações a detectar o uso de uma interface incorreta.

Quais informações uma função fallback pode ler?

Uma função fallback pode acessar o endereço que iniciou a chamada atual.

Quando é payable, ela pode acessar o valor de criptomoeda nativa anexado à chamada.

Ela pode inspecionar toda a calldata fornecida pelo remetente da chamada.

A calldata completa inclui o possível seletor e quaisquer valores codificados adicionais.

A forma parametrizada da função fallback pode receber esses dados como uma sequência de bytes.

Ela também pode retornar bytes brutos diretamente ao remetente da chamada.

A Solidity não aplica automaticamente a codificação ABI normal aos dados brutos retornados pela função fallback.

Esse comportamento é particularmente útil para contratos proxy que precisam retornar exatamente o que um contrato de implementação retornou.

Uma função fallback deve decodificar a calldata?

Uma função fallback pode inspecionar e decodificar a calldata manualmente.

Os quatro primeiros bytes podem ser comparados com os seletores esperados.

Os bytes restantes podem ser decodificados nos tipos de parâmetro esperados.

No entanto, a documentação da Solidity recomenda recorrer à decodificação manual na função fallback apenas como último recurso.

Funções normais nomeadas oferecem interfaces mais claras, decodificação automática mais segura e integração mais fácil.

A decodificação manual deve verificar o tamanho da calldata, os deslocamentos, os tipos e os seletores compatíveis.

Dados malformados devem ser rejeitados antes de qualquer alteração sensível de estado.

Uma decodificação incorreta pode causar comportamento inesperado, transações malsucedidas ou vulnerabilidades de segurança.

Funções fallback em contratos proxy atualizáveis

Contratos proxy atualizáveis são um dos usos mais importantes das funções fallback em aplicações de criptomoedas.

Um proxy separa o endereço do contrato e o estado armazenado do código que contém a lógica de negócios da aplicação.

Os usuários enviam transações para o endereço do proxy.

O proxy armazena o endereço de um contrato de implementação que contém a lógica ativa.

As chamadas que não correspondem às funções definidas diretamente pelo proxy chegam à função fallback.

A função fallback encaminha essas chamadas ao contrato de implementação por meio de delegatecall.

A documentação da Ethereum sobre atualizações de proxy explica que essa estrutura permite alterar a lógica de negócios enquanto os usuários continuam interagindo com o mesmo endereço de proxy.

O proxy mantém os saldos e o armazenamento da aplicação após a alteração da implementação.

Essa abordagem pode viabilizar correções de bugs e novos recursos sem exigir que todos os usuários migrem para um novo endereço de contrato.

O que é delegatecall?

Delegatecall é uma operação da Ethereum Virtual Machine que executa o código de outro contrato no contexto do contrato que faz a chamada.

Em um sistema de proxy, o contrato de implementação fornece o código.

O proxy fornece o endereço, o saldo em criptomoeda e o armazenamento persistente.

O remetente original e o valor da transação continuam disponíveis durante a execução delegada.

Assim, a implementação se comporta como se sua lógica fizesse parte do proxy.

O EIP-7 introduziu delegatecall como uma operação de baixo nível para executar código externo preservando o contexto do remetente e do valor da chamada.

Delegatecall é uma operação poderosa porque a implementação pode ler e modificar o armazenamento do proxy.

Pelo mesmo motivo, também é perigosa.

Uma implementação maliciosa ou incompatível pode corromper saldos, permissões, dados de propriedade ou outros estados críticos.

Como uma função fallback de proxy roteia uma chamada

Primeiro, o proxy recebe toda a calldata do usuário.

Sua função fallback identifica o endereço atual da implementação.

O proxy encaminha a calldata original para essa implementação por meio de delegatecall.

A implementação executa sua lógica usando o armazenamento do proxy.

O proxy recebe os dados de resposta da implementação.

Quando a chamada delegada é bem-sucedida, o proxy retorna a mesma resposta ao remetente original.

Quando a chamada delegada falha, o proxy deve devolver ao remetente as informações originais da falha.

Um encaminhamento incorreto pode ocultar erros, modificar os dados de retorno ou fazer com que integrações interpretem o resultado incorretamente.

Slots de armazenamento do proxy

Um proxy precisa armazenar o endereço de sua implementação em algum local do armazenamento persistente do contrato.

Esse local não pode entrar em conflito com as variáveis usadas pelo contrato de implementação.

O ERC-1967 define slots de armazenamento padronizados para informações sobre a implementação, o beacon e o administrador do proxy.

Esses locais são escolhidos para evitar os slots de armazenamento comuns atribuídos pelo compilador da Solidity.

Os slots padronizados também ajudam exploradores de blockchain e ferramentas de desenvolvimento a identificar relações entre proxies.

Usar um slot de armazenamento estabelecido reduz a possibilidade de colisões acidentais, mas não elimina todos os riscos de atualização.

As versões da implementação ainda precisam manter um layout de armazenamento compatível.

Risco do layout de armazenamento

Um proxy mantém os dados existentes quando o contrato de implementação é atualizado.

A nova implementação deve interpretar esses dados armazenados da mesma forma que a implementação anterior.

Alterar a ordem das variáveis de estado existentes pode fazer com que um valor seja lido como outro.

Alterar o tipo de uma variável pode corromper seu significado ou torná-la inacessível.

Alterar a herança também pode modificar o layout de armazenamento esperado.

Novas variáveis de estado devem ser adicionadas de acordo com as regras de armazenamento da arquitetura de proxy escolhida.

Uma atualização pode ser concluída com sucesso no nível da transação e, ainda assim, danificar silenciosamente o armazenamento do contrato.

Por isso, a compatibilidade do armazenamento deve ser verificada antes de cada atualização da implementação.

Colisão de seletores de função

Um seletor de função contém apenas quatro bytes.

Em teoria, duas assinaturas de função diferentes podem produzir o mesmo seletor.

Esse evento é conhecido como colisão de seletores.

Uma colisão é especialmente importante quando tanto o proxy quanto sua implementação definem funções que podem ser chamadas.

O proxy pode interceptar um seletor que o usuário esperava encaminhar à implementação.

O ERC-1967 explica que conflitos entre seletores podem causar respostas inesperadas e até ocultar comportamentos maliciosos do proxy.

Os desenvolvedores devem testar todos os seletores das funções do proxy, da implementação, administrativas e das atualizações planejadas.

O nome de uma função, por si só, não comprova que seu seletor seja exclusivo em vários contratos.

Risco de autoridade de atualização

Um proxy atualizável normalmente tem uma conta ou um mecanismo de governança autorizado a alterar o endereço da implementação.

Quem controla essa autoridade pode alterar o código executado por meio da função fallback.

Uma chave de atualização comprometida pode instalar uma implementação que transfira ativos ou altere saldos de contas.

Um administrador malicioso também pode substituir a lógica legítima por uma lógica prejudicial.

Os usuários devem examinar o endereço do administrador, o número mínimo de assinantes, o processo de governança, o atraso de execução, os poderes de emergência e o histórico de atualizações.

Verificar o código-fonte da função fallback de um proxy não garante que todas as implementações futuras serão seguras.

A possibilidade de atualização envolve confiança contínua na governança e nas operações.

Funções fallback em contratos Diamond

Um contrato Diamond roteia diferentes seletores de função para vários contratos de implementação conhecidos como facets.

A função fallback examina o seletor recebido e identifica a facet responsável por essa função.

Em seguida, encaminha a chamada à facet selecionada por meio de delegatecall.

O ERC-2535 define uma arquitetura de proxy multifacet para sistemas de contratos inteligentes modulares.

Esse modelo pode dar suporte a aplicações com mais lógica do que um único contrato de implementação comportaria de forma prática.

Também é possível adicionar, substituir ou remover grupos específicos de funções.

Essa flexibilidade aumenta a complexidade relacionada a seletores, armazenamento, inicialização, permissões e atualizações.

Analisar apenas uma facet não revela todos os comportamentos acessíveis pelo endereço do Diamond.

Funções fallback em contas inteligentes modulares

Contas de contratos inteligentes podem usar handlers fallback para adicionar recursos modulares.

Um handler pode oferecer suporte a assinaturas, callbacks de tokens, recuperação de conta, permissões de sessão ou interfaces específicas de uma aplicação.

O ERC-7579 descreve os handlers fallback como módulos que podem ampliar as funcionalidades de contas inteligentes.

A conta deve controlar quais handlers podem ser instalados, substituídos e removidos.

Um handler não autorizado pode criar uma via para comportamentos inesperados da conta.

Os usuários de carteiras devem entender que alterar um módulo fallback pode mudar a forma como a conta responde a chamadas externas.

Gas e funções fallback

Uma função fallback pode executar operações complexas quando o remetente fornece gas suficiente.

Ela não deve presumir que todos os remetentes fornecerão a mesma quantidade.

Alguns métodos antigos de transferência de criptomoedas encaminham ao contrato destinatário apenas uma pequena quantidade de gas.

A documentação atual da Solidity alerta que send e transfer estão obsoletos e têm remoção prevista.

Uma quantidade pequena de gas pode ser insuficiente para atualizar o armazenamento, realizar transferências adicionais, criar contratos ou fazer chamadas externas dispendiosas.

Os custos de gas também podem mudar com as atualizações da rede.

Por isso, um fluxo de pagamento deve evitar depender de uma lógica fallback complexa.

Os desenvolvedores não devem considerar uma pequena quantidade de gas como única defesa contra callbacks maliciosos.

Risco de reentrância em funções fallback

Uma função fallback pode chamar outro contrato quando há gas suficiente.

Ela pode chamar novamente o contrato que originalmente enviou criptomoeda ou iniciou a interação.

Esse comportamento pode causar reentrância quando o contrato remetente ainda não concluiu sua contabilidade antes da chamada externa.

As orientações de segurança da Solidity sobre reentrância explicam que chamadas externas a contratos podem permitir que o controle retorne antes da conclusão da operação original.

Os contratos devem validar as condições antes de fazer chamadas externas.

O estado interno crítico deve ser atualizado antes que o controle seja transferido a um contrato não confiável.

Uma proteção adequada contra reentrância pode oferecer uma camada adicional de defesa.

Toda chamada externa deve ser tratada como uma possível execução de código não confiável.

Risco de negação de serviço

Uma função fallback pode ser revertida deliberadamente ou por acidente.

Se outro contrato precisar que um pagamento seja concluído antes de terminar uma operação maior, o destinatário poderá bloquear essa operação.

Uma função fallback também pode consumir gas em excesso ou fazer chamadas externas dispendiosas.

Isso é especialmente perigoso quando uma falha de pagamento faz com que todo um loop de distribuição seja revertido.

As orientações da Solidity sobre o envio de criptomoedas recomendam modelos baseados em saques para muitos sistemas de pagamento.

Um modelo de saque permite que cada destinatário solicite os fundos de forma independente.

Assim, o comportamento da função fallback de um destinatário tem menos chances de bloquear pagamentos destinados a outros usuários.

Sucesso inesperado de chamada de baixo nível

Uma chamada de baixo nível informa se a execução no destino foi bem-sucedida ou revertida.

Um resultado bem-sucedido não comprova que a função nomeada pretendida existia.

Um seletor desconhecido pode chegar a uma função fallback permissiva e ser processado com sucesso.

Um contrato que verifica apenas o status de sucesso pode presumir incorretamente que a operação solicitada foi executada.

Ao usar chamadas de baixo nível, os desenvolvedores devem validar os dados retornados e as alterações de estado esperadas.

Em geral, uma interface tipada é mais segura quando a função de destino já é conhecida.

Funções fallback e criptomoedas nativas

Uma função fallback payable pode aceitar criptomoeda nativa por meio de chamadas não correspondentes.

Quando não há uma função receive, ela também pode processar uma transferência simples com calldata vazia.

Em geral, um contrato sem uma função receive ou fallback payable rejeita transferências diretas comuns.

No entanto, um contrato não pode garantir que seu saldo permanecerá sempre em zero.

A EVM tem mecanismos excepcionais que podem aumentar o saldo de um contrato sem executar sua lógica receive ou fallback.

A contabilidade interna do contrato não deve presumir que seu saldo real sempre corresponde à soma registrada pelas funções de processamento de pagamentos.

Funções fallback e tokens ERC-20

Uma transferência normal de token ERC-20 não chama a função fallback do contrato destinatário.

O contrato do token altera os saldos em seu próprio armazenamento.

O contrato destinatário pode receber um saldo de tokens sem executar nenhum código.

O ERC-20 define as transferências por meio do contrato do token, e não de um callback obrigatório no destinatário.

Um contrato não deve depender da execução da função fallback para detectar todos os depósitos de tokens.

As aplicações costumam usar funções de depósito explícitas ou regras separadas de contabilização de saldos.

Funções fallback e NFTs

Alguns métodos seguros de transferência de NFT chamam uma função receptora específica no contrato de destino.

Essa função receptora é diferente da função fallback genérica.

Se a função receptora esperada não existir, a chamada poderá chegar à função fallback porque seu seletor não corresponde a nenhuma função.

Uma função fallback permissiva não deve simular suporte à recepção de NFTs, a menos que o contrato implemente intencionalmente o comportamento exigido.

Uma resposta incorreta pode fazer com que a transferência seja revertida ou criar problemas para recuperar o ativo.

Uma função fallback pode emitir eventos?

Uma função fallback pode emitir eventos quando recebe um pagamento ou uma chamada não compatível.

Um evento pode registrar o remetente, o valor transferido, o seletor ou outro valor útil.

Essas informações podem ajudar os desenvolvedores a monitorar integrações e investigar atividades inesperadas.

A emissão de eventos consome gas e pode falhar quando o remetente fornece uma quantidade muito limitada.

Os eventos on-chain são públicos e não devem ser tratados como registros confidenciais.

Registrar toda a calldata também pode gerar custos desnecessários, pois os dados da transação já podem ser observados publicamente.

Uma função fallback pode modificar o armazenamento?

Uma função fallback pode modificar o armazenamento do contrato quando há gas suficiente.

Ela pode atualizar contadores, registros de pagamento, permissões, informações de roteamento ou outros estados.

A modificação do armazenamento aumenta o uso de gas e amplia o impacto da função sobre a segurança.

Uma função fallback que altera estados importantes deve ter controles de acesso claros e condições cuidadosamente testadas.

O recebimento de pagamentos não deve depender de gravações no armazenamento quando o remetente pode fornecer apenas uma quantidade limitada de gas.

Uma função fallback pode ser herdada?

Uma função fallback pode participar da herança da Solidity.

Ela pode ser declarada como virtual e substituída por um contrato derivado.

Também pode usar modificadores.

A herança pode dificultar a compreensão do comportamento final das chamadas quando vários contratos contribuem com lógicas relacionadas.

Os auditores devem analisar toda a estrutura de herança compilada, em vez de ler apenas um arquivo-fonte.

Como testar uma função fallback

Os desenvolvedores devem testar uma chamada com um seletor desconhecido de quatro bytes.

Também devem testar uma calldata com menos de quatro bytes.

Devem testar calldata vazia sem criptomoeda anexada.

Devem testar calldata vazia com criptomoeda anexada.

Devem testar calldata não vazia e não correspondente, com e sem valor anexado.

Devem verificar a diferença de roteamento quando há uma função receive.

Um proxy deve ser testado para garantir o encaminhamento correto dos dados de retorno e de reversão.

Os testes de atualização devem confirmar que todo o armazenamento existente permanece válido.

Os testes de segurança devem abranger reentrância, colisões de seletores, calldata malformada, atualizações não autorizadas e gas insuficiente.

Como auditar uma função fallback

Primeiro, uma auditoria deve identificar todos os tipos de chamada que podem chegar à função fallback.

O auditor deve determinar se a função é payable.

É preciso verificar se o contrato tem uma função receive separada.

Todas as atualizações de armazenamento, chamadas externas, modificadores, operações em assembly e verificações de privilégios devem ser examinadas.

Uma auditoria de proxy deve verificar como o endereço da implementação é selecionado.

O destino de delegatecall não pode ser alterável por um usuário não autorizado.

Os dados de retorno e de reversão devem ser encaminhados corretamente.

As atualizações da implementação devem preservar a compatibilidade do armazenamento.

A análise também deve examinar o administrador, o processo de governança, o atraso para atualização e os controles de emergência.

Boas práticas para funções fallback

Sempre que possível, use funções normais nomeadas para o comportamento comum da aplicação.

Defina uma função receive separada quando o contrato aceitar intencionalmente transferências simples de criptomoeda nativa.

Rejeite seletores não compatíveis quando não houver necessidade de roteamento personalizado.

Mantenha simples o comportamento da função fallback relacionado a pagamentos.

Trate toda calldata e todos os remetentes como não confiáveis.

Valide os seletores e o tamanho dos dados antes da decodificação manual.

Use padrões de proxy auditados em vez de criar uma lógica de encaminhamento não testada.

Proteja os locais de armazenamento da implementação, do administrador e do beacon.

Preserve o layout de armazenamento entre as atualizações.

Implemente controles de acesso claros para todas as funções de atualização.

Ao encaminhar chamadas, retorne corretamente os dados de sucesso e de falha.

Use uma ordem segura para as atualizações de estado e uma proteção adequada contra reentrância.

Teste chamadas incomuns que as interfaces de carteira normais talvez nunca gerem.

Use uma versão estável e atual do compilador da Solidity e consulte a lista oficial de bugs conhecidos do compilador.

Erros comuns em funções fallback

Um erro comum é presumir que a função fallback será executada depois que uma função correspondente for revertida.

Outro erro é tornar a função payable sem um sistema seguro de saque.

Alguns contratos aceitam pagamentos simples por meio da função fallback sem definir uma função receive mais clara.

A decodificação manual da calldata pode ser feita sem verificar o tamanho dos dados.

Um contrato que faz uma chamada de baixo nível pode confundir a execução bem-sucedida da função fallback com a execução bem-sucedida da função solicitada.

Um proxy pode armazenar o endereço da implementação em um local que colida com o estado da aplicação.

Uma atualização pode reordenar variáveis e corromper saldos ou permissões.

Um destino de delegatecall sem restrições pode permitir a execução de código arbitrário no contexto do proxy.

Uma função fallback complexa pode falhar ao receber menos gas do que o esperado.

Um desenvolvedor pode esperar incorretamente que uma transferência ERC-20 acione a execução da função fallback.

Equívocos comuns sobre funções fallback

Uma função fallback não é um manipulador universal de erros de contratos inteligentes.

Ela não é chamada após toda transação malsucedida.

Ela não é automaticamente payable.

Ela nem sempre é a função certa para receber pagamentos comuns em criptomoedas.

Um contrato pode conter apenas uma função fallback.

Uma função fallback não tem um seletor de função normal.

Ela pode processar calldata não correspondente mesmo quando nenhuma criptomoeda é transferida.

Uma execução bem-sucedida da função fallback não comprova que o remetente usou a interface correta do contrato.

Uma função fallback de proxy pode expor os usuários a um código que não está armazenado no endereço do proxy.

Verificar apenas o código-fonte do proxy não comprova que sua implementação atual seja segura.

Perguntas frequentes

O que é uma função fallback na Solidity?

Uma função fallback é uma função externa especial que processa chamadas que não correspondem a outra função de um contrato inteligente.

Quando a função fallback é executada?

Ela é executada quando nenhuma função declarada corresponde ao seletor fornecido ou quando a calldata está vazia e não existe uma função receive.

Um contrato pode ter várias funções fallback?

Não. Um contrato da Solidity pode ter no máximo uma função fallback.

Uma função fallback tem nome?

Não. Ela é declarada com a palavra-chave fallback, e não com um nome de função comum.

Uma função fallback precisa ser external?

Sim. Uma função fallback deve usar visibilidade external.

Uma função fallback é automaticamente payable?

Não. Ela só aceita criptomoeda nativa quando é explicitamente marcada como payable.

O que acontece quando um valor é enviado para uma função fallback nonpayable?

A chamada não correspondente é revertida quando tenta transferir um valor diferente de zero.

Qual é a diferença entre fallback e receive?

Receive processa calldata vazia, enquanto fallback processa principalmente chamadas que não correspondem a uma função declarada.

Qual função processa uma transferência simples de criptomoeda?

Quando existe, a função receive processa a transferência. A função fallback payable só a processa quando não há uma função receive.

A função fallback é executada depois que outra função falha?

Não. Uma falha dentro de uma função correspondente não redireciona a execução para fallback.

A função fallback pode inspecionar os dados da transação?

Sim. Ela pode acessar toda a calldata fornecida pelo remetente.

A função fallback pode retornar dados?

Sim. Sua forma avançada pode retornar bytes brutos diretamente ao remetente.

Por que contratos proxy usam fallback?

Eles a usam para encaminhar chamadas dos usuários a um contrato de implementação por meio de delegatecall.

O que delegatecall preserva?

Ela preserva o remetente e o valor originais enquanto executa o código da implementação usando o armazenamento e o saldo do proxy.

Delegatecall modifica o armazenamento da implementação?

Não. Em geral, o código delegado da implementação lê e grava no armazenamento do proxy que faz a chamada.

O que é um contrato de implementação?

É o contrato que contém a lógica de negócios executada por meio de um proxy atualizável.

O que é uma colisão de seletores?

Ela ocorre quando assinaturas de funções diferentes produzem o mesmo seletor de quatro bytes.

Por que o layout de armazenamento é importante?

Layouts de armazenamento incompatíveis podem fazer com que uma implementação atualizada interprete incorretamente ou sobrescreva dados existentes do proxy.

Uma função fallback pode causar reentrância?

Sim. Quando há gas suficiente, ela pode fazer uma chamada de retorno a outro contrato.

A função fallback pode rejeitar um pagamento?

Sim. Uma função fallback nonpayable ou que seja explicitamente revertida pode rejeitar um pagamento comum feito por uma chamada de mensagem.

Um contrato pode impedir todo e qualquer aumento de saldo?

Não. Alguns mecanismos da EVM podem aumentar o saldo de um contrato sem executar a lógica receive ou fallback.

Uma transferência ERC-20 aciona a função fallback?

Normalmente, não, pois o contrato do token atualiza os saldos sem chamar o destinatário.

A função fallback pode emitir um evento?

Sim, desde que a chamada forneça gas suficiente para a operação do evento.

A função fallback pode atualizar o armazenamento?

Sim, mas as atualizações de armazenamento aumentam os custos e podem falhar quando há pouco gas disponível.

A função fallback pode usar modificadores?

Sim. Uma função fallback pode usar modificadores da Solidity.

A função fallback pode ser herdada?

Sim. Ela pode ser virtual e sobrescrita por um contrato derivado.

Uma chamada de baixo nível bem-sucedida comprova que a função solicitada existe?

Não. Um seletor desconhecido pode ter sido aceito pela função fallback.

Todo contrato inteligente deve ter uma função fallback?

Não. Um contrato só deve definir uma função fallback quando precisar tratar chamadas não correspondentes de forma personalizada.

Uma função fallback é segura em um contrato atualizável?

Ela pode ser segura quando a lógica de encaminhamento, o layout de armazenamento, a implementação e a autoridade de atualização são projetados e auditados corretamente.

Qual é o maior risco de uma função fallback?

O maior risco depende da finalidade da função, mas a delegação por proxy, as chamadas externas sem restrições, as atualizações inseguras e o tratamento inesperado de pagamentos podem ser críticos.

Conclusão

Uma função fallback é um ponto de entrada especial da Solidity para chamadas externas que não correspondem a outra função declarada do contrato inteligente.

Ela também pode processar calldata vazia quando o contrato não define uma função receive.

Uma função fallback payable pode aceitar criptomoeda nativa, enquanto uma função fallback nonpayable rejeita chamadas não correspondentes que transportem valor.

Em geral, a função receive é a opção mais clara para transferências simples intencionais de criptomoeda.

As funções fallback são essenciais para proxies atualizáveis, pois podem encaminhar chamadas a contratos de implementação por meio de delegatecall.

Esse processo preserva o remetente e o valor originais enquanto executa o código da implementação usando o armazenamento do proxy.

O roteamento de chamadas por funções fallback de proxy envolve riscos relacionados ao layout de armazenamento, a colisões de seletores, à autoridade de atualização e a delegatecall.

As funções fallback também podem criar problemas de reentrância, negação de serviço, gas, decodificação e sucesso inesperado de chamadas.

Os desenvolvedores devem manter restrito o comportamento das funções fallback, rejeitar chamadas não compatíveis quando apropriado e usar funções normais nomeadas para a lógica comum da aplicação.

Compreender a função fallback é essencial para avaliar contratos inteligentes de criptomoedas, pois esse ponto de entrada sem nome pode controlar pagamentos, o roteamento de proxies, o comportamento de contas modulares e a execução de uma aplicação descentralizada inteira.