• 🧠 Executive Summary
• 🏗 Architectural Flow
• ✍️ EIP-712 Signature Standards
• 🔢 Merkle Tree Mathematics
• 🛡 Security & Vesting Timeline
• 📂 Project Structure

This protocol solves the "Million User Problem" in token distribution. Sending tokens to 1 million users via a loop would cost millions of dollars in gas.

Instead, we use a Pull-Based Architecture:

1. Compression: We compress 1 million user balances into a single 32-byte Merkle Root.
2. Verification: Users provide a cryptographic proof that they are part of that root.
3. Security: We add an extra layer of EIP-712 Signatures to prevent "Front-Running Claims" where a bot steals a user's proof to claim tokens for themselves.

The system uses a Hybrid Off-Chain/On-Chain model. We calculate eligibility off-chain to save gas, and verify proofs on-chain for trustless execution.

graph LR
    %% Backend Logic
    subgraph OFFCHAIN ["💻 Off-Chain Backend"]
        Input[("📄 Whitelist")] -->|1. Hash & Sort| Script{{"⚙️ Merkle Engine"}}
        Script -->|Output| Root[("🌳 Merkle Root")]
        Script -->|Output| Proofs[("🔐 User Proofs")]
    end

    %% Interaction Logic
    subgraph ONCHAIN ["⛓️ On-Chain Layer"]
        Root -.->|2. Deploy| Contract["🏛️ Airdrop Contract"]
        User((👤 User)) -->|3. Sign Msg| Wallet["🦊 MetaMask"]
        
        Wallet -->|4. Call Claim| Contract
        Proofs -.->|Verify Path| Contract
        Contract -->|5. Transfer Token| User
    end

    style OFFCHAIN fill:#1a1a1a,stroke:#b298dc
    style ONCHAIN fill:#2d1b4e,stroke:#9d4edd,stroke-width:2px
    style Contract fill:#1a1a1a,stroke:#fff
    style Script fill:#1a1a1a,stroke:#fff

We implement strict Typed Structured Data hashing. This ensures users know exactly what they are signing, preventing phishing attacks.

struct EIP712Domain {
    string name;              // "SisoAirdrop"
    string version;           // "1.0.0"
    uint256 chainId;          // 11155111 (Sepolia)
    address verifyingContract;// Contract Address
}

struct AirdropClaim {
    address account;
    uint256 amount;
}

Why? This prevents Replay Attacks. A signature generated for the Sepolia Testnet cannot be re-used on Mainnet because the chainId inside the hash would be different.

The Merkle Tree allows us to verify inclusion in a set of data without revealing the entire set.

• Leaves: Keccak256(address, amount)
• Nodes: Keccak256(Child_A, Child_B)
• Root: The final hash at the top of the tree.

If a user wants to claim, they must provide a Proof Path (hashes of sibling nodes). The contract re-calculates the hash up the tree.

$$ \text{If } \text{CalculatedRoot} == \text{StoredRoot} \implies \text{Valid Claim} $$

The distribution follows a Time-Based Lifecycle to protect the token economy from immediate sell pressure.

timeline
    title Airdrop Lifecycle (0 to 97 Days)
    Day 0 : 🟢 TGE Starts : 50% Unlocked
    Day 30 : 🟡 Cliff Starts : Claims Paused
    Day 90 : 🔵 Cliff Ends : Remaining 50% Unlocked
    Day 97 : 🔴 Expiry : Unclaimed Tokens Burned

A clean separation of concerns: Data (Off-chain generation) vs Source (On-chain execution).

Siso-Merkle-Airdrop/
├── airdrop-data/          # 🧠 Off-Chain Logic
│   ├── input.json         # Raw Whitelist (Address + Amount)
│   ├── merkle.js          # Node.js Script for Root Generation
│   └── backend/           # EIP-712 Signing Utilities
├── src/                   # ⛓️ Smart Contracts
│   ├── SisoToken.sol      # The ERC20 Asset
│   └── MerkleAirdrop.sol  # Distribution Logic
├── script/                # 🚀 DevOps
│   └── Deploy.s.sol       # Deployment Scripts
└── test/                  # 🧪 Foundry Test Suite