IDL & Codegen Blueprint

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.

A IDL do Anchor é a entrada prática; declare_program!, Gerando Clientes TS, Codama a partir de uma IDL do Anchor, Versionamento de IDL e IDLs On-Chain cada um se aprofunda em um estágio. Esta página fica abaixo: como as peças se conectam, o que você fixa e qual caminho seguir da primeira compilação para produção multi-cliente.

Resumo

• 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.

Fundamentos

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:

  +------------------------------------------+
  |  Integradores (dApps, bots, exploradores) |  <- chamadas tipadas, descoberta
  +------------------------------------------+
  |  Consumidores de Codegen                 |
  |    declare_program! (CPI Rust)           |
  |    Anchor TS Program / Codama + kit      |
  +------------------------------------------+
  |  Artefato IDL (JSON, git/npm/on-chain)   |  <- contrato versionado
  +------------------------------------------+
  |  anchor build (macros + compilação sBPF) |
  +------------------------------------------+
  |  Código-fonte do Programa (crates Anchor 0.32.1) |
  +------------------------------------------+

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.

Mecânicas e Interações

Build produz o contrato

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.

declare_program! é codegen de CPI em tempo de compilação

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!.

Duas histórias TypeScript, uma IDL

Ambos os principais caminhos TS começam com o mesmo JSON:

1. 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.
2. 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.

Versionamento é engenharia de lançamento

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.

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.

IDL On-Chain é descoberta, não confiança única

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.

Um dia de trabalho em todo o pipeline

1. Edite instruções do programa e structs de conta sob Anchor 0.32.1; compile com Agave/CLI e Rust fixados.
2. Revise a diferença em target/idl; comite o artefato se ele for a fonte da verdade da equipe.
3. Atualize consumidores declare_program! e recompila programas CPI.
4. Regenere tipos Anchor TS ou clientes Codama kit; falhe a CI em árvores geradas sujas.
5. No deploy, atualize a IDL on-chain se você publicar uma; marque o lançamento com o hash do programa + versão da IDL.
6. Integradores atualizam seu pacote IDL ou pin git e reimplantam clientes.

Considerações Avançadas e Aplicações

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.

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.

Concepções Errôneas Comuns

• "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.

FAQs

Relacionados

• A IDL do Anchor - o que o JSON contém e como as macros o produzem
• declare_program! - clientes CPI em tempo de compilação a partir da IDL da chamada
• Gerando Clientes TS - Program TypeScript do Anchor e tipagem
• Codama a partir de uma IDL do Anchor - codegen nativo do kit a partir da IDL
• Versionamento de IDL - pins de lançamento, mudanças que quebram, migrações
• IDLs On-Chain - publicar, atualizar e buscar contas IDL

Versões da Pilha: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, e @solana/kit 7.0.0.