IDL - واجهة برنامج سهلة الاستخدام

IDL اختصار لـ Interface Definition Language (لغة تعريف الواجهة).
على سولانا، ملفات IDL هي ملفات JSON تصف واجهة البرنامج. وهي تتيح للمستكشفين والمستخدمين فك تشفير تعليمات البرنامج وبيانات الحسابات وأخطاء البرنامج، كما توفر إمكانية توليد عملاء بلغات برمجية مختلفة.

لماذا تهمنا ملفات IDL

• التوحيد القياسي ← تنسيق موحد لواجهات البرامج.
• تجربة المطور ← توليد حزم SDK للعملاء تلقائياً.
• قابلية التركيب ← يستطيع المطورون الآخرون التفاعل مع برنامجك دون الحاجة إلى قراءة كوده المصدري.
• سهولة القراءة ← يمكن للجميع قراءة تعليمات البرنامج وبيانات الحسابات في المستكشفين دون قراءة الكود المصدري للبرنامج.

ما الذي يمكنك فعله بملفات IDL

فك تشفير بيانات التعليمات والحسابات

تستخدم جميع المستكشفين ملفات IDL للبرامج لفك تشفير التعليمات وبيانات الحسابات. يمكنك هنا مشاهدة مثال على Anchor 0.30.1 ومثال على Legacy IDL في واجهة مستخدم Solana Explorer. في هذه المعاملة yيمكنك رؤية التعليمة المفكوكة للعبة 2048، بما فيها pushInDirection واتجاهها.

يمكنك فك تشفير التعليمات وبيانات الحسابات في عميل TypeScript الخاص بك باستخدام مساعدات Solana JS.

تتبع تغييرات الحسابات

يمكنك بسهولة الاشتراك في تغييرات الحسابات في برنامجك باستخدام أنواع TypeScript المُولَّدة.

import { Connection } from "@solana/web3.js";
const connection = new Connection("https://api.devnet.solana.com");

// Fetch account once
const account = await program.account.counter.fetch(counterPda);

// Subscribe via websocket to account changes
program.account.counter.subscribe(counterPda).on("change", (account) => {
  console.log("Account changed:", account);
});

// Or use decoder to decode any account or instruction data
connection.onAccountChange(counterPda, (accInfo) => {
  console.log(
    "Account changed:",
    program.coder.accounts.decode("counterData", account.data)
  );
});

لتعريفات الأحداث والاشتراكات وفك تشفير السجلات وCPI والتعبئة الخلفية والإصدار والاختبار، راجع Anchor Events.

فك تشفير المعاملات

يمكنك أيضاً فك تشفير المعاملات في عميلك باستخدام مساعدات Solana JS. سيمنحك هذا كائناً محدد الأنواع للمعاملة بأكملها.

بناء عميلك الخاص

باستخدام IDL يمكنك إنشاء عميلك الخاص بالعديد من اللغات. ما عليك سوى إيجاد برنامج تريد التفاعل معه، وتنزيل ملف IDL الخاص به، ثم توليد عميل بلغتك المفضلة.

إليك مثال على كيفية توليد عميل بلغة TypeScript.

ملفات IDL في Anchor

إذا كنت تستخدم إطار عمل Anchor:

• يتم توليد ملف IDL تلقائياً عند بناء برنامجك.
• يوجد في المسار target/idl/<program>.json.
• يتم توليد أنواع TypeScript في target/types/<program>.ts.
• يُخزَّن عنوان البرنامج في ملف IDL (idl.address).

anchor build
cat target/idl/counter.json

تشريح ملف IDL

إليك مثال مبسّط (مواصفة Anchor v0.30+):

{
  "address": "6khKp4BeJpCjBY1Eh39ybiqbfRnrn2UzWeUARjQLXYRC",
  "metadata": {
    "name": "counter",
    "version": "0.1.0",
    "spec": "0.1.0"
  },
  "instructions": [
    {
      "name": "increment",
      "discriminator": [11, 18, 104, 9, 104, 174, 59, 33],
      "accounts": [{ "name": "counter", "writable": true }],
      "args": []
    }
  ],
  "accounts": [
    {
      "name": "Counter",
      "discriminator": [255, 176, 4, 245, 188, 253, 124, 25]
    }
  ],
  "types": [
    {
      "name": "Counter",
      "type": {
        "kind": "struct",
        "fields": [{ "name": "count", "type": "u64" }]
      }
    }
  ]
}

• address: معرّف البرنامج على السلسلة.
• metadata: { name, version, spec, ... } معلومات حول البرنامج/الواجهة.
• instructions: الأساليب القابلة للاستدعاء مع accounts وargs و discriminator.
• accounts: أنواع الحسابات التي يكشفها البرنامج (مع المميزات).
• types: أسماء بديلة للهياكل والتعدادات والأنواع المرجعية في التعليمات/الحسابات.
• events / errors / constants: تعريفات اختيارية للأحداث ورموز الخطأ والثوابت.

ملاحظة: قدّم Anchor v0.30 مواصفة IDL جديدة. كانت ملفات IDL القديمة (قبل 0.30) تستخدم حقولاً مثل name وversion على المستوى الأعلى وisMut/isSigner في الحسابات. يمكنك تحويل ملفات IDL القديمة باستخدام anchor idl convert أو إعادة البناء باستخدام Anchor v0.30+. إذا كنت بحاجة إلى تحويل ملف IDL قديم إلى المواصفة الجديدة أثناء التشغيل، يمكنك أيضاً استخدام كود التحويل. هذا مفيد مثلاً إذا كنت تدير مستكشف سولانا وتريد الحفاظ على التوافق مع الإصدارات القديمة.

عميل TypeScript

سيقوم Anchor أيضاً بتوليد عميل TypeScript تلقائياً. يمكنك إيجاد العميل المُولَّد في مجلد target/types.

ثم في عميلك (TypeScript، v0.30+) يمكنك استدعاء تعليمات البرنامج وجلب الحسابات بسهولة كالتالي:

import { AnchorProvider, Program } from "@coral-xyz/anchor";
import idl from "./counter.json";

const provider = AnchorProvider.local();
const program = new Program(idl, provider);
await program.methods.increment().rpc();

عميل C#

لتوليد عميل C# يمكنك استخدام الأمر التالي:

cd program
dotnet tool install Solana.Unity.Anchor.Tool <- run once
dotnet anchorgen -i target/idl/counter.json -o target/idl/Counter.cs

يمكنك قراءة المزيد حول كيفية التفاعل مع عميل C# من Unity في الإعداد المسبق لألعاب سولانا أو في توثيق الألعاب.

عميل Python

بالنسبة لـ Python يمكنك استخدام مكتبة AnchorPy.

ستتوفر مولّدات عملاء إضافية باستخدام محوّلات Codama في المستقبل.

ملفات IDL بدون Anchor

ليست جميع البرامج مبنية باستخدام Anchor.
بالنسبة لبرامج سولانا الأصلية:

• أداة تُسمى Codama قيد التطوير حالياً لتوليد ملفات IDL من Rust عبر الماكرو أو بتحويل ملفات IDL الخاصة بـ Anchor. إليك مثال قيد التطوير لـ Codama Macros لتوليد ملف Codama IDL. يحوّل Codama ملفات IDL الخاصة بـ Anchor/Shank إلى ملف Codama IDL. للحصول على ملف Anchor IDL، قم بتوليده مع Anchor (أو استخدم anchor idl convert للمشاريع القديمة).
• حتى تصبح ماكرو Codama جاهزة تماماً، يمكنك أيضاً استخدام Metaplex Shank لتوليد ملف Shank IDL ثم تحويله إلى ملف Codama IDL.
• يمكنك أيضاً كتابة ملف IDL يدوياً (بتنسيقات Anchor أو Codama) لكن هذا ليس موثوقاً بالكامل. أدوات الذكاء الاصطناعي مثل Cursor يمكنها مساعدتك في كتابة ملف IDL، لكن يجب دائماً التحقق منه مقارنةً بالكود المصدري للبرنامج، والأفضل هو استخدام Anchor أو Codama أو Metaplex Shank.

تخزين ملفات IDL على السلسلة

هناك طريقتان لرفع ملفات IDL على السلسلة. الأكثر استخداماً والمعيارية هي حساب Anchor IDL. تتيح لك Anchor رفع ملفات IDL على السلسلة عن طريق إضافة تعليمات إضافية إلى برنامجك تمكّنك من رفع وتحديث ملفات IDL على السلسلة. يُضيف هذا حجماً إضافياً للبرنامج، ولهذا السبب تم إنشاء برنامج البيانات الوصفية للبرنامج. في برنامج البيانات الوصفية تُخزَّن جميع ملفات IDL ومعلومات security.txt كالاسم وجهة الاتصال والأيقونة في عناوين PDA الخاصة بـ برنامج البيانات الوصفية.

حساب Anchor IDL

يحفظ Anchor ملفات IDL على السلسلة في عنوان PDA خاص ببرنامجك.

• يمكن رفع ملفات IDL على السلسلة إلى حساب Anchor IDL.
• يتيح هذا للمستكشفين والمحافظ وحزم SDK جلب ملف IDL مباشرةً من سولانا.

المرة الأولى (تهيئة حساب IDL):

anchor idl init <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

الترقيات (التحديثات اللاحقة من قِبل الجهة المخوّلة):

anchor idl upgrade <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

أوامر مفيدة ذات صلة:

anchor idl fetch -o idl.json <PROGRAM_ID>
anchor idl authority <PROGRAM_ID>
anchor idl set-authority -p <PROGRAM_ID> -n <NEW_AUTHORITY>
anchor idl erase-authority -p <PROGRAM_ID>

لاحظ أن توليد حساب Anchor IDL هو بدون إذن مسبق بشكل افتراضي. لذا ارفع ملف IDL الخاص بك في أقرب وقت ممكن ثم قم بتعيين جهة مخوّلة.

يمكنك قراءة المزيد حول حساب Anchor IDL في توثيق Anchor.

برنامج البيانات الوصفية للبرنامج (PMP)

برنامج البيانات الوصفية هو برنامج يتيح لك تخزين ملفات IDL ومعلومات security.txt كالاسم وجهة الاتصال والأيقونة على السلسلة. سيكون هذا على الأرجح الطريقة المعيارية لتخزين ملفات IDL على السلسلة في المستقبل.

npx @solana-program/program-metadata write idl <program-id> ./idl.json

يمكنك قراءة المزيد حول برنامج البيانات الوصفية في توثيق برنامج البيانات الوصفية.

ملاحظة: حتى آخر تحديث لهذه المقالة، لا يدعم PMP جميع المستكشفين بعد.

أفضل الممارسات

أفضل ممارسة لنشر البرامج هي استخدام Multisig مثل Squads، ولتسهيل هذه العملية قدر الإمكان يمكنك استخدام سير عمل GitHub Actions لسولانا.

بهذه الطريقة سيتم ترقية البرنامج تلقائياً، ورفع ملف IDL، والتحقق من البناء، ثم اقتراح معاملة لتوقيعها ونشر البرنامج عبر Multisig الخاص بك.

1. حافظ على تحديث ملفات IDL ← قم دائماً بتحديث ملف IDL عند إجراء تغييرات على برنامجك.
2. ارفع ملفات IDL على السلسلة ← لضمان الشفافية ودعم الأدوات.
3. وثّق الأخطاء المخصصة ← يُحسّن تجربة المستخدم للعملاء.
4. تحقق من عمليات البناء ← تأكد من تطابق ملف IDL مع البرنامج المنشور.

إصدار ملفات IDL

حالياً مع Anchor لا يمكنك سوى امتلاك إصدار واحد من ملف IDL على السلسلة في أي وقت. هذا يعني أنك إذا أردت إجراء تغييرات على برنامجك فستحتاج إلى رفع إصدار جديد من ملف IDL، ويُفضَّل أن يكون ذلك في نفس وقت ترقية البرنامج. قد يؤدي هذا إلى مشاكل إذا لم يتم تحديث العملاء بعد، وهو أحد أسباب كتابة برنامج البيانات الوصفية. مع PMP ستتمكن من امتلاك بذور مختلفة لبرنامجك وإجراء الإصدار بهذه الطريقة. التصميم الخاص بذلك لم يُحسم بالكامل بعد وهو مفتوح للنقاش.

مزيد من المطالعة

• توثيق Anchor حول IDLs ← يولّد ملفات IDL والعملاء تلقائياً. (TypeScript، C#، Python)
• Codama ← أدوات IDL + مولّدات العملاء (Rust، JS/TS، Umi/Kit، إلخ).
• برنامج البيانات الوصفية ← تخزين ملفات IDL ومعلومات security.txt على السلسلة.

هذه هي أساسيات ملفات IDL على سولانا. إنها الجسر بين البرامج على السلسلة وعملاء خارج السلسلة، مما يُتيح المنظومة الغنية من الأدوات وحزم SDK التي تراها اليوم.