Noções Básicas de Anchor

10 exemplos para você começar com Anchor no Solana - 7 básicos e 3 intermediários.

Pré-requisitos

• Rust 1.91.1 e Anchor CLI 0.32.1 (anchor --version)
• Solana CLI 3.0.10 (solana --version) com um keypair financiado para deploy
• anchor init my_program ou um workspace existente com Anchor.toml

Exemplos Básicos

1. Estruturar um workspace

Anchor cria programas, testes e configuração em uma única árvore.

anchor init counter --no-git
cd counter
cat programs/counter/Cargo.toml

• programs/ contém crates Rust on-chain
• tests/ contém testes de integração TypeScript
• Anchor.toml fixa o cluster, ID do programa e scripts
• Fixe anchor-lang = "0.32.1" em Cargo.toml

Relacionado: Estrutura do Projeto - layout de pastas

2. Declarar o ID do seu programa

O endereço do programa deve corresponder ao deploy on-chain.

use anchor_lang::prelude::*;
 
declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");
 
#[program]
pub mod counter {
    use super::*;
    pub fn initialize(_ctx: Context<Initialize>) -> Result<()> {
        Ok(())
    }
}

• declare_id! define a chave pública do programa
• Execute anchor keys sync após anchor deploy atualizar o ID
• Incompatibilidade causa DeclaredProgramIdMismatch em tempo de execução

Relacionado: O Módulo #[program]

3. Definir uma struct de contas

Anchor valida cada conta antes que seu manipulador seja executado.

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

• Signer prova que a conta assinou a transação
• Program<System> verifica o endereço do programa do sistema
• Restrições são executadas antes do corpo do manipulador

Relacionado: A Struct de Contas

4. Escrever um manipulador de instrução

Manipuladores recebem Context<T> com contas validadas.

pub fn increment(ctx: Context<Increment>) -> Result<()> {
    ctx.accounts.counter.count += 1;
    Ok(())
}

• Retorne Result<()> para instruções falíveis
• Modifique contas através dos campos ctx.accounts
• Use require! para verificações personalizadas dentro dos manipuladores

Relacionado: Manipuladores de Instrução

5. Construir e inspecionar a IDL

anchor build compila SBF e emite o JSON da IDL.

anchor build
cat target/idl/counter.json | head

• IDL lista instruções, contas e tipos para clientes
• IDL fica em target/idl/<program>.json
• Regenere após cada alteração na API pública

Relacionado: Construindo e Implantando

6. Executar testes locais

Testes TypeScript exercitam o programa em um validador local.

anchor test

• Inicia Surfpool/validador local, implanta, executa tests/*.ts
• Use clientes @coral-xyz/anchor ou @solana/kit nos testes
• Iteração rápida sem gastar SOL de devnet

Relacionado: O Fluxo de Trabalho do Anchor

7. Fixar dependências

Combine as versões da CLI e dos crates para evitar desvios de macro.

[dependencies]
anchor-lang = "0.32.1"
anchor-spl = "0.32.1"

• Mantenha anchor-lang e Anchor CLI na mesma versão menor
• Cargo.lock do workspace deve ser commitado
• Atualize a CLI e os crates juntos

Exemplos Intermediários

8. Inicializar uma conta com base em PDA

Endereços derivados do programa armazenam estado de propriedade do programa.

#[account(
    init,
    payer = payer,
    space = 8 + Counter::INIT_SPACE,
    seeds = [b"counter", payer.key().as_ref()],
    bump
)]
pub counter: Account<'info, Counter>,
pub payer: Signer<'info>,
pub system_program: Program<'info, System>,

• init cria a conta na mesma instrução
• seeds + bump derivam um PDA determinístico
• Sempre defina space para dimensionamento isento de aluguel

Relacionado: PDAs em Anchor

9. Emitir um evento

Eventos estruturados ajudam os indexadores a observar mudanças de estado.

#[event]
pub struct CountChanged {
    pub new_count: u64,
}
 
pub fn increment(ctx: Context<Increment>) -> Result<()> {
    ctx.accounts.counter.count += 1;
    emit!(CountChanged { new_count: ctx.accounts.counter.count });
    Ok(())
}

• #[event] registra um tipo na IDL
• emit! escreve uma entrada de log self-CPI
• Prefira eventos a msg! para saída legível por máquina

Relacionado: Eventos com emit!

10. Declarar erros personalizados

Erros tipados decodificam de forma limpa nos clientes.

#[error_code]
pub enum CounterError {
    #[msg("Count cannot exceed maximum")]
    CountOverflow,
}
 
require!(ctx.accounts.counter.count < 100, CounterError::CountOverflow);

• #[error_code] mapeia para códigos de erro Anchor na IDL
• require! é a macro de guarda idiomática
• Clientes mapeiam códigos de erro para mensagens humanas

Relacionado: #[error_code] & require!

Versões da Pilha: 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.