# Signature Distributor

## Introduction

The ECDSA Distributor system provides signature-based token distribution using ECDSA signatures for claim verification. This approach offers an alternative to Merkle tree-based distributions, allowing for more flexible and dynamic claim authorization.

## 🚀 Quick Start

### What is an ECDSA Distributor?

An ECDSA Distributor is a smart contract system that enables efficient token distribution using signature verification. Instead of storing a Merkle tree root, it uses cryptographic signatures from an authorized signer to validate claims, offering greater flexibility for dynamic distributions.

### Key Benefits

* ✅ **Dynamic Claims** - No need to generate Merkle trees in advance
* ✅ **Signature-Based** - Claims authorized via ECDSA signatures
* ✅ **Batch Processing** - Process multiple claims in one transaction

### Key Differences from Merkle Distributors

| Feature      | Merkle Distributor  | ECDSA Distributor |
| ------------ | ------------------- | ----------------- |
| Verification | Merkle proofs       | ECDSA signatures  |
| Data Storage | Merkle root         | Authorized signer |
| Claim Data   | Fixed at deployment | Dynamic per claim |
| Gas Cost     | Higher for setup    | Higher per claim  |
| Flexibility  | Limited             | High              |

## 📋 System Overview

### Architecture Diagram

```
┌─────────────────────────────────────────────────────┐
│                MDCreate2 Factory                    │
└────────────────────────┬────────────────────────────┘
                         │ Deploys
┌────────────────────────▼────────────────────────────┐
│                BaseECDSADistributor                 │
│    (Abstract base with signature verification)      │
└────────────────────────┬────────────────────────────┘
                         │ Inherited by
        ┌────────────────┴────────────────┐
        │                                 │
┌───────▼───────────────────────┐   ┌─────▼──────────────────────┐
│ FungibleTokenECDSADistributor │   │ FungibleTokenWithFeesECDSA │
│                               │   │ Distributor                │
└───────────────────────────────┘   └────────────────────────────┘
```

### Core Components

* **Base Contract** - Core distribution logic with signature verification
* **Standard Extensions** - ERC20 and native token implementations
* **Fee Extensions** - Custom fee handling implementations
* **Factory Integration** - Same MDCreate2 factory for deployment

## 🔧 Core Contracts

### BaseECDSADistributor

The foundation contract providing signature-based distribution functionality.

#### Key Features

**Storage Pattern (ERC7201)**

```solidity
struct BaseECDSADistributorStorage {
    mapping(bytes32 userClaimId => bool claimed) claimedClaims;
    address deployer;
    address authorizedSigner;
    address token;
    address claimHook;
    uint256 startTime;
    uint256 endTime;
}
```

**Claim Mechanism**

Batch claim support with signature verification:

```solidity
function claim(
    address[] calldata recipients,
    bytes32[] calldata userClaimIds,
    bytes[] calldata datas,
    bytes[] calldata signatures,
    bytes[] calldata extraDatas
) external payable
```

**Security Features**

* ECDSA signature verification
* Pausable functionality
* Reentrancy protection
* Claim ID tracking to prevent double claims

#### Key Functions

| Function           | Description                                    |
| ------------------ | ---------------------------------------------- |
| `setBaseParams()`  | Sets token, time window, and authorized signer |
| `setClaimHook()`   | Configures optional claim hook                 |
| `claim()`          | Processes batch claims with signatures         |
| `togglePause()`    | Emergency pause functionality                  |
| `getClaimStatus()` | Check if claims are already processed          |

## 🔌 Extension Contracts

### FungibleTokenECDSADistributor

Standard implementation for ERC20 and native token distribution.

**Data Structure:**

```solidity
struct FungibleTokenECDSADistributorData {
    uint256 claimableTimestamp;
    uint256 claimableAmount;
}
```

**Key Features:**

* Supports both ERC20 and native tokens
* Time-locked claims based on `claimableTimestamp`
* Standard withdrawal function for unclaimed tokens

### FungibleTokenWithFeesECDSADistributor

Extension that includes fee data in the claim structure.

**Data Structure:**

```solidity
struct FungibleTokenWithFeesECDSADistributorData {
    uint256 claimableTimestamp;
    uint256 claimableAmount;
    uint256 fees;
}
```

**Key Features:**

* Fees encoded in claim data
* Batch fee collection
* Mandatory fee collector configuration
* Custom fee amounts per claim

## 💰 Fee System

### Overview

The ECDSA distributor system supports flexible fee collection with different implementations.

### Fee Flow

```
    ┌─────────────────┐
    │  Batch Claims   │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │ Calculate Total │
    │      Fees       │
    └────────┬────────┘
             │
             ▼
    ┌──────────────────┐
    │  Fee Collector   │
    │  Set?            │
    └─────┬───────┬────┘
          │       │
    Yes   │       │   No
          │       │
          ▼       ▼
    ┌──────────┐ ┌─────────┐
    │ Charge   │ │  Skip   │
    │ Fees     │ │  Fees   │
    └────┬─────┘ └─────────┘
         │
         ▼
    ┌──────────────────┐
    │    Fee Token?    │
    └─────┬───────┬────┘
          │       │
   Native │       │ ERC20
          │       │
          ▼       ▼
    ┌──────────┐ ┌─────────────┐
    │ Transfer │ │  Transfer   │
    │ ETH      │ │  Tokens     │
    └──────────┘ └─────────────┘
```

### Fee Implementations

1. **Fixed Fee** - Base implementation charges per claim or batch
2. **Custom Fee** - Extension allows per-claim fee amounts

## 🔒 Security

### Access Control

| Role              | Permissions                                    |
| ----------------- | ---------------------------------------------- |
| Owner             | Set parameters, toggle pause, configure signer |
| Authorized Signer | Sign claim authorizations                      |
| Users             | Submit claims with valid signatures            |

### Security Features

* **Signature Verification** - ECDSA signature validation
* **Pausable** - Emergency stop functionality
* **Reentrancy Guards** - Protection against reentrancy attacks
* **Claim Tracking** - Prevents double claiming
* **Time Windows** - Enforced distribution periods

## 📡 Events & Errors

### Errors

| Error                  | Condition                     | Selector     |
| ---------------------- | ----------------------------- | ------------ |
| `UnsupportedOperation` | Operation not allowed         | `0x9ba6061b` |
| `TimeInactive`         | Outside distribution window   | `0x0c143eb8` |
| `InvalidSignature`     | Signature verification failed | `0x8baa579f` |
| `ClaimClaimed`         | Claim already processed       | `0xadeff36f` |
| `IncorrectFees`        | Fee amount mismatch           | `0x1669aa83` |
| `FeeCollectorNotSet`   | Missing fee collector         | `0xb4b53f42` |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tokentable.xyz/for-developers/airdrop/evm/ecdsa.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.