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

ما هو IDL

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

حيث تجدها

تعيش IDLs في مستودع مخصص:
الملفات الدقيقة: يتم إصدار ملفات IDL في سجل git للمستودع؛ ثبّت على commit معين إذا كنت بحاجة إلى قابلية إعادة الإنتاج بدقة البايت. يمكن أيضًا سحب بعض IDLs مباشرة من mainnet:
هناك الآن آليتان على السلسلة لـ IDL، وتنقسم برامج Raydium عبرهما — وهذا مهم لأن إصدار Anchor CLI معين قد يعرف واحدة فقط:
CPMM ليس لديه حساب anchor:idl قديم. تم ترحيل IDL الخاص به إلى برنامج Program Metadata، لذا فإن anchor idl fetch CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C يفشل على أي Anchor CLI يتحقق فقط من PDA القديم. استخدم IDL المرسل مع SDK، أو اقرأ حساب البيانات الوصفية أعلاه، حتى يدعم CLI الخاص بك برنامج البيانات الوصفية.
جميع حسابات IDL الثلاثة القديمة قابلة للكتابة بواسطة سلطة IDL 2XVnob28A5Qnpcy95UVeHWNT6G8Poy3tpA3AFyAMoZDt، وهي منفصلة عن سلطة ترقية BPF للبرامج — لذا يمكن تحديث IDL دون إعادة نشر، ويمكن أيضًا أن يتأخر عن إعادة النشر. تعامل مع IDL على السلسلة كمسألة راحة، وليس كإثبات لشكل bytecode المنشور.

إعادة إنشاء عميل TypeScript

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

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

تنشر Raydium صناديق Anchor للبرامج التي لديها IDLs:
في الكود، أشر إليها باستخدام أسماء lib الخاصة بها، raydium_cp_swap و raydium_clmm. لا يوجد صندوق يسمى raydium_amm_v3 تحت أي تهجئة. انتبه للفرع. كلا المستودعين master لا يزالان يثبتان anchor-lang 0.32.1، لذا فإن تكامل Anchor 1.0 يحتاج chore/upgrade-anchor على كل واحد. مع كلا الصندوقين على هذا الفرع، يشاركان =1.0.2 ويمكنهما العيش في صندوق واحد. خلط صندوق master مع صندوق فرع الترقية لا ينشئ. تكشف ميزة cpi عن هياكل حسابات cpi::accounts::<Ix> و invokers cpi::<ix>() — غلافات CPI جاهزة للاستخدام. انظر sdk-api/rust-cpi لأنماط الاستخدام. إذا كنت تفضل إنشاء ربطات جديدة:

إعادة إنشاء عميل Python

لا يوجد SDK Python رسمي لـ Raydium. تتضمن المولدات من جهات خارجية:
  • anchorpy — منفذ Python لعميل Anchor TypeScript. ينشئ منشئات طرق مكتوبة من IDLs.
  • solders — بدائيات Solana منخفضة المستوى (المعاملات، المفاتيح، pubkeys) في ربطات Rust؛ تُستخدم تحت anchorpy.
انظر 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 من البرنامج المباشر:
بالنسبة لـ CPMM هذا لن ينجح — انظر جدول موقع IDL أعلاه؛ اسحب IDL المرسل مع SDK بدلاً من ذلك.

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

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

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

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

مؤشرات

المصادر: