Saltar para o conteúdo principal

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.

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

​
O que é um IDL

Programas Anchor na Solana publicam um arquivo IDL (Interface Definition Language) descrevendo suas instruções, layouts de contas, enumeração de erros e esquemas de structs. O IDL é a fonte de verdade para geração de código cliente — o SDK TS, crate CPI Rust e clientes de terceiros são todos gerados a partir dele (ou escritos manualmente contra ele). A Raydium publica IDLs para CPMM, CLMM e LaunchLab. AMM v4, Stable AMM e Farm (v3 / v5 / v6) são anteriores a Anchor ou não são distribuídos por Anchor — suas estruturas de contas são mantidas manualmente no SDK.

​
Onde encontrá-los

Os IDLs vivem em um repositório dedicado: 
https://github.com/raydium-io/raydium-idl
Os arquivos exatos:
ProgramaArquivo IDL
CPMMraydium_cpmm/raydium_cp_swap.json
CLMMraydium_clmm/raydium_clmm.json
LaunchLabraydium_launchpad/raydium_launchpad.json
AMM v4sem IDL oficial — veja raydium-sdk-V2/src/raydium/liquidity/layout.ts para layouts escritos manualmente
Stable AMMsem IDL oficial — layouts no SDK
Farmsem IDL oficial — layouts no SDK
Os arquivos IDL são versionados no histórico git do repositório; fixe em um commit específico se você precisar de reprodutibilidade byte-for-byte. Os IDLs também podem ser extraídos diretamente dos programas implantados através do recurso on-chain IDL do Anchor (se o publicador do programa optou por isso): 
anchor idl fetch <PROGRAM_ID> --provider.cluster mainnet
CPMM, CLMM e LaunchLab todos têm IDLs on-chain. AMM v4, Stable AMM e Farm não têm (programas anteriores a Anchor).

​
Regenerando um cliente TypeScript

A geração de código do Anchor produz um cliente digitado a partir do IDL: 
# Usando a CLI do anchor
anchor build
anchor idl parse \
  --file target/idl/cpmm.json \
  --out target/types/cpmm.ts

# Ou com os helpers TS do `@coral-xyz/anchor` em tempo de execução:

import { Program, AnchorProvider } from "@coral-xyz/anchor";
// Extraia o IDL diretamente do repositório raydium-idl (ou inclua-o no seu projeto).
import cpmmIdl from "./idls/raydium_cp_swap.json";

const provider = new AnchorProvider(connection, wallet, {});
const program  = new Program(cpmmIdl as any, CPMM_PROGRAM_ID, provider);

// Construtores de método digitados gerados automaticamente:
await program.methods
  .swapBaseInput(new BN(amountIn), new BN(minAmountOut))
  .accounts({ ... })
  .rpc();
A maioria dos integradores não faz isso — eles usam o helper de nível superior raydium.cpmm.swap(...) que envolve os métodos Anchor mais toda a contabilidade (criação de ATA, ajuste de taxa de transferência, budget de computação, roteamento de programa Token-2022). Regenere apenas quando você precisar de uma camada abaixo do SDK.

​
Regenerando um cliente Rust (crate CPI)

A Raydium publica crates Anchor para os programas que têm IDLs: 
# Cargo.toml
[dependencies]
raydium_cp_swap = { git = "https://github.com/raydium-io/raydium-cp-swap", branch = "master", features = ["cpi"] }
raydium_amm_v3 = { git = "https://github.com/raydium-io/raydium-clmm",    branch = "master", features = ["cpi"] }
O recurso cpi expõe structs de contas cpi::accounts::<Ix> e invocadores cpi::<ix>() — wrappers CPI prontos para usar. Veja sdk-api/rust-cpi para padrões de uso. Se você preferir gerar associações frescas: 
# A partir do IDL, usando anchor-client
anchor idl parse \
  --file raydium_cpmm/raydium_cp_swap.json \
  --out src/generated/cpmm_bindings.rs

​
Regenerando um cliente Python

Não há SDK Python oficial da Raydium. Geradores de terceiros incluem:
  • anchorpy — porta Python de @coral-xyz/anchor. Gera construtores de método digitados a partir de IDLs.
  • solders — primitivas Solana de baixo nível (transações, keypairs, pubkeys) em associações Rust; usado por baixo de anchorpy.
pip install anchorpy solders solana

from anchorpy import Program, Provider
from solana.rpc.async_api import AsyncClient
from pathlib import Path
import json

idl = json.loads(Path("cpmm.json").read_text())
provider = Provider(AsyncClient("https://api.mainnet-beta.solana.com"), wallet)
program  = Program(idl, CPMM_PROGRAM_ID, provider)

await program.rpc["swap_base_input"](amount_in, min_amount_out, ctx=Context(accounts={...}))
Veja sdk-api/python-integration para um guia mais completo.

​
Política de mudanças de IDL

A Raydium segue estas regras para estabilidade de IDL:
  1. Discriminadores de instrução nunca mudam. Adicionar novas instruções estende o enum no final; discriminadores existentes permanecem estáveis.
  2. Layouts de struct de conta evoluem apenas aditivamente. Novos campos vão no final, precedidos por um aumento de tamanho no esquema on-chain. Campos existentes mantêm seus offsets.
  3. Códigos de enumeração de erro são append-only. Um código de erro existente sempre significa a mesma coisa.
  4. Mudanças quebradas são enviadas em novos programas. Quando uma reformulação é necessária, o time implanta um novo ID de programa (por exemplo, CPMM como um programa novo em vez de atualizar AMM v4). Pools antigos continuam a rodar no programa antigo; pools novos vão para o novo.
Esta política torna clientes regenerados retrocompatíveis: um cliente gerado contra um IDL de duas versões atrás ainda decodificará o estado atual corretamente (ele vê bytes finais extras como preenchimento).

​
O que fazer quando o IDL muda

  1. Atualize o SDK. npm update @raydium-io/raydium-sdk-v2.
  2. Regenere seu código cliente se você usar a geração de código Anchor diretamente.
  3. Faça diff do layout da conta. Os campos finais do novo layout são a única coisa que seu código não viu; confirme se você precisa deles.
  4. Não assuma que discriminadores de instrução antigos são inválidos. De acordo com a regra 1, eles ainda funcionam.
  5. Re-execute testes de integração contra devnet antes de implantar em mainnet.

​
Solução de problemas de IDL

​
Erros “Invalid discriminator”

Geralmente significa que um cliente construído contra a versão N do IDL está tentando invocar uma instrução que existia apenas em uma versão anterior ao deploy do programa. Re-extraia o IDL do programa ativo: 
anchor idl fetch <PROGRAM_ID>

​
Falhas de decodificação de conta

Se program.account.<Name>.fetch(pubkey) lança um erro “Invalid account discriminator”, a conta foi criada por uma versão anterior do programa e o Anchor está rejeitando seu discriminador de 8 bytes. A solução é usar o analisador de layout bruto do SDK (PoolInfoLayout.decode(accountData)) que não força discriminadores Anchor.

​
Instruções ausentes no cliente gerado

A geração de código TS do Anchor só gera métodos para instruções cujas entradas IDL têm um name que funciona como um identificador válido. As instruções da Raydium todas satisfazem isso, mas se você vir uma discrepância, verifique se o arquivo IDL é da versão atual do SDK.

​
Referências

Fontes: