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-js

Ejemplos 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/cli por 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 null cuando 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 Instruction de 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 gill

import { 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.