🛡️ ERC-5484 On-Chain Reputation System

Soulbound Identity · Dynamic NFT Medals · UUPS Upgradeable Engine

A fully on-chain reputation protocol built on ERC-5484 Soulbound Tokens.
Wallet behaviour tracked on-chain. Score evolves. Medal art upgrades automatically. No IPFS dependency.

🌐 Live Demo • 💻 Source Code • 🔗 ReputationToken • 🔗 Engine Proxy • 🔗 ReputationVault

---

🦅 Executive Summary

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.

---

📑 Table of Contents

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

---

Features

• 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

Key Design Decisions

Decision	Rationale
Token is immutable	SBT ownership is ground truth — upgradeability would allow silent record tampering
Engine is UUPS upgradeable	Scoring logic must evolve; token state must not
On-chain SVG medals	Zero IPFS dependency — token lives as long as Ethereum
Dynamic metadata	tokenURI() reads live score from engine — medal upgrades on score change, no re-mint
_mint not _safeMint	SBTs have no receiver contract — onERC721Received is meaningless and adds reentrancy surface
_update() override	Exhaustively blocks all OZ transfer paths in one hook

---

✅ Deployed Contracts

All contracts deployed and verified on Ethereum Sepolia Testnet.

Contract	Address	Etherscan
ReputationToken	0x9c77Ce31a110e360d62e4eF8B1F4cf8576F70F46	🔎 View
ReputationEngine (Impl)	0xC81532619d5fB4728932A43A77Bfea04c3df5957	🔎 View
ReputationEngine (Proxy)	0x4eFC1adc7Dd594C4bB04865B6dCc5101392FaBD8	🔎 View
ReputationVault	0xd53320CDEF6f3DfA54436D2806e765d6d6bD98b6	🔎 View

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

---

🎖️ Reputation Tiers & Medal System

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.

Tier	Score Range	Medal Design	Voting Power	Loan Limit
Unranked	0 – 99	Grey hexagon + ?	0.5×	None
Bronze 🥉	100 – 299	Copper circle + 6-point star	1×	20% of collateral
Silver 🥈	300 – 599	Silver circle + 5-point star	1.5×	40% of collateral
Gold 🥇	600 – 849	Gold circle + crown + gems	2×	60% of collateral
Platinum 💎	850 – 1000	Platinum ring + diamond	3×	80% of collateral

---

⚙️ Scoring Actions

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.

Action	Function	Score Delta	Cooldown
DAO Vote	castVote()	+10	12 hours
DAO Proposal	submitProposal()	+25	24 hours
Loan Repaid	repayLoan()	+30	None (natural gate)
Loan Defaulted	markDefault()	−50	None (owner only)
Airdrop Held 30d	settleAirdrop()	+15	None (natural gate)
Airdrop Dumped	settleAirdrop()	−20	None (natural gate)
NFT Minted	mintNFT()	+5	12 hours

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

---

🧩 Smart Contract Breakdown

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

ReputationMath Library — Audit Highlights

• 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.

Security Invariants

Invariant	Enforced By
One SBT per wallet	s_walletToToken[to] != 0 check in issue()
Engine address immutable post-deploy	setEngine() reverts with EngineAlreadySet on second call
Transfer always reverts	_update() override — catches all OZ paths
Score always in [0, 1000]	ReputationMath.applyAction() — clamped by design
All storage writes before external calls	Strict CEI in recordAction() and all Vault functions
No re-entrancy	nonReentrant on all state-changing engine + vault functions
SBT auto-issued on first action	token.issue() called last in CEI — after all storage writes

---

🧪 Testing Strategy

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

Run Tests

# Full suite
forge test -v

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

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

---

Frontend

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

Engineered by NexTech Architect

🌐 Live Demo · Connect on 𝕏

Smart Contract Developer · Solidity · Foundry · Web3 Engineering