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.

🛠 Tech Stack

• Blockchain: Stellar (Soroban Smart Contracts)
• Frontend: Next.js 14, React, 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)

1. Clone the repository:

   git clone https://github.com/your-username/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
   

   The backend waits for PostgreSQL to be ready, runs npm run migrate:up to apply SQL migrations, then starts the API.

4. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001
   • API Documentation: http://localhost:3001/api-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"
   

🤝 Contributing

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

Quick Contribution Guide

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

📄 License

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