Разработка whitelist/allowlist для минтинга NFT
Типичная ситуация: коллекция на 10,000 NFT, whitelist-минт для 3,000 адресов за 12 часов до публичного. Если хранить whitelist on-chain как mapping(address => bool) — деплой контракта с записью 3,000 адресов обходится примерно в 15-20M gas только на SSTORE. При 20 gwei это $300-400 только на whitelist. Merkle proof решает это за 50k gas на весь список независимо от размера.
Merkle proof: как работает и где ошибаются
Merkle tree строится off-chain: каждый адрес хэшируется через keccak256(abi.encodePacked(address)), из листьев строится дерево попарным хэшированием. Результат — 32-байтный merkleRoot. Этот root деплоится в контракт. При минте пользователь передаёт proof[] — массив хэшей-братьев по пути от его листа до корня. Контракт верифицирует через MerkleProof.verify() из OpenZeppelin.
Распространённая ошибка — двойной минт. Если в контракте нет mapping(address => bool) public hasMinted (или mapping(address => uint256) public mintedCount), пользователь из whitelist может минтить неограниченное количество раз. Proof остаётся валидным. Контракт не знает, что адрес уже минтил.
Вторая ошибка — leaf encoding. OpenZeppelin MerkleProof ожидает, что лист — это keccak256(keccak256(data)) (double hash) для защиты от preimage attacks в случае если узлы дерева совпадают с листьями. Если генерируешь дерево через merkletreejs с одинарным hash, а контракт использует _leaf = keccak256(abi.encodePacked(account)) без double hash — может сработать collision attack при определённых конфигурациях. Используем keccak256(bytes.concat(keccak256(abi.encode(addr)))) или стандартную связку @openzeppelin/merkle-tree JS библиотека + MerkleProof.sol.
Варианты реализации
Merkle proof (основной)
Подходит для: списков от 100 до миллиона адресов. Стоимость деплоя не зависит от размера списка. Proof передаётся пользователем при минте (frontend генерирует автоматически).
Ограничение: нельзя добавить адрес после деплоя без пересборки дерева и обновления root. Если контракт upgradeable или owner может вызвать setMerkleRoot(bytes32) — это решается. Если immutable — нет.
Подпись backend (ECDSA)
Owner контракта держит приватный ключ. Для каждого whitelist-адреса backend подписывает keccak256(abi.encodePacked(address, nonce)). Контракт проверяет подпись через ECDSA.recover() и сверяет с signer address.
Преимущество: динамическое управление — можно добавлять адреса без изменения контракта, можно выдавать приоритеты, разные квоты. Недостаток: централизованный signer — single point of failure и trust. Если ключ утечёт — любой может заминтить.
Применение: gaming mint (backend знает achievement пользователя), динамические кампании.
On-chain mapping
Только для очень маленьких списков (<100 адресов) или когда список известен заранее и не изменится. addToWhitelist(address[]) с onlyOwner модификатором. 20,000 gas на адрес.
Дополнительная механика
Multi-tier whitelist — разные квоты для разных уровней. Merkle дерево содержит листья keccak256(abi.encode(address, maxMintAmount)). Пользователь передаёт proof + свой maxMintAmount, контракт верифицирует оба параметра вместе.
Temporal phases — WL → Allowlist → Public. Контракт держит enum SalePhase { PAUSED, WHITELIST, ALLOWLIST, PUBLIC }. Разные root'ы для каждой фазы, разные цены. owner меняет фазу через setPhase().
Batch mint с WL — пользователь может минтить N NFT за одну транзакцию, если его квота позволяет. mintedCount[msg.sender] += amount вместо bool флага.
Процесс работы
Реализация (1-2 дня). Контракт с Merkle verify + hasMinted mapping + phase management. Тесты в Foundry с edge cases: повторный минт, невалидный proof, исчерпанная квота.
Frontend интеграция (1 день). Генерация proof через @openzeppelin/merkle-tree, wagmi hook useMint().
Деплой. Foundry script с автоматической верификацией Etherscan.
Ориентиры по срокам
Whitelist контракт с Merkle proof — 2-3 дня включая тесты и frontend интеграцию.
Стоимость рассчитывается индивидуально.