Trust3 ID - Web3 Credit Score Protocol

Disclaimer: This is an experimental protocol for educational and research purposes. It is NOT financial advice, NOT a regulated credit reporting service, and NOT audited by a professional security firm. Smart contracts may contain bugs. Users deploy and use this software entirely at their own risk and are responsible for compliance with applicable local laws. See LICENSE for details.

A decentralized credit scoring system for Web3 wallets. Provides transparent, verifiable, and explainable on-chain reputation analysis with Soulbound Token (SBT) integration.

What Problem Does This Solve?

DeFi lending protocols require 150-200% collateral. Trust3 ID provides on-chain credit scores (0-100) so protocols can offer lower collateral to trustworthy users — like a FICO score for Web3.

Features

• Multi-dimensional Scoring — History, Wealth, Behavior, Identity, Risk, NFT, DeFi, and Time-Series analysis
• Sybil Detection — Automated detection of bot/farming wallets via funding patterns, behavior analysis, and temporal clustering
• EIP-712 Signatures — Cryptographically signed reports, verifiable on-chain
• Soulbound Token (SBT) — Non-transferable on-chain identity via ERC-721
• Multi-sig Governance — Decentralized validator consensus (OpenZeppelin ECDSA)
• Zero-Knowledge Proofs (Planned) — Privacy-preserving score verification via circom circuits (circuit designed, integration in progress)
• Multi-chain — Aggregates balances from Ethereum, Arbitrum, Optimism, Base, Polygon
• Multi-source Fallback — Etherscan → Alchemy → Infura with automatic failover
• Score History API — Track credit score changes over time
• AI Appeal Generator — Personalized appeal templates with improvement tips
• i18n — English, Chinese, Spanish

Quick Start

# Clone
git clone https://github.com/yourusername/trust3-id.git
cd trust3-id

# Install
npm install

# Configure
cp .env.example .env.local
# Edit .env.local — at minimum set ETHERSCAN_API_KEY and SIGNER_PRIVATE_KEY

# Database
npx prisma generate
npx prisma migrate dev

# Run
npm run dev

Open http://localhost:3000

API Endpoints

POST /api/analyze — Analyze a wallet

curl -X POST http://localhost:3000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

Response:

{
  "score": 85,
  "summary": "Excellent Credit: This address holds high-value NFT/DeFi assets...",
  "factors": [...],
  "radar": { "history": 90, "wealth": 80, "behavior": 75, "identity": 60, "risk": 95 },
  "signature": { "signatures": [...], "signerAddresses": [...] }
}

GET /api/score?address=0x... — Look up latest score (public, no auth)

GET /api/history?address=0x...&limit=10 — Score history over time

POST /api/verify-payment — Verify on-chain payment to unlock full report

Rate Limits

• Free: 3 req/min per IP, 5 req/5min per address
• API Key: configurable per organization

Architecture

Frontend (Next.js 16 + React 19)
    │
    ▼
API Layer (rate limiting, auth, validation)
    │
    ▼
Scoring Engine ──► 8 Scorers (History, Behavior, Risk, Identity, NFT, DeFi, TimeSeries, Sybil)
    │
    ├── Etherscan API (primary)
    ├── Alchemy API (fallback)
    ├── Infura API (fallback)
    ├── Moralis API (NFT/tokens)
    └── ENS (identity)
    │
    ▼
Smart Contracts (Solidity)
    ├── Trust3SBT.sol — Soulbound Token (ERC-721 + EIP-712)
    └── MultiSigAuthority.sol — Decentralized governance
    │
    ▼
ZK Circuits (circom) — Privacy-preserving score proofs

Project Structure

trust3-id/
├── app/
│   └── api/
│       ├── analyze/          # Main scoring endpoint
│       ├── score/            # Public score lookup
│       ├── history/          # Score history
│       └── verify-payment/   # Payment verification
├── lib/
│   ├── core/                 # Signer, scanner, types
│   ├── modules/
│   │   ├── explainability/   # Scoring engine + 7 scorers
│   │   ├── ai/               # Appeal text generator
│   │   └── sybil/            # Sybil attack detection
│   ├── datasources/          # Multi-source data fetcher
│   ├── auth/                 # API key management
│   └── config/               # App configuration
├── contracts/
│   ├── Trust3SBT.sol         # Soulbound Token
│   └── governance/
│       └── MultiSigAuthority.sol
├── circuits/
│   └── credit_score.circom   # ZK circuit
└── prisma/
    └── schema.prisma         # Database schema

Environment Variables

See .env.example for full list. Minimum required:

Variable	Required	Description
ETHERSCAN_API_KEY	Yes	Free at etherscan.io
SIGNER_PRIVATE_KEY	Yes	For EIP-712 signing
DATABASE_URL	Yes	SQLite by default
MORALIS_API_KEY	No	For NFT/token data
ALCHEMY_API_KEY	No	Fallback data source
PAYMENT_ADDRESS	No	Your receiving wallet

Smart Contract Deployment

# Compile
npx hardhat compile

# Deploy (edit scripts/deploy.ts with your config)
npx hardhat run scripts/deploy.ts --network mainnet

# Verify on Etherscan
npx hardhat verify --network mainnet DEPLOYED_ADDRESS

Deploy on Vercel

1. Push code to GitHub
2. Import in Vercel
3. Set environment variables
4. Deploy

Note: For Vercel, change DATABASE_URL to a hosted database (e.g., Turso, PlanetScale).

Development

npm run dev          # Development server
npm run build        # Production build
npm run type-check   # TypeScript check
npm run lint         # ESLint
npm run test         # Vitest
npx prisma studio    # Database GUI

Security

• Smart contracts use OpenZeppelin ECDSA (prevents signature malleability)
• abi.encode used instead of abi.encodePacked (prevents hash collisions)
• Score bounds validated on-chain (0-100)
• Transaction receipt verification for payments
• Multi-layer rate limiting
• API key authentication for B2B

Warning: This project has NOT been professionally audited. Do not use in production without a security audit.

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT