در تاریخ 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 در 28 سپتامبر به Walt تبدیل شد، و رجیستری نام را در 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 و جدیدتر در دسترس است، اما اینکه آیا ورود با امضا موفقیت‌آمیز خواهد بود یا خیر، توسط سرور برنامه تعیین می‌شود.
