Conceptos básicos de @solana/kit

9 ejemplos para empezar con @solana/kit: 6 básicos y 3 intermedios.

Prerrequisitos

Instala kit 7.0.0 y las utilidades del programa del sistema:

npm install @solana/kit@7.0.0 @solana-program/system

Establece RPC_URL a un endpoint de devnet (se recomienda la URL del proveedor sobre los límites de tasa públicos).

Ejemplos básicos

1. Crear un cliente RPC

JSON-RPC tipado con .send() en cada método.

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

• createSolanaRpc devuelve un cliente apto para tree-shaking: importa solo lo que uses.
• Cada llamada RPC termina con .send() para E/S de red explícita.
• Cambia la URL por mainnet-beta cuando intentes usar SOL real.

Relacionado: RPC y suscripciones - suscripciones y proveedores

2. Leer el saldo de una cuenta

Las direcciones son cadenas de texto con marca: no son arrays de bytes en el código de la aplicación.

import { createSolanaRpc, address, lamports } from "@solana/kit";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
const owner = address("TU_PUBKEY_DE_CARTERA");
const { value } = await rpc.getBalance(owner).send();
console.log(Number(value) / 1e9);

• address() valida base58 y devuelve una Address tipada.
• Los saldos devuelven Lamports (bigint): conviértelos cuidadosamente para mostrarlos.
• Guarda en caché las lecturas en la interfaz de usuario; el estado de la cadena cambia en cada slot.

Relacionado: RPC y suscripciones - HTTP vs WebSocket

3. Generar un firmante Keypair

Los scripts del servidor y las pruebas usan firmantes explícitos.

import { generateKeyPairSigner } from "@solana/kit";
 
const signer = await generateKeyPairSigner();
console.log(signer.address);

• generateKeyPairSigner crea una clave Ed25519 utilizable en mensajes de transacción.
• Las aplicaciones del navegador deben preferir firmantes de cartera, no claves secretas incrustadas.
• Guarda los secretos con chmod 600 y nunca los incluyas en git.

Relacionado: Keypairs y firmantes - CryptoKey y importación de archivos

4. Cargar un Keypair desde JSON

Coincide con el formato de array de solana-keygen.

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { readFileSync } from "node:fs";
 
const secret = Uint8Array.from(
  JSON.parse(readFileSync("./dev-wallet.json", "utf8"))
);
const signer = await createKeyPairSignerFromBytes(secret);

• El archivo JSON es un array de clave secreta de 64 bytes.
• Usa keypairs separadas por clúster (devnet vs mainnet).
• En CI, carga desde secretos de entorno, no desde archivos del repositorio.

Relacionado: Keypairs y firmantes - traits de firmante

5. Obtener el último Blockhash

Los blockhashes caducan: actualízalos por cada lote de transacciones.

const { value: blockhash } = await rpc.getLatestBlockhash().send();
console.log(blockhash.blockhash, blockhash.lastValidBlockHeight);

• La vida útil está ligada a lastValidBlockHeight: los hashes obsoletos fallan en la confirmación.
• Obtén una vez por gesto del usuario, no una vez por carga de página.
• Empareja con lógica de reintento en errores de caducidad de blockhash.

Relacionado: Construcción de mensajes de transacción - vidas útiles

6. Construir un mensaje de Versión 0

La pipe funcional compone transformaciones inmutables de mensajes.

import {
  createTransactionMessage,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const message = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayerSigner(signer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) =>
    appendTransactionMessageInstruction(
      getTransferSolInstruction({
        source: signer,
        destination: recipient,
        amount: 10_000_000n,
      }),
      m
    )
);

• Los mensajes de versión 0 admiten tablas de búsqueda de direcciones.
• Las instrucciones provienen de paquetes @solana-program/*, no de IDs de programa en cadena.
• Las cantidades son lamports bigint.

Relacionado: Construcción de mensajes de transacción - pipeline completo

Ejemplos intermedios

7. Firmar y enviar

Los firmantes se resuelven desde el mensaje, luego el RPC envía la transacción de red.

import {
  signTransactionMessageWithSigners,
  getSignatureFromTransaction,
  sendAndConfirmTransactionFactory,
} from "@solana/kit";
 
const signed = await signTransactionMessageWithSigners(message);
const signature = getSignatureFromTransaction(signed);
 
const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
await sendAndConfirm(signed, { commitment: "confirmed" });

• signTransactionMessageWithSigners recopila los firmantes requeridos del mensaje.
• Usa suscripciones WebSocket para la confirmación cuando estén disponibles.
• Registra las firmas para tickets de soporte y enlaces a exploradores.

Relacionado: Firma y envío - estrategias de confirmación

8. Suscribirse a cambios de cuenta

Las actualizaciones push son mejores que el sondeo para las interfaces de usuario de carteras.

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

• Aborta siempre las suscripciones al desmontar.
• Usa endpoints wss://; las URLs HTTP fallan para las suscripciones.
• Los niveles de los proveedores difieren en los límites de suscripción.

Relacionado: RPC y suscripciones - tipos de suscripción

9. Codificar datos de cuenta con Codecs

Los codecs de Kit reemplazan los diseños de Buffer hechos a mano.

import {
  getU32Encoder,
  getU32Decoder,
  getStructEncoder,
  getStructDecoder,
} from "@solana/kit";
 
const layout = getStructEncoder([["count", getU32Encoder()]]);
const bytes = layout.encode({ count: 42 });
const decoded = getStructDecoder([["count", getU32Decoder()]]).decode(bytes);

• Los codificadores y decodificadores están separados para el tree-shaking.
• Empareja con diseños generados por Codama para cuentas de programas.
• Prefiere codecs generados sobre offsets de IDL copiados y pegados.

Relacionado: Codecs y serialización - diseños avanzados

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.