Typed Clients Best Practices
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/generateddiferir apósanchor 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.
FAQs
Ainda usar Anchor TS client?
Mantenha legacy; código novo usa output kit Codama.
Commit generated?
Sim com checagem de drift CI, ou regen só em CI se artefato IDL armazenado.
IDL nativo não-Anchor?
Codama suporta schemas JSON IDL compatíveis.
Relacionados
- Codama - ferramenta codegen
- @solana/kit Best Practices - camada RPC
- Generating TS Clients - fluxo
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.