The problem: distributing at scale
You want to reward thousands (or millions) of users. Sending assets to each address proactively looks simple-until you see the bill. Network fees add up fast when the sender pays for every transfer.The twist: let users claim
An airdrop flips the model. Instead of the distributor paying all fees, each eligible user claims their allocation and covers the network fees themselves. The straightforward approach is to keep a precomputed mapping of recipient → allocation in the contract. When a user sends a claim message, the contract releases the preassigned drop for that user.
The naive approach-and its limit
Keep a precomputed mapping of recipient → allocation in the contract. When a user sends a claim message, the contract releases the preassigned amount. This works-until the list becomes too large, starting at roughly 3,000 entries, problems begin to surface with external limit (see more in limits).The scalable design: shard and prove
To scale, we split state across many contracts (contract sharding) and keep only a compact commitment to the list on-chain: a root hash of a dictionary (see hashmap). Users then present a Merkle proof to claim. We must also prevent double-claims. The airdrop have a small per-user marker contract that records whether the user has already claimed. This marker blocks any subsequent attempts.Why not simply update the Merkle root with each claim?With many users, several claims are likely to arrive concurrently. After the first update, all other in-flight proofs become stale, causing many transactions to fail.
How to prepare
- Prepare a list of eligible recipients and their allocations, and construct a dictionary.
- Store the root hash in the airdrop contract.
- Provide each user with their Merkle proof (or enable self-service proof retrieval).
Claim flow
- The user sends a message that deploys their per-user marker contract along with their Merkle proof.
- If valid, the marker records that the claim has been made and rejects further requests.
- The airdrop contract verifies the Merkle proof and transfers the asset to the address specified in the proof.
