# Airdrop distribution flow

Source: https://docs.settlemint.com/docs/architecture/flows/airdrop-distribution
How DALP moves tokens from a funded airdrop contract to eligible addresses, including
Merkle proof checks, claim tracking, strategy variants, and failure modes.




## System context [#system-context]

Airdrop distribution starts after an asset exists and the issuer funds an airdrop contract. DALP stores a Merkle root for the recipient allocation, verifies a submitted proof before each distribution, records claim state, and transfers tokens from the airdrop contract to eligible addresses.

<Mermaid
  chart="`
flowchart TD
  Configured[Issuer sets root and strategy]
  Funded[Tokens transferred to airdrop contract]
  ClaimOpen[Time-bound or vesting claim window opens]
  PushReady[Push batch is ready]
  ProofChecked[Proof and limits checked]
  Distributed[Tokens distributed]
  Rejected[Proof, timing, or amount rejected]
  Indexed[Token transfer emitted]

  Configured --> Funded
  Funded --> ClaimOpen
  Funded --> PushReady
  ClaimOpen --> ProofChecked
  PushReady --> ProofChecked
  ProofChecked --> Distributed
  ProofChecked --> Rejected
  Distributed --> Indexed
  Rejected --> ClaimOpen
  Rejected --> PushReady

`"
/>

Identity, claim topics, and trusted issuers are defined in the [claims and identity model](/docs/architecture/concepts/claims-and-identity). Per-asset compliance checks are defined in [asset policy](/docs/architecture/concepts/asset-policy).

## Related [#related]

* [Airdrop](/docs/architecture/components/capabilities/airdrop), contracts, roles, and configuration
* [Signing flow](/docs/architecture/flows/signing-flow), transaction signing and custody
* [Compliance transfer](/docs/architecture/flows/compliance-transfer), transfer validation for compliance-enabled tokens
* [Asset issuance](/docs/architecture/flows/asset-issuance), how assets are created before distribution

***

## Flow overview [#flow-overview]

The airdrop distribution flow moves tokens from a funded airdrop contract to eligible recipients. Eligibility is verified with Merkle proofs against the stored root, so the contract does not trust an off-chain oracle at claim time. The flow applies to time-bound, vesting, and push strategies. Each strategy adds a different timing, release, or distribution constraint.

## Claim-based happy path [#claim-based-happy-path]

<Mermaid
  chart="`
sequenceDiagram
  participant Admin
  participant AirdropContract as Airdrop Contract
  participant ClaimTracker as Claim Tracker
  participant Token as Token Contract
  participant Recipient

  Admin->>AirdropContract: 1. Deploy with Merkle root + config
  Admin->>AirdropContract: 2. Fund with tokens
  Recipient->>AirdropContract: 3. claim(proof, amount)
  AirdropContract->>AirdropContract: 4. Verify Merkle proof against root
  AirdropContract->>ClaimTracker: 5. Check claim status
  ClaimTracker-->>AirdropContract: Not yet claimed / within allocation
  AirdropContract->>Token: 6. Transfer tokens to recipient
  Token-->>Recipient: Tokens received
  AirdropContract->>ClaimTracker: 7. Record claim

`"
/>

1. The admin deploys the airdrop contract with a Merkle root for the recipient list and allocations. Strategy-specific parameters, such as time windows or vesting schedules, are set at deployment.
2. The admin funds the contract address with enough tokens to cover the intended allocation.
3. The recipient generates a Merkle proof off-chain and calls `claim(proof, amount)`.
4. The contract verifies the proof against the stored root. Invalid proofs revert with no distribution.
5. The contract checks the claim tracker to confirm the recipient has not exceeded the allocation.
6. The contract transfers tokens to the recipient address through ERC20 transfer.
7. The claim tracker records the claim so the same allocation cannot be claimed twice.

## Strategy variants [#strategy-variants]

Each strategy modifies the base flow with additional constraints:

### Time-bound airdrop [#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 [#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 [#push-airdrop]

* **Admin initiated.** The administrator calls a distribution function, supplies the recipient allocation proof, and pushes tokens directly to recipient addresses. Recipients do not call `claim()`.
* **Owner controlled claim tracking.** Distribution is controlled by the admin. The Merkle root still validates recipient eligibility, but the claim lifecycle is inverted.

## Claim tracking strategies [#claim-tracking-strategies]

| Strategy                        | Mechanism                      | Best for                         | Gas profile                                         |
| ------------------------------- | ------------------------------ | -------------------------------- | --------------------------------------------------- |
| Bitmap (DALPBitmapClaimTracker) | One bit per recipient          | All-or-nothing claims            | Constant cost, gas-efficient for large lists        |
| Amount (DALPAmountClaimTracker) | Tracks claimed amount per user | Partial claims, vesting airdrops | Higher per-claim cost, supports progressive release |

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 [#failure-modes]

| Failure                                       | Result                                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Invalid Merkle proof                          | The proof does not match the stored root. The transaction reverts with no state change.            |
| Already claimed with bitmap tracking          | The recipient bit is already set. The transaction reverts.                                         |
| Claim exceeds allocation with amount tracking | The cumulative claimed amount would exceed the Merkle encoded allocation. The transaction reverts. |
| Outside a time-bound claim window             | `block.timestamp` is before start or after end. The transaction reverts.                           |
| Before a vesting cliff                        | No tokens are releasable. The transaction reverts.                                                 |
| Insufficient airdrop balance                  | The contract does not hold enough tokens to fulfil the claim. ERC20 transfer reverts.              |

<Callout type="info">
  Airdrop contracts and factory identifiers exist for the supported strategies. Treat this page as the architecture
  explanation for distribution semantics, not as a UI walkthrough.
</Callout>

## Related resources [#related-resources]

* [Airdrop](/docs/architecture/components/capabilities/airdrop), contracts, roles, and configuration
* [Signing flow](/docs/architecture/flows/signing-flow), how transactions are signed and broadcast
* [Compliance transfer](/docs/architecture/flows/compliance-transfer), transfer validation when tokens carry compliance rules
* [Asset issuance](/docs/architecture/flows/asset-issuance), how assets are created before airdrops
* [Capabilities overview](/docs/architecture/components/capabilities), how capabilities extend the platform