> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Programas e Anchor

> Como os programas Solana são implantados e atualizados, o que o framework Anchor adiciona sobre o modelo nativo de Solana, e como ler o IDL da Raydium para gerar seus próprios clientes.

<Info>
  **Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.**

  [Ver versão em inglês →](/solana-fundamentals/programs-and-anchor)
</Info>

<Info>
  Os programas mais recentes da Raydium (CPMM, CLMM, Farm v6, LaunchLab) são escritos em **Anchor** — um framework Rust que expande o modelo de programa nativo do Solana para fornecer validação de conta, tratamento de erros e um IDL (interface description). AMM v4 e farms antigas precedem o Anchor. Compreender ambos os paradigmas ajuda você a ler o código, gerar clientes a partir do IDL e depurar erros inesperados.
</Info>

## Modelo de implantação de programas

Todo programa Solana reside em uma `Pubkey`. O bytecode do programa é armazenado em uma conta **executável** pertencente ao **BPF Upgradable Loader** (`BPFLoaderUpgradeab1e11111111111111111111111`).

Uma implantação de programa compreende três contas:

1. **Conta de programa**: pequena conta de metadados no ID do programa. Proprietário: BPF Upgradable Loader.
2. **Conta ProgramData**: contém o bytecode real. Derivada como `[program_id, "programdata"]`.
3. **Conta Buffer** (transitória): contém novo bytecode durante uma atualização. Descartada após a atualização.

A conta ProgramData tem uma **autoridade de atualização** — uma chave que pode substituir o bytecode por uma nova versão. A autoridade de atualização da Raydium é um multisig com um timelock de 24 horas; veja [`security/admin-and-multisig`](/pt/security/admin-and-multisig).

### Verificando um programa implantado

Para confirmar que o que está na chain corresponde ao que foi aprovado na auditoria:

```bash theme={null}
# Extrair o programa da mainnet
solana program dump CPMMoo8L3F4NbTegBCKVNunggL7H1Zpdmwpwh8KMoZ0F cpmm-onchain.so

# Construir a partir de uma fonte conhecida
cargo build-bpf --manifest-path raydium-cp-swap/programs/cp-amm/Cargo.toml
cp target/deploy/raydium_cp_swap.so cpmm-source.so

# Comparar
sha256sum cpmm-onchain.so cpmm-source.so
```

Hashes correspondentes provam que você está interagindo com a fonte que pensa estar. A Raydium publica instruções de verificação de build nas notas de lançamento.

## Anchor: um framework sobre Solana

Programas Solana brutos são funções Rust com esta assinatura:

```rust theme={null}
pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    // Analisar manualmente instruction_data
    // Validar contas manualmente
    // Desserializar dados de conta manualmente
    // Verificar manualmente flags de assinante/escrita
    // ... então fazer o trabalho real
}
```

Anchor envolve todo o código repetitivo e permite você escrever:

```rust theme={null}
#[program]
pub mod cpmm {
    use super::*;

    pub fn swap_base_input(
        ctx: Context<Swap>,
        amount_in: u64,
        min_out: u64,
    ) -> Result<()> {
        // Apenas a lógica de negócios — ctx é pré-validado
    }
}

#[derive(Accounts)]
pub struct Swap<'info> {
    pub payer: Signer<'info>,
    #[account(mut, seeds = [b"pool", config.key().as_ref(), ...], bump)]
    pub pool_state: AccountLoader<'info, PoolState>,
    #[account(mut)]
    pub input_vault: Box<Account<'info, TokenAccount>>,
    // ... mais contas
}
```

Anchor:

* Gera automaticamente um **discriminador** determinístico de 8 bytes para cada instrução e tipo de conta.
* Valida restrições de conta (proprietário, seeds, escrita, assinante, compatibilidade de mint, compatibilidade de programa de token) antes do seu código ser executado.
* Gera um **IDL** — um arquivo de descrição de interface que clientes usam para chamar o programa.
* Vem com uma biblioteca de cliente Rust, TypeScript e Python.

### O discriminador de 8 bytes

Toda conta Anchor e toda instrução Anchor começam com um discriminador de 8 bytes — os primeiros 8 bytes do SHA-256 de uma string fixa:

```
Discriminador de conta:     sha256("account:PoolState")[0..8]
Discriminador de instrução: sha256("global:swap_base_input")[0..8]
```

Quando você chama uma instrução Anchor, os primeiros 8 bytes dos dados da instrução são este discriminador; Anchor distribui para o handler correto procurando-os.

Quando você lê uma conta Anchor, os primeiros 8 bytes informam seu tipo — crucial para ferramentas como `getProgramAccounts` que enumeram todas as contas de um tipo.

### Erros

Programas Anchor definem erros via `#[error_code]`:

```rust theme={null}
#[error_code]
pub enum ErrorCode {
    #[msg("Slippage tolerance exceeded")]
    SlippageExceeded,
    #[msg("Pool is disabled")]
    PoolDisabled,
    // ...
}
```

Anchor atribui automaticamente esses códigos numéricos começando a partir de 6000 (0x1770). A tabela completa de códigos de erro da Raydium está em [`reference/error-codes`](/pt/reference/error-codes).

## O IDL

Um arquivo **IDL** (Interface Description Language) do Anchor é uma descrição JSON de um programa: suas instruções, contas, tipos, erros e eventos. É o equivalente de um ABI Ethereum.

A Raydium publica IDLs para todos os programas Anchor. Busque ao vivo da chain:

```bash theme={null}
anchor idl fetch CPMMoo8L3F4NbTegBCKVNunggL7H1Zpdmwpwh8KMoZ0F -o cpmm.idl.json
```

Ou da fonte do SDK: `src/raydium/*/idl/*.json`.

### Estrutura do IDL

```json theme={null}
{
  "version":      "0.1.0",
  "name":         "raydium_cp_swap",
  "instructions": [ { "name": "swap_base_input", "accounts": [ ... ], "args": [ ... ] }, ... ],
  "accounts":     [ { "name": "PoolState", "type": { ... } }, ... ],
  "types":        [ { "name": "AmmConfig", "type": { ... } }, ... ],
  "errors":       [ { "code": 6000, "name": "SlippageExceeded", "msg": "..." }, ... ],
  "events":       [ { "name": "SwapEvent", "fields": [ ... ] }, ... ]
}
```

### Gerando um cliente a partir do IDL

A CLI `anchor` do Anchor gera tipos TypeScript e Rust:

```bash theme={null}
anchor idl build -o target/idl/cpmm.json
# Tipos TypeScript auto-gerados pelo ts-client do Anchor
# O SDK da Raydium já inclui estes
```

Ferramentas de terceiros como [Kinobi](https://github.com/metaplex-foundation/kinobi) podem gerar clientes Rust, Python, C ou Go a partir de um IDL.

### Quando o IDL é seu amigo

Se você quer construir uma integração customizada que não passa pelo SDK Raydium:

1. Busque o IDL (ao vivo da chain ou da fonte do SDK).
2. Procure a instrução que deseja (ex., `swap_base_input`).
3. Construa os dados da instrução: discriminador de 8 bytes + args codificados.
4. Passe contas na ordem que o IDL especifica.

Veja [`sdk-api/anchor-idl`](/pt/sdk-api/anchor-idl) para exemplos elaborados.

## Programas pré-Anchor: AMM v4 e Farm v3/v5

Estes programas precedem Anchor. Eles usam:

* **Dispatch de instrução manual**: uma tag `u8` em `instruction_data` com uma declaração `match`.
* **Validação de conta manual**: `if accounts[0].owner != &expected_program { ... }`.
* **Args de instrução serializados por Borsh**: sem discriminador, apenas `instruction_data[1..]`.
* **Layout via `#[repr(C, packed)]`**: layout de struct C binário.

O SDK v2 da Raydium fornece layouts TypeScript para as instruções AMM v4 não-Anchor para que clientes possam codificar/decodificar sem Anchor:

```ts theme={null}
import { liquidityStateV4Layout, swapInstructionData }
  from "@raydium-io/raydium-sdk-v2";

const data = swapInstructionData.encode({
  instruction: 9,   // swap
  amountIn:    1_000_000n,
  minAmountOut: 950_000n,
});
```

O padrão de integração é o mesmo — você apenas não obtém a auto-geração orientada por IDL do Anchor.

## Mecânica de atualização de programas

Apenas a `upgrade_authority` da ProgramData pode atualizar. Passos:

1. Compilar o novo bytecode.
2. Escrevê-lo em uma conta buffer (`solana program write-buffer`).
3. Enviar uma instrução de atualização: `BpfLoaderUpgradeable::Upgrade { buffer, program, authority }`.
4. O runtime substitui atomicamente o bytecode do programa pelo conteúdo do buffer.

A Raydium gerea isso atrás de um **timelock de 24 horas** implementado nas configurações do multisig Squads. Uma transação de atualização deve aguardar 24 horas após a aprovação do multisig antes da execução. Isso protege contra atualizações apressadas / coagidas.

Veja [`security/admin-and-multisig`](/pt/security/admin-and-multisig).

### Tornando um programa imutável

Uma autoridade de atualização pode ser definida como `None`, ponto em que o programa se torna permanentemente imutável. A Raydium não fez isso para nenhum produto — a equipe retém a capacidade de enviar correções de segurança. Trade-off: usuários devem confiar no processo multisig + timelock.

## Programas e aluguel

Implantar um programa consome lamports isentos de aluguel:

* Um programa de 50 KB: \~0,35 SOL em aluguel.
* Um programa de 200 KB: \~1,4 SOL em aluguel.

Fechar um programa (via `solana program close`) retorna os lamports. Os programas Raydium permanecem ativos e não estão agendados para encerramento.

## Depurando programas Anchor

### Saída de log

A macro `msg!` do Anchor escreve no log da transação. Simule uma transação para ver logs:

```ts theme={null}
const sim = await connection.simulateTransaction(tx);
console.log(sim.value.logs);
```

Logs incluem:

* Invocação de programa (`Program CPMMoo8... invoke [1]`).
* Chamadas `msg!` do código do programa.
* Consumo de unidade de computação (`consumed 137842 of 400000 compute units`).
* Sucesso ou erro do programa.

### Códigos de erro

Se um programa Anchor lança, o log mostra:

```
Program CPMMoo8... failed: custom program error: 0x1770
```

0x1770 = 6000 decimal = o primeiro erro Anchor (ex., `SlippageExceeded`). Consulte cruzadamente com o array `errors` do IDL.

Veja [`reference/error-codes`](/pt/reference/error-codes) para a tabela completa de erros da Raydium.

### Incompatibilidades de layout de conta

Se você passar a conta errada no slot errado, as macros de validação de conta do Anchor retornam erros como:

```
AnchorError: AccountNotInitialized. Error Number: 3012
```

Números de erro abaixo de 6000 são erros embutidos do Anchor (veja o enum `ErrorCode` do Anchor); erros ≥6000 são códigos customizados do programa.

## Referências

* [`solana-fundamentals/account-model`](/pt/solana-fundamentals/account-model) — como programas possuem contas.
* [`solana-fundamentals/pdas-and-cpis`](/pt/solana-fundamentals/pdas-and-cpis) — PDAs conforme Anchor declara.
* [`sdk-api/anchor-idl`](/pt/sdk-api/anchor-idl) — buscando e usando IDLs da Raydium.
* [`reference/program-addresses`](/pt/reference/program-addresses) — IDs de programas.
* [`reference/error-codes`](/pt/reference/error-codes) — referência de códigos de erro.
* [`security/admin-and-multisig`](/pt/security/admin-and-multisig) — controles de autoridade de atualização.

Fontes:

* [Livro Anchor](https://book.anchor-lang.com).
* [Implantação de programa Solana](https://docs.solana.com/cli/deploy-a-program).
* IDLs Raydium (publicados em SDK `src/raydium/*/idl/*.json`).