Cuentas de Farm / Staking

FarmState, UserStake / Ledger, bóvedas de recompensas y PDAs de autoridad — esquemas y semillas PDA para farm v3, v5 y v6.

Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.

Ver versión en inglés →

Tres programas, tres esquemas. Farm v3, v5 y v6 son programas separados con esquemas de estado distintos. Esta página documenta cada uno lado a lado. En la práctica, la mayoría de integraciones nuevas apuntan a v6; v3 y v5 son de solo lectura para la mayoría de integradores (el staking ya ocurrió hace mucho tiempo y los pools están en fase de liquidación).

​

Inventario de cuentas (por farm, cualquier versión)

Cuenta	Propietario	Propósito
FarmState	Programa Farm (v3/v5/v6)	Estado raíz: mint de staking, total apostado, flujos de recompensas.
farm_authority	Programa Farm	PDA que posee la bóveda de staking y las bóvedas de recompensas.
staking_vault	SPL Token	Contiene LP apostado (o el mint de staking que sea).
reward_vault_{i}	SPL Token	Contiene el presupuesto no distribuido para el flujo de recompensas i. Uno por flujo.
UserStake (v3/v5) / UserLedger (v6)	Programa Farm	Libro mayor por (farm, usuario): cantidad apostada + snapshot de recompensa-por-share por flujo.

El SDK devuelve el conjunto completo en raydium.farm.getFarmById. Para farms de terceros arbitrarios, el endpoint de API GET https://api-v3.raydium.io/main/farms/info?ids=<FARM_ID> también los devuelve.

​

Esquema FarmState — v6

v6 es la versión actual. Su estructura de cuenta es la más general.

// programs/farm_v6/src/state/farm.rs (abreviado)
pub struct FarmState {
    pub state: u64,                // bitfield: 0 = activo, 1 = pausado, ...
    pub nonce: u64,                 // bump para farm_authority
    pub creator: Pubkey,            // creador original (puede añadir recompensas / transferir admin)
    pub staking_mint: Pubkey,
    pub staking_vault: Pubkey,
    pub staking_token_program: Pubkey, // SPL Token o Token-2022
    pub lp_mint_decimals: u8,
    pub reward_period_len: u64,     // duración mínima entre ediciones de SetRewards
    pub reward_period_min: u64,
    pub total_staked: u64,
    pub reward_info_count: u8,
    pub _reserved: [u8; ...],
    pub reward_infos: [RewardInfo; 5], // hasta 5 flujos de recompensas
}

pub struct RewardInfo {
    pub reward_state: u8,           // 0 = no usado, 1 = ejecutándose, 2 = finalizado
    pub open_time: u64,             // tiempo_inicio
    pub end_time: u64,
    pub last_update_time: u64,
    pub emission_per_second_x64: u128, // tasa en punto fijo Q64.64
    pub reward_total_emissioned: u64,   // suma de emisiones hasta ahora
    pub reward_claimed: u64,            // suma pagada a los apostadores
    pub reward_vault: Pubkey,
    pub reward_mint: Pubkey,
    pub reward_sender: Pubkey,          // quién depositó el presupuesto; puede reabastecer
    pub reward_token_program: Pubkey,   // SPL o Token-2022
    pub reward_per_share_x64: u128,     // contador Q64.64
}

Campos relevantes para integradores:

• staking_mint, staking_vault — qué se apuesta y dónde se guarda.
• total_staked — total actual. Necesario para calcular APR: reward_per_second × 86400 / total_staked.
• reward_infos[i].emission_per_second_x64 — la tasa Q64.64. Divide entre 2^64 para obtener el conteo verdadero de tokens por segundo.
• reward_infos[i].open_time / end_time — para pantallas de UI “X días restantes”.
• reward_infos[i].reward_per_share_x64 — el contador del que UserLedger descuenta.

​

Esquema FarmState — v5

pub struct FarmStateV5 {
    pub state: u64,
    pub nonce: u64,
    pub lp_vault: Pubkey,            // aka staking_vault
    pub reward_vaults: [Pubkey; 2],
    pub owner: Pubkey,
    pub reward_mints: [Pubkey; 2],
    pub reward_total_emissioned: [u64; 2],
    pub reward_claimed: [u64; 2],
    pub reward_per_second: [u64; 2],  // entero, no punto fijo
    pub reward_open_time: [u64; 2],
    pub reward_end_time: [u64; 2],
    pub reward_per_share: [u128; 2],  // Q56.8 o similar; verifica la fuente del programa
    pub total_staked: u64,
    pub last_slot: u64,               // v5 se actualiza por slot en mainnet
    pub _reserved: [u8; 256],
}

Diferencias respecto a v6:

• Por slot, no por segundo. El bucle de actualización de v5 se ejecuta por slots en lugar de en reloj de pared. El SDK normaliza esto a “por segundo” para la UI pero en cadena la unidad es slots.
• Tasa de emisión entera. reward_per_second es u64. Esto limita la tasa expresable mínima a 1 unidad por segundo, lo que es demasiado grueso para flujos de baja emisión en mints de 9 decimales. v6 lo arregló con la tasa Q64.64.
• Sin reward_sender. En v5 el propietario es el remitente implícito; solo owner puede reabastecer.

​

Esquema FarmState — v3

pub struct FarmStateV3 {
    pub state: u64,
    pub nonce: u64,
    pub lp_vault: Pubkey,
    pub reward_vault: Pubkey,          // recompensa única
    pub owner: Pubkey,
    pub reward_mint: Pubkey,
    pub reward_total_emissioned: u64,
    pub reward_claimed: u64,
    pub reward_per_slot: u64,
    pub reward_per_share: u128,
    pub total_staked: u64,
    pub last_slot: u64,
    pub _reserved: [u8; 256],
}

Recompensa única. Basado en slots. La generación de programa más antigua, mantenida viva para los farms RAY-USDC y SOL-USDC que preceden a v5.

​

UserLedger (v6) / UserStake (v5/v3)

Estado por usuario, una cuenta por par (farm, usuario). PDA derivada:

// v6
const [ledgerPda] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer(), user.toBuffer(), Buffer.from("user_stake_info_v2")],
  FARM_V6_PROGRAM_ID,
);

// v5
const [stakePda] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer(), user.toBuffer(), Buffer.from("user_stake_info")],
  FARM_V5_PROGRAM_ID,
);

// v3
const [stakePda] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer(), user.toBuffer(), Buffer.from("staker_info")],
  FARM_V3_PROGRAM_ID,
);

(Las cadenas de semilla son los valores usados realmente por el SDK; las versiones de programa las han variado históricamente. Verifica contra la fuente v6 para cualquier cosa crítica en seguridad.)

// v6
pub struct UserLedger {
    pub version: u64,
    pub farm_id: Pubkey,
    pub owner: Pubkey,
    pub deposited: u64,                          // stake actual
    pub reward_debts: [u128; 5],                 // snapshot de reward_per_share_x64 × deposited
}

El descuento por flujo es el desplazamiento de contabilidad descrito en la descripción general:

pending_for_stream_i = deposited × reward_per_share_x64[i] / 2^64  − reward_debts[i]

Después de cada Deposit, Withdraw o Harvest, el descuento se reinicia a deposited × reward_per_share_x64[i] / 2^64 actual.

​

PDAs de autoridad

// v6
const [farmAuthorityV6] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer()],
  FARM_V6_PROGRAM_ID,
);

// v5
const [farmAuthorityV5] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer()],
  FARM_V5_PROGRAM_ID,
);

// v3
const [farmAuthorityV3] = PublicKey.findProgramAddressSync(
  [farmId.toBuffer()],
  FARM_V3_PROGRAM_ID,
);

Las tres versiones derivan la autoridad del farm por farm con una única semilla. Este PDA es la autoridad sobre la bóveda de staking y sobre cada bóveda de recompensas. Firma cada transferencia que realiza el farm.

​

Bóvedas

Las bóvedas de staking y recompensas son cuentas SPL Token estándar cuyo owner es el PDA de autoridad del farm. Las direcciones se almacenan en FarmState — no las re-derives; léelas del estado. Las autoridades de congelación deben estar deshabilitadas en el mint de staking para v5/v6 (el programa lo verifica).

Notas sobre Token-2022:

• v3: Solo SPL Token.
• v5: Solo SPL Token.
• v6: Compatible con Token-2022 en mints de staking y recompensas, controlado por campos staking_token_program / reward_token_program. Las comisiones de transferencia en mints de recompensas Token-2022 se cobran en emisión (bóveda → usuario).

​

Observación y APR

Los farms no almacenan APR en cadena. Para calcular:

annualized_rewards_value_usd = reward_per_second × 86400 × 365 × reward_usd_price
tvl_usd                     = total_staked / 10^decimals × staking_mint_usd_price
apr                         = annualized_rewards_value_usd / tvl_usd

Los consumidores típicamente extraen staking_mint_usd_price del pool al que pertenece el LP (vía api-v3.raydium.io/pools/info/ids) y reward_usd_price de cualquier oráculo de precios.

​

Qué hacer a continuación

• products/farm-staking/instructions — referencia de instrucciones por versión.
• products/farm-staking/code-demos — staking, harvesting y creación de farms vía el SDK.
• reference/program-addresses — todos los tres IDs de programa.

Fuentes:

• Módulo Farm del SDK v2 de Raydium
• La fuente del programa Farm v6 no se publica actualmente como repo independiente; el IDL está incluido en el SDK en raydium-io/raydium-sdk-V2 bajo src/raydium/farm/.