Веб-інтерфейс мінтингу NFT: смарт-контракти, Merkle Tree

Веб-інтерфейс мінтингу: від контракту до транзакції

Зазначимо: коли користувач натискає кнопку Mint, фронтенд зв'язується з контрактом через гаманець. Помилки на кшталт InsufficientFunds або InvalidMerkleProof лякають користувачів, а газові війни на піку вимагають швидкого зворотного зв'язку. Без правильної обробки транзакція може згоріти, обійшовшись користувачеві в $0.5 даремного газу. Ми будуємо інтерфейс, який передбачуваний: коннект гаманця, перевірка умов (whitelist, ліміти, статус продажу), відправка транзакції з декодуванням помилок і фінальний екран з токеном. Клієнти часто стикаються з неправильною перевіркою whitelist-статусу або невірною ціною газу. Наше рішення автоматично підбирає оптимальний gas price через viem і перевіряє всі умови перед відправкою. Наша команда має багаторічний досвід у блокчейн-розробці — ми реалізували десятки NFT-проєктів з інтеграцією смарт-контрактів на Ethereum та EVM-сумісних мережах. Гарантуємо чистий код на TypeScript з використанням актуальних бібліотек wagmi та viem.

Підготовка смарт-контракту

Перший крок — вивчити ABI. Типовий контракт використовує стандарт ERC-721A для ефективного batch-мінту. Обов'язкові функції: mint, whitelistMint, totalSupply, maxSupply, mintPrice, maxPerWallet, saleState та numberMinted. Приклад ABI з viem — читайте стан контракту через multicall для одночасного отримання всіх даних:

// Типові функції мінт-контракту
function mint(uint256 quantity) external payable;
function whitelistMint(uint256 quantity, bytes32[] calldata proof) external payable;
function totalSupply() external view returns (uint256);
function maxSupply() external view returns (uint256);
function mintPrice() external view returns (uint256);
function maxPerWallet() external view returns (uint256);
function saleState() external view returns (uint8); // 0=paused, 1=whitelist, 2=public
function numberMinted(address owner) external view returns (uint256);

Для читання стану використовуємо multicall — він дозволяє за один RPC-запит отримати totalSupply, maxSupply, mintPrice, maxPerWallet, saleState та numberMinted для гаманця. Це знижує навантаження на провайдер і прискорює UI.

Чому Merkle Tree — стандарт для whitelist?

Зберігання всіх whitelist-адрес у контракті коштує газу при розгортанні. Merkle tree вирішує цю проблему: в контракті зберігається лише корінь, а proof генерується на фронтенді за адресою користувача. Це в 10 разів дешевше по газу. Реалізація на TypeScript з бібліотекою merkletreejs:

// lib/merkle.ts
import { MerkleTree } from 'merkletreejs';
import { keccak256, encodePacked } from 'viem';
// allowlist.json — масив адрес з CMS або API
import allowlist from '@/data/allowlist.json';

function hashLeaf(address: string): `0x${string}` {
  return keccak256(encodePacked(['address'], [address as `0x${string}`]));
}

const leaves = allowlist.map(hashLeaf);
const tree = new MerkleTree(leaves, keccak256, { sortPairs: true });

export function getMerkleProof(address: string): `0x${string}`[] {
  const leaf = hashLeaf(address);
  return tree.getHexProof(leaf) as `0x${string}`[];
}

export function isWhitelisted(address: string): boolean {
  const leaf = hashLeaf(address);
  return tree.verify(tree.getHexProof(leaf), leaf, tree.getRoot());
}

Економія на розгортанні становить 0.09 ETH — вагомий аргумент для Merkle Tree. При середньому газі 20 Gwei це близько $500 економії на одному розгортанні. Крім того, кожна whitelist-перевірка стає дешевшою, що особливо помітно при великій кількості користувачів.

Які кроки з інтеграції інтерфейсу?

1. Проаналізуйте ABI контракту: виділіть всі функції та події, необхідні для мінту.
2. Спроектуйте структуру React-компонентів: MintWidget, StatusBar, ErrorDisplay, TransactionProgress.
3. Реалізуйте хуки для читання стану за допомогою useReadContract та useReadContracts з wagmi.
4. Додайте логіку відправки транзакцій через useWriteContract та відстежуйте статус через useWaitForTransactionReceipt.
5. Інтегруйте Merkle Tree: згенеруйте proof на фронтенді та передайте в контракт.
6. Протестуйте на тестнеті, симулюйте всі помилки, задеплойте на продакшн.

Ці кроки покривають повний цикл розробки. На кожному етапі ми проводимо код-рев'ю та перевіряємо відповідність best practices.

Як обробляти помилки мінтингу?

Мінтинг падає з багатьох причин: недостатньо ETH, перевищено ліміт гаманця, продаж не активна, невірний proof. Помилки з viem містять ABI-декодоване повідомлення контракту:

import { ContractFunctionRevertedError, UserRejectedRequestError } from 'viem';

function parseMintError(error: Error): string {
  if (error instanceof UserRejectedRequestError) {
    return 'Транзакцію відхилено в гаманці';
  }
  if (error instanceof ContractFunctionRevertedError) {
    const reason = error.data?.errorName ?? error.message;
    const messages: Record<string, string> = {
      'ExceedsMaxPerWallet': 'Перевищено ліміт токенів на гаманець',
      'SaleNotActive': 'Продаж ще не розпочався',
      'InvalidMerkleProof': 'Ваша адреса не в вайтлісті',
      'InsufficientFunds': 'Недостатньо ETH',
      'MaxSupplyReached': 'Всі токени замінчено',
    };
    return messages[reason] ?? `Помилка контракту: ${reason}`;
  }
  return 'Невідома помилка';
}

Тестування та безпека

Перед запуском ми проводимо симуляцію всіх станів контракту за допомогою Hardhat fork. Тестуємо граничні випадки: коли maxSupply досягнуто, коли гаманець не має ETH, коли proof невірний. Використовуємо принципи checks-effects-interactions для запобігання reentrancy атакам. Додатково налаштовуємо моніторинг через Etherscan API для відстеження успішних та невдалих транзакцій. Це гарантує, що користувач ніколи не побачить незрозумілу помилку, а газ не буде витрачено даремно.

Процес роботи та що входить

В роботу входить повний код на TypeScript, документація щодо підключення, інструкція з розгортання, гарантія на код протягом місяця. Ми також надаємо навчання вашій команді роботі з кодом та підтримку протягом тижня після запуску.

Терміни: базова версія з публічним мінтингом та прогрес-баром — 2–3 дні. Повна реалізація з whitelist, Merkle Tree та деплоєм — 4–6 днів.

Замовте розробку інтерфейсу мінтингу — зв'яжіться з нами для оцінки вашого проєкту. Отримайте консультацію та точний кошторис.