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-js

Exemplos 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 gill

import { 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.