عقد ذكي ⁦Hello World⁩ للمبتدئين

Solidity

Hardhat

Alchemy

عقود ذكية

نشر

مبتدئ

إيلانه

31 مارس 2021

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

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

بمجرد نشر عقدك، يمكنك بناء واجهة مستخدم له.

إذا كانت لديك أسئلة في أي وقت، فلا تتردد في التواصل معنا في ديسكورد Alchemy (يفتح في علامة تبويب جديدة)!

الخطوة 1: الاتصال بشبكة إيثيريوم

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

الخطوة 2: إنشاء تطبيقك (ومفتاح API)

بمجرد إنشاء حساب Alchemy، يمكنك إنشاء مفتاح API عن طريق إنشاء تطبيق. سيسمح لنا ذلك بتقديم طلبات إلى شبكة اختبار Sepolia. إذا لم تكن على دراية بشبكات الاختبار، فراجع هذه الصفحة.

انتقل إلى صفحة "Create new app" (إنشاء تطبيق جديد) في لوحة تحكم Alchemy الخاصة بك عن طريق تحديد "Select an app" (تحديد تطبيق) في شريط التنقل والنقر على "Create new app"

قم بتسمية تطبيقك "Hello World"، وقدم وصفًا قصيرًا، واختر حالة استخدام، على سبيل المثال، "Infra & Tooling". بعد ذلك، ابحث عن "Ethereum" وحدد الشبكة.

انقر على "Next" (التالي) للمتابعة، ثم "Create app" (إنشاء تطبيق) وهذا كل شيء! يجب أن يظهر تطبيقك في القائمة المنسدلة لشريط التنقل، مع توفر مفتاح API للنسخ.

الخطوة 3: إنشاء حساب إيثيريوم (عنوان)

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

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

إذا لم ترَ Sepolia مدرجة، فافتح القائمة في الزاوية العلوية اليمنى، وحدد "Networks" (الشبكات)، وقم بتشغيل "Show test networks" (إظهار شبكات الاختبار) في أسفل قائمة الشبكات (راجع دليل ميتاماسك لعرض شبكات الاختبار (يفتح في علامة تبويب جديدة)). ثم حدد "Sepolia" في قائمة اختيار الشبكة.

الخطوة 4: إضافة إيثر من صنبور

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

الخطوة 5: التحقق من رصيدك

للتحقق مرة أخرى من وجود رصيدنا، دعنا نجري طلب eth_getBalance باستخدام أداة الملحن الخاصة بـ Alchemy (يفتح في علامة تبويب جديدة). سيعيد هذا مقدار ETH في محفظتنا. بعد إدخال عنوان حساب ميتاماسك الخاص بك والنقر على "Send Request" (إرسال طلب)، يجب أن ترى استجابة مثل هذه:

{ "jsonrpc": "2.0", "id": 0, "result": "0x2B5E3AF16B1880000" }

ملاحظة: هذه النتيجة بوحدة Wei وليس ETH. تُستخدم Wei كأصغر فئة من الإيثر. التحويل من Wei إلى ETH هو: 1 eth = 10¹⁸ wei. لذا إذا قمنا بتحويل 0x2B5E3AF16B1880000 إلى النظام العشري نحصل على 5*10¹⁸ والذي يساوي 5 ETH.

أوف! أموالنا الوهمية كلها موجودة .

الخطوة 6: تهيئة مشروعنا

أولاً، سنحتاج إلى إنشاء مجلد لمشروعنا. انتقل إلى سطر الأوامر واكتب:

mkdir hello-world
cd hello-world

الآن بعد أن أصبحنا داخل مجلد مشروعنا، سنستخدم npm init لتهيئة المشروع. إذا لم يكن لديك npm مثبتًا بالفعل، فاتبع إرشادات تثبيت Node.js (يفتح في علامة تبويب جديدة) (سنحتاج إلى Node.js وnpm لهذا البرنامج التعليمي).

npm init

لا يهم حقًا كيف تجيب على أسئلة التثبيت، إليك كيف فعلنا ذلك كمرجع:

package name: (hello-world)
version: (1.0.0)
description: hello world smart contract
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to /Users/.../.../.../hello-world/package.json:

{
  "name": "hello-world",
  "version": "1.0.0",
  "description": "hello world smart contract",
  "main": "index.js",
  "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

وافق على package.json. يدعم Hardhat 3، الذي سنقوم بتثبيته بعد ذلك، مشاريع وحدات ES فقط، لذا حدد المشروع كواحد منها:

npm pkg set type=module

ونحن جاهزون للبدء!

الخطوة 7: تنزيل Hardhat (يفتح في علامة تبويب جديدة)

Hardhat هي بيئة تطوير لتجميع برامج إيثيريوم الخاصة بك ونشرها واختبارها وتصحيح أخطائها. إنها تساعد المطورين عند بناء العقود الذكية والتطبيقات اللامركزية (dapps) محليًا قبل النشر على السلسلة المباشرة.

يتطلب Hardhat 3 إصدار Node.js v22.13.0 أو أحدث. داخل مشروع hello-world الخاص بنا، قم بتشغيل:

npm install --save-dev hardhat

تحقق من هذه الصفحة لمزيد من التفاصيل حول إرشادات التثبيت (يفتح في علامة تبويب جديدة).

الخطوة 8: إنشاء مشروع Hardhat

سيؤدي تشغيل npx hardhat --init إلى إنشاء مشروع نموذج كامل، ولكن في هذا البرنامج التعليمي سنقوم بإعداد الأشياء يدويًا حتى تتمكن من رؤية كل جزء. في الدليل الجذر لمجلد مشروعك، قم بإنشاء ملف يسمى hardhat.config.js بالمحتويات التالية:

import { defineConfig } from "hardhat/config"

export default defineConfig({
  solidity: "0.8.34",
})

هذا هو المكان الذي سنحدد فيه كل الإعدادات لمشروعنا (في الخطوة 13). في الوقت الحالي، يخبر Hardhat فقط بإصدار مترجم Solidity الذي يجب استخدامه.

الخطوة 9: إضافة مجلدات المشروع

للحفاظ على تنظيم مشروعنا، سنقوم بإنشاء مجلدين جديدين. انتقل إلى الدليل الجذر لمشروعك في سطر الأوامر واكتب:

mkdir contracts
mkdir scripts

contracts/ هو المكان الذي سنحتفظ فيه بملف كود العقد الذكي hello world الخاص بنا
scripts/ هو المكان الذي سنحتفظ فيه بالبرامج النصية لنشر عقدنا والتفاعل معه

الخطوة 10: كتابة عقدنا

قد تسأل نفسك، متى بحق الجحيم سنكتب الكود؟؟ حسنًا، ها نحن ذا، في الخطوة 10.

افتح مشروع hello-world في محرر النصوص المفضل لديك (نحن نفضل VSCode (يفتح في علامة تبويب جديدة)). تُكتب العقود الذكية بلغة تسمى Solidity وهي ما سنستخدمه لكتابة العقد الذكي HelloWorld.sol الخاص بنا.‌

انتقل إلى مجلد "contracts" وقم بإنشاء ملف جديد يسمى HelloWorld.sol
يوجد أدناه نموذج لعقد ذكي Hello World من مؤسسة إيثيريوم سنستخدمه في هذا البرنامج التعليمي. انسخ والصق المحتويات أدناه في ملف HelloWorld.sol الخاص بك، وتأكد من قراءة التعليقات لفهم ما يفعله هذا العقد:

// SPDX-License-Identifier: MIT
// يحدد إصدار Solidity، باستخدام تحديد الإصدار الدلالي.
// لمعرفة المزيد: https://docs.soliditylang.org/en/latest/layout-of-source-files.html#pragma
pragma solidity ^0.8.24;

// يحدد عقداً باسم `HelloWorld`.
// العقد هو مجموعة من الدوال والبيانات (حالته). بمجرد نشره، يتواجد العقد في عنوان محدد على سلسلة الكتل لإيثيريوم. لمعرفة المزيد: https://docs.soliditylang.org/en/latest/structure-of-a-contract.html
contract HelloWorld {

   // يعلن عن متغير حالة `message` من النوع `string`.
   // متغيرات الحالة هي متغيرات يتم تخزين قيمها بشكل دائم في مساحة تخزين العقد. الكلمة المفتاحية `public` تجعل المتغيرات قابلة للوصول من خارج العقد وتنشئ دالة يمكن للعقود أو العملاء الآخرين استدعاؤها للوصول إلى القيمة.
   string public message;

   // على غرار العديد من اللغات كائنية التوجه القائمة على الفئات، فإن المُنشئ هو دالة خاصة يتم تنفيذها فقط عند إنشاء العقد.
   // تُستخدم المُنشئات لتهيئة بيانات العقد. لمعرفة المزيد: https://docs.soliditylang.org/en/latest/contracts.html#constructors
   constructor(string memory initMessage) {

      // يقبل وسيطة نصية `initMessage` ويعين القيمة في متغير التخزين `message` الخاص بالعقد).
      message = initMessage;
   }

   // دالة عامة تقبل وسيطة نصية وتحدث متغير التخزين `message`.
   function update(string memory newMessage) public {
      message = newMessage;
   }
}

هذا عقد ذكي بسيط للغاية يخزن رسالة عند الإنشاء ويمكن تحديثه عن طريق استدعاء دالة update.

الخطوة 11: ربط ميتاماسك وAlchemy بمشروعك

لقد أنشأنا محفظة ميتاماسك، وحساب Alchemy، وكتبنا عقدنا الذكي، والآن حان الوقت لربط الثلاثة.

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

لمعرفة المزيد حول إرسال المعاملات، تحقق من وثائق المعاملات.

قم بإنشاء ملف .env في الدليل الجذر لمشروعنا، وأضف إليه مفتاحك الخاص في ميتاماسك وعنوان URL الخاص بـ HTTP Alchemy API.

اتبع هذه الإرشادات (يفتح في علامة تبويب جديدة) لتصدير مفتاحك الخاص
انظر أدناه للحصول على عنوان URL الخاص بـ HTTP Alchemy API

انسخ عنوان URL الخاص بـ Alchemy API

يجب أن يبدو ملف .env الخاص بك هكذا:

API_URL="https://eth-sepolia.g.alchemy.com/v2/your-api-key"
PRIVATE_KEY="your-metamask-private-key"

لربط هذه المتغيرات فعليًا بالكود الخاص بنا، سنشير إليها في ملف hardhat.config.js الخاص بنا في الخطوة 13. يمكن لـ Node.js قراءة ملفات .env بمفرده، لذلك لا توجد حزمة إضافية لتثبيتها.

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

الخطوة 12: تثبيت Ethers.js

Ethers.js هي مكتبة تسهل التفاعل وتقديم الطلبات إلى إيثيريوم عن طريق تغليف طرق JSON-RPC القياسية بطرق أكثر سهولة في الاستخدام.

يجعل Hardhat من السهل جدًا دمج المكونات الإضافية (Plugins) (يفتح في علامة تبويب جديدة) للحصول على أدوات إضافية ووظائف موسعة. سنستفيد من المكون الإضافي Ethers (يفتح في علامة تبويب جديدة) لنشر العقد (يحتوي Ethers.js (يفتح في علامة تبويب جديدة) على بعض طرق نشر العقود النظيفة للغاية).

في دليل مشروعك اكتب:

npm install --save-dev @nomicfoundation/hardhat-ethers ethers

سنضيف أيضًا المكون الإضافي إلى hardhat.config.js الخاص بنا في الخطوة التالية.

الخطوة 13: تحديث hardhat.config.js

لقد أضفنا العديد من التبعيات والمكونات الإضافية حتى الآن، والآن نحتاج إلى تحديث hardhat.config.js حتى يعرف مشروعنا عنها جميعًا.

قم بتحديث hardhat.config.js الخاص بك ليبدو هكذا:

import { existsSync } from "node:fs"
import hardhatEthers from "@nomicfoundation/hardhat-ethers"
import { configVariable, defineConfig } from "hardhat/config"

// تحميل API_URL و PRIVATE_KEY من ملف .env إلى process.env، إذا كان موجوداً
if (existsSync(".env")) process.loadEnvFile()

export default defineConfig({
  plugins: [hardhatEthers],
  solidity: "0.8.34",
  networks: {
    sepolia: {
      type: "http",
      url: configVariable("API_URL"),
      accounts: [configVariable("PRIVATE_KEY")],
    },
  },
})

يخبر configVariable Hardhat بقراءة كل قيمة من متغير بيئة فقط عند الحاجة إليها، لذلك تعمل الأوامر مثل compile حتى قبل تعيين القيم. إذا كنت تفضل عدم الاحتفاظ بمفتاحك الخاص في ملف نصي عادي، فيمكن لـ Hardhat أيضًا قراءة متغيرات التكوين من مخزن المفاتيح المشفر (يفتح في علامة تبويب جديدة).

الخطوة 14: تجميع عقدنا

للتأكد من أن كل شيء يعمل حتى الآن، دعنا نجمع عقدنا. مهمة compile هي إحدى مهام Hardhat المدمجة.

من سطر الأوامر قم بتشغيل:

npx hardhat compile

في المرة الأولى التي تقوم فيها بالتجميع، يقوم Hardhat بتنزيل مترجم Solidity. يجب أن ترى بعد ذلك شيئًا مثل Compiled 1 Solidity file with solc 0.8.34. إذا لم يكن الأمر كذلك، يمكنك دائمًا إرسال رسالة في ديسكورد Alchemy (يفتح في علامة تبويب جديدة).

الخطوة 15: كتابة برنامج النشر النصي الخاص بنا

الآن بعد أن تمت كتابة عقدنا وأصبح ملف التكوين الخاص بنا جاهزًا، حان الوقت لكتابة البرنامج النصي لنشر العقد.

انتقل إلى مجلد scripts/ وقم بإنشاء ملف جديد يسمى deploy.js، مع إضافة المحتويات التالية إليه:

import { network } from "hardhat"

const { ethers } = await network.create()

const HelloWorld = await ethers.getContractFactory("HelloWorld")

// بدء النشر، وإرجاع وعد يحل إلى كائن عقد
const hello_world = await HelloWorld.deploy("Hello World!")
await hello_world.waitForDeployment()
console.log("Contract deployed to address:", await hello_world.getAddress())

دعنا نستعرض ما يفعله كل سطر من أسطر الكود هذه.

const { ethers } = await network.create()

في Hardhat 3، يفتح البرنامج النصي اتصالاً بشبكة بشكل صريح. يتصل network.create() بالشبكة التي تختارها باستخدام خيار --network عند تشغيل البرنامج النصي، ويضيف المكون الإضافي hardhat-ethers كائن ethers إلى هذا الاتصال.

const HelloWorld = await ethers.getContractFactory("HelloWorld")

ContractFactory في ethers.js هو تجريد يُستخدم لنشر عقود ذكية جديدة، لذا فإن HelloWorld هنا هو مصنع لمثيلات عقد hello world الخاص بنا. عند استخدام المكون الإضافي hardhat-ethers، يتم توصيل مثيلات ContractFactory وContract بالموقّع الأول افتراضيًا.

const hello_world = await HelloWorld.deploy("Hello World!")

سيؤدي استدعاء deploy() على ContractFactory إلى بدء النشر، وإرجاع Promise الذي يتم حله إلى Contract. هذا هو الكائن الذي يحتوي على طريقة لكل دالة من دوال العقد الذكي الخاص بنا. تذهب الوسائط التي تمررها إلى deploy() إلى مُنشئ العقد، وهنا الرسالة الأولية.

ينتظر waitForDeployment() حتى يتم تضمين معاملة النشر في كتلة، ويعيد getAddress() عنوان العقد الجديد. راجع وثائق عقد ethers.js (يفتح في علامة تبويب جديدة) لمزيد من التفاصيل.

الخطوة 16: نشر عقدنا

نحن مستعدون أخيرًا لنشر عقدنا الذكي! انتقل إلى سطر الأوامر وقم بتشغيل:

npx hardhat run scripts/deploy.js --network sepolia

يجب أن ترى بعد ذلك شيئًا مثل:

Contract deployed to address: 0x6cd7d44516a20882cEa2DE9f205bF401c0d23570

إذا ذهبنا إلى Etherscan الخاص بـ Sepolia (يفتح في علامة تبويب جديدة) وبحثنا عن عنوان عقدنا، فيجب أن نتمكن من رؤية أنه قد تم نشره بنجاح. ستبدو المعاملة كالتالي:

يجب أن يتطابق عنوان From (من) مع عنوان حساب ميتاماسك الخاص بك وسيشير عنوان To (إلى) إلى "Contract Creation" (إنشاء عقد) ولكن إذا نقرنا على المعاملة فسنرى عنوان عقدنا في حقل To:

تهانينا! لقد قمت للتو بنشر عقد ذكي على سلسلة إيثيريوم 🎉

لفهم ما يحدث داخليًا، يمكنك إلقاء نظرة على الطلبات التي تلقاها تطبيق "Hello World" الخاص بك في لوحة تحكم Alchemy (يفتح في علامة تبويب جديدة).

هناك سترى مجموعة من استدعاءات JSON-RPC التي أجراها Hardhat/Ethers داخليًا نيابة عنا عندما استدعينا دالة .deploy(). هناك استدعاءان مهمان يجب الإشارة إليهما هنا وهما eth_sendRawTransaction، وهو طلب كتابة عقدنا فعليًا على سلسلة Sepolia، وeth_getTransactionByHash وهو طلب لقراءة معلومات حول معاملتنا بناءً على التجزئة (نمط نموذجي عند إرسال المعاملات). لمعرفة المزيد حول إرسال المعاملات، تحقق من وثائق المعاملات.

هذا كل شيء في هذا البرنامج التعليمي. بعد ذلك، يمكنك بناء واجهة مستخدم لعقدك.