Смарт-контракт Hello World для початківців

solidity

hardhat

alchemy

смарт-контракти

розгортання

Для початківців

elanh

31 березня 2021 р.

11 хвилин на читання

Якщо ви новачок у розробці на блокчейні й не знаєте, з чого почати, або якщо ви просто хочете зрозуміти, як розгортати смарт-контракти та взаємодіяти з ними, цей посібник для вас. Ми пройдемо через створення та розгортання простого смарт-контракту в тестовій мережі Sepolia за допомогою віртуального гаманця МетаМаск (відкривається в новій вкладці), Solidity (відкривається в новій вкладці), Hardhat (відкривається в новій вкладці) та Alchemy (відкривається в новій вкладці) (не хвилюйтеся, якщо ви ще не розумієте, що все це означає, ми все пояснимо).

Після розгортання вашого контракту ви можете створити для нього інтерфейс користувача.

Якщо у вас виникнуть запитання на будь-якому етапі, не соромтеся звертатися до Discord 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 ETH, ви можете перейти до деталей мережі Sepolia, щоб переглянути список різних кранів. Якщо один не працює, спробуйте інший, оскільки іноді вони можуть вичерпуватися. Деякі крани мають правила щодо відповідності вимогам; наприклад, кран Sepolia від Alchemy вимагає, щоб на адресі отримувача було щонайменше 0.001 ETH у головній мережі Ethereum. Отримання тестового ETH може зайняти деякий час через завантаженість мережі. Незабаром ви побачите ETH у своєму акаунті МетаМаск!

Крок 5: Перевірка балансу

Щоб переконатися, що наш баланс поповнено, давайте зробимо запит eth_getBalance за допомогою інструмента composer від 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 — це середовище розробки для компіляції, розгортання, тестування та налагодження вашого програмного забезпечення для Етеріум. Воно допомагає розробникам створювати смарт-контракти та децентралізовані застосунки (dapp) локально перед розгортанням у робочому ланцюзі.

Hardhat 3 вимагає Node.js версії 22.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 від Фундації Ethereum, який ми будемо використовувати для цього посібника. Скопіюйте та вставте наведений нижче вміст у ваш файл 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 API Alchemy.

Дотримуйтесь цих інструкцій (відкривається в новій вкладці), щоб експортувати свій приватний ключ
Дивіться нижче, щоб отримати URL-адресу HTTP API Alchemy

Скопіюйте URL-адресу API Alchemy

Ваш .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, тому не потрібно встановлювати додаткові пакети.

Не робіть коміт файлу .env! Будь ласка, ніколи не діліться та не розкривайте свій файл .env нікому, оскільки цим ви ставите під загрозу свої секрети. Якщо ви використовуєте контроль версій, додайте свій .env до файлу gitignore.

Крок 12: Встановлення Ethers.js

Ethers.js — це бібліотека, яка полегшує взаємодію та виконання запитів до Етеріум, обгортаючи стандартні методи JSON-RPC більш зручними для користувача методами.

Hardhat робить надзвичайно простим інтеграцію плагінів (відкривається в новій вкладці) для додаткових інструментів і розширеної функціональності. Ми скористаємося плагіном 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. Якщо ні, ви завжди можете написати в Discord 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, який є запитом на читання інформації про нашу транзакцію за заданим хешем (типовий патерн під час надсилання транзакцій). Щоб дізнатися більше про надсилання транзакцій, перегляньте документацію про транзакції.

На цьому цей посібник завершено. Далі ви можете створити інтерфейс користувача для вашого контракту.