A pilha de IDL e codegen da Solana é como a superfície pública de um programa se torna módulos Rust tipados de CPI, construtores de instruções TypeScript e interfaces descobertas para exploradores e integradores. Assim que você tratar a Interface Definition Language (IDL) como o contrato compartilhado e cada gerador de cliente como um consumidor desse contrato, as macros do Anchor, declare_program!, Codama, pacotes npm e contas IDL on-chain deixarão de parecer tribos de ferramentas separadas e começarão a parecer um único pipeline de macros para máquinas.
Uma IDL descreve a API pública de um programa (instruções, contas, tipos, eventos, erros, metadados de endereço do programa), e ferramentas de codegen regeneram clientes tipados e helpers de CPI a partir desse JSON para que humanos não codifiquem discriminadores e layouts manualmente.
Por que Importa: Sem uma única espinha dorsal de IDL, dApps, bots, chamadores de CPI e indexadores inventam layouts incompatíveis; com ela, você envia um artefato do anchor build e regenera cada consumidor quando a superfície do programa muda.
Conceitos Chave:JSON da IDL do Anchor, discriminadores e layouts Borsh, declare_program!, Programa TS do Anchor, Codama + @solana/kit, versionamento de IDL / tags de lançamento, contas IDL on-chain, verificações de desvio de CI.
Quando Usar: Integrando ou fazendo CPI em programas Anchor, criando clientes tipados, publicando SDKs, coordenando atualizações entre aplicativos, ou explicando por que "a IDL está desatualizada" quebra carteiras e CPI ao mesmo tempo.
Limitações / Trade-offs: A qualidade da IDL acompanha as macros e a configuração de compilação; contas remanescentes e alguns programas nativos precisam de documentação além da IDL; a IDL on-chain é descobrível, mas não substitui hashes de lançamento confiáveis; Codama e Anchor TS são runtimes diferentes, então escolha uma história de cliente por aplicativo.
Tópicos Relacionados: IDL do Anchor, declare_program, gerando clientes TS, Codama a partir da IDL do Anchor, versionamento de IDL, IDLs on-chain.
Programas Solana não expõem um "arquivo ABI" embutido como algumas ferramentas EVM fazem por padrão. Anchor preenche essa lacuna para programas de framework: atributos Rust (#[program], #[account], #[event], #[error_code], e metadados de restrição de conta) se expandem em código de validação e serialização, e anchor build emite uma IDL JSON em target/idl/ que espelha os manipuladores e tipos públicos.
Esse JSON é o contrato, não um dump "bom de ter". Nomes de instruções mapeiam para discriminadores de 8 bytes e codificações de argumentos. Listas de contas nomeiam papéis, mutabilidade e signatários. A seção de tipos espelha contas e structs personalizadas. Erros e eventos fornecem aos clientes códigos legíveis por humanos e formas de log. O campo address (quando presente) vincula o artefato a um ID de programa de declare_id!.
Pense na pilha como camadas de macros para integradores:
Codegen significa "não invente bytes manualmente". Fora da cadeia, isso geralmente é TypeScript: ou o Program do @coral-xyz/anchor (comum com anchor test e muitos dApps existentes) ou Codama gerando codecs de instrução e decodificadores de conta @solana/kit 7.0.0-nativos para pilhas kit greenfield. Na cadeia, entre programas, declare_program! incorpora uma IDL de chamada em tempo de compilação e gera structs de conta CPI e helpers de invocação para que seu programa falhe na compilação quando o caminho ou a forma da IDL estiverem errados, em vez de falhar apenas após uma CPI ruim on-chain.
Versionamento é como você mantém esses consumidores honestos entre os deploys. IDLs On-Chain (anchor idl init / upgrade / fetch) colocam uma cópia da interface em uma conta de propriedade do programa para descoberta; sistemas de produção ainda fixam um hash de IDL confiável ou tag de lançamento para que uma autoridade de upgrade comprometida não possa redefinir silenciosamente a API para clientes automatizados.
O kit fora da cadeia (este site: @solana/kit 7.0.0) fica na camada do cliente para RPC e montagem de transações. Ele não substitui a IDL; Codama é a ponte usual da IDL do Anchor para os tipos do kit. Os pins da plataforma para o lado do programa permanecem Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, e Rust 1.91.1.
anchor build executa o caminho de compilação sBPF e regenera a IDL a partir das macros atuais. O arquivo autoritativo é o que o build acabou de escrever em target/idl/<program>.json (equipes frequentemente copiam um artefato revisado para idl/ para o git). Editar manualmente esse JSON para "corrigir" um cliente quase sempre causa desvio silencioso: o programa ainda codifica o layout definido pela macro, enquanto os clientes codificam ficção.
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
A IDL do Anchor detalha o layout dos campos. A regra do blueprint é: regenerar, revisar, fixar; nunca inventar.
Quando o programa A precisa fazer CPI no programa Anchor B, A pode incluir a IDL de B e usar declare_program!(b). A macro gera módulos para verificação de tipos do programa, construtores de instruções e helpers de cpi que preenchem listas AccountMeta de forma consistente com a IDL de B.
Esse caminho é estático: IDL incorreta ou ausente falha a compilação. A segurança em tempo de execução ainda depende do B implantado corresponder à IDL com a qual você compilou (mesmos discriminadores de instrução e expectativas de conta). Fixe a IDL da chamada para um SHA de git ou lançamento que corresponda ao hash do programa implantado. Detalhes: declare_program!.
Ambos os principais caminhos TS começam com o mesmo JSON:
Cliente Anchor TS carrega a IDL em new Program(idl, provider) e expõe program.methods.<ix>(...).accounts(...).rpc(). Forte adequação para testes Anchor e pilhas já com dependências da era @coral-xyz/anchor + web3.js. Veja Gerando Clientes TS.
Codama lê a IDL do Anchor e emite módulos orientados ao kit (getters de instrução, codecs, mapas de erro). Forte adequação quando o aplicativo padroniza construtores de mensagens de transação @solana/kit 7.0.0. Veja Codama a partir de uma IDL do Anchor.
JSON da IDL do Anchor | +-------------+-------------+ v v @coral-xyz/anchor CLI Codama Program.methods.* codecs kit gerados | | v v dApps legados / de teste dApps kit-first
Não misture a montagem de transações do kit com objetos de instrução do web3.js sem uma camada de ponte deliberada. Escolha um runtime de cliente por aplicativo e regenere quando a IDL mudar.
Trate cada lançamento de programa como um pacote: hash do .so, JSON da IDL, pacote npm opcional ou tag git, e changelog de alterações voltadas para a IDL. A CI deve falhar se anchor build produzir uma IDL que difira do artefato commitado sem uma revisão explícita.
Mudança
Impacto típico no cliente
Nova instrução
Aditiva; clientes antigos a ignoram
Novo campo de conta / layout maior
Quebra sem plano de migração
Reordenação de campo ou mudança de tipo
Quebra para decodificadores
Reordenação do enum de erro
Quebra para mapas de código; apenas anexar
Novo evento
Aditivo se os clientes não o exigirem
Bytes de version da conta e instruções de migração vivem no design do programa; a IDL ainda deve descrever o layout ativo que os clientes decodificam. Prática completa: Versionamento de IDL.
anchor idl init cria uma conta IDL on-chain para um ID de programa; upgrade a atualiza após alterações de API; fetch puxa JSON para exploradores e clientes oportunistas. Isso é excelente para descoberta. Não é uma história completa de cadeia de suprimentos por si só: qualquer pessoa que controle a autoridade da IDL pode publicar uma interface enganosa.
Pipeline de lançamento confiável Descoberta na cadeia --------------------------------- ------------------- tag git + hash IDL ----fixar----> anchor idl fetch (verificação opcional) solana-verify / hash do programa exploradores, carteiras, demos npm @org/program-idl@x.y.z ainda comparar com hash fixado
Use IDL on-chain para bootstrap e ferramentas; fixe artefatos verificados para bots de produção, CPI e UIs de alto valor. Detalhes: IDLs On-Chain.
Equipes não precisam de todos os consumidores no primeiro dia. Combine a superfície de integração e o risco com um caminho, e então adicione canais quando terceiros ou clientes multi-runtime aparecerem.
Caminho
O que você envia
Pontos fortes
Pontos fracos
Melhor ajuste
Apenas IDL do Repositório
JSON commitado no Git + build do programa
Simples; diffs revisáveis
Sem descoberta on-chain
Monorepos de equipe única
IDL + Anchor TS
Tipos npm ou monorepo para Program
Testes rápidos e dApps clássicos
Atrito de migração para Kit posteriormente
Frontends Anchor existentes
IDL + Codama + kit
Codecs kit gerados em CI
Pilha Kit moderna; codecs explícitos
Etapa extra de codegen para fixar
dApps Kit Greenfield
IDL + declare_program!
JSON de chamada incluído em crates CPI
CPI tipada; verificações em tempo de compilação
Precisa reconstruir em atualizações de chamada
Espaços de trabalho multi-programa
Pacote de lançamento completo
Hash, IDL, npm, upgrade on-chain, changelog
Pronto para integrador; amigável para auditoria
Custo de processo
Programas Mainnet com clientes externos
Espaços de trabalho multi-programa: um arquivo IDL por crate de programa; nunca mescle superfícies em um único JSON. Bordas CPI declaram qual versão da IDL cada pin de chamada usa.
Indexadores e análises também analisam com discriminadores e layouts de IDL; uma IDL desatualizada no indexador é a mesma classe de bug que um cliente dApp desatualizado, apenas mais silencioso até que as métricas deem errado.
Chamadas nativas ou Pinocchio podem não ter uma IDL Anchor completa. Prefira uma IDL compatível mantida manualmente, Codama a partir de uma descrição personalizada, ou metadados CPI manuais; não assuma que declare_program! inventa uma superfície completa.
Para revisões de design, responda primeiro: quem é o proprietário do artefato IDL, como a CI detecta desvios, qual runtime TS você padroniza, quais chamadas são fixadas para CPI, e se a IDL on-chain é descoberta de marketing ou um feed de produção controlado pela autoridade.
"A IDL é documentação opcional." Para ecossistemas Anchor, é o contrato de máquina para clientes, macros CPI e muitos indexadores; trate-o como um produto de API.
"Posso editar manualmente a IDL para corresponder ao meu frontend." A codificação frontend e on-chain divergirão; regenere apenas a partir das macros.
"declare_program! rastreia o mainnet automaticamente." Ele incorpora a IDL com a qual você compila; fixe na versão do programa implantada.
"Anchor TS e Codama são substitutos intercambiáveis." Ambos leem IDL, mas visam pilhas de clientes diferentes; escolha um caminho de transação.
"Publicar IDL on-chain substitui compilações verificáveis." A descoberta não é atestação de bytecode; combine com a verificação do hash do programa quando a confiança for importante.
"Qualquer mudança na IDL é não-quebradora se o programa atualizar." A renumeração de layout e erros quebra clientes antigos, mesmo quando a atualização é bem-sucedida.
"Contas remanescentes aparecerão na IDL." Listas de contas dinâmicas geralmente precisam de documentação separada e construção cuidadosa do cliente.
"A versão do pacote npm sozinha é suficiente." Fixe o ID do programa, o cluster e o hash de conteúdo da IDL (ou SHA do commit) para que uma republicação não possa trocar layouts silenciosamente.
Um artefato IDL versionado é o contrato compartilhado; cada cliente tipado e helper de CPI é um consumidor regenerado desse contrato, não uma ABI paralela escrita à mão.
O que a IDL do Anchor contém?
JSON para instruções públicas (contas e argumentos), tipos de conta e personalizados, eventos, erros e metadados de endereço do programa derivados de macros em tempo de compilação.
Quando a IDL é regenerada?
Em anchor build (e comandos relacionados da IDL do Anchor). Comite e revise diffs; não trate target/idl como ruído opcional.
Para que serve declare_program!?
Geração em tempo de compilação de módulos Rust e helpers de CPI a partir da IDL de outro programa para que seu programa possa chamá-lo com metadados de conta tipados.
Preciso de declare_program! para clientes fora da cadeia?
Não. Aplicativos fora da cadeia usam Anchor TS ou Codama (ou outros bindings de linguagem). declare_program! é para CPI Rust on-chain em programas descritos por IDL.
Novos dApps devem usar Anchor TS ou Codama?
Se você padronizar em @solana/kit 7.0.0, prefira clientes gerados por Codama. Se você vive em testes clássicos do Anchor e pilhas web, o cliente Program do Anchor continua prático.
Como Codama se relaciona com a IDL do Anchor?
Codama ingere JSON da IDL do Anchor e emite codecs TypeScript e helpers de instrução orientados ao kit; reconstrua quando a IDL mudar e fixe a versão da CLI Codama na CI.
Como devemos versionar as IDLs?
Envie a IDL com cada lançamento do programa, use tags semânticas ou de lançamento, diff de CI do JSON commitado, códigos de erro apenas anexáveis quando possível, e documente mudanças de layout que quebram com migrações.
A IDL on-chain é obrigatória?
Não. Ela ajuda exploradores e descoberta. Muitos clientes de produção usam pins git ou npm e apenas opcionalmente verificam fetches on-chain.
O que quebra se a IDL e o programa divergirem?
Discriminadores incorretos, ordem de contas ou layouts causam falhas de simulação, erros personalizados crípticos, decodificação de contas corrompida ou rejeição de CPI no chamado.
Programas não-Anchor podem participar?
Sim, se você fornecer uma IDL correta ou codecs feitos à mão. A geração automática do Anchor é o caminho feliz; programas nativos precisam de disciplina extra.
Onde @solana/kit se encaixa?
Kit é a pilha moderna de RPC e transações TypeScript (este site: 7.0.0). Codama faz a ponte da IDL do Anchor para essa pilha; kit não compila sBPF nem possui o formato IDL.
O que a CI deve impor?
Anchor/Agave/Rust fixados, artefato IDL igual à saída de build fresca, clientes regenerados limpos, e jobs de lançamento que publicam hash de programa e versão de IDL correspondentes.
Como as contas remanescentes interagem com o codegen?
Elas geralmente estão fora das listas de contas fixas da IDL. Documente-as, passe-as explicitamente nos clientes e nunca assuma que o codegen inventou o grafo completo de contas em tempo de execução.