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.
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.
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:
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.
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.
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!.
Ambas rutas principales de TS comienzan desde el mismo JSON:
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.
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.
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.
Cambio
Impacto típico en el cliente
Nueva instrucción
Aditivo; los clientes antiguos la ignoran
Campo de cuenta nuevo / layout más grande
Rompedor sin plan de migración
Reordenamiento de campos o cambio de tipo
Rompedor para decodificadores
Reordenamiento del enum de errores
Rompedor para mapas de códigos; solo añadir
Nuevo evento
Aditivo si los clientes no lo requieren
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.
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.
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.
Camino
Qué envías
Fortalezas
Debilidades
Mejor ajuste
Solo IDL del Repositorio
JSON confirmado en Git + compilación del programa
Simple; diferencias revisables
Sin descubrimiento en cadena
Monorepos de un solo equipo
IDL + TS de Anchor
Tipos npm o de monorepo para Program
Pruebas rápidas y dApps clásicas
Fricción de migración a Kit más tarde
Frontends de Anchor existentes
IDL + Codama + Kit
Codecs de Kit generados en CI
Pila Kit moderna; codecs explícitos
Paso adicional de codegen a fijar
dApps Kit Greenfield
IDL + declare_program!
JSON de llamante incluido en crates CPI
CPI tipada; comprobaciones en tiempo de compilación
Debe reconstruir en actualizaciones del llamante
Espacios de trabajo multi-programa
Paquete de lanzamiento completo
Hash, IDL, npm, actualización en cadena, registro de cambios
Listo para integradores; amigable para auditorías
Costo del proceso
Programas Mainnet con clientes externos
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.
"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.
Un artefacto IDL versionado es el contrato compartido; cada cliente tipado y ayudante CPI es un consumidor regenerado de ese contrato, no una ABI paralela escrita a mano.
¿Qué contiene el IDL de Anchor?
JSON para instrucciones públicas (cuentas y argumentos), tipos de cuenta y personalizados, eventos, errores y metadatos de dirección del programa derivados de macros en tiempo de compilación.
¿Cuándo se regenera el IDL?
En anchor build (y comandos relacionados de IDL de Anchor). Confirma y revisa las diferencias; no trates target/idl como ruido opcional.
¿Para qué sirve declare_program!?
Generación en tiempo de compilación de módulos Rust y ayudantes CPI a partir del IDL de otro programa para que tu programa pueda llamarlo con metadatos de cuenta tipados.
¿Necesito declare_program! para clientes fuera de cadena?
No. Las aplicaciones fuera de cadena usan Anchor TS u Codama (u otros enlaces de idioma). declare_program! es para CPI Rust en cadena en programas descritos por IDL.
¿Deberían las nuevas dApps usar Anchor TS o Codama?
Si te estandarizas en @solana/kit 7.0.0, prefiere los clientes generados por Codama. Si vives dentro de las pruebas clásicas de Anchor y las pilas web, el cliente Program de Anchor sigue siendo práctico.
¿Cómo se relaciona Codama con el IDL de Anchor?
Codama ingiere JSON IDL de Anchor y emite codecs y ayudantes de instrucciones orientados a kit; reconstruye cuando el IDL cambia y fija la versión de la CLI de Codama en CI.
¿Cómo deberíamos versionar los IDLs?
Envía el IDL con cada lanzamiento del programa, usa etiquetas semánticas o de lanzamiento, compara la CI con el JSON confirmado, códigos de error añadidos siempre que sea posible y documenta los cambios rompedores de layout con migraciones.
¿Es obligatorio el IDL en cadena?
No. Ayuda a los exploradores y al descubrimiento. Muchos clientes de producción usan fijaciones git o npm y solo verifican opcionalmente las recuperaciones en cadena.
¿Qué se rompe si el IDL y el programa divergen?
Discriminadores, orden de cuentas o layouts incorrectos causan fallos de simulación, errores personalizados crípticos, decodificaciones de cuenta corruptas o rechazo de CPI en el llamante.
¿Pueden participar programas que no son de Anchor?
Sí, si proporcionas un IDL correcto o codecs construidos manualmente. La generación automática de Anchor es el camino feliz; los programas nativos necesitan disciplina adicional.
¿Dónde encaja @solana/kit?
Kit es la pila moderna de RPC y transacciones de TypeScript (este sitio: 7.0.0). Codama une el IDL de Anchor a esa pila; kit no compila sBPF ni posee el formato IDL.
¿Qué debería forzar la CI?
Anchor/Agave/Rust fijados, artefacto IDL igual a la salida de compilación fresca, clientes regenerados limpios, y trabajos de lanzamiento que publiquen hash de programa y versión de IDL coincidentes.
¿Cómo interactúan las cuentas restantes con el codegen?
A menudo están fuera de las listas de cuentas IDL fijas. Documentalas, pásalas explícitamente en los clientes y nunca asumas que el codegen inventó el grafo completo de cuentas en tiempo de ejecución.