農場 / 質押帳户

本頁內容由 AI 自動翻譯，所有內容以英文版本為準。查看英文版 →

三個程序，三種協議。 農場 v3、v5 和 v6 是獨立的程序，擁有獨立的狀態佈局。本頁將各版本並排說明。實務上，大多數新的整合都以 v6 為目標；v3 和 v5 對大多數整合者來說是唯讀的（質押早已發生，這些池正處於退場階段）。

帳户清單（每個農場，任何版本）

帳户	所有者	用途
`FarmState`	農場程序 (v3/v5/v6)	根狀態：質押鑄幣、總質押、獎勵流。
`farm_authority`	農場程序	擁有質押金庫和獎勵金庫的 PDA。
`staking_vault`	SPL Token	持有質押的 LP（或質押鑄幣）。
`reward_vault_{i}`	SPL Token	持有獎勵流 `i` 未分配的預算。每個流一個。
`UserStake` (v3/v5) / `UserLedger` (v6)	農場程序	每個 `(farm, user)` 的帳簿：質押金額 + 每個流的獎勵占比快照。

SDK 在 raydium.farm.getFarmById 上返回完整集合。對於任意第三方農場，API 端點 GET https://api-v3.raydium.io/main/farms/info?ids=<FARM_ID> 也會返回這些帳户。

`FarmState` 佈局 — v6

v6 是當前版本，其帳户結構最通用。

// programs/farm_v6/src/state/farm.rs (abridged)
pub struct FarmState {
    pub state: u64,                // bitfield: 0 = live, 1 = paused, ...
    pub nonce: u64,                 // bump for farm_authority
    pub creator: Pubkey,            // original creator (can add rewards / transfer admin)
    pub staking_mint: Pubkey,
    pub staking_vault: Pubkey,
    pub staking_token_program: Pubkey, // SPL Token or Token-2022
    pub lp_mint_decimals: u8,
    pub reward_period_len: u64,     // minimum duration between SetRewards edits
    pub reward_period_min: u64,
    pub total_staked: u64,
    pub reward_info_count: u8,
    pub _reserved: [u8; ...],
    pub reward_infos: [RewardInfo; 5], // up to 5 reward streams
}

pub struct RewardInfo {
    pub reward_state: u8,           // 0 = unused, 1 = running, 2 = ended
    pub open_time: u64,             // start_time
    pub end_time: u64,
    pub last_update_time: u64,
    pub emission_per_second_x64: u128, // Q64.64 fixed-point rate
    pub reward_total_emissioned: u64,   // sum of emissions so far
    pub reward_claimed: u64,            // sum paid out to stakers
    pub reward_vault: Pubkey,
    pub reward_mint: Pubkey,
    pub reward_sender: Pubkey,          // who deposited the budget; can top up
    pub reward_token_program: Pubkey,   // SPL or Token-2022
    pub reward_per_share_x64: u128,     // Q64.64 counter
}

整合者相關欄位：

staking_mint、staking_vault — 什麼被質押以及它位於何處。
total_staked — 當前總額。計算 APR 所需：reward_per_second × 86400 / total_staked。
reward_infos[i].emission_per_second_x64 — Q64.64 速率。除以 2^64 得到真正的每秒代幣數。
reward_infos[i].open_time / end_time — 用於 UI 的「剩餘 X 天」顯示。
reward_infos[i].reward_per_share_x64 — UserLedger 扣款的計數器。

`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],  // integer, not fixed-point
    pub reward_open_time: [u64; 2],
    pub reward_end_time: [u64; 2],
    pub reward_per_share: [u128; 2],  // Q56.8 or similar; check program source
    pub total_staked: u64,
    pub last_slot: u64,               // v5 updates per-slot on mainnet
    pub _reserved: [u8; 256],
}

與 v6 的差異：

每個插槽，而非每秒。 v5 的更新循環按插槽而非牆上時鐘運行。SDK 為 UI 將其規範化為「每秒」，但鏈上單位是插槽。
整數發放速率。 reward_per_second 是 u64。這將最小可表達速率限制為每秒 1 個單位，對於 9 位小數鑄幣的低發放流來說太粗糙。v6 使用 Q64.64 速率解決了這個問題。
沒有 reward_sender。在 v5 上，所有者是隱含的發送方；只有 owner 可以充值。

`FarmState` 佈局 — v3

pub struct FarmStateV3 {
    pub state: u64,
    pub nonce: u64,
    pub lp_vault: Pubkey,
    pub reward_vault: Pubkey,          // single reward
    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],
}

單獎勵。基於插槽。最古老的程序版本，為先於 v5 的 RAY-USDC 和 SOL-USDC 農場而保留。

`UserLedger` (v6) / `UserStake` (v5/v3)

每個用戶狀態，每個 (farm, user) 對一個帳户。衍生 PDA：

// 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,
);

（種子字符串是 SDK 實際使用的值；程序版本在歷史上有所不同。如有任何安全相關的事項，請對照 v6 源代碼驗證。）

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

每個流的扣款是概覽中描述的帳務抵消：

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

在每個 Deposit、Withdraw 或 Harvest 後，扣款會重置為當前的 deposited × reward_per_share_x64[i] / 2^64。

授權 PDA

// 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,
);

所有三個版本都用單一種子為每個農場衍生農場授權。此 PDA 是質押金庫和每個獎勵金庫的授權。它簽署農場進行的每項轉帳。

金庫

質押和獎勵金庫是標準 SPL Token 帳户，其 owner 是農場授權 PDA。地址存儲在 FarmState 上 — 不要重新衍生；從狀態讀取。質押鑄幣上的凍結授權必須在 v5/v6 上禁用（程序會檢查）。 Token-2022 注意事項：

v3：僅 SPL Token。
v5：僅 SPL Token。
v6：在質押和獎勵鑄幣上都支持 Token-2022，由 staking_token_program / reward_token_program 欄位控制。Token-2022 獎勵鑄幣上的轉帳費在發放時收取（金庫 → 用戶）。

觀察和 APR

農場不在鏈上存儲 APR。計算方法：

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

消費者通常從 LP 所屬的池中拉取 staking_mint_usd_price（通過 api-v3.raydium.io/pools/info/ids）以及從任何價格預言機拉取 reward_usd_price。

下一步

products/farm-staking/instructions — 每個版本的指令參考。
products/farm-staking/code-demos — 通過 SDK 進行質押、收穫和創建農場。
reference/program-addresses — 所有三個程序 ID。

來源：

Raydium SDK v2 Farm 模塊
農場 v6 程序源代碼目前未作為獨立存儲庫發佈；IDL 捆綁在 raydium-io/raydium-sdk-V2 的 SDK 中的 src/raydium/farm/ 下。

產品

演算法

帳户清單（每個農場，任何版本）

`FarmState` 佈局 — v6

`FarmState` 佈局 — v5

`FarmState` 佈局 — v3

`UserLedger` (v6) / `UserStake` (v5/v3)

授權 PDA

金庫

觀察和 APR

下一步

​帳户清單（每個農場，任何版本）

​FarmState 佈局 — v6

​FarmState 佈局 — v5

​FarmState 佈局 — v3

​UserLedger (v6) / UserStake (v5/v3)

​授權 PDA

​金庫

​觀察和 APR

​下一步

帳户清單（每個農場，任何版本）

`FarmState` 佈局 — v6

`FarmState` 佈局 — v5

`FarmState` 佈局 — v3

`UserLedger` (v6) / `UserStake` (v5/v3)

授權 PDA

金庫

觀察和 APR

下一步