Mejores Prácticas para Clientes Tipados
25 prácticas para clientes Solana completamente tipados y basados en IDL.
//
Busca en todas las páginas de la documentación
25 prácticas para clientes Solana completamente tipados y basados en IDL.
Trata la IDL como contrato de API: Cada cambio en cuentas y argumentos es una revisión de cambio disruptivo (Conceptos Básicos de Clientes Tipados).
Regenera en CI: Falla cuando clients/generated difiere después de anchor build + Codama.
Fija el renderizador de Codama con el kit 7.0.0: Las versiones principales del renderizador siguen los diseños de los codecs.
Nunca edites archivos generados: Envuelve las extensiones en módulos escritos a mano.
Confirma la IDL o un artefacto de compilación verificable: El soporte debe poder reproducir la generación del cliente.
Nombra los resultados de múltiples programas: Evita colisiones de nombres de exportación.
Usa las utilidades fetch*: Combina RPC + decodificación para reducir errores (Obtención y Decodificación de Cuentas).
Simula lotes de instrucciones: Detecta errores de restricciones antes del modal de la billetera.
Mapea errores del programa: Muestra los códigos de error de la IDL en la copia de la UI.
bigint para u64: Coincide con los tipos Borsh en cadena en TypeScript.
Coordina el despliegue + frontend: Envía las actualizaciones del cliente con las actualizaciones del programa.
IDs de programa específicas del entorno: devnet ≠ mainnet en archivos .env.
Documenta el hash de la IDL en los lanzamientos: Entrada de registro de cambios por cada cambio de interfaz.
Prefiere Codama sobre codecs manuales: El costo de mantenimiento es menor a largo plazo.
gill para el arranque, kit para casos extremos: Entiende ambas capas (gill).
El servidor lee tipado: Las rutas de Next.js importan decodificadores sin billeteras.
El cliente escribe tipado: La billetera firma solo las instrucciones generadas.
Prueba fixtures de decodificación: Instantáneas de bytes de cuenta en pruebas unitarias.
Evita getProgramAccounts en la UI de mainnet: Usa un indexador o RPC filtrado.
Alineación con Anchor 0.32.1: IDL del crate anchor-lang coincidente.
No web3.js en la ruta generada: Modelo de Dirección Única a través de kit.
Carga diferida de IDLs grandes: Divide los programas para reducir el tamaño del paquete.
Envuelve errores de RPC: Traduce 429 y timeouts para los usuarios.
Audita cuentas CPI en la IDL: Los clientes deben incluir las cuentas restantes cuando sea necesario.
Educa al equipo sobre los comandos de codegen: CONTRIBUTING.md lista los pasos exactos.
Manten el legado; el código nuevo usa la salida del kit Codama.
Sí, con verificación de deriva en CI, o regenera solo en CI si el artefacto de IDL está almacenado.
Codama soporta esquemas de IDL JSON compatibles.
Versiones de la Pila: Esta página fue escrita 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.
Revisado por Chris St. John·Última actualización: 19 jul 2026