Every major EVM airdrop — from Uniswap's UNI to zkSync's ZK — uses a Merkle tree to decide who can claim. You've probably seen the phrase "Merkle proof" in error messages when a claim fails, or in protocol docs that assume you already know what it means. Most users don't, and that knowledge gap costs real money: failed claims, expired windows, invalid proofs submitted to the wrong contract state.
This guide explains the full mechanism from the ground up — how the tree is built, what happens inside the contract when you claim, why proofs fail, and how DropsHub reads on-chain roots directly to tell you whether your claim is executable right now.
Why Airdrops Use Merkle Trees
When a protocol distributes tokens to tens of thousands of wallets, it faces a hard engineering problem: how do you store the full eligibility list on-chain without spending hundreds of thousands of dollars in gas writing every address into contract storage?
The answer is a Merkle tree. Instead of storing the entire list, the contract stores a single 32-byte value — the Merkle root — that cryptographically commits to every address and amount in the distribution. A user proves their eligibility by submitting a Merkle proof: a small set of hashes that, when combined with their data, reconstructs the root. If the reconstructed root matches what's stored on-chain, the claim is valid.
The result is a claiming contract that costs roughly the same to deploy whether it covers 500 wallets or 5,000,000. Every major EVM distribution since Uniswap's 2020 UNI drop has used some variant of this pattern.
The Merkle root is the only eligibility data that ever lives on-chain. The full address list — with amounts and indices — is kept off-chain by the protocol and served via API or IPFS. If that off-chain data disappears, claims become impossible even for eligible wallets.
How the Tree Is Constructed
Step 1 — Building the Leaf Set
Each eligible wallet becomes a leaf in the tree. A leaf is a 32-byte hash of the wallet's claim data, typically encoded as:
keccak256(abi.encodePacked(
index, // uint256 — position in the list
account, // address — eligible wallet
amount // uint256 — claimable token amount (in wei)
))
Some protocols double-hash the leaf to prevent second-preimage attacks. The exact encoding is protocol-specific — a detail that matters when we get to why proofs fail.
Step 2 — Hashing Up the Tree
Leaves are paired and hashed together to form the next layer. Those results are paired and hashed again, continuing upward until a single hash remains. That final hash is the Merkle root.
[ ROOT ]
/ \
[ H(AB) ] [ H(CD) ]
/ \ / \
[ H(A) ] [ H(B) ] [ H(C) ] [ H(D) ]
| | | |
wallet1 wallet2 wallet3 wallet4
In a real distribution with 50,000 wallets, the tree has about 16 levels. A Merkle proof for any leaf is just the 16 sibling hashes needed to reconstruct the path from that leaf to the root — roughly 512 bytes of calldata, regardless of how large the full list is.
Step 3 — Publishing the Root
The deployer writes the Merkle root into the distributor contract's storage at deployment. From this point on, anyone holding a valid proof for a leaf in that tree can claim — without needing the protocol to take any further action on their behalf.
Pairs in the tree are typically sorted before hashing — the smaller hash always goes left — so proof generation is deterministic regardless of the order addresses appear in the input list. Naive proof implementations that skip this step will generate invalid proofs.
The On-Chain Claim Flow
When you hit "Claim" in a protocol's UI, your wallet submits a transaction calling something like claim(index, account, amount, proof[]) on the distributor contract. Here's what happens inside:
function verify(
bytes32[] memory proof,
bytes32 root,
bytes32 leaf
) internal pure returns (bool) {
bytes32 computedHash = leaf;
for (uint256 i = 0; i < proof.length; i++) {
bytes32 proofElement = proof[i];
if (computedHash <= proofElement) {
computedHash = keccak256(abi.encodePacked(computedHash, proofElement));
} else {
computedHash = keccak256(abi.encodePacked(proofElement, computedHash));
}
}
return computedHash == root;
}
- Double-claim check — the contract checks a bitfield to confirm this index has not already been claimed. Attempting to claim twice reverts before proof verification even begins
- Leaf reconstruction — the contract hashes your submitted index, account, and amount using the same encoding used to build the original tree
- Proof verification — the contract walks up your proof array, hashing each sibling pair, until it arrives at a reconstructed root
- Root comparison — if the reconstructed root equals the stored Merkle root, tokens are transferred. If not, the transaction reverts — gas consumed, nothing received
Why Claims Fail — 7 Common Reasons
Understanding the verification flow above makes it clear why claims fail even for wallets that are genuinely in the eligibility list.
claim() function reverts unconditionally regardless of proof validity. Unclaimed tokens are often swept back to the treasury. DropsHub flags approaching expiry windows in the scanner output.pause() due to a security incident or routine maintenance. All claim attempts revert until unpaused. This is temporary in most cases, but requires monitoring the protocol's status channels.Never generate or fetch a Merkle proof from unofficial third-party sources. A malicious proof supplier can hand you a proof that triggers unexpected contract calls or drains token approvals on interaction. Always use the protocol's official API or a read-only tool that decodes the root directly from on-chain state.
The Root Is On-Chain. The List Is Not.
This is the most misunderstood aspect of Merkle-based airdrops. The root stored in the contract is immutable and publicly readable. But the root alone tells you nothing — it's just a 32-byte hash. To know whether your address is in the tree, you need the full leaf set to reconstruct which addresses were included and what proofs correspond to them.
Most protocols publish this data via a JSON API or an IPFS CID referenced in the deployment transaction. If that data goes offline — which happens more often than you'd expect with smaller protocols — you cannot generate a valid proof even if your address was definitely included in the original distribution.
DropsHub maintains indexed copies of leaf data for all 247 tracked protocols. When you scan your wallet, the eligibility check isn't just comparing your address against a static database — it's reconstructing your Merkle proof against the live on-chain root to confirm the claim is still executable right now.
Most airdrop trackers check whether your address appears in a cached list. DropsHub verifies that your proof is currently valid against the live root state. If a protocol updates its Merkle root after a Sybil filtering round, DropsHub detects the change within minutes and re-validates your eligibility automatically.
Multi-Round Distributions and Root Updates
An increasingly common pattern is distributing tokens in multiple rounds, each with its own Merkle root. Optimism's OP token used this approach, and several Arbitrum ecosystem protocols have followed with rolling distributions that reward ongoing activity rather than a single historical snapshot.
In multi-root contracts, the distributor stores a mapping of round ID to Merkle root. Each claim call must specify which round it belongs to, and the proof must be valid against that round's root. Wallets eligible in round 1 but not round 2 have no valid proof for round 2's tree — attempting to submit one will fail verification.
This is why "I claimed before but there seems to be more to claim" can be legitimate — and why "I claimed but now it says nothing is available" almost always reflects a successful prior claim against a now-exhausted round. DropsHub's scanner shows per-round eligibility status and marks already-claimed indices so the state is unambiguous.
Merkle vs. Signature-Based Claims
A minority of protocols skip the Merkle tree in favour of per-address EIP-712 signatures issued by an off-chain signer. The mechanics look similar from a user perspective, but there are important differences in trust model and failure modes.
- Merkle claims are fully trustless — once the root is on-chain, no third party can block or modify who can claim. The protocol doesn't need to serve proofs; they can be reconstructed from public data
- Signature claims require a live signer — if the protocol's signing server goes down or is compromised, claims are blocked or become forgeable. This has happened in several documented incidents
- Signatures can be retroactively invalidated — a protocol can rotate the signer address and invalidate all previously issued signatures, effectively rescinding eligibility after the fact
- Merkle proofs are larger calldata — a signature is 65 bytes; a Merkle proof for a 50k-address tree is ~512 bytes. This creates a small but real gas difference per claim
For these reasons, the MerkleDistributor pattern (originally open-sourced by Uniswap) has become the dominant standard for large-scale EVM distributions. It's the pattern DropsHub is built to scan.
FAQ
What is a Merkle proof in an airdrop?
A Merkle proof is a small set of hashes that lets you prove your address and claimable amount are part of a distribution without storing the full list on-chain. You submit the proof with your claim transaction, and the contract uses it to reconstruct the Merkle root. If the result matches what's stored, the claim is valid and tokens are transferred.
Why does my airdrop claim keep failing?
The most common causes are: the proof was fetched from a stale API after the protocol updated its root, the amount in your cached data differs from the contract's record, the index has already been claimed, or the claim window has expired. Use DropsHub's terminal to verify your proof live against the on-chain root — it surfaces the exact failure reason rather than a generic revert.
Is the full eligibility list stored on-chain?
No. Only the 32-byte Merkle root is stored on-chain. The full list of eligible addresses and amounts is kept off-chain by the protocol, typically served via an API or IPFS. If that off-chain data disappears, valid proofs cannot be generated even for genuinely eligible wallets.
What is the difference between a Merkle airdrop and a signature-based airdrop?
In a Merkle airdrop, eligibility is committed on-chain via a root hash — no ongoing server is required and no one can retroactively block your claim. In a signature-based airdrop, a protocol server must sign each claim. If the server rotates its key or goes offline, previously issued signatures can be invalidated. Merkle distributions are more trustless and are now the dominant standard for large-scale EVM drops.