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.

🛠 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 (v22 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)

1. Clone the repository:

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

2. Configure environment:

   cp backend/.env.example backend/.env

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

3. 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)

4. Access the application:

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

Manual Setup

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Install dependencies:

   npm install

3. Configure environment:

   cp .env.example .env

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

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

4. Apply database migrations (creates scores, loan_events, indexer_state, and other tables):

   npm run migrate:up

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

5. Run development server:

   npm run dev

6. 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

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Run development server:

   npm run dev

4. Access the application: Open http://localhost:3000 in your browser

5. 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

1. Install Rust and wasm32 target:

   rustup target add wasm32-unknown-unknown

2. Install Soroban CLI:

   cargo install --locked soroban-cli

3. Navigate to contracts directory:

   cd contracts

4. Build all contracts:

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

5. Run tests:

   cargo test

6. Deploy to testnet (example):

   soroban contract deploy \
     --wasm target/wasm32-unknown-unknown/release/remittance_nft.wasm \
     --source <YOUR_SECRET_KEY> \
     --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.

Bug-hunt exercise

Some issues are intentionally seeded bugs used for contributor bug-hunting. The answer key for these bugs is teacher-only and is deliberately not part of the public repository (it is listed in .gitignore and never committed to the default branch) so that browsing the repo does not spoil the exercise. Do not commit a BUG_HUNT_ANSWER_KEY.md file in any pull request.

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

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

📄 License

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