On-chain identity is broken. Wallets are anonymous. There is no way to distinguish a DeFi power user from a fresh wallet. This protocol fixes that.

The ERC-5484 Reputation System assigns every wallet a Soulbound Token — non-transferable, non-mintable by the holder — that reflects their on-chain behaviour score. As the wallet performs positive actions (DAO votes, loan repayments, airdrop holding), their score rises and their medal art upgrades automatically with no re-mint required.

The scoring engine is UUPS upgradeable — logic can evolve as the protocol matures. The token contract is intentionally immutable — SBT ownership records are the ground truth of on-chain identity and must be permanent.

1. 🌐 Frontend App
2. 🏛️ Architecture
3. ✅ Deployed Contracts
4. 🎖️ Reputation Tiers & Medal System
5. ⚙️ Scoring Actions
6. 🧩 Smart Contract Breakdown
7. 🧪 Testing Strategy
8. 🚀 Local Setup

A production-grade Web3 frontend ships alongside the protocol, deployed live at rst-reputation-protocol.vercel.app.

• Live reputation dashboard — real-time score, tier, voting power, and loan access pulled directly from contracts
• Dynamic SBT medal display — on-chain SVG decoded and rendered from tokenURI() with no IPFS
• All vault actions wired — castVote, submitProposal, mintNFT, takeLoan, repayLoan, claimAirdrop, settleAirdrop — all executable from the UI
• Live cooldown bars — per-action countdown timers that update every second
• 30-day airdrop progress bar — visual hold tracker with early-settle warning
• Animated tier showcase — auto-cycles through all 5 tiers with cinematic morph transitions
• Scroll-reveal sections — intersection observer based section animations
• Particle canvas background — same as landing page, with comet trails

cd web3-app
npm install
npm run dev

Requires MetaMask or any RainbowKit-supported wallet connected to Sepolia Testnet.

The system is split into three layers with clear separation of concerns:

┌─────────────────────────────────────────────────────┐
│                     USER / DAPP                      │
│         Wagmi v2 · Viem · RainbowKit (Frontend)      │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│              REPUTATION VAULT                        │
│   castVote() · takeLoan() · claimAirdrop() · ...     │
│   12h / 24h cooldowns · CEI strict · nonReentrant    │
└────────────────────┬────────────────────────────────┘
                     │ recordAction()
┌────────────────────▼────────────────────────────────┐
│         REPUTATION ENGINE  (UUPS Proxy)              │
│   Score calculation · Tier resolution · SBT issuer   │
│   ReputationMath library · Storage gap pattern       │
└──────────┬──────────────────────────────────────────┘
           │ issue() / burn()
┌──────────▼──────────────────────────────────────────┐
│         REPUTATION TOKEN  (Immutable)                │
│   ERC-5484 Soulbound · On-chain SVG medals           │
│   _update() transfer lock · ERC-165 registered       │
└─────────────────────────────────────────────────────┘

All contracts deployed and verified on Ethereum Sepolia Testnet.

Interact with the proxy address only — never the implementation directly.

Every wallet's SBT displays a dynamic on-chain SVG medal that reflects their current tier. No IPFS. No centralized server. The medal art is generated entirely in Solidity and upgrades automatically as score increases.

Actions are recorded through the ReputationVault. Each action maps to a signed score delta enforced by the ReputationMath library. Raw deltas are never exposed — only the Action enum is accessible to callers.

Score is always clamped to [0, 1000]. Underflow and overflow are impossible by design.

src/
├── ReputationToken.sol       # ERC-5484 SBT — immutable, transfer-locked
├── ReputationEngine.sol      # UUPS scoring engine — issues SBTs, tracks scores
├── ReputationVault.sol       # Action simulator — user entry point
├── interfaces/
│   ├── IReputationToken.sol  # Full error + event surface for callers
│   └── IReputationEngine.sol # CEI order + reentrancy requirements documented
└── libraries/
    ├── ReputationMath.sol    # Pure math — Action enum, score clamping, tier resolution
    └── ReputationSVG.sol     # On-chain SVG medal generator — 5 tier designs

• Enum-gated deltas — arbitrary int256 deltas are never exposed. Only Action enum variants can mutate scores.
• Overflow guards — _applyDelta() has early-exit guards for extreme deltas, future-proofing against new high-magnitude actions.
• Single guard pattern — _assertValidScore() is called once per public entry point. _resolveTierUnchecked() avoids a double-guard in tierName().
• Zero state — pure library. Zero reentrancy surface.

The project uses a 4-layer testing approach with Foundry.

test/
├── unit/
│   ├── ReputationMathTest.t.sol    # Score math, tier resolution, delta clamping
│   ├── ReputationTokenTest.t.sol   # SBT issuance, transfer lock, burn, ERC-5484
│   ├── ReputationEngineTest.t.sol  # recordAction CEI, auth, score updates
│   └── ReputationVaultTest.t.sol   # All actions, cooldowns, loan/airdrop lifecycle
├── integration/
│   └── ReputationFlowTest.t.sol    # Full lifecycle: Unranked → Bronze → Gold
└── fuzz/
    └── FuzzReputation.t.sol        # Score bounds, loan math, SBT uniqueness

• Score never exceeds 1000 — fuzz tested across 50+ random action sequences
• Score never underflows to negative — loan default on zero score → still zero
• Cooldown enforcement — exact timestamp boundary testing
• Diamond hands vs paper hands — airdrop held 30d vs immediate settle
• CEI verification — mock engine tracks call order in vault tests
• SBT uniqueness — fuzz tested across random wallet addresses

# Full suite
forge test -v

# Vault tests only
forge test --match-contract ReputationVaultTest -vvvv

# Fuzz tests
forge test --match-path test/fuzz/* -vvvv

• Foundry (nightly)
• Node.js 18+ (for frontend)
• Git

git clone https://github.com/NexTechArchitect/ERC-5484.git
cd ERC-5484

forge install OpenZeppelin/openzeppelin-contracts --no-commit
forge install OpenZeppelin/openzeppelin-contracts-upgradeable --no-commit
forge install foundry-rs/forge-std --no-commit

Create a .env file:

PRIVATE_KEY=0x...
DEPLOYER_ADDRESS=0x...
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
ETHERSCAN_API_KEY=...

forge build
forge test -v

# Deploy to Sepolia
source .env && forge script script/DeployReputation.s.sol:DeployReputation \
  --rpc-url $SEPOLIA_RPC_URL --broadcast --verify -vvvv

cd web3-app
npm install
npm run dev
# → http://localhost:3000

Connect any RainbowKit-supported wallet to Sepolia Testnet to interact.

This repository is for educational and portfolio purposes. The smart contracts implement production-grade patterns and have been thoroughly self-audited, but have not undergone a formal external security audit. Do not use with real funds without a professional security review.