Rust CPI

هذه الصفحة مُترجَمة آليًا بواسطة الذكاء الاصطناعي. النسخة الإنجليزية هي المرجع المعتمد.عرض النسخة الإنجليزية →

CPI (“cross-program invocation” أو استدعاء البرنامج المتقاطع) هي الآلية التي يستدعي بها برنامج Solana واحد برنامجًا آخر. تشحن معظم برامج Raydium مع crate غلاف CPI قائم على Anchor يجعل موقع الاستدعاء يبدو مثل استدعاء دالة مكتوبة بشكل صحيح، مع هياكل حسابات لها أسماء حقول تم التحقق منها ومساعدات cpi::<ix>(). توثق هذه الصفحة النمط العام مرة واحدة، ثم الاختلافات لكل برنامج. للحصول على TypeScript قابل للتشغيل، انظر صفحة code-demos في فصل كل منتج.

أي نمط ينطبق على أي برنامج

البرنامج	قائم على Anchor	Crate	حيث
CPMM	نعم	`raydium-cp-swap` (مستودع عام؛ مسار Rust `use` هو `raydium_cp_swap`)	النمط العام، المثال العملي
CLMM	نعم	`raydium-clmm` (مستودع عام؛ مسار Rust `use` هو `raydium_clmm`)	تطبيق النمط: CLMM
LaunchLab	نعم	لا يوجد اسم crate مؤكد؛ مصدر البرنامج مغلق، لكن معرّف البيانات الوصفية الداخلية للـ IDL على السلسلة هو `raydium_launchpad`، وهو اسم تقني وليس اسم المنتج (انظر التحذير في تطبيق النمط: LaunchLab)	تطبيق النمط: LaunchLab
Farm v6	غير مؤكد؛ لم يتم العثور على IDL عام أو مصدر (انظر التحذير في Farm v6)	غير متاح	Farm v6
AMM v4	لا، يسبق Anchor بدون crate CPI	لا يوجد	AMM v4

إذا كنت تدمج CPMM أو CLMM أو LaunchLab، اقرأ النمط العام أولاً، ثم انتقل إلى قسم برنامجك للحصول على قائمة الحسابات وأي اختلافات. Farm v6 و AMM v4 مختلفان بما يكفي لضمان قراءة أقسامهما بشكل مستقل.

تبعيات Cargo

# كلا crate CPI العام من Raydium يثبتان Anchor =1.0.2 على `master`،
# لذا يمكن لبرنامج واحد أن يعتمد على أحدهما أو كليهما — انظر الجدول أدناه.
[dependencies]
anchor-lang     = "=1.0.2"
anchor-spl      = "=1.0.2"
raydium-cp-swap = { git = "https://github.com/raydium-io/raydium-cp-swap", branch = "master", features = ["cpi"] }
raydium-clmm    = { git = "https://github.com/raydium-io/raydium-clmm",    branch = "master", features = ["cpi"] }
# ملاحظة: إذا ثبتت `rev` أقدم من قبل ترقية Anchor 1.0 (CPMM 2026-09-09،
# CLMM 2026-09-30)، فإن هذا الـ rev يثبت anchor-lang 0.32.1؛ استخدم =0.32.1 و
# واجهة برمجية CpiContext 0.3x — وبعد ذلك واحد فقط من الاثنين crate في المرة الواحدة.
# LaunchLab: مصدر البرنامج غير متاح للعموم (انظر reference/program-addresses).
# لا توجد تبعية git للإشارة إليها. بدلاً من ذلك، أنشئ ربط CPI من IDL المنشور.
# انظر "تطبيق النمط: LaunchLab" أدناه.
# AMM v4 لا يحتوي على crate CPI عام قائم على Anchor؛ انظر قسمه الخاص.

يجب أن يطابق مفتاح التبعية اسم [package] في المستودع المستهدف بالضبط، بما في ذلك الواصلات. لا يعامل Cargo raydium_cp_swap كمكافئ لـ raydium-cp-swap عند حل تبعية git.

branch = "master" يتتبع أحدث مصدر منشور؛ ثبّت على rev = "<commit>" محدد إذا كنت بحاجة إلى بناء قابل للتكرار. يُنصح بهذا بمجرد الانتهاء من النماذج الأولية، لأن تغيير تخطيط الحساب في master سيكسر بناءك بدون تحذير. علم الميزة cpi يجعل crates تجميع السطح فقط من CPI (هياكل الحسابات + المستدعيات) بدلاً من البرنامج الكامل، لذا يبقى ملفك الثنائي صغيراً. يجب أن يطابق anchor-lang / anchor-spl ما يثبته crate المستهدف:

Crate	يثبت `anchor-lang` / `anchor-spl`
`raydium-cp-swap` (`master`)	`=1.0.2`، من ترقية 2026-09-09
`raydium-clmm` (`master`)	`=1.0.2`، من ترقية 2026-09-30
أي crate في `rev` قبل ترقيته	`0.32.1`

خذ كلا crate من نفس سطر Anchor. كلا فرع master يثبتان =1.0.2، لذا يمكن لبرنامج واحد أن يستدعي CPI إلى CPMM و CLMM من crate واحد. خلط الأسطر يكسر البناء: على سبيل المثال، raydium-cp-swap على master مع raydium-clmm مثبت على rev من قبل ترقية Anchor 1.0. سيضطر Cargo إلى ربط نسختين غير متوافقتين من سمات Anchor في ملف ثنائي واحد. إذا كنت عالقًا في زوج مختلط، قسّم البرنامج إلى اثنين، أو أسقط crate CPI المكتوب للجانب الآخر وقم بترميز هذا التعليمات يدويًا (النمط الموضح لـ AMM v4 يعمل مع أي برنامج).

غيّر Anchor 1.0 شيئين يلمسهما كل موقع استدعاء CPI. إذا كنت تنقل تكاملاً عاملاً من 0.3x:

CpiContext::new يأخذ Pubkey، وليس AccountInfo. CpiContext::new(ctx.accounts.cpmm_program.to_account_info(), accts) يصبح CpiContext::new(*ctx.accounts.cpmm_program.key, accts). نفس الشيء لـ new_with_signer. حقل الهيكل الآن program_id: Pubkey.
Context له عمر واحد، وليس أربعة. Context<'_, '_, 'info, 'info, MyProxySwap<'info>> يصبح Context<'info, MyProxySwap<'info>>.

على جانب العميل، RequestBuilder::instructions() من anchor-client يعيد الآن Vec<Instruction> بدلاً من Result<Vec<Instruction>> (أسقط ?)، و CommitmentConfig انتقل من solana-sdk — خذه من anchor_client بدلاً من ذلك. spl-associated-token-account 8.0 يعيد تصدير مساعداته من crate spl-associated-token-account-interface الجديد. get_associated_token_address و ID لا تزال قابلة للوصول في جذر crate (spl_associated_token_account::{get_associated_token_address, ID})، لكن مساعدات العنوان مهملة هناك — فضّل الاعتماد على spl-associated-token-account-interface مباشرة واستيراد spl_associated_token_account_interface::address::get_associated_token_address و spl_associated_token_account_interface::program::ID. لاحظ أن ::address و ::program هي وحدات من crate الواجهة؛ spl_associated_token_account::address::… لا تحل.

للحصول على أمثلة CPI عاملة تربط هياكل الحسابات من البداية إلى النهاية، انظر raydium-io/raydium-cpi-example (يغطي AMM v4 و CPMM و CLMM). أحدث فرع لها هو anchor-0.31.0 — لا يوجد فرع Anchor 1.x حتى الآن، لذا تعامل مع هذا المستودع كمرجع لـ ربط هيكل الحسابات، وليس لتثبيتات الإصدار التي تفرضها هذه الصفحة.

نمط Anchor CPI العام

يشرح هذا القسم CPMM من البداية إلى النهاية كمثال عملي: هيكل Accounts، CpiContext، cpi::<ix>(). يتبع CLMM الشكل المطابق تماماً، مع قائمة حسابات مختلفة ومتطلب remaining-accounts. يتبع LaunchLab نفس الآليات لكن قائمة حساباته تحتوي على عدة حسابات بلا مكافئ في CPMM/CLMM (global_config، platform_config، event_authority، program)، لذا تعامل معها كنفس النمط، وليس نفس الشكل. راجع قسم كل برنامج بدلاً من افتراض أن قائمة الحسابات في هذا الشرح تنطبق مباشرة.

بناء قائمة الحسابات

كل CPI من Raydium يتطلب هيكل Accounts في البرنامج الذي يستدعيه. حقوله هي أي حسابات تحتاجها تعليماتك، مع محققات على مستوى الحقل؛ ترتيب إعلانها لا يجب أن يطابق ترتيب حسابات تعليمات Raydium الخاصة، لأن عميل IDL الذي تم إنشاؤه يعالجها بالاسم وليس بالموضع:

use anchor_lang::prelude::*;
use anchor_spl::token::{Token, TokenAccount, Mint};

#[derive(Accounts)]
pub struct MyProxySwap<'info> {
    #[account(mut)]
    pub user: Signer<'info>,

    /// CHECK: validated by CPMM
    #[account(mut)]
    pub pool_state: UncheckedAccount<'info>,

    /// CHECK: ditto
    pub amm_config: UncheckedAccount<'info>,

    /// CHECK: ditto
    pub pool_authority: UncheckedAccount<'info>,

    #[account(mut)]
    pub input_vault: Account<'info, TokenAccount>,
    #[account(mut)]
    pub output_vault: Account<'info, TokenAccount>,

    pub input_mint: Account<'info, Mint>,
    pub output_mint: Account<'info, Mint>,

    #[account(mut)]
    pub user_input_ata:  Account<'info, TokenAccount>,
    #[account(mut)]
    pub user_output_ata: Account<'info, TokenAccount>,

    /// Typed as `Program<RaydiumCpSwap>` rather than `UncheckedAccount`: this account
    /// is the program being invoked, not Raydium-owned data, so Anchor's `Program<T>`
    /// wrapper checks its address automatically instead of leaving that check to the
    /// callee.
    pub cpmm_program: Program<'info, raydium_cp_swap::program::RaydiumCpSwap>,
    pub token_program: Program<'info, Token>,
    /// CHECK: observation PDA
    #[account(mut)]
    pub observation_state: UncheckedAccount<'info>,
}

معظم حسابات جانب Raydium هي UncheckedAccount لأن المستدعى (Raydium) يمتلك التحقق. برنامجك الذي يستدعي يتحقق بصرامة فقط من الحسابات التي تمتلكها، مثل ATAs المستخدم و PDAs الخاصة بك. تعليق /// CHECK: يقمع تحذير Anchor حول الفحوصات المفقودة. الاستثناء الوحيد من جانب Raydium هو cpmm_program نفسه: إنه البرنامج الذي يتم استدعاؤه وليس حساب بيانات يتحقق منه Raydium داخلياً، لذا يتم كتابته كـ Program<T> ويحصل على فحص العنوان التلقائي من Anchor بدلاً من فحص /// CHECK: يدوي. هذا الشكل الذي يحتوي على UncheckedAccount في الغالب، حيث يتحقق Raydium من حساباته الخاصة، هو نفسه بالنسبة لـ CLMM و LaunchLab. يفترض هذا المثال أن كلا الـ mints كلاسيكي SPL Token؛ إذا كان أي جانب يمكن أن يكون Token-2022 mint، أضف حقل token_program_2022: Program<'info, anchor_spl::token_2022::Token2022> وأمرره كـ input_token_program/output_token_program لذلك الجانب في استدعاء CPI أدناه بدلاً من token_program.

بناء استدعاء CPI

ينشئ Anchor مساعداً واحداً لكل تعليمة، مع هيكل حسابات CPI (cpi::accounts::Swap، مستعار كـ CpmmSwap أدناه). بخلاف هيكل MyProxySwap الخاص بك أعلاه، أسماء الحقول والترتيب في هذا الهيكل ثابتة بواسطة IDL الخاص بـ raydium-cp-swap ويجب أن تطابق بالضبط:

use raydium_cp_swap::cpi::{self, accounts::Swap as CpmmSwap};

pub fn my_proxy_swap(
    ctx: Context<MyProxySwap>,
    amount_in: u64,
    minimum_amount_out: u64,
) -> Result<()> {
    let cpi_accounts = CpmmSwap {
        // `payer` is YOUR signer — it must own `input_token_account`.
        payer:                ctx.accounts.user.to_account_info(),
        // `authority` is CPMM's OWN vault PDA at seeds [b"vault_and_lp_mint_auth_seed"],
        // which CPMM signs with itself. Passing your signer here fails the
        // seeds constraint (`ConstraintSeeds`) before any transfer runs.
        authority:            ctx.accounts.pool_authority.to_account_info(),
        amm_config:           ctx.accounts.amm_config.to_account_info(),
        pool_state:           ctx.accounts.pool_state.to_account_info(),
        input_token_account:  ctx.accounts.user_input_ata.to_account_info(),
        output_token_account: ctx.accounts.user_output_ata.to_account_info(),
        input_vault:          ctx.accounts.input_vault.to_account_info(),
        output_vault:         ctx.accounts.output_vault.to_account_info(),
        input_token_program:  ctx.accounts.token_program.to_account_info(),
        output_token_program: ctx.accounts.token_program.to_account_info(),
        input_token_mint:     ctx.accounts.input_mint.to_account_info(),
        output_token_mint:    ctx.accounts.output_mint.to_account_info(),
        observation_state:    ctx.accounts.observation_state.to_account_info(),
    };
    // Anchor 1.0: the first argument is the program's Pubkey, not its AccountInfo.
    let cpi_ctx = CpiContext::new(
        *ctx.accounts.cpmm_program.key,
        cpi_accounts,
    );

    cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out)?;
    Ok(())
}

cpi::swap_base_input يتم إنشاؤه من IDL؛ قائمة حجته تعكس قائمة حجج تعليمات Anchor. كل برنامج Raydium مؤكد قائم على Anchor (CPMM، CLMM، LaunchLab) ينشئ مساعدات cpi::<ix>() بنفس الطريقة، مع تطابق اسم الدالة مع اسم التعليمة بصيغة snake_case. ما إذا كان هذا يمتد إلى Farm v6 غير مؤكد؛ راجع قسمه.

بذور الموقّع (CPI موقّع بـ PDA)

عندما يوقّع برنامجك على CPI نيابة عن PDA (شائع للخزائن والضمانات، إلخ)، استخدم CpiContext::new_with_signer:

let bump         = ctx.accounts.my_authority_bump;
let signer_seeds: &[&[&[u8]]] = &[&[b"my_authority", &[bump]]];

let cpi_ctx = CpiContext::new_with_signer(
    *ctx.accounts.cpmm_program.key,
    cpi_accounts,
    signer_seeds,
);

cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out)?;

يجب أن تطابق بذور الموقّع اشتقاق PDA. لأي حساب يتم تمريره كـ authority (أو دور موقّع مشابه)، يتحقق وقت تشغيل Solana من أن PDA يوقّع عبر هذه البذور.

الحسابات المتبقية

بعض تعليمات Raydium تأخذ حسابات متبقية، قائمة بطول متغير مُلحقة بعد الحسابات الثابتة. مساعدات CPI الخاصة بـ Anchor لا تفحص نوع الحسابات المتبقية؛ مررها عبر .with_remaining_accounts(...):

let cpi_ctx = CpiContext::new(program_id, accounts)
    .with_remaining_accounts(ctx.remaining_accounts.to_vec());

الترتيب مهم دائماً، لأن برنامج المستقبل يكرر الحسابات المتبقية بالترتيب الذي تمررها به. ترتيبان مؤكدان:

CLMM SwapV2: مصفوفات التجزئة، مرتبة اتجاهياً.
Farm v6: أزواج (reward_vault, user_reward_ata)، لكن فقط من تدفق المكافأة الثاني فما بعده؛ راجع Farm v6 لمعرفة ما يظهره فك تشفير معاملة حقيقية.

تطبيق النمط: CLMM

يتبع SwapV2 النمط العام أعلاه مع قائمة حسابات مختلفة ومتطلب remaining-accounts لمصفوفات التجزئة. وحدة #[program] الخاصة بـ crate مسماة raydium_clmm، وهي أيضاً مسار Rust use الخاص بها.

هيكل حسابات CPI مسمى SwapSingleV2، وليس SwapV2. SwapV2 هو اسم التعليمة على السلسلة.

use raydium_clmm::cpi::{self, accounts::SwapSingleV2 as ClmmSwap};

#[derive(Accounts)]
pub struct MyProxyClmmSwap<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,

    /// CHECK: validated by CLMM
    pub amm_config: UncheckedAccount<'info>,
    /// CHECK: ditto
    #[account(mut)]
    pub pool_state: UncheckedAccount<'info>,

    #[account(mut)]
    pub input_token_account: Account<'info, TokenAccount>,
    #[account(mut)]
    pub output_token_account: Account<'info, TokenAccount>,
    #[account(mut)]
    pub input_vault: Account<'info, TokenAccount>,
    #[account(mut)]
    pub output_vault: Account<'info, TokenAccount>,

    /// CHECK: observation PDA
    #[account(mut)]
    pub observation_state: UncheckedAccount<'info>,

    pub token_program: Program<'info, Token>,
    pub token_program_2022: Program<'info, anchor_spl::token_2022::Token2022>,
    /// CHECK: SPL memo program, required for some Token-2022 paths
    pub memo_program: UncheckedAccount<'info>,

    pub input_vault_mint: Account<'info, Mint>,
    pub output_vault_mint: Account<'info, Mint>,

    /// Typed as `Program<T>` rather than `UncheckedAccount`, same reason as CPMM's
    /// `cpmm_program` in the general pattern above: it's the invoked program, and
    /// `Program<T>` checks its address automatically.
    pub clmm_program: Program<'info, raydium_clmm::program::RaydiumClmm>,
    // remaining_accounts: tick_array_bitmap_extension (if the walk needs it), then
    // as many tick_array accounts as the swap's expected price range spans.
}

احسب قائمة مصفوفة التجزئة بنفس الطريقة التي يفعلها SDK، عبر اقتباس ضد حالة المجموعة الحالية، بدلاً من تخمين عدد ثابت؛ مبادلة تتجاوز المصفوفات التي مررتها تعود مع TickArrayNotFound (راجع products/clmm/instructions للحصول على جدول الحسابات الكامل وقائمة الأخطاء). مررها في اتجاه المشي السعري: أول مصفوفة في اتجاه المبادلة أولاً.

تطبيق النمط: LaunchLab

LaunchLab مبني على Anchor ومنشور عبر IDL: raydium_launchpad/raydium_launchpad.json في مستودع raydium-idl العام. معرّف البيانات الوصفية الداخلي لهذا IDL هو raydium_launchpad، وهو اسم تقني للبرنامج الأساسي وليس اسماً بديلاً للمنتج. بخلاف CPMM و CLMM، الكود المصدري للبرنامج نفسه غير متاح للعموم (انظر reference/program-addresses). لا توجد تبعية git = "..." لتوجيه Cargo إليها، ولا يوجد مصدر للتحقق من مسار Rust use الفعلي للـ crate. أنشئ الربطات من IDL المنشور باستخدام ماكرو Anchor declare_program!. احفظ ملف JSON الخاص بـ IDL باسم idls/raydium_launchpad.json في crate الخاص بك (يبحث Cargo عن مجلد idls/ نسبة إلى CARGO_MANIFEST_DIR)، ثم declare_program!(raydium_launchpad); ينشئ هياكل raydium_launchpad::cpi::accounts::<Ix> ودوال cpi::<ix>() مباشرة من IDL، بدون الحاجة إلى مصدر البرنامج. اسم هيكل الحسابات المُنشأ هو دائماً اسم التعليمة بصيغة PascalCase (buy_exact_in → BuyExactIn)، وأسماء الحقول تطابق أسماء الحسابات في IDL بالضبط، نفس قائمة الحسابات المستخدمة بالفعل في MyProxyBuy أدناه. شكل CPI يتبع النمط العام. قائمة الحسابات والمعاملات أدناه تأتي من تعليمة buy_exact_in في IDL على السلسلة، وليس من products/launchlab/instructions.mdx:

use anchor_lang::prelude::*;
use anchor_spl::token::{Token, TokenAccount, Mint};
use raydium_launchpad::cpi::{self, accounts::BuyExactIn};

#[derive(Accounts)]
pub struct MyProxyBuy<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,

    /// CHECK: PDA, seeds = [b"vault_auth_seed"], validated by the program
    pub authority: UncheckedAccount<'info>,

    /// CHECK: validated by the program
    pub global_config: UncheckedAccount<'info>,
    /// CHECK: validated by the program
    pub platform_config: UncheckedAccount<'info>,

    /// CHECK: validated by the program
    #[account(mut)]
    pub pool_state: UncheckedAccount<'info>,

    #[account(mut)]
    pub user_base_token: Account<'info, TokenAccount>,
    #[account(mut)]
    pub user_quote_token: Account<'info, TokenAccount>,
    #[account(mut)]
    pub base_vault: Account<'info, TokenAccount>,
    #[account(mut)]
    pub quote_vault: Account<'info, TokenAccount>,

    pub base_token_mint: Account<'info, Mint>,
    pub quote_token_mint: Account<'info, Mint>,

    /// CHECK: base mint's token program (SPL Token or Token-2022, depending on the mint)
    pub base_token_program: UncheckedAccount<'info>,
    /// Typed as `Program<Token>` rather than `UncheckedAccount`: the IDL fixes this to
    /// classic SPL Token specifically (unlike base_token_program above), so Anchor's
    /// built-in address check on `Program<Token>` is sufficient on its own.
    pub quote_token_program: Program<'info, Token>,

    /// CHECK: PDA, seeds = [b"__event_authority"], required by the program's emit_cpi! pattern
    pub event_authority: UncheckedAccount<'info>,
    /// CHECK: the program's own account, required alongside event_authority
    pub program: UncheckedAccount<'info>,
}

pub fn my_proxy_buy(
    ctx: Context<MyProxyBuy>,
    amount_in: u64,
    minimum_amount_out: u64,
    share_fee_rate: u64,
) -> Result<()> {
    let cpi_accounts = BuyExactIn {
        payer:               ctx.accounts.payer.to_account_info(),
        authority:           ctx.accounts.authority.to_account_info(),
        global_config:       ctx.accounts.global_config.to_account_info(),
        platform_config:     ctx.accounts.platform_config.to_account_info(),
        pool_state:          ctx.accounts.pool_state.to_account_info(),
        user_base_token:     ctx.accounts.user_base_token.to_account_info(),
        user_quote_token:    ctx.accounts.user_quote_token.to_account_info(),
        base_vault:          ctx.accounts.base_vault.to_account_info(),
        quote_vault:         ctx.accounts.quote_vault.to_account_info(),
        base_token_mint:     ctx.accounts.base_token_mint.to_account_info(),
        quote_token_mint:    ctx.accounts.quote_token_mint.to_account_info(),
        base_token_program:  ctx.accounts.base_token_program.to_account_info(),
        quote_token_program: ctx.accounts.quote_token_program.to_account_info(),
        event_authority:     ctx.accounts.event_authority.to_account_info(),
        program:             ctx.accounts.program.to_account_info(),
    };
    // `program` doubles as the CPI target here: LaunchLab's own account is both one of
    // its instruction's required accounts (for its emit_cpi! pattern) and the program
    // CpiContext::new invokes.
    let cpi_ctx = CpiContext::new(
        *ctx.accounts.program.key,
        cpi_accounts,
    );

    cpi::buy_exact_in(cpi_ctx, amount_in, minimum_amount_out, share_fee_rate)?;
    Ok(())
}

بعد التخرج، البرنامج المستهدف هو CPMM أو AMM v4 حسب pool_state.migrate_type، والذي تقول products/launchlab/accounts.mdx أنه يُعيّن في وقت Initialize. قائمة حسابات CPI الخاصة بك يجب أن تكون مُعدّة لأي منهما، أو تحتاج إلى قراءة migrate_type من PoolState أولاً والتفرع.

نشر الأخطاء

كل برنامج Raydium مبني على Anchor يُرجع enum أخطاء خاص به؛ Anchor يلفّه، لذا برنامجك الذي يستدعي يرى الأخطاء كـ Err(ProgramError::Custom(code)). للتعامل مع أخطاء محددة:

use raydium_cp_swap::error::ErrorCode as CpmmErr;

match cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out) {
    Ok(_) => Ok(()),
    Err(e) => {
        msg!("CPMM swap failed: {:?}", e);
        // Re-raise, or convert to your own error type.
        Err(e)
    }
}

استبدل نوع الخطأ ذا الصلة للبرنامج الذي تستدعيه (raydium_clmm::error::ErrorCode لـ CLMM، وهكذا). أرقام رموز الأخطاء مستقرة وفقاً لسياسة IDL (sdk-api/anchor-idl)، لذا يمكنك الاختبار مقابل رموز محددة بمقارنة القيمة الرقمية. جداول الأخطاء الكاملة: CPMM، CLMM، AMM v4، Farm v6، و LaunchLab.

ميزانية الحساب في CPIs المركبة

لكل إطار CPI تكلفة عامة، واستهلاك CU الخاص بالمستدعى يتراكم فوق استهلاكك، لذا معاملة تستدعي Raydium من داخل برنامجك تحتاج إلى ميزانية حساب صريحة بدلاً من الاعتماد على الحد الافتراضي 200k CU.

مقاس، وليس مقدّر. swap_base_input في CPMM على mainnet يستهلك ~23,000 CU في برنامج CPMM نفسه — تم أخذ عينات في 2026-09-09 عبر ثماني مبادلات مباشرة على مجموعة عالية الحجم (22,721–23,052)، مقروءة من سطر السجل Program CPMMoo8… consumed N of M compute units. للمقارنة: AMM v4 swap ~26,000؛ CLMM swap ~41,000؛ CLMM swap_v2 ~48,000 (43,838–52,887)، يرتفع مع كل عبور tick.نسخة سابقة من هذه الصفحة أبلغت عن ~47,700 CU لـ proxy-swap CPI. كان هذا الرقم المعاملة بأكملها (computeUnitsConsumed)، والذي يشمل برنامجك الخاص، إطار CPI وأي إعداد ATA — وليس تكلفة المستدعى. كلاهما مفيد، لكنهما ليسا نفس الرقم، لذا قارن مثل مع مثل. قس معاملتك الخاصة بدلاً من وضع ميزانية من أي من الرقمين.

CPIs في CLMM و LaunchLab تكلف أكثر (CLMM بشكل خاص يمشي عبر مصفوفات tick إضافية عبر remaining_accounts، مضيفاً CU لكل مصفوفة)، لكن فقط الرقم CPMM أعلاه هو قيمة مقاسة. اضبط دائماً تعليمة ComputeBudgetProgram::set_compute_unit_limit(...) صريحة بحجم من قياسك الخاص، وليس رقماً منسوخاً من التوثيق، لأن حد 200k CU الافتراضي سيستنزف بصمت وتكاليف كل تعليمة تتغير مع ترقية البرامج.

AMM v4: بناء Instruction يدوي

AMM v4 يسبق Anchor وليس لديه crate CPI، مما يجعله البرنامج الوحيد في هذا المستند الذي لا يتبع النمط العام أعلاه. بناء Instruction يدويًا:

use anchor_lang::prelude::*;
use anchor_lang::solana_program::program::invoke_signed;
use anchor_lang::solana_program::instruction::{Instruction, AccountMeta};

const AMM_V4_PROGRAM_ID: Pubkey = pubkey!("675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8");

// SwapBaseIn discriminator is 9.
let mut data = vec![9u8];
data.extend_from_slice(&amount_in.to_le_bytes());
data.extend_from_slice(&minimum_amount_out.to_le_bytes());

let ix = Instruction {
    program_id: AMM_V4_PROGRAM_ID,
    accounts: vec![
        AccountMeta::new_readonly(token_program_id, false),
        AccountMeta::new(amm_id, false),
        AccountMeta::new_readonly(amm_authority, false),
        // ... remaining accounts per products/amm-v4/instructions ...
    ],
    data,
};
invoke_signed(&ix, &account_infos, signer_seeds)?;

انظر products/amm-v4/code-demos للحصول على قائمة الحسابات الكاملة.

Farm v6

استخدم TS SDK إذا كان هذا خياراً لتكاملك. raydium.farm.deposit(...) (انظر products/farm-staking/code-demos) يتم ممارسته من خلال عروض توضيحية حقيقية ولا يعتمد على ما إذا كان crate Anchor موجود لهذا البرنامج.

Farm v6 لا يوفر مسار Anchor CPI. لا يوجد crate raydium_farm_v6 على crates.io، لا توجد مستودع مصدر عام، ولا يوجد IDL على السلسلة — البرنامج لا يملك حساب anchor:idl قديم ولا إدخال في برنامج Program Metadata (انظر sdk-api/anchor-idl). تعامل معه كبرنامج غير Anchor وبناء تعليماته يدويًا، كما هو موضح أدناه.

إذا كنت بحاجة إلى Rust CPI بغض النظر، على سبيل المثال التركيب من برنامج آخر على السلسلة، بناء Instruction يدويًا، بنفس الطريقة كما في AMM v4: اشتق قائمة الحسابات الحقيقية ومميزات التعليمات بشكل مستقل، على سبيل المثال بفك تشفير تخطيطات TypeScript الخاصة بـ SDK (raydium-sdk-V2’s farm module)، فك تشفير المعاملات الحقيقية مباشرة (انظر أدناه)، أو تفريغ وفك تجميع البرنامج المنشور. لشكل التعليمة بدون معاملات متسق مع استدعاء harvest أو claim، ترتيب الحساب الحقيقي هو بادئة ثابتة (token_program، حساب حالة المزرعة، PDA سلطة الخزن، أول خزن مكافآت PDA، ثاني PDA، المستدعي، و ATA المستدعي لأول mint مكافآت)، متبوعاً بأزواج (reward_vault_i, user_reward_ata_i) في remaining_accounts لكل تدفق مكافآت بعد الأول. اتفاقية الاقتران حقيقية، لكنها تبدأ فقط عند تدفق المكافآت الثاني: خزن وATA تدفق المكافآت الأول حسابات ثابتة، وليست مجاورة لبعضها البعض، وليست جزءاً من remaining_accounts على الإطلاق.

اختبار تدفق CPI

يتطلب التطوير المحلي توفر برامج Raydium في مدقق الاختبار المحلي لديك. ثلاث خيارات:

anchor test مع استنساخ البرنامج. يسحب bytecode المنشور من mainnet إلى مدقق الاختبار المحلي؛ انظر استنساخ البرامج إلى مدقق محلي أدناه للحصول على إعدادات Anchor.toml وشيئين يسبّبان مشاكل في اختبارات إنشاء المجمع تحديداً.
Devnet. تنشر Raydium معظم البرامج على devnet، لكن بـ معرفات برامج مختلفة عن mainnet لكل برنامج (CPMM و CLMM و AMM v4 و Stable AMM و LaunchLab لكل منها عنوان devnet مختلف؛ انظر جدول Devnet في reference/program-addresses). لا يتم نشر Farm v3/v5/v6 بشكل موثوق على devnet؛ واجهة برمجية حية (https://api-v3-devnet.raydium.io/main/info) توضح الصورة الحالية. إذا استخدمت ثوابت DEVNET_PROGRAM_ID المضمنة في raydium_clmm (أو ما يعادلها في صناديق أخرى)، فلا تفترض أن معرف mainnet يعمل أيضاً على devnet. شغّل anchor test --provider.cluster devnet للوصول إلى الكود الحي بمجرد حصولك على العناوين الصحيحة.
نشر محلي. استنسخ مستودعات Raydium (CPMM و CLMM؛ مصدر LaunchLab غير متاح لهذا الخيار) و anchor deploy إلى مدقق محلي. يضيف تكلفة دورة اختبار لكن يتيح لك تعديل المستدعى للتصحيح.

شغّل باستخدام anchor test، أو anchor build أولاً ثم anchor test --skip-build بعده إذا كنت تكرر على ملف الاختبار دون تغيير البرنامج.

استنساخ البرامج إلى مدقق محلي

[test]
# Default (5s) isn't enough once you're cloning several accounts, since each is
# a sequential mainnet RPC round trip during validator startup.
startup_wait = 60000

[test.validator]
url = "https://api.mainnet-beta.solana.com"

[[test.validator.clone]]
address = "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK"  # CLMM

[[test.validator.clone]]
address = "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C"  # CPMM

[[test.validator.clone]]
address = "LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj"   # LaunchLab

[[test.validator.clone]]
address = "FarmqiPv5eAj3j1GMdMCMUGXqPUvmquZtMy86QH6rzhG"  # Farm v6

يعمل هذا بواسطة معرف البرنامج بغض النظر عما إذا كان مصدر البرنامج عاماً أم لا، لذا يستنسخ LaunchLab بنفس الطريقة التي يستنسخ بها CPMM و CLMM حتى وإن لم يكن مصدره متاحاً. reference/program-addresses هو مصدر الحقيقة لكل عنوان هنا.

استنساخ البرنامج وحده غير كافٍ إذا كان اختبارك أيضاً ينشئ مجمعاً (بدلاً من المبادلة مقابل واحد موجود بالفعل). تتحقق تعليمة initialize الخاصة بـ CPMM من حسابات amm_config و create_pool_fee مقابل بيانات حقيقية على السلسلة، لذا تحتاج إلى استنساخ تلك أيضاً، وإلا فإن initialize يفشل تماماً. بالنسبة إلى CPMM تحديداً: استنسخ AmmConfig لفئة الرسوم التي تريدها (احصل على عنوانها من GET https://api-v3.raydium.io/main/cpmm-config، الفهرس 0 هو فئة 0.25%) وحساب رمز استقبال الرسوم، يتم التحقق منه بالعنوان الدقيق، وليس إنشاؤه على الطاير، لذا يجب أن يكون موجوداً بالفعل.

المجمع الذي أنشأه اختبارك للتو ليس قابلاً للمبادلة في نفس اللحظة. تتجاوز تعليمة initialize الخاصة بـ CPMM بصمت open_time مطلوب ليس بدقة في المستقبل (if open_time <= block_timestamp { open_time = block_timestamp + 1 })، لذا حتى startTime: 0 (“افتح فوراً،” وفقاً لـ SDK) يترك فجوة حقيقية ≥1 ثانية قبل أن يقبل المجمع المبادلات. سيؤدي الاختبار الذي ينشئ مجمعاً ويتبادل معه بدون تأخير إلى NotApproved. انتظار قصير (1–2 ثانية) بين إنشاء المجمع والمبادلة الأولى كافٍ. هذا خاص بالاختبار؛ الشخص الذي يشغل أمرين منفصلين يدويين عادة لن يلاحظ، لأن الكتابة وبدء العملية يستهلكان بالفعل أكثر من ثانية.

مؤشرات

products/cpmm/code-demos، products/clmm/code-demos، products/amm-v4/code-demos، products/farm-staking/code-demos، products/launchlab/code-demos: أمثلة CPI و TypeScript خاصة بالمنتج.
sdk-api/anchor-idl: استرجاع IDL وإعادة إنشاء العميل، بما في ذلك مسار IDL-codegen لـ LaunchLab.
integration-guides/cpi-integration: أنماط تكامل أعلى مستوى مثل الضمانات والأقبية وتكوين المجمّع.

المصادر:

raydium-cp-swap
raydium-clmm
raydium-idl: LaunchLab IDL (مصدر البرنامج نفسه مغلق)
Anchor CPI docs

Solana fundamentals

Quick start

SDK & API

Integration guides

أي نمط ينطبق على أي برنامج

تبعيات Cargo

نمط Anchor CPI العام

بناء قائمة الحسابات

بناء استدعاء CPI

بذور الموقّع (CPI موقّع بـ PDA)

الحسابات المتبقية

تطبيق النمط: CLMM

تطبيق النمط: LaunchLab

نشر الأخطاء

ميزانية الحساب في CPIs المركبة

AMM v4: بناء Instruction يدوي

Farm v6

اختبار تدفق CPI

استنساخ البرامج إلى مدقق محلي

مؤشرات

​أي نمط ينطبق على أي برنامج

​تبعيات Cargo

​نمط Anchor CPI العام

​بناء قائمة الحسابات

​بناء استدعاء CPI

​بذور الموقّع (CPI موقّع بـ PDA)

​الحسابات المتبقية

​تطبيق النمط: CLMM

​تطبيق النمط: LaunchLab

​نشر الأخطاء

​ميزانية الحساب في CPIs المركبة

​AMM v4: بناء Instruction يدوي

​Farm v6

​اختبار تدفق CPI

​استنساخ البرامج إلى مدقق محلي

​مؤشرات

أي نمط ينطبق على أي برنامج

تبعيات Cargo

نمط Anchor CPI العام

بناء قائمة الحسابات

بناء استدعاء CPI

بذور الموقّع (CPI موقّع بـ PDA)

الحسابات المتبقية

تطبيق النمط: CLMM

تطبيق النمط: LaunchLab

نشر الأخطاء

ميزانية الحساب في CPIs المركبة

AMM v4: بناء Instruction يدوي

Farm v6

اختبار تدفق CPI

استنساخ البرامج إلى مدقق محلي

مؤشرات