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

المعاملات

web3.js

Alchemy

مبتدئ

إيلان هالبرن

4 نوفمبر 2020

9 دقيقة للقراءة

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

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

الأساسيات

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

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

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

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

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

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

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

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

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

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

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

تُستخدم eth_sendTransaction (يفتح في علامة تبويب جديدة) لإرسال المعاملات غير الموقعة، مما يعني أن العقدة التي ترسل إليها يجب أن تدير مفتاحك الخاص حتى تتمكن من توقيع المعاملة قبل بثها إلى السلسلة. نظرًا لأن Alchemy لا تحتفظ بالمفاتيح الخاصة للمستخدمين، فإنها لا تدعم هذه الطريقة.
تُستخدم eth_sendRawTransaction (يفتح في علامة تبويب جديدة) لبث المعاملات التي تم توقيعها بالفعل. هذا يعني أنه يجب عليك أولاً استخدام signTransaction(tx, private_key) (يفتح في علامة تبويب جديدة)، ثم تمرير النتيجة إلى eth_sendRawTransaction.

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

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

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

Web3.js هي مكتبة تغليف (wrapper) حول استدعاءات JSON-RPC القياسية والتي يشيع استخدامها في تطوير إيثيريوم.
هناك العديد من مكتبات Web3 للغات مختلفة. في هذا البرنامج التعليمي، سنستخدم Alchemy Web3 (يفتح في علامة تبويب جديدة) المكتوبة بلغة JavaScript. يمكنك التحقق من الخيارات الأخرى هنا مثل Ethers.js (يفتح في علامة تبويب جديدة).

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

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

تمتلك Alchemy مجموعة من الموارد الخاصة بالمعاملات (يفتح في علامة تبويب جديدة). يمكنك استخدامها لإرسال المعاملات، ومحاكاة المعاملات قبل حدوثها، وإرسال معاملات خاصة، وإرسال معاملات مُحسَّنة الغاز.
يمكنك أيضًا استخدام خطافات الويب (webhooks) الخاصة بـ Alchemy (يفتح في علامة تبويب جديدة) لتلقي تنبيهات عندما يتم سحب معاملتك من مجمع الذاكرة وإضافتها إلى السلسلة.

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

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

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

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

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

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

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

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

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

mkdir sendtx-example
cd sendtx-example

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

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

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

npm install @alch/alchemy-web3

5. تثبيت dotenv

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

npm install dotenv --save

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

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

للعثور على عنوان URL الخاص بـ API لـ Alchemy، انتقل إلى صفحة تفاصيل التطبيق الذي أنشأته للتو في لوحة التحكم الخاصة بك، وانقر على "View Key" في الزاوية العلوية اليمنى، وانسخ عنوان HTTP URL.
للعثور على مفتاحك الخاص باستخدام ميتاماسك، تحقق من هذا الدليل (يفتح في علامة تبويب جديدة).

API_URL = "your-api-url"
PRIVATE_KEY = "your-private-key"

لا تقم بإيداع (commit) ملف .env! يرجى التأكد من عدم مشاركة أو كشف ملف .env الخاص بك لأي شخص، حيث أنك تعرض أسرارك للخطر بفعل ذلك. إذا كنت تستخدم نظام التحكم في الإصدارات (version control)، فأضف ملف .env إلى ملف gitignore.

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

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

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

async function main() {
    require('dotenv').config();
    const { API_URL, PRIVATE_KEY } = process.env;
    const { createAlchemyWeb3 } = require("@alch/alchemy-web3");
    const web3 = createAlchemyWeb3(API_URL);
    const myAddress = '0x610Ae88399fc1687FA7530Aac28eC2539c7d6d63' //TODO: استبدل هذا العنوان بعنوانك العام

    const nonce = await web3.eth.getTransactionCount(myAddress, 'latest'); // يبدأ الرقم الفريد (nonce) العد من 0

    const transaction = {
     'to': '0x31B98D14007bDEe637298086988A0bBd31184523', // عنوان الصنبور لإرجاع eth
     'value': 1000000000000000000, // 1 ETH
     'gas': 30000,
     'nonce': nonce,
     // حقل بيانات اختياري لإرسال رسالة أو تنفيذ عقد ذكي
    };

    const signedTx = await web3.eth.accounts.signTransaction(transaction, PRIVATE_KEY);

    web3.eth.sendSignedTransaction(signedTx.rawTransaction, function(error, hash) {
    if (!error) {
      console.log("🎉 The hash of your transaction is: ", hash, "\n Check Alchemy's Mempool to view the status of your transaction!");
    } else {
      console.log("❗Something went wrong while submitting your transaction:", error)
    }
   });
}

main();

تأكد من استبدال العنوان في السطر 6 بعنوانك العام.

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

nonce: تُستخدم مواصفة الرقم الفريد (nonce) لتتبع عدد المعاملات المرسلة من عنوانك. نحتاج إلى هذا لأغراض أمنية ولمنع هجمات إعادة الإرسال (replay attacks). للحصول على عدد المعاملات المرسلة من عنوانك، نستخدم getTransactionCount (يفتح في علامة تبويب جديدة).
transaction: يحتوي كائن المعاملة على بعض الجوانب التي نحتاج إلى تحديدها
- to: هذا هو العنوان الذي نريد إرسال ETH إليه. في هذه الحالة، نقوم بإرسال ETH مرة أخرى إلى صنبور Sepolia (يفتح في علامة تبويب جديدة) الذي طلبنا منه في البداية.
- value: هذا هو المبلغ الذي نرغب في إرساله، محددًا بوحدة Wei حيث 10^18 Wei = 1 ETH
- gas: هناك العديد من الطرق لتحديد الكمية المناسبة من الغاز لتضمينها مع معاملتك. تدعم Alchemy خطافات الويب (webhooks) (يفتح في علامة تبويب جديدة) التي يمكنها إعلامك بالنشاط على السلسلة. بالنسبة لمعاملات الشبكة الرئيسية، من الممارسات الجيدة التحقق من ظروف الغاز الحالية لتحديد الكمية المناسبة من الغاز لتضمينها. 21,000 هو الحد الأدنى لكمية الغاز التي ستستخدمها أي عملية على إيثيريوم، لذا لضمان تنفيذ معاملتنا نضع 30,000 هنا.
- nonce: راجع تعريف الرقم الفريد أعلاه. يبدأ الرقم الفريد العد من الصفر.
- [اختياري] data: يُستخدم لإرسال معلومات إضافية مع تحويلك، أو استدعاء عقد ذكي، وهو غير مطلوب لتحويلات الرصيد، تحقق من الملاحظة أدناه.
signedTx: لتوقيع كائن المعاملة الخاص بنا، سنستخدم طريقة signTransaction مع PRIVATE_KEY الخاص بنا.
sendSignedTransaction: بمجرد أن يكون لدينا معاملة موقعة، يمكننا إرسالها ليتم تضمينها في كتلة لاحقة باستخدام sendSignedTransaction.

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

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

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

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

node sendTx.js

9. رؤية معاملتك في مجمع الذاكرة (Mempool)

افتح صفحة مجمع الذاكرة (يفتح في علامة تبويب جديدة) في لوحة تحكم Alchemy الخاصة بك وقم بالتصفية حسب التطبيق الذي أنشأته للعثور على معاملتك. هذا هو المكان الذي يمكننا فيه مشاهدة انتقال معاملتنا من حالة التعليق (pending) إلى حالة التعدين (mined) (إذا نجحت) أو حالة الإسقاط (dropped) إذا لم تنجح. تأكد من إبقائها على "الكل" (All) حتى تتمكن من التقاط المعاملات "المُعدَّنة" و"المُعلَّقة" و"المُسقَطة". يمكنك أيضًا البحث عن معاملتك من خلال البحث عن المعاملات المرسلة إلى العنوان 0x31b98d14007bdee637298086988a0bbd31184523 .

لعرض تفاصيل معاملتك بمجرد العثور عليها، حدد تجزئة المعاملة (tx hash)، والتي يجب أن تنقلك إلى عرض يبدو كالتالي:

من هناك يمكنك عرض معاملتك على Etherscan بالنقر فوق الرمز المحاط بدائرة حمراء!

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

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

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