Depurando Transações que Falharam

Transações Solana que falham deixam pistas em logs de simulação, códigos de erro RPC e output de programa em explorers. Um fluxo disciplinado de decode separa erros de usuário, bugs de client, problemas de RPC e defeitos de programa on-chain antes de você fazer retry ou acionar on-call.

Receita

Card de receita de referência rápida - pronto para copiar e colar.

import { createSolanaRpc } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
 
const sim = await rpc
  .simulateTransaction(base64Tx, {
    sigVerify: false,
    replaceRecentBlockhash: true,
    commitment: "confirmed",
  })
  .send();
 
if (sim.value.err) {
  console.error("err:", sim.value.err);
  console.error("logs:", sim.value.logs?.join("\n"));
  console.error("units:", sim.value.unitsConsumed);
}

Quando usar:

• Um usuário reporta "transação falhou" com apenas uma signature
• Preflight rejeita antes da tx chegar à rede
• Programa retorna Custom: N e você precisa do mapeamento do enum
• Erros de compute ou tamanho de conta disparam após deploy
• Triagem de incidente precisa de classe de erro antes de acionar donos do programa

Exemplo Funcional

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getBase64EncodedWireTransaction,
  pipe,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
 
async function debugTransfer(signer: Awaited<ReturnType<typeof import("@solana/kit").createKeyPairSignerFromBytes>>) {
  const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
  const message = pipe(
    createTransactionMessage({ version: 0 }),
    (m) => setTransactionMessageFeePayer(signer.address, m),
    (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
    (m) =>
      appendTransactionMessageInstruction(
        getTransferSolInstruction({
          source: signer,
          destination: signer.address,
          amount: 1n,
        }),
        m,
      ),
  );
 
  const signed = await signTransactionMessageWithSigners(message);
  const wire = getBase64EncodedWireTransaction(signed);
 
  const sim = await rpc
    .simulateTransaction(wire, {
      sigVerify: true,
      replaceRecentBlockhash: false,
      commitment: "confirmed",
    })
    .send();
 
  return {
    err: sim.value.err,
    logs: sim.value.logs ?? [],
    unitsConsumed: sim.value.unitsConsumed,
    accounts: sim.value.accounts,
  };
}

O que isso demonstra:

• Construir transação real e simular com replaceRecentBlockhash desligado ao testar validade de assinatura
• Ler err, logs e unitsConsumed como a tríade principal de debug
• Usar tipos RPC @solana/kit 7.0.0 para respostas de simulação tipadas
• Capturar state de conta pós-simulação ao depurar rent ou mismatch de owner

Aprofundamento

Como Funciona

• Simulação preflight executa a transação contra o state atual do ledger antes do broadcast (quando habilitada em sendTransaction).
• Logs de programa emitem via sol_log / msg! / anchor_lang::prelude::* e aparecem em simulação e metadata de transação confirmada.
• Erros customizados de programa codificam como InstructionError::Custom(u32) - mapeie para seu IDL ou enum #[error_code].
• Compute budget padrão é 200.000 CUs por instruction a menos que você prependa instructions ComputeBudget.
• Mismatch de meta de conta falha antes da execução: flag signer errada, flag writable errada ou conta faltando.

Classes de Erro em Resumo

Notas TypeScript

function parseCustomError(logs: string[]): number | null {
  const line = logs.find((l) => l.includes("custom program error:"));
  if (!line) return null;
  const m = line.match(/custom program error: (0x[0-9a-f]+|\d+)/i);
  if (!m) return null;
  return m[1].startsWith("0x") ? parseInt(m[1], 16) : Number(m[1]);
}

Notas Rust / Anchor

// Anchor 0.32.1 - erros aparecem como códigos Custom nos logs
#[error_code]
pub enum MyError {
    #[msg("Vault is paused")]
    VaultPaused,
}
// Map: anchor error --program-id <PID> mostra código -> nome

Erros Comuns

• Retry sem ler logs - Usuários martelam resubmit; você queima priority fees na mesma falha determinística. Correção: Simule uma vez, classifique erro, corrija causa raiz.
• RPC de cluster errado - Tx devnet simulada contra RPC mainnet retorna AccountNotFound. Correção: Fixe RPC_URL, rede da wallet e explorer ?cluster= juntos.
• Assumir que preflight está sempre ligado - Alguns caminhos de servidor desligam preflight por latência. Correção: simulateTransaction explícito em tooling de suporte.
• Decimais vs lamports - Client envia 1.5 SOL como float; programa espera lamports inteiros. Correção: bigint ponta a ponta; converta apenas na borda da UI.
• Mapa de erros IDL obsoleto - Programa v2 implantado, client ainda decodifica códigos v1. Correção: Versione IDL em CI; regenere clients a cada release de programa.
• Ignorar unitsConsumed - Programas perto do limite falham só sob carga. Correção: Rastreie CU em métricas; alerte quando p95 exceder 80% do budget.

Alternativas

FAQs

Relacionado

• Transações que Não Pousam - quando simulação passa mas inclusão falha
• Outages de RPC e Infraestrutura - falhas do lado do provedor
• Checklists de Prevenção - monitores e alertas após incidentes

Versões do stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.