Infraestrutura compartilhada

​

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 fronteiam todos os quatro programas. Os integradores interagem com um host HTTP e um pacote NPM independentemente de qual programa 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 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á substituição de administrador.

​

2. Contas de administrador e configuração

// 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],
}

• Os níveis de taxa são globais. Quando um pool diz “este é um pool de 0,25%”, significa que se vincula ao AmmConfig cuja trade_fee_rate era 0,25% no momento da criação. Não há substituição de taxa por pool.
• Uma configuração pode ser alterada, mas os pools não a seguem. Se a autoridade de configuração editar um AmmConfig, cada pool existente vinculado a essa configuração pega a nova taxa imediatamente. Isso é um recurso, não um bug; é assim que as mudanças econômicas no nível do protocolo se propagam sem migrações por pool.
• disable_create_pool é a alavanca de descontinuação. Quando um nível de taxa é descontinuado, o multisig do protocolo define esse sinalizador — os 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 taxas. Defini-los como um multisig é o que controla a retirada de taxas. 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 a quantidade 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 de token por LP implícito.
2. As porções de protocolo/fundo/criador são deduzidas dessa acumulação 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 a instrução de coleta correspondente. 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. Os caminhos de protocolo e fundo exigem o signatário protocol_owner / fund_owner respectivo do AmmConfig. As taxas de criador CPMM usam o caminho CollectCreatorFee assinado pelo criador ou CollectCreatorFeePermissionless, que qualquer pagador pode disparar, mas que fixa os destinos aos ATAs canônicos do criador.

• Os percentuais de divisão são da taxa de negociação, não da negociação. Uma taxa de negociação de 0,25% com uma participação de protocolo de 12% significa que o protocolo obtém 0,25% × 12% = 0,03% da negociação — não 12% da negociação.
• As taxas de criador existem apenas em pools graduados do LaunchLab. Os 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 em Initialize e imutável.
• AMM v4 divide apenas de duas maneiras, codificado 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 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]). Os consumidores escolhem duas observações entre a janela desejada e dividem.
• O próprio Raydium não usa o TWAP para precificação. A matemática AMM lê as reservas de spot diretamente. As 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; os integradores que desejam 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 visão indexada principalmente de leitura de todo o estado on-chain mais um mecanismo 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 Rust / Python downstream 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 LP — tudo isso é trabalho de indexador. Os próprios programas não fazem isso.
• O tempo de inatividade do indexador é o tempo de inatividade da API. Se a API retorna dados desatualizados ou vazios, o indexador é o suspeito. O estado on-chain não é afetado; integradores com seu próprio RPC e SDK podem continuar transacionando.

​

O que não é compartilhado

• Os 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/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 estaca é de um pool CPMM, um mint 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. A precificação é reservas on-chain. Não há fallback Pyth/Switchboard; o AMM não verifica um oráculo antes de limpar.

​

Ponteiros

• 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 inline acima.