DEV Community

Cover image for tx-explainer: اقرأ معاملة Solana بلغة بسيطة
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

tx-explainer: اقرأ معاملة Solana بلغة بسيطة

العثور على معاملة (transaction) في Solana سهل، لكن قراءتها صعبة. المستكشف (explorer) يعطيك توقيعًا (signature)، وقائمة من مفاتيح الحسابات، وتعليمات (instructions) بياناتها سلسلة من البايتات. لتعرف ما الذي حدث فعلًا، عليك أن تتذكر أن أول بايت في تعليمة Token هو وسم (tag)، وأن المبالغ أعداد صحيحة بترتيب little-endian وبلا فاصلة عشرية، وأن برنامج Anchor يخفي اسم التعليمة خلف discriminator من 8 بايتات.

tx-explainer يقوم بهذه القراءة مكانك. تعطيه توقيعًا، أو بايتات المعاملة الخام، أو ردّ getTransaction محفوظًا في ملف، فيطبع ما فعلته كل تعليمة في جمل بسيطة، ثم الرسوم، ووحدات الحساب (compute units)، وتغيّرات الأرصدة.

هو أداة فك ترميز للقراءة فقط: لا يوقّع ولا يرسل أي شيء أبدًا. والـ README صريح في حدوده: المشروع لم يخضع لتدقيق أمني (not audited)، وهو موجّه أولًا إلى devnet وtestnet وlocalnet، والنص المبسّط اجتهاد قدر الإمكان ولا يغني عن قراءة كود البرنامج.

ماذا يقدّم

هذا ناتج الأداة على معاملة حقيقية من devnet موجودة ضمن ملفات الاختبار:

$ tx-explainer --file test/fixtures/devnet-memo.json
Transaction 5zhK…  [legacy]
Status: succeeded
Fee: 0.0000155 SOL (of which priority ≈ 0.0000105 SOL)
Compute units: 26,021 of 70,000 requested

What happened:
  1. [Compute Budget] Set compute unit limit to 70,000
  2. [Compute Budget] Set priority fee to 150,000 micro-lamports per compute unit
  3. [Associated Token Account] Create (if missing) the associated token account Expy…TCA6 for wallet 6a1w…BNqd and mint 4wMp…jY4y, paid by 2VyJ…TeEs (fee payer)
  4. [SPL Token] Transfer 1,236.871165 tokens of mint 4wMp…jY4y from 55Xo…AmDQ to Expy…TCA6 (authority 2VyJ…TeEs (fee payer))
  5. [Memo] Memo: "helm-payout-v1:…"

Token balance changes:
  55Xo…AmDQ (owner 2VyJ…TeEs): -1,236.871165 of mint 4wMp…jY4y
  Expy…TCA6 (owner 6a1w…BNqd): +1,236.871165 of mint 4wMp…jY4y
Enter fullscreen mode Exit fullscreen mode

البرامج المدمجة. الأداة تعرف البرامج التي تظهر في أغلب المعاملات:

  • System: التعليمات CreateAccount وAssign وTransfer وCreateAccountWithSeed، وعمليات الـ nonce، وAllocate وTransferWithSeed.
  • SPL Token وToken-2022: تهيئة الـ mint والحسابات، وTransfer وTransferChecked، وApprove وRevoke وSetAuthority وMintTo وBurn وCloseAccount وFreeze وThaw وSyncNative وغيرها. أما تعليمات امتدادات Token-2022 فتُذكر برقمها فقط.
  • Associated Token Account: التعليمات Create وCreateIdempotent وRecoverNested.
  • Compute Budget: التعليمات SetComputeUnitLimit وSetComputeUnitPrice وRequestHeapFrame وSetLoadedAccountsDataSizeLimit.
  • Memo (الإصداران v1 وv2)، ويُعرض كنص UTF-8.

أي برنامج Anchor عبر الـ IDL. مرّر ملف IDL الخاص بالبرنامج بالخيار --idl (صيغة Anchor 0.30 وما بعدها)، فتعرض الأداة اسم التعليمة، والوسائط بعد فك ترميز Borsh (structs وenums وvec وoption والمصفوفات)، وأسماء الحسابات، وأسماء الأخطاء المخصّصة إن فشلت المعاملة.

بيانات الـ RPC الوصفية (metadata). عندما يأتي الإدخال من getTransaction، يضمّ الناتج أيضًا الحالة (مع أسماء أخطاء Anchor)، والرسوم، وتقديرًا لرسوم الأولوية (priority fee) يساوي حد وحدات الحساب × سعر الوحدة، ووحدات الحساب المستهلكة، والتعليمات الداخلية (CPIs)، وتغيّرات رصيد SOL، وتغيّرات أرصدة التوكنات بالخانات العشرية الصحيحة.

رسائل legacy وv0. الصيغتان مدعومتان. عناوين جداول البحث (address lookup tables) تُحلّ من meta.loadedAddresses. وفي الإدخال الخام، حيث لا توجد هذه البيانات، تُعرض بالشكل table[index].

ثلاث طرق للتشغيل. نفس منطق فك الترميز متاح كأداة سطر أوامر (CLI)، وكمكتبة TypeScript، وكواجهة ويب صغيرة تعمل كليًا داخل المتصفح وتتصل مباشرة بالـ RPC العام للشبكة المختارة. يضع الـ README رابطًا لنسخة تجريبية حية من هذه الواجهة: https://abdeldjalilchougui.github.io/tx-explainer/.

طريقة الاستعمال

تحتاج Node.js 20 أو أحدث. انسخ المستودع ثم ابنِه:

git clone https://github.com/AbdeldjalilChougui/tx-explainer
cd tx-explainer
pnpm install
pnpm build
Enter fullscreen mode Exit fullscreen mode

ثم شغّل الـ CLI من مجلد المشروع:

node dist/cli.js <signature> --cluster devnet           # fetch via getTransaction
node dist/cli.js <signature> --rpc http://127.0.0.1:8899
node dist/cli.js --raw <base64-or-base58 tx bytes>      # offline, no metadata
node dist/cli.js --file saved-getTransaction.json --idl target/idl/my_program.json
node dist/cli.js ... --json                             # machine-readable
node dist/cli.js serve --port 8787                      # web UI on 127.0.0.1
Enter fullscreen mode Exit fullscreen mode

الشكلان الأولان يجلبان المعاملة من شبكة أو من الـ validator المحلي. الخيار --raw يعمل بلا اتصال على بايتات بصيغة base64 أو base58. والخيار --file يقرأ ردّ getTransaction محفوظًا، وهذا مفيد في تقارير الأخطاء والاختبارات. أما --json فيعطي نفس الشرح كبيانات منظّمة يستطيع سكربت أن يقرأها.

وكمكتبة، ثلاث دوال تغطي الحالة الشائعة:

import { explain, render, fetchTransaction } from "tx-explainer";
const e = explain({ rpc: await fetchTransaction(sig, "https://api.devnet.solana.com") }, { idls: [myIdl] });
console.log(render(e));
Enter fullscreen mode Exit fullscreen mode

الدالة fetchTransaction تجلب المعاملة، وexplain تبني الشرح المنظّم، وrender تحوّله إلى النص الذي رأيته في الأعلى.

كيف يعمل من الداخل

يصف الـ README أربع وحدات صغيرة، ومعرفة هذا التقسيم تفيدك إن أردت إضافة decoder جديد:

  1. الملف message.ts يحلّل صيغة الإرسال (wire format) يدويًا: أطوال compact-u16، والتواقيع، وترويسة الرسالة، ومفاتيح الحسابات، والتعليمات المجمّعة، وجداول البحث في v0. ثم يستنتج من الترويسة إن كان كل مفتاح موقّعًا (signer) أو قابلًا للكتابة (writable).
  2. الملف programs.ts فيه decoder صغير لكل برنامج مدمج. كل واحد يقرأ وسم التعليمة (u32 في System وu8 في Token) وحقولها بواسطة Reader يعمل بترتيب little-endian.
  3. الملف anchor.ts يقارن أول 8 بايتات من بيانات التعليمة مع الـ discriminator لكل تعليمة في الـ IDL، ثم يفك ترميز الوسائط بـ Borsh انطلاقًا من شجرة الأنواع في الـ IDL.
  4. الملف explain.ts يجمع كل ذلك مع بيانات الـ RPC: أرصدة التوكنات تعطي الـ mint وعدد الخانات العشرية، والتعليمات الداخلية تعطي الـ CPIs، والأرصدة قبل وبعد تعطي الفروقات.

ما يجب معرفته

  • غير مدقَّق، والناتج اجتهاد. الجمل وسيلة مساعدة لقراءة المعاملة. لا تغني عن قراءة كود البرنامج، ولا ينبغي أن تبني عليها وحدها قرارًا يخص أموالًا حقيقية.
  • امتدادات Token-2022 تُعرض برقمها فقط. رسوم التحويل، والتحويلات السرّية، وباقي تعليمات الامتدادات لا تُحوَّل إلى جمل.
  • بعض البرامج يُذكر اسمها فقط. تعليمات Stake وVote وAddress Lookup Table والـ loader تُعرَّف بالاسم دون فك ترميزها.
  • رسوم الأولوية تقديرية. تُحسب بالصيغة ceil(limit × price / 1e6). وإن لم تحدّد المعاملة حدًّا، تفترض الأداة القيمة الافتراضية: 200 ألف وحدة حساب لكل تعليمة.
  • الإدخال الخام بلا بيانات وصفية. مع --raw لا توجد حالة ولا رسوم ولا تغيّرات أرصدة ولا تعليمات داخلية، لأن هذه المعلومات تأتي من الـ RPC وليس من بايتات المعاملة.
  • ما تم اختباره. الأمر pnpm test يستعمل فقط ملفات محفوظة في test/fixtures/. أربع منها معاملات اصطناعية يبنيها سكربت بمكتبة @solana/web3.js من مفاتيح عامة ثابتة. تُترك بلا توقيع، فلا يُنشأ أي keypair، وتحمل بيانات وصفية مكتوبة يدويًا: تحويل SOL مع memo وcompute budget، وإنشاء ATA مع TransferChecked وCPIs، وعملية mint بـ Token-2022 عبر lookup table في رسالة v0، ونداء Anchor فاشل. والخامسة معاملة حقيقية واحدة من devnet، التُقطت مرة واحدة عبر RPC للقراءة فقط.

لماذا بنيته

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

أردت أداة واحدة تقوم بهذه الخطوات بنفس الطريقة في كل مرة، وتعمل على validator محلي كما تعمل على devnet، وتعمل بلا اتصال على البايتات الخام، ويمكن استعمالها من الطرفية (terminal) أو من الكود أو من تبويب في المتصفح. وتحليل صيغة الإرسال يدويًا، بدل إخفائها خلف مكتبة كبيرة، يُبقي الكود صغيرًا يمكن قراءته وتوسيعه.

الكود

الكود، وملفات الاختبار، والاختبارات، وواجهة الويب موجودة على GitHub: https://github.com/AbdeldjalilChougui/tx-explainer. الرخصة MIT، والـ issues والـ pull requests مرحّب بها، خصوصًا إضافة decoders للبرامج التي يُذكر اسمها فقط حاليًا.


نُشر في الأصل على abdeldjalilchougui.biz.

Top comments (0)