RPC Basics

10 exemplos para você começar com Solana JSON-RPC - 7 básicos e 3 intermediários.

Pré-requisitos

• URL de endpoint RPC (devnet pública ou provedor)
• @solana/kit 7.0.0 para exemplos TypeScript

npm install @solana/kit@7.0.0

Exemplos Básicos

1. Formato HTTP JSON-RPC

Nós Solana falam JSON-RPC 2.0 via HTTP POST.

curl https://api.devnet.solana.com -s -X POST -H "Content-Type: application/json" -d '
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getHealth"
}'

• Métodos são camelCase como getBalance, getSlot.
• Respostas incluem result ou error com código e mensagem.
• A mesma URL frequentemente suporta WebSocket em porta/caminho diferente para assinaturas.

2. Criar um cliente RPC com Kit

Leituras type-safe com @solana/kit 7.0.0.

import { createSolanaRpc, address } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
 
const health = await rpc.getHealth().send();
console.log(health);

• createSolanaRpc encapsula chamadas JSON-RPC baseadas em fetch.
• .send() executa a requisição e retorna resultados tipados.
• Troque a URL por endpoints de provedor em produção.

Relacionado: Core RPC Methods - métodos comuns

3. Commitment: processed

Leituras mais rápidas - podem reverter em forks.

import { createSolanaRpc, address } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
 
const slot = await rpc.getSlot({ commitment: "processed" }).send();
console.log("processed slot:", slot);

• Use para polling de UI onde leve obsolescência é aceitável.
• Não ideal para decisões financeiras de finalidade.
• Comportamento padrão do cliente pode diferir - defina explicitamente.

4. Commitment: confirmed

Padrão para a maioria das leituras de aplicativo.

const balance = await rpc
  .getBalance(address("11111111111111111111111111111111"), {
    commitment: "confirmed",
  })
  .send();
console.log("lamports:", balance.value);

• Supermaioria votou no slot - saldo prático para dApps.
• Combine com confirmed em envios antes de mostrar UI de sucesso.
• Commitment padrão da CLI alinha com este nível.

5. Commitment: finalized

Leituras mais seguras para tesouraria e contabilidade.

const account = await rpc
  .getAccountInfo(address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"), {
    commitment: "finalized",
    encoding: "base64",
  })
  .send();
console.log(account.value?.lamports);

• Finalized não pode reverter sob condições normais de rede.
• Mais lento - espere minutos na mainnet após escritas.
• Use para saques e estados de UI irreversíveis.

6. Verificar headers de rate limit

Provedores retornam HTTP 429 quando limitados.

curl -i https://api.devnet.solana.com -s -X POST -H "Content-Type: application/json" -d '
{"jsonrpc":"2.0","id":1,"method":"getSlot"}' | head -20

• Endpoints públicos limitam agressivamente - espere 429 em CI.
• Faça backoff exponencial e cache leituras.
• Chaves de provedor dedicadas elevam limites.

Relacionado: RPC Providers - comparação de provedores

7. CLI usa o mesmo RPC

Comandos de terminal atingem o mesmo JSON-RPC do seu app.

solana config set --url https://api.devnet.solana.com
solana slot

• solana slot mapeia para getSlot.
• Depuração começa alinhando URL da CLI e RPC_URL do app.
• Flags de commitment espelham parâmetros RPC.

Exemplos Intermediários

8. Requisições em lote (conceito)

Reduza round trips agrupando JSON-RPC em um corpo HTTP.

import { createSolanaRpc, address } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
 
const [slot, blockHeight] = await Promise.all([
  rpc.getSlot().send(),
  rpc.getBlockHeight().send(),
]);
console.log({ slot, blockHeight });

• Promise.all paralelo ainda usa múltiplas requisições HTTP a menos que o provedor suporte arrays em lote.
• Prefira getMultipleAccounts em vez de N chamadas getAccountInfo.
• Veja página de paginação para padrões de scan.

Relacionado: Pagination & Efficiency - leituras eficientes

9. WebSocket vs HTTP

Assinaturas precisam de transporte WebSocket.

# HTTP for one-shot reads
curl https://api.devnet.solana.com ...
 
# WS for accountSubscribe (kit or ws client)

• accountSubscribe, logsSubscribe exigem socket persistente.
• URL WSS do provedor pode diferir da URL RPC HTTPS.
• HTTP permanece melhor para leituras stateless em escala.

Relacionado: WebSocket Subscriptions - atualizações ao vivo

10. DAS e RPC padrão

Digital Asset Standard API estende leituras para NFTs e ativos comprimidos.

// DAS methods (e.g. getAsset) live on provider DAS-enabled endpoints
// Standard getAccountInfo still underlies raw account bytes

• Nem todo RPC público expõe DAS - verifique matriz de features do provedor.
• Use DAS para metadados de ativos; use getAccountInfo para contas de programa customizadas.
• Veja página DAS para lista de métodos.

Relacionado: The DAS API - leituras de ativos

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.