Conceptos básicos de RPC

10 ejemplos para empezar con Solana JSON-RPC: 7 básicos y 3 intermedios.

Prerrequisitos

• URL del endpoint RPC (devnet público o proveedor)
• @solana/kit 7.0.0 para ejemplos de TypeScript

npm install @solana/kit@7.0.0

Ejemplos básicos

1. Forma de JSON-RPC HTTP

Los nodos de Solana utilizan JSON-RPC 2.0 sobre POST HTTP.

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

• Los métodos son camelCase, como getBalance, getSlot.
• Las respuestas incluyen result o error con código y mensaje.
• La misma URL a menudo admite WebSocket en un puerto/ruta diferente para suscripciones.

2. Crear un cliente RPC con Kit

Lecturas seguras de tipos con @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 envuelve las llamadas JSON-RPC basadas en fetch.
• .send() ejecuta la solicitud y devuelve resultados tipados.
• Cambie la URL por los endpoints del proveedor en producción.

Relacionado: Métodos RPC principales - métodos comunes

3. Compromiso: processed

Lecturas más rápidas: pueden revertirse en bifurcaciones.

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

• Úselo para sondeos de UI donde un ligero retraso está bien.
• No es ideal para decisiones de finalidad financiera.
• El comportamiento predeterminado del cliente puede variar; configúrelo explícitamente.

4. Compromiso: confirmed

Predeterminado para la mayoría de las lecturas de aplicaciones.

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

• Supermayoría votó sobre el slot: equilibrio práctico para dApps.
• Empareje con confirmed en los envíos antes de mostrar la UI de éxito.
• El compromiso predeterminado de la CLI se alinea con este nivel.

5. Compromiso: finalized

Lecturas más seguras para tesorería y contabilidad.

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

• finalized no se puede revertir en condiciones normales de red.
• Más lento: espere minutos en mainnet después de las escrituras.
• Úselo para retiros y estados de UI irreversibles.

6. Comprobar las cabeceras de límite de tasa

Los proveedores devuelven HTTP 429 cuando se limitan.

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

• Los endpoints públicos limitan agresivamente: espere 429 en CI.
• Retroceda exponencialmente y almacene en caché las lecturas.
• Las claves de proveedor dedicadas aumentan los límites.

Relacionado: Proveedores RPC - comparación de proveedores

7. La CLI utiliza el mismo RPC

Los comandos de terminal acceden al mismo JSON-RPC que su aplicación.

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

• solana slot se mapea a getSlot.
• La depuración comienza alineando la URL de la CLI y la RPC_URL de la aplicación.
• Las banderas de compromiso reflejan los parámetros RPC.

Ejemplos intermedios

8. Solicitudes por lotes (Concepto)

Reduzca los viajes de ida y vuelta agrupando JSON-RPC en un solo cuerpo 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 en paralelo todavía usa múltiples solicitudes HTTP a menos que el proveedor admita matrices de lotes.
• Prefiera getMultipleAccounts sobre N llamadas a getAccountInfo.
• Consulte la página de paginación para ver patrones de escaneo.

Relacionado: Paginación y eficiencia - lecturas eficientes

9. WebSocket vs HTTP

Las suscripciones necesitan transporte WebSocket.

# HTTP para lecturas únicas
curl https://api.devnet.solana.com ...
 
# WS para accountSubscribe (kit o cliente ws)

• accountSubscribe, logsSubscribe requieren un socket persistente.
• La URL WSS del proveedor puede diferir de la URL RPC HTTPS.
• HTTP sigue siendo la mejor opción para lecturas sin estado a escala.

Relacionado: Suscripciones WebSocket - actualizaciones en vivo

10. DAS y RPC estándar

La API de Digital Asset Standard extiende las lecturas para NFTs y activos comprimidos.

// Los métodos DAS (por ejemplo, getAsset) residen en los endpoints habilitados para DAS del proveedor
// El getAccountInfo estándar todavía subyace a los bytes brutos de la cuenta

• No todos los RPC públicos exponen DAS; consulte la matriz de características del proveedor.
• Use DAS para metadatos de activos; use getAccountInfo para cuentas de programas personalizadas.
• Consulte la página DAS para ver la lista de métodos.

Relacionado: La API DAS - lecturas de activos

Versiones de la pila: Esta página se escribió 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 y LiteSVM 0.6.x.