Decodificando swaps SCW

Com carteiras de contrato inteligente (SCWs), as trocas seguem um caminho muito diferente do que com carteiras tradicionais do Ethereum/EVM. Essa diferença pode ser confusa, especialmente quando algo dá errado. Mas, uma vez que você entende os principais participantes do fluxo — e como ler o que aconteceu passo a passo no app e no explorador — as coisas começam a fazer sentido.

Vamos analisar isso juntos.

De um toque à execução on-chain: o que realmente acontece

Quando você toca em “Swap” no app, parece uma única ação. Na realidade, você está iniciando um processo em várias camadas construído sobre a abstração de conta do Ethereum (ERC-4337). Sua transação não vai direto para a blockchain como em uma carteira normal. Em vez disso, ela faz um desvio:

  1. Nós construímos a rota. Pedimos ao motor de roteamento (como o 1inch) para encontrar o melhor caminho para sua troca e simulamos para garantir que funciona. Estimamos o gás, validamos que você tem os tokens e empacotamos as instruções em um formato especial: um UserOperation.

  2. Um bundler entra em cena. Esse é um ator off-chain responsável por submeter UserOperations à blockchain. Ele verifica sua operação, confirma que é válida e pré-paga o gás por você (é reembolsado depois).

  3. Sua UserOp entra na blockchain através do EntryPoint smart contract. Pense no EntryPoint como o portão pelo qual todas as transações SCW passam. O EntryPoint executa checagens finais e, se tudo parecer certo…

  4. O EntryPoint diz à sua Smart Contract Wallet (SCW) para executar a troca. Sua SCW chama o roteador (por exemplo, 1inch), o roteador chama os pools, os tokens se movem e o resultado volta para sua carteira.

Então, para resumir: você toca em swap → nós simulamos → o bundler submete → EntryPoint valida → sua SCW executa.

Vamos ver um exemplo real

Agora que entendemos o fluxo em alto nível, vamos ver como isso se desenrola em uma troca real: primeiro no app, depois on-chain:

Aqui está o que vemos:

  • Trocamos 1 USDC por 0,765 KTA.

  • A troca foi executada na Base (observe o ícone da Base nos símbolos das moedas).

  • Pagamos:

    • $0,03 de gás (em ETH)

    • 0,22% de taxa de swap para a goodcryptoX

    • 0,05% de taxa de roteador para a 1inch

  • A rota foi simples: 100% através de um pool Uniswap v4.

  • Bundler: Alchemy (veja o Passo 2 acima para recapitulação)

  • Links do explorador aparecem se a transação alcançou a blockchain e foi registrada no bloco (mesmo que falhe)

Até aqui, tudo bem. Em seguida, vamos clicar no link do BaseScan para ver como essa transação aparece on-chain:

Observação sobre links do explorador: Nas versões mais recentes do aplicativo, os links do explorador já abrem sua Transação AA (UserOp). Se é isso que você vê (o campo "From" mostra o endereço da sua carteira), você pode ir direto para Passo 5 – página de detalhes da Transação AA. Os passos anteriores só se aplicam se seu link apontar para a transação externa do bundler (onde "From" NÃO é sua carteira). Ainda assim, é uma leitura útil para entender melhor como as transações SCW funcionam

De: esta não é sua carteira — é o bundler da Alchemy. Isso é esperado, já que o bundler submeteu a transação.

Para: EntryPoint (v0.6.0). Novamente, esperado — todas as transações SCW entram por aqui.

Transações internas: mostra fluxos de tokens nativos (ETH na Base) dentro da transação. Veja o que vemos:

  • Nossa carteira (…0A5) enviou ETH ao EntryPoint para a taxa de gás.

  • O EntryPoint reembolsou o bundler com o custo real do gás (já que o bundler pré-pagou o gás em seu nome; veja o Passo 2 acima). Qualquer ETH restante permaneceu no EntryPoint como seu depósito para transações futuras.

Transferências ERC-20: mostra os movimentos reais dos tokens:

Nossa carteira não enviou USDC diretamente. Em vez disso, o contrato token USDC (…2A8) processou e disparou as transferências. Isso é normal: em cadeias EVM, as transferências de tokens são tratadas pelo próprio contrato do token após receber uma instrução da sua smart contract wallet.

  1. O contrato USDC dividiu nosso 1 USDC em três transferências:

    • 0,0022 USDC para a carteira de taxas do nosso protocolo (…608A)

    • 0,0005 USDC para a carteira de taxas da 1inch (…1DE5)

    • Os restantes 0,9973 USDC para o roteador Uniswap v4 (…Universal Router)

  2. O roteador Uniswap v4 o repassou ao Pool Manager do Uniswap v4 (contrato único que lida com todos os pools v4).

  3. O Pool Manager executou a troca: USDC entra → KTA sai.

  4. O KTA foi roteado de volta através do Aggregation Router da 1inch, que o encaminhou para nossa carteira (…0A5).

🧩 Como decodificar uma transação SCW falhada

Agora que entendemos como as trocas com smart-contract-wallet (SCW) funcionam — e já passamos por uma negociação bem-sucedida — vamos usar as mesmas ferramentas para decifrar uma que falhou.

Usaremos outro caso real: uma troca ETH → token no Ethereum que falhou dentro do contrato EntryPoint porque não havia ETH suficiente para cobrir tanto a troca quanto a taxa de gás.

Ok, então você vê “Error” como o status da sua troca no app ou recebe uma notificação push de que sua troca falhou. O que fazer?

Passo 1 — Verifique os detalhes do pedido na goodcryptoX

Aqui está o que você vê neste caso:

Usando a estrutura que desenvolvemos anteriormente, você nota rapidamente:

  • O status da troca é Error (falhou?)

  • Nenhuma mensagem de erro é exibida (isso é incomum)

  • Há taxa de gás (atingiu a blockchain?)

  • Há rota exibida (a simulação deu certo?)

  • Há links para exploradores de blockchain (posso checar a tx na blockchain!).

Vamos checar sua intuição:

  • O Error status significa que a troca falhou

  • Deveria haver tanto uma mensagem de erro legível para humanos (traduzida do bruto) quanto a mensagem bruta. A ausência de mensagem de erro definitivamente indica que algo incomum aconteceu

  • A taxa de gás de fato significa que a transação alcançou a blockchain e alguma atividade on-chain aconteceu (que consumiu gás)

  • A rota confirma que a simulação da transação passou e resultou em um caminho claro para execução

  • Os links do explorador confirmam que a transação alcançou a blockchain — mesmo que tenha falhado. Devemos definitivamente abrir um deles e investigar mais a fundo

Passo 2 – Abra a transação no explorador de blockchain

Observação sobre links do explorador: Nas versões mais recentes do aplicativo, os links do explorador já abrem sua Transação AA (UserOp). Se é isso que você vê (o campo "From" mostra o endereço da sua carteira), você pode ir direto para Passo 5 – página de detalhes da Transação AA. Os passos anteriores só se aplicam se seu link apontar para a transação externa do bundler (onde "From" NÃO é sua carteira). Ainda assim, é uma leitura útil para entender melhor como as transações SCW funcionam

Você toca no link do Etherscan para ver o que aconteceu:

À primeira vista, as coisas ficam ainda mais confusas:

  • O status diz ✅ Success — espere, o quê?!

  • Mas nós já sabemos que a troca não foi concluída

  • Sob o campo “To” (EntryPoint), há uma pequena mensagem amarela:

    “Embora um ou mais erros tenham ocorrido [execution reverted] Contract Execution Completed”

Então, o que está realmente acontecendo aqui?

Lembre-se do fluxo de transação SCW que cobrimos antes:

  • o bundler empacota sua troca em um UserOperation (um pacote de dados com sua lógica de swap)

  • depois envia para o contrato EntryPoint

  • O EntryPoint valida (checando seu saldo, assinatura e nonce)

  • se tudo estiver certo, ele executa sua intenção — chamando roteadores, pools e movendo tokens.

Do ponto de vista da blockchain, porém, tudo isso parece apenas “bundler envia dados para EntryPoint”.

Em termos SCW, essa etapa é chamada de transação externa.

E essa transação teve sucesso: os dados foram entregues e o EntryPoint começou a executar sua lógica interna. Daí o ✅ Success no topo.

Mas o explorador, sendo cuidadoso, ainda avisa que algo falhou dentro do EntryPoint com aquela pequena nota amarela. Para o explorador, essa falha interna não é suficiente para marcar a transação como falhada.

Agora, outro detalhe chama atenção na aba Overview:

  • Cerca de $6 de ETH foram enviados da sua carteira para o EntryPoint (o pré-fundo de gás).

  • Apenas $2.3 de ETH foi reembolsado ao bundler.

  • E a taxa de transação mostrada no topo é ainda menor — cerca de $2.15.

À primeira vista, esses números não parecem bater. Vamos desvendar isso antes de continuar com a investigação

Passo 3 – Entendendo a discrepância do gás

Aqui está a divisão:

  • SCW → EntryPoint (~$6): Este é o pré-fundo de gás. O EntryPoint sempre coleta mais do que o necessário para garantir que sua UserOp possa rodar.

  • EntryPoint → Bundler (~$2,3): Este é o reembolso real do gás. É o valor real que você pagou por essa tentativa falhada.

  • Taxa de Transação (~$2,15): Isso é o que o bundler gastou para enviar sua UserOp ao EntryPoint. É menor porque o próprio EntryPoint usou gás extra durante a validação e o reembolso ao bundler — esse custo extra foi cobrado de você.

Regra prática:

👉 Seu custo real de gás é sempre o reembolso EntryPoint ➜ Bundler (não a “Taxa de Transação” mostrada no topo)

E a diferença entre o que você pré-fundou ($6) e o que foi reembolsado ($2,3) não desapareceu. Permaneceu no EntryPoint como seu depósito, que será aplicado automaticamente na sua próxima transação.

Passo 4 – Verifique a aba AA Transactions

No explorador, você vê uma aba AA Transactions (AA = Account Abstraction). É aqui que a atividade de smart contract wallet aparece, já que SCWs rodam na Account Abstraction (ERC-4337).

Vamos mudar para essa aba a partir do Overview:

Aqui você finalmente vê nossa UserOperation listada como uma entrada separada dentro da transação externa do bundler:

  • O campo "From" agora mostra o endereço da nossa carteira, confirmando que esta é a nossa operação.

  • Há um AA Txn Hash separado, diferente do hash da transação externa. Por quê?

    • O Txn Hash externo pertence à transação Bundler->EntryPoint que continha sua UserOp (e pode ter incluído múltiplas UserOps de vários usuários).

    • O AA Txn Hash é o identificador único para sua UserOperation dentro desse pacote.

Esta é a ideia-chave do empacotamento:

  • Um bundler pode agrupar muitas UserOps em uma única transação.

  • Cada UserOp recebe seu próprio AA Txn Hash, para que possa ser rastreada separadamente dentro do pacote.

  • No nosso caso, por se tratar de uma transação antiga (há mais de 400 dias), as SCWs ainda eram raras e o pacote continha apenas nossa UserOp — por isso a aba mostra “AA Transactions (1).” Em transações mais recentes, você frequentemente verá múltiplas UserOps agrupadas em um só pacote.

Nesta visão, você também notará um (!) vermelho ao lado do seu AA Txn Hash — confirmação de que sua troca não foi executada.

O próximo passo é clicar no AA Txn Hash. Isso abre a página dedicada à UserOperation, onde você verá os detalhes completos da nossa tentativa de swap — taxa, transferências e onde falhou.

Passo 5 – Abra a página de detalhes da AA Transaction

Clicar no AA Txn Hash leva você à página de detalhes dedicada à sua UserOperation:

Aqui você finalmente pode ver nossa tentativa de swap real claramente exposta:

  • Status: x Fail (sem ambiguidade desta vez)

  • From: o endereço da sua smart contract wallet

  • AA Transaction Fee: ~0,00231 ETH ($2,31). Este é o custo real de gás que você pagou — o reembolso enviado ao bundler.

  • Transação interna: uma transferência de ~0,00145 ETH ($6,36) da sua SCW para o EntryPoint (pré-fundo de gás). Nenhuma outra transferência ocorreu, o que confirma que a própria troca nunca foi executada.

  • Bundle Txn Hash: também mostrado, vinculando de volta à transação externa do bundler.

Esta página finalmente corresponde à sua intuição: esta é a transação real — a UserOperation que representou sua tentativa de swap.

Isto quase conclui nossa investigação. Mas como já chegamos até aqui, vamos também clicar em Internal Txns.

Passo 6 – Verifique a aba Internal Transactions

Mude para a aba Internal Txns dentro da visão da AA Transaction:

Aqui você vê as ações passo a passo que o EntryPoint tentou executar em seu nome:

  1. ✅ Transferência da sua SCW → EntryPoint (~0,00145 ETH, ~$6,36) = pré-fundo de gás. Isso teve sucesso.

  2. ❌ Execute da sua SCW → Uniswap Universal Router (~0,002 ETH) = tentativa de swap. Isso falhou.

Essa divisão explica a falha:

  • Você enviou com sucesso ETH ao EntryPoint como pré-fundo de gás.

  • Mas quando o EntryPoint tentou encaminhar ETH para a Uniswap para a troca, a tentativa falhou.

Para a análise mais detalhada, abra a aba Logs.

Passo 7 – Inspecione a aba Logs

Clique em Logs (3):

Aqui você encontrará três eventos-chave:

  • Deposited → confirma que seu pré-fundo de gás foi recebido pelo EntryPoint.

  • BeforeExecution → mostra que o EntryPoint começou a processar sua UserOperation.

  • UserOperationEvent → success: False — o registro canônico on-chain de que sua UserOp falhou.

O que realmente aconteceu (juntando tudo)

Esse tipo de falha é específico de swaps com SCWs em EVMs onde a entrada é o token nativo (ETH, BNB, MATIC…).

  • A lacuna: nem o bundler nem o EntryPoint verificam se você tem token nativo suficiente para cobrir tanto o pré-fundo de gás quanto a troca juntos. Eles só verificam separadamente — “suficiente para o gás?” e “suficiente para a troca?”. Por isso a simulação passou.

  • Construímos um sistema de defesa no app para esses casos, alertando na interface que o gás pode ser insuficiente. Mas, como a simulação parecia ok, você ainda pôde confirmar.

  • Uma vez que você confirmou, o bundler submeteu sua UserOperation ao EntryPoint.

  • O EntryPoint puxou cerca de $6 em ETH como pré-fundo.

  • Quando tentou executar a troca, não havia ETH suficiente restante para cobrir tanto a troca quanto o pré-fundo ao mesmo tempo.

  • A chamada de swap reverteu dentro do EntryPoint.

  • Você ainda pagou cerca de $2,3 em gás (o reembolso ao bundler).

  • Os cerca de $3,7 não usados permaneceram no EntryPoint como seu depósito, para serem usados automaticamente na sua próxima transação.

PreviousGás em qualquer tokenNextCarteiras externas

Last updated