Transações Ethereum pendentes: nonce, substituição e cancelamento

Depois que você assina uma transação Ethereum, a carteira pode enviá-la a um cliente de execução ou serviço de transações. Os nós que a aceitam podem retransmiti-la para outros pares, e um proponente de bloco pode incluí-la em um bloco mais tarde. Até a inclusão, a transação não alterou o estado canônico da cadeia. O status “pending” em uma carteira ou explorador geralmente significa que o serviço conhece a transação, mas ainda não a observou em um bloco; ele não representa uma fila universal da rede. O guia de transações da Ethereum.org descreve o caminho entre a assinatura, a transmissão e a inclusão em um bloco.

Uma transação pode ficar aguardando por motivos diferentes. Os limites de taxa podem não atender às condições de um bloco, uma transação anterior da mesma conta pode continuar sem resolução, um nó pode não ter recebido a transação ou a carteira pode exibir informações desatualizadas ou específicas do provedor. Cada causa exige verificações diferentes. Aumentar a taxa não corrige a seleção de uma rede errada, e enviar outro pagamento sem conferir o primeiro pode gerar um segundo pagamento.

“Pending” também é diferente de “confirmed”, “finalized” ou “failed”. O hash da transação pode ficar visível antes da existência de um recibo; o recibo fica disponível depois que a transação é incluída em um bloco. Em seguida, os blocos Ethereum passam por estados de consenso. Carteiras e exploradores podem usar esses rótulos de formas diferentes. Por isso, confira o hash, o bloco, o recibo e o estado atual da cadeia em vez de confiar em um único rótulo curto de status.

Uma conta Ethereum comum de propriedade externa (externally owned account, EOA) tem um nonce que ordena suas transações. O nonce é um contador, não uma taxa, um registro de horário ou um hash exclusivo da transação. Para cada conta, a cadeia aceita uma transação somente quando ela usa o próximo nonce esperado pelo estado daquela conta. A mesma conta não pode executar duas transações com o mesmo nonce na cadeia canônica. A documentação de contas da Ethereum.org descreve o nonce como contador de transações da conta e mecanismo de proteção contra replay.

Suponha que o próximo nonce ainda não usado por uma conta seja 41. A próxima transação válida usa o nonce 41; depois que ela é incluída e aplicada, a seguinte usa o nonce 42. O nonce está associado à conta remetente, não ao endereço de destino. Duas contas diferentes podem ter, ao mesmo tempo, uma transação de número 41, pois cada uma tem sua própria sequência.

É possível assinar uma transação com um nonce superior ao nonce atual da conta na cadeia, mas ela não pode pular a sequência quando for executada. O nonce anterior que está faltando precisa ser consumido primeiro. Uma transação com nonce já consumido pela conta está obsoleta e não pode ser executada como uma nova transação. Essa ordem permite que a rede processe sequencialmente as transações de cada conta, mesmo quando são transmitidas em momentos diferentes ou chegam por nós diferentes.

A regra do nonce se aplica às transações comuns de EOA na camada de execução do Ethereum. Ela não descreve universalmente toda abstração de carteira, sequenciador de rollup ou cadeia. Sistemas de smart accounts podem adicionar suas próprias regras de operação e nonce, como veremos mais adiante neste guia.

O Ethereum não tem uma única sala de espera sincronizada que todas as carteiras, nós, exploradores de blocos e proponentes veem exatamente da mesma forma. Cada cliente de execução mantém um pool local de transações que recebeu e considera elegíveis segundo seus próprios limites e políticas. Uma transação pode aparecer no pool de um nó e não no de outro. A documentação RPC do txpool da Geth expõe os grupos locais pending e queued desse cliente e informa que várias transações podem estar associadas ao mesmo remetente e nonce.

Na terminologia da Geth, pending geralmente se refere a transações que podem ser processadas na ordem dos nonces a partir do estado atual da conta; queued pode incluir transações com nonces futuros aguardando o preenchimento de uma lacuna. Esses nomes descrevem uma interface do cliente, não estados de consenso que todos os softwares Ethereum precisam exibir. Uma carteira pode chamar toda a lista de transações não confirmadas de “pending”, enquanto um explorador pode mostrar apenas as transações observadas por seus próprios provedores de dados.

Por exemplo, se um nó conhece uma transação com nonce 41 e outra com nonce 43, ele não pode executar a 43 antes da 42. O nó pode manter a 43 em fila até que a 42 chegue ou a conta avance de outra forma. Outro nó que nunca recebeu a 43 não vai exibi-la. Por isso, dois exploradores podem divergir sobre a transação estar pending ou não ser encontrada, sem que qualquer uma das telas prove o que todos os validadores viram.

Alguns clientes também permitem mais de uma transação candidata não confirmada para o mesmo remetente e nonce. Elas são alternativas concorrentes pelo mesmo espaço na sequência, não duas transações que podem ser aplicadas em ordem. Capacidade do pool, tempo de permanência da transação e regras de substituição são políticas de implementação que podem mudar entre versões do software. Por exemplo, as opções configuráveis do pool de transações da Geth incluem um limite de aumento de preço específico do cliente; isso não deve ser tratado como uma regra universal de taxas do Ethereum. Consulte a referência de linha de comando da Geth para entender o escopo dessas opções.

Imagine que o próximo nonce on-chain de uma conta seja 41. Você transmite a transação A com nonce 41 e, em seguida, a transação B com nonce 42. Se A continuar sem resolução, B não poderá ser aplicada primeiro. B pode ficar em uma fila local, aparecer como pending apenas na carteira ou não aparecer em um explorador que ainda não a recebeu. O que importa é a relação entre os nonces, não a ordem em que a carteira criou ou exibiu as transações.

Se A acabar sendo incluída, o nonce da conta avança para 42, e B pode então se tornar elegível, dependendo da validade da própria transação, das condições de taxa e das políticas do pool. Se A for substituída por outra transação válida com nonce 41, a substituta ocupará a mesma posição na sequência caso seja ela a incluída. Se outra transação da conta tiver consumido o nonce 41, a candidata antiga com nonce 41 estará obsoleta e não poderá ser executada depois.

É por isso que enviar uma nova transação com nonce mais alto não é uma forma geral de liberar uma transação travada. Isso apenas acrescenta outra transação depois da lacuna. Cancelar B também não resolve A se B for a transação posterior. Comece pelo nonce sem resolução mais baixo da conta e confira seu status antes de alterar qualquer coisa.

Uma lacuna pode ser temporária ou persistente. A transação anterior talvez não tenha chegado ao nó que você está consultando, suas configurações de taxa podem ser pouco atrativas ou insuficientes para as condições atuais, ou ela pode ter sido removida do pool de um nó. Uma carteira também pode exibir uma transação queued criada em outro dispositivo. A tela por si só não indica qual situação ocorreu; compare o nonce confirmado da conta, os hashes das transações e mais de uma fonte confiável.

A ordem dos nonces e a elegibilidade da taxa são condições distintas. Uma transação com o próximo nonce correto ainda pode esperar se seus parâmetros de taxa não atenderem às condições de um bloco. Uma transação com nonce mais alto não pode passar à frente apenas por oferecer uma gorjeta maior. Aumentar a taxa do nonce 42 não faz o nonce 41 desaparecer.

Em uma transação EIP-1559 padrão, a taxa máxima precisa cobrir a base fee do bloco que incluirá a transação, e a priority fee pode influenciar a escolha do proponente do bloco. A base fee e o espaço disponível no bloco podem mudar enquanto uma transação espera. A taxa máxima é um limite, e um limite maior não garante um prazo específico para a confirmação. O guia de taxas de gas do Ethereum explica esses campos e como a taxa efetiva é determinada.

Um nó ou uma carteira pode aplicar regras adicionais de retransmissão ou substituição. Essas políticas determinam o que aquele serviço específico aceita ou encaminha; nem todas são regras de consenso. Por exemplo, a Geth oferece um limite configurável de aumento de preço para substituir uma transação pending em seu próprio pool. Outro cliente, provedor, carteira ou versão do software pode se comportar de outra forma. Não confie em uma porcentagem de que você se lembra ou em um período fixo de espera como garantia para toda a rede.

Se a transação está esperando porque um nonce menor continua sem resolução, primeiro identifique a transação que usa esse nonce. Se ela espera porque o limite da taxa não cobre as condições atuais da base fee, entenda os campos de taxa antes de alterá-los. O guia de taxas do Ethereum é a referência para os cálculos; este artigo trata do problema separado de ordenação.

O recurso “acelerar” de uma carteira geralmente monta uma nova transação da mesma conta, com o mesmo nonce e parâmetros de taxa ajustados. As duas candidatas entram em conflito porque a conta só pode executar uma transação para aquele nonce. Se a substituta for aceita pelos pools de transações relevantes e incluída, ela poderá ocupar o espaço do nonce; a transação original não poderá também ser executada na cadeia canônica. O guia da MetaMask sobre transações pendentes descreve seu recurso de aceleração como um novo envio com o mesmo nonce e uma taxa maior.

A substituta pode manter o destino e a ação originais e alterar apenas os campos de taxa, mas confira a tela de assinatura em vez de presumir que isso acontecerá. Uma implementação de carteira pode expor outros campos ou usar outro nome para a ação. Antes de assinar uma substituta, confirme a conta remetente, o nonce, o destino, o valor e os dados do contrato. Se a substituta mudar o que a transação faz, não se trata apenas de um ajuste inofensivo de taxa.

Não há garantia de que a substituta será aceita em todos os lugares ou incluída rapidamente. A original talvez já tenha sido incluída; um nó pode rejeitar a substituta segundo sua política; ela ainda pode não ser atraente para um proponente; ou o serviço pode não retransmiti-la aos nós que você está acompanhando. Se a original já estiver confirmada, enviar outra transação com aquele nonce consumido não poderá desfazê-la e normalmente será rejeitada como obsoleta.

Aqui, “substituta” significa uma transação concorrente da mesma conta e com o mesmo nonce. Não aplique ao Ethereum os procedimentos de RBF ou CPFP do Bitcoin. O Bitcoin usa um modelo de transação diferente, e seus mecanismos de aumento de taxa não são instruções para contas Ethereum.

Depois que uma transação Ethereum assinada é transmitida, não existe um comando de desfazer no nível do protocolo que a retire de todos os nós. Algumas carteiras oferecem uma opção de cancelar enquanto a transação ainda não foi confirmada. Em geral, essa opção tenta publicar outra transação da mesma conta com o mesmo nonce; uma prática comum em carteiras é enviar uma transação de valor zero para o próprio endereço do remetente. Se a candidata de cancelamento for aceita e incluída antes da original, ela consumirá o nonce e tornará a candidata original inválida para execução posterior. A construção exata e a disponibilidade dependem da carteira.

A transação original e a candidata de cancelamento podem competir. Se a original for incluída primeiro, um cancelamento enviado depois não poderá desfazer seus efeitos. Se nenhuma das duas candidatas for aceita ou incluída, o nonce pode continuar sem resolução. O clique no botão da carteira ou uma mensagem de sucesso não provam que o cancelamento venceu. Confira o hash da transação resultante e o status na cadeia canônica. As instruções da MetaMask limitam expressamente a tentativa de cancelamento a uma transação ainda pending e explicam que uma transação confirmada não pode ser cancelada.

Antes de assinar uma transação de cancelamento, confirme que ela usa a mesma conta e o mesmo nonce da transação que você pretende substituir e confira todos os campos exibidos pela carteira. Se for incluída, ela pode exigir outra taxa de rede. A própria candidata de cancelamento também pode ficar aguardando ou não conseguir substituir a original de acordo com as políticas dos pools de transações relevantes. A palavra “cancelada” na carteira não prova uma reversão no nível do protocolo; só considere o resultado confirmado depois de verificar qual transação consumiu o nonce.

Se a transação já executou uma aprovação de token, uma chamada de contrato ou uma transferência, cancelar uma transação posterior não reverte a mudança de estado concluída. Algumas ações de contrato têm métodos separados para uma ação posterior, mas a disponibilidade e as consequências dependem do contrato. Não assine uma transação desconhecida só porque uma interface a chama de cancelamento.

Uma transação incluída tem um bloco e um recibo. Se for bem-sucedida, as mudanças de estado pretendidas podem ter sido aplicadas. Se a execução da EVM sofrer revert, as mudanças de estado daquela execução são desfeitas, mas a transação ainda consumiu o nonce da conta e pode cobrar gas. Use o recibo e o status da execução em vez de deduzir o sucesso por uma notificação da carteira. Consulte o guia de transações do Ethereum e o guia de gas para entender a diferença entre inclusão e resultado da execução.

O rótulo “dropped” ou “not found” costuma ser um relato de uma carteira, explorador, provedor de RPC ou pool local. Por si só, ele não prova que o protocolo cancelou a transação nem que o nonce está livre. Outro nó talvez ainda a conheça; a carteira pode retransmitir a transação assinada; ou um bloco posterior pode mostrar que o nonce da conta já avançou. Por outro lado, uma transação antiga pode não aparecer nas consultas feitas enquanto o nonce confirmado da conta permanece igual.

Se o hash da transação não for encontrado, confira se você selecionou a mesma cadeia e conta usadas para criá-la. Compare o nonce on-chain mais recente da conta com o nonce da transação e examine as transações recentes daquele remetente. Uma resposta nonce too low indica que o nonce talvez já tenha sido consumido na visão do endpoint, não que você deva repetir a mesma solicitação. Verifique qual transação o usou e se o bloco continua canônico.

Uma transação incluída também pode ser afetada por uma reorganização de curta duração antes de a cadeia se estabilizar. Carteiras e exploradores podem atualizar os rótulos quando sua visualização muda. Para uma transferência importante, aguarde de acordo com a política de confirmação do serviço recebedor e, quando relevante, por uma finalização de consenso mais forte. “Vista em um bloco” e “irreversível em todas as circunstâncias” não são afirmações equivalentes.

Comece confirmando a cadeia, a conta remetente e o hash da transação. Pesquise o hash em um explorador confiável da rede correta. Confira se há um recibo, qual nonce foi usado, se a execução teve sucesso e se a conta fez uma transação posterior. Não revele nem digite sua frase-semente para verificar uma transação; um endereço público e o hash da transação bastam para consultas em uma cadeia pública.

Se o hash não estiver visível, compare o nonce confirmado mais recente da conta com o nonce exibido na carteira. Um desenvolvedor ou operador de nó pode consultar eth_getTransactionCount usando as tags de bloco latest e pending. A referência JSON-RPC da Ethereum.org define essas tags: latest corresponde ao estado do bloco mais recente, enquanto pending corresponde ao estado pending. O resultado pending ainda depende da visão daquele endpoint RPC; provedores diferentes podem retornar valores distintos. A maioria dos usuários consegue obter as mesmas primeiras pistas pela atividade da conta na carteira e por um explorador confiável, sem executar comandos.

Em seguida, comece pelo menor nonce que ainda não foi consumido. Se a transação original ainda estiver visível e a carteira aceitar substituições, revise os campos exatos e as configurações de taxa da substituta antes de assinar. Se ela não estiver visível, pergunte à carteira ou ao provedor de RPC como eles lidam com reenvio e substituição, em vez de presumir que a transação desapareceu da rede. Se o nonce já tiver sido consumido, identifique a transação incluída antes de qualquer outra ação. Evite enviar várias transações novas com nonces posteriores; isso pode alongar a fila sem resolver a primeira lacuna.

Essas etapas se aplicam às transações padrão de contas externas do Ethereum. Sistemas de abstração de conta podem enviar UserOperations por meio de bundlers, e smart accounts podem usar chaves e sequências de nonce mais complexas do que um contador simples. A EIP-4337 define uma estrutura de nonce para essas operações, portanto uma carteira que usa abstração de conta pode não funcionar exatamente como nos exemplos de EOA deste artigo. Para conferir redes de destino, endereços e o status da transferência, consulte o checklist de transferência de cripto.