RemitLend

RemitLend treats remittance history as credit history. Migrant workers prove their financial reliability through monthly cross-border transfers, allowing them to receive fair loans without predatory fees. In return, lenders earn transparent yield powered by the Stellar network.

✨ Key Features

For Borrowers

• Credit Building: Convert your existing remittance history into an actionable credit score.
• Fair Rates: Access loans with transparent, non-predatory interest rates.
• Self-Custody: Maintain full control of your assets using Stellar wallets.

For Lenders

• Transparent Yield: Earn interest by providing liquidity to audited borrowing pools.
• Risk Assessment: Make informed decisions based on verifiable, on-chain remittance proofs (Remittance NFTs).

Technical Highlights

• NFT-Based Collateral: Remittance NFTs serve as proof of reliability and loan collateral.
• Decentralized Lending Pools: Lenders provide liquidity and earn transparent yields.
• Transparent & Auditable: All transactions and loan terms recorded on-chain.

🏗 Project Structure

The repository is organized as a monorepo containing three core packages:

• backend/: Node.js/Express server providing API support, score generation, and metadata management.
• frontend/: Next.js web application providing the UI for both borrowers and lenders.
• contracts/: Soroban (Rust) smart contracts covering the lending pools, loan management, and NFT collateral logic.

For a detailed look at how these components interact, see our Architecture Diagram. New contributor? Start with the in-repo wiki: docs/wiki/README.md. Looking for deployed contract IDs? See docs/deployed-contracts.md.

API Reference

The backend exposes an interactive Swagger UI for exploring and testing API endpoints. Start the backend server (see Quick Start or Manual Setup), then open:

• Swagger UI: http://localhost:3001/docs
• OpenAPI JSON: http://localhost:3001/docs.json

Both endpoints are gated to non-production environments (NODE_ENV !== "production").

Webhooks

RemitLend supports real-time event notifications via webhooks. See the Webhook Integration Guide for details on subscribing, event payloads, retry semantics, circuit-breaker behavior, and HMAC signature verification.

• Swagger UI: http://localhost:3001/docs
• OpenAPI JSON: http://localhost:3001/docs.json

Both endpoints are gated to non-production environments (NODE_ENV !== "production").

🛠 Tech Stack

• Blockchain: Stellar (Soroban Smart Contracts)
• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
• Backend: Node.js, Express, TypeScript, Jest
• Wallet Integration: Stellar Wallet Kit (Freighter)

🏁 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Docker & Docker Compose (Recommended for easy setup)
• Rust & Cargo (Required for contract development)
• Soroban CLI (Required for contract deployment)
• Stellar Wallet (Freighter recommended for testing)

Quick Start with Docker (Recommended)

• Clone the repository:

git clone https://github.com/LabsCrypt/remitlend.git
   cd remitlend

• Configure environment:

cp backend/.env.example backend/.env

Edit backend/.env if needed (defaults work for local development).

• Start all services:

docker compose up --build

Docker Compose uses healthchecks so services start cleanly: - PostgreSQL (db) is marked healthy via pg_isready - The backend waits for healthy Postgres before starting, runs npm run migrate:up, then starts the API - The backend container is marked healthy by polling GET /health every 10 seconds (3 retries)

• Access the application:

- Frontend: http://localhost:3000 - Backend API: http://localhost:3001 - API Documentation: http://localhost:3001/docs

Manual Setup

Backend Setup

• Navigate to backend directory:

cd backend

• Install dependencies:

npm install

• Configure environment:

cp .env.example .env

Update .env with your configuration (at minimum DATABASE_URL for PostgreSQL):

CORSALLOWEDORIGINS=http://localhost:3000
   PORT=3001
   NODE_ENV=development
   DATABASE_URL=postgres://postgres:postgres@localhost:5432/remitlend

• Apply database migrations (creates scores, loanevents, indexerstate, and other tables):

npm run migrate:up

Migration scripts use the colon form (migrate:up / migrate:down), which is the standard npm convention.

• Run development server:

npm run dev

• Available scripts:

- npm run dev - Start development server with hot reload - npm run build - Build for production - npm start - Run production build - npm test - Run test suite - npm run lint - Check code quality - npm run format - Format code with Prettier

Frontend Setup

• Navigate to frontend directory:

cd frontend

• Install dependencies:

npm install

• Run development server:

npm run dev

• Access the application:

Open http://localhost:3000 in your browser

• Available scripts:

- npm run dev - Start development server - npm run build - Build for production - npm start - Run production build - npm run lint - Check code quality

Smart Contracts Setup

• Install Rust and wasm32 target:

rustup target add wasm32-unknown-unknown

• Install Soroban CLI:

cargo install --locked soroban-cli

• Navigate to contracts directory:

cd contracts

• Build all contracts:

cargo build --target wasm32-unknown-unknown --release

• Run tests:

cargo test

• Deploy to testnet (example):

soroban contract deploy \
     --wasm target/wasm32-unknown-unknown/release/remittance_nft.wasm \
     --source <YOURSECRETKEY> \
     --rpc-url https://soroban-testnet.stellar.org \
     --network-passphrase "Test SDF Network ; September 2015"

🔒 Security

For details on how to report a security vulnerability, please see our Security Policy.

🤝 Contributing

We welcome contributions from developers of all skill levels! Please see our CONTRIBUTING.md for detailed guidelines on how to get started.

Environment Variables

See docs/ENVIRONMENT.md for a full reference of all environment variables across backend, frontend, and scripts. Each .env.example file also links to this document.

Quick Contribution Guide

• Fork the repository.
• Create a feature branch (git checkout -b feat/amazing-feature).
• Make your changes and commit using Conventional Commits (git commit -m 'feat: add amazing feature').
• Push to your branch (git push origin feat/amazing-feature).
• Open a Pull Request.

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.