WebSocket Subscriptions

Assine mudanças de conta, logs de transação e confirmação de assinatura via Solana WebSocket JSON-RPC.

Receita

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

import { createSolanaRpcSubscriptions, address } from "@solana/kit";
 
const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);
 
const abort = new AbortController();
const accountNotifications = await rpcSubscriptions
  .accountNotifications(address("YOUR_ACCOUNT"), { commitment: "confirmed" })
  .subscribe({ abortSignal: abort.signal });
 
for await (const notification of accountNotifications) {
  console.log(notification.value.lamports);
}

Quando usar:

• Atualizações ao vivo de saldo de carteira sem polling.
• Esperar confirmação de transação na UI.
• Streaming de logs de programa para filtro de mention específico.
• Construir dashboards reativos.

Exemplo Prático

import {
  createSolanaRpcSubscriptions,
  address,
} from "@solana/kit";
 
const rpcSubscriptions = createSolanaRpcSubscriptions(
  "wss://api.devnet.solana.com"
);
 
async function watchSignature(signature: string) {
  const abort = new AbortController();
  const sigNotifications = await rpcSubscriptions
    .signatureNotifications(signature, { commitment: "confirmed" })
    .subscribe({ abortSignal: abort.signal });
 
  for await (const n of sigNotifications) {
    if (n.value.err) {
      console.error("failed", n.value.err);
    } else {
      console.log("confirmed");
    }
    abort.abort();
    break;
  }
}
 
watchSignature("YOUR_TX_SIGNATURE");

O que isso demonstra:

• signatureNotifications resolve quando transação atinge commitment.
• accountNotifications envia novo estado de conta em escritas.
• AbortController limpa assinaturas no unmount.

Aprofundamento

Como funciona

• Cliente abre WebSocket, envia método JSON-RPC *Subscribe, recebe mensagens push *Notification.
• Cada assinatura tem id para *Unsubscribe.
• Commitment na assinatura controla timing de notificação.
• Endpoints WSS de provedor podem exigir query params de API key.

Tipos de assinatura

Notas TypeScript

// Logs subscription with mentions filter (provider support varies)
// Use rpcSubscriptions.logsNotifications({ mentions: [programId] })

Erros comuns

• URL HTTP no cliente WebSocket - conexão falha. Correção: use endpoint wss:// das docs do provedor.
• Vazamento de assinatura - abas abertas acumulam carga no servidor. Correção: abort no unmount do componente e mudança de rota.
• Notificações processed revertem - UI mostra sucesso depois reverte. Correção: assine em confirmed ou finalized.
• Rate limits WSS públicos - conexões caem sob carga. Correção: tier de provedor com tetos maiores de assinatura.
• Assumir ordenação entre contas - notificações são por assinatura. Correção: projete merges de UI idempotentes.

Alternativas

FAQs

Relacionados

• RPC Basics - HTTP vs WS
• Logs & Debugging - stream de log CLI
• Webhooks - eventos server-side
• RPC Providers - endpoints WSS

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.