تخطي إلى المحتوى الرئيسي

إرسال المعاملات باستخدام ⁦viem⁩

المعاملات
viem
Alchemy
مبتدئ
إيلان هالبرن
4 نوفمبر 2020
10 دقيقة للقراءة

هذا دليل صديق للمبتدئين لإرسال معاملات إيثيريوم باستخدام مكتبة viem (يفتح في علامة تبويب جديدة). هناك ثلاث خطوات رئيسية من أجل إرسال معاملة إلى سلسلة كتل إيثيريوم: الإنشاء، والتوقيع، والبث. سنمر على الثلاثة، ونأمل أن نجيب على أي أسئلة قد تكون لديك! في هذا البرنامج التعليمي، سنستخدم Alchemy (يفتح في علامة تبويب جديدة) لإرسال معاملاتنا إلى سلسلة إيثيريوم. يمكنك إنشاء حساب Alchemy مجاني هنا (يفتح في علامة تبويب جديدة).

ملاحظة: هذا الدليل مخصص لتوقيع معاملاتك في الواجهة الخلفية لتطبيقك. إذا كنت ترغب في دمج توقيع معاملاتك في الواجهة الأمامية، فراجع واجهة برمجة تطبيقات مزود ميتاماسك (يفتح في علامة تبويب جديدة).

الأساسيات

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

1. لا تقوم Alchemy بتخزين مفاتيحك الخاصة

  • هذا يعني أن Alchemy لا يمكنها توقيع وإرسال المعاملات نيابة عنك. السبب في ذلك هو لأغراض أمنية. لن تطلب منك Alchemy أبدًا مشاركة مفتاحك الخاص، ويجب ألا تشارك مفتاحك الخاص أبدًا مع عقدة مستضافة (أو مع أي شخص آخر في هذا الصدد).
  • يمكنك القراءة من سلسلة الكتل باستخدام API الأساسية لـ Alchemy، ولكن للكتابة عليها ستحتاج إلى استخدام شيء آخر لتوقيع معاملاتك قبل إرسالها عبر Alchemy (وهذا ينطبق على أي خدمة عقدة أخرى).

2. ما هو "المُوقِّع"؟

  • سيقوم المُوقِّعون بتوقيع المعاملات نيابة عنك باستخدام مفتاحك الخاص. في هذا البرنامج التعليمي، سنستخدم viem (يفتح في علامة تبويب جديدة) لتوقيع معاملتنا، ولكن يمكنك أيضًا استخدام أي مكتبة Web3 أخرى.
  • في الواجهة الأمامية، من الأمثلة الجيدة على المُوقِّع ميتاماسك (يفتح في علامة تبويب جديدة)، والذي سيقوم بتوقيع وإرسال المعاملات نيابة عنك.

3. لماذا أحتاج إلى توقيع معاملاتي؟

  • يجب على كل مستخدم يرغب في إرسال معاملة على شبكة إيثيريوم توقيع المعاملة (باستخدام مفتاحه الخاص)، من أجل التحقق من أن مصدر المعاملة هو بالفعل الشخص الذي يدعيه.
  • من المهم جدًا حماية هذا المفتاح الخاص، حيث أن الوصول إليه يمنح تحكمًا كاملاً في حساب إيثيريوم الخاص بك، مما يسمح لك (أو لأي شخص لديه حق الوصول) بإجراء معاملات نيابة عنك.

4. كيف أحمي مفتاحي الخاص؟

  • هناك العديد من الطرق لحماية مفتاحك الخاص واستخدامه لإرسال المعاملات. في هذا البرنامج التعليمي، سنستخدم ملف .env. ومع ذلك، يمكنك أيضًا استخدام مزود منفصل يخزن المفاتيح الخاصة، أو استخدام ملف مخزن المفاتيح، أو خيارات أخرى.

5. ما الفرق بين eth_sendTransaction و eth_sendRawTransaction؟

eth_sendTransaction و eth_sendRawTransaction هما دالتان في واجهة برمجة تطبيقات (API) إيثيريوم تقومان ببث معاملة إلى شبكة إيثيريوم بحيث تتم إضافتها إلى كتلة مستقبلية. يختلفان في كيفية تعاملهما مع توقيع المعاملات.

عند استخدام viem، يتم الوصول إلى eth_sendRawTransaction عن طريق استدعاء الدالة sendRawTransaction (يفتح في علامة تبويب جديدة).

هذا ما سنستخدمه في هذا البرنامج التعليمي.

6. ما هي مكتبة Web3؟

حسنًا، الآن بعد أن أجبنا على بعض هذه الأسئلة، دعنا ننتقل إلى البرنامج التعليمي. لا تتردد في طرح الأسئلة في أي وقت في ديسكورد (يفتح في علامة تبويب جديدة) الخاص بـ Alchemy!

7. كيف ترسل معاملات آمنة، ومُحسَّنة الغاز، وخاصة؟

ملاحظة: يتطلب هذا الدليل حساب Alchemy، وعنوان إيثيريوم أو محفظة ميتاماسك، وتثبيت Node.js و npm. إذا لم يكن لديك ذلك، فاتبع هذه الخطوات:

  1. إنشاء حساب Alchemy مجاني (يفتح في علامة تبويب جديدة)
  2. إنشاء حساب ميتاماسك (يفتح في علامة تبويب جديدة) (أو الحصول على عنوان إيثيريوم)
  3. تثبيت Node.js و npm (يفتح في علامة تبويب جديدة)

خطوات إرسال معاملتك

1. إنشاء تطبيق Alchemy على شبكة اختبار Sepolia

انتقل إلى لوحة تحكم Alchemy (يفتح في علامة تبويب جديدة) الخاصة بك وأنشئ تطبيقًا جديدًا، مع اختيار Sepolia (أو أي شبكة اختبار أخرى) كشبكتك.

2. طلب ETH من صنبور Sepolia

اتبع التعليمات الموجودة على صنبور Sepolia من Alchemy (يفتح في علامة تبويب جديدة) لتلقي ETH، أو استخدم أحد صنابير Sepolia الأخرى. توزع الصنابير مبالغ صغيرة (يعطي صنبور Alchemy 0.1 ETH يوميًا)، وهو ما يكفي لهذا البرنامج التعليمي. تأكد من تضمين عنوان إيثيريوم الخاص بك على Sepolia (من ميتاماسك) وليس شبكة أخرى. بعد اتباع التعليمات، تحقق مرة أخرى من أنك تلقيت ETH في محفظتك.

3. إنشاء دليل مشروع جديد والانتقال إليه باستخدام cd

أنشئ دليل مشروع جديد من سطر الأوامر (الطرفية لأجهزة Mac) وانتقل إليه:

mkdir sendtx-example
cd sendtx-example

4. تثبيت viem (أو أي مكتبة Web3)

قم بتشغيل الأمر التالي في دليل مشروعك لتثبيت viem (يفتح في علامة تبويب جديدة):

ملاحظة، إذا كنت ترغب في استخدام مكتبة Ethers.js، فاتبع التعليمات هنا (يفتح في علامة تبويب جديدة).

npm init -y
npm install viem

5. تثبيت dotenv

سنستخدم ملف .env لتخزين مفتاح API والمفتاح الخاص بنا بأمان.

npm install dotenv

6. إنشاء ملف .env

أنشئ ملف .env في دليل مشروعك وأضف ما يلي (مع استبدال "your-api-url" و "your-private-key")

  • للعثور على عنوان URL لواجهة برمجة تطبيقات Alchemy الخاصة بك، انتقل إلى صفحة تفاصيل التطبيق للتطبيق الذي أنشأته للتو في لوحة التحكم الخاصة بك، وانقر على "View Key" في الزاوية العلوية اليمنى، وانسخ عنوان URL لـ HTTP.
  • للعثور على مفتاحك الخاص باستخدام ميتاماسك، راجع هذا الدليل (يفتح في علامة تبويب جديدة). استخدم حسابًا يحتوي فقط على ETH لشبكة اختبار.
API_URL="your-api-url"
PRIVATE_KEY="your-private-key"
لا تقم بإيداع (commit) ملف .env! يرجى التأكد من عدم مشاركة أو كشف ملف .env الخاص بك لأي شخص، حيث أنك تعرض أسرارك للخطر بفعل ذلك. إذا كنت تستخدم نظام التحكم في الإصدارات، فأضف ملف .env الخاص بك إلى ملف gitignore.

7. إنشاء ملف sendTx.js

رائع، الآن بعد أن قمنا بحماية بياناتنا الحساسة في ملف .env، دعنا نبدأ في كتابة التعليمات البرمجية. في مثال إرسال المعاملة الخاص بنا، سنرسل 0.001 ETH إلى عنوان آخر تتحكم فيه، مثل حساب ثانٍ في ميتاماسك.

أنشئ ملف sendTx.js، وهو المكان الذي سنقوم فيه بتكوين وإرسال معاملة المثال الخاصة بنا، وأضف إليه أسطر التعليمات البرمجية التالية:

تأكد من استبدال 0xYourSecondAddress بالعنوان الذي تريد إرسال ETH إليه. يستخرج البرنامج النصي عنوانك الخاص (المرسل) من PRIVATE_KEY، لذلك لا تحتاج إلى إدخاله.

الآن، قبل أن ننتقل إلى تشغيل هذه التعليمات البرمجية، دعنا نتحدث عن بعض المكونات هنا.

  • account: حساب محلي تم إنشاؤه من مفتاحك الخاص باستخدام privateKeyToAccount (يفتح في علامة تبويب جديدة). يتم التوقيع على جهازك، ولا يتم إرسال المفتاح الخاص أبدًا إلى Alchemy.
  • publicClient و walletClient: عملاء viem الذين يرسلون طلبات JSON-RPC إلى عنوان URL الخاص بـ Alchemy. يقرأ العميل العام من السلسلة، ويقوم عميل المحفظة بإعداد وتوقيع المعاملات لحسابك.
  • nonce: تُستخدم مواصفات الرقم الفريد لتتبع عدد المعاملات المرسلة من عنوانك. نحتاج إلى هذا لأغراض أمنية ولمنع هجمات إعادة التشغيل. للحصول على عدد المعاملات المرسلة من عنوانك، نستخدم getTransactionCount (يفتح في علامة تبويب جديدة). ستقوم viem أيضًا بملء هذا نيابة عنك، لكننا نجلبه صراحةً هنا لإظهار من أين يأتي.
  • transaction: يحتوي كائن المعاملة على بعض الجوانب التي نحتاج إلى تحديدها. تقوم prepareTransactionRequest (يفتح في علامة تبويب جديدة) بملء الباقي لنا، بما في ذلك chainId وحقول رسوم EIP-1559 maxFeePerGas و maxPriorityFeePerGas، بناءً على ظروف الشبكة الحالية
    • to: هذا هو العنوان الذي نريد إرسال ETH إليه.
    • value: هذا هو المبلغ الذي نرغب في إرساله، محددًا بوحدة Wei حيث 10^18 Wei = 1 ETH. تقوم parseEther (يفتح في علامة تبويب جديدة) بتحويل مبلغ ETH إلى Wei نيابة عنا. يحتاج حسابك إلى أكثر من هذا بقليل، لأنه يدفع أيضًا مقابل الغاز
    • gas: هناك العديد من الطرق لتحديد الكمية المناسبة من الغاز لتضمينها في معاملتك. تدعم Alchemy خطافات الويب (webhooks) (يفتح في علامة تبويب جديدة) التي يمكنها إعلامك بالنشاط على السلسلة. بالنسبة لمعاملات الشبكة الرئيسية، من الممارسات الجيدة التحقق من ظروف الغاز الحالية لتحديد الكمية المناسبة من الغاز لتضمينها. يستخدم تحويل ETH العادي إلى عنوان عادي دائمًا 21000 غاز بالضبط، وهو الحد الأدنى لأي معاملة، لذلك نضع 21000 هنا. إذا تركت gas فارغًا، فستقوم viem بتقديره نيابة عنك.
    • nonce: راجع تعريف الرقم الفريد أعلاه. يبدأ الرقم الفريد في العد من الصفر.
    • [اختياري] data: تُستخدم لإرسال معلومات إضافية مع تحويلك، أو استدعاء عقد ذكي، وهي غير مطلوبة لتحويلات الرصيد، راجع الملاحظة أدناه.
  • signedTx: لتوقيع كائن المعاملة الخاص بنا، سنستخدم طريقة signTransaction، والتي تقوم بتوقيعه محليًا باستخدام الحساب الذي تم إنشاؤه من PRIVATE_KEY الخاص بنا
  • sendRawTransaction: بمجرد أن يكون لدينا معاملة موقعة، يمكننا إرسالها ليتم تضمينها في كتلة لاحقة باستخدام sendRawTransaction، والتي تستدعي eth_sendRawTransaction
  • waitForTransactionReceipt: تنتظر حتى يتم تضمين المعاملة في كتلة وتعيد إيصالها

ملاحظة حول البيانات (data) هناك نوعان رئيسيان من المعاملات التي يمكن إرسالها في إيثيريوم.

  • تحويل الرصيد: إرسال ETH من عنوان إلى آخر. لا يلزم وجود حقل بيانات، ومع ذلك، إذا كنت ترغب في إرسال معلومات إضافية إلى جانب معاملتك، فيمكنك تضمين هذه المعلومات بتنسيق HEX في هذا الحقل.
    • على سبيل المثال، لنفترض أننا أردنا كتابة تجزئة مستند IPFS إلى سلسلة إيثيريوم من أجل إعطائه طابعًا زمنيًا غير قابل للتغيير. يجب أن يبدو حقل البيانات الخاص بنا حينئذٍ مثل data: toHex("IPFS hash")، باستخدام toHex (يفتح في علامة تبويب جديدة) الخاصة بـ viem. والآن يمكن لأي شخص الاستعلام عن السلسلة ومعرفة متى تمت إضافة هذا المستند.
  • معاملة العقد الذكي: تنفيذ بعض التعليمات البرمجية للعقد الذكي على السلسلة. في هذه الحالة، يجب أن يحتوي حقل البيانات على الدالة الذكية التي ترغب في تنفيذها، إلى جانب أي معلمات.

8. تشغيل التعليمات البرمجية باستخدام node sendTx.js

ارجع إلى الطرفية أو سطر الأوامر وقم بتشغيل:

node sendTx.js

9. رؤية معاملتك على مستكشف الكتل

يطبع البرنامج النصي تجزئة المعاملة بمجرد أن تقبل العقدة المعاملة، ثم ينتظر حتى يتم تضمينها في كتلة (عادةً في غضون ثوانٍ قليلة) ويطبع النتيجة. لرؤية التفاصيل، الصق التجزئة في مستكشف كتل Sepolia مثل Sepolia Etherscan (يفتح في علامة تبويب جديدة) أو Blockscout (يفتح في علامة تبويب جديدة). هناك يمكنك مشاهدة المعاملة تنتقل من معلقة إلى مضمنة، ورؤية المبلغ والرسوم والكتلة التي هبطت فيها.

إذا رأيت خطأ insufficient funds بدلاً من ذلك، فهذا يعني أن حسابك لا يحتوي على ما يكفي من Sepolia ETH لتغطية القيمة بالإضافة إلى الغاز. ارجع إلى الخطوة 2 واطلب المزيد من صنبور.

مرحى! لقد أرسلت للتو أول معاملة إيثيريوم لك باستخدام Alchemy 🎉

للحصول على ملاحظات واقتراحات حول هذا الدليل، يرجى مراسلة Elan على ديسكورد (يفتح في علامة تبويب جديدة) الخاص بـ Alchemy!

نُشر في الأصل بواسطة Alchemy.