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
addressda IDL corresponde aodeclare_id! - A lista de instruções inclui nomes de contas e mutabilidade
- A seção
typesespelha 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
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Conta de IDL On-chain | Descoberta on-chain | IDL apenas no repositório |
| Transformação de IDL Codama | Saída nativa do Kit | Apenas IDL Anchor bruta |
FAQs
Versão do Anchor?
0.32.1 para tópicos avançados.
Quando usar `zero_copy`?
Layouts grandes e fixos quando o custo de computação (CU) do Borsh é muito alto.
O `realloc` é reversível?
Não facilmente; planeje o crescimento futuro.
As contas restantes (`remaining accounts`) estão na IDL?
Não; documente separadamente.
O `declare_program!` precisa de quê?
JSON da IDL do chamador em tempo de compilação.
O Anchor pode fazer CPI para o Pinocchio?
Sim, com metadados de conta corretos.
Flags de recursos e IDL?
Evite IDLs diferentes para cada recurso na mainnet.
Como medir o CU?
LiteSVM, Surfpool, simulação em devnet.
Tipos de conta personalizados são comuns?
Não; último recurso.
Próximos passos?
Veja os links relacionados para idl.
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.