Estrutura do Projeto

Um workspace Anchor separa programas on-chain, testes de cliente e configuração de implantação. Saber onde cada artefato reside evita desvios na IDL e scripts de implantação quebrados.

Receita

my_workspace/
  Anchor.toml          # cluster, scripts, IDs de programa
  Cargo.toml           # raiz do workspace
  programs/
    my_program/
      Cargo.toml       # anchor-lang = "0.32.1"
      src/lib.rs
  tests/
    my_program.ts
  target/
    deploy/            # .so após a compilação
    idl/               # IDL JSON

Quando usar isso: Você está se integrando a um repositório existente ou dividindo um programa em múltiplos crates.

Exemplo de Trabalho

# Anchor.toml (trecho)
[toolchain]
anchor_version = "0.32.1"
 
[programs.localnet]
my_program = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"
 
[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

# Cargo.toml (raiz do workspace)
[workspace]
members = ["programs/*"]
resolver = "2"

O que isso demonstra:

Anchor.toml é a única fonte para IDs de programa por cluster
Cada programa é seu próprio crate em programs/
target/idl/ é gerado; não edite manualmente
Testes ficam fora do Rust para iteração mais rápida do cliente

Análise Profunda

Como Funciona

Membros do workspace - Cargo compila todos os crates programs/* com um lockfile compartilhado.
Crate do programa - Um único lib.rs com #[program], structs de conta e tipos de estado.
Saída da IDL - anchor build grava o JSON usado por clientes TS e declare_program!.
Runner de teste - A seção [scripts] conecta o teste do Anchor ao seu framework de teste TS.

Arquivos Chave

Caminho	Propósito
`programs/*/src/lib.rs`	Lógica on-chain
`Anchor.toml`	Alvos de implantação e scripts de teste
`target/idl/*.json`	Entrada para geração de código do cliente
`target/deploy/*.so`	Binário do programa atualizável

Armadilhas

Editar a IDL manualmente - Clientes compilam contra tipos desatualizados. Correção: Regenerar apenas com anchor build.
ID do programa apenas em lib.rs - A implantação usa uma chave diferente de declare_id!. Correção: Execute anchor keys sync após a implantação.
Testes na pasta errada - anchor test não consegue encontrá-los. Correção: Mantenha os testes em tests/ de acordo com a convenção do Anchor.
Membro do workspace ausente - Novo crate de programa não compilado. Correção: Adicione o caminho do crate aos membros do Cargo.toml raiz.
Versões misturadas do Anchor - A expansão de macro falha misteriosamente. Correção: Alinhe a CLI, anchor-lang e anchor-spl na versão 0.32.1.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Monorepo com múltiplos workspaces Anchor	Produtos independentes compartilhando infraestrutura	Programa único com layout simples
Workspace Cargo nativo sem Anchor.toml	Controle máximo, sem IDL	Você deseja clientes tipados e restrições
Layout Pinocchio/Steel	Programas críticos para CU	Você precisa das macros de conta do Anchor

FAQs

Qual versão do Anchor este site usa?

0.32.1 para anchor-lang, Anchor CLI e exemplos nesta seção.

Preciso do Solana CLI junto com o Anchor?

Sim. O Solana CLI 3.0.10 lida com keypairs, airdrops e inspeção de solana program.

Onde a IDL fica após a compilação?

target/idl/<program>.json no seu workspace.

Posso misturar UncheckedAccount com Signer?

Sim, mas cada campo não verificado precisa de restrições explícitas ou verificações no manipulador.

Como testar sem devnet?

Use anchor test com Surfpool 0.12.0 ou LiteSVM 0.6.x em CI.

Qual é o prefixo de 8 bytes nos dados da conta?

Discriminador de conta Anchor; não o remova ao dimensionar o space.

Devo commitar a IDL gerada?

Sim, ou publique a IDL on-chain para que os clientes tenham uma fonte canônica.

Como depurar falhas de restrição?

Execute com logs; o Anchor imprime o nome da restrição e o índice da conta.

O Anchor funciona no Agave 4.1.1?

Sim. Esta stack tem como alvo validadores Agave com Solana CLI 3.0.10.

O que devo ler a seguir nesta seção?

Veja artigos irmãos vinculados em Relacionados para tópicos mais aprofundados sobre estrutura de projeto.

Relacionados

Noções Básicas do Anchor - tour do primeiro programa
Compilando e Implantando - comandos de compilação e implantação
O Módulo #[program] - layout do manipulador

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.

Estrutura do Projeto

Um workspace Anchor separa programas on-chain, testes de cliente e configuração de implantação. Saber onde cada artefato reside evita desvios na IDL e scripts de implantação quebrados.

Receita

my_workspace/
  Anchor.toml          # cluster, scripts, IDs de programa
  Cargo.toml           # raiz do workspace
  programs/
    my_program/
      Cargo.toml       # anchor-lang = "0.32.1"
      src/lib.rs
  tests/
    my_program.ts
  target/
    deploy/            # .so após a compilação
    idl/               # IDL JSON

Quando usar isso: Você está se integrando a um repositório existente ou dividindo um programa em múltiplos crates.

Exemplo de Trabalho

# Anchor.toml (trecho)
[toolchain]
anchor_version = "0.32.1"
 
[programs.localnet]
my_program = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"
 
[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

# Cargo.toml (raiz do workspace)
[workspace]
members = ["programs/*"]
resolver = "2"

O que isso demonstra:

Anchor.toml é a única fonte para IDs de programa por cluster
Cada programa é seu próprio crate em programs/
target/idl/ é gerado; não edite manualmente
Testes ficam fora do Rust para iteração mais rápida do cliente

Análise Profunda

Como Funciona

Membros do workspace - Cargo compila todos os crates programs/* com um lockfile compartilhado.
Crate do programa - Um único lib.rs com #[program], structs de conta e tipos de estado.
Saída da IDL - anchor build grava o JSON usado por clientes TS e declare_program!.
Runner de teste - A seção [scripts] conecta o teste do Anchor ao seu framework de teste TS.

Arquivos Chave

Caminho	Propósito
`programs/*/src/lib.rs`	Lógica on-chain
`Anchor.toml`	Alvos de implantação e scripts de teste
`target/idl/*.json`	Entrada para geração de código do cliente
`target/deploy/*.so`	Binário do programa atualizável

Armadilhas

Editar a IDL manualmente - Clientes compilam contra tipos desatualizados. Correção: Regenerar apenas com anchor build.
ID do programa apenas em lib.rs - A implantação usa uma chave diferente de declare_id!. Correção: Execute anchor keys sync após a implantação.
Testes na pasta errada - anchor test não consegue encontrá-los. Correção: Mantenha os testes em tests/ de acordo com a convenção do Anchor.
Membro do workspace ausente - Novo crate de programa não compilado. Correção: Adicione o caminho do crate aos membros do Cargo.toml raiz.
Versões misturadas do Anchor - A expansão de macro falha misteriosamente. Correção: Alinhe a CLI, anchor-lang e anchor-spl na versão 0.32.1.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Monorepo com múltiplos workspaces Anchor	Produtos independentes compartilhando infraestrutura	Programa único com layout simples
Workspace Cargo nativo sem Anchor.toml	Controle máximo, sem IDL	Você deseja clientes tipados e restrições
Layout Pinocchio/Steel	Programas críticos para CU	Você precisa das macros de conta do Anchor

FAQs

Qual versão do Anchor este site usa?

0.32.1 para anchor-lang, Anchor CLI e exemplos nesta seção.

Preciso do Solana CLI junto com o Anchor?

Sim. O Solana CLI 3.0.10 lida com keypairs, airdrops e inspeção de solana program.

Onde a IDL fica após a compilação?

target/idl/<program>.json no seu workspace.

Posso misturar UncheckedAccount com Signer?

Sim, mas cada campo não verificado precisa de restrições explícitas ou verificações no manipulador.

Como testar sem devnet?

Use anchor test com Surfpool 0.12.0 ou LiteSVM 0.6.x em CI.

Qual é o prefixo de 8 bytes nos dados da conta?

Discriminador de conta Anchor; não o remova ao dimensionar o space.

Devo commitar a IDL gerada?

Sim, ou publique a IDL on-chain para que os clientes tenham uma fonte canônica.

Como depurar falhas de restrição?

Execute com logs; o Anchor imprime o nome da restrição e o índice da conta.

O Anchor funciona no Agave 4.1.1?

Sim. Esta stack tem como alvo validadores Agave com Solana CLI 3.0.10.

O que devo ler a seguir nesta seção?

Veja artigos irmãos vinculados em Relacionados para tópicos mais aprofundados sobre estrutura de projeto.

Relacionados

Noções Básicas do Anchor - tour do primeiro programa
Compilando e Implantando - comandos de compilação e implantação
O Módulo #[program] - layout do manipulador

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.

Estrutura do Projeto

Buscar na documentação

Estrutura do Projeto