Typed Clients Best Practices
25 práticas para clientes Solana totalmente tipados e orientados por IDL.
//
Busque em todas as páginas da documentação
25 práticas para clientes Solana totalmente tipados e orientados por IDL.
Trate IDL como contrato de API: Toda mudança de conta e arg é review de breaking change (Typed Clients Basics).
Regenere em CI: Falhe quando clients/generated diferir após anchor build + Codama.
Fixe renderer Codama com kit 7.0.0: Majors de renderer acompanham layouts de codec.
Nunca edite arquivos gerados: Envolva extensões em módulos escritos à mão.
Commit IDL ou artefato verifiable build: Suporte deve reproduzir gen de cliente.
Namespace outputs multi-programa: Evite colisões de nome de export.
Use helpers fetch:* Combine RPC + decode para reduzir erros (Fetching & Decoding Accounts).
Simule lotes de instrução: Capture erros de constraint antes do modal da carteira.
Mapeie erros de programa: Exponha códigos de erro IDL na cópia da UI.
bigint para u64: Corresponda tipos Borsh on-chain em TypeScript.
Coordene deploy + frontend: Envie atualizações de cliente com upgrades de programa.
Program IDs por ambiente: devnet ≠ mainnet em arquivos .env.
Documente hash IDL em releases: Entrada de changelog por bump de interface.
Prefira Codama a codecs manuais: Custo de manutenção menor no longo prazo.
gill para bootstrap, kit para edge cases: Entenda ambas as camadas (gill).
Leituras server tipadas: Rotas Next.js importam decoders sem carteiras.
Escritas client tipadas: Carteira assina só instruções geradas.
Teste fixtures de decode: Snapshot bytes de conta em testes unitários.
Evite getProgramAccounts na UI mainnet: Use indexer ou RPC filtrado.
Alinhamento Anchor 0.32.1: IDL do crate anchor-lang correspondente.
Sem web3.js no caminho gerado: Modelo Address único via kit.
Lazy load IDLs grandes: Divida programas para reduzir bundle.
Envolva erros RPC: Traduza 429 e timeout para usuários.
Audite contas CPI no IDL: Clientes devem incluir remaining accounts quando necessário.
Eduque equipe nos comandos codegen: CONTRIBUTING.md lista passos exatos.
Mantenha legacy; código novo usa output kit Codama.
Sim com checagem de drift CI, ou regen só em CI se artefato IDL armazenado.
Codama suporta schemas JSON IDL compatíveis.
Versões da stack: 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.
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026