Conceptos básicos de clientes tipados
8 ejemplos de clientes TypeScript impulsados por IDL: 5 básicos y 3 intermedios.
Prerrequisitos
anchor build # Anchor 0.32.1
npm install @solana/kit@7.0.0
npm install -D @codama/cli @codama/renderers-jsEjemplos básicos
1. ¿Por qué generar clientes?
La IDL es el contrato entre Rust en la cadena y TypeScript fuera de la cadena.
ls target/idl/my_program.json- Los diseños escritos a mano se desvían de las estructuras de Anchor 0.32.1.
- Los códecs generados coinciden exactamente con los discriminadores.
- Una única fuente de verdad reduce los incidentes en mainnet.
2. Cliente Anchor TS
La clase Program de @coral-xyz/anchor todavía funciona para aplicaciones heredadas.
// Prefiere Codama + kit para módulos nuevos- Históricamente, el cliente Anchor está acoplado a los tipos de web3.js.
- Migra las llamadas al programa de forma incremental.
- Consulta El cliente Anchor TS.
3. Pipeline de Codama
IDL → grafo de nodos → renderizador → cliente TypeScript kit.
npx codama run --config codama.json- Confirma la salida generada o regenérala en CI.
- Falla la CI si la carpeta está sucia después de la compilación.
- Fija la versión de
@codama/clipor repositorio.
4. Obtener cuenta tipada
Los decodificadores generados analizan los datos de la cuenta.
import { createSolanaRpc, address } from "@solana/kit";
// import { fetchMyAccount } from "./generated";
const rpc = createSolanaRpc(process.env.RPC_URL!);- Obtiene y decodifica en un único helper al usar la salida de gill/Codama.
- Maneja
nullcuando la cuenta no está inicializada. - Consulta Obtención y decodificación de cuentas.
5. Construir instrucción tipada
Los constructores de instrucciones codifican el discriminador y los argumentos.
// getIncrementInstruction({ account, authority }) del cliente generado- Los constructores devuelven el tipo
Instructionde kit. - Añade al mensaje de transacción con las API de kit.
- Las metadatos de cuenta se ordenan según la IDL.
Ejemplos intermedios
6. Conveniencia de gill
Helpers de nivel superior que agrupan kit y programas comunes.
npm install gillimport { createSolanaClient } from "gill";- Arranque más rápido para flujos estándar.
- Utiliza kit para metadatos de cuenta poco comunes.
- Consulta gill.
7. Regeneración en CI
anchor build && npx codama run && git diff --exit-code clients/- Evita enviar clientes obsoletos.
- Empareja con pruebas de integración de Surfpool.
- Documenta la generación de código en CONTRIBUTING.md.
8. Aplicaciones multi-programa
Un monorepo puede alojar varias IDL.
{ "idl": "target/idl/program_a.json", "before": [], "scripts": { "js": "@codama/renderers-js" } }- Nombra las carpetas generadas por programa.
- Evita nombres de exportación duplicados entre programas.
- Consulta Mantener los clientes sincronizados.
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.