Typed Clients Basics
8 exemplos para clientes TypeScript orientados por IDL - 5 básicos e 3 intermediários.
Pré-requisitos
anchor build # Anchor 0.32.1
npm install @solana/kit@7.0.0
npm install -D @codama/cli @codama/renderers-jsExemplos Básicos
1. Por que gerar clientes?
IDL é o contrato entre Rust on-chain e TypeScript off-chain.
ls target/idl/my_program.json- Layouts escritos à mão desviam das structs Anchor 0.32.1.
- Codecs gerados correspondem exatamente aos discriminators.
- Uma fonte de verdade reduz incidentes na mainnet.
2. Anchor TS Client
A classe Program de @coral-xyz/anchor ainda funciona para apps legacy.
// Prefer Codama + kit for new modules- Cliente Anchor acopla historicamente a tipos web3.js.
- Migre chamadas de programa incrementalmente.
- Veja The Anchor TS Client.
3. Pipeline Codama
IDL → grafo de nós → renderer → cliente kit TypeScript.
npx codama run --config codama.json- Commit output gerado ou regenere em CI.
- Falhe CI quando pasta estiver dirty após build.
- Fixe versão @codama/cli por repo.
4. Buscar conta tipada
Decoders gerados parseiam dados de conta.
import { createSolanaRpc, address } from "@solana/kit";
// import { fetchMyAccount } from "./generated";
const rpc = createSolanaRpc(process.env.RPC_URL!);- Fetch + decode em um helper com output gill/Codama.
- Trate null quando conta não inicializada.
- Veja Fetching & Decoding Accounts.
5. Construir instrução tipada
Instruction builders codificam discriminator + args.
// getIncrementInstruction({ account, authority }) from generated client- Builders retornam tipo Instruction do kit.
- Acrescente à mensagem de transação com APIs kit.
- Account metas ordenadas conforme IDL.
Exemplos Intermediários
6. Conveniência gill
Helpers de nível superior agrupam kit + programas comuns.
npm install gillimport { createSolanaClient } from "gill";- Bootstrap mais rápido para fluxos padrão.
- Desça para kit em account metas incomuns.
- Veja gill.
7. Regeneração em CI
anchor build && npx codama run && git diff --exit-code clients/- Impede envio de clientes obsoletos.
- Combine com testes de integração Surfpool.
- Documente codegen em CONTRIBUTING.md.
8. Apps multi-programa
Monorepo pode hospedar vários IDLs.
{ "idl": "target/idl/program_a.json", "before": [], "scripts": { "js": "@codama/renderers-js" } }- Namespace pastas geradas por programa.
- Evite nomes de export duplicados entre programas.
- Veja Keeping Clients in Sync.
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.