A IDL do Anchor

A IDL (Interface Description Language) do Anchor é uma descrição JSON das instruções, contas, tipos, eventos e erros do seu programa. O comando anchor build a regenera a partir de macros Rust.

Receita

anchor build
ls target/idl/my_program.json

{
  "address": "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
  "instructions": [ { "name": "initialize", "accounts": [], "args": [] } ],
  "errors": [],
  "events": []
}

Quando usar isso: Você integra clientes, consumidores de CPI (Cross-Program Invocation) ou publica metadados on-chain.

Exemplo de Trabalho

// Macros Rust controlam o conteúdo da 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 }

Após a compilação, a IDL inclui todas as instruções públicas, tipos de conta, eventos e erros.

O que isso demonstra:

• O campo address da IDL corresponde ao declare_id!
• A lista de instruções inclui nomes de contas e mutabilidade
• A seção types espelha as structs #[account]
• Os erros incluem código e mensagem (msg)

Mergulho Profundo

Consumidores de IDL

• Clientes TypeScript (@coral-xyz/anchor, Codama)
• Geração de CPI com declare_program!
• Publicação de documentação e SDKs

Versionamento

Marque o JSON da IDL com a versão do programa. Mudanças que quebram o layout da conta exigem atualizações nos clientes.

Armadilhas Comuns

• Editar a IDL manualmente - Desvia da verdade on-chain. Correção: Regenerar apenas via build.
• Não publicar atualizações da IDL - Clientes quebram silenciosamente. Correção: Verificar diff da IDL em PRs com CI.
• Instruções privadas - Apenas handlers públicos aparecem na IDL. Correção: Manter helpers privados.
• Campos Rust renomeados sem migração - Ordem das contas do cliente quebra. Correção: Versionar instruções.
• IDL ausente no pacote npm - Integradores adivinham layouts. Correção: Incluir artefato da IDL.

Alternativas

FAQs

Relacionados

• declare_program! - consumir IDL em Rust
• Gerando Clientes TS - TS
• IDLs On-Chain - publicar

Versões das Ferramentas: Esta página foi 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, e LiteSVM 0.6.x.