Blueprint de Clientes Tipados

Los clientes tipados son la forma en que TypeScript off-chain habla con un programa de Solana sin codificar a mano discriminadores, metadatos de cuentas y layouts de Borsh. Una vez que tratas la IDL como el contrato compartido y cada generador de clientes como un consumidor de ese contrato, la API Program de Anchor, la salida de Codama, los ayudantes de gill, los constructores de instrucciones y los decodificadores de cuentas dejan de parecer bibliotecas competidoras y empiezan a parecer un único pipeline desde anchor build hasta una transacción firmada.

Conceptos básicos de clientes tipados es la entrada práctica; El Cliente TS de Anchor, Codama, gill, Construcción de Instrucciones, Obtención y Decodificación de Cuentas y Mantener los Clientes Sincronizados se centran en una etapa cada uno. Esta página se sitúa debajo: cómo conectan las piezas, qué ruta elegir y qué fijar para que los frontends y bots se mantengan honestos después de las actualizaciones del programa.

Resumen

• La superficie pública de un programa se describe mediante una IDL; los clientes tipados regeneran constructores de instrucciones, codecs y ayudantes de fetch a partir de ese JSON, de modo que TypeScript no pueda inventar silenciosamente layouts que diverjan de la codificación on-chain.
• Por qué Importa: Las listas de cuentas y los buffers de argumentos escritos a mano se desvían; una superficie de cliente impulsada por IDL reduce los errores de codificación en mainnet, acelera el trabajo de UI y bots, y permite que CI falle cuando la interfaz se mueve sin una actualización del cliente.
• Conceptos Clave: IDL de Anchor, Program TS de Anchor, Codama + @solana/kit, gill, constructores de instrucciones tipados, ayudantes de fetch/decode, discriminadores y Borsh, regeneración de CI y comprobaciones de desvío.
• Cuándo Usar: Para lanzar o mantener aplicaciones TypeScript contra programas de Anchor (o descritos por IDL), elegir entre el cliente clásico de Anchor y stacks centrados en kit, o diseñar puertas de lanzamiento de monorepos para programas más frontend.
• Limitaciones / Compensaciones: La calidad del cliente sigue a la calidad de la IDL; las cuentas restantes y algunos programas nativos necesitan documentación adicional; Anchor TS y Codama se dirigen a diferentes tiempos de ejecución, así que elige una historia de transacción por aplicación; gill no genera la superficie del programa de tu IDL.
• Temas Relacionados: Cliente TS de Anchor, Codama, gill, construcción de instrucciones, obtención y decodificación de cuentas, mantenimiento de clientes sincronizados.

Fundamentos

Los programas de Solana exponen bytes: datos de instrucciones (generalmente un discriminador de 8 bytes más argumentos) y listas de cuentas con indicadores de firmante y escritura. Nada en la red es "nativo de TypeScript". Sin una descripción compartida de esas formas, cada dApp, script e indexador inventa su propia codificación y, finalmente, discrepa con el programa.

Anchor llena ese vacío para los programas del framework. Las macros en instrucciones, cuentas, eventos y errores alimentan anchor build, que emite JSON de IDL bajo target/idl/. Ese archivo es el contrato para el trabajo off-chain en esta sección: nombres de instrucciones y cuentas, tipos, errores, eventos y metadatos de dirección del programa. Los clientes tipados existen para consumir ese contrato, no para reemplazarlo.

Piensa en el stack off-chain como capas desde la IDL hacia la UX:

  +------------------------------------------+
  |  App / bot / API (flujos de negocio)       |  <- UI, trabajos, wallets
  +------------------------------------------+
  |  Conveniencia (ayudantes opcionales de gill) |  <- Patrones RPC + envío
  +------------------------------------------+
  |  Superficie del cliente del programa       |
  |    Codecs / ixs generados por Codama       |
  |    o Anchor TS Program.methods.*           |
  +------------------------------------------+
  |  Primitivas de tiempo de ejecución (@solana/kit 7.0.0) |  <- RPC, mensajes, firmantes
  +------------------------------------------+
  |  Artefacto IDL (JSON, anclado en git/npm)  |  <- Contrato versionado
  +------------------------------------------+
  |  Build del programa (Anchor 0.32.1 + sBPF) |
  +------------------------------------------+

Dos historias de cliente de programa de TypeScript dominan:

1. Cliente TS de Anchor (@coral-xyz/anchor): carga la IDL en new Program(...), llama a program.methods.<ix>(...).accounts(...).rpc(). Encaja bien con anchor test, dApps existentes y equipos que ya usan patrones de Anchor Provider.
2. Codama: analiza la IDL de Anchor en un grafo de nodos y renderiza módulos orientados a @solana/kit (get*Instruction, ayudantes fetch* / decode*, mapas de errores). Encaja bien con stacks de kit nuevos y ensamblaje de transacciones apto para tree-shaking.

@solana/kit 7.0.0 es la capa moderna de RPC, codecs, firmantes y mensajes de transacción. Codama es el puente habitual desde la IDL de Anchor a los tipos de kit. Kit por sí solo no conoce los layouts de cuenta de tu programa; sin Codama (o codecs escritos a mano) vuelves a inventar bytes.

gill se sitúa por encima de kit como conveniencia opcional: patrones de fábrica de clientes, RPC por nombre y ayudantes de envío comunes. No reemplaza la salida de Codama para tu programa personalizado. Todavía generas constructores y decodificadores específicos del programa a partir de la IDL, y luego los compones con rutas de envío de kit o gill.

Lecturas y escrituras comparten la misma superficie generada: los constructores codifican el discriminador + argumentos y metadatos de cuenta; los ayudantes de fetch decodifican los bytes de RPC con el layout coincidente. Un generador mantiene ambas rutas alineadas.

Los pines de plataforma para este sitio son: Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.

Mecánicas e Interacciones

IDL de entrada, superficie tipada de salida

La espina dorsal es siempre:

  programs/.../lib.rs  --macros-->  anchor build
                                         |
                                         v
                                  target/idl/foo.json
                                         |
              +--------------------------+--------------------------+
              v                                                     v
     Anchor TS Program(idl)                               Codama CLI + renderers
     methods / account.fetch                              get*Instruction, fetch*
              |                                                     |
              v                                                     v
     Proveedor clásico / pruebas                           mensajes de transacción de kit

Regenera en cada cambio de interfaz pública. Editar a mano carpetas generadas o el JSON de IDL para "coincidir con la UI" crea un desvío silencioso: el programa todavía codifica el layout definido por macros mientras que los clientes codifican ficción. Los detalles para la generación se encuentran en Codama; la ruta clásica es El Cliente TS de Anchor.

Elegir entre Anchor TS y Codama

No mezcles el ensamblaje de transacciones de kit con objetos de instrucción de web3.js sin un puente deliberado. Elige un tiempo de ejecución de cliente por aplicación y regenera cuando la IDL cambie. Prefiere Codama + kit para módulos nuevos; mantén Anchor TS donde el costo de migración sea dominante.

Construcción de instrucciones

Un constructor de instrucciones generado responde: qué cuentas, qué indicadores, qué tipos de argumentos, qué discriminador. Pasas direcciones y firmantes; el constructor emite un objeto de instrucción nativo de kit (o nativo de Anchor) listo para ser añadido a un mensaje de transacción.

  getIncrementInstruction({ counter, authority })
           |
           v
  Instruction {
    programAddress,
    accounts: [ { counter, writable }, { authority, signer } ],
    data: discriminator || borsh(args)
  }
           |
           v
  añadir a TransactionMessage -> firmar -> enviar

Nunca reordenes manualmente los metadatos de cuenta. El orden y los indicadores provienen de la IDL; los flujos de tipo init todavía necesitan el Sistema Program y cuentas de financiación cuando sea necesario. Inmersión profunda: Construcción de Instrucciones.

Obtención y decodificación de cuentas

Las lecturas son el dual de las escrituras:

1. RPC devuelve propietario, lamports y bytes de datos (getAccountInfo o un ayudante de fetch generado).
2. El decodificador generado verifica el discriminador / layout y devuelve un objeto tipado.
3. Los llamadores manejan null (cuentas faltantes o cerradas) antes de la UI o la lógica de negocio.

  RPC getAccountInfo(address)
           |
           v
  bytes crudos + propietario
           |
           v
  decodeFoo / fetchFoo  -->  { data: { ... }, ... } | null

Un propietario incorrecto, un ID de programa de clúster incorrecto o un decodificador obsoleto producen basura que parece válida hasta que una escritura falla. Prefiere los ayudantes fetch* generados; usa RPC crudo + decode* para lotes personalizados. Detalles: Obtención y Decodificación de Cuentas.

Dónde encaja gill

gill reduce el boilerplate de kit (creación de clientes, nombres de alias, patrones de envío y confirmación). El conocimiento específico del programa todavía proviene de Codama (o Anchor TS). Una composición saludable es:

  gill createSolanaClient  -->  ayudantes de RPC y envío
  Módulo generado por Codama  -->  getIx / fetchAccount
  Código de la aplicación      -->  componer ambos

Trata gill como una aceleración sobre la familiaridad con kit, no como una caja negra que inventa la API de tu programa. Ver gill.

Mantener los clientes sincronizados

Los clientes tipados solo se mantienen correctos si la regeneración es mecánica y forzada:

1. Edita la superficie del programa bajo Anchor 0.32.1; compila con Agave/CLI y Rust fijados.
2. Revisa la diferencia de IDL; confirma el artefacto si es la fuente de verdad del equipo.
3. Ejecuta Codama (o actualiza los tipos de Anchor); falla CI en árboles generados sucios.
4. Ejecuta pruebas unitarias/de integración contra localnet o harnesses estilo Surfpool.
5. Coordina los despliegues de frontend/bots con los despliegues de programas cuando el cambio sea disruptivo.
6. Etiqueta las versiones con el ID del programa, el clúster y el hash del contenido de la IDL (o SHA del commit).

  cambio de programa --> diferencia IDL --> diferencia cliente --> reconstrucción de app --> despliegue
                         ^
                         |
              CI: git diff --exit-code generated/

La obtención de IDL on-chain ayuda al descubrimiento; los clientes de producción todavía fijan artefactos confiables. Práctica completa: Mantener los Clientes Sincronizados.

Un día de trabajo en todo el pipeline

1. Cambia una instrucción o una estructura de cuenta; anchor build.
2. Confirma que target/idl coincide con la superficie pública prevista.
3. Regenera los clientes de Codama (o recarga la IDL de Anchor en las pruebas).
4. Actualiza los puntos de llamada; corrige los errores de TypeScript.
5. Simula la instrucción; obtén y decodifica la cuenta afectada.
6. Implementa las puertas de CI para que la regeneración no pueda omitirse.

Consideraciones Avanzadas y Aplicaciones

Ajusta la antigüedad del stack, la elección del tiempo de ejecución y el rigor de la versión a una ruta, luego añade compuertas cuando aumente el desvío entre desarrolladores o el riesgo de mainnet.

Aplicaciones multi-programa: nunca fusiones superficies de IDL en un solo JSON. Nombra por espacio de nombres la salida generada (clients/program_a, clients/program_b) y evita colisiones de nombres de exportación.

Los indexadores y bots también son clientes; un decodificador de trabajador obsoleto es la misma clase de error que un hook de UI obsoleto, solo que más silencioso.

Los programas nativos pueden carecer de una IDL de Anchor completa. Prefiere una IDL compatible mantenida, Codama a partir de una descripción personalizada, o codecs de kit construidos a mano.

Las cuentas restantes a menudo se encuentran fuera de las listas fijas de IDL. Documentarlas y pasarlas explícitamente; la generación de código puede no inventar el grafo completo de cuentas en tiempo de ejecución.

Para revisiones de diseño: qué tiempo de ejecución TS se estandariza, quién posee el artefacto de IDL, cómo la CI detecta el desvío, si se permite gill y cómo se implementan los cambios disruptivos de IDL.

Conceptos Erróneos Comunes

• "Los clientes tipados significan que puedo saltarme aprender los mensajes de kit." Los constructores todavía aterrizan en mensajes de transacción; la simulación, las tarifas y los firmantes siguen siendo tu responsabilidad.
• "Anchor TS y Codama son reemplazos directos." Ambos leen la IDL, pero se dirigen a diferentes stacks de clientes; elige una ruta de transacción principal por aplicación.
• "gill genera mi cliente de programa." gill ayuda con los flujos de trabajo de kit; las instrucciones y decodificadores específicos del programa todavía provienen de Codama o Anchor TS.
• "Puedo editar manualmente los archivos generados para una corrección urgente." La próxima regeneración los borrará; pon las anulaciones solo en módulos envolventes.
• "Si la UI tiene tipos correctos, la IDL coincide con mainnet." Los tipos coinciden con la IDL contra la que generaste, no necesariamente con el programa desplegado; fija el ID del programa, el clúster y el hash de la IDL.
• "Los ayudantes de fetch son un pulido opcional." Los decodificadores compartidos evitan que dos layouts (ruta de lectura vs ruta de escritura) diverjan dentro de una misma base de código.
• "La regeneración de CI es excesiva para un repositorio individual." El desvío aparece la primera vez que cambias un campo de cuenta y olvidas un segundo paquete.
• "Importar el JSON completo de la IDL en tiempo de ejecución siempre está bien." Las IDLs grandes hinchan los bundles; prefiere módulos generados aptos para tree-shaking o cargas perezosas.

Preguntas Frecuentes

Relacionados

• El Cliente TS de Anchor - Program, métodos y flujos clásicos de Provider
• Codama - generación de clientes @solana/kit a partir de IDL de Anchor
• gill - ayudantes de kit de nivel superior para patrones comunes de RPC y envío
• Construcción de Instrucciones - constructores de instrucciones tipados en mensajes de transacción
• Obtención y Decodificación de Cuentas - lecturas tipadas con codecs generados
• Mantener los Clientes Sincronizados - regeneración impulsada por IDL y compuertas de desvío de CI

Versiones del Stack: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.