🧊 Etherbox

Create. Share. Claim.

Etherbox is a smart contract protocol for distributing tokens through unique “boxes” — claimable allocations that can be shared with anyone via a simple ID.

---

✨ Overview

Etherbox allows anyone to:

• send crypto gifts to friends
• reward community members
• run public airdrops
• distribute tokens during launches

Each box has a unique ID. Anyone with the ID can claim — depending on the rules set by the creator.

---

⚙️ How it works

1. Create a box

The creator defines:

• token
• amount per wallet
• number of claims
• public or private access

const boxId = ethers.id("my-unique-box");

---

2. Share the ID

Send it anywhere:

• DM
• Telegram / Discord
• email
• public post

---

3. Claim tokens

Users:

1. paste the box ID
2. connect wallet
3. click Claim

Tokens are transferred instantly.

---

🔐 Features

• 🧾 Public & private boxes
• 👥 Whitelist support
• 🛡 Anti-Sybil hook (extensible)
• ⚡ Instant on-chain claiming
• 🧊 Simple and predictable logic
• 💸 0% platform fee (gas only)

---

📁 Project Structure

contracts/
├── core/
│   ├── Etherbox.sol
│   ├── Box.sol
│   └── Claim.sol
├── extensions/
│   ├── AntiSybil.sol
│   └── Whitelist.sol
├── libraries/
│   ├── BoxLib.sol
│   └── ValidationLib.sol
├── interfaces/
│   ├── IERC20.sol
│   └── IEtherbox.sol
└── mocks/
    └── MockERC20.sol

---

🚀 Getting Started

Install

npm install

Compile

npx hardhat compile

Run tests

npx hardhat test

---

🧪 Example

Create a box locally:

npx hardhat run scripts/createBox.ts

Deploy contract:

npx hardhat run scripts/deploy.ts

---

📊 Test Coverage

✔ Public box creation ✔ Private box (whitelist) ✔ Claim execution ✔ Double-claim protection ✔ Validation (limits, inputs) ✔ Anti-Sybil placeholder

---

🧠 Architecture

See:

• docs/ARCHITECTURE.md
• docs/BOX_FLOW.md
• docs/SECURITY.md

---

⚠️ Disclaimer

This repository is a reference implementation of the Etherbox protocol.

• Not audited
• Not intended for production use
• Provided for educational and demonstration purposes

---

📜 License

MIT

---

🌐 Vision

Etherbox aims to become a universal primitive for token distribution across Web3:

• simple
• composable
• chain-agnostic

A box is just an ID. Everything else is trustless.

---

Built for Web3 distribution.