# 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` |