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

المعاملات

web3.js

Alchemy

مبتدئ

إيلان هالبرن

4 نوفمبر 2020

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

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

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

الأساسيات

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

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

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

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

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

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

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

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

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

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

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

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

عند استخدام Web3، يتم الوصول إلى eth_sendRawTransaction عن طريق استدعاء الدالة web3.eth.sendSignedTransaction (opens in a new tab).

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

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

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

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

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

تمتلك Alchemy مجموعة من واجهات برمجة تطبيقات المعاملات (Transact APIs) (opens in a new tab). يمكنك استخدامها لإرسال معاملات معززة، ومحاكاة المعاملات قبل حدوثها، وإرسال معاملات خاصة، وإرسال معاملات مُحسّنة الغاز.
يمكنك أيضًا استخدام Notify API (opens in a new tab) لتلقي تنبيهات عندما يتم سحب معاملتك من مجمع الذاكرة وإضافتها إلى السلسلة.

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

إنشاء حساب Alchemy مجاني (opens in a new tab)
إنشاء حساب ميتاماسك (opens in a new tab) (أو الحصول على عنوان إيثيريوم)
اتبع هذه الخطوات لتثبيت NodeJs و NPM (opens in a new tab)

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

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

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

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

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

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

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

mkdir sendtx-example
cd sendtx-example

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

قم بتشغيل الأمر التالي في دليل مشروعك لتثبيت Alchemy Web3 (opens in a new tab):

ملاحظة، إذا كنت ترغب في استخدام مكتبة Ethers.js، فاتبع التعليمات هنا (opens in a new tab).

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.
للعثور على مفتاحك الخاص باستخدام ميتاماسك، تحقق من هذا الدليل (opens in a new tab).

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("🎉 تجزئة معاملتك هي: ", hash, "\n تحقق من مجمع الذاكرة الخاص بـ Alchemy لعرض حالة معاملتك!");
    } else {
      console.log("❗حدث خطأ ما أثناء إرسال معاملتك:", error)
    }
   });
}

main();

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

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

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

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

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

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

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

node sendTx.js

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

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

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

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

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

للملاحظات والاقتراحات حول هذا الدليل، يرجى مراسلة إيلان على ديسكورد (opens in a new tab) الخاص بـ Alchemy!

نُشر في الأصل على https://docs.alchemyapi.io/tutorials/sending-transactions-using-web3-and-alchemy (opens in a new tab)