Como uma Transação Flui

Uma transação Solana viaja do seu client pela rede até um líder produtor de blocos, executa atomicamente on-chain e ganha votos até atingir o nível de commitment escolhido. Entender esse caminho explica latência, falhas e estratégia de retry.

Receita

Cartão de receita de referência rápida - pronto para copiar.

Client build → Sign → sendTransaction → Leader receives (Gulf Stream)
→ PoH ordering → Sealevel execution → Block propagation (Turbine)
→ Validator votes (TowerBFT) → RPC confirmation polling

import { createSolanaRpc, createSolanaRpcSubscriptions } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const rpcSubs = createSolanaRpcSubscriptions("wss://api.devnet.solana.com");
 
// Após sendTransaction retornar signature:
const sub = await rpcSubs.signatureNotifications(signature, { commitment: "confirmed" });

Quando usar:

• Depurar por que transação foi descartada vs rejeitada
• Escolher nível de commitment certo para sua UX
• Entender timing de retry relativo à expiração de blockhash
• Explicar "processed" sub-segundo vs "finalized" ~12s aos usuários
• Projetar reenvio idempotente de transação

Exemplo Prático

import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createKeyPairSignerFromBytes,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  signTransactionMessageWithSigners,
  getSignatureFromTransaction,
  pipe,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
import { readFileSync } from "node:fs";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const rpcSubs = createSolanaRpcSubscriptions("wss://api.devnet.solana.com");
 
const secret = Uint8Array.from(
  JSON.parse(readFileSync(process.env.HOME + "/.config/solana/id.json", "utf8")),
);
const signer = await createKeyPairSignerFromBytes(secret);
 
// 1. Buscar blockhash recente (lifetime da transação)
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
// 2. Montar e assinar
const message = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(signer.address, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) =>
    appendTransactionMessageInstruction(
      getTransferSolInstruction({
        source: signer.address,
        destination: signer.address, // self-transfer demo
        amount: 1n,
      }),
      m,
    ),
);
 
const signed = await signTransactionMessageWithSigners(message, [signer]);
const signature = getSignatureFromTransaction(signed);
 
// 3. Enviar
await rpc.sendTransaction(signed, { encoding: "base64" }).send();
console.log("Submitted:", signature);
 
// 4. Aguardar commitment confirmed
const notifications = await rpcSubs.signatureNotifications(signature, {
  commitment: "confirmed",
});
for await (const note of notifications) {
  if (note.value.err) {
    console.error("Failed on-chain:", note.value.err);
  } else {
    console.log("Confirmed at slot:", note.context.slot);
  }
  break;
}

O que isso demonstra:

• Blockhash vincula transação a estado recente do ledger (~60-90 segundos de validade)
• sendTransaction transmite ao RPC, que encaminha via Gulf Stream
• WebSocket signatureNotifications é mais eficiente que polling getSignatureStatuses
• confirmed significa supermaioria votou no bloco; finalized é mais forte

Aprofundamento

Como Funciona

1. Build - client monta instruções, contas e blockhash recente
2. Sign - signatários exigidos produzem assinaturas Ed25519
3. Submit - nó RPC recebe e encaminha ao líder atual/próximo
4. Schedule - líder ordena transações usando ticks de Proof of History
5. Execute - Sealevel executa instruções em paralelo onde locks de conta permitem
6. Commit - mudanças de transação são escritas no accounts database
7. Vote - validadores votam no bloco; TowerBFT acumula lockouts
8. Confirm - RPC reporta status no nível de commitment solicitado

Níveis de Commitment

Modos de Falha

• Dropped - nunca entrou em bloco (skip de líder, priority fee baixa, blockhash expirado)
• Rejected - entrou mas programa retornou erro (fundos insuficientes, violação de constraint)
• Simulation failure - preflight RPC capturou erro antes do envio

Erros Comuns

• Tratar processed como final - forks podem reordenar neste nível. Correção: aguarde confirmed ou finalized antes de UX irreversível.
• Não atualizar blockhash no retry - transações expiradas são descartadas silenciosamente. Correção: busque novo blockhash e re-assine em cada retry.
• Ignorar erros de preflight - skipPreflight: true oculta falhas de simulação. Correção: simule primeiro em desenvolvimento; decodifique erros antes de retry.
• Polling em loop apertado - martela RPC e ainda perde confirmações rápidas. Correção: use subscriptions WebSocket de signature.
• Reenvio da mesma signature - válido e idempotente, mas inútil se blockhash expirou. Correção: reenvie mesma signature só dentro da janela de blockhash.
• Skip de líder durante congestionamento - transações enfileiram mais. Correção: adicione priority fees via Compute Budget Program.

Alternativas

FAQs

Relacionado

• Noções Básicas de Solana - exemplo ponta a ponta
• Slots, Blocos e Epochs - contexto de temporização
• Keypairs e Endereços - etapa de assinatura

Versões da 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.