Реалізація взаємодії з блокчейном через ethers.js/web3.js на сайті

Реалізація взаємодії з блокчейном через ethers.js/web3.js на веб-сайті

ethers.js v6 та web3.js v4 — дві зрілі бібліотеки для роботи з EVM-блокчейнами. ethers.js використовується частіше: менший розмір бандлу, краща типізація, чистіший API. web3.js зустрічається у legacy-проектах та там, де історично використовувався цей стек. Давайте розглянемо обидва варіанти.

ethers.js v6: ключові концепції

У ethers v6 змінилися імпорти та з'явилася підтримка ESM без CJS-fallback:

import {
  BrowserProvider,      // для window.ethereum (гаманець користувача)
  JsonRpcProvider,      // для серверного RPC-доступу
  Contract,             // для взаємодії з контрактами
  formatEther,          // BigInt → рядок у ETH
  parseEther,           // рядок у ETH → BigInt
  formatUnits,          // з урахуванням decimals
  parseUnits,
  isAddress,            // валідація адреси
  getAddress,           // нормалізація до checksum
} from 'ethers';

Постачальники

// Серверний постачальник (для SSR, API routes, cron)
const serverProvider = new JsonRpcProvider(process.env.ETH_RPC_URL);

// Клієнтський постачальник через гаманець користувача
async function getWalletProvider() {
  if (!window.ethereum) throw new Error('Wallet not found');
  const provider = new BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  return { provider, signer };
}

// Fallback: пробуємо кілька RPC
import { FallbackProvider } from 'ethers';

const fallbackProvider = new FallbackProvider([
  { provider: new JsonRpcProvider('https://rpc1.example.com'), priority: 1, weight: 2 },
  { provider: new JsonRpcProvider('https://rpc2.example.com'), priority: 2, weight: 1 },
]);

Робота з контрактами через ethers.js

const ERC20_ABI = [
  'function balanceOf(address owner) view returns (uint256)',
  'function transfer(address to, uint256 amount) returns (bool)',
  'function approve(address spender, uint256 amount) returns (bool)',
  'function allowance(address owner, address spender) view returns (uint256)',
  'event Transfer(address indexed from, address indexed to, uint256 value)',
];

// Read-only контракт (серверний постачальник)
const tokenRead = new Contract(TOKEN_ADDRESS, ERC20_ABI, serverProvider);

// Контракт з підписом (гаманець користувача)
const { signer } = await getWalletProvider();
const tokenWrite = new Contract(TOKEN_ADDRESS, ERC20_ABI, signer);

// Читання
const balance = await tokenRead.balanceOf(walletAddress);
console.log(formatUnits(balance, 18));

// Запис
const tx = await tokenWrite.transfer(recipientAddress, parseUnits('10', 18));
const receipt = await tx.wait(); // чекаємо підтвердження
console.log('Confirmed in block', receipt.blockNumber);

Підписка на события

// Слухаємо Transfer-события в реальному часі
tokenRead.on('Transfer', (from, to, value, event) => {
  console.log(`${from} → ${to}: ${formatUnits(value, 18)} токенів`);
  console.log('Block:', event.log.blockNumber);
});

// Фільтровані события — тільки входящі на адресу
const filter = tokenRead.filters.Transfer(null, walletAddress);
tokenRead.on(filter, (from, to, value) => {
  console.log(`Отримано ${formatUnits(value, 18)} від ${from}`);
});

// Відписка при unmount
return () => { tokenRead.removeAllListeners(); };

Історичні события

async function getTransferHistory(
  contractAddress: string,
  walletAddress: string,
  fromBlock: number,
) {
  const contract = new Contract(contractAddress, ERC20_ABI, serverProvider);
  const filter = contract.filters.Transfer(null, walletAddress);
  const events = await contract.queryFilter(filter, fromBlock, 'latest');

  return events.map(event => ({
    from: event.args[0],
    to: event.args[1],
    amount: formatUnits(event.args[2], 18),
    blockNumber: event.blockNumber,
    txHash: event.transactionHash,
  }));
}

web3.js v4: основні паттерни

web3.js v4 — повна переробка з нативною підтримкою TypeScript:

import { Web3 } from 'web3';

const web3 = new Web3(window.ethereum);

// Або з HTTP постачальником
const web3Server = new Web3(process.env.ETH_RPC_URL);

// Контракт через web3.js
const erc20Contract = new web3.eth.Contract(ERC20_ABI, TOKEN_ADDRESS);

// Читання
const balance = await erc20Contract.methods.balanceOf(walletAddress).call();
const formatted = web3.utils.fromWei(balance, 'ether');

// Запис
const accounts = await web3.eth.getAccounts();
const receipt = await erc20Contract.methods
  .transfer(recipient, web3.utils.toWei('10', 'ether'))
  .send({ from: accounts[0] });

Обробка BigInt в UI

ethers v6 повертає нативний BigInt, web3.js v4 теж. Проблема — JSON.stringify не серіалізує BigInt:

// Безпечна серіалізація для state/API
const replacer = (_: string, value: unknown) =>
  typeof value === 'bigint' ? value.toString() : value;

JSON.stringify(data, replacer);

// Або використовуйте SuperJSON для Prisma/tRPC стеку
import superjson from 'superjson';
superjson.stringify(data); // автоматично обробляє BigInt

Утиліти, які потрібні в кожному проекті

// Скорочення адреси для відображення
export function shortenAddress(address: string): string {
  return `${address.slice(0, 6)}…${address.slice(-4)}`;
}

// Перевірка та нормалізація адреси
export function safeGetAddress(input: string): string | null {
  try {
    return getAddress(input); // бросає якщо невалідна
  } catch {
    return null;
  }
}

// Конвертація timestamp блока в дату
export async function blockToDate(blockNumber: number): Promise<Date> {
  const block = await serverProvider.getBlock(blockNumber);
  return new Date(Number(block!.timestamp) * 1000);
}

Часова шкала: інтеграція читання даних з контракту та підписки на況況иця через ethers.js — 1–2 дні. Повноцінний шар взаємодії з кількома контрактами, обробкою помилок, fallback-постачальниками та історичними события — 3–4 дні.