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)

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:

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:

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:

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