Anchor IDL

حيث تجد IDL لكل برنامج Raydium، وكيفية إعادة توليد عملاء TS / Rust / Python منه، وسياسة تغيير IDL للبروتوكول.

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

عرض النسخة الإنجليزية →

​

ما هو IDL

برامج Anchor على Solana تنشر ملف IDL (لغة تعريف الواجهة) يصف تعليماتها وتخطيطات الحسابات وتعداد الأخطاء وأنماط الهياكل. يعتبر IDL مصدر الحقيقة لتوليد كود العميل — SDK TypeScript وصندوق Rust CPI والعملاء من جهات خارجية جميعها يتم توليدها من (أو كتابتها يدويًا ضد) IDL.

تنشر Raydium IDLs لـ CPMM و CLMM و LaunchLab. AMM v4 و Stable AMM و Farm (v3 / v5 / v6) سابقة لـ Anchor أو غير موزعة عبر Anchor بطريقة أخرى — تُحتفظ بهياكل حساباتها يدويًا في SDK.

​

حيث تجدها

تعيش IDLs في مستودع مخصص:

https://github.com/raydium-io/raydium-idl

الملفات الدقيقة:

البرنامج	ملف IDL
CPMM	raydium_cpmm/raydium_cp_swap.json
CLMM	raydium_clmm/raydium_clmm.json
LaunchLab	raydium_launchpad/raydium_launchpad.json
AMM v4	لا يوجد IDL رسمي — انظر raydium-sdk-V2/src/raydium/liquidity/layout.ts للتخطيطات المكتوبة يدويًا
Stable AMM	لا يوجد IDL رسمي — التخطيطات في SDK
Farm	لا يوجد IDL رسمي — التخطيطات في SDK

ملفات IDL مرقمة في سجل git للمستودع؛ ثبّت على commit محدد إذا كنت تحتاج إلى قابلية إعادة الإنتاج بدقة البايت.

يمكن أيضًا سحب بعض IDLs مباشرة من mainnet:

anchor idl fetch <PROGRAM_ID> --provider.cluster mainnet

هناك الآن آليتان على السلسلة لـ IDL، وبرامج Raydium موزعة عليهما — وهذا مهم لأن إصدار Anchor CLI معين قد يعرف واحدة فقط:

البرنامج	حيث يعيش IDL الخاص به	الحساب	التقارير
CLMM	حساب Anchor القديم anchor:idl	FbDNAPsgm8Y5jWXQkXjpfN6Bp8xHeRkhMmsstAooPyY9	raydium_clmm 0.1.0 — 38 تعليمة، 52 خطأ (39 / 53 بعد ترقية 2026-09-30؛ 37 / 53 بعد ترقية 2026-10-22)
LaunchLab	حساب Anchor القديم anchor:idl	E6wT2uNeoWUvDrwdch1R8ETsyewR1ZM4WAwsa5hLJK5Z	raydium_launchpad 0.2.0 — 27 تعليمة
Lock (Burn & Earn)	حساب Anchor القديم anchor:idl	HzLkUWn57cdtyQNQLJpyu2EPF8qQAiGt4iuiEo1XnEFK	4 تعليمات (IDL spec سابق للـ metadata)
CPMM	برنامج Program Metadata ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S	FHuJXL7cEttfHk4sXdTAXVaRymBdKfVs7ZH6cMgA1ihk (canonical، seed idl)	raydium_cp_swap 0.2.0
AMM v4، Stable AMM، AMM Routing، Farm v3 / v5 / v6	لا مكان	—	برامج غير Anchor؛ لا يتم نشر IDL

CPMM ليس لديه حساب anchor:idl قديم. تم ترحيل IDL الخاص به إلى برنامج Program Metadata، لذا فإن anchor idl fetch CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C يفشل على أي Anchor CLI يتحقق فقط من PDA القديم. استخدم IDL المرسل مع SDK، أو اقرأ حساب metadata أعلاه، حتى يدعم CLI الخاص بك برنامج metadata.

جميع حسابات IDL الثلاثة القديمة قابلة للكتابة بواسطة سلطة IDL 2XVnob28A5Qnpcy95UVeHWNT6G8Poy3tpA3AFyAMoZDt، وهي منفصلة عن سلطة ترقية BPF للبرامج — لذا يمكن تحديث IDL دون إعادة نشر، ويمكن أيضًا أن يتأخر عن إعادة نشر. تعامل مع IDL على السلسلة كمجرد راحة، وليس كإثبات لشكل bytecode المنشور.

​

إعادة توليد عميل TypeScript

يُنتج codegen الخاص بـ Anchor عميلاً مكتوبًا من IDL:

# استخدام anchor CLI
anchor build
anchor idl parse \
  --file target/idl/cpmm.json \
  --out target/types/cpmm.ts

# أو مع مساعدات TS `@anchor-lang/core` في وقت التشغيل:

import { Program, AnchorProvider } from "@anchor-lang/core";
// اسحب IDL مباشرة من مستودع raydium-idl (أو ضعه في مشروعك).
import cpmmIdl from "./idls/raydium_cp_swap.json";

const provider = new AnchorProvider(connection, wallet, {});
// Anchor >= 0.30 يقرأ معرف البرنامج من `idl.address` — هذه IDLs هي spec 0.1.0
// وتحمله. نموذج الثلاث حجج `new Program(idl, programId, provider)` هو
// pre-0.30 ويرمي.
const program  = new Program(cpmmIdl as any, provider);

// منشئو الطرق المكتوبة المُنتجة تلقائيًا:
await program.methods
  .swapBaseInput(new BN(amountIn), new BN(minAmountOut))
  .accounts({ ... })
  .rpc();

معظم المدمجين لا يفعلون هذا — يستخدمون مساعد raydium.cpmm.swap(...) ذو المستوى الأعلى الذي يلف طرق Anchor بالإضافة إلى كل الحفظيات (إنشاء ATA، تعديل رسوم النقل، ميزانية الحساب، توجيه برنامج Token-2022). أعد التوليد فقط عندما تحتاج إلى طبقة أسفل SDK.

​

إعادة توليد عميل Rust (صندوق CPI)

تنشر Raydium صناديق Anchor للبرامج التي لديها IDLs:

# Cargo.toml — يجب أن يكون مفتاح الاعتماد اسم PACKAGE للصندوق.
[dependencies]
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"] }

في الكود، أشر إليها باستخدام أسماء lib الخاصة بها، raydium_cp_swap و raydium_clmm. لا يوجد صندوق يسمى raydium_amm_v3 تحت أي تهجئة. كلا المستودعين master يثبتان anchor-lang =1.0.2، لذا يشترك الصندوقان في سطر Anchor واحد ويمكنهما العيش في صندوق واحد.

تكشف ميزة cpi عن هياكل حسابات cpi::accounts::<Ix> و invokers cpi::<ix>() — غلافات CPI جاهزة للاستخدام. انظر sdk-api/rust-cpi لأنماط الاستخدام.

إذا كنت تفضل توليد ربطات جديدة:

# من IDL، باستخدام anchor-client
anchor idl parse \
  --file raydium_cpmm/raydium_cp_swap.json \
  --out src/generated/cpmm_bindings.rs

​

إعادة توليد عميل Python

لا يوجد SDK Python رسمي لـ Raydium. تشمل المولدات من جهات خارجية:

• anchorpy — منفذ Python لعميل Anchor TypeScript. يولد منشئي طرق مكتوبة من IDLs.
• solders — بدائيات Solana منخفضة المستوى (معاملات، مفاتيح، pubkeys) في ربطات Rust؛ تُستخدم تحت anchorpy.

pip install anchorpy solders solana

from anchorpy import Program, Provider
from solana.rpc.async_api import AsyncClient
from pathlib import Path
import json

idl = json.loads(Path("cpmm.json").read_text())
provider = Provider(AsyncClient("https://api.mainnet-beta.solana.com"), wallet)
program  = Program(idl, CPMM_PROGRAM_ID, provider)

await program.rpc["swap_base_input"](amount_in, min_amount_out, ctx=Context(accounts={...}))

انظر sdk-api/python-integration لشرح أكثر اكتمالاً.

​

سياسة تغيير IDL

تتبع Raydium هذه القواعد لاستقرار IDL:

1. مميزات التعليمات لا تتغير أبدًا. إضافة تعليمات جديدة تمدد التعداد في النهاية؛ المميزات الموجودة تبقى مستقرة.
2. أحجام الحسابات مستقرة؛ الحقول الجديدة تأتي من الحشو المحجوز. كل هيكل حالة Raydium يحمل منطقة حشو زائدة بحجم عند الإنشاء، والحقل الجديد يُنحت من هذا الحشو بدلاً من الإضافة — لذا يبقى طول الحساب بالبايت وإزاحات جميع الحقول الموجودة مسبقًا ثابتة. النتيجة هي أن البايتات التي كنت تقرأها سابقًا كحشو يمكن أن تصبح ذات معنى، والحقل يمكن أن يتقاعد مرة أخرى إلى الحشو (كما حدث مع PlatformConfig.curve_params في إصدار 2026-08-31). أعد قراءة تعريف الهيكل بعد ترقية؛ لا تفترض أن الحشو يبقى صفرًا.
3. أكواد تعداد الأخطاء قابلة للإضافة فقط. كود خطأ موجود يعني دائمًا نفس الشيء.
4. التغييرات الجذرية تُشحن في برامج جديدة. عندما يكون هناك حاجة لإعادة تصميم، يقوم الفريق بنشر معرف برنامج جديد (مثل CPMM كبرنامج جديد بدلاً من ترقية AMM v4). تستمر المجموعات القديمة في التشغيل على البرنامج القديم؛ المجموعات الجديدة تذهب إلى الجديد.

تحافظ هذه السياسة على توافق العملاء المُنتجة بشكل أساسي للخلف: عميل مُنتج ضد IDL أقدم يستمر في فك تشفير الحقول التي يعرفها، بالإزاحات التي يعرفها. ما لن يراه هو حقل منحوت من ما يعتبره لا يزال حشوًا — وفي حالة التقاعد النادرة، قد لا يتم كتابة حقل يفك تشفيره. لا يرى “بايتات زائدة زائدة”: طول الحساب لا يتغير.

​

ماذا تفعل عندما يتغير IDL

1. حدّث SDK. npm update @raydium-io/raydium-sdk-v2.
2. أعد توليد كود العميل الخاص بك إذا كنت تستخدم Anchor codegen مباشرة.
3. قارن تخطيط الحساب. الحقول الزائدة للتخطيط الجديد هي الشيء الوحيد الذي لم يره الكود الخاص بك؛ تأكد مما إذا كنت تحتاجها.
4. لا تفترض أن مميزات التعليمات القديمة غير صالحة. وفقًا للقاعدة 1، لا تزال تعمل.
5. أعد تشغيل اختبارات التكامل ضد devnet قبل الانتقال إلى mainnet.

​

استكشاف أخطاء IDL

​

أخطاء “Invalid discriminator”

عادة ما يعني أن عميلاً مبنيًا ضد الإصدار N من IDL يحاول استدعاء تعليمة موجودة فقط في نسخة ما قبل النشر من البرنامج. أعد سحب IDL من البرنامج المباشر:

anchor idl fetch <PROGRAM_ID>

بالنسبة لـ CPMM هذا لن يعمل — انظر جدول موقع IDL أعلاه؛ اسحب IDL المرسل مع SDK بدلاً من ذلك.

​

فشل فك تشفير الحساب

إذا رمى program.account.<Name>.fetch(pubkey) مع “Invalid account discriminator”، تم إنشاء الحساب بواسطة نسخة برنامج سابقة و Anchor يرفض مميز 8 بايت الخاص به. الحل هو استخدام محلل التخطيط الخام من SDK (PoolInfoLayout.decode(accountData)) الذي لا يفرض مميزات Anchor.

​

تعليمات مفقودة في العميل المُنتج

يولد codegen TS الخاص بـ Anchor فقط طرقًا للتعليمات التي يحتوي إدخال IDL الخاص بها على name يُحلل كمعرف صالح. جميع تعليمات Raydium تستوفي هذا، لكن إذا رأيت عدم تطابق، تحقق مما إذا كان ملف IDL من إصدار SDK الحالي.

​

مؤشرات

• sdk-api/rust-cpi — استخدام صناديق Rust CPI.
• sdk-api/python-integration — Python عبر anchorpy.
• sdk-api/typescript-sdk — عميل TS ذو المستوى الأعلى.

المصادر:

• مستودع Raydium IDL
• مواصفات Anchor IDL