> For the complete documentation index, see [llms.txt](https://docs.tokentable.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tokentable.xyz/for-developers/airdrop/evm/merkle.md).

# Merkle Distributor

## Introduction

The Merkle Distributor provides a modular and efficient solution for token distribution using merkle proofs, supporting various token standards and customizable distribution patterns.

## 🚀 Quick Start

### What is a Merkle Distributor?

A Merkle Distributor is a smart contract system that enables efficient and verifiable token airdrops. Instead of storing all recipient data on-chain, it uses a Merkle tree where only the root is stored, significantly reducing gas costs while maintaining security.

### Key Benefits

* ✅ **Gas Efficient** - Only stores Merkle root on-chain
* ✅ **Verifiable** - Claims are cryptographically proven
* ✅ **Flexible** - Supports multiple token types and distribution patterns
* ✅ **Secure** - Built with security best practices

## 📋 System Overview

### Architecture Diagram

```
┌────────────────────────────────────────────────────┐
│                MDCreate2 Factory                   │
└────────────────────────┬───────────────────────────┘
                         │ Deploys
┌────────────────────────▼───────────────────────────┐
│               BaseMerkleDistributor                │
│      (Abstract base with core functionality)       │
└────────────────────────┬───────────────────────────┘
                         │ Inherited by
        ┌────────────────┴────────────────┐
        │                                 │
┌───────▼──────────┐           ┌──────────▼──────────┐
│ ERC20 Extensions │           │  ERC721 Extensions  │
└──────────────────┘           └─────────────────────┘
```

### Core Components

* **Base Contract** - Core distribution logic
* **Extensions** - Token-specific implementations
* **Custom Extensions** - Special use cases

## 🔧 Core Contracts

### BaseMerkleDistributor

The foundation contract providing core distribution functionality.

#### Key Features

**Storage Pattern (ERC7201)**

The contract uses ERC7201 storage pattern:

```solidity
struct BaseMerkleDistributorStorage {
    mapping(bytes32 leaf => bool used) usedLeafs;
    bytes32 root;
    address deployer;
    address token;
    address claimDelegate;
    uint256 startTime;
    uint256 endTime;
    address claimHook;
}
```

**Claim Mechanism**

Two ways to claim tokens:

1. **Direct Claim** - Recipients claim their own tokens
2. **Delegate Claim** - Authorized delegate claims for recipients

```solidity
function claim(
    bytes32[] calldata proof,
    bytes32 group,
    bytes calldata data,
    bytes calldata extraData
) external payable
```

**Security Features**

* Reentrancy protection on all claim functions
* Double-claim prevention via leaf tracking
* Time-based access control
* Owner-only administrative functions

## 🔌 Extension Contracts

### ERC20 Extensions

#### TokenTableMerkleDistributor

Standard ERC20 token distribution with time-locked claims.

```solidity
struct TokenTableMerkleDistributorData {
    uint256 index;
    uint256 claimableTimestamp;
    uint256 claimableAmount;
}
```

#### TokenTableNativeMerkleDistributor

Distributes native tokens (ETH) with similar functionality.

**Special Features:**

* Handles ETH transfers
* `receive()` function for accepting ETH
* Native token withdrawal support

### ERC721 Extensions

#### SimpleERC721MerkleDistributor

Mints new NFTs to recipients.

**Key Behavior:**

* Creates new tokens via `safeMint`
* No withdrawal function (mints are permanent)

#### SimpleNoMintERC721MerkleDistributor

Distributes pre-existing NFTs.

**Key Behavior:**

* Transfers NFTs held by contract
* Owner can withdraw specific token IDs
* Repurposes `amount` parameter as `tokenId`

### Custom Extensions

#### CustomFeesNativeMerkleDistributor

Native token distributor with fee threshold logic.

**Features:**

* Configurable `feelessThreshold`
* Claims below threshold bypass fees
* Modified claim flow for fee handling

#### NFTGatedMerkleDistributor

Claims gated by NFT ownership.

```solidity
struct NFTGatedMerkleDistributorData {
    TokenTableMerkleDistributorData base;
    uint256 expiryTimestamp;
    uint256 nftTokenId;
}
```

**Special Features:**

* Claims tied to NFT ownership
* Delegate.xyz integration
* Auto-recipient from NFT owner

## 💰 Fee System

### Overview

The fee system provides flexible fee collection for claims.

### Components

```
     ┌─────────────────┐
     │  Claim Request  │
     └────────┬────────┘
              │
              ▼
    ┌────────────────────┐
    │ Fee Collector Set? │
    └─────┬───────┬──────┘
          │       │
      Yes │       │ No
          │       │
          ▼       ▼
    ┌──────────┐ ┌─────────┐
    │Calculate │ │  No     │
    │   Fee    │ │  Fee    │
    └────┬─────┘ └─────────┘
         │
         ▼
    ┌──────────────────┐
    │    Fee Token?    │
    └─────┬───────┬────┘
          │       │
   Native │       │ ERC20
          │       │
          ▼       ▼
    ┌──────────┐ ┌─────────────┐
    │ Deduct   │ │  Transfer   │
    │ from     │ │  from       │
    │ msg.value│ │  Payer      │
    └──────────┘ └─────────────┘
```

### Configuration

1. **Fee Collector** - Address that receives fees
2. **Fee Token** - Native or ERC20 token for fees
3. **Fee Calculation** - External `ITTUFeeCollector` interface

## 🔒 Security

### Access Control

| Role     | Permissions                                           |
| -------- | ----------------------------------------------------- |
| Owner    | Set parameters, withdraw tokens, configure extensions |
| Delegate | Claim on behalf of recipients                         |
| Users    | Claim their allocated tokens                          |

### Security Features

* **Reentrancy Guards** - All state-changing functions protected
* **Leaf Tracking** - Prevents double claims
* **Time Windows** - Enforced distribution periods
* **Proof Verification** - Cryptographic claim validation

## 📡 Events & Errors

### Events

| Event              | Description              |
| ------------------ | ------------------------ |
| `ClaimDelegateSet` | Delegate address updated |
| `Claimed`          | Successful token claim   |

### Errors

| Error                  | Condition             | Selector     |
| ---------------------- | --------------------- | ------------ |
| `UnsupportedOperation` | Operation not allowed | `0x9ba6061b` |
| `TimeInactive`         | Outside claim window  | `0x0c143eb8` |
| `InvalidProof`         | Merkle proof invalid  | `0x09bde339` |
| `LeafUsed`             | Already claimed       | `0x0e4b0ab2` |
| `IncorrectFees`        | Fee amount mismatch   | `0x1669aa83` |