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

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

لماذا تُعدّ IDLs مهمة

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

ما يمكنك فعله باستخدام IDLs

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

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

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

تحليل أحداث Anchor أو تغييرات الحسابات

يمكنك الاشتراك بسهولة في تغييرات الحسابات في برنامجك باستخدام أنواع 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)
  );
});

يمكنك مثلاً إصدار أحداث Anchor في برنامجك ثم تسجيل هذه الأحداث، أو كتابتها في قاعدة بيانات، أو استخدامها لإرسال رسالة إلى مجموعة تيليغرام على سبيل المثال.

// Emit the purchase event
emit!(PurchaseMade {
    buyer: *ctx.accounts.signer.key,
    product_name: name,
    price,
    timestamp: Clock::get()?.unix_timestamp,
    table_number,
    receipt_id,
    telegram_channel_id: ctx.accounts.receipts.telegram_channel_id.clone(),
    store_name: ctx.accounts.receipts.store_name.clone(),
    receipts_account: ctx.accounts.receipts.key(),
});

لذلك يمكنك استخدام مساعدات Solana JS لتحليل الأحداث. إليك مثال تطبيقي يستخدم أحداث Anchor لنشر الرسائل في مجموعة تيليغرام.

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

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

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

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

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

IDLs في 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 جديدة. كانت IDLs القديمة (ما قبل 0.30) تستخدم حقولاً مثل name وversion على المستوى الأعلى، وisMut/isSigner في الحسابات. يمكنك تحويل IDLs القديمة باستخدام 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 في المستقبل.

IDLs بدون Anchor

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

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

تخزين IDLs على السلسلة

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

حساب Anchor IDL

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

• يمكن رفع IDLs على السلسلة إلى حساب 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 مثل الاسم وجهة الاتصال والأيقونة على السلسلة. من المرجح أن يصبح هذا الطريقة المعيارية لتخزين IDLs على السلسلة في المستقبل.

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

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

ملاحظة: حتى آخر تحديث للمقالة، لا يزال PMP غير مدعوم من قِبَل جميع المستكشفين.

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

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

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

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

إدارة إصدارات IDLs

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

قراءات إضافية

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

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