> ## 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.

# 農場 / 質押帳户

> FarmState、UserStake / Ledger、獎勵金庫與授權 PDA — 農場 v3、v5、v6 的布局和 PDA 種子。

<Info>
  **本頁內容由 AI 自動翻譯，所有內容以英文版本為準。**

  [查看英文版 →](/products/farm-staking/accounts)
</Info>

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

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

| 帳户                                      | 所有者             | 用途                                       |
| --------------------------------------- | --------------- | ---------------------------------------- |
| `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 是當前版本，其帳户結構最通用。

```rust theme={null}
// 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

```rust theme={null}
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

```rust theme={null}
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：

```ts theme={null}
// 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 源代碼驗證。）

```rust theme={null}
// 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

```ts theme={null}
// 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`](/zh-Hant/products/farm-staking/instructions) — 每個版本的指令參考。
* [`products/farm-staking/code-demos`](/zh-Hant/products/farm-staking/code-demos) — 通過 SDK 進行質押、收穫和創建農場。
* [`reference/program-addresses`](/zh-Hant/reference/program-addresses) — 所有三個程序 ID。

來源：

* [Raydium SDK v2 `Farm` 模塊](https://github.com/raydium-io/raydium-sdk-V2)
* 農場 v6 程序源代碼目前未作為獨立存儲庫發佈；IDL 捆綁在 [`raydium-io/raydium-sdk-V2`](https://github.com/raydium-io/raydium-sdk-V2) 的 SDK 中的 `src/raydium/farm/` 下。