إنتقل إلى المحتوى الرئيسي

الورشة 2: احمِ الأموال بمفتاح ما بعد كمومي

أرسلت الورشة 1 معاملة واحدة موقّعة بمفتاحين. أما الورشة 2 فتستخدم المفتاح ما بعد الكمومي لحماية الأموال: أولًا عقد ذكي لا يدفع إلا عندما يوقّع مفتاح ما بعد كمومي، ثم وكيل ذكاء اصطناعي تفرض السلسلة حدود إنفاقه، ثم طريقة لتسأل السلسلة كيف حُميت كل معاملة.

لا يلزم أن تكون خبيرًا في الأمن. كل أمر أدناه يشرح ماذا يفعل وماذا ينبغي أن تراه. التطبيقات الثلاثة النموذجية عامة: github.com/qorechain/build-before-qday، المجلد workshop-2.

كم يستغرق ذلك: نحو 40 دقيقة للخزنة، و25 للوكيل، و10 للأسئلة الموجّهة إلى السلسلة. يمكنك إنجاز الأجزاء بأي ترتيب، لكن كل جزء يحتاج إلى حساب اختباري خاص به.

ما الذي نبنيه​

الجزءالتطبيقما يوضّحه
1QDayVault (Solidity وTypeScript)خزنة لا تدفع إلا بتوقيع ML-DSA-87، تفحصه السلسلة بالـ precompile المسمّى pqcVerify. لا يكفي مفتاح مسروق من نمط إيثريوم لأخذ الأموال.
2وكيل دفع الفواتير (Node.js)وكيل له مفتاحه الخاص. تفرض السلسلة حدوده: الإرسال فقط، و1 QOR لكل دفعة، و3 QOR في اليوم، لمدة 24 ساعة.
3اسأل السلسلة (MCP وqore-cli)أسئلة للقراءة فقط: هل وُقّعت هذه المعاملة توقيعًا ما بعد كمومي، وما حالة مفتاح هذا الحساب؟

الابتكارات التي تقف خلفها:

  • التحقق ما بعد الكمومي داخل العقد. في السلسلة عقود مدمجة (precompiles) على عناوين ثابتة تفحص توقيعات ML-DSA-87 وتُبلغ عن المفتاح المسجّل لحساب ما. يستدعيها كود Solidity الخاص بك كأي عقد آخر.
  • حدود تعيش على السلسلة. صلاحيات الوكيل وقواعد إنفاقه جزء من الحساب نفسه، فلا يستطيع خطأ برمجي أو خادم مسروق رفعها.
  • تصنيفات صادقة. تستطيع السلسلة أن تخبرك أي المعاملات حملت توقيعًا ما بعد كمومي وأيها لم تحمله.

كلمات تُستخدم في هذا الدليل​

الكلمةمعناها ببساطة
Precompileعقد مدمج على عنوان ثابت تشغّله السلسلة أصليًا. pqcVerify على العنوان 0x0000000000000000000000000000000000000a01 وpqcKeyStatus على العنوان 0x0000000000000000000000000000000000000a02. اكتب العناوين بأحرف صغيرة: مترجم Solidity يرفض الكتابة المختلطة الحالة
ML-DSA-87خوارزمية التوقيع ما بعد الكمومي (NIST FIPS 204) التي تستخدمها QoreChain
نافذة EVM (EVM window)تفويض قصير ومحدود لإرسال معاملات من نمط إيثريوم من حساب ما. فتحها يحتاج إلى معاملة موقّعة بالمفتاحين معًا، فلا يستطيع مفتاح إيثريوم وحده أن يفتح نافذة أبدًا
الوصيّ (Guardian)الحساب الذي يجب أن يوقّع مفتاحه ما بعد الكمومي على كل سحب من الخزنة
المصادِق (Authenticator)مفتاح مرتبط بحسابك بقواعد تفرضها السلسلة، كما يستخدمه الوكيل في الجزء 2
الحساب المؤقت (Throwaway account)مفتاح أُنشئ لهذا التمرين ويحمل QOR اختبارية فقط
حسابات اختبارية مؤقتة فقط

استخدم مفاتيح أُنشئت لهذه الورشة وتحمل QOR اختبارية بلا قيمة. لا تضع أبدًا في ملف .env أو في أي أمر مفتاحًا أو رمز استرداد لحساب يحمل أموالًا حقيقية.

قبل أن تبدأ​

تحتاج إلى الأدوات المذكورة في قبل أن تبدأ (طرفية وNode.js الإصدار 22 أو أحدث وGit)، ومتصفح ويب. تحقق من Node.js:

node -v

يجب أن يطبع v22 أو رقمًا أعلى. يحتاج الجزء 1 أيضًا إلى pnpm وFoundry:

npm install -g pnpm

يثبّت pnpm، أداة الحزم التي تستخدمها الخزنة. تحقق منه بـ pnpm -v.

يجمّع Foundry عقود Solidity ويختبرها وينشرها. ثبّته من getfoundry.sh: تعطيك الصفحة أمرًا واحدًا لنظامك، ثم تشغّل:

foundryup

ينزّل أدوات Foundry. تحقق منها بـ forge --version وcast --version.

احصل على الشيفرة النموذجية:

git clone https://github.com/qorechain/build-before-qday.git
cd build-before-qday/workshop-2

السطر الأول ينزّل الأمثلة إلى مجلد باسم build-before-qday. والثاني ينتقل إلى مجلد workshop-2 الذي يضم التطبيقات الثلاثة.

للحصول على QOR اختبارية تستخدم الصنبور في لوحة التحكم. تعمل التطبيقات الثلاثة على الشبكة الاختبارية qorechain-diana فقط.

الجزء 1: QDayVault، خزنة تصمد أمام تسرّب المفتاح​

الشيفرة: workshop-2/01-qday-vault. مفتاح المحفظة العادي (مفتاح secp256k1 الذي يستخدمه MetaMask) قد يكسره حاسوب كمومي يومًا ما. بُنيت هذه الخزنة بحيث لا يكفي مفتاح مسروق من هذا النوع: لا تخرج الأموال إلا حين يوقّع الوصيّ على السحب بمفتاح ما بعد كمومي، ويفحص العقد هذا التوقيع بنفسه على السلسلة. يمكن لأي شخص أن يرسل السحب الموقّع. المهم هو التوقيع، لا من يرسله.

cd 01-qday-vault

ينتقل إلى مجلد الخزنة.

كيف يعمل العقد​

افتح src/QDayVault.sol. الدالة المهمة هي withdraw:

(bool registered,, bytes memory pubkey, bool proven) = PQC_KEYS.pqcKeyStatus(guardian);
if (!registered || pubkey.length == 0) revert GuardianKeyNotRegistered();
if (!proven) revert GuardianKeyNotProven();

uint256 n = nonce;
if (!PQC_VERIFY.pqcVerify(pubkey, mldsaSignature, withdrawalMessage(to, amount, n))) revert BadPqcSignature();

nonce = n + 1;
emit Withdrawn(to, amount, n);
(bool ok,) = to.call{value: amount}("");
if (!ok) revert TransferFailed();
  1. اقرأ مفتاح الوصيّ من السلسلة. حجم المفتاح 2,592 بايت، لذلك لا يخزّنه العقد. وإذا بدّل الوصيّ مفتاحه على السلسلة تبعته الخزنة.
  2. ارفض مفتاحًا لم يثبت. "ثبت" يعني أن الحساب وقّع إثبات ملكية عند تسجيل المفتاح. دون هذا الفحص يستطيع شخص أن يسجّل مفتاحًا لا يملكه.
  3. تحقق من التوقيع على رسالة محددة بدقة. تربط الرسالة وسمًا ثابتًا ومعرّف السلسلة وعنوان الخزنة والمستلم والمبلغ والـ nonce، فيصلح التوقيع لسحب واحد، على خزنة واحدة، على سلسلة واحدة، مرة واحدة.
  4. ارفع الـ nonce قبل إرسال الأموال. فلا يمكن استخدام التوقيع نفسه مرتين، وتتغير الحالة قبل الاستدعاء الخارجي، وهذا يحمي من إعادة الدخول (reentrancy).
  5. تأكد من نجاح التحويل. إن فشل، تُلغى المعاملة كلها.

الخطوة 1: شغّل الاختبارات (لا حاجة إلى حساب)​

pnpm install

ينزّل حزم JavaScript المذكورة في package.json (حزمة QoreChain SDK وviem وtsx).

pnpm forge-std

ينزّل forge-std، المكتبة القياسية لـ Foundry، إلى lib/. تستوردها الاختبارات وسكربت النشر. تفعل ذلك مرة واحدة.

forge test

يجمّع العقد ويشغّل الاختبارات الثمانية في test/QDayVault.t.sol. يجب أن ترى 8 passed; 0 failed. لا تحتوي السلسلة المحلية للاختبار على precompiles الخاصة بـ QoreChain، لذلك تضع الاختبارات عقودًا بديلة صغيرة على عنواني الـ precompile بالأمر vm.etch. وهي تفحص المنطق: التوقيع الصحيح يدفع، والخاطئ يُرفض، والتوقيع يصلح مرة واحدة، والمفتاح غير المثبت يُرفض. أما الـ precompiles الحقيقية فتعمل في الخطوات التالية.

الخطوة 2: أنشئ حسابًا للشبكة الاختبارية فقط​

cast wallet new

يطبع عنوانًا جديدًا ومفتاحًا خاصًا. استخدمه للشبكة الاختبارية فقط.

على macOS وLinux:

cp .env.example .env

وعلى Windows PowerShell استخدم Copy-Item .env.example .env. ينشئ هذا ملف إعداداتك الخاص. الملف .env يتجاهله Git، فلا يُودَع أبدًا. افتح .env وضع في PRIVATE_KEY المفتاح الخاص الذي طبعه cast wallet new.

pnpm window recovery-code

يطبع رمز استرداد يبدأ بـ QRC1-. يُصنع منه مفتاحك ما بعد الكمومي. ضعه في .env باسم QORE_PQC_RECOVERY_CODE واحتفظ بنسخة في مكان آمن بعيدًا عن المفتاح الخاص. استخدم الرمز نفسه دائمًا: رمز مختلف يعني مفتاحًا ما بعد كمومي مختلفًا.

الخطوة 3: موّل الحساب​

pnpm window status

يطبع حسابك بصيغتين، 0x... وqor1.... هما الحساب نفسه. الصق عنوان qor1... في الصنبور.

الخطوة 4: سجّل مفتاحك ما بعد الكمومي، مرة واحدة​

pnpm window register

يضع مفتاحك العام ML-DSA-87 على السلسلة مع إثبات أنك تملكه. تفعل ذلك مرة واحدة لكل حساب. بعدها يعرض pnpm window status السطر PQC key: registered. هذه هي المعاملة الوحيدة التي تقبلها السلسلة بالمفتاح الكلاسيكي وحده، لأن السلسلة لا تعرف مفتاحك ما بعد الكمومي بعد. لمعرفة ما يربطه التسجيل فعلًا، راجع كيف يرتبط مفتاحك ما بعد الكمّي بحسابك.

الخطوة 5: افتح نافذة EVM محدودة النطاق​

pnpm window:scoped

يرسل معاملة موقّعة بالمفتاحين تفتح نافذة EVM مدتها 600 كتلة (نحو 15 دقيقة)، و3 معاملات، و2 QOR من القيمة مع الرسوم. هذا يكفي للنشر وسحب واحد، ولا شيء أكثر. إذا تسرّب مفتاحك الكلاسيكي أثناء فتح النافذة، فإن الضرر محصور في هذه الميزانية؛ وعندما تنتهي، يُغلق مسار نمط إيثريوم من جديد.

انتظر نحو 10 ثوانٍ قبل الخطوة التالية. فتح النافذة استهلك nonce واحدًا من حسابك، ويجب أن تضمّه الكتلة التالية أولًا.

الخطوة 6: انشر الخزنة​

pnpm deploy:testnet

يشغّل سكربت Foundry script/QDayVault.s.sol: ينشر الخزنة بإيداع قدره 1 QOR ويجعل حسابك أنت الوصيّ. ابحث عن QDayVault 0x... في المخرجات. في مخرجات Foundry تعني "ETH" عملة QOR.

pnpm vault status

يعرض عنوان الخزنة ورصيدها (1 QOR) والوصيّ (أنت) والـ nonce (0).

الخطوة 7: الهجوم، على سبيل المحاكاة​

pnpm vault attack 0x1b6dF9880065e7758c6e82741c50cEaD80664937 0.5

يؤدي دور مهاجم يملك مفتاحك الكلاسيكي لكنه لا يملك مفتاحك ما بعد الكمومي. يوقّع السحب بمفتاح ML-DSA-87 عشوائي ويسأل السلسلة عمّا سيحدث. يجب أن ترى BLOCKED by the vault: BadPqcSignature. هي محاكاة فقط، فلا تكلّف شيئًا ولا تستهلك نافذتك. يصلح أي عنوان مستلمًا.

الخطوة 8: السحب الحقيقي​

pnpm vault withdraw 0x1b6dF9880065e7758c6e82741c50cEaD80664937 0.5

يوقّع السحب بمفتاحك أنت من نوع ML-DSA-87 (رسالة من 157 بايت، وتوقيع من 4,627 بايت) ويرسله. تفحصه الخزنة بـ pqcVerify وتدفع. يجب أن ترى WITHDRAWN tx 0x... ورابطًا إلى المستكشف.

pnpm window status

يعرض ما تبقى من النافذة: معاملة واحدة، وهي بالضبط الميزانية التي أعطيتها.

إذا حدث خطأ​

ما تراهمعناهماذا تفعل
REFUSED: Missing or invalid parameters عند النشر أو السحبلا توجد نافذة EVM فعّالة: انتهت أو استُنفدتشغّل pnpm window status، ثم pnpm window:scoped، وانتظر 10 ثوانٍ، وأعد المحاولة
does not exist on chain yetلا يملك الحساب أي QOR بعداستخدم الصنبور (الخطوة 3)
PQC key: not registeredتم تخطي الخطوة 4شغّل pnpm window register
GuardianKeyNotRegisteredلا يملك الوصيّ مفتاح ML-DSA-87 على السلسلةسجّله (الخطوة 4)
No vault yetلم يُنشر أي شيء من هذا المجلدنفّذ الخطوة 6، أو اضبط VAULT_ADDRESS في .env

دقّق العقد قبل نشره​

يحتوي مجلد audit/ على المسودة الأولى من العقد، وفيها أخطاء حقيقية، والنسخة المصحَّحة. وهو يُظهر مسارًا من مرحلتين مع مدقّق العقود في لوحة التحكم: دقّق المسودة، وأصلح كل ملاحظة باختبار، ثم دقّق العقد النهائي واحتفظ بالتقريرين. التدقيق الآلي لا يغني عن تدقيق بشري قبل الشبكة الرئيسية. بالنسبة إلى Solidity يظهر تقييم الجاهزية الكمومية "Not scored"، وهذا متوقع: على EVM تتولى السلسلة الفحص ما بعد الكمومي عبر الـ precompile. راجع audit/README.md في المجلد، وصفحة EVM Precompiles لعناوين الـ precompiles والغاز.

الجزء 2: وكيل يدفع الفواتير بحدود تفرضها السلسلة​

الشيفرة: workshop-2/02-pq-agent. إذا أعطيت روبوتًا مفتاحك الخاص، فإن حدود إنفاقه تعيش في شيفرته هو. خطأ برمجي واحد، أو حقن أوامر واحد (prompt injection)، أو خادم مسروق واحد، وتضيع الحدود. أما على QoreChain فالحدود تعيش على السلسلة: يحصل الوكيل على مفتاحه الخاص، مرتبطًا بحسابك بقواعد تفحصها السلسلة عند كل دفعة.

ارجع مجلدًا واحدًا ثم ادخل إلى الوكيل:

cd ../02-pq-agent

ثلاثة مفاتيح، ثلاثة أدوار​

المفتاحمن يحملهماذا يستطيع أن يفعل
المالك (Owner)أنتحسابك، موقّع بالمفتاحين. يحمل الأموال، ويربط الوكيل، ويكتب القواعد
مفتاح الوكيلالوكيلمفتاح ed25519. يستطيع أن يطلب الإنفاق من حساب المالك، داخل القواعد فقط. لا يحمل أموالًا
محفظة الغاز (Gas wallet)الوكيلحساب صغير منفصل يرسل طلبات الوكيل ويدفع الرسوم. لا يحمل أموال المالك أبدًا

القواعد في هذا المثال: يستطيع الوكيل إرسال QOR فقط، بحد أقصى 1 QOR لكل دفعة و3 QOR في اليوم، وينتهي الربط بعد 24 ساعة. افتح agent.mjs وانظر إلى الأمر pay: لا يوجد فيه أي فحص للحدود. الوكيل يحاول الدفع فقط. كل حد سترى أثره يأتي من السلسلة.

الخطوة 1: ثبّت وأنشئ المفاتيح​

npm install

ينزّل الحزم المذكورة في package.json: حزمة QoreChain SDK وCosmJS و@noble/curves لمفتاح ed25519.

node agent.mjs init

ينشئ مفتاح ed25519 الخاص بالوكيل ومحفظة الغاز الخاصة به ويحفظهما في ~/.config/qday/agent.env، ولا يقرؤه غيرك. ويطبع عنوان qor1... لمحفظة الغاز.

node agent.mjs owner-init

ينشئ حساب مالك مؤقتًا للشبكة الاختبارية ويحفظه في ~/.config/qday/owner.env. لاستخدام حساب لديك بالفعل، ضع QORE_MNEMONIC="..." في هذا الملف بدلًا من ذلك. المفاتيح لا تغادر حاسوبك، ولا تُطبع أبدًا، ولا مكان لها في مستودع.

node agent.mjs whoami

يطبع العناوين الثلاثة: المالك ومفتاح الوكيل ومحفظة الغاز.

الخطوة 2: موّل المالك ومحفظة الغاز​

الصق كل عنوان qor1... في الصنبور. يحتاج المالك إلى بضع QOR للفواتير، ومحفظة الغاز إلى نحو 3 QOR للرسوم.

node agent.mjs balance

يتحقق من أن لدى كل منهما QOR.

الخطوة 3: سجّل المفاتيح ما بعد الكمومية، مرة واحدة​

node agent.mjs register owner
node agent.mjs register gas

يضع كل حساب مفتاحه العام ML-DSA-87 على السلسلة مع إثبات ملكية. ومن ذلك الحين يوقّع الاثنان كل معاملة بمفتاحين.

node agent.mjs link 1 3

يرسل المالك معاملة واحدة، موقّعة بالمفتاحين، تربط مفتاح ed25519 الخاص بالوكيل بحساب المالك (يوقّع مفتاح الوكيل إثباتًا بموافقته، فلا يستطيع أحد أن يربط مفتاحًا لا يملكه)، وتمنحه صلاحية واحدة (send)، وتكتب قاعدة إنفاق (1 QOR لكل دفعة، و3 QOR في اليوم، وuqor فقط)، وتحدد انتهاءً بعد 24 ساعة. أضف رقمًا ثالثًا لعدد ساعات آخر، بحد أقصى 30 يومًا. يجب أن ترى agent linked وhybrid ML-DSA-87: verified.

node agent.mjs rules

يقرأ من السلسلة ما تفرضه: القاعدة والصلاحية وموعد الانتهاء وعدد الدفعات التي أجراها الوكيل. لمعرفة كيف يعمل الربط، راجع المصادِقات.

الخطوة 5: دع الوكيل يدفع الفواتير​

node agent.mjs run bills.json

يحاول الوكيل دفع الفواتير الخمس في bills.json، بمجموع 8.2 QOR. يوقّع لكل منها طلبًا بمفتاح ed25519 الخاص به وترسله محفظة الغاز. يجب أن ترى:

الفاتورةالمبلغالنتيجةالسبب
Server hosting0.8PAID
Domain renewal0.5PAID
Invoice from an unknown sender5REFUSED BY THE CHAINتجاوزت حد 1 QOR لكل دفعة
API credits1PAID
Monitoring0.9REFUSED BY THE CHAINتجاوزت الحد اليومي 3 QOR: أُنفق 2.3 وبقي 0.7

الرفض يأتي من السلسلة، لا من شيفرة الوكيل. وتفصيل واحد في المستكشف: الدفعة المرفوضة تظهر مع ذلك معاملة بالرمز 0. فالمعاملة نفسها قُبلت في كتلة، لكن الدفعة داخلها رُفضت. يقرأ agent.mjs نتيجة الدفعة الداخلية، وهذا ما يطبعه.

الخطوة 6: اسحب صلاحية الوكيل​

node agent.mjs revoke

معاملة واحدة من المالك توقف مفتاح الوكيل.

node agent.mjs pay qor1s90l5nnwfjznf4cdj3p4pf2p7uk32axf8800yu 0.1 "after revoke"

يحاول دفعة أخرى. يجب أن ترى REFUSED BY THE CHAIN: linked key is unbound or revoked. فإذا اختُرق وكيل يومًا، فأقصى ما تخسره هو حدّه اليومي، ومعاملة واحدة توقفه.

لتشغيل العرض مرة أخرى، انقل ~/.config/qday/agent.env إلى مكان آخر (بعد نقل QOR الخاصة بمحفظة الغاز خارجها) ثم شغّل node agent.mjs init من جديد.

كل الأوامر: init وowner-init وwhoami وregister owner|gas وlink <perTxQOR> <dailyQOR> [hours] وrules وpay <to> <QOR> [memo] وrun <bills.json> وrevoke وbalance. يمكنك تغيير QORE_REST وQORE_RPC (عقدتك الخاصة) وQDAY_DIR (مكان ملفات المفاتيح) بمتغيرات البيئة.

الجزء 3: اسأل السلسلة، بـ MCP و qore-cli​

الشيفرة: workshop-2/03-mcp. MCP (Model Context Protocol) طريقة قياسية لمساعدي البرمجة وأدوات الذكاء الاصطناعي الأخرى لاستخدام أدوات خارجية. يمنحها خادم MCP الخاص بـ QoreChain، @qorechain/mcp، صلاحية القراءة على السلسلة: الكتل والمعاملات والحسابات وحالة المفتاح ما بعد الكمومي لحساب ما وتقديرات الرسوم والمحاكاة. فيه 14 أداة. وهو لا يوقّع ولا يحتفظ بالمفاتيح ولا يبثّ أبدًا: إذا طلبت تحويلًا أعطاك مستندًا غير موقّع توقّعه أنت في محفظتك.

أضفه إلى عميل MCP لديك​

يصلح أي عميل MCP. يستخدم معظمها إعدادًا كهذا:

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

يقوم npx -y بتنزيل الخادم في المرة الأولى وتشغيله. ثم يعرض العميل أدواته، مثل get_pq_status وget_transaction وget_address_info وread_contract وestimate_fee وsimulate_tx وprepare_transfer.

الأسئلة نفسها من الطرفية​

يعطي qore-cli الإجابات نفسها دون عميل ذكاء اصطناعي. اطرح ثلاثة أسئلة عمّا بنيته:

npx -y @qorechain/qore-cli pq status <hash of an agent payment>

هل وُقّعت دفعة الوكيل توقيعًا ما بعد كمومي؟ المتوقع: tier: pqc وverified: true. إنها معاملة أصلية (native)، موقّعة بالمفتاحين ومفحوصة من السلسلة.

npx -y @qorechain/qore-cli pq status <hash of the vault withdrawal>

وماذا عن سحب الخزنة؟ المتوقع: tier: classical وreason: evm_lane. وهذه إجابة صادقة: معاملات نمط إيثريوم لا تحمل توقيعًا ما بعد كمومي. تحميها نافذة EVM، وفي حالتنا عقد الخزنة الذي يفحص توقيع ML-DSA-87 بنفسه.

npx -y @qorechain/qore-cli pq status <your 0x or qor1 address>

وماذا عن الحساب؟ المتوقع: registered: true وpossession_proven: true، ونافذة EVM مع ما تبقى منها.

عميل مرئي (اختياري)​

للتنقل بين الأدوات بالنقر دون مساعد ذكاء اصطناعي:

npx -y @modelcontextprotocol/inspector npx -y @qorechain/mcp

ثم اختر Connect ثم Tools ثم List Tools، واختر get_pq_status، وضع عنوانًا أو hash في target، واختر Run Tool.

ما أصبح لديك الآن​

عقد لا يدفع إلا مقابل توقيع ما بعد كمومي، ووكيل تفرض السلسلة حدوده، وأدوات لفحص كيف حُميت أي معاملة. استخدم أيًّا منها أساسًا لمشاركتك: راجع Build Before Q-Day للمستويات والقواعد.