Airdrop Distribution Flow

Purpose: Step-by-step walkthrough of the Merkle proof claim workflow and how each airdrop strategy variant executes token distribution.

• Doc type: How-to

What you'll find here

• Happy path for the standard claim-based airdrop flow
• How each strategy variant (time-bound, vesting, push) modifies the base flow
• Claim tracking strategies and their gas/flexibility tradeoffs
• Failure modes and revert conditions at each step
• Sequence diagram of the end-to-end claim lifecycle

Related

• Airdrop -- contracts, roles, and configuration
• Signing Flow -- transaction signing and custody
• Compliance Transfer -- transfer validation for compliance-enabled tokens
• Asset Issuance -- how assets are created before distribution

---

Flow overview

The airdrop distribution flow moves tokens from a funded airdrop contract to eligible recipients. Eligibility is verified cryptographically using Merkle proofs -- no off-chain oracle is trusted at claim time. The flow applies to all three strategy types, with each variant adding constraints on timing, release schedule, or distribution model.

Happy path -- claim-based airdrop

1. Admin deploys airdrop -- the airdrop contract is deployed with a Merkle root encoding the full recipient list and allocations. Strategy-specific parameters (time window, vesting schedule) are set at deployment and are immutable.
2. Admin funds the contract -- tokens are transferred to the airdrop contract address. The contract must hold sufficient balance to cover all allocations.
3. Recipient submits claim -- an eligible recipient generates a Merkle proof off-chain and calls claim(proof, amount) on the airdrop contract.
4. Merkle proof verification -- the contract verifies the submitted proof against the stored root. Invalid proofs revert immediately.
5. Claim tracker check -- the contract queries the claim tracker to confirm the recipient has not exceeded their allocation.
6. Token transfer -- tokens move from the airdrop contract to the recipient address via ERC20 transfer.
7. Claim recorded -- the claim tracker updates state to prevent duplicate claims.

Strategy variants

Each strategy modifies the base flow with additional constraints:

Time-bound airdrop

• Claim window enforced -- the contract checks that block.timestamp falls between the configured start and end times. Claims outside this window revert.
• Post-expiration withdrawal -- after the end time, the contract owner can withdraw unclaimed tokens. Recipients can no longer claim.

Vesting airdrop

• Cliff period -- no tokens release until the cliff duration elapses from the vesting start time.
• Progressive release -- after the cliff, tokens unlock linearly over the vesting period. Recipients can claim their vested portion at any time.
• Multiple claims -- recipients call claim() repeatedly as more tokens vest. The amount tracker records cumulative claims against the total allocation.

Push airdrop

• Admin-initiated -- the administrator calls a batch distribution function, pushing tokens directly to recipient addresses. No Merkle proof or recipient action is required.
• No claim tracker -- distribution is controlled entirely by the admin. The Merkle root still validates recipient eligibility, but the claim lifecycle is inverted.

Claim tracking strategies

The claim tracker is selected at deployment and cannot be changed. Bitmap tracking is the default for time-bound and push strategies. Amount tracking is required for vesting airdrops.

Failure modes

• Invalid Merkle proof -- proof does not match the stored root. Transaction reverts with no state change.
• Already claimed (bitmap) -- recipient's bit is already set. Transaction reverts.
• Claim exceeds allocation (amount) -- cumulative claimed amount would exceed the Merkle-encoded allocation. Transaction reverts.
• Outside claim window (time-bound) -- block.timestamp is before start or after end. Transaction reverts.
• Before cliff (vesting) -- vesting cliff has not elapsed. No tokens are releasable; transaction reverts.
• Insufficient airdrop balance -- the contract does not hold enough tokens to fulfill the claim. ERC20 transfer reverts.

Related resources

• Airdrop -- contracts, roles, and configuration
• Signing Flow -- how transactions are signed and broadcast
• Compliance Transfer -- transfer validation when tokens carry compliance rules
• Asset Issuance -- how assets are created before airdrops
• Capabilities overview -- how capabilities extend the platform