في 11 أكتوبر، صدر TON Connect 5.0.0، وهي مجموعة من المكتبات التي تستخدمها المواقع والتطبيقات المصغرة لربط محافظ TON. في نافذة اختيار المحفظة، أصبحت محفظة Telegram المدمجة الآن في المقدمة، كزر منفصل يحمل عنوان «ربط Telegram»، وتمت تسمية @wallet السابق باسم Walt. يوصي الفريق للمطورين الذين يعتمد تسجيل الدخول لديهم على توقيع ton_proof بمراجعة الخادم الخاص بهم مع الوثائق: فالعديد من التطبيقات المصغرة لا تستطيع التحقق من توقيع محفظة Telegram، وبالتالي لا يمكن للمستخدمين الذين يستخدمونها تسجيل الدخول.
ماذا يجب على المطور فعله
تحديث الحزم. تم نشر حزم @tonconnect/sdk و @tonconnect/ui و @tonconnect/ui-react بالإصدار 5.0.0، وبحلول مساء اليوم نفسه، تلقت حزم الواجهة الإصدار 5.0.1. لا يعني تغيير الرقم الرئيسي إعادة كتابة الكود: فوفقًا لسجل التغييرات، فإن الإصدار 5.0.0 هو نفس كود SDK 4.1.0 و UI 3.1.0، وقد تم توحيد الأرقام ببساطة لكي تتوافق الحزم الثلاث التي يتم تثبيتها معًا في إصدار واحد. إذا كنت تستخدم UI 3.0.x، فإن الانتقال إلى 5.0 يعادل الانتقال إلى 3.1 بكل تغييراته (المذكورة أدناه).
التحقق من جانب الخادم لـ ton_proof. هذا هو التوقيع الذي تثبت به المحفظة لخادم التطبيق عند الاتصال أن العنوان يخصها: يصدر الخادم سلسلة نصية لمرة واحدة، توقع المحفظة عليها بمفتاحها، ثم يجد الخادم المفتاح العام للمحفظة ويتحقق من التوقيع. تبحث التطبيقات النموذجية عن المفتاح في walletStateInit، وهي الحالة الأولية للعقد، والتي ترسلها المحفظة مع العنوان: تتعرف على المحفظة القياسية (v3، v4، v5) من خلال تجزئة الكود وتقرأ المفتاح من بياناتها. في محفظة Telegram، لا يجد هذا التحليل المفتاح، ويفشل التحقق.
وفقًا للتوثيق المحدث، تتطلب محفظة Telegram مسارًا منفصلاً:
- مقارنة تجزئة الكود في
walletStateInitمع تجزئة عقد الترامبولين WalletTg. - طلب حالة الحساب من الشبكة والتأكد من أنه نشط وأن نفس الترامبولين منتشر فيه.
- بعد ذلك فقط، استدعاء طريقة
get_public_keyمن العقد والتحقق من التوقيع باستخدام المفتاح المُعاد.
يجب رفض الحساب غير النشط، أو الكود غير المتطابق، أو الاستدعاء الفاشل وفقًا للوثائق. ويُشدد بشكل خاص على أن وجود طريقة get_public_key في العقد لا يثبت شيئًا بحد ذاته: لا يمكن استدعاؤها إلا من كود تم التحقق منه مقابل قائمة التطبيقات الموثوقة. إذا قام SDK بتمرير مفتاح في account.publicKey، فيجب أن يتطابق مع المفتاح الذي تم العثور عليه؛ وإذا لم يقم بتمريره، فهذا ليس سببًا لرفض التوقيع الذي تم التحقق منه بمفتاح من الشبكة.
التخطيط للمحفظة غير النشطة. يصبح الحساب في TON نشطًا مع أول معاملة صادرة: قبل ذلك، قد يكون هناك رصيد في العنوان، ولكن لا يوجد عقد هناك. محفظة Telegram، التي تم إنشاؤها للمستخدم عن طريق تحويل خارجي ولم يتم إرسال أي شيء منها بعد، لن تتمكن من تسجيل الدخول عبر ton_proof وفقًا لقواعد الوثائق. يجب أن تكون رسالة الخطأ في هذا المكان واضحة للمستخدم، وليس مجرد «تم رفض التوقيع».
إعادة تجميع معالجة الأخطاء. في SDK 4.1.0، أصبح error.name لجميع أخطاء المكتبة هو اسم الفئة (UserRejectsError وما إلى ذلك) بدلاً من "Error" السابق، ولم يعد يتشوه بالتقليص. ستنشئ أدوات تتبع الأخطاء التي تجمع حسب الاسم والنص مجموعات جديدة بعد التحديث. يأتي رد المحفظة برمز 400 الآن كـ MethodNotSupportedError جديد، وليس UnknownError؛ ويأتي الرد غير المفهوم من المحفظة المدمجة كـ WalletTransportError مع القيمة الأصلية في cause.
مراعاة عنوان التحميل الجديد. في UI 5.0.1، ظهرت بلورة ثلاثية الأبعاد فوق زر Telegram على الهاتف. يبلغ حجم النموذج حوالي 540 كيلوبايت ويتم تحميله ليس من الحزمة، بل من s.ton-connect.io؛ على جهاز ضعيف، إذا انخفضت الرسوم المتحركة إلى أقل من 20 إطارًا في الثانية، فتبقى صورة ثابتة بدلاً منها. تحتاج التطبيقات ذات سياسة التحميل الصارمة (CSP) إلى السماح بهذا العنوان أو قبول الصورة الثابتة.
ما الذي تغير في نافذة اختيار المحفظة
لا تحتفظ المكتبة بقائمة المحافظ بداخلها، بل تقوم بتحميلها في كل مرة يتم فيها الفتح من السجل العام config.ton.org/wallets-v2.json؛ تحتوي الحزمة فقط على نسخة احتياطية في حال عدم توفر السجل. لذلك، تغير ترتيب المحافظ في 11 أكتوبر لجميع التطبيقات في وقت واحد، بتعديل السجل، دون تحديث الكود. أضافت الحزم الجديدة إلى ذلك تخطيطًا: تم نقل محفظة Telegram و Gram Wallet إلى أزرار منفصلة فوق الصف العام للمحافظ، بدلاً من أن تكون ضمن البلاط مع البقية.
| المكان في السجل | الاسم في القائمة | ما هو | إلى أين يؤدي |
|---|---|---|---|
| 1 | Telegram | محفظة مدمجة في تطبيق المراسلة نفسه | t.me/sendgrams، جسر tonbridge.telegram.org |
| 2 | Gram Wallet | تطبيق منفصل لنظامي iOS و Android من موقع gramwallet.io | connect.gramwallet.io |
| 3 | Walt (ex. Wallet) | بوت @wallet السابق | t.me/walt |
| 4 | Keeper | Tonkeeper السابق | app.tonkeeper.com |
حتى 11 أكتوبر، كان بوت @wallet هو الأول في السجل، وتم إضافة إدخال «Telegram» في 15 سبتمبر إلى نهاية القائمة. كانت الإصدارات القديمة من UI ترسم زرًا ثابتًا «Wallet in Telegram» يؤدي إلى البوت. في الإصدارات الجديدة، تم تثبيت أماكن زرين فقط، ويتم أخذ الاسم والأيقونة والجسر والرابط من السجل، مثل أي محفظة أخرى.
يجب التمييز بين الأسماء. في المقالات والمحادثات، تُسمى محفظة Telegram المدمجة Gram Wallet، ويذكر إعلان TON Connect أيضًا «Gram Wallet in Telegram». ولكن في سجل TON Connect، تُسجل المحفظة المدمجة باسم Telegram، وتحت اسم Gram Wallet يوجد تطبيق جوال منفصل بجسره الخاص. يؤدي زر «ربط Telegram» إلى المحفظة المدمجة، ويؤدي الزر الشفاف تحته إلى التطبيق.
التسمية «Walt (ex. Wallet)» ليست إعادة تسمية جديدة. أصبح بوت محفظة TOP هو Walt في 28 سبتمبر، وغير السجل الاسم في 29 سبتمبر. في 11 أكتوبر، تمت إضافة الملاحظة «ex. Wallet» إلى الاسم، وتم تحويل الرابط إلى t.me/walt: يفتح نفس البوت أيضًا عبر @wallet. تنقل الواجهة الجديدة الملاحظة بين قوسين إلى السطر الثاني من البلاط، بحيث يرى المستخدم «Walt» وتحتها «ex. Wallet».
تم تصحيح الرابط الذي تفتح الواجهة من خلاله محفظة Telegram: بالنسبة للعنوان بدون اسم التطبيق المصغر، مثل t.me/sendgrams، كانت الإصدارات القديمة تضع السلسلة الحرفية appname=undefined في الرابط. دخل هذا التصحيح في UI 3.1.0، وبالتالي في 5.0 أيضًا.
لماذا لا تجتاز محفظة Telegram التحقق القديم
تعمل محفظة Telegram على عقد WalletTg، وهي مصممة بشكل مختلف عن المحافظ القياسية. لا يوجد عقد المحفظة نفسه في كل عنوان، بل يوجد ترامبولين صغير غير قابل للتغيير: ينقل التحكم إلى كود WalletTg، الذي يتم تخزينه في تكوين الشبكة تحت الفهرس -123 ويتغير فقط عن طريق تصويت المدققين. بهذه الطريقة، يصل الإصدار الجديد من المحفظة إلى جميع المستخدمين في وقت واحد، دون الحاجة إلى تحديث كل عقد.
من هنا يأتي فشل التحقق. يحتوي walletStateInit الخاص بمحفظة Telegram على كود الترامبولين، وليس كود المحفظة v4 أو v5 المعروف للمحلل، لذلك لا يجد جدول الإصدارات المفتاح. بالإضافة إلى ذلك، يسمح WalletTg بتغيير مفتاح التوقيع: يتم إعادة كتابة المفتاح في تخزين العقد، والمصدر الوحيد للمفتاح الحالي هو طريقة get_public_key في الحساب النشط. وصف توثيق TON Connect هذا المسار في 12 أكتوبر، في اليوم التالي لإصدار الحزم.
تم تصميم الخادم المرجعي من مستودع SDK في التطبيق التجريبي بهذه الطريقة: يحاول أولاً تحليل walletStateInit، وإذا لم يتم التعرف على الإصدار، فإنه يطلب المفتاح من الشبكة. التطبيقات التي تم كتابة خادمها وفقًا للأمثلة القديمة التي تحتوي على النصف الأول فقط، ترفض توقيع محفظة Telegram. هذا الانتهاك للمواصفات هو ما يسميه الإعلان سبب فشل عمليات تسجيل الدخول.
كيف تتلقى المحفظة المدمجة طلبات التطبيقات
يقوم TON Connect بنقل الطلبات بين التطبيق والمحفظة عبر جسر — وهو خادم تمر عبره الرسائل المشفرة. لمحفظة Telegram جسرها الخاص، tonbridge.telegram.org، وتصل الطلبات إلى العميل عبر بروتوكول Telegram نفسه. في مخطط MTProto للطبقة 230، تحتوي المحفظة على مجموعة كاملة من الأساليب wallet.tonConnect*: لإنشاء جلسة، الحصول على الطلبات المعلقة، استلام طلب لجهاز واحد، إرسال رد. يصل طلب التطبيق إلى العميل كرسالة تحمل اسم التطبيق وموضوعه، ويقوم TDLib بوصفه على أنه messageTonConnectRequest. في نفس المخطط، يوجد wallet.getExistingWaltBalance: يوضح TDLib أن هذا تحقق مما إذا كان لدى المستخدم رصيد في بوت t.me/walt.
أين يعمل الاتصال بالفعل
بحلول 10 أكتوبر، جرت محاولات لربط محفظة Telegram في Getgems، DeDust، STON.fi، Tonstakers، Tonnel، و TON DNS. يظهر إدخال «Telegram» في نافذة الاختيار من السجل، ولذلك يظهر في القائمة حتى للتطبيقات التي تستخدم إصدارًا قديمًا من المكتبة. الزر المنفصل فوق صف المحافظ والرابط المصحح — متاحان فقط مع واجهة المستخدم (UI) 3.1.0 والإصدارات الأحدث، بينما يقرر خادم التطبيق ما إذا كان تسجيل الدخول بالتوقيع سينجح أم لا.
