La IDL de Anchor
La IDL de Anchor es una descripción JSON de las instrucciones, cuentas, tipos, eventos y errores de tu programa. anchor build la regenera a partir de macros de Rust.
Receta
anchor build
ls target/idl/my_program.json{
"address": "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
"instructions": [ { "name": "initialize", "accounts": [], "args": [] } ],
"errors": [],
"events": []
}Cuándo usar esto: Cuando integras clientes, consumidores de CPI o publicas metadatos en la cadena.
Ejemplo de Trabajo
// Las macros de Rust controlan el contenido de la IDL
#[program]
pub mod my_program { /* ... */ }
#[account]
pub struct Config { pub admin: Pubkey }
#[event]
pub struct ConfigUpdated { pub admin: Pubkey }
#[error_code]
pub enum MyError { #[msg("Unauthorized")] Unauthorized }Después de la compilación, la IDL incluye todas las instrucciones públicas, tipos de cuenta, eventos y errores.
Lo que esto demuestra:
- El campo
addressde la IDL coincide condeclare_id! - La lista de instrucciones incluye nombres de cuenta y mutabilidad
- La sección
typesrefleja las estructuras#[account] - Los errores incluyen código y mensaje (
msg)
Profundización
Consumidores de IDL
- Clientes TypeScript (@coral-xyz/anchor, Codama)
- Generación de CPI con
declare_program! - Publicación de documentación y SDK
Versionado
Etiqueta la IDL JSON con la versión del programa. Los cambios que rompen el diseño de la cuenta requieren actualizaciones del cliente.
Errores Comunes
- Edición manual de la IDL: Se desvía de la verdad en la cadena. Solución: Regenerar solo a través de
build. - No publicar actualizaciones de la IDL: Los clientes fallan silenciosamente. Solución: Comprobar en CI la diferencia de la IDL en los PR.
- Instrucciones privadas: Solo los manejadores públicos aparecen en la IDL. Solución: Mantener las funciones auxiliares privadas.
- Campos de Rust renombrados sin migración: El orden de las cuentas del cliente se rompe. Solución: Versionar las instrucciones.
- IDL ausente del paquete npm: Los integradores adivinan los diseños. Solución: Incluir el artefacto IDL.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Cuenta IDL en cadena | Descubrible en cadena | IDL solo en repositorio |
| Transformación de IDL Codama | Salida nativa del kit | Solo IDL de Anchor sin procesar |
Preguntas Frecuentes
¿Versión de Anchor?
0.32.1 en temas avanzados.
¿Cuándo usar `zero_copy`?
Diseños grandes y fijos cuando el costo de Borsh (CU) es demasiado alto.
¿Es reversible `realloc`?
No fácilmente; planifica el crecimiento futuro.
¿Están las cuentas restantes en la IDL?
No; documentar por separado.
¿Qué necesita `declare_program!`?
La IDL JSON del llamado en tiempo de compilación.
¿Puede Anchor hacer CPI a Pinocchio?
Sí, con las metadatos de cuenta correctas.
¿Banderas de características y la IDL?
Evita diferentes IDL por característica en mainnet.
¿Cómo medir el CU?
LiteSVM, Surfpool, simulación en devnet.
¿Son comunes los tipos de cuenta personalizados?
No; último recurso.
¿Próximos pasos?
Ver enlaces relacionados para idl.
Relacionados
- declare_program! - consumir IDL en Rust
- Generación de Clientes TS - TS
- IDLs en Cadena - publicar
Versiones de Stack: 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.