MicroLend - Decentralized Micro-Lending Platform

A complete full-stack decentralized micro-lending platform combining blockchain technology, AI-powered risk assessment, and modern web technologies. Built for HackWithStack Hackathon by Team MicroLend.

🌟 Overview

MicroLend is a peer-to-peer lending platform that enables borrowers to request loans and lenders to fund them through Ethereum smart contracts. The platform features AI-driven risk assessment, explainable AI insights, user authentication, and a modern responsive interface.

✨ Features

🔗 Blockchain Features

💰 Loan Requests - Create loan requests with custom amount, interest rate, duration, and purpose
🤝 Loan Funding - Lenders can fund loans directly through smart contracts
💸 Loan Repayment - Automatic interest calculation and repayment tracking
📊 Risk Scoring - ML-powered risk assessment (0-100 scale)
⭐ Reputation System - On-chain reputation tracking for borrowers
🛡️ Security - ReentrancyGuard, Ownable pattern, comprehensive input validation
📢 Event Emissions - Complete transparency with blockchain events
💼 Escrow System - Secure fund holding in smart contract

🤖 AI & ML Features

🧠 Machine Learning Risk Assessment - LightGBM model for credit scoring
🔍 Explainable AI - SHAP (SHapley Additive exPlanations) for feature importance
🗣️ Natural Language Explanations - Gemini AI generates human-readable risk assessments
📊 Feature Importance - Shows which factors (income, age, employment) impact risk most
🎯 Auto Risk Calculation - Automatic risk score generation during borrower signup
💡 AI Insights - Lenders see detailed AI explanations for each loan opportunity

🔐 Authentication & User Management

👤 User Registration - Secure signup with user type selection (borrower/lender)
🔑 JWT Authentication - Token-based authentication with 7-day expiration
📝 User Profiles - Editable profiles with financial information
🔒 Password Hashing - Secure password storage with Werkzeug
💾 MongoDB Storage - User data and financial profiles stored in MongoDB Atlas
🔄 Session Persistence - Remember me functionality with localStorage

🎨 Frontend Features

📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile
🎯 Role-Based Dashboards - Separate interfaces for borrowers and lenders
📊 Real-Time Stats - Live portfolio metrics and loan statistics
🔄 Auto-Refresh - Real-time updates from blockchain
🎨 Modern UI - Clean, intuitive interface with TailwindCSS
⚡ Fast Performance - Built with Vite for optimal speed
🌈 Color-Coded Status - Visual indicators for loan states and risk levels
📋 Two-Column Layout - Enhanced visibility for investments and opportunities (lender)
📑 Two-Column Grid - Organized loan cards for better overview (borrower)

📸 Application Screenshots

Landing Page

The homepage welcomes users with a clean interface and easy access to sign up or log in.

Borrower Dashboard

Borrowers can view all their loans, track repayment status, and manage their loan requests.

Lender Dashboard - Investments

Lenders can track their active investments, earnings, and portfolio performance in the left column.

Lender Dashboard - Opportunities

The right column shows available loan opportunities with risk scores and potential earnings.

AI Analytics Feature

Explainable AI provides detailed risk analysis showing which factors impact the borrower's credit score.

Profile Management

Users can update their financial information, which is used for risk assessment calculations.

Loan Request Form

Borrowers can create new loan requests with custom terms including amount, interest rate, and duration.

Loan Details Modal

Detailed view of loan information including terms, repayment schedule, and current status.

🚧 Challenges We Ran Into

MetaMask Transaction Signing Issues: Initially struggled with ethers.js v6 breaking changes. The switch from signer.sendTransaction() to contract method calls required restructuring our Web3 provider initialization.

SHAP Integration with Flask: The SHAP LinearExplainer required specific numpy array formatting. We solved this by preprocessing user input to match the exact feature order and data types expected by our LightGBM model.

MongoDB Atlas Connection Timeouts: Intermittent connection drops during JWT authentication. Fixed by implementing connection pooling and proper error handling with automatic reconnection logic.

Smart Contract Gas Optimization: Our initial MicroLending contract exceeded gas limits for loan creation. We optimized by removing redundant storage operations and using events instead of storing detailed loan histories on-chain.

Cross-Origin CORS Conflicts: React frontend couldn't communicate with Flask backend during local development. Resolved by configuring Flask-CORS with specific origins and credential handling.

Gemini API Rate Limiting: Hit API limits when generating explanations for multiple loans. Implemented caching for risk explanations and graceful fallback to SHAP-only mode when API is unavailable.

Each challenge taught us valuable lessons about blockchain development, ML integration, and building production-ready full-stack applications.

️ Tech Stack

Frontend

React 18 - Modern UI library
Vite - Lightning-fast build tool
TailwindCSS - Utility-first styling
Ethers.js v6 - Ethereum interaction
React Router - Client-side routing
Lucide React - Beautiful icons

Backend

Flask - Python web framework
PyMongo - MongoDB driver
Flask-CORS - Cross-origin support
JWT - Token authentication
Werkzeug - Password hashing

Machine Learning

LightGBM - Gradient boosting model
SHAP - Explainable AI library
Scikit-learn - Data preprocessing
NumPy - Numerical computing
Google Gemini AI - Natural language generation

Blockchain

Hardhat 3.x - Development environment
Solidity ^0.8.20 - Smart contract language
OpenZeppelin - Security contracts
Ethers.js - Blockchain interaction

Database

MongoDB Atlas - Cloud database

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v16 or higher) & npm
Python 3.x (3.8 or higher)
Git - Version control
MetaMask - Browser extension for Ethereum wallet
MongoDB Atlas Account - Free tier is sufficient

🚀 Complete Setup Guide

Step 1: Clone the Repository

git clone https://github.com/aayushhh-operator/HackWithStack_LogicLooms.git
cd HackWithStack_LogicLooms-contracts

Step 2: Backend Setup

2.1 Install Python Dependencies

cd backend
pip install -r requirements.txt

2.2 Configure Environment Variables

The .env file should already exist in the backend/ folder with:

MONGODB_URI=your_mongodb_connection_string
SECRET_KEY=your_jwt_secret_key
GEMINI_API_KEY=your_gemini_api_key  # Optional, for AI explanations

Important:

Replace your_mongodb_connection_string with your MongoDB Atlas connection string
Change your_jwt_secret_key to a secure random string
Get Gemini API key from Google AI Studio (optional)

2.3 Verify ML Model

Ensure risk_model (1).pkl exists in the backend/ folder. This is the trained LightGBM model.

Step 3: Smart Contract Setup

3.1 Install Contract Dependencies

cd ../contracts
npm install

3.2 Compile Contracts

npx hardhat compile

Step 4: Frontend Setup

4.1 Install Frontend Dependencies

cd ../frontend
npm install

Step 5: MetaMask Configuration

Install MetaMask browser extension if not already installed
Create or import a wallet
Add Hardhat Local Network:
- Open MetaMask → Settings → Networks → Add Network
- Network Name: Hardhat Local
- RPC URL: http://127.0.0.1:8545
- Chain ID: 1337
- Currency Symbol: ETH

🎬 Starting the Application

You need to run 4 separate terminal windows simultaneously:

Terminal 1: Start Hardhat Blockchain Node

cd contracts
npx hardhat node

What this does:

Starts local Ethereum blockchain on port 8545
Provides 20 test accounts with 10,000 ETH each
Keep this running - don't close the terminal

Copy one of the private keys shown - you'll need it for MetaMask.

Terminal 2: Deploy Smart Contract

Wait for Terminal 1 to be fully running, then in a new terminal:

cd contracts
npx hardhat ignition deploy ignition/modules/MicroLending.js --network localhost

What this does:

Deploys MicroLending contract to local blockchain
Shows contract address (save this)
Creates deploymentInfo.json with contract details

Note: If you restart the Hardhat node (Terminal 1), you must re-deploy the contract.

Terminal 3: Start Backend Server

cd backend
python app.py

What this does:

Starts Flask server on port 5000
Loads ML model and SHAP explainer
Configures Gemini AI (if API key provided)
Connects to MongoDB

You should see:

✓ ML Model loaded successfully
✓ SHAP Explainer configured
✓ Gemini AI configured (or warning if no API key)
* Running on http://127.0.0.1:5000

Terminal 4: Start Frontend Development Server

cd frontend
npm run dev

What this does:

Starts Vite dev server on port 5173
Enables hot module replacement
Provides local and network URLs

You should see:

VITE v5.x.x  ready in xxx ms
➜  Local:   http://localhost:5173/
➜  Network: http://192.168.x.x:5173/

🎮 Using the Application

1. Import Test Account to MetaMask

Open MetaMask
Click account icon → Import Account
Paste a private key from Terminal 1 (Hardhat node output)
Switch to Hardhat Local network

2. Create Your Account

Navigate to http://localhost:5173
Click "Get Started" or "Sign Up"
Fill in registration form:
- Name, Email, Password, Phone
- Age (used for risk calculation)
- Annual Income (in USD)
- Employment Length (in years)
- Select user type: Borrower or Lender
Click "Sign Up"
Risk score is automatically calculated on signup

3. Login

Use your email and password
Check "Remember me" to save email
Click "Login"

4. Connect Wallet

On Dashboard, click "Connect Wallet"
MetaMask will pop up
Select your imported account
Click "Connect"

5. As a Borrower

Request a Loan

Click "Request Loan" button
Fill in loan details:
- Amount (in ETH, e.g., 0.5)
- Interest Rate (%, e.g., 10)
- Duration (days, e.g., 30)
- Purpose (optional description)
Click "Submit Request"
Confirm transaction in MetaMask
Wait for transaction confirmation

View Your Loans

My Loans section shows all your loan requests
Status indicators:
- 🟡 Pending - Waiting for lender
- 🟢 Funded - Money received, needs repayment
- ⚪ Repaid - Fully paid back

Repay a Loan

Find a Funded loan
Click "Repay Now"
Confirm repayment amount (principal + interest)
Approve transaction in MetaMask

6. As a Lender

View Opportunities

Available Opportunities section lists all pending loans
Each opportunity shows:
- Loan amount and interest rate
- Borrower's risk score
- Expected return
- Duration and purpose

Get AI Insights

Find a loan opportunity
Click "View AI Risk Analysis"
Review:
- AI Explanation - Natural language assessment
- Key Risk Factors - Top 3 factors with impacts
- Feature Importance - Which borrower attributes matter most
- Recommendation - AI-based investment suggestion

Fund a Loan

Review loan details and AI insights
Click "Fund Loan"
Confirm amount in MetaMask
Approve transaction
Loan moves to your My Investments section

Monitor Investments

My Investments (left column) shows funded loans
Track progress bars
View expected returns
Monitor due dates

7. Profile Management

Click "Profile" in navigation
Update financial information:
- Age
- Annual Income
- Employment Length
Changes affect risk score
Click "Save Changes"

📊 Understanding Risk Scores

Risk Score Range

0-29: 🟢 Low Risk - Highly recommended
30-59: 🟡 Medium Risk - Moderate caution
60-100: 🔴 High Risk - Careful consideration needed

Risk Factors

The ML model considers 7 key features:

Age - Older borrowers typically lower risk
Income - Higher income = better repayment capacity
Employment Length - Longer employment = stability
Loan Amount - Higher amounts = higher risk
Interest Rate - Market signal of risk
Percent of Income - Loan amount as % of income
Credit History Length - Calculated as (Age - 18)

AI Explanations

SHAP Values show feature importance
Positive impact (🟢) - Factor decreases risk
Negative impact (🔴) - Factor increases risk
Impact % - Relative importance of each factor

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    User (Browser)                        │
│              MetaMask + React Frontend                   │
└─────────────────────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Flask API   │  │   Ethers.js  │  │  Hardhat     │
│  (Port 5000) │  │   Web3       │  │  Node        │
│              │  │   Context    │  │  (Port 8545) │
└──────────────┘  └──────────────┘  └──────────────┘
        │                                    │
        ▼                                    ▼
┌──────────────┐                   ┌──────────────┐
│   MongoDB    │                   │ MicroLending │
│   Atlas      │                   │ Smart        │
│   (Users)    │                   │ Contract     │
└──────────────┘                   └──────────────┘
        │
        ▼
┌──────────────┐
│   ML Model   │
│  LightGBM    │
│  + SHAP      │
└──────────────┘

Data Flow

User Authentication: Frontend → Flask API → MongoDB
Loan Operations: Frontend → Ethers.js → MetaMask → Smart Contract
Risk Assessment: Flask API → ML Model → SHAP → Gemini AI
Real-time Updates: Smart Contract Events → Frontend Updates

📁 Project Structure

MicroLend/
│
├── backend/                          # Flask Backend
│   ├── app.py                        # Main Flask application
│   ├── requirements.txt              # Python dependencies
│   ├── .env                          # Environment variables
│   └── risk_model (1).pkl            # Trained ML model
│
├── contracts/                        # Smart Contracts
│   ├── contracts/
│   │   ├── MicroLending.sol          # Main lending contract
│   │   └── Counter.sol               # Example contract
│   ├── ignition/
│   │   └── modules/
│   │       └── MicroLending.js       # Deployment module
│   ├── test/
│   │   └── MicroLending.test.js      # Contract tests
│   ├── hardhat.config.js             # Hardhat configuration
│   ├── deploymentInfo.json           # Deployed contract info
│   └── package.json                  # Node dependencies
│
├── frontend/                         # React Frontend
│   ├── src/
│   │   ├── components/               # Reusable components
│   │   ├── contexts/
│   │   │   ├── AuthContext.jsx       # Authentication state
│   │   │   └── Web3Context.jsx       # Blockchain state
│   │   ├── hooks/
│   │   │   └── useLoan.jsx          # Loan operations hook
│   │   ├── pages/
│   │   │   ├── LandingPage.jsx      # Homepage
│   │   │   ├── Login.jsx            # Login page
│   │   │   ├── Signup.jsx           # Registration page
│   │   │   ├── Profile.jsx          # User profile
│   │   │   ├── BorrowerDashboard.jsx # Borrower interface
│   │   │   └── LenderDashboard.jsx  # Lender interface
│   │   ├── App.jsx                  # Main app component
│   │   └── index.css                # Global styles
│   ├── package.json                 # Frontend dependencies
│   └── vite.config.js               # Vite configuration
│
├── MDs/                             # Documentation
│   ├── EXPLAINABLE_AI_COMPLETE.md   # AI features guide
│   ├── LAYOUT_ENHANCEMENT.md        # UI improvements
│   ├── METAMASK_GUIDE.md            # Wallet setup
│   └── QUICK_REFERENCE.md           # Quick commands
│
└── README.md                        # This file

🧪 Testing

Smart Contract Tests

cd contracts
npx hardhat test

Tests include:

Loan request creation
Loan funding
Loan repayment
Risk score calculation
Access control
Edge cases

Manual Testing Checklist

🐛 Troubleshooting

Common Issues

1. MetaMask Connection Failed

Problem: Can't connect wallet

Solutions:

Ensure MetaMask is installed
Check you're on Hardhat Local network (Chain ID 1337)
Refresh page and try again
Check browser console for errors

2. Transaction Fails

Problem: Transaction reverts or fails

Solutions:

Ensure you have enough ETH for gas
Check contract is deployed (Terminal 2 output)
Verify you're on correct network
Check account has sufficient balance

3. Backend Not Loading

Problem: Flask server errors

Solutions:

Check MongoDB connection string in .env
Verify Python dependencies installed: pip install -r requirements.txt
Check ML model file exists: risk_model (1).pkl
Look for port conflicts (port 5000)

4. Frontend Won't Start

Problem: Vite dev server errors

Solutions:

Delete node_modules and reinstall: npm install
Clear Vite cache: rm -rf node_modules/.vite
Check port 5173 is available
Verify all dependencies installed

5. AI Explanations Not Working

Problem: Risk analysis shows error

Solutions:

Add Gemini API key to backend/.env
SHAP still works without Gemini (shows feature importance only)
Check backend logs for specific errors
Verify ML model loaded successfully

6. Contract Not Found

Problem: "Contract not deployed" error

Solutions:

Restart Hardhat node (Terminal 1)
Re-deploy contract (Terminal 2)
Check deploymentInfo.json exists
Verify contract address in logs

📚 Additional Documentation

EXPLAINABLE_AI_COMPLETE.md - Complete AI features guide
EXPLAINABLE_AI_SUMMARY.md - Quick AI overview
LAYOUT_ENHANCEMENT.md - UI/UX improvements
METAMASK_GUIDE.md - Detailed wallet setup

🔑 Smart Contract Functions

Public Functions

// Request a new loan
requestLoan(uint256 amount, uint256 interestRate, uint256 duration, string purpose)

// Fund an existing loan
fundLoan(uint256 loanId) payable

// Repay a funded loan
repayLoan(uint256 loanId) payable

// Get loan details
getLoan(uint256 loanId) returns (Loan)

// Calculate risk score
calculateRiskScore(address borrower, uint256 amount) returns (uint256)

// Get total number of loans
getTotalLoans() returns (uint256)

// Get all loans for a borrower
getBorrowerLoans(address borrower) returns (uint256[])

// Get all loans for a lender
getLenderLoans(address lender) returns (uint256[])

Loan Statuses

0 = Requested - Loan created, waiting for lender
1 = Funded - Loan funded, awaiting repayment
2 = Repaid - Loan fully repaid
3 = Defaulted - Loan not repaid (future feature)

🔒 Security Features

Smart Contract Security

✅ ReentrancyGuard - Prevents reentrancy attacks on payable functions
✅ Ownable - Admin-only functions protected
✅ Input Validation - All inputs validated before processing
✅ Safe Math - Overflow protection (Solidity 0.8+)
✅ Access Control - Only borrower can repay, only lenders can fund
✅ Event Emissions - Full audit trail on blockchain

Backend Security

✅ Password Hashing - Werkzeug secure password hashing
✅ JWT Authentication - Token-based auth with expiration
✅ CORS Protection - Configured for frontend origin only
✅ Input Sanitization - MongoDB injection prevention

Best Practices

⚠️ Never share private keys
⚠️ Don't commit .env files
⚠️ Test thoroughly before mainnet
⚠️ Audit smart contracts professionally
⚠️ Use hardware wallets for production

🚀 Deployment to Production

Frontend Deployment (Vercel/Netlify)

Build production bundle: npm run build
Deploy dist/ folder
Update environment variables for production backend URL

Backend Deployment (Railway/Heroku)

Ensure requirements.txt is up-to-date
Configure environment variables
Deploy Flask app
Update CORS origins for production frontend

Smart Contract Deployment (Sepolia Testnet)

Get Sepolia ETH from faucet
Update hardhat.config.js with Sepolia RPC
Set SEPOLIA_PRIVATE_KEY environment variable
Deploy: npx hardhat ignition deploy --network sepolia ignition/modules/MicroLending.js

📊 Features Roadmap

Implemented ✅

User authentication & profiles
Loan creation, funding, repayment
ML-powered risk assessment
Explainable AI with SHAP
Gemini AI natural language explanations
Real-time blockchain integration
Responsive UI with modern design
MetaMask integration

Future Enhancements 🔮

📝 License

MIT License - See LICENSE file for details

👥 Team MicroLend

Built for HackWithStack Hackathon 2025

Contributors

_{@aayushhh-operator}

_@ArshvirSk

_@AgentR04

_{@Aagnya-Mistry}

_@kabir-999

⭐ Star this repository if you find it helpful!

🐛 Report issues: GitHub Issues

📧 Contact: arshvirsk26@gmail.com

Last Updated: November 21, 2025

Name		Name	Last commit message	Last commit date
MDs		MDs
backend		backend
contracts		contracts
frontend		frontend
screenshots		screenshots
.gitignore		.gitignore
README.md		README.md
start.ps1		start.ps1

Latest commit

History

Folders and files

Repository files navigation

MicroLend - Decentralized Micro-Lending Platform

🌟 Overview

✨ Features

🔗 Blockchain Features

🤖 AI & ML Features

🔐 Authentication & User Management

🎨 Frontend Features

📸 Application Screenshots

Landing Page

Borrower Dashboard

Lender Dashboard - Investments

Lender Dashboard - Opportunities

AI Analytics Feature

Profile Management

Loan Request Form

Loan Details Modal

🚧 Challenges We Ran Into

️ Tech Stack

Frontend

Backend

Machine Learning

Blockchain

Database

📋 Prerequisites

🚀 Complete Setup Guide

Step 1: Clone the Repository

Step 2: Backend Setup

2.1 Install Python Dependencies

2.2 Configure Environment Variables

2.3 Verify ML Model

Step 3: Smart Contract Setup

3.1 Install Contract Dependencies

3.2 Compile Contracts

Step 4: Frontend Setup

4.1 Install Frontend Dependencies

Step 5: MetaMask Configuration

🎬 Starting the Application

Terminal 1: Start Hardhat Blockchain Node

Terminal 2: Deploy Smart Contract

Terminal 3: Start Backend Server

Terminal 4: Start Frontend Development Server

🎮 Using the Application

1. Import Test Account to MetaMask

2. Create Your Account

3. Login

4. Connect Wallet

5. As a Borrower

Request a Loan

View Your Loans

Repay a Loan

6. As a Lender

View Opportunities

Get AI Insights

Fund a Loan

Monitor Investments

7. Profile Management

📊 Understanding Risk Scores

Risk Score Range

Risk Factors

AI Explanations

🏗️ Architecture

Data Flow

📁 Project Structure

🧪 Testing

Smart Contract Tests

Manual Testing Checklist

🐛 Troubleshooting

Common Issues

1. MetaMask Connection Failed

2. Transaction Fails

3. Backend Not Loading

4. Frontend Won't Start

5. AI Explanations Not Working

6. Contract Not Found

📚 Additional Documentation

🔑 Smart Contract Functions