IDL y Blueprint de Codegen

La pila de IDL y codegen de Solana es cómo la superficie pública de un programa se convierte en módulos CPI tipados de Rust, constructores de instrucciones TypeScript e interfaces descubribles para exploradores e integradores. Una vez que tratas el Lenguaje de Definición de Interfaz (IDL) como el contrato compartido y cada generador de cliente como un consumidor de ese contrato, las macros de Anchor, declare_program!, Codama, los paquetes npm y las cuentas IDL en cadena dejan de parecer tribus de herramientas separadas y comienzan a parecer una sola tubería desde las macros hasta las máquinas.

El IDL de Anchor es la entrada práctica; `declare_program!](./declare-program.md), Generación de Clientes TS, Codama desde un IDL de Anchor, Versionado de IDL y IDLs en Cadena cada uno se enfoca en una etapa. Esta página se sitúa debajo: cómo se conectan las piezas, qué fijas y qué camino tomar desde la primera compilación hasta la producción multi-cliente.

Resumen

• Un IDL describe la API pública de un programa (instrucciones, cuentas, tipos, eventos, errores, metadatos de dirección del programa), y las herramientas de codegen regeneran clientes tipados y ayudantes CPI a partir de ese JSON para que los humanos no codifiquen a mano discriminadores y layouts.
• Por Qué Importa: Sin una columna vertebral IDL única, las dApps, bots, llamantes CPI e indexadores inventan layouts incompatibles; con él, envías un artefacto desde anchor build y regeneras cada consumidor cuando la superficie del programa cambia.
• Conceptos Clave: JSON IDL de Anchor, discriminadores y layouts Borsh, declare_program!, Programa TS de Anchor, Codama + @solana/kit, versionado de IDL / etiquetas de lanzamiento, cuentas IDL en cadena, comprobaciones de deriva CI.
• Cuándo Usar: Integrar o hacer CPI a programas de Anchor, generar clientes tipados, publicar SDKs, coordinar actualizaciones entre aplicaciones, o explicar por qué "el IDL está obsoleto" rompe billeteras y CPI a la vez.
• Limitaciones / Compensaciones: La calidad del IDL sigue a las macros y la configuración de compilación; las cuentas restantes y algunos programas nativos necesitan documentación más allá del IDL; el IDL en cadena es descubrible pero no sustituye a los hashes de lanzamiento de confianza; Codama y Anchor TS son tiempos de ejecución diferentes, así que elige una historia de cliente por aplicación.
• Temas Relacionados: IDL de Anchor, declare_program, generación de clientes TS, Codama desde IDL de Anchor, versionado de IDL, IDLs en cadena.

Fundamentos

Los programas de Solana no exponen un "archivo ABI" incorporado como lo hacen algunas cadenas de herramientas EVM por defecto. Anchor llena ese vacío para los programas del framework: atributos Rust (#[program], #[account], #[event], #[error_code], y metadatos de restricciones de cuenta) se expanden en código de validación y serialización, y anchor build emite un IDL JSON bajo target/idl/ que refleja los manejadores y tipos públicos.

Ese JSON es el contrato, no un volcado de "agradable tener". Los nombres de instrucciones se mapean a discriminadores de 8 bytes y codificaciones de argumentos. Las listas de cuentas nombran roles, mutabilidad y firmantes. La sección de tipos refleja las cuentas y las estructuras personalizadas. Los errores y eventos dan a los clientes códigos legibles por humanos y formas de registro. El campo address (cuando está presente) vincula el artefacto a un ID de programa de declare_id!.

Piensa en la pila como capas desde las macros hacia los integradores:

  +------------------------------------------+
  |  Integradores (dApps, bots, exploradores) |  <- llamadas tipadas, descubrimiento
  +------------------------------------------+
  |  Consumidores de Codegen                 |
  |    declare_program! (CPI Rust)           |
  |    Programa TS de Anchor / Codama + kit  |
  +------------------------------------------+
  |  Artefacto IDL (JSON, git/npm/en cadena) |  <- contrato versionado
  +------------------------------------------+
  |  anchor build (macros + compilación sBPF)|
  +------------------------------------------+
  |  Código fuente del programa (crates Anchor 0.32.1) |
  +------------------------------------------+

Codegen significa "no inventes bytes a mano". Fuera de cadena, eso suele ser TypeScript: ya sea el Program de @coral-xyz/anchor (común con anchor test y muchas dApps existentes) o Codama generando codecs de instrucciones y decodificadores de cuentas nativos de @solana/kit 7.0.0 para pilas de kit nuevas. En cadena entre programas, declare_program! incrusta un IDL de llamante en tiempo de compilación y genera estructuras de cuenta CPI y ayudantes de invocación para que tu programa falle al compilar cuando la ruta o forma del IDL sea incorrecta, en lugar de fallar solo después de una CPI incorrecta en cadena.

Versionado es cómo mantienes honestos a esos consumidores a través de los despliegues. Los IDLs en cadena (anchor idl init / upgrade / fetch) colocan una copia de la interfaz en una cuenta propiedad del programa para su descubrimiento; los sistemas de producción aún fijan un hash de IDL de confianza o una etiqueta de lanzamiento para que una autoridad de actualización comprometida no pueda redefinir silenciosamente la API para clientes automatizados.

El kit fuera de cadena (este sitio: @solana/kit 7.0.0) se sitúa en la capa del cliente para RPC y ensamblaje de transacciones. No reemplaza el IDL; Codama es el puente habitual desde el IDL de Anchor hacia los tipos de kit. Las fijaciones de plataforma para el lado del programa siguen siendo Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1 y Rust 1.91.1.

Mecánicas e Interacciones

Build produce el contrato

anchor build ejecuta la ruta de compilación sBPF y regenera el IDL a partir de las macros actuales. El archivo autoritativo es lo que la compilación acaba de escribir bajo target/idl/<program>.json (los equipos a menudo copian un artefacto revisado a idl/ para git). Editar manualmente ese JSON para "arreglar" un cliente casi siempre causa una deriva silenciosa: el programa todavía codifica el layout definido por la macro, mientras que los clientes codifican ficción.

  programs/foo/src/lib.rs  --macros-->  anchor build
                                            |
                    +-----------------------+-----------------------+
                    v                       v                       v
              target/deploy/foo.so    target/idl/foo.json    target/types/...
                    |                       |
                    v                       +--> declare_program! / Codama / TS
              solana program deploy

El IDL de Anchor detalla el layout de los campos. La regla del blueprint es: regenerar, revisar, fijar; nunca inventar.

declare_program! es codegen CPI en tiempo de compilación

Cuando el programa A debe hacer CPI al programa B de Anchor, A puede incluir el IDL de B y usar declare_program!(b). La macro genera módulos para comprobaciones de tipos del programa, constructores de instrucciones y ayudantes cpi que rellenan listas AccountMeta de manera consistente con el IDL de B.

Esa ruta es estática: un IDL incorrecto o faltante falla la compilación. La seguridad en tiempo de ejecución todavía depende de que B desplegado coincida con el IDL contra el que compilaste (mismos discriminadores de instrucción y expectativas de cuenta). Fija el IDL del llamante a un SHA de git o lanzamiento que coincida con el hash del programa desplegado. Detalles: declare_program!.

Dos historias de TypeScript, un IDL

Ambas rutas principales de TS comienzan desde el mismo JSON:

1. Cliente TS de Anchor carga el IDL en new Program(idl, provider) y expone program.methods.<ix>(...).accounts(...).rpc(). Encaja bien para pruebas de Anchor y muchas dApps existentes. Ver Generación de Clientes TS.
2. Codama lee el IDL de Anchor y emite módulos orientados a kit (obtener instrucciones, codecs, mapas de errores). Encaja bien cuando la aplicación se estandariza en los constructores de mensajes de transacción de @solana/kit 7.0.0. Ver Codama desde un IDL de Anchor.

                 JSON IDL de Anchor
                        |
          +-------------+-------------+
          v                           v
   @coral-xyz/anchor            CLI Codama
   Program.methods.*            codecs de kit generados
          |                           |
          v                           v
   dApps legacy / test          dApps kit-first

No mezcles el ensamblaje de transacciones de kit con objetos de instrucción de web3.js sin una capa de puente deliberada. Elige un tiempo de ejecución de cliente por aplicación y regenera cuando cambien los IDL.

El versionado es ingeniería de lanzamientos

Trata cada lanzamiento de programa como un paquete: hash .so, JSON IDL, paquete npm opcional o etiqueta git, y registro de cambios de modificaciones que afectan al IDL. La CI debería fallar si anchor build produce un IDL que difiere del artefacto confirmado sin una revisión explícita.

Los bytes de version de cuenta y las instrucciones de migración viven en el diseño del programa; el IDL aún debe describir el layout en vivo que los clientes decodifican. Práctica completa: Versionado de IDL.

El IDL en cadena es descubrimiento, no confianza única

anchor idl init crea una cuenta IDL en cadena para un ID de programa; upgrade la actualiza después de cambios de API; fetch extrae JSON para exploradores y clientes oportunistas. Eso es excelente para la descubrimiento. No es una historia completa de cadena de suministro por sí sola: cualquiera que controle la autoridad del IDL puede publicar una interfaz engañosa.

  Pipeline de lanzamiento confiable         Descubrimiento en cadena
  ---------------------------------         ----------------------
  etiqueta git + hash IDL  ----fijar---->      anchor idl fetch (verificación opcional)
  solana-verify / hash programa           exploradores, billeteras, demos
  npm @org/program-idl@x.y.z              aún comparar con hash fijado

Usa el IDL en cadena para el arranque y las herramientas; fija artefactos verificados para bots de producción, CPI y UIs de alto valor. Detalles: IDLs en Cadena.

Un día de trabajo en toda la tubería

1. Edita instrucciones del programa y estructuras de cuenta bajo Anchor 0.32.1; compila con Agave/CLI y Rust fijados.
2. Revisa la diferencia de target/idl; confirma el artefacto si es la fuente de verdad del equipo.
3. Actualiza los consumidores de declare_program! y recompila los programas CPI.
4. Regenera los tipos TS de Anchor o los clientes kit de Codama; falla la CI en árboles generados sucios.
5. Al desplegar, actualiza el IDL en cadena si publicas uno; etiqueta el lanzamiento con el hash del programa + versión del IDL.
6. Los integradores actualizan su paquete IDL o fijación git y redespliegan clientes.

Consideraciones Avanzadas y Aplicaciones

Los equipos no necesitan todos los consumidores desde el primer día. Empareja la superficie de integración y el riesgo con un camino, luego agrega canales cuando aparezcan terceros o clientes multi-runtime.

Espacios de trabajo multi-programa: un archivo IDL por crate de programa; nunca fusiones superficies en un solo JSON. Los bordes CPI declaran qué versión de IDL usa cada fijación de llamante.

Indexadores y análisis también analizan con discriminadores y layouts de IDL; un IDL obsoleto en el indexador es la misma clase de error que un cliente de dApp obsoleto, solo que más silencioso hasta que las métricas fallan.

Llamantes nativos o Pinocchio pueden carecer de un IDL de Anchor completo. Prefiere un IDL mantenido manualmente compatible, Codama desde una descripción personalizada, o metadatos CPI manuales; no asumas que declare_program! inventa una superficie completa.

Para revisiones de diseño, responde primero: quién posee el artefacto IDL, cómo la CI detecta la deriva, en qué runtime TS te estandarizas, qué llamantes se fijan para CPI, y si el IDL en cadena es descubrimiento de marketing o un feed de producción controlado por la autoridad.

Conceptos Erróneos Comunes

• "El IDL es documentación opcional." Para los ecosistemas de Anchor, es el contrato máquina para clientes, macros CPI y muchos indexadores; trátalo como un producto de API.
• "Puedo editar manualmente el IDL para que coincida con mi frontend." El frontend y la codificación en cadena divergirán; regenera solo desde las macros.
• "declare_program! rastrea mainnet automáticamente." Incrusta cualquier IDL contra el que compiles; fija a la versión del programa desplegada.
• "Anchor TS y Codama son intercambiables." Ambos leen IDL, pero apuntan a diferentes pilas de clientes; elige una ruta de transacción.
• "Publicar IDL en cadena reemplaza las compilaciones verificables." El descubrimiento no es atestación de bytecode; empareja con la verificación del hash del programa cuando la confianza importa.
• "Cualquier cambio en el IDL no es rompedor si el programa se actualiza." El reordenamiento de layouts y errores rompe clientes antiguos, incluso cuando la actualización tiene éxito.
• "Las cuentas restantes aparecerán en el IDL." Las listas de cuentas dinámicas a menudo necesitan documentación separada y construcción cuidadosa del cliente.
• "La versión del paquete npm por sí sola es suficiente." Fija el ID del programa, el clúster y el hash del contenido del IDL (o SHA del commit) para que una republicación no pueda intercambiar layouts silenciosamente.

Preguntas Frecuentes

Relacionado

• El IDL de Anchor - qué contiene el JSON y cómo las macros lo producen
• declare_program! - clientes CPI en tiempo de compilación desde IDL de llamante
• Generación de Clientes TS - Program de TypeScript de Anchor y tipado
• Codama desde un IDL de Anchor - codegen nativo de kit desde IDL
• Versionado de IDL - fijaciones de lanzamiento, cambios rompedores, migraciones
• IDLs en Cadena - publicar, actualizar y obtener cuentas IDL

Versiones de la pila: 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.