Como uma Transação Flui

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

Receita

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

Cliente constrói → Assina → sendTransaction → Líder recebe (Gulf Stream)
→ Ordenação PoH → Execução Sealevel → Propagação de Bloco (Turbine)
→ Votos do Validador (TowerBFT) → Verificação de confirmação RPC

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 uma assinatura:
const sub = await rpcSubs.signatureNotifications(signature, { commitment: "confirmed" });

Quando recorrer a isto:

• Depurando por que uma transação foi descartada vs rejeitada
• Escolhendo o nível de commitment correto para sua UX
• Entendendo o timing da retentativa em relação à expiração do blockhash
• Explicando "processado" em sub-segundo vs "finalizado" em ~12s para os usuários
• Projetando o reenvio de transações idempotentes

Exemplo de Trabalho

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 (tempo de vida da transação)
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
// 2. Construir 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, // demonstração de auto-transferência
        amount: 1n,
      }),
      m,
    ),
);
 
const signed = await signTransactionMessageWithSigners(message, [signer]);
const signature = getSignatureFromTransaction(signed);
 
// 3. Enviar
await rpc.sendTransaction(signed, { encoding: "base64" }).send();
console.log("Submetido:", signature);
 
// 4. Aguardar commitment confirmado
const notifications = await rpcSubs.signatureNotifications(signature, {
  commitment: "confirmed",
});
for await (const note of notifications) {
  if (note.value.err) {
    console.error("Falha on-chain:", note.value.err);
  } else {
    console.log("Confirmado no slot:", note.context.slot);
  }
  break;
}

O que isto demonstra:

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

Análise Detalhada

Como Funciona

1. Construir - o cliente monta instruções, contas e um blockhash recente
2. Assinar - os signatários necessários produzem assinaturas Ed25519
3. Enviar - o nó RPC recebe e encaminha para o líder atual/próximo
4. Agendar - o líder ordena transações usando os ticks do Proof of History
5. Executar - Sealevel executa instruções em paralelo onde os bloqueios de conta permitem
6. Commit - as alterações da transação são gravadas no banco de dados de contas
7. Votar - validadores votam no bloco; TowerBFT acumula lockouts
8. Confirmar - o RPC relata o status no nível de commitment solicitado

Níveis de Commitment

Modos de Falha

• Descartado - nunca entrou em um bloco (pulo do líder, taxa de prioridade baixa, blockhash expirado)
• Rejeitado - entrou, mas o programa retornou um erro (fundos insuficientes, violação de restrição)
• Falha na simulação - o preflight do RPC capturou o erro antes do envio

Armadilhas

• Tratar processed como final - forks podem reordenar neste nível. Correção: aguarde confirmed ou finalized antes de uma UX irreversível.
• Não atualizar o blockhash na retentativa - transações expiradas são descartadas silenciosamente. Correção: busque um novo blockhash e re-assine em cada retentativa.
• Ignorar erros de preflight - skipPreflight: true oculta falhas de simulação. Correção: simule primeiro em desenvolvimento; decodifique erros antes de retentar.
• Fazer polling em um loop apertado - sobrecarrega o RPC e ainda assim perde confirmações rápidas. Correção: use assinaturas de notificação WebSocket.
• Reenvio da mesma assinatura - válido e idempotente, mas inútil se o blockhash expirou. Correção: reenvie a mesma assinatura apenas dentro da janela do blockhash.
• Pulo do líder durante congestionamento - transações entram em fila por mais tempo. Correção: adicione taxas de prioridade via Compute Budget Program.

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1v201x3x1v1t1v1z1t20

Alternativas

FAQs

Relacionado

• Noções Básicas de Solana - exemplo ponta a ponta
• Slots, Blocos e Épocas - contexto de tempo
• 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.