run_get_method: استدعاء أي get-method في عقد TON دون SDK

فتحتَ المستكشف لتعرف seqno محفظتك قبل إرسال معاملة، لا أكثر. أو احتجت total_supply لجيتون. أو بيانات عرض NFT من أحد الأسواق. وها أنت من جديد تكتب npm i @ton/ton، وترفع TonClient، وتبحث عن نقطة نهاية لايت-سيرفر تعمل فعلًا، وتحاول أن تفهم كيف تحزم العنوان داخل beginCell().storeAddress()، ثم تفكّك BOC الخارج بيديك. ثلاثون سطرًا من الشيفرة — من أجل رقم واحد يعطيه العقد مجانًا أصلًا.

المشكلة ليست في TON. المشكلة أن بينك وبين استدعاء قراءة بسيط تقع طبقة SDK كاملة عليك تثبيتها وضبطها ثم الحرص على ألّا تنكسر مع التحديث التالي. وإذا كنت تربط وكيل ذكاء اصطناعي بشبكة TON (Claude أو Cursor أو ChatGPT/Codex)، فكتابة هذه الطبقة يدويًا عبثٌ محض: على الوكيل أن يستدعي الدالة وحسب.

وفي ما يلي كيفية استدعاء أي get-method لأي عقد على TON عبر run_get_method، دون سطر واحد من عميل SDK.

ما هو get-method في عقود TON ولماذا يُجرّ معه SDK عادةً

الـget-method دالة للقراءة فقط في العقد الذكي. المحفظة تعطي seqno، والعقد الرئيسي للجيتون يعطي get_jetton_data، وعقد بيع NFT يعطي get_sale_data، ومجمّع STON.fi/DeDust يعطي get_pool_data. والكلمة المفتاح هنا للقراءة فقط:

• الدالة لا تغيّر شيئًا في حالة العقد؛
• ولا تتطلّب توقيعًا ولا تستهلك غاز المستخدم؛
• وتُنفَّذ على لايت-سيرفر أو داخل محاكي TVM (آلة TON الافتراضية)، لا عبر إرسال معاملة.

أي إن استدعاء get-method ليس معاملة. لا شيء هنا يُوقَّع، ولا شيء يُدفَع، ولا شيء يُنتظَر في كتلة. إنها في جوهرها دالة تقول: «اقرأ قيمة من عقد حيّ».

لكن استدعاءها «بالطريقة القديمة» يستلزم عدّة كاملة: SDK (ton أو tonweb أو tonutils)، وعميل ADNL خاص بك إلى اللايت-سيرفر أو غلاف HTTP من نوع toncenter، وتجميع وسائط الدخل يدويًا في خلايا، وتفكيك BOC الخارج يدويًا. أجزاء متحرّكة كثيرة من أجل قراءة واحدة. وكل جزء منها نقطة فشل: فاللايت-سيرفرات العامة في الإعداد العالمي مشتركة ومحدودة، وتحت الحِمل تجيب بـnot ready أو بمهلة ADNL منتهية؛ وواجهات HTTP العامة عند تجاوز الحدّ تعيد 429 Too Many Requests (وبلا مفتاح — نحو طلب واحد في الثانية).

run_get_method: أداة واحدة لأي دالة قراءة في أي عقد

run_get_method أداة MCP تستدعي أي get-method للقراءة فقط في أي عقد على TON. تمرّر عنوان العقد واسم الدالة وقائمة الوسائط — فتنفّذ الأداة الدالة على السلسلة عبر TVM وتعيد لك المكدّس الخارج.

وما لا تحتاج إليه في المقابل:

• تثبيت SDK وتحديثه (ton/tonweb/tonutils)؛
• كتابة عميل ADNL خاص بك؛
• حزم الوسائط يدويًا في خلايا وتفكيك BOC عند الخرج.

وrun_get_method جزء من مجموعة القراءة في TONNode — خادم MCP مُستضاف لشبكة TON. وMCP (Model Context Protocol) معيارٌ تستدعي عبره وكلاء الذكاء الاصطناعي الأدوات. ومجموعة القراءة كاملةً متاحة مجانًا محليًا عبر npx -y @tonnode/mcp (على الإعداد العام، بلا بطاقة)، أو عبر نقطة النهاية المُستضافة https://mcp.tonnode.io/mcp بمفتاح Bearer. ويمكنك التجربة الآن حالًا دون أن تشتري شيئًا.

الوسائط والمكدّس: كيف تمرّر الدخل وتفكّك خرج TVM

تعمل TVM بالمكدّس. والتشبيه: تضع على الطاولة عدّة «بطاقات» تحمل قيم الدخل، فتأخذها الدالة وتشتغل، ثم تضع مكانها «بطاقات» تحمل النتيجة.

الدخل يُمرَّر قيمًا على مكدّس TVM، وهو عادةً:

• int — أعداد صحيحة (مثل الفهرس، أو مبلغ بالوحدات الخام، أو query id)؛
• عنوان من نوع slice — عنوان محزوم داخل شريحة من خلية؛
• cell — خلية بيانات اعتباطية.

ويعود الخرج على هيئة مكدّس قيم: int وslice وcell وtuple. ويفكّكه الوكيل بالمواقع — القيمة الأولى، فالثانية، فالثالثة. مثلًا، تعيد get_jetton_data بالترتيب: total_supply (int)، ثم علم mintable، ثم admin (عنوان slice)، ثم content (cell)، ثم شيفرة المحفظة (cell). فالموقع هو ما يحدّد المعنى — وهذا جزء من اتفاق ABI الخاص بالعقد نفسه.

وكثير من الدوال المفيدة (seqno وget_jetton_data) لا تتطلّب دخلًا إطلاقًا — فمكدّس الوسائط فارغ. أما الوسائط فتظهر حيث تبحث الدالة عن شيء بمفتاح: كحساب عنوان محفظة الجيتون انطلاقًا من عنوان المالك.

وتفصيلة مهمة: run_get_method يعيد المكدّس كما هو، بالوحدات الخام. فالأرقام تصل بلا معالجة، دون إعادة حساب بحسب decimals ودون تحويل الخلايا إلى نصوص مقروءة. وهذا مرن، لكنه يفترض أن تفهم ما تقرأ — وسنعود إلى ذلك في الفقرة الخاصة بـget_jetton_info.

exit_code: كيف تعرف أن الدالة قد أدّت عملها

لكل استدعاء get-method قيمة exit_code — رمز إنهاء TVM. ولا معنى لتفكيك المكدّس الخارج إلا إذا نجح الاستدعاء أصلًا. والقاعدة في دوال get مخالفة للحدس، وتستحقّ أن تُحفَظ:

• exit_code بقيمة 0 و1 — نجاح (كلاهما يُعدّ إنهاءً طبيعيًا، فلا تفزع من الواحد)؛
• exit_code أكبر من 1 — خطأ، ولا يجوز الوثوق بالمكدّس عند الخرج.

ورموز الأخطاء الشائعة:

exit_code	ماذا يعني
2	stack underflow — قُدِّمت إلى المكدّس وسائط أقلّ ممّا تنتظره الدالة
4	integer overflow / القسمة على صفر
11	غالبًا — استدعاء دالة غير موجودة (خطأ مطبعي في الاسم)
13	out of gas

وعمليًا: إن جاءك 2 فتحقّق من أنك مرّرت كل الوسائط وبالترتيب الصحيح. وإن جاءك 11 فالأرجح أنك أخطأت مطبعيًا في اسم الدالة أو أن العقد لا ينفّذها. وإن جاءك 13 فالدالة ثقيلة وقد اصطدمت بحدّ الغاز.

أمثلة عبر الوكيل: seqno وget_jetton_data وget_sale_data

وأمتع ما في الأمر أن يستدعي run_get_method وكيلٌ لا إنسان. فأنت تصوغ المهمة بالكلمات، ويختار الوكيل بنفسه العنوان واسم الدالة والوسائط، ثم يحصل على المكدّس ويشرح لك الحقول.

seqno قبل الإرسال. الـseqno رقم المعاملة الصادرة من المحفظة، ويُقرأ قبل تجميع التحويل: فبدونه لن تمرّ الرسالة.

موجّه للوكيل: «استدعِ seqno على محفظتي UQD… وقل لي الرقم الحالي».

فيستدعي الوكيل run_get_method بلا وسائط، ويحصل على int واحدة في المكدّس الخارج، ويعطيك الرقم.

get_jetton_data — البيانات الوصفية للعقد الرئيسي للجيتون. تعيد الدالة total_supply وعلم mintable وعنوان المدير وcontent.

موجّه للوكيل: «استدعِ get_jetton_data على عقد USDT الرئيسي هذا وفكّك الحقول».

فيستدعي الوكيل run_get_method بعنوان العقد الرئيسي وباسم get_jetton_data، ويقرأ المكدّس ويشرح المواقع. وهنا تفصيلة مهمة نأتي إليها بعد قليل.

get_sale_data — بيانات عرض NFT. ليست هذه أداة NFT منفصلة، بل هي run_get_method نفسها: أنت تقرأ get-method خاصًّا بعقد البيع في السوق. وتعيد get_sale_data السعر والبائع وحالة الصفقة — وهو ما يريحك في معرفة ما إذا كان الـNFT قد بِيع فعلًا أم أنه ما زال معروضًا.

موجّه للوكيل: «اقرأ get_sale_data من عقد البيع هذا وقل لي السعر بالـGRAM».

ولا تكتب أنت أي عميل. الوكيل يستدعي أداة واحدة. أما الدوال الرائجة الأخرى — get_wallet_data (بيانات محفظة الجيتون) وget_pool_data (مجمّعات STON.fi/DeDust) — فتُستدعى بالطريقة ذاتها تمامًا: اسم الدالة، والعنوان، والوسائط عند اللزوم.

get_jetton_data أم get_jetton_info: متى تحتاج جوابًا مقروءًا للبشر

وهنا المطبّ الأكبر. run_get_method يعيد المكدّس كما هو: فـget_jetton_data ستعطيك total_supply عددًا صحيحًا هائلًا بالوحدات الخام، وcontent خليةً لا يزال عليك أن تستخرج منها الاسم والرمز. لا «USDT» ولا «6 decimals» ولا رقمًا جميلًا — إنه خرج TVM منخفض المستوى. فإن كنت تريد وصولًا منخفض المستوى بعينه إلى العقد الرئيسي، أو حقلًا غير قياسي — فهذه أداتك.

أما إذا كانت المهمة مجرّد معرفة اسم الجيتون ورمزه وdecimals في صورة جاهزة، فلا تُتعِب نفسك بتفكيك الخلايا. لذلك توجد أداة منفصلة — get_jetton_info: تعطيك الاسم والرمز وdecimals والمعروض الكلي مفكَّكةً سلفًا.

ولماذا هذا مهمّ إلى هذا الحدّ؟ لأن decimals لازمة لتحويل الوحدات الخام إلى مبالغ حقيقية. فـUSDT على شبكة TON له decimals = 6، وأغلب الجيتونات لها 9. وإذا أخذت total_supply من get_jetton_data الخام ولم تقسمه على 10^decimals، خرج معك رقم يفارق الحقيقة بمليون مرة أو مليار. وتفصيل هذا المطبّ في مادة decimals في جيتونات TON.

والقاعدة بسيطة:

• تريد حقول العقد الخام (المعروض الكلي، admin، content، أي دالة مخصّصة) → run_get_method مع get_jetton_data؛
• تريد جوابًا جاهزًا مقروءًا للبشر عن الجيتون (الاسم، الرمز، decimals) → get_jetton_info.

ولا تخلط بين الأرقام الخام من get_jetton_data والجواب الجاهز من get_jetton_info.

دعامتان مفيدتان: parse_address وget_account_state

قبل استدعاء الدالة يحسن أن ترتّب أمر العنوان وتتأكّد من أن العقد حيّ أصلًا:

• parse_address — يوحّد صيغة العنوان بين EQ/UQ/raw، دون اتصال ودون أي طلب إلى الشبكة. فصيغ العناوين في TON متعدّدة، وليست كل دالة تقبل أيًّا منها؛ ومن المريح أن تحوّل EQ… الذي أعطاه المستخدم إلى الصيغة المطلوبة قبل وضعه في الوسائط.
• get_account_state — يفحص الحالة والأعلام وآخر معاملة للعقد. فإن لم يكن الحساب منشورًا (uninit) أو كان مجمَّدًا، سقط أي get-method سقوطًا متوقَّعًا — وفحص الحالة سلفًا أرخص من ملاحقة exit_code غامض.

كيف تربط وتستدعي دون سطر واحد من عميل

أمامك طريقان. الأول — مجانًا محليًا، بمجموعة القراءة كاملةً على الإعداد العام وبلا بطاقة:

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

حزمة @tonnode/mcp مفتوحة المصدر (MIT)، وموجودة على npm وGitHub (tonnode/mcp)، وتعمل عبر بروتوكول ADNL الأصلي في TON، دون طبقات HTTP وسيطة. وللطريق المجاني مادة منفصلة — TON MCP مجانًا.

والثاني — نقطة نهاية مُستضافة بسعة تمريرية مضمونة وبمفتاحك أنت:

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

وجميع الأدوات الستّ عشرة متاحة على كل الباقات — فأنت تدفع مقابل السعة التمريرية وحدها. ومفتاح Hobby المجاني (60 طلبًا/دقيقة) يُصدَر فور تسجيل الدخول، دون بطاقة.

وبعد الربط تصبح مجموعة القراءة كاملةً — بما فيها run_get_method وget_jetton_info وparse_address وget_account_state — متاحةً للوكيل كأدوات عادية. ويبدو الاستدعاء عبارةً عادية في المحادثة: «استدعِ get_pool_data على مجمّع DeDust هذا»، «اقرأ seqno لهذه المحفظة» — ويختار الوكيل بنفسه run_get_method والوسائط، ثم يشرح الحقول. وإذا كانت المهمة معرفة رصيد USDT، فثمّة طريق جاهز باستدعاء واحد: رصيد USDT على TON باستدعاء واحد.

---

خذ مفتاح Hobby المجاني واستدعِ run_get_method من داخل وكيلك مباشرةً → tonnode.io/dashboard?plan=hobby. يُصدَر المفتاح فور تسجيل الدخول، دون بطاقة، بواقع 60 طلبًا في الدقيقة — وهو يكفي وزيادةً لقراءة العقود.

ألا تريد حتى التسجيل؟ شغّله محليًا: npx -y @tonnode/mcp. والقائمة الكاملة للأدوات ومعاملاتها على صفحة tonnode.io/mcp.

لم تعد قراءة حالة البلوكتشين تعني تجميع عميل. صارت تعني صياغة الطلب.