Codama

Gere clientes @solana/kit 7.0.0 a partir de IDLs Anchor 0.32.1.

Receita

npm install -D @codama/cli @codama/nodes-from-anchor @codama/renderers-js

{
  "idl": "target/idl/my_program.json",
  "scripts": { "js": "@codama/renderers-js" }
}

Quando usar:

Qualquer programa Anchor precisando de clientes frontend tipados.
Compartilhar instruction builders entre web e rotas API.
Eliminar discriminators mantidos manualmente.

Exemplo Prático

anchor build
npx codama run --config codama.json

import { createSolanaRpc } from "@solana/kit";
import { fetchCounter, getIncrementInstruction } from "./generated/clients/js";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
const account = await fetchCounter(rpc, counterAddress);
const ix = getIncrementInstruction({ counter: counterAddress, authority: signer });

O que isso demonstra:

Helpers fetch* combinam RPC + decoder.
get*Instruction retorna instruções nativas do kit.
Pasta de output segura para commit com checagens de drift em CI.

Aprofundamento

Como funciona

Codama parseia IDL em grafo AST de nós.
Renderers emitem TypeScript ajustado aos codecs @solana/kit.
Funciona com IDL Anchor; IDLs Shank nativos suportados com schema compatível.
Atualize renderer ao fazer bump major do kit.

Erros comuns

Esqueceu anchor build - input IDL obsoleto. Correção: etapa codegen depende do artefato de build.
Skew renderer/kit - erros de tipo. Correção: fixe versões compatíveis na documentação.
Edições manuais em pasta gerada - apagadas no regen. Correção: estenda só via wrappers.
Contas ausentes no builder - simulação falha. Correção: confie nos account metas gerados.
IDL commitado do cluster errado - program id errado. Correção: config por ambiente.

Alternativas

Alternativa	Use quando	Não use quando
anchor-client-gen (legacy)	Repos antigos	Pipeline Codama novo
Codecs escritos à mão	One-off pequeno	Apps Anchor em produção

FAQs

IDL Anchor 0.32.1?

Rode anchor build; aponte Codama para JSON em target/idl.

Quando regenerar?

Toda mudança de interface on-chain em CI.

Clientes tipados kit?

Codama renderiza funções nativas @solana/kit.

gill obrigatório?

Açúcar opcional sobre kit.

Next.js?

Importe clientes gerados em client components para escritas.

Testes?

Surfpool + testes de integração devnet.

web3.js?

Não misture com clientes kit gerados.

Múltiplos programas?

Uma config Codama por programa ou workspace monorepo.

Fetch de conta?

Use decoders gerados com getAccountInfo.

Erros?

Mapeie códigos de erro do programa a partir de metadados IDL.

Relacionados

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.

Receita

npm install -D @codama/cli @codama/nodes-from-anchor @codama/renderers-js

{
  "idl": "target/idl/my_program.json",
  "scripts": { "js": "@codama/renderers-js" }
}

Quando usar:

Qualquer programa Anchor precisando de clientes frontend tipados.
Compartilhar instruction builders entre web e rotas API.
Eliminar discriminators mantidos manualmente.

Exemplo Prático

anchor build
npx codama run --config codama.json

import { createSolanaRpc } from "@solana/kit";
import { fetchCounter, getIncrementInstruction } from "./generated/clients/js";
 
const rpc = createSolanaRpc(process.env.RPC_URL!);
const account = await fetchCounter(rpc, counterAddress);
const ix = getIncrementInstruction({ counter: counterAddress, authority: signer });

O que isso demonstra:

Helpers fetch* combinam RPC + decoder.
get*Instruction retorna instruções nativas do kit.
Pasta de output segura para commit com checagens de drift em CI.

Aprofundamento

Como funciona

Codama parseia IDL em grafo AST de nós.
Renderers emitem TypeScript ajustado aos codecs @solana/kit.
Funciona com IDL Anchor; IDLs Shank nativos suportados com schema compatível.
Atualize renderer ao fazer bump major do kit.

Erros comuns

Esqueceu anchor build - input IDL obsoleto. Correção: etapa codegen depende do artefato de build.
Skew renderer/kit - erros de tipo. Correção: fixe versões compatíveis na documentação.
Edições manuais em pasta gerada - apagadas no regen. Correção: estenda só via wrappers.
Contas ausentes no builder - simulação falha. Correção: confie nos account metas gerados.
IDL commitado do cluster errado - program id errado. Correção: config por ambiente.

Alternativas

Alternativa	Use quando	Não use quando
anchor-client-gen (legacy)	Repos antigos	Pipeline Codama novo
Codecs escritos à mão	One-off pequeno	Apps Anchor em produção

FAQs

IDL Anchor 0.32.1?

Rode anchor build; aponte Codama para JSON em target/idl.

Quando regenerar?

Toda mudança de interface on-chain em CI.

Clientes tipados kit?

Codama renderiza funções nativas @solana/kit.

gill obrigatório?

Açúcar opcional sobre kit.

Next.js?

Importe clientes gerados em client components para escritas.

Testes?

Surfpool + testes de integração devnet.

web3.js?

Não misture com clientes kit gerados.

Múltiplos programas?

Uma config Codama por programa ou workspace monorepo.

Fetch de conta?

Use decoders gerados com getAccountInfo.

Erros?

Mapeie códigos de erro do programa a partir de metadados IDL.

Relacionados

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.

Codama

Buscar na documentação

Codama