Infraestrutura compartilhada

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.

​

O que “compartilhado” significa aqui

• Compartilhamento de convenção. Todo programa usa o mesmo padrão de derivação de PDA, a mesma forma de divisão de taxas e a mesma ideia de conta de observação — mas cada um os implementa em seu próprio programa com suas próprias sementes.
• Compartilhamento de conta. Um punhado de contas são literalmente o mesmo registro em muitos pools (o PDA de autoridade global em CPMM, as contas AmmConfig).
• Compartilhamento off-chain. Uma API REST e um SDK TypeScript front todos os quatro programas. Integradores interagem com um host HTTP e um pacote NPM, independentemente de qual programa eles acabam chamando.

​

1. PDAs de autoridade

• Para CPMM e CLMM, o PDA de autoridade é uma conta global — cada pool desse tipo a usa. Se você está fazendo CPI em CPMM, você precisa dela uma vez, não por pool.
• Para autoridades por pool / por farm, você deriva o PDA a partir do ID do pool/farm. O SDK faz isso em getPoolKeys / getFarmKeys; se você está integrando diretamente, você deriva com findProgramAddressSync.
• A propriedade do cofre não pode ser alterada. Uma vez que uma conta de token é criada com o PDA de autoridade como proprietário, apenas esse PDA — invocado pelo programa — pode transferir para fora. Não há sobrescrita de administrador.

​

2. Contas de admin e config

// CPMM AmmConfig (abreviado — a versão CLMM é estruturalmente similar)
pub struct AmmConfig {
    pub bump: u8,
    pub disable_create_pool: bool,        // gate new pool creation in this tier
    pub index: u16,                       // tier index
    pub trade_fee_rate: u64,              // fraction of trade going to fees
    pub protocol_fee_rate: u64,           // fraction of trade fee to protocol
    pub fund_fee_rate: u64,               // fraction of trade fee to fund
    pub create_pool_fee: u64,             // one-time per-pool creation fee
    pub protocol_owner: Pubkey,           // signer for CollectProtocolFee
    pub fund_owner: Pubkey,               // signer for CollectFundFee
    pub padding: [u64; 16],
}

• Níveis de taxa são globais. Quando um pool diz “este é um pool de 0,25%”, significa que ele se liga ao AmmConfig cuja trade_fee_rate era 0,25% no momento da criação. Não há sobrescrita de taxa por pool.
• Uma config pode ser alterada mas pools não a acompanham. Se a autoridade de config editar um AmmConfig, cada pool existente ligado a essa config pega a nova taxa imediatamente. Isso é um recurso, não um bug; é assim que as mudanças econômicas de nível de protocolo se propagam sem migrações por pool.
• disable_create_pool é a alavanca de depreciação. Quando um nível de taxa é descontinuado, o multisig do protocolo define esse flag — pools existentes continuam funcionando mas nenhum novo pool pode escolher o nível.
• protocol_owner / fund_owner são os signatários para chamadas de coleta de taxa. Defini-los como um multisig é o que controla o saque de taxa. Eles NÃO são os endereços de destino das taxas em si; isso é protocol_fee_destination / fund_fee_destination na mesma conta.

​

3. A divisão de taxa de protocolo / fundo / criador

                         total swap fee
                              │
              ┌───────────────┼───────────────┬──────────────┐
              ▼               ▼               ▼              ▼
        LP pool side     Protocol         Fund         Creator
        (raises k)       treasury         multisig     (LaunchLab pools)

1. A taxa de negociação se acumula no pool. A taxa é removida do lado de entrada do swap e o valor pós-taxa é o que a matemática de produto constante vê. Isso é o que “o LP ganha a taxa” significa — k sobe e assim também o valor implícito de token por LP.
2. As porções de protocolo/fundo/criador são deduzidas desse acúmulo do lado LP em contas de contador por pool. Elas ficam no estado do pool (protocol_fees_token{0,1}, fund_fees_token{0,1}, etc.) até que alguém chame CollectProtocolFee / CollectFundFee / CollectCreatorFee. Elas não saem dos cofres do pool até então; da perspectiva de um swap elas ainda estão “no pool”.
3. A coleta as move para fora. O signatário respectivo (as chaves protocol_owner / fund_owner no AmmConfig, ou o criador de lançamento para pools LaunchLab) chama a instrução de coleta e o programa transfere do cofre do pool para um ATA de destino.

• Os percentuais de divisão são da taxa de negociação, não do negócio. Uma taxa de negociação de 0,25% com uma participação de protocolo de 12% significa que o protocolo recebe 0,25% × 12% = 0,03% do negócio — não 12% do negócio.
• Taxas de criador existem apenas em pools graduados do LaunchLab. Pools CPMM/CLMM padrão têm uma divisão de 3 vias (LP / protocolo / fundo). LaunchLab adiciona um quarto slot roteado para quem lançou o token, configurado no Initialize e imutável.
• AMM v4 divide de apenas duas maneiras, codificadas por pool: LP e protocolo. Sem slot de fundo, sem slot de criador.
• Fundo vs protocolo — ambos são destinos de tesouro do protocolo, mas têm signatários diferentes e usos pretendidos diferentes. protocol historicamente financia operações; fund é o tesouro de longo prazo. A divisão entre os dois é em si uma ajustável.

​

4. Contas de observação (buffer de anel TWAP)

// CPMM ObservationState (abreviado)
pub struct ObservationState {
    pub initialized: bool,
    pub observation_index: u16,            // next slot to overwrite
    pub pool_id: Pubkey,
    pub observations: [Observation; OBSERVATION_NUM],
    pub padding: [u64; 4],
}

pub struct Observation {
    pub block_timestamp: u64,
    pub cumulative_token_0_price_x32: u128,  // sum of (price × dt) since init
    pub cumulative_token_1_price_x32: u128,
}

• Cada swap chama update_observation. O programa lê o preço atual, multiplica pelos segundos decorridos desde a observação anterior e o adiciona ao contador cumulativo. A nova entrada sobrescreve o slot mais antigo (estilo buffer de anel).
• TWAP sobre uma janela = (cumul[end] − cumul[start]) / (timestamp[end] − timestamp[start]). Consumidores escolhem duas observações delimitando a janela desejada e dividem.
• O próprio Raydium não usa o TWAP para precificação. A matemática do AMM lê as reservas de spot diretamente. Observações são uma externalidade — Raydium paga o custo de escrevê-las para que outros contratos possam ler.
• AMM v4 não tem conta de observação. É mais antigo que o design ObservationState; integradores querendo um TWAP v4 têm que computar um off-chain do histórico de logs.

​

5. API REST + SDK + IDL

• API REST — https://api-v3.raydium.io. Uma visualização indexada principalmente de leitura de todo o estado on-chain mais um motor de cotação. Um host, um esquema.
• SDK TypeScript — @raydium-io/raydium-sdk-v2 no NPM. Constrói e assina transações para cada programa. Fala com a API para cotações/metadados, fala com um RPC Solana para atualizações de estado pré-assinatura.
• Registro IDL — IDLs Anchor para cada programa publicado vivem no repositório raydium-idl (um JSON por programa: CPMM, CLMM, LaunchLab). O SDK TypeScript consome esses IDLs internamente; clientes downstream Rust / Python regeneram dos mesmos arquivos.

​

6. Indexadores e feeds de preço

• O indexador é a única coisa que “sabe sobre” estado entre programas. Mapear um pool CPMM para seu equivalente CLMM, computar um número de volume de 24h entre versões de programa, pegar um farm associado a um mint de LP — tudo isso é trabalho de indexador. Os próprios programas não fazem isso.
• Tempo de inatividade do indexador é tempo de inatividade da API. Se a API retorna dados obsoletos ou vazios, o indexador é o suspeito. O estado on-chain é afetado; integradores com seu próprio RPC e SDK podem continuar transacionando.

​

O que não é compartilhado

• Programas não chamam uns aos outros. Um swap CPMM nunca faz CPI em CLMM ou AMM v4. O único programa que compõe múltiplos AMMs é o programa AMM Routing — e esse é em si fino, apenas emitindo CPIs em cada AMM em sequência.
• Nenhuma autoridade de atualização compartilhada entre programas. Cada programa on-chain tem sua própria chave de atualização de programa (um multisig 3 de 4 mais um timelock de 24h). Elas não estão vinculadas.
• Nenhum estado compartilhado entre farms e AMMs. Um farm não sabe qual LP que ele staked vem de um pool CPMM, um mint de NFT de posição CLMM ou um token SPL não relacionado. O programa farm trata o mint de staking como opaco.
• Nenhuma dependência de oráculo. Precificação é reservas on-chain. Não há fallback de Pyth/Switchboard; o AMM não verifica um oráculo antes de liquidar.

​

Apontadores

• protocol-overview/architecture — o diagrama canônico mostrando como essas peças se compõem.
• protocol-overview/versions-and-migration — como as convenções evoluíram entre versões de programa.
• security/admin-and-multisig — quem controla as chaves por trás dos AmmConfigs.
• reference/fee-comparison — matriz de taxa de taxa por produto.
• reference/program-addresses — IDs de programa canônicos.

• Raydium SDK v2 — a fonte da verdade para sementes de PDA, layouts de conta e definições de IDL.
• Registro IDL Raydium — IDLs Anchor.
• Páginas de contas por produto citadas acima.