Airdrop

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 the external limit (see more in limits).

Scalable airdrop architecture

A scalable airdrop consists of two independent modules:

1. Double-claim prevention - ensures each user can claim only once
2. Eligibility verification - proves the user is entitled to claim a specific drop

These modules are independent and can be combined in different ways.

Double-claim prevention

Markers

Each user has a small marker contract at a deterministic address derived from their address.

How it works:

1. User sends a message that deploys their marker contract.
2. Marker contract checks it has not been deployed before.
3. If already deployed, the claim is rejected (user already claimed).
4. If not deployed, the marker is created and the claim proceeds.

Eligibility verification

This module proves which users can claim and how much. Two approaches exist.

Merkle proof

The airdrop contract stores a root hash of a dictionary (see hashmap) containing all allocations. Users present a Merkle proof to verify their allocation against this root.

On-chain state:

• Root hash (256 bits)

How to prepare:

1. Prepare a list of eligible recipients and their allocations, and construct a dictionary.
2. Store the root hash in the airdrop contract.
3. Provide each user with their Merkle proof.

Signed proof

The airdrop contract stores a backend public key. The backend signs authorization messages for eligible users. Users present the signature to claim.

On-chain state:

• Backend public key (256 bits)

How to prepare:

1. Deploy airdrop contract with backend public key.
2. Backend validates eligibility criteria on demand (database, external API, business logic).
3. Backend signs authorization messages for eligible users.

For signature implementation details and security considerations, see signing messages.

Claim flow

The claim process combines both modules.

1. User sends a message that deploys their marker contract along with Merkle proof.
2. Marker contract checks it has not been deployed before (double-claim prevention).
3. Airdrop contract verifies proof (eligibility verification).
4. Airdrop contract transfers assets to recipient.

Choosing an approach

Merkle proof fits when:

• Trustless, verifiable distribution is required.
• Eligibility list is static or changes infrequently.
• Backend control over claims is not desired.

Signed authorization fits when:

• Eligibility rules change frequently or depend on external data.
• Trust in the backend is acceptable (centralized projects, known organizations).
• Lower gas costs per claim are a priority.

Examples

• cNFT
• Mintless Jetton