إنشاء محفظة TON برمجيًا (v4 وv5 وhighload)

أطلقتَ حملة توليد 500 كود ترويجي، وكل دفعة تحتاج إلى محفظة TON خاصة بها. أو أنك تكتب وكيل ذكاء اصطناعي ينشئ محفظة «ساخنة» عند الطلب، ويستقبل إيداعًا، ويفعل به شيئًا. وأول ما تجده على الإنترنت كومة من أمثلة الـ SDK: استورد @ton/ton، وافهم الفرق بين WalletContractV4 وWalletContractV5R1، واستدعِ mnemonicNew() يدويًا، واشتقّ المفاتيح، واحسب العنوان، ولا تنسَ subwallet_id في highload. فيذهب نصف يوم في كتابة كود بنية تحتية لا صلة له بمهمتك من الأساس. وإذا كان مَن ينشئ المحافظ وكيلَ ذكاء اصطناعي، فعليه أن يعرف كيف يفعل ذلك بنفسه — دون أن تُضمّنه أنت منطق التشفير يدويًا.

وفيما يلي طريقة إنشاء محفظة TON برمجيًا (generate wallet / إنشاء محفظة في TON) باستدعاء واحد لأداة generate_wallet، وكيفية الاختيار بين الإصدارات v3r2 وv4 وv5r1 وhighload_v3، وكيف تتجنّب خسارة أول إيداع بسبب الخطأ الكلاسيكي في عنوان bounceable.

لماذا تنشئ محفظة TON برمجيًا (ولماذا لا عبر SDK)

الإنشاء اليدوي عبر SDK أمر مقبول تمامًا — إلى أن تصل إلى أول بيئة إنتاج. وعند التوسّع تطفو المشكلات على السطح:

• الإصدارات. لا توجد في TON «محفظة» واحدة، بل عدّة عقود: v3r2 وv4 وv5r1 وhighload. لكلٍّ منها منطقه الخاص وعنوانه الخاص انطلاقًا من المفتاح نفسه. وإن أخطأت في الإصدار حصلت على عنوان غير الذي تقصده.
• صيغ العنوان. للمحفظة الواحدة صيغتان: EQ وUQ. وإن خلطت بينهما عند إعطاء عنوان الإيداع، ارتدّت الأموال إلى مرسلها (تفصيل ذلك أدناه).
• وكيل الذكاء الاصطناعي. الوكيل (Claude أو Cursor أو ChatGPT/Codex) لا يمكنك أن «تعطيه مكتبة» — فهو يحتاج إلى أداة يستدعيها انطلاقًا من وصفها. وعبر MCP (Model Context Protocol) يستدعي الوكيل generate_wallet كأي دالة عادية، ويحصل على استجابة مهيكلة جاهزة. ويبقى منطق الإصدارات والمفاتيح والصيغ كلّه داخل خادم MCP.
• مكدّس متعدد اللغات. إن كنت لا تريد صيانة TON-SDK بلغات Go وPython وNode في آن واحد، فإن MCP يمنحك واجهة واحدة تكفيها جميعًا.

أداة generate_wallet واحدة من 16 أداة في TONNode، خادم MCP المُستضاف لشبكة TON. وهي تفعل شيئًا واحدًا بالضبط: تنشئ محفظة جديدة وتسلّمك كل ما تحتاجه لتملّكها. وإذا كنت تتعرّف على هذا النهج للتوّ، فابدأ من دليل MCP لـ TON.

generate_wallet في استدعاء واحد: ما الذي يعود إليك بالضبط

تنشئ generate_wallet محفظة TON جديدة وتعيد كل ما يلزم لتملّكها واستعادتها:

• العبارة التذكيرية (seed phrase) — مجموعة كلمات مقروءة للبشر يُشتقّ منها كل ما عداها اشتقاقًا حتميًا؛
• المفتاح الخاص — لتوقيع المعاملات؛
• المفتاح العام؛
• عنوان المحفظة — بصيغ TON القياسية.

ونصّ الطلب (prompt) الموجَّه إلى الوكيل يبدو حرفيًا هكذا:

أنشئ محفظة TON جديدة بإصدار v5r1 عبر generate_wallet
وأظهر العنوان والعبارة التذكيرية.

يستدعي الوكيل الأداة مع معامِل الإصدار، ويعيد بنية قريبة من هذا الشكل (القيم هنا توضيحية؛ ومفاتيح Ed25519 في TON هي hex عادي، دون بادئة 0x الخاصة بـ Ethereum):

{
  "version": "v5r1",
  "mnemonic": ["word1", "word2", "...", "word24"],
  "public_key": "e3f1a2…",
  "private_key": "9b7c4d…",
  "address": {
    "bounceable": "EQ…",
    "non_bounceable": "UQ…",
    "raw": "0:abcd…"
  }
}

لا SDK ولا اشتقاق يدوي. وبعد ذلك تقرّر بنفسك أين تخزّن هذا كلّه. والنقطة الجوهرية: لا يحتفظ الخادم لديه بهذه العبارة التذكيرية ولا بهذه المفاتيح — وتفصيل ذلك أدناه في القسم الخاص بعدم الاحتجاز.

إصدارات المحافظ v3r2 وv4 وv5r1 وhighload_v3 — أيّها تختار

تدعم generate_wallet أربعة إصدارات من عقد المحفظة. والقاعدة ليست «الأحدث يعني الأفضل»: فلكلٍّ منها مجال استخدامه الخاص.

v5r1 (W5) — الخيار الافتراضي للمشاريع الجديدة

أحدث الإصدارات. يدعم الامتدادات وسيناريوهات gasless — حين يمكن لمُرحِّل (relayer) خارجي أن يدفع العمولة نيابةً عن المستخدم. وهذه خاصية عقد v5 نفسه، لا خدمة تقدّمها TONNode: فالخادم يكتفي بإنشاء محفظة من هذا النوع، ولا يوفّر أي مُرحِّل gasless. فإذا كنت تبني وكيلًا حديثًا من الصفر ولا تحتاج تحديدًا إلى highload — فخذ v5r1.

v4 — إصدار الإضافات (plugins)

الجيل السابق الأوسع انتشارًا. يدعم الإضافات: إذ يمكن ربط عقود امتدادات بالمحفظة (للاشتراكات والمدفوعات المؤجّلة مثلًا). ظلّ طويلًا المعيار الفعلي، وتدعمه المحافظ والخدمات على نطاق واسع. خذه إن كانت لديك تبعية لنموذج الإضافات في v4.

v3r2 — محفظة أساسية بسيطة

عقد بالحدّ الأدنى، دون امتدادات ولا إضافات. متوقَّع السلوك ورخيص من حيث الغاز. مناسب للعناوين الخدمية التي يكون كل منطقها «استقبل وأرسل».

highload_v3 — للدفعات الجماعية

صنف قائم بذاته. محفظة مخصّصة للسعة التمريرية العالية: إذ يمكن لرسالة خارجية واحدة أن تحمل تحويلات كثيرة. وهذا ما تختاره من أجل الدفعات المجمّعة، والدروب، وتوزيع المكافآت، وبوّابات الدفع، وعمليات السحب من المنصّات. وهو يدفع ثمن هذه الكفاءة بنموذج خاص لتتبّع الرسائل (query_id / expiration)، ولذلك يتطلّب تعاملًا حذرًا — انظر قسم تخزين المعامِلات.

الإصدار	متى تختاره
v5r1	مشاريع جديدة، امتدادات، gasless
v4	تحتاج إلى الإضافات (الاشتراكات ونحوها)، أقصى توافقية
v3r2	محفظة خدمية بسيطة بلا زخارف
highload_v3	دفعات جماعية/مجمّعة، سعة تمريرية عالية

مثال على طلب خاص بالدفعات:

ولّد محفظة highload_v3 للدفعات المجمّعة وأعد
العبارة التذكيرية والمفاتيح والعنوان.

أول إيداع: لماذا تُرسله إلى عنوان UQ غير القابل للارتداد

أكثر الأخطاء شيوعًا وإيلامًا بعد إنشاء المحفظة هو ضياع أول إيداع. والآلية كالتالي: المحفظة المُنشأة حديثًا لم تُنشر بعد في البلوكتشين — فالعقد غير موجود فيزيائيًا على العنوان إلى أن يصله أول تحويل ينشر شفرته.

وفي TON للعنوان راية (flag) اسمها «bounceable»:

• EQ (bounceable) — إن لم يكن على العنوان عقد حيّ، ترتدّ الشبكة بالتحويل («bounce») إلى مرسله. وهذه بالضبط حالتك مع محفظة جديدة.
• UQ (non-bounceable) — يبقى التحويل «ملتصقًا» بالعنوان حتى لو لم يُنشر العقد بعد. وهذا تحديدًا ما يلزم من أجل أول إيداع.

القاعدة بسيطة: أرسِل أول تحويل تشحن به محفظة جديدة إلى عنوان UQ. أما على EQ فسيعود إليك، وستظلّ تتساءل لماذا الرصيد فارغ. وبعد أن تنفّذ المحفظة أول معاملة صادرة وتُنشَر فعليًا، يمكنك استخدام الصيغة bounceable باطمئنان.

كيف تحصل على صيغة UQ بصورة موثوقة؟ عبر الأداة المحلّية parse_address — فهي تحوّل بين صيغ EQ/UQ/raw وتتحقّق منها دون أي اتصال بالشبكة:

عبر parse_address حوّل هذا العنوان إلى صيغة UQ
غير القابلة للارتداد من أجل أول إيداع

وبعد الشحن تحقّق من الحالة عبر get_account_state — فهو يُظهر حالة الحساب (uninitialized / active) والرايات وآخر معاملة:

تحقّق من get_account_state للعنوان UQ… — هل نُشرت المحفظة
وما الرصيد

وما دام العقد غير نشط، فستخبرك الحالة بأن الإيداع لم «يُوقِظ» المحفظة بعد. والتحليل المفصّل للصيغ موجود في مقال صيغ العناوين EQ/UQ/raw.

محفظة highload: ثبّت subwallet_id وtimeout بنفسك

تحذير خاص لمن اختار highload_v3. فالعبارة التذكيرية وحدها لا تكفي هنا لإعادة بناء المحفظة العاملة بصورة صحيحة ولتكرار سلوكها. فلعقد highload، إلى جانب المفتاح، معامِلان آخران يُحدَّدان عند الإنشاء ويدخلان في بياناته الابتدائية (state init):

• subwallet_id — معرّف المحفظة الفرعية (يتيح اشتقاق عدّة عناوين مختلفة من عبارة استرداد واحدة)؛
• timeout — نافذة حياة الرسائل الخارجية، وعليها يقوم منطق query_id والانتهاء.

ومن المهم أن تنتبه: تعيد generate_wallet العبارة التذكيرية والمفاتيح والعنوان — أما subwallet_id وtimeout فتختارهما وتثبّتهما أنت بنفسك بوصفهما معامِلَي بناء محفظة highload. وأنت وحدك المسؤول عن تدوين القيم التي أُنشئت بها المحفظة.

تتعقّب محفظة highload أيّ الرسائل ما تزال «حيّة» انطلاقًا من timeout. فإن استعدت المحفظة بعبارة الاسترداد وحدها، دون subwallet_id وtimeout، فإنك:

• تحصل على عنوان مختلف — إذ يدخل كلٌّ من subwallet_id وtimeout في state init، ولذا فإن تغيير أيٍّ منهما يغيّر البيانات الابتدائية للعقد، ومن ثمّ يغيّر عنوانه؛
• لن تعيد إنتاج منطق الانتهاء وإزالة تكرار الرسائل بصورة صحيحة — وتخاطر بكسر تتبّع التحويلات الصادرة.

قاعدة عملية: في highload_v3 ضع subwallet_id وtimeout في المخزن بجوار العبارة التذكيرية، كجزء من سجلّ واحد للمحفظة. فهذه ليست بيانات وصفية اختيارية — بل جزء من هوية المحفظة نفسها.

# سجلّ سرّ توضيحي
mnemonic:      "word1 word2 … word24"
version:       "highload_v3"
subwallet_id:  <القيمة التي حدّدتها عند الإنشاء>
timeout:       <القيمة التي حدّدتها عند الإنشاء>

أما v3r2/v4/v5r1 فلا تشترط ذلك — تكفيها العبارة التذكيرية ومعرفة الإصدار.

غير احتجازية: الخادم لا يخزّن المفاتيح ولا يوقّع بها

السؤال الأهمّ حين تُنشأ المحفظة «في مكان ما على الخادم»: مَن يملك المفاتيح في نهاية المطاف؟ والجواب هنا لا لبس فيه.

أداة generate_wallet غير احتجازية بصرامة:

• الخادم لا يخزّن أبدًا المفاتيح الخاصة ولا العبارة التذكيرية ولا الأموال؛
• الخادم لا يوقّع أبدًا المعاملات نيابةً عنك؛
• المحفظة المولَّدة — العبارة التذكيرية والمفاتيح والعنوان — تُسلَّم إليك بالكامل في الاستجابة، ولا يُحتفظ بها في جانب الخادم.

لا قاعدة بيانات تضمّ عبارات استرداد الآخرين، ولا مفتاح مشغّل (operator) يوقّع شيئًا نيابةً عنك. وأداة generate_wallet في جوهرها غلاف مريح فوق توليد حتمي: تجري عملية التشفير، وتذهب النتيجة إليك، ولا يبقى لدى الخادم شيء. وهذا فارق مبدئي عن محافظ الوكلاء الاحتجازية، حيث تحتفظ الخدمة بالمفتاح (أو بجزء منه) وتوقّع المعاملات بنفسها. ونحلّل هذا الفرق على حدة في مقال MCP احتجازي في مقابل غير احتجازي.

والخلاصة العملية: احفظ استجابة generate_wallet في مخزنك الآمن فورًا. فالخادم لن «يستخرج» لك المحفظة نفسها مرّة ثانية — هو لا يتذكّرها، والاستعادة «عبر الدعم الفني» مستحيلة. وهذه ميزة لا خلل.

كيف تربط الخادم وتنشئ أول محفظة

الربط لا يستغرق أكثر من دقيقة. تشغّل حزمة @tonnode/mcp محليًا ومجانًا عبر npx؛ ومجموعة أدوات القراءة كاملةً متاحة دون مفتاح.

إعداد عميل MCP (Claude Desktop أو Cursor أو أي عميل MCP):

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

حزمة @tonnode/mcp مفتوحة المصدر (MIT)، وموجودة على npm وGitHub (tonnode/mcp)، وتعمل ببروتوكول TON الأصلي ADNL، دون طبقات HTTP وسيطة بين وكيلك والشبكة. أعد تشغيل العميل — وستصبح الأدوات الـ16 كلها، ومنها generate_wallet وparse_address وget_account_state، متاحة للوكيل. وطريقة توصيلها بعميل بعينه موجودة في دليل ربط Claude وCursor بشبكة TON.

تندرج أداة generate_wallet ضمن الأدوات الـ16 كاملةً، وهي متاحة في جميع الباقات، بما فيها باقة Hobby المجانية — 60 طلبًا في الدقيقة، دون بطاقة. ويُصدر المفتاح المجاني فور تسجيل الدخول. فأنت تدفع مقابل السعة التمريرية فقط، لا مقابل الوصول إلى الأدوات.

وفيما يلي ثلاث أدوات تغطّي سيناريو «أنشئ واشحن بأمان» كاملًا:

1. generate_wallet — أنشئ محفظة بالإصدار المطلوب، وخذ العبارة التذكيرية والمفاتيح والعنوان.
2. parse_address — احصل على صيغة UQ للعنوان من أجل أول إيداع (دون اتصال بالشبكة).
3. get_account_state — تأكّد من أن الإيداع قد نشر العقد.

مثال على طلب كامل للوكيل:

أنشئ محفظة v5r1 عبر generate_wallet. ثم أعطني عبر
parse_address عنوانها بصيغة UQ من أجل أول شحن.
وبعد أن أرسل العملات، تحقّق عبر get_account_state
من أن المحفظة قد نُشرت.

متى تحتاج إلى مفتاح hosted

التشغيل المحلي عبر npx يستخدم الإعداد العام، وهو ممتاز للتطوير. فإذا احتجت إلى سعة تمريرية مضمونة تحت الحمل (الدفعات الجماعية نفسها عبر highload مثلًا)، فاربط النقطة الطرفية المُستضافة بمفتاحك الخاص:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

الخلاصة

• تنشئ generate_wallet محفظة TON باستدعاء واحد وتعيد العبارة التذكيرية والمفتاحين الخاص والعام والعنوان — استدعاء واحد مع اختيار الإصدار، لا تجميع SDK يدويًا.
• الإصدار الافتراضي لمشروع جديد هو v5r1؛ وللدفعات الجماعية highload_v3؛ وv4 من أجل الإضافات؛ وv3r2 حين تحتاج إلى محفظة بسيطة.
• أرسل أول إيداع إلى عنوان UQ غير القابل للارتداد، وإلا ارتدّ؛ وصيغة UQ تعطيها parse_address، والحالة يتحقّق منها get_account_state.
• في highload ثبّت بنفسك subwallet_id وtimeout واحفظهما مع العبارة التذكيرية — فكلاهما يدخل في state init ويؤثّر في العنوان.
• الخادم غير احتجازي: لا يخزّن المفاتيح ولا الأموال ولا يوقّع نيابةً عنك — المفاتيح لك.

احصل على مفتاح Hobby المجاني وأنشئ أول محفظة عبر generate_wallet في دقيقتين — tonnode.io/dashboard?plan=hobby.