المعاملات ذات الإصدارات

تدعم سولانا ثلاث صيغ للمعاملات: legacy وv0 وv1. يُوصف كلٌّ منها أدناه بالأجزاء الثلاثة ذاتها: كيفية ترتيب بياناته على السلك، وكيفية الإشارة إلى الحسابات، ومصدر حدود موارده.

مقارنة الصيغ

انتقل إلى: Legacy · v0 · v1

صيغة Legacy

الصيغة الأصلية، ولا تزال الافتراضية في معظم الأدوات. لا تحتوي على بادئة إصدار على الإطلاق: البايت الأول من المعاملة هو عدد compact-u16 لمصفوفة التوقيعات، والبايت الأول من الرسالة هو num_required_signatures الذي تكون بتته العليا دائماً غير مضبوطة.

تخطيط سلك Legacy

كل مصفوفة متغيرة الطول تُسبق بطول compact-u16: بايت واحد للقيم من 0 إلى 127، و2–3 بايتات للقيم الأكبر. للاطلاع على تخطيط التعليمة الفردية وحساب حجم عملي، انظر الصيغة الثنائية للمعاملة.

الحسابات في Legacy

يُكتب كل حساب كمفتاح عام كامل بطول 32 بايت في account_keys، وتُشير إليه التعليمات بمؤشر أحادي البايت في تلك المصفوفة. لا توجد طريقة للإشارة إلى حساب غير مُدرج صراحةً في المعاملة، وهذا ما يحدّ معاملة legacy بحوالي 32 حساباً قبل أن تنفد الـ 1,232 بايت.

حدود الموارد في Legacy

يُطلب تحديد حد وحدات الحوسبة، وحد حجم بيانات الحسابات المُحمَّلة، وحجم الكومة، ورسوم الأولوية، بإدراج تعليمات برنامج ComputeBudget في المعاملة. يكلّف كل منها فتحة تعليمة slot و150 وحدة حوسبة. الحذف آمن: يعود وقت التشغيل إلى القيم الافتراضية وهي 200,000 وحدة حوسبة لكل تعليمة (بحد أقصى 1.4M)، وحد حجم بيانات 64 ميبيبايت، وكومة 32 كيبيبايت، ورسوم أولوية بقيمة صفر.

صيغة V0

v0 هي رسالة legacy مضافاً إليها أمران: بايت بادئة إصدار 0x80 ومصفوفة address_table_lookups تُلحق بعد التعليمات. كل ما قبل ذلك مطابق بالبايت لصيغة legacy.

تخطيط سلك V0

يحتوي كل إدخال في جدول البحث عن العناوين على:

جداول بحث العناوين

ALT هو حساب على السلسلة يخزن ما يصل إلى 256 مفتاحاً عاماً. من خلال الإشارة إلى ALT، يمكن للمعاملة تضمين حسابات إضافية باستخدام فهارس بحجم 1 بايت بدلاً من المفاتيح العامة بحجم 32 بايت، مما يقلل بشكل كبير من العبء لكل حساب.

في وقت التشغيل، قبل بدء التنفيذ، يقوم المدقق بتحليل جميع مراجع ALT إلى مفاتيح عامة كاملة. يتم إلحاق العناوين المحللة بمفاتيح الحسابات الثابتة لتشكيل قائمة مفاتيح الحسابات الكاملة. تتبع الحسابات المحللة من ALT نفس الترتيب الخاص بالحسابات الثابتة: تأتي عمليات البحث القابلة للكتابة قبل عمليات البحث للقراءة فقط.

حدود الموارد في v0

لم تتغير عن legacy: تعليمات ComputeBudget، مع القيم الافتراضية ذاتها عند حذفها.

صيغة V1

ترفع v1 حد الحجم إلى 4,096 بايت وتعيد هيكلة الرسالة حول إعداد المعاملة: تنتقل حدود الموارد من تعليمات ComputeBudget إلى حقول ذات موضع ثابت في الرسالة نفسها. يتيح ذلك للشبكة ترتيب المعاملات حسب رسوم الأولوية بقراءة واحدة ذات إزاحة ثابتة بدلاً من فحص قائمة التعليمات وفك تسلسلها.

تخطيط سلك V1

ثمة فارقان هيكليان عن legacy وv0 يستحقان الانتباه عند كتابة مُفككّ ترميز. الأعداد حقول u8 ذات عرض ثابت بدلاً من compact-u16، والتعليمات مقسّمة إلى جريانين: كل الرؤوس ذات الحجم الثابت أولاً، ثم كل الحمولات متغيرة الطول، بدلاً من أن تكون كل تعليمة متتالية.

الحسابات في v1: بدون جداول بحث العناوين

تزيل v1 دعم ALT بشكل مقصود. 64 عنواناً خاماً تبلغ 2,048 بايت، وهو ضمن حد الـ 4,096 بايت بمريح، لذا كل عنوان مضمّن كما هو في legacy. إذا كان تطبيقك يعتمد على جداول البحث، فإن الانتقال إلى v1 يعني تضمين تلك العناوين.

حدود الموارد في v1: إعداد المعاملة

الإعداد هو قناع بتات u32 يعقبه قيم ذات عرض ثابت لكل حقل مضبوطة بتّته:

تُرفض البتات غير المعروفة. ونظراً لأن الرسالة موقّعة، لا يمكن حذف حقول الإعداد غير المعروفة بصمت.

تعليمات ComputeBudget لا تؤثر في v1

لا ترفض معاملة v1 تعليمات ComputeBudget — بل تتجاهلها للإعداد. لا تزال تُنفَّذ كعمليات ناجحة لا أثر لها، تستهلك 150 وحدة حوسبة وفتحة واحدة من فتحات التعليمات الـ 64، دون أي تأثير على الميزانية. احذفها عند بناء معاملات v1، وتوقف عن البحث عنها عند قراءة معاملات v1: القيم موجودة في إعداد الرسالة.

يجب ضبط حقول الإعداد صراحةً

أهم تغيير سلوكي للمُرسِلين: خلافاً لـ legacy وv0، يجب على معاملات v1 ضبط حد وحدات الحوسبة وحد حجم بيانات الحسابات المُحمَّلة صراحةً، وإلا فستفشل معاملتك.

النهج الموصى به هو المحاكاة مرة واحدة مع رفع كلا الحدين إلى الأقصى، ثم كتابة unitsConsumed وloadedAccountsDataSize المُعادَين في الإعداد، مع تقريب حجم البيانات إلى أعلى صفحة 32 كيبيبايت لإبقاء هامش (يتقاضى نموذج تكلفة الكتلة وفق صفحات 32 كيبيبايت، لذا فأي هامش دون حدود الصفحة التالية مجاني).

الاستعداد لـ v1

تُغيّر v1 طريقة قراءة المعاملات، لا إرسالها فحسب. عند تفعيل v1، سيبدأ أي عميل يستدعي getTransaction أو getBlock دون الاشتراك في الدعم بالفشل عند معاملات v1:

• مرّر maxSupportedTransactionVersion: 1 — العدد الصحيح JSON الصحيح 1، لا السلسلة النصية "1" — إلى getTransaction وgetBlock. تمرير 0 يُفشل معاملات v1 تماماً كحذف المعامل، لذا قد تحتاج قاعدة التعليمات البرمجية المحدَّثة إبان طرح v0 إلى تغيير القيمة.
• getTransaction يفشل عند معاملة v1 بالخطأ -32015، ومعاملة v1 واحدة تُفشل استجابة getBlock بأكملها بالخطأ ذاته — لا يوجد نتيجة جزئية.
• blockSubscribe يُصدر block: null ويتوقف عن التقدم، لذا قد يُفسّر مستهلك يعتبر ذلك كتلة فارغة أنه يتأخر بصمت اعتباراً من أول slot لـ v1.
• getSignaturesForAddress لا يفحص أجسام المعاملات أبداً، لذا تظهر توقيعات v1 بشكل طبيعي.
• تتضمن الاستجابات المُشترَكة كائن transactionConfig في الرسالة لمعاملات v1 (غائب كلياً لـ legacy وv0). ستُبلّغ مسارات معالجة البيانات التي تستخرج رسوم الأولوية أو حدود الحوسبة بفحص تعليمات ComputeBudget عن صفر بصمت لكل معاملة v1.
• استخدم encoding: 'base64' عند فك ترميز المعاملات من جانب العميل، وكذلك مع sendTransaction/simulateTransaction للمعاملات التي تتجاوز 1,232 بايت — يظل ترميز base58 محدوداً بالحجم القديم.
• دعم مكتبات العميل يتطلب إصدارات حديثة: @solana/kit الإصدار 8.0 فأعلى، أو حزم Rust من جيل Agave 4.2.x، أو web3.js v3. يقرأ web3.js v1 معاملات v1 اعتباراً من الإصدار 1.99.0، لكنه لا يستطيع بناءها أو إرسالها.

للاطلاع على دليل الترحيل الكامل — بما في ذلك دعم مكتبات العميل، واكتشاف الإصدار في البث المباشر (Geyser/gRPC)، وسلوك المحاكاة — راجع صفحة ترقية صيغة المعاملة v1.