CrediFi — Undercollateralized Lending on HashKey Chain

CrediFi is a decentralized lending protocol combining on-chain smart contracts with off-chain credit scoring. Users borrow HSK from a shared liquidity pool by posting collateral; their required collateral ratio is determined by a credit score computed off-chain, signed via EIP-712, and verified on-chain. Lenders earn interest proportional to pool utilization; the protocol collects a treasury fee verified through HSP (HashKey Settlement Protocol).

Architecture

Smart Contracts (Solidity 0.8.24):

• CrediFiOracle: Verifies EIP-712 signatures, stores nonces (replay protection), and tier thresholds
• CrediFiPool: Manages borrow/repay/liquidate logic, interest accrual (linear per block), collateral, and fee distribution

Backend (Node.js + TypeScript):

• Dual-network indexer: Simultaneously indexes testnet (chainId 133) and mainnet (chainId 177) with separate state tracking
• EIP-712 score signer: Computes wallet credit score from on-chain history (age, transactions, repayment history, asset diversity), signs via relayer key
• Per-network contract accessors: Allows read-only endpoints to hit either network; indexer stays bound to env-configured network
• HSP integration: Fire-and-forget USDC settlement verification for treasury fees (non-blocking; failures don't stall indexer)

Frontend (React 19 + wagmi + RainbowKit):

• NetworkSwitcher: Runtime network selection syncs wallet connection and API routes
• Real-time state: TanStack Query + useWalletQueries for live pool stats, user scores, and loan positions
• Borrow flow: Sign score → submit via relayer → borrow with signed score + collateral

Quick Start

# Backend (dual-network indexing + API)
cd backend
npm install
npx prisma migrate deploy
npx prisma generate
npm run dev

# Frontend (React dev server)
cd frontend
npm install
npm run dev

Backend: http://localhost:3001/api/status
Frontend: http://localhost:5173

HashKey Settlement Protocol (HSP) Integration

HSP provides off-chain, verifiable USDC settlement verification for CrediFi's treasury fees. When users repay loans, the Pool emits a Repaid event with the treasury fee amount. The backend indexer listens for this event and simultaneously initiates an HSP settlement: a verifiable, signed mandate that records the fee payment in HSP's USDC settlement layer.

How it works:

• On-chain: Pool collects treasury fee (25% of accrued interest) in HSK
• Off-chain: Backend fires a fire-and-forget HSP settlement request (non-blocking; HSP slowness never stalls the indexer)
• Verification: GET /api/hsp/settlements returns a paginated list of all treasury fee settlements with their HSP status and proof links
• Idempotency: Each settlement is keyed by repayTxHash, so re-running the indexer over the same block range doesn't double-settle

Configuration (backend .env):

HSP_COORDINATOR_URL=https://hsp-coordinator.hashkeymerchant.com
HSP_API_KEY=<your-hsp-api-key>
HSP_PRIVATE_KEY=0x<hsp-signer-key>
TREASURY_HSP_PAYOUT_ADDRESS=0x<recipient-wallet>
HSP_CHAIN=hashkey-testnet|hashkey-mainnet

Role in the protocol: HSP adds a compliance layer — treasury fees are simultaneously recorded on-chain (Pool accounting) and off-chain (HSP settlement), creating dual proof of treasury health. This is especially useful for audits, regulatory reporting, and cross-chain fee reconciliation. For local dev, you can set dummy HSP values; the backend gracefully handles HSP unavailability (fees still accrue on-chain).

Key API Endpoints

• GET /api/status — protocol health, indexer state
• GET /api/pool/stats?network=testnet|mainnet — pool TVL, utilization, APY per network
• GET /api/score/:address — user's current score, tier, factor breakdown
• POST /api/score/:address/sign?network=testnet|mainnet — backend signs score (EIP-712) and returns bundle
• POST /api/score/:address/submit?network=testnet|mainnet — relayer broadcasts signed score on-chain
• GET /api/loan/:address/active?network=testnet|mainnet — active loan details
• GET /api/hsp/settlements — treasury fee settlement history (HSP Coordinator)

Deployments

Network	ChainId	Oracle	Pool
Testnet	133	0x6345Ec7861cDCf8798F5D40348d91Cdbe077544B	0x0bFeE39682e4a5CA057A33838d06Ca7b43bF42Cc
Mainnet	177	0x0Babe379A92d4e429cBEd99148D849bc76140428	0xee52772820cA14022668708C62F11CE02819020a

Score Tiers & Collateral Ratios

Tier	Score Range	Collateral Ratio
A	800–1000	50%
B	650–799	80%
C	450–649	120%
D	0–449	150%

Configuration

Backend .env example:

HSK_RPC_URL=https://mainnet.hsk.xyz
CHAIN_ID=177
ORACLE_ADDRESS=0x0Babe379A92d4e429cBEd99148D849bc76140428
POOL_ADDRESS=0xee52772820cA14022668708C62F11CE02819020a
RELAYER_PRIVATE_KEY=0x...
HSP_COORDINATOR_URL=https://...
HSP_API_KEY=...
HSP_PRIVATE_KEY=0x...
TREASURY_HSP_PAYOUT_ADDRESS=0x...
DATABASE_URL=postgresql://...

Defaults: Backend serves mainnet by default (override with env vars); frontend NetworkSwitcher allows runtime selection. Multi-network indexers run independently; each maintains separate block state. HSP integration is optional for local dev (set dummy values in .env.example).

Development Notes

• Indexer: backend/src/indexer/indexer-multi.ts spawns parallel loops for testnet and mainnet; each queries per-network RPC and maintains separate state
• Score signing: backend/src/score/sign.ts includes network in EIP-712 domain (chainId + verifyingContract from per-network oracle address)
• Prisma schema: Score and IndexerState models track network; queries filter by network to isolate per-chain data
• Frontend queries: All sensitive requests (sign, submit, borrow) include ?network= param; read-only endpoints (pool stats) also support it

See contracts/README.md for contract architecture and deployment instructions.