Transações que Não Pousam

Uma transação que simula limpo ainda pode nunca confirmar: leaders a pulam durante congestionamento, blockhashes expiram ou lances de fee perdem o leilão de prioridade. Triagem em produção separa falha de execução de falha de inclusão antes de mudar lógica de programa.

Receita

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

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstructions,
  signTransactionMessageWithSigners,
  getSignatureFromTransaction,
} from "@solana/kit";
import {
  getSetComputeUnitLimitInstruction,
  getSetComputeUnitPriceInstruction,
} from "@solana-program/compute-budget";
 
// 1. Blockhash fresco  2. ix compute budget  3. send + subscribe

Quando usar:

• Usuários veem "pendente" indefinidamente na wallet
• Taxa de erro é baixa mas volume de suporte para txs presas é alto
• Pico pós-deploy de signatures não confirmadas
• Bots competindo durante mint NFT ou launch de token
• Você precisa de SLOs para latência de pouso de transação

Exemplo Funcional

import { createSolanaRpc, createSolanaRpcSubscriptions } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
const subs = createSolanaRpcSubscriptions(process.env.WS_URL!);
 
async function sendWithLandingWatch(wireBase64: string, signature: string) {
  await rpc.sendTransaction(wireBase64, {
    encoding: "base64",
    skipPreflight: false,
    maxRetries: 0,
    preflightCommitment: "confirmed",
  }).send();
 
  const started = Date.now();
  const sub = await subs.signatureNotifications(signature, { commitment: "confirmed" });
 
  for await (const note of sub) {
    if (note.value.err) throw new Error(`On-chain err: ${JSON.stringify(note.value.err)}`);
    return { landedMs: Date.now() - started, slot: note.context.slot };
  }
 
  throw new Error("Subscription ended without confirmation");
}

O que isso demonstra:

• maxRetries: 0 para seu app controlar política de retry com blockhashes frescos
• WebSocket signatureNotifications em vez de polling getSignatureStatuses
• Medir latência de pouso para dashboards SLO
• Tratar err on-chain separado de nunca pousar

Aprofundamento

Como Funciona

• Gulf Stream encaminha transações para leaders futuros; não há ordenação global garantida de mempool.
• Recent blockhash define lifetime da transação (~60-90 segundos de validade). Txs expiradas são descartadas silenciosamente.
• Priority fee (set_compute_unit_price) oferece micro-lamports por CU; lances maiores tendem a pousar primeiro sob carga.
• Limite de compute units limita execução; CU sub-ofertado pode causar ineficiência de scheduling.
• Address Lookup Tables (ALTs) reduzem tamanho da tx para mais txs caberem por bloco.

Modos de Falha de Pouso

Notas TypeScript

// Busque priority fees recentes para suas contas de programa
const fees = await rpc.getRecentPrioritizationFees({
  lockedWritableAccounts: [programId],
}).send();
const p75 = fees.value.map((f) => f.prioritizationFee).sort((a, b) => a - b)[
  Math.floor(fees.value.length * 0.75)
] ?? 1;

Erros Comuns

• Resubmits idênticos - Rebroadcast dos mesmos bytes assinados após expiração desperdiça fees. Correção: Reconstrua mensagem com novo blockhash e re-assine.
• Preço de CU padrão zero durante mints - Suas txs perdem todo leilão. Correção: Oráculo de fee dinâmico de getRecentPrioritizationFees.
• Confiar em processed para UX - Forks podem desfazer processed. Correção: Mostre sucesso em confirmed; liquide dinheiro em finalized se necessário.
• Transações enormes sem ALTs - Excede tamanho do pacote; RPC pode aceitar mas leaders descartam. Correção: Compile com lookup tables; divida instructions.
• Tempestades de retry RPC - Client e RPC ambos fazem retry; confusão de nonce e rate limits. Correção: Chaves de idempotência no app; maxRetries: 0 no send.
• Ignorar congestionamento por horário - Picos mainnet diferem de devnet. Correção: Rastreie p95 de pouso por hora; escale multiplicador de fee automaticamente.

Alternativas

FAQs

Relacionado

• Depurando Transações que Falharam - simulação e erros de programa
• Outages de RPC e Infraestrutura - failover de provedor
• Antes/Depois: Fazendo Transações Pousarem com Confiabilidade - estudo de caso

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.