Fundamentos de Solana

9 ejemplos para empezar con los fundamentos de Solana: 6 básicos y 3 intermedios. Cubre cuentas, programas, transacciones, SOL, clústeres y el flujo de trabajo del desarrollador en Agave 4.1.1.

Prerrequisitos

Instala la CLI de Solana 3.0.10 y crea un par de claves predeterminado en devnet.

sh -c "$(curl -sSfL https://release.anza.xyz/v3.0.10/install)"
solana --version
solana config set --url devnet
solana-keygen new --no-bip39-passphrase -o ~/.config/solana/id.json
solana airdrop 2

Para los ejemplos del cliente TypeScript, usa @solana/kit 7.0.0:

npm install @solana/kit@7.0.0

Ejemplos Básicos

1. Leer el Saldo de una Cuenta

Cada dirección en Solana se mapea a una cuenta, incluso si tiene cero lamports.

import { createSolanaRpc, address, lamports } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const pubkey = address("11111111111111111111111111111111");
 
const { value } = await rpc.getBalance(pubkey).send();
console.log(`Balance: ${Number(lamports(value)) / 1e9} SOL`);

Los saldos se almacenan en lamports (u64), no en números flotantes de SOL.
getBalance devuelve los lamports directamente del campo lamports de la cuenta.
Las direcciones no inicializadas devuelven 0; no existe una cuenta hasta que se financia.

Relacionado: SOL, Lamports y Unidades - precisión y conversiones

2. Comprender el Modelo de Cuentas

Las cuentas son la única abstracción para todo el estado en la cadena.

// Diseño conceptual - cada cuenta tiene estos campos
pub struct Account {
    pub lamports: u64,      // Saldo de SOL en lamports
    pub data: Vec<u8>,      // buffer de bytes arbitrario
    pub owner: Pubkey,      // programa permitido para escribir datos
    pub executable: bool,   // true para programas desplegados
    pub rent_epoch: u64,    // seguimiento de alquiler (campo heredado)
}

Los programas son cuentas con executable = true y código en data.
Las cuentas de datos almacenan el estado del programa, propiedad del programa que las interpreta.
Solo el programa propietario puede mutar los datos de una cuenta (con excepciones de firmante).

Relacionado: El Modelo Mental de Solana frente a EVM - cuentas vs contratos

3. Enviar una Transferencia Simple

Una transacción con una instrucción del Programa del Sistema mueve SOL entre cuentas.

solana transfer <CLAVE_PÚBLICA_DEL_DESTINATARIO> 0.1 --allow-unfunded-recipient

La CLI construye una transacción con la instrucción Transfer del Programa del Sistema.
El par de claves del remitente firma como pagador de tarifas y como autoridad de la cuenta de origen.
--allow-unfunded-recipient crea el destino si aún no tiene una cuenta.

Relacionado: Cómo Fluye una Transacción - del cliente a la confirmación

4. Inspeccionar una Transacción

Usa la CLI o RPC para ver instrucciones, firmantes y unidades de cómputo consumidas.

solana confirm -v <FIRMA>

-v imprime el ID del programa, las cuentas y los datos de cada instrucción.
Los registros muestran las unidades de cómputo (CU) consumidas por instrucción.
Las transacciones fallidas aún aparecen en la cadena con códigos de error en los registros.

Relacionado: Pares de Claves y Direcciones - quién firma qué

5. Elegir el Clúster Correcto

Solana ejecuta múltiples clústeres independientes con diferentes propósitos.

solana config set --url devnet      # SOL de prueba gratuito, RPC público
solana config set --url testnet     # pruebas de validadores, menos estable
solana config set --url mainnet-beta # producción - SOL real
solana-test-validator               # nodo Agave 4.1.1 local

Devnet es el predeterminado para el desarrollo de aplicaciones.
El validador local te da control total y latencia de red cero.
Mainnet-beta requiere SOL real y tarifas de prioridad durante la congestión.

Relacionado: Clústeres y Redes - cuándo usar cada uno

6. Comprender las Ranuras y la Sincronización

Solana tiene como objetivo ranuras de ~400 ms; los líderes producen bloques por ranura.

solana slot
solana block-time $(solana slot)

Una ranura es una ventana de tiempo en la que un validador es el productor de bloques.
Una época es un número fijo de ranuras (aprox. 432,000 ranuras, ~2 días).
Las ranuras omitidas ocurren cuando el líder asignado está fuera de línea o es lento.

Relacionado: Ranuras, Bloques y Épocas - detalles del calendario de épocas

Ejemplos Intermedios

7. Construir una Transacción con @solana/kit

Kit usa una tubería funcional para ensamblar transacciones versionadas.

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  pipe,
  address,
  getSignatureFromTransaction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const feePayer = address("TU_CLAVE_PÚBLICA_PAGADORA_DE_TARIFAS");
const recipient = address("CLAVE_PÚBLICA_DEL_DESTINATARIO");
 
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
const transferIx = getTransferSolInstruction({
  source: feePayer,
  destination: recipient,
  amount: 100_000_000n, // 0.1 SOL en lamports
});
 
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(feePayer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstruction(transferIx, m),
);
 
// Firma con tu firmante de par de claves, luego envía a través de sendTransaction

Kit separa la construcción del mensaje de la firma y el envío.
Las cantidades son siempre bigint lamports, nunca números flotantes de JavaScript.
Las transacciones de versión 0 admiten tablas de búsqueda de direcciones para más cuentas.

Relacionado: Billeteras y Exploradores - flujo de trabajo de devnet

8. Generar y Usar un Par de Claves

Los pares de claves Ed25519 son la raíz de la identidad y la firma en Solana.

solana-keygen new --outfile ./dev-wallet.json --no-bip39-passphrase
solana-keygen pubkey ./dev-wallet.json

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

El archivo JSON es un array de clave secreta de 64 bytes; trátalo como una contraseña.
Las claves públicas (direcciones) son puntos Ed25519 de 32 bytes, codificados en base58.
Nunca incluyas archivos de par de claves en el control de versiones.

Relacionado: Pares de Claves y Direcciones - modelo de firma

9. Seguir una Transacción de Extremo a Extremo

Sigue una transferencia desde la sumisión del cliente hasta la confirmación finalizada.

# 1. Enviar
SIG=$(solana transfer <DESTINATARIO> 0.01 --output json | jq -r .signature)
 
# 2. Consultar confirmación
solana confirm $SIG --commitment confirmed
 
# 3. Inspeccionar en el explorador
echo "https://explorer.solana.com/tx/$SIG?cluster=devnet"

Procesado: el nodo lo ha visto; aún puede ser descartado.
Confirmado: una supermayoría votó el bloque que lo contiene.
Finalizado: el bloque está enraizado y no se puede revertir.

Relacionado: Cómo Fluye una Transacción - canalización completa

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.

Prerrequisitos

Instala la CLI de Solana 3.0.10 y crea un par de claves predeterminado en devnet.

sh -c "$(curl -sSfL https://release.anza.xyz/v3.0.10/install)"
solana --version
solana config set --url devnet
solana-keygen new --no-bip39-passphrase -o ~/.config/solana/id.json
solana airdrop 2

Para los ejemplos del cliente TypeScript, usa @solana/kit 7.0.0:

npm install @solana/kit@7.0.0

Ejemplos Básicos

1. Leer el Saldo de una Cuenta

Cada dirección en Solana se mapea a una cuenta, incluso si tiene cero lamports.

import { createSolanaRpc, address, lamports } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const pubkey = address("11111111111111111111111111111111");
 
const { value } = await rpc.getBalance(pubkey).send();
console.log(`Balance: ${Number(lamports(value)) / 1e9} SOL`);

Los saldos se almacenan en lamports (u64), no en números flotantes de SOL.
getBalance devuelve los lamports directamente del campo lamports de la cuenta.
Las direcciones no inicializadas devuelven 0; no existe una cuenta hasta que se financia.

Relacionado: SOL, Lamports y Unidades - precisión y conversiones

2. Comprender el Modelo de Cuentas

Las cuentas son la única abstracción para todo el estado en la cadena.

// Diseño conceptual - cada cuenta tiene estos campos
pub struct Account {
    pub lamports: u64,      // Saldo de SOL en lamports
    pub data: Vec<u8>,      // buffer de bytes arbitrario
    pub owner: Pubkey,      // programa permitido para escribir datos
    pub executable: bool,   // true para programas desplegados
    pub rent_epoch: u64,    // seguimiento de alquiler (campo heredado)
}

Los programas son cuentas con executable = true y código en data.
Las cuentas de datos almacenan el estado del programa, propiedad del programa que las interpreta.
Solo el programa propietario puede mutar los datos de una cuenta (con excepciones de firmante).

Relacionado: El Modelo Mental de Solana frente a EVM - cuentas vs contratos

3. Enviar una Transferencia Simple

Una transacción con una instrucción del Programa del Sistema mueve SOL entre cuentas.

solana transfer <CLAVE_PÚBLICA_DEL_DESTINATARIO> 0.1 --allow-unfunded-recipient

La CLI construye una transacción con la instrucción Transfer del Programa del Sistema.
El par de claves del remitente firma como pagador de tarifas y como autoridad de la cuenta de origen.
--allow-unfunded-recipient crea el destino si aún no tiene una cuenta.

Relacionado: Cómo Fluye una Transacción - del cliente a la confirmación

4. Inspeccionar una Transacción

Usa la CLI o RPC para ver instrucciones, firmantes y unidades de cómputo consumidas.

solana confirm -v <FIRMA>

-v imprime el ID del programa, las cuentas y los datos de cada instrucción.
Los registros muestran las unidades de cómputo (CU) consumidas por instrucción.
Las transacciones fallidas aún aparecen en la cadena con códigos de error en los registros.

Relacionado: Pares de Claves y Direcciones - quién firma qué

5. Elegir el Clúster Correcto

Solana ejecuta múltiples clústeres independientes con diferentes propósitos.

solana config set --url devnet      # SOL de prueba gratuito, RPC público
solana config set --url testnet     # pruebas de validadores, menos estable
solana config set --url mainnet-beta # producción - SOL real
solana-test-validator               # nodo Agave 4.1.1 local

Devnet es el predeterminado para el desarrollo de aplicaciones.
El validador local te da control total y latencia de red cero.
Mainnet-beta requiere SOL real y tarifas de prioridad durante la congestión.

Relacionado: Clústeres y Redes - cuándo usar cada uno

6. Comprender las Ranuras y la Sincronización

Solana tiene como objetivo ranuras de ~400 ms; los líderes producen bloques por ranura.

solana slot
solana block-time $(solana slot)

Una ranura es una ventana de tiempo en la que un validador es el productor de bloques.
Una época es un número fijo de ranuras (aprox. 432,000 ranuras, ~2 días).
Las ranuras omitidas ocurren cuando el líder asignado está fuera de línea o es lento.

Relacionado: Ranuras, Bloques y Épocas - detalles del calendario de épocas

Ejemplos Intermedios

7. Construir una Transacción con @solana/kit

Kit usa una tubería funcional para ensamblar transacciones versionadas.

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  pipe,
  address,
  getSignatureFromTransaction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const feePayer = address("TU_CLAVE_PÚBLICA_PAGADORA_DE_TARIFAS");
const recipient = address("CLAVE_PÚBLICA_DEL_DESTINATARIO");
 
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
const transferIx = getTransferSolInstruction({
  source: feePayer,
  destination: recipient,
  amount: 100_000_000n, // 0.1 SOL en lamports
});
 
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(feePayer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstruction(transferIx, m),
);
 
// Firma con tu firmante de par de claves, luego envía a través de sendTransaction

Kit separa la construcción del mensaje de la firma y el envío.
Las cantidades son siempre bigint lamports, nunca números flotantes de JavaScript.
Las transacciones de versión 0 admiten tablas de búsqueda de direcciones para más cuentas.

Relacionado: Billeteras y Exploradores - flujo de trabajo de devnet

8. Generar y Usar un Par de Claves

Los pares de claves Ed25519 son la raíz de la identidad y la firma en Solana.

solana-keygen new --outfile ./dev-wallet.json --no-bip39-passphrase
solana-keygen pubkey ./dev-wallet.json

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

El archivo JSON es un array de clave secreta de 64 bytes; trátalo como una contraseña.
Las claves públicas (direcciones) son puntos Ed25519 de 32 bytes, codificados en base58.
Nunca incluyas archivos de par de claves en el control de versiones.

Relacionado: Pares de Claves y Direcciones - modelo de firma

9. Seguir una Transacción de Extremo a Extremo

Sigue una transferencia desde la sumisión del cliente hasta la confirmación finalizada.

# 1. Enviar
SIG=$(solana transfer <DESTINATARIO> 0.01 --output json | jq -r .signature)
 
# 2. Consultar confirmación
solana confirm $SIG --commitment confirmed
 
# 3. Inspeccionar en el explorador
echo "https://explorer.solana.com/tx/$SIG?cluster=devnet"

Procesado: el nodo lo ha visto; aún puede ser descartado.
Confirmado: una supermayoría votó el bloque que lo contiene.
Finalizado: el bloque está enraizado y no se puede revertir.

Relacionado: Cómo Fluye una Transacción - canalización completa

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.

Fundamentos de Solana

Buscar en la documentación

Fundamentos de Solana