Ethos Reputation Launch

⚠️ Hackathon Project: Built for Ethos Vibeathon 2026. This is a demonstration of reputation-gated NFT systems and should not be used in production without proper security audits and decentralized oracle implementation.

⭐ If this project inspires you, please give it a star on GitHub — it fuels open-source innovation!

Ethos Reputation Launch

A soulbound NFT launch system that gates access based on onchain reputation scores from Ethos Network. Users with verified reputation can mint non-transferable NFTs and claim tiered token rewards - creating fair, bot-resistant launches for Web3 communities.

The Problem

Current NFT launches suffer from:

Bot farming: Automated scripts mint massive quantities
Sybil attacks: Single users create hundreds of wallets
Unfair distribution: Real community members get nothing
No accountability: Bad actors face no consequences

Result: Communities lose trust. Projects fail. Real users are priced out.

The Solution

Reputation-gated launches powered by Ethos Network:

Prove Your Reputation - Users must have verified Ethos credibility scores
Mint Your Badge - High-reputation users mint soulbound NFTs (non-transferable)
Claim Your Rewards - NFT holders claim tokens based on reputation tier
Build Trust - Only real, verified community members participate

Result: Fair launches. Real users rewarded. Bots eliminated.

Features

Soulbound NFTs (Non-Transferable)

NFTs are permanently bound to minter's wallet
Cannot be transferred, sold, or moved
Prevents multi-wallet farming
True identity-based access

Tiered Reputation System

Gold Tier (1400+ score): 15,000 tokens
Silver Tier (1000-1399): 10,000 tokens
Bronze Tier (800-999): 5,000 tokens
Denied (<800 score): No access

Configurable Tier Thresholds

Contract owner (king) can set custom tier thresholds at deployment
Allows reusability across different projects with varying requirements
Example: Project A requires 1200+ for Gold, Project B requires 1600+

One-Time Claims

Each NFT can claim tokens exactly once
Prevents double-claiming exploits
Fair distribution guaranteed

Security-First Design

Custom King security modules
Reentrancy protection
Pausable in emergencies
Role-based access control

Emergency Recovery

NFTs are soulbound and cannot be transferred by users. However, the contract owner (king) has emergency recovery capabilities:

Use case: User loses access to wallet, needs NFT moved to new wallet
Implementation: King can call transferFrom() without requiring approval
Limitation: This is centralized trust - king must be trusted entity
Production: In production, this could be replaced with multi-sig or time-delayed governance

This design balances user protection (soulbound) with practical recovery needs.

Design Decision: Snapshot-Based Reputation

This system uses snapshot-based reputation rather than dynamic reputation:

At NFT Mint:

User's Ethos score is checked
Tier (Gold/Silver/Bronze) is calculated and permanently stored with the NFT
This tier never changes, even if the user's Ethos score changes later

At Token Claim:

The stored tier (not current score) determines token rewards
This prevents reputation manipulation and rewards users based on their reputation when they committed to the system

Why This Design?

Anti-gaming: Users can't temporarily boost score, mint, then drop
Fairness: Rewards reflect reputation at commitment time
Gas efficiency: No need to re-check external scores on every claim
Simplicity: Immutable tier = predictable behavior

Alternative Design: A dynamic system could re-check scores at claim time, but this would:

Be more expensive (extra external calls)
Enable gaming (boost score temporarily)
Punish users for temporary reputation drops

Architecture

┌─────────────────────────────────────────────┐
│    Off-Chain (Ethos Network)                │
│  - User reputation scores                   │
│  - Community attestations                   │
│  - Behavioral data                          │
└──────────────────┬──────────────────────────┘
                   │ Oracle Pattern
                   ↓
┌─────────────────────────────────────────────┐
│   Contract Owner and Admin (Trusted Relayer)│
│  - Fetches verified scores from Ethos API   │
│  - Stores scores onchain via setEthosScore()│
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│        ReputationNFT Contract               │
│  ┌─────────────────────────────────────┐    │
│  │  EthosIntegration Module            │    │
│  │  - Stores reputation scores         │    │
│  │  - Maps address → score             │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  TierManager Module                 │    │
│  │  - Calculates tier from score       │    │
│  │  - Gold/Silver/Bronze/Denied        │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  Minting Logic                      │    │
│  │  - Checks score ≥ 800               │    │
│  │  - Mints soulbound NFT              │    │
│  │  - Stores tier onchain              │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  Soulbound Enforcement              │    │
│  │  - Overrides transferFrom()         │    │
│  │  - Overrides safeTransferFrom()     │    │
│  │  - Reverts all transfer attempts    │    │
│  └─────────────────────────────────────┘    │
└──────────────────┬──────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────┐
│  ReputationToken Contract                   │
│  - Checks NFT ownership via interface       │
│  - Reads tier from NFT contract             │
│  - Mints tokens based on tier               │
│  - Tracks claims (one per NFT)              │
└─────────────────────────────────────────────┘

Contract Interactions

User Flow:

User → NFT Contract: mint()
NFT Contract → EthosIntegration: getEthosScore(user)
NFT Contract → TierManager: calculateTier(score)
NFT Contract: Mints soulbound NFT with stored tier
User → Token Contract: claimTokens(nftId)
Token Contract → NFT Contract: getTier(nftId)
Token Contract: Mints tokens based on tier

Oracle Pattern (Production): In production, the trusted relayer would be replaced by:

Chainlink Functions for automated score fetching
Decentralized validator network
Multi-signature oracle consensus
Time-delayed attestations

Documentation

ARCHITECTURE.md - Technical details
SECURITY.md - Security considerations
DEPLOYMENT.md - Deployment guide

Project Structure

ethos-reputation-launch/
├── src/
│   ├── ReputationNFT.sol              # Main soulbound NFT contract
│   ├── ReputationToken.sol            # ERC20 token for claims
│   │
│   ├── modules/
│   │   ├── EthosIntegration.sol       # Ethos score storage & retrieval
│   │   └── TierManager.sol            # Tier calculation logic
│   │
│   ├── interfaces/
│   │   ├── IReputationNFT.sol         # NFT contract interface
│   │   └── IEthosIntegration.sol      # Ethos module interface
│   │
│   └── types/
│       └── ReputationTypes.sol        # Enums (Tier)
│
├── test/
│   ├── unit/
│   │   ├── ReputationNFTTest.t.sol    # NFT core functionality
│   │   ├── ReputationTokenTest.t.sol  # Token claim logic
│   │   └── EthosIntegrationTest.t.sol # Score management
│   │
│   └── integration/
│       └── FullFlowTest.t.sol         # End-to-end scenarios
│
├── script/
│   ├── DeployReputationNFT.s.sol       # NFT deployment script
|   ├── DeployEthosIntegration.s.sol    # Ethos score deployment script. 
|   └── DeployReputationToken.s.sol     # Token deployment script
│
│
└── docs/
|    ├── ARCHITECTURE.md                # Technical deep dive
|    ├── DEPLOYMENT.md                  # Deployment guide
|    └── SECURITY.md                    # Security considerations
|
└── README.md                           # This File.

Quick Start

Prerequisites

Foundry installed
Base Sepolia testnet ETH (faucet)
Git for version control

Installation

# Clone the repository
git clone https://github.com/BuildsWithKing/ethos-reputation-launch.git
cd ethos-reputation-launch

# Install dependencies
forge install

# Compile contracts
forge build

Running Tests

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run specific test file
forge test --match-path test/unit/ReputationNFTTest.t.sol

# Check test coverage
forge coverage

# Gas snapshot
forge snapshot

Deployment (Base Sepolia)

# Set environment variables 
export PRIVATE_KEY=your_private_key
export BASE_SEPOLIA_RPC=your_rpc_url

# Deploy contracts
forge script script/DeployEthosIntegration.s.sol --rpc-url $BASE_RPC_URL --private-key $PRIVATE_KEY --broadcast --verify

forge script script/DeployReputationNFT.s.sol --rpc-url $BASE_RPC_URL --private-key $PRIVATE_KEY --broadcast --verify

forge script script/DeployReputationToken.s.sol --rpc-url $BASE_RPC_URL --private-key $PRIVATE_KEY --broadcast --verify


## Usage Guide

### For Contract Owners

**1. Deploy Contracts**
```solidity
// Deploy EthosIntegration contract 
ethosIntegration = new EthosIntegration(kingAddress_, adminAddress_);


// Deploy NFT contract
reputationNFT = new ReputationNFT(s_king, address(s_ethosIntegration), "Reputation Badge", "REPBADGE", 800, 1000, 1400);


// Deploy Token contract
reputationToken = new ReputationToken(s_king, address(s_reputationNFT), "Reputation Token", "REPTOKEN", 5000, 10000, 15000);

2. Set Reputation Scores

// Single score
ethosIntegraation.setEthosScore(userAddress, 1500); // Gold tier

// Batch scores (more efficient)
address[] memory users = new address[](3);
uint256[] memory scores = new uint256[](3);

users[0] = 0xAlice...;
scores[0] = 1500; // Gold

users[1] = 0xBob...;
scores[1] = 1100; // Silver

users[2] = 0xCharlie...;
scores[2] = 850; // Bronze

ethosIntegraation.setEthosScoreBatch(users, scores);

For Users

1. Check Your Score

uint256 myScore = reputationNFT.getEthosScore(msg.sender);
// Returns: 0 if not set, otherwise your score

2. Mint Your NFT

// Must have score ≥ 800 set by contract owner
reputationNFT.mint();
// Reverts if:
// - Already minted
// - Score not set
// - Score < 800

3. Claim Your Tokens

// Must own an NFT
reputationToken.claimTokens();
// Returns amount claimed based on tier

4. Check Claimable Amount

uint256 claimable = reputationToken.getClaimableAmount(msg.sender);
// Returns: 0 if already claimed or no NFT
//          15000, 10000, or 5000 based on tier

Testing Strategy

Unit Tests

✅ NFT minting with various score thresholds
✅ Soulbound enforcement (transfer reverts)
✅ Tier calculation accuracy
✅ Token claim logic
✅ One-time claim enforcement
✅ Access control (king-only functions)
✅ Edge cases (zero addresses, re-minting, etc.)

Integration Tests

✅ Full user journey: score → mint → claim
✅ Multiple users with different tiers
✅ Score updates after minting
✅ Contract interactions (NFT ↔ Token)

Coverage

Current test coverage: 98.71%

Security Considerations

What's Secure

✅ Soulbound Implementation: Transfers properly blocked via override pattern
✅ Reentrancy Protection: KingReentrancyGuard on critical functions
✅ Emergency Pause: Contract can be paused by the king on emergencies
✅ Access Control: King/Admin separation via Kingable module
✅ Emergency Migration: If user loses wallet, NFT can be moved by the king
✅ One-Time Claims: Mapping tracks NFT token IDs that claimed
✅ Input Validation: Zero checks, balance checks throughout

Known Limitations (Hackathon Version)

⚠️ Centralized Score Oracle: Contract owner and admin sets scores (trusted relayer pattern)
⚠️ No Score Updates: Once NFT minted, tier is locked (even if reputation changes)
⚠️ No Burning: NFTs are permanent

Production Recommendations

Decentralize oracle with Chainlink Functions
Add multi-sig for score setting
Add NFT burning for user privacy
Professional security audit before mainnet

Built With

Language: Solidity ^0.8.30
Framework: Foundry
Network: Base Sepolia (testnet)
Standards: ERC721 (NFT), ERC20 (Token) OpenZeppelin/openzeppelin-contracts
Security: BuildsWithKing Security Modules
Oracle Pattern: Trusted relayer (hackathon) → Chainlink (production)
Reputation: Ethos Network API

Hackathon Context

Event: Ethos Vibeathon 2026
Track: Net New Product (Build something entirely new using Ethos)
Timeline: Jan 19-22, 2026 (72 hours)
Goal: Demonstrate innovative use of Ethos reputation primitive

Why This Project?

Solves REAL problem (bot-farmed launches)
Uses Ethos in novel way (onchain reputation gates)
Shows technical depth (Solidity + oracle patterns)
Deployed on Base
Production-ready architecture (with noted limitations)

Roadmap

Phase 1: Hackathon MVP (Completed)

Phase 2: Post-Hackathon Improvements

Gas optimization pass
Frontend integration (wagmi + viem)
Subgraph for event indexing
Documentation expansion

Phase 3: Production Preparation

Chainlink Functions integration
Multi-sig governance
Professional security audit
Mainnet deployment (Base L2)

Phase 4: Ecosystem Integration

Launch platform partnerships
Cross-chain reputation bridges
DAO governance integration
Additional reputation sources

Additional Resources

Contributing

Contributions welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Test thoroughly (forge test)
Commit with clear messages (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Testing Requirements:

All new features must include tests
Maintain or improve test coverage
No breaking changes without discussion

License

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: Free to use, modify, and distribute. No warranty. Attribution appreciated but not required.

Author

Michealking

GitHub: @BuildsWithKing
Twitter: @BuildsWithKing
Discord: @BuildsWithKing

Acknowledgements

Ethos Network for hosting the vibeathon and building reputation infrastructure
Base for providing a fast, affordable L2 for deployment
OpenZeppelin for battle-tested smart contract standards
Foundry for the best Solidity development experience
Claude (Anthropic) for guidance during architecture planning
Web3 Community for inspiration and open-source contributions

Project Stats

Development Time: 72 hours (Jan 19-22, 2026)
Test Coverage: 98.71%
Lines of Code:
Contracts: 2 main + 2 modules

Demo

Video Demo: Video

Live Deployment

EthosIntegration Contract Address: 0x652493b15b707aEdd61A879f4d7520e8baF5Dc5E
ReputationNFT Contract Address: 0x3809bb0696881432a5be72e12FF730828B77269e
ReputationToken Contract Address: 0xB857087d4e23c6a281A3349C4beedD9C821A1425

Built for fairness. Secured by reputation. Powered by Base.

If you found this project helpful, consider:

⭐ Starring this repo
🐦 Sharing on Twitter
💬 Discussing in GitHub Issues
🤝 Contributing improvements

Together, we build a fairer Web3. 🌐

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
broadcast		broadcast
coverage		coverage
docs		docs
lib		lib
screenshot		screenshot
script		script
src		src
test		test
.gas-snapshot		.gas-snapshot
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
README.md		README.md
foundry.toml		foundry.toml
lcov.info		lcov.info

Folders and files

Latest commit

History

Repository files navigation

Ethos Reputation Launch

Table of Contents

The Problem

The Solution

Features

Soulbound NFTs (Non-Transferable)

Tiered Reputation System

Configurable Tier Thresholds

One-Time Claims

Security-First Design

Emergency Recovery

Design Decision: Snapshot-Based Reputation

Architecture

Contract Interactions

Documentation

Project Structure

Quick Start

Prerequisites

Installation

Running Tests

Deployment (Base Sepolia)

For Users

Testing Strategy

Unit Tests

Integration Tests

Coverage

Security Considerations

What's Secure

Known Limitations (Hackathon Version)

Production Recommendations

Built With

Hackathon Context

Roadmap

Phase 1: Hackathon MVP (Completed)

Phase 2: Post-Hackathon Improvements

Phase 3: Production Preparation

Phase 4: Ecosystem Integration

Additional Resources

Contributing

License

Author

Acknowledgements

Project Stats

Demo

Live Deployment

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages