Розробка Merkle Distributor для масових виплат токенів

Розробка Merkle Distributor для масових виплат

Ми регулярно вирішуємо задачу масових виплат токенів — airdrop на 50 000+ адрес. Наївне рішення — зберігати mapping(address => uint256) on-chain і ітеруватися по ньому в скрипті деплою. Деплой такого маппінгу коштує ~50 SLOAD + 50 SSTORE на кожного отримувача, разом при 50K отримувачах — кілька ETH тільки на запис даних у storage. Наприклад, при ціні ETH $2000 це близько $5000. Merkle Tree вирішує це принципово інакше: економія газу на деплой сягає 95% порівняно з прямим storage, що дає економію до $4750 при тому ж airdrop. Кожен claim обходиться у фіксовану суму — приблизно $5 (при низькій ціні газу). Це в 4 рази дешевше, ніж прямі перекази.

Як працює Merkle Distributor?

У контракт деплоїться лише один bytes32 merkleRoot — корінь дерева. Вся таблиця виплат (адреса → сума) залишається off-chain. Отримувач сам приходить за своїми токенами з merkleProof — набором хешів, що доводять його включення в дерево.

On-chain верифікація:

function claim(
    uint256 index,
    address account,
    uint256 amount,
    bytes32[] calldata merkleProof
) external {
    require(!isClaimed(index), "Already claimed");

    bytes32 node = keccak256(abi.encodePacked(index, account, amount));
    require(MerkleProof.verify(merkleProof, merkleRoot, node), "Invalid proof");

    _setClaimed(index);
    require(IERC20(token).transfer(account, amount), "Transfer failed");

    emit Claimed(index, account, amount);
}

isClaimed(index) перевіряє один біт у mapping(uint256 => uint256) — packed bitmask. 50 000 отримувачів = ~1563 uint256 слотів замість 50 000. Економія на storage — в 32 рази.

Чому цей розподільник — стандарт для airdrop?

Порівняємо витрати на деплой для 50 000 отримувачів:

Економія понад 95% (в 31 раз). Для одиничного claim:

При 50 000 claims економія складе десятки ETH.

Як побудувати Merkle Tree: покрокове керівництво

Підготуйте список отримувачів з індексами, адресами та сумами. Сформуйте листя: leaf = keccak256(abi.encodePacked(index, address, amount)) — подвійне хешування захищає від second preimage attack. Побудуйте дерево: використовуйте бібліотеку @openzeppelin/merkle-tree (JS/TS) або rs_merkle (Rust). Кожен internal node = keccak256(abi.encodePacked(left, right)) з canonical ordering (менший хеш зліва). Отримайте корінь: tree.root — єдине значення, що зберігається в контракті. Згенеруйте proofs: для кожного отримувача за допомогою tree.getProof(...). Роздайте proofs через API або опублікуйте в IPFS.

Типовий скрипт:

import { StandardMerkleTree } from "@openzeppelin/merkle-tree";

const values = recipients.map(([address, amount], index) => [
    index, address, amount
]);
const tree = StandardMerkleTree.of(values, ["uint256", "address", "uint256"]);
console.log("Root:", tree.root);

// proof для конкретного отримувача
const proof = tree.getProof([index, address, amount]);

Типові помилки при реалізації

Найпоширеніша помилка — некоректна бітова маска для захисту від double spend. Якщо _setClaimed встановлює біт неправильно, можливий повторний claim. Використовуйте перевірений патерн з OpenZeppelin. Друга проблема — колізія листя: якщо листя формуються без index (keccak256(abi.encodePacked(address, amount))), то два отримувачі з однаковою сумою можуть довести claim один на одного. Додавання index гарантує унікальність. Третя помилка — невідповідність кодування: abi.encodePacked в off-chain та в Solidity повинні співпадати.

Розширені патерни

Багатораундовий distributor: новий merkleRoot кожен тиждень/епоху. Замість деплою нового контракту — оновлюваний root через updateMerkleRoot(bytes32) з onlyOwner або governance. Claimed bitmask скидається для нової епохи або індексується по епосі: mapping(uint256 epoch => mapping(uint256 wordIndex => uint256 bitmask)).

Delegated claiming: отримувач підписує дозвіл на claim від свого імені — для gasless UX через релеєр або ERC-2771 meta-transactions. Патерн: claimFor(address account, uint256 amount, bytes32[] calldata proof, bytes calldata signature).

Тестування на Foundry

function test_ClaimValidProof() public {
    bytes32[] memory leaves = new bytes32[](3);
    leaves[0] = keccak256(abi.encodePacked(uint256(0), alice, uint256(100e18)));
    distributor.claim(0, alice, 100e18, proof);
    assertEq(token.balanceOf(alice), 100e18);
    vm.expectRevert("Already claimed");
    distributor.claim(0, alice, 100e18, proof);
}

Для генерації proofs у Foundry тестах: vm.ffi з викликом TypeScript скрипту через @openzeppelin/merkle-tree. Або пишіть чисту Solidity-реалізацію в setUp().

Що входить до нашої розробки

Ми на ринку понад 5 років, реалізували 20+ distributor-контрактів для airdrop, стейкінгу та масових виплат. У вартість входить:

• Вихідний код смарт-контракту на Solidity (протестований на Foundry, включає fuzz-тести).
• Off-chain скрипти: побудова дерева, генерація proofs, деплой та верифікація (TypeScript, ethers.js).
• Документація: опис архітектури, інструкція з розгортання, опис API.
• Доопрацювання під ваш токен: ERC-20, ERC-721, ERC-1155 або кросс-чейн за допомогою bridge.
• Підтримка після запуску: виправлення багів, консультації з інтеграції.

Терміни та вартість

Базовий Merkle Distributor з single root: 2-3 дні включаючи off-chain скрипти. Багатораундовий з governance та gasless claiming: 4-5 днів. Деплой та верифікація контракту на mainnet — додатково кілька годин. Вартість розраховується індивідуально після уточнення деталей. Зв'яжіться з нами для оцінки вашого проекту — проаналізуємо кількість отримувачів, вимоги до епох та UX. Замовте розробку Merkle Distributor і заощадьте тисячі доларів на газі. Отримайте консультацію прямо зараз.

Розробка смарт-контрактів

Ми зіткнулися з ситуацією: контракт задеплоєно, за два тижні приходить повідомлення — пул дреновано на значну суму. Дивимося транзакцію в Tenderly: атакуючий викликав deposit(), всередині callback на ERC-777 повторно викликав withdraw() — баланс оновився тільки після другого виходу. Класична reentrancy, але не через ETH transfer, а через хук ERC-777. ReentrancyGuard стояв тільки на withdraw().

Такі випадки — не рідкість. Смарт-контракт — це фінансова логіка без можливості пропатчити її вночі. Наша команда розробляє контракти під ключ, вбудовуючи захист від reentrancy, MEV та gas-атак на ранніх етапах. Reentrancy attack — одна з найпоширеніших вразливостей, що потребує глибокого розуміння EVM.

Як ми розробляємо смарт-контракти під ключ?

Починаємо з аудиту бізнес-логіки та вибору стеку. Solidity 0.8.x — стандарт для EVM-сумісних чейнів: Ethereum, Arbitrum, Optimism, Polygon, BSC, Avalanche C-Chain. Для Solana використовуємо Rust та Anchor: модель акаунтів і програм вимагає явного оголошення всіх ресурсів. Для проектів з формальною верифікацією підходить Move (Aptos, Sui) — лінійні типи мови виключають копіювання ресурсів на рівні компілятора. Vyper обираємо для контрактів, де критична простота аудиту (Curve Finance).

Gas optimization — не передчасна оптимізація, а архітектурне рішення. На Ethereum mainnet деплой погано спроектованого контракту може коштувати значну суму тільки через неоптимальний storage layout. Переупаковка структури Proposal з 7 слотів до 4 заощадила 18k gas на кожному голосуванні — економія на масштабі протоколу з тисячами голосувань на день дає відчутну річну вигоду.

Типові помилки в gas: передача масивів через memory замість calldata в external функціях (дорожче в 2-3 рази); використання require з довгими рядками замість custom error error InsufficientBalance(...). Кастомні помилки дешевші на 50-200 gas на revert і передають структуровані дані фронтенду.

Чому аудит смарт-контрактів критичний для безпеки?

Аудит — не разова перевірка, а вбудований етап розробки. Використовуємо три рівні:

1. Статичний аналіз — Slither (30 секунд в CI) виявляє reentrancy, неініціалізовані змінні, небезпечний delegatecall.
2. Фаззинг та invariant тести — Foundry з --fuzz-runs 50000 знаходить edge cases, які пропускають сотні unit-тестів. Echidna перевіряє інваріанти («сума всіх балансів ≤ totalSupply»).
3. Ручний code review — наші інженери з досвідом 10+ років у блокчейні виявляють логічні помилки, які не ловлять інструменти. Для протоколів з високим TVL обов'язковий зовнішній аудит з боку Trail of Bits, Consensys Diligence або OpenZeppelin. Термін — 2-4 тижні.

Будь-який апгрейдуємий протокол повинен мати timelock. TimelockController з OpenZeppelin: операція пропонується → чекає мінімальний delay (48-72 години) → виконується. Без timelock один скомпрометований deployer wallet = втрата всього пулу.

OpenZeppelin Security Audits підтверджують, що 80% вразливостей, знайдених у деплоїних контрактах, пов'язані з відсутністю перевірок доступу або reentrancy. Ми включаємо ці перевірки в CI ще до першого деплою.

Які патерни апгрейду обираємо?

Storage collision — головна небезпека проксі. Implementation v2 не повинен додавати змінні перед існуючими. OpenZeppelin Upgrades plugin для Hardhat та Foundry перевіряє це автоматично, але тільки при використанні його API.

Як захистити контракт від MEV та front-running?

На Ethereum mainnet транзакції в mempool видно всім. MEV-боти проводять sandwich-атаки на DEX, фронтраннінги мінтингу та governance. Рішення: commit-reveal scheme для аукціонів, приватна відправка через Flashbots PROTECT RPC. EIP-7702 та PBS (proposer-builder separation) змінюють картину, але поки не масово.

Процес розробки

1. Аналітика — специфікація функцій, діаграма викликів, аналіз edge cases. Без цього кодинг починається даремно.
2. Розробка — Solidity/Rust з тестами паралельно. Тест → код → рефакторинг. Використовуємо Foundry для fuzz та invariant тестів.
3. Внутрішній аудит — Slither + Echidna + ручний code review. Foundry invariant tests для протокольних інваріантів.
4. Зовнішній аудит — для проектів з реальними грошима. Термін: 2-4 тижні.
5. Деплой — Foundry scripts або Hardhat Ignition з verify на Etherscan. Gnosis Safe для ownership transfer одразу після деплою.
6. Моніторинг — Tenderly alerts, OpenZeppelin Defender, Forta Network.

Що входить в роботу

• Документація на архітектуру та специфікацію контракту (NatSpec).
• Вихідний код з репозиторієм та CI (Slither, Foundry, coverage).
• Розгорнута версія контракту з verify на блокчейн-експлорері.
• Результати аудиту (внутрішнього та зовнішнього за запитом).
• Доступи до моніторингу та управління (Gnosis Safe).
• Гарантія на код: фікси критичних багів протягом місяця після деплою.
• Консультація щодо інтеграції з веб-інтерфейсом (wagmi, RainbowKit).

Терміни орієнтовно

• ERC-20 token з базовими функціями: 1-2 тижні
• Vesting контракт з cliff/linear schedule: 2-3 тижні
• NFT ERC-721/1155 з маркетплейсом: 4-6 тижнів
• AMM або lending протокол: 2-4 місяці
• Мультичейн протокол з bridge: 4-7 місяців

Аудит додає 3-6 тижнів і йде паралельно з фінальним тестуванням де можливо. Вартість розраховується індивідуально — зв'яжіться з нами, і ми оцінимо ваш проект безкоштовно. Економія на газі завдяки нашій оптимізації може сягати 30% на рік для високонавантажених протоколів.

Зв'яжіться з нами для оцінки вашого проекту. Замовте розробку смарт-контракту — отримайте консультацію з архітектури та захисту від reentrancy, MEV та gas-атак. Напишіть нам — ми підберемо оптимальний стек під вашу задачу.