برنامج Anchor يصف نفسه في ملف IDL: تعليماته (instructions)، وحساباته، وأنواعه، وأحداثه، وأخطاؤه، وبذور (seeds) عناوين الـ PDA. جهة البرنامج تولّدها لك macros الخاصة بـ Anchor. أما جهة العميل (client) فمنها يبدأ العمل اليدوي. على أحدهم أن يكتب الدالة التي تحوّل الوسائط بترميز Borsh، وتضع أمامها الـ discriminator المكوّن من 8 بايتات، وترتّب الحسابات بالترتيب الصحيح مع أعلام signer وwritable الصحيحة، وتشتق عناوين الـ PDA من نفس البذور التي يستعملها البرنامج.
كتابة ذلك مرة واحدة أمر مقبول. لكن كتابته مرتين، بـ TypeScript لتطبيق الويب وبـ Dart لتطبيق Flutter، تعني نسختين يجب أن تبقيا متطابقتين مع البرنامج ومع بعضهما. وبايت واحد خاطئ في إحداهما يعطي معاملة تفشل على السلسلة برسالة خطأ لا تشرح الكثير.
idl-codegen يقرأ ملف Anchor IDL (مواصفة 0.30 وما بعدها) ويكتب العميلين معًا. والـ README يبدأ بتحذير يجب ذكره هنا أيضًا: المشروع لم يخضع لتدقيق أمني. العملاء المولَّدون يبنون التعليمات ويفكّون ترميز الحسابات، ولا يوقّعون ولا يرسلون شيئًا. راجع الكود المولَّد مقابل برنامجك قبل استعماله مع أموال حقيقية، وجرّب على devnet أولًا.
ماذا يقدّم
أمر واحد ينتج مجموعتين من الملفات:
-
TypeScript: الملفان
<name>.tsوborsh.ts، ويعتمدان على@solana/web3.jsv1. -
Dart: الملفان
<name>.dartوborsh.dart، ويعتمدان علىpackage:crypto، وهما موجّهان لتطبيقات Flutter.
كل عميل يحتوي نفس المكوّنات.
معرّف البرنامج. الثابت PROGRAM_ID في TypeScript و<name>ProgramId في Dart.
الأنواع. في TypeScript تحصل على interfaces، وعلى الـ enums في شكل اتحادات { kind: ... }، وعلى دوال encodeX / decodeX. وفي Dart تحصل على أصناف (classes) فيها encode وstatic decode. الـ enums التي بلا بيانات تصبح enum عادية في Dart، والتي تحمل بيانات تصبح أصنافًا من نوع sealed.
بناء التعليمات. الدالة createXInstruction(accounts, args) تُرجع TransactionInstruction في TypeScript. ونسخة Dart تأخذ وسائط مسمّاة وتُرجع Instruction. الحسابات التي لها address ثابت في الـ IDL، مثل System Program، تأخذه كقيمة افتراضية. والحسابات الاختيارية تأخذ معرّف البرنامج كقيمة افتراضية، وهذا عُرف Anchor للتعبير عن "None".
فك ترميز الحسابات. الدالة decodeXAccount(data) تتحقق من الـ discriminator قبل الفك، وفي TypeScript توجد أيضًا isXAccount.
الأحداث (events). الدالة decodeXEvent(data) في اللغتين.
دوال PDA. الدالة findXPda(...seeds) تُولَّد من pda.seeds في الـ IDL: البذور الثابتة، وبذور الحسابات، وبذور الوسائط، وحالات seeds::program مثل حسابات التوكن المرتبطة (ATA). وعميل Dart يأتي بدالة findProgramAddress خاصة به.
الأخطاء والثوابت. في TypeScript: ERRORS و<Name>Error.fromCode(). وفي Dart: <name>Errors و<Name>Exception.fromCode(). ومعها قيم #[constant] المعرّفة في البرنامج.
تحويل الأنواع يتبع نفس الفكرة في الجهتين: u64 وi64 وu128 وi128 تصبح bigint / BigInt؛ والأعداد الصحيحة الأصغر تصبح number / int؛ وpubkey يصبح PublicKey / Pubkey؛ وbytes يصبح Uint8Array / Uint8List؛ وOption<T> يصبح T | null / T?. أما tuple structs وtuple variants فتصبح values: [...] في TypeScript وfield0, field1 في Dart.
طريقة الاستعمال
تحتاج Node.js 20 أو أحدث. انسخ المستودع وشغّل المولّد من مجلد المشروع:
git clone https://github.com/AbdeldjalilChougui/idl-codegen
cd idl-codegen
pnpm install
pnpm gen target/idl/my_program.json --ts app/src/generated --dart mobile/lib/generated
# or after `pnpm build`: node dist/cli.js <idl.json> --ts <dir> --dart <dir>
الوسيط الأول هو ملف الـ IDL الذي كتبه anchor build. والخياران --ts و--dart هما مجلدا الإخراج. كود TypeScript المولَّد يحتاج @solana/web3.js v1 في تطبيقك، وكود Dart المولَّد يحتاج package:crypto.
ثم في تطبيق الويب:
import { createIncrementInstruction, findCounterPda } from "./generated/counter_todo.js";
const [counter] = findCounterPda(wallet.publicKey);
const ix = createIncrementInstruction({ authority: wallet.publicKey, counter }, { by: 1n });
ونفس النداء في تطبيق Flutter:
import 'generated/counter_todo.dart';
final (counter, _) = findCounterPda(authority: me);
final ix = createIncrementInstruction(authority: me, counter: counter, by: BigInt.one);
المقطعان يشتقان نفس الـ PDA ويبنيان نفس بايتات التعليمة. التوقيع والإرسال يبقيان في كودك أنت، بالمحفظة وطبقة الـ RPC التي يستعملها تطبيقك أصلًا.
كيف اختُبر
الكود المولَّد لا ينفع إلا إذا وثقت في البايتات، ولهذا يدور أغلب قسم الاختبارات في الـ README حول هذه النقطة.
-
اختبارات golden. كل IDL في
test/fixtures/يُولَّد ثم يُقارن بايتًا ببايت معtest/golden/. الملفات هيcounter_todoوescrow، وهما IDL حقيقيان من مشاريع Anchor مجاورة، وkitchen_sinkالمكتوب يدويًا ليغطي كل الأنواع: مجموعات حسابات متداخلة، وحسابات اختيارية، وenums تحمل بيانات، وtuple structs، وu128/i128، وf64، ومصفوفات ثابتة الطول، وseeds::program. -
مترجمات صارمة. كود TypeScript المولَّد يمرّ من
tsc --strict، وكود Dart المولَّد يمرّ منdart analyze --fatal-infos. ويُتجاوز فحص Dart إن لم يكنdartموجودًا في الـ PATH. -
السلوك. دوال PDA تطابق
PublicKey.findProgramAddressSync، بما فيها عناوين ATA. بيانات التعليمة هي الـ discriminator متبوعًا بوسائط Borsh. والحسابات تمرّ بدورة encode ثم decode وتعود كما كانت، مع التحقق من الـ discriminator. -
بين اللغتين. برنامج Dart في
test/golden/dart/bin/check.dartيبني نفس التعليمات وعناوين PDA وبايتات الحسابات، والاختبار يتحقق من أن ناتجه يطابق عميل TypeScript بايتًا ببايت.
هذا الفحص الأخير كشف خطأً حقيقيًا. على Dart 3.9 VM كانت الدالة BigInt.modPow تُرجع نتائج خاطئة لبعض المدخلات ذات 255 بت، فتعطّل فحص وقوع النقطة على منحنى ed25519 الذي تعتمد عليه findProgramAddress. لذلك يستعمل كود Dart المولَّد الآن خوارزمية square-and-multiply خاصة به.
ما يجب معرفته
- غير مدقَّق. العملاء يبنون التعليمات ويفكّون البيانات فقط، لكن تعليمة خاطئة قد تحرّك أموالًا بعد أن توقّعها. قارن الناتج مع برنامجك وجرّبه على devnet أولًا.
-
الأنواع العامة (generics) مرفوضة. الـ IDL الذي يستعمل
genericsلا يُولَّد منه شيء. -
بعض بذور PDA تصبح بايتات خام. البذور التي تقرأ بيانات حساب (
path: "list.next_id") أو حقلًا من وسيط من نوع struct تتحول إلى وسيطbytesخام. وإن كانت تعليمة أخرى تشتق نفس الحساب من وسيط بسيط، يستعمل المولّد ذلك الشكل الأبسط. -
coptionلم يُختبر مع برنامج حقيقي. هو مدعوم في الترميز وفك الترميز، لا أكثر. -
ملفات IDL القديمة تحتاج تحويلًا. ملفات IDL السابقة لـ Anchor 0.30 يجب تحويلها أولًا بالأمر
anchor idl convert. -
web3.js v1. ناتج TypeScript موجّه إلى
@solana/web3.jsv1.
لماذا بنيته
المشكلة هي التكرار. ملف الـ IDL يحتوي أصلًا كل ما يحتاجه العميل: أنواع الوسائط، وترتيب الحسابات، والـ discriminators، والبذور، ورموز الأخطاء. كتابة العميل يدويًا تعني نسخ هذه المعلومات إلى كود، ثم نسخها مرة ثانية عندما يوجد تطبيق موبايل بـ Dart بجانب تطبيق ويب بـ TypeScript. بعدها يجب تكرار كل تغيير في البرنامج في مكانين، ولا شيء ينبّهك عندما يتأخر أحدهما عن الآخر.
توليد العميلين من نفس الـ IDL يلغي خطوة النسخ، ويجعل اختبار أحد الناتجين مقابل الآخر ممكنًا. إذا أنتج عميل TypeScript وعميل Dart نفس البايتات لنفس المدخلات، ووافق عميل TypeScript مكتبة @solana/web3.js في عناوين PDA، يضيق المجال كثيرًا أمام اختلاف صامت. وخطأ BigInt.modPow مثال جيد على قيمة هذه المقارنة: لا شيء في كود Dart كان يبدو خاطئًا، ولم تكشفه إلا مقارنة البايتات.
الكود
المولّد، وملفات الاختبار، وملفات golden، والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/idl-codegen. الرخصة MIT، والـ issues والـ pull requests مرحّب بها.
نُشر في الأصل على abdeldjalilchougui.biz.
Top comments (0)