CrediFi Documentation

Complete guide to CrediFi's architecture, smart contracts, backend APIs, and how everything works together.

Architecture

Smart Contracts

Two core contracts on HashKey Chain: CrediFiOracle verifies EIP-712 signatures and stores nonces; CrediFiPool manages borrow/repay/liquidate logic.

Learn more

Backend API

Dual-network indexer for testnet/mainnet, EIP-712 score signing, per-network contract accessors, and HSP integration for treasury settlement verification.

API Reference

Frontend

React 19 + wagmi + RainbowKit. Network-aware UI, real-time state via TanStack Query, borrow/lend/repay flows.

Frontend Guide

Smart Contracts

CrediFiOracle

Verifies EIP-712 signatures, stores per-wallet nonces for replay protection, and computes credit tiers from scores. Prevents the backend from lying about tier independently of score.

address: 0x0Babe379A92d4e429cBEd99148D849bc76140428

(Mainnet, chainId 177)

CrediFiPool

Manages pooled lending: lenders deposit HSK and earn shares; borrowers post collateral and borrow at tier-based ratios. Interest accrues linearly per block (8% APR), split 75% to lenders, 25% to treasury.

address: 0xee52772820cA14022668708C62F11CE02819020a

(Mainnet, chainId 177)

Backend API

All endpoints support dual-network queries via ?network=testnet|mainnet. Defaults to env-configured network.

GET /api/status

Protocol health, indexer state, configured network.

GET /api/pool/stats?network=testnet|mainnet

Pool TVL, utilization, APY per network.

GET /api/score/:address

User's current score, tier, factor breakdown, and recent history.

POST /api/score/:address/sign?network=testnet|mainnet

Backend signs score (EIP-712) and returns bundle with signature.

POST /api/score/:address/submit?network=testnet|mainnet

Relayer broadcasts signed score on-chain via CrediFiOracle.

GET /api/loan/:address/active?network=testnet|mainnet

Active loan details (principal, collateral, tier, health factor).

GET /api/hsp/settlements

Treasury fee settlements with HSP status and proof links.

Credit Scoring

Scores are computed off-chain from on-chain history, signed via EIP-712, and verified on-chain. The score determines your credit tier, which sets your collateral ratio.

Tier	Score Range	Collateral Ratio	Terms
A	800–1000	50%	Best
B	650–799	80%	Good
C	450–649	120%	Fair
D	0–449	150%	Entry-level

Scoring factors: Wallet age (20%), transaction activity (25%), repayment history (35%), asset diversity (20%). Liquidations incur a 25-point penalty per event.

Networks

HashKey Chain Testnet

Chain ID: 133

Oracle: 0x6345Ec7861c...

Pool: 0x0bFeE39682e...

RPC: https://testnet.hsk.xyz

HashKey Chain Mainnet

Chain ID: 177

Oracle: 0x0Babe379A92d...

Pool: 0xee52772820c...

RPC: https://mainnet.hsk.xyz

Development

Getting Started

Backend and frontend run independently. Start both:

# Backend (port 3001)
cd backend
npm install
npx prisma migrate deploy
npm run dev

# Frontend (port 5173)
cd frontend
npm install
npm run dev

Dual-Network Indexing

The backend runs independent indexer loops for both testnet and mainnet in parallel. Each maintains separate block state. The env-bound indexer is kept for backward compatibility; new endpoints accept ?network= to query either network.

Configuration

Backend env variables required:

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