Tài khoản Farm / Staking

FarmState, UserStake / Ledger, vault phần thưởng, và PDA quyền hạn — bố cục và seed PDA cho farm v3, v5, và v6.

Trang này được dịch tự động bằng AI. Phiên bản tiếng Anh là bản chính thức.

Xem bản tiếng Anh →

Ba chương trình, ba schema. Farm v3, v5, và v6 là những chương trình riêng biệt với bố cục state riêng biệt. Trang này trình bày từng phiên bản cạnh nhau. Trong thực tế, hầu hết các tích hợp mới nhắm tới v6; v3 và v5 là chỉ-đọc cho hầu hết các nhà tích hợp (staking đã xảy ra ở đó từ lâu và các pool đang trong giai đoạn kết thúc).

​

Danh sách tài khoản (mỗi farm, bất kỳ phiên bản)

Tài khoản	Chủ sở hữu	Mục đích
FarmState	Chương trình Farm (v3/v5/v6)	State gốc: mint staking, tổng số staked, dòng phần thưởng.
farm_authority	Chương trình Farm	PDA sở hữu vault staking và các vault phần thưởng.
staking_vault	SPL Token	Giữ LP được stake (hoặc bất kỳ mint staking nào).
reward_vault_{i}	SPL Token	Giữ ngân sách chưa phân phối cho dòng phần thưởng i. Một cho mỗi dòng.
UserStake (v3/v5) / UserLedger (v6)	Chương trình Farm	Sổ cái mỗi (farm, user): số tiền stake + ảnh chụp phần thưởng-trên-cổ phần cho mỗi dòng.

SDK trả về toàn bộ tập hợp trên raydium.farm.getFarmById. Đối với các farm của bên thứ ba tùy ý, endpoint API GET https://api-v3.raydium.io/main/farms/info?ids=<FARM_ID> cũng trả về chúng.

​

Bố cục FarmState — v6

v6 là phiên bản hiện tại. Cấu trúc tài khoản của nó là chung nhất.

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

Các trường hướng tới nhà tích hợp:

• staking_mint, staking_vault — những gì được stake và nơi nó được đặt.
• total_staked — tổng hiện tại. Cần thiết để tính APR: reward_per_second × 86400 / total_staked.
• reward_infos[i].emission_per_second_x64 — tỷ lệ Q64.64. Chia cho 2^64 để có số token thực trên giây.
• reward_infos[i].open_time / end_time — cho hiển thị UI “X ngày còn lại”.
• reward_infos[i].reward_per_share_x64 — bộ đếm mà UserLedger dư nợ.

​

Bố cục 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],
}

Sự khác biệt so với v6:

• Mỗi slot, không phải mỗi giây. Vòng lặp cập nhật của v5 chạy trên các slot thay vì đồng hồ treo tường. SDK chuẩn hóa điều này thành “mỗi giây” cho UI nhưng trên chuỗi đơn vị là slots.
• Tỷ lệ emission nguyên. reward_per_second là u64. Điều này giới hạn tỷ lệ tối thiểu biểu thị được ở 1 đơn vị mỗi giây, quá thô cho các dòng phát hành thấp trên mint 9-chữ số. v6 đã sửa điều này bằng tỷ lệ Q64.64.
• Không reward_sender. Trên v5, chủ sở hữu là người gửi ngầm; chỉ owner có thể bổ sung.

​

Bố cục 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],
}

Phần thưởng đơn. Dựa trên slot. Thế hệ chương trình lâu nhất, được giữ cho các farm RAY-USDC và SOL-USDC có trước v5.

​

UserLedger (v6) / UserStake (v5/v3)

State cho mỗi người dùng, một tài khoản cho mỗi cặp (farm, user). PDA seed:

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

(Chuỗi seed là những giá trị thực sự được SDK sử dụng; các phiên bản chương trình trong lịch sử đã thay đổi chúng. Xác minh so với nguồn v6 cho bất kỳ điều gì quan trọng về bảo mật.)

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

Dư nợ mỗi dòng là bù toán kế toán được mô tả trong tổng quan:

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

Sau mỗi Deposit, Withdraw, hoặc Harvest, dư nợ được đặt lại thành deposited × reward_per_share_x64[i] / 2^64 hiện tại.

​

PDA quyền hạn

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

Cả ba phiên bản đều suy ra quyền hạn farm mỗi farm với một seed duy nhất. PDA này là quyền hạn trên vault staking và trên mỗi vault phần thưởng. Nó ký tất cả các lần chuyển mà farm thực hiện.

​

Vault

Vault staking và phần thưởng là các tài khoản SPL Token tiêu chuẩn có owner là PDA quyền hạn farm. Các địa chỉ được lưu trữ trên FarmState — không tái tạo; đọc từ state. Các quyền hạn đóng băng phải bị vô hiệu hóa trên mint staking cho v5/v6 (chương trình kiểm tra).

Ghi chú Token-2022:

• v3: Chỉ SPL Token.
• v5: Chỉ SPL Token.
• v6: Hỗ trợ Token-2022 trên cả mint staking và mint phần thưởng, gated trên các trường staking_token_program / reward_token_program. Phí chuyển trên mint phần thưởng Token-2022 được tính trên emit (vault → user).

​

Quan sát và APR

Farm không lưu trữ APR trên chuỗi. Để tính toán:

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

Người tiêu dùng thường lấy staking_mint_usd_price từ pool mà LP thuộc về (qua api-v3.raydium.io/pools/info/ids) và reward_usd_price từ bất kỳ oracle giá nào.

​

Bước tiếp theo

• products/farm-staking/instructions — tham khảo hướng dẫn mỗi phiên bản.
• products/farm-staking/code-demos — staking, harvesting, và tạo farm qua SDK.
• reference/program-addresses — cả ba ID chương trình.

Nguồn:

• Mô-đun Farm Raydium SDK v2
• Mã nguồn chương trình Farm v6 hiện không được xuất bản dưới dạng repo độc lập; IDL được đóng gói trong SDK tại raydium-io/raydium-sdk-V2 dưới src/raydium/farm/.