إرسال المعاملات باستخدام viem
هذا دليل صديق للمبتدئين لإرسال معاملات إيثيريوم باستخدام مكتبة 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) إيثيريوم تقومان ببث معاملة إلى شبكة إيثيريوم بحيث تتم إضافتها إلى كتلة مستقبلية. يختلفان في كيفية تعاملهما مع توقيع المعاملات.
- تُستخدم
eth_sendTransactionلإرسال معاملات غير موقعة، مما يعني أن العقدة التي ترسل إليها يجب أن تدير مفتاحك الخاص حتى تتمكن من توقيع المعاملة قبل بثها إلى السلسلة. نظرًا لأن Alchemy لا تحتفظ بالمفاتيح الخاصة للمستخدمين، فإنها لا تدعم هذه الطريقة. - تُستخدم
eth_sendRawTransaction(يفتح في علامة تبويب جديدة) لبث المعاملات التي تم توقيعها بالفعل. هذا يعني أنه يجب عليك أولاً توقيع المعاملة باستخدام مفتاحك الخاص (في viem، باستخدامsignTransaction(يفتح في علامة تبويب جديدة) مع حساب محلي (يفتح في علامة تبويب جديدة))، ثم تمرير النتيجة إلىeth_sendRawTransaction.
عند استخدام viem، يتم الوصول إلى eth_sendRawTransaction عن طريق استدعاء الدالة sendRawTransaction (يفتح في علامة تبويب جديدة).
هذا ما سنستخدمه في هذا البرنامج التعليمي.
6. ما هي مكتبة Web3؟
- مكتبة Web3 هي غلاف حول استدعاءات JSON-RPC القياسية والتي يشيع استخدامها في تطوير إيثيريوم.
- هناك العديد من مكتبات Web3 للغات مختلفة. في هذا البرنامج التعليمي، سنستخدم viem (يفتح في علامة تبويب جديدة)، المكتوبة بلغة TypeScript وتعمل في أي مشروع 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 الأخرى. توزع الصنابير مبالغ صغيرة (يعطي صنبور 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"
.env! يرجى التأكد من عدم مشاركة أو كشف ملف .env الخاص بك لأي شخص، حيث أنك تعرض أسرارك للخطر بفعل ذلك. إذا كنت تستخدم نظام التحكم في الإصدارات، فأضف ملف .env الخاص بك إلى ملف gitignore.7. إنشاء ملف sendTx.js
رائع، الآن بعد أن قمنا بحماية بياناتنا الحساسة في ملف .env، دعنا نبدأ في كتابة التعليمات البرمجية. في مثال إرسال المعاملة الخاص بنا، سنرسل 0.001 ETH إلى عنوان آخر تتحكم فيه، مثل حساب ثانٍ في ميتاماسك.
أنشئ ملف sendTx.js، وهو المكان الذي سنقوم فيه بتكوين وإرسال معاملة المثال الخاصة بنا، وأضف إليه أسطر التعليمات البرمجية التالية:
require("dotenv").config({ quiet: true })
const { createPublicClient, createWalletClient, http, parseEther } = require("viem")
const { privateKeyToAccount } = require("viem/accounts")
const { sepolia } = require("viem/chains")
async function main() {
const { API_URL, PRIVATE_KEY } = process.env
const account = privateKeyToAccount(
PRIVATE_KEY.startsWith("0x") ? PRIVATE_KEY : `0x${PRIVATE_KEY}`
)
const publicClient = createPublicClient({
chain: sepolia,
transport: http(API_URL),
})
const walletClient = createWalletClient({
account,
chain: sepolia,
transport: http(API_URL),
})
const nonce = await publicClient.getTransactionCount({
address: account.address,
blockTag: "pending",
}) // يبدأ الرقم الفريد العد من 0
const transaction = await walletClient.prepareTransactionRequest({
to: "0xYourSecondAddress", // TODO: استبدله بالعنوان الذي تريد إرسال ETH إليه
value: parseEther("0.001"), // 0.001 ETH
gas: 21000n,
nonce,
// حقل بيانات اختياري لإرسال رسالة أو تنفيذ عقد ذكي
})
const signedTx = await walletClient.signTransaction(transaction)
try {
const hash = await walletClient.sendRawTransaction({
serializedTransaction: signedTx,
})
console.log("🎉 The hash of your transaction is:", hash)
const receipt = await publicClient.waitForTransactionReceipt({ hash })
console.log(`Transaction ${receipt.status} in block ${receipt.blockNumber}`)
} catch (error) {
console.log(
"❗Something went wrong while submitting your transaction:",
error.details ?? error.message
)
}
}
main()
تأكد من استبدال 0xYourSecondAddress بالعنوان الذي تريد إرسال ETH إليه. يستخرج البرنامج النصي عنوانك الخاص (المرسل) من PRIVATE_KEY، لذلك لا تحتاج إلى إدخاله.
الآن، قبل أن ننتقل إلى تشغيل هذه التعليمات البرمجية، دعنا نتحدث عن بعض المكونات هنا.
account: حساب محلي تم إنشاؤه من مفتاحك الخاص باستخدامprivateKeyToAccount(يفتح في علامة تبويب جديدة). يتم التوقيع على جهازك، ولا يتم إرسال المفتاح الخاص أبدًا إلى Alchemy.publicClientوwalletClient: عملاء viem الذين يرسلون طلبات JSON-RPC إلى عنوان URL الخاص بـ Alchemy. يقرأ العميل العام من السلسلة، ويقوم عميل المحفظة بإعداد وتوقيع المعاملات لحسابك.nonce: تُستخدم مواصفات الرقم الفريد لتتبع عدد المعاملات المرسلة من عنوانك. نحتاج إلى هذا لأغراض أمنية ولمنع هجمات إعادة التشغيل. للحصول على عدد المعاملات المرسلة من عنوانك، نستخدم getTransactionCount (يفتح في علامة تبويب جديدة). ستقوم viem أيضًا بملء هذا نيابة عنك، لكننا نجلبه صراحةً هنا لإظهار من أين يأتي.transaction: يحتوي كائن المعاملة على بعض الجوانب التي نحتاج إلى تحديدها. تقومprepareTransactionRequest(يفتح في علامة تبويب جديدة) بملء الباقي لنا، بما في ذلكchainIdوحقول رسوم EIP-1559maxFeePerGasو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_sendRawTransactionwaitForTransactionReceipt: تنتظر حتى يتم تضمين المعاملة في كتلة وتعيد إيصالها
ملاحظة حول البيانات (data) هناك نوعان رئيسيان من المعاملات التي يمكن إرسالها في إيثيريوم.
- تحويل الرصيد: إرسال ETH من عنوان إلى آخر. لا يلزم وجود حقل بيانات، ومع ذلك، إذا كنت ترغب في إرسال معلومات إضافية إلى جانب معاملتك، فيمكنك تضمين هذه المعلومات بتنسيق HEX في هذا الحقل.
- على سبيل المثال، لنفترض أننا أردنا كتابة تجزئة مستند IPFS إلى سلسلة إيثيريوم من أجل إعطائه طابعًا زمنيًا غير قابل للتغيير. يجب أن يبدو حقل البيانات الخاص بنا حينئذٍ مثل
data: toHex("IPFS hash")، باستخدامtoHex(يفتح في علامة تبويب جديدة) الخاصة بـ viem. والآن يمكن لأي شخص الاستعلام عن السلسلة ومعرفة متى تمت إضافة هذا المستند.
- على سبيل المثال، لنفترض أننا أردنا كتابة تجزئة مستند IPFS إلى سلسلة إيثيريوم من أجل إعطائه طابعًا زمنيًا غير قابل للتغيير. يجب أن يبدو حقل البيانات الخاص بنا حينئذٍ مثل
- معاملة العقد الذكي: تنفيذ بعض التعليمات البرمجية للعقد الذكي على السلسلة. في هذه الحالة، يجب أن يحتوي حقل البيانات على الدالة الذكية التي ترغب في تنفيذها، إلى جانب أي معلمات.
- للحصول على مثال عملي، راجع البرنامج التعليمي للعقد الذكي Hello World.
8. تشغيل التعليمات البرمجية باستخدام node sendTx.js
ارجع إلى الطرفية أو سطر الأوامر وقم بتشغيل:
node sendTx.js
9. رؤية معاملتك على مستكشف الكتل
يطبع البرنامج النصي تجزئة المعاملة بمجرد أن تقبل العقدة المعاملة، ثم ينتظر حتى يتم تضمينها في كتلة (عادةً في غضون ثوانٍ قليلة) ويطبع النتيجة. لرؤية التفاصيل، الصق التجزئة في مستكشف كتل Sepolia مثل Sepolia Etherscan (يفتح في علامة تبويب جديدة) أو Blockscout (يفتح في علامة تبويب جديدة). هناك يمكنك مشاهدة المعاملة تنتقل من معلقة إلى مضمنة، ورؤية المبلغ والرسوم والكتلة التي هبطت فيها.
إذا رأيت خطأ insufficient funds بدلاً من ذلك، فهذا يعني أن حسابك لا يحتوي على ما يكفي من Sepolia ETH لتغطية القيمة بالإضافة إلى الغاز. ارجع إلى الخطوة 2 واطلب المزيد من صنبور.
مرحى! لقد أرسلت للتو أول معاملة إيثيريوم لك باستخدام Alchemy 🎉
للحصول على ملاحظات واقتراحات حول هذا الدليل، يرجى مراسلة Elan على ديسكورد (يفتح في علامة تبويب جديدة) الخاص بـ Alchemy!
نُشر في الأصل بواسطة Alchemy.