Skip to content

✨ Transform README with modern GitHub-trending design and Shadowgraph Labs branding #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

✨ Transform README with modern GitHub-trending design and Shadowgraph Labs branding #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b702143
Initial plan
Copilot Sep 22, 2025
f88f7fa
Update README with hipster/GitHub-trending style and Shadowgraph Labs…
Copilot Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .svelte-kit/generated/server/internal.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ export const options = {
app: ({ head, body, assets, nonce, env }) => "<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"utf-8\" />\n <link rel=\"icon\" href=\"" + assets + "/favicon.png\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n <script>\n // Prevent Flash Of Unstyled Content (FOUC) by applying the user's theme\n // preference before the app hydrates. Uses localStorage when available,\n // otherwise falls back to the system preference.\n (function () {\n try {\n var theme = localStorage.getItem(\"theme\");\n if (theme === \"dark\") {\n document.documentElement.classList.add(\"dark\");\n } else if (theme === \"light\") {\n document.documentElement.classList.remove(\"dark\");\n } else if (\n window.matchMedia &&\n window.matchMedia(\"(prefers-color-scheme: dark)\").matches\n ) {\n document.documentElement.classList.add(\"dark\");\n }\n } catch (e) {\n // ignore errors (e.g. blocked storage)\n }\n })();\n </script>\n " + head + "\n </head>\n <body data-sveltekit-preload-data=\"hover\" class=\"antialiased\">\n <div class=\"min-h-screen site-container\">" + body + "</div>\n </body>\n</html>\n",
error: ({ status, message }) => "<!doctype html>\n<html lang=\"en\">\n\t<head>\n\t\t<meta charset=\"utf-8\" />\n\t\t<title>" + message + "</title>\n\n\t\t<style>\n\t\t\tbody {\n\t\t\t\t--bg: white;\n\t\t\t\t--fg: #222;\n\t\t\t\t--divider: #ccc;\n\t\t\t\tbackground: var(--bg);\n\t\t\t\tcolor: var(--fg);\n\t\t\t\tfont-family:\n\t\t\t\t\tsystem-ui,\n\t\t\t\t\t-apple-system,\n\t\t\t\t\tBlinkMacSystemFont,\n\t\t\t\t\t'Segoe UI',\n\t\t\t\t\tRoboto,\n\t\t\t\t\tOxygen,\n\t\t\t\t\tUbuntu,\n\t\t\t\t\tCantarell,\n\t\t\t\t\t'Open Sans',\n\t\t\t\t\t'Helvetica Neue',\n\t\t\t\t\tsans-serif;\n\t\t\t\tdisplay: flex;\n\t\t\t\talign-items: center;\n\t\t\t\tjustify-content: center;\n\t\t\t\theight: 100vh;\n\t\t\t\tmargin: 0;\n\t\t\t}\n\n\t\t\t.error {\n\t\t\t\tdisplay: flex;\n\t\t\t\talign-items: center;\n\t\t\t\tmax-width: 32rem;\n\t\t\t\tmargin: 0 1rem;\n\t\t\t}\n\n\t\t\t.status {\n\t\t\t\tfont-weight: 200;\n\t\t\t\tfont-size: 3rem;\n\t\t\t\tline-height: 1;\n\t\t\t\tposition: relative;\n\t\t\t\ttop: -0.05rem;\n\t\t\t}\n\n\t\t\t.message {\n\t\t\t\tborder-left: 1px solid var(--divider);\n\t\t\t\tpadding: 0 0 0 1rem;\n\t\t\t\tmargin: 0 0 0 1rem;\n\t\t\t\tmin-height: 2.5rem;\n\t\t\t\tdisplay: flex;\n\t\t\t\talign-items: center;\n\t\t\t}\n\n\t\t\t.message h1 {\n\t\t\t\tfont-weight: 400;\n\t\t\t\tfont-size: 1em;\n\t\t\t\tmargin: 0;\n\t\t\t}\n\n\t\t\t@media (prefers-color-scheme: dark) {\n\t\t\t\tbody {\n\t\t\t\t\t--bg: #222;\n\t\t\t\t\t--fg: #ddd;\n\t\t\t\t\t--divider: #666;\n\t\t\t\t}\n\t\t\t}\n\t\t</style>\n\t</head>\n\t<body>\n\t\t<div class=\"error\">\n\t\t\t<span class=\"status\">" + status + "</span>\n\t\t\t<div class=\"message\">\n\t\t\t\t<h1>" + message + "</h1>\n\t\t\t</div>\n\t\t</div>\n\t</body>\n</html>\n"
},
version_hash: "1xkp038"
version_hash: "qbzkuy"
};

export async function get_hooks() {
Expand Down
329 changes: 251 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,118 +1,291 @@
# Shadowgraph Reputation-Scaled Airdrop Client
<div align="center">

This is a SvelteKit dApp client for participating in a Shadowgraph reputation-scaled airdrop campaign. It supports both ECDSA-based claims and ZK-proof-based claims.
# 🌟 Shadowgraph Reputation-Gated Airdrop

## Features
### _The Future of Merit-Based Token Distribution_ 🚀

- **Wallet Connection**: Connect via MetaMask, WalletConnect, or Coinbase Wallet.
- **Score Checking**: Fetches your reputation score from the Shadowgraph backend.
- **Payout Preview**: See your potential airdrop amount based on your score and the configured curve.
- **Claim Flow**: A guided process to claim your tokens via an on-chain transaction.
- **Chain Awareness**: Automatically detects and prompts for switching to the correct network.
- **Debug Mode**: A special view for developers to inspect configuration and state.
<p align="center">
<img src="https://img.shields.io/badge/Built%20by-Shadowgraph%20Labs-blueviolet?style=for-the-badge" alt="Built by Shadowgraph Labs" />
<img src="https://img.shields.io/badge/Web3-Ready-00D4AA?style=for-the-badge" alt="Web3 Ready" />
<img src="https://img.shields.io/badge/Zero%20Knowledge-Enabled-FF6B6B?style=for-the-badge" alt="ZK Enabled" />
</p>

## Tech Stack

- **Framework**: SvelteKit
- **Styling**: TailwindCSS
- **Blockchain**: `viem` for EVM interactions, `@web3-onboard` for wallet connections.
- **Validation**: `zod` for environment and API response validation.
- **Icons**: `lucide-svelte`
- **Testing**: Vitest (unit), Playwright (e2e)
<p align="center">
<img src="https://img.shields.io/github/stars/Steake/Reputation-Gated-Airdrop?style=social" alt="GitHub Stars" />
<img src="https://img.shields.io/github/forks/Steake/Reputation-Gated-Airdrop?style=social" alt="GitHub Forks" />
<img src="https://img.shields.io/github/watchers/Steake/Reputation-Gated-Airdrop?style=social" alt="GitHub Watchers" />
</p>

---

## Getting Started
_Revolutionizing airdrops through reputation-based distribution with cutting-edge zero-knowledge proofs._

**Powered by [Shadowgraph Labs](https://shadowgraph.io) 🧪**

</div>

## 🎯 Why This Project Rocks

> **Traditional airdrops are broken.** They reward bots, incentivize Sybil attacks, and dilute value for genuine contributors.

**Our solution?** A sophisticated reputation-gated system that:

- 🛡️ **Prevents Sybil attacks** with cryptographic reputation scoring
- 🔮 **Rewards genuine contributors** based on provable on-chain activity
- 🚀 **Scales infinitely** with zero-knowledge proof technology
- 🌊 **Flows seamlessly** with multi-wallet support and intuitive UX

## ✨ Features That Matter

### 🔗 **Universal Wallet Support**

Connect with MetaMask, WalletConnect, Coinbase Wallet, and more. We've got you covered.

### 📊 **Real-Time Reputation Scoring**

Your contributions are continuously evaluated and reflected in your reputation score.

### 🎢 **Dynamic Payout Curves**

Choose from linear, square root, or quadratic distribution curves to optimize fairness.

### 🧙‍♂️ **Zero-Knowledge Privacy**

Prove your reputation without revealing sensitive data using cutting-edge ZK-SNARK technology.

### 🌐 **Multi-Chain Ready**

Built for Ethereum and EVM-compatible networks with seamless chain switching.

### 1. Installation
### 🔧 **Developer Experience**

Clone the repository and install the dependencies:
Comprehensive debug mode and developer tools for seamless integration.

## 🛠️ Tech Stack That Slaps

<div align="center">

| Frontend | Blockchain | Security | Testing |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| ![SvelteKit](https://img.shields.io/badge/SvelteKit-FF3E00?style=for-the-badge&logo=svelte&logoColor=white) | ![Viem](https://img.shields.io/badge/Viem-1B1B1D?style=for-the-badge) | ![Zod](https://img.shields.io/badge/Zod-3E67B1?style=for-the-badge) | ![Vitest](https://img.shields.io/badge/Vitest-6E9F18?style=for-the-badge) |
| ![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white) | ![Web3 Onboard](https://img.shields.io/badge/Web3%20Onboard-627EEA?style=for-the-badge) | ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white) | ![Playwright](https://img.shields.io/badge/Playwright-45BA4B?style=for-the-badge) |

</div>

### 🧬 **Architecture Highlights**

- **🔥 Svelte 4** - Blazing fast reactive framework
- **⚡ Vite** - Lightning-fast development experience
- **🎨 TailwindCSS** - Utility-first styling that scales
- **🔗 Viem** - Type-safe Ethereum interactions
- **🧪 Zod** - Runtime type validation for bulletproof APIs
- **🎭 Lucide Icons** - Beautiful, consistent iconography

## 🚀 Quick Start Guide

Ready to dive in? Let's get you up and running in under 5 minutes!

### 📦 **1. Installation**

Clone this masterpiece and install dependencies:

```bash
git clone <repository-url>
cd shadowgraph-airdrop-client
# Clone the repository
git clone https://github.com/Steake/Reputation-Gated-Airdrop.git
cd Reputation-Gated-Airdrop

# Install dependencies (Node.js 18+ required)
npm install

# You're ready to rock! 🎸
```

### 2. Environment Variables
### ⚙️ **2. Environment Configuration**

Create your `.env` file - this is where the magic happens! ✨

Create a `.env` file in the root of the project. This file is critical for configuring the dApp to point to the correct contracts, chain, and backend services.
```bash
# 🔮 Create your environment configuration
cp .env.example .env
```

<details>
<summary>📋 <strong>Complete Environment Variables Guide</strong></summary>

```env
# REQUIRED: Web3 & Chain Configuration
VITE_CHAIN_ID="11155111" # e.g., Sepolia
VITE_RPC_URL="https://rpc.sepolia.org"
VITE_TOKEN_ADDR="0x..." # The ERC20 token being airdropped

# REQUIRED: Airdrop Campaign Configuration
VITE_CAMPAIGN="0x..." # 32-byte campaign identifier
VITE_FLOOR_SCORE="600000" # Min score to claim (1e6 scale)
VITE_CAP_SCORE="1000000" # Score for max payout (1e6 scale)
VITE_MIN_PAYOUT="100" # Min token payout (in token units, e.g., "100" for 100 tokens)
VITE_MAX_PAYOUT="1000" # Max token payout
VITE_CURVE="SQRT" # Payout curve: "LIN", "SQRT", or "QUAD"

# REQUIRED: Backend API
VITE_API_BASE="https://api.shadowgraph.io/v1" # Base URL for score/artifact endpoints

# REQUIRED: Web3-Onboard Project ID
# Get one from https://cloud.walletconnect.com/
VITE_WALLETCONNECT_PROJECT_ID="YOUR_PROJECT_ID"

# OPTIONAL: Contract Addresses (at least one path must be enabled)
# To enable the ECDSA claim path:
VITE_AIRDROP_ECDSA_ADDR="0x..." # ReputationAirdropScaled contract
# To enable the ZK claim path:
VITE_AIRDROP_ZK_ADDR="0x..." # ReputationAirdropZKScaled contract
VITE_VERIFIER_ADDR="0x..." # EZKL Verifier contract

# OPTIONAL: Debug Mode
# Set to 'true' to enable the /debug route
VITE_DEBUG="true"
# 🌐 BLOCKCHAIN CONFIGURATION
VITE_CHAIN_ID="11155111" # Sepolia testnet (or your preferred network)
VITE_RPC_URL="https://rpc.sepolia.org" # RPC endpoint
VITE_TOKEN_ADDR="0x..." # ERC20 token being airdropped

# 🎯 AIRDROP CAMPAIGN SETTINGS
VITE_CAMPAIGN="0x..." # 32-byte campaign identifier
VITE_FLOOR_SCORE="600000" # Minimum score to claim (1e6 scale)
VITE_CAP_SCORE="1000000" # Score for maximum payout (1e6 scale)
VITE_MIN_PAYOUT="100" # Minimum token payout
VITE_MAX_PAYOUT="1000" # Maximum token payout
VITE_CURVE="SQRT" # Payout curve: "LIN", "SQRT", or "QUAD"

# 🔗 API & SERVICES
VITE_API_BASE="https://api.shadowgraph.io/v1" # Shadowgraph backend API
VITE_WALLETCONNECT_PROJECT_ID="YOUR_PROJECT_ID" # Get from https://cloud.walletconnect.com/

# 📜 SMART CONTRACTS (Choose your path!)
# 🖋️ Traditional ECDSA path:
VITE_AIRDROP_ECDSA_ADDR="0x..." # ReputationAirdropScaled contract

# 🧙‍♂️ Zero-Knowledge path:
VITE_AIRDROP_ZK_ADDR="0x..." # ReputationAirdropZKScaled contract
VITE_VERIFIER_ADDR="0x..." # EZKL Verifier contract

# 🔧 DEVELOPER TOOLS
VITE_DEBUG="true" # Enable debug mode (/debug route)
```

### 3. Running the Development Server
</details>

### 🚀 **3. Launch Your Dev Server**

Time to see your work come to life!

```bash
# 🔥 Fire up the development server
npm run dev

# 🌍 Open your browser to http://localhost:5173
# Watch the magic happen! ✨
```

Open [http://localhost:5173](http://localhost:5173) to view the application.
> **Pro Tip:** The app will automatically reload as you make changes. Happy coding! 👨‍💻

---
## 🎭 Development Modes

## Development Modes
### 🎪 **Mock Mode** (Perfect for Development)

### Mock Mode
No backend? No problem! When `VITE_API_BASE` is **not set**, we've got you covered:

If the `VITE_API_BASE` environment variable is **not set**, the application will run in **Mock Mode**. In this mode, it does not make real network requests to a backend. Instead, it uses mock data generators to simulate API responses. This is useful for UI development and testing without needing a live backend.
- 🎲 **Deterministic scores** based on wallet addresses
- 🎭 **Realistic mock data** for `/claim-artifact` and `/proof-meta` endpoints
- 🚀 **Zero setup** - just start coding!

- `/scores/:addr` returns a deterministic score based on the address.
- `/claim-artifact` and `/proof-meta` return fake but correctly-shaped data.
Perfect for UI development and testing without infrastructure dependencies.

### Production Mode
### 🌍 **Production Mode** (The Real Deal)

Set `VITE_API_BASE` to your backend's URL to connect to the live services.
Set `VITE_API_BASE` to connect to live Shadowgraph services. Experience the full power of reputation-gated airdrops!

## Claim Paths (ECDSA vs. ZK)
## 🛤️ Claim Paths: Choose Your Adventure

The application can be configured for one or both claim paths:
### 🖋️ **ECDSA Path** (Traditional & Reliable)

- **ECDSA Path**: Requires `VITE_AIRDROP_ECDSA_ADDR` to be set. The client fetches a signed EIP-712 artifact from the backend and submits it to the `ReputationAirdropScaled` contract.
- **ZK Path**: Requires `VITE_AIRDROP_ZK_ADDR` and `VITE_VERIFIER_ADDR` to be set. The client fetches ZK proof calldata from the backend and submits it to the `ReputationAirdropZKScaled` contract.
- **Setup**: Configure `VITE_AIRDROP_ECDSA_ADDR`
- **How it works**: Fetches signed EIP-712 artifacts from Shadowgraph backend
- **Submits to**: `ReputationAirdropScaled` smart contract
- **Best for**: Standard deployments and maximum compatibility

If both are configured, the UI will prioritize the ZK path by default.
### 🧙‍♂️ **Zero-Knowledge Path** (Cutting-Edge Privacy)

## Available Scripts
- **Setup**: Configure `VITE_AIRDROP_ZK_ADDR` and `VITE_VERIFIER_ADDR`
- **How it works**: Generates zero-knowledge proofs for reputation verification
- **Submits to**: `ReputationAirdropZKScaled` smart contract
- **Best for**: Privacy-focused applications and advanced cryptographic setups

- `npm run dev`: Start the dev server.
- `npm run build`: Build the application for production.
- `npm run preview`: Preview the production build locally.
- `npm run test:unit`: Run unit tests with Vitest.
- `npm run test:e2e`: Run end-to-end tests with Playwright.
- `npm run lint`: Check for linting and formatting issues.
- `npm run format`: Automatically format the code.
> **💡 Pro Tip:** Configure both paths for maximum flexibility! The UI will intelligently prioritize ZK when available.

```
## 📜 Available Scripts

| Command | Description | Duration |
| ------------------- | ----------------------------- | -------- |
| `npm run dev` | 🚀 Start development server | ~2s |
| `npm run build` | 🏗️ Build for production | ~30s |
| `npm run preview` | 👁️ Preview production build | ~2s |
| `npm run test:unit` | 🧪 Run unit tests (Vitest) | ~2s |
| `npm run test:e2e` | 🎭 Run E2E tests (Playwright) | Variable |
| `npm run lint` | 🔍 Check code quality | ~8s |
| `npm run format` | ✨ Auto-format code | ~9s |

> **💡 Quick Commands:** Run `npm run format && npm run lint` before committing to ensure pristine code quality!

## 🏗️ Project Structure

```
src/
├── lib/
│ ├── components/ # 🧩 Reusable Svelte components
│ ├── stores/ # 📦 Svelte stores (state management)
│ ├── web3/ # 🔗 Blockchain interaction logic
│ ├── abi/ # 📜 Smart contract ABIs
│ └── utils/ # 🛠️ Utility functions
├── routes/ # 🛤️ SvelteKit routes and pages
└── app.html # 🌐 HTML template

tests/
├── unit/ # 🧪 Vitest unit tests
└── e2e/ # 🎭 Playwright E2E tests
```

## 🤝 Contributing

We love contributions! Here's how to get involved:

1. 🍴 **Fork** the repository
2. 🌿 **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. ✨ **Make** your changes (don't forget to run `npm run format && npm run lint`)
4. 📝 **Commit** your changes (`git commit -m 'Add amazing feature'`)
5. 🚀 **Push** to the branch (`git push origin feature/amazing-feature`)
6. 🎉 **Open** a Pull Request

### 🌟 Contributing Guidelines

- Follow existing code style and conventions
- Add tests for new features
- Update documentation as needed
- Be respectful and collaborative

## 🚨 Issues & Support

Encountered a bug? Have a feature request? We'd love to hear from you!

- 🐛 **Bug Reports**: [Open an issue](https://github.com/Steake/Reputation-Gated-Airdrop/issues/new?template=bug_report.md)
- 💡 **Feature Requests**: [Request a feature](https://github.com/Steake/Reputation-Gated-Airdrop/issues/new?template=feature_request.md)
- 💬 **Discussions**: [Join the conversation](https://github.com/Steake/Reputation-Gated-Airdrop/discussions)

## 📊 Stats & Recognition

<div align="center">

![GitHub repo size](https://img.shields.io/github/repo-size/Steake/Reputation-Gated-Airdrop?style=for-the-badge)
![GitHub code size](https://img.shields.io/github/languages/code-size/Steake/Reputation-Gated-Airdrop?style=for-the-badge)
![GitHub top language](https://img.shields.io/github/languages/top/Steake/Reputation-Gated-Airdrop?style=for-the-badge)

</div>

## 🙏 Acknowledgments

This project builds upon the incredible work of:

- **SvelteKit Team** - For the amazing framework
- **Viem Contributors** - For type-safe Ethereum interactions
- **Web3-Onboard Team** - For seamless wallet connections
- **EZKL Community** - For zero-knowledge proof infrastructure
- **The entire Web3 community** - For pushing the boundaries of decentralized technology

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">

### 🌟 **Built with ❤️ by [Shadowgraph Labs](https://shadowgraph.io)** 🌟

_Revolutionizing decentralized reputation systems, one commit at a time._

**[🌐 Website](https://shadowgraph.io) • [📧 Contact](mailto:[email protected]) • [🐦 Twitter](https://twitter.com/shadowgraphlabs) • [💼 LinkedIn](https://linkedin.com/company/shadowgraph-labs)**

---

_"In cryptography we trust, in reputation we thrive." - Shadowgraph Labs_

</div>
Loading