Off-chain orchestration layer for Buy Now Pay Later (BNPL) flows on Stellar Network

Features • Tech Stack • Quick Start • Documentation • Contributing

---

📖 About

TrustUp API is a production-ready backend service that orchestrates BNPL (Buy Now Pay Later) transactions on the Stellar blockchain. Built with NestJS and Fastify, it provides a fast, scalable off-chain layer that enhances user experience while maintaining blockchain decentralization.

Key Features

• 🔐 Wallet-based Authentication - Secure signature-based auth with JWT
• 💰 BNPL Loan Management - Create, track, and repay loans on-chain
• ⭐ Reputation System - On-chain reputation scoring with fast cache
• 🏪 Merchant Integration - Merchant registry and loan quotes
• 💧 Liquidity Pool - Investor deposits and withdrawals
• 📊 Real-time Indexing - Background jobs sync blockchain events
• 🔔 Notifications - Loan reminders and status updates
• 🚀 Production Ready - Comprehensive testing, logging, and monitoring

🛠 Tech Stack

N20 · TS5 · NJS10/FST4 · SSDK11/SRPC · SBP15 · RDS7 · BMQ5 · ZOD3 · JWT10 · PIN8 · SNT8

Core Technologies

Category	Technology	Version
Runtime	Node.js	20 LTS
Language	TypeScript	5.4
Framework	NestJS	10.3
HTTP Server	Fastify	4.28
Blockchain	Stellar SDK	11.2
Database	Supabase (Postgres)	15
Cache/Jobs	Redis	7
Queue	BullMQ	5.12
Validation	Zod	3.23
Auth	JWT	10.2
Logging	Pino	8.21
Monitoring	Sentry	8.14

Blockchain Integration

• 🌟 Stellar Network - Mainnet & Testnet support
• 🔷 Soroban - Smart contract interactions
• 📡 Horizon API - Transaction queries
• 🔗 Soroban RPC - Contract state reading

📁 Project Structure

TrustUp-API/
├── src/
│   ├── main.ts                 # Application bootstrap
│   ├── app.module.ts           # Root module
│   ├── config/                 # Configuration (env, swagger)
│   ├── modules/                # API modules (auth, loans, reputation, etc.)
│   ├── blockchain/             # Stellar/Soroban clients
│   │   ├── stellar/            # Stellar network client
│   │   ├── soroban/            # Soroban RPC client
│   │   └── contracts/          # Contract clients (TypeScript wrappers)
│   ├── database/               # Supabase client and repositories
│   ├── jobs/                   # Background jobs (BullMQ)
│   └── common/                 # Shared utilities (guards, filters, utils)
├── test/
│   ├── unit/                   # Unit tests
│   ├── e2e/                    # End-to-end tests
│   ├── fixtures/               # Test data
│   └── helpers/                # Test helpers
├── docs/                       # Documentation
│   ├── architecture/           # Architecture documentation
│   ├── development/            # Development guides and standards
│   ├── setup/                  # Setup and configuration guides
│   └── api/                    # API reference
├── supabase/
│   └── migrations/             # Database migrations
├── CONTRIBUTING.md             # Contribution guidelines
├── ROADMAP.md                  # Development roadmap
├── SECURITY.md                 # Security policy
└── LICENSE                     # MIT License

🚀 Quick Start

Prerequisites

• Node.js 20 LTS or higher
• npm or yarn
• Redis (for jobs and cache)
• Supabase account and project

Installation

# Clone the repository
git clone https://github.com/TrustUp-app/TrustUp-API.git
cd TrustUp-API

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Configure your .env file (see Configuration section)

Configuration

1. Supabase Setup

   • Create a project at supabase.com
   • Get your credentials from Settings → API
   • Add to .env:

     SUPABASE_URL=your_project_url
     SUPABASE_ANON_KEY=your_anon_key
     SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

2. Stellar Configuration

   STELLAR_NETWORK=testnet  # or mainnet
   STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
   SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

3. Redis Setup

   REDIS_HOST=localhost
   REDIS_PORT=6379

4. JWT Secrets

   JWT_SECRET=your_jwt_secret
   JWT_REFRESH_SECRET=your_refresh_secret

For complete setup instructions, see Installation Guide and Contributing Guide.

Running the Application

# Development mode (with hot reload)
npm run dev

# Production build
npm run build
npm run start:prod

# The API will be available at http://localhost:4000/api/v1

Database Migrations

# Install Supabase CLI (if not already installed)
npm install -g supabase

# Login to Supabase
supabase login

# Link your project
supabase link --project-ref your-project-ref

# Apply migrations
supabase db push

🧪 Testing

# Unit tests
npm run test

# Watch mode
npm run test:watch

# E2E tests
npm run test:e2e

# Coverage report
npm run test:cov

📚 Documentation

Comprehensive documentation is organized into the following categories:

🏗 Architecture

• Architecture Overview - System architecture and design principles
• Blockchain Layer - Stellar/Soroban integration
• Database Schema - PostgreSQL database design

🚀 Getting Started

• Installation Guide - Step-by-step setup instructions
• Environment Variables - Configuration reference
• Supabase Setup - Database setup guide

💻 Development

• Naming Conventions - Code style and conventions
• Controllers Structure - Controller patterns
• Services Structure - Service layer patterns
• DTO Standards - Data transfer object patterns
• Response Standards - API response formats
• Error Handling - Error handling standards
• Guards & Filters - Authentication and validation
• Logging Standards - Logging best practices
• Testing Structure - Testing guidelines

📡 API Reference

• API Endpoints - Complete API documentation
• Roadmap - Development phases and progress

🤝 Contributing

• Contributing Guide - How to contribute to the project
• Security Policy - Security guidelines and reporting vulnerabilities

Interactive Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:4000/api/v1/docs
• Health Check: http://localhost:4000/api/v1/health

🏗 Architecture Principles

• 🔗 On-chain is truth - Blockchain is the source of truth
• ⚡ Fast UX - Off-chain indexing for quick queries
• 🔒 Decentralized - Users sign transactions, API doesn't hold keys
• 🧩 Modular - Replaceable backend components
• 📊 Observable - Comprehensive logging and monitoring
• ✅ Tested - Unit, integration, and E2E tests

🔐 Security

• Wallet Signature Authentication - No password storage
• JWT Tokens - Secure access and refresh tokens
• Helmet - Security headers
• Rate Limiting - Throttler protection
• Row Level Security - Database-level access control
• Input Validation - Zod schema validation

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

Check out the Roadmap to see what we're working on and find areas where you can contribute.

🙏 Acknowledgments

• Stellar Development Foundation - For the amazing blockchain platform
• NestJS - For the excellent framework
• Supabase - For the database infrastructure

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for the Stellar ecosystem