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

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

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

Как работает 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) проверяет один bit в mapping(uint256 => uint256) — packed bitmask. 50 000 получателей = ~1563 uint256 слотов вместо 50 000. Экономия на storage — в десятки раз.

Почему Merkle Distributor — стандарт для airdrop?

Сравним затраты на деплой для 50 000 получателей:

Экономия более 95%. Кроме того, off-chain таблица легко обновляется без передеплоя контракта. Для ещё большей наглядности — сравнение затрат на единичный claim:

При 50 000 claims экономия составит десятки ETH. Merkle Distributor лучше прямого storage в 32 раза по газу на деплой.

Как построить Merkle Tree: пошаговое руководство

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]); 

Какие ошибки допускают при реализации Merkle Distributor?

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

Расширенные паттерны

Многораундовый 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))); // merkle proof вычисляем вручную или через FFI к JS скрипту distributor.claim(0, alice, 100e18, proof); assertEq(token.balanceOf(alice), 100e18); vm.expectRevert("Already claimed"); distributor.claim(0, alice, 100e18, proof); // double claim } 

Для генерации 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, и мы поможем сэкономить тысячи долларов на газе. Получите консультацию прямо сейчас.