Mobile Money to Stellar Bridge

A production-ready backend service that bridges African mobile money providers (MTN, Airtel, Orange) with the Stellar blockchain network, enabling seamless cross-border payments and remittances.

🌟 What We're Building

This platform solves a critical problem in African financial infrastructure: connecting traditional mobile money systems with blockchain technology. We enable:

Cross-border remittances with lower fees than traditional services
Instant settlements using Stellar's fast blockchain
Financial inclusion by bridging mobile money (used by 500M+ Africans) with global crypto markets
Compliance-first approach with built-in KYC, AML monitoring, and transaction limits
Developer-friendly APIs (REST + GraphQL) for easy integration

Real-World Use Cases

Remittances: Send money from Europe/US to Africa instantly via Stellar, recipient withdraws to mobile money
Cross-border payments: Pay suppliers in different African countries without expensive wire transfers
Savings in stable assets: Convert volatile local currency to USDC/XLM via mobile money
Merchant payments: Accept crypto payments, settle in local mobile money
DeFi access: Bridge between mobile money and Stellar DeFi protocols

🚀 Key Features

Core Functionality

Mobile Money Integration: MTN, Airtel, Orange Money support
Stellar Blockchain: Native XLM and custom asset support (USDC, anchored assets)
Dual API: RESTful API + GraphQL for flexible integration
Real-time Processing: Background job queues with BullMQ and Redis
WebSocket Support: Live transaction updates and notifications

Security & Compliance

KYC/AML: Multi-tier verification with transaction limits
2FA: TOTP-based two-factor authentication
RBAC: Role-based access control with Casbin
Rate Limiting: Intelligent rate limiting and DDoS protection
Audit Logging: Comprehensive audit trails for compliance
Session Security: IP tracking, device fingerprinting, anomaly detection

Financial Features

Dynamic Fees: VIP tiers with volume-based discounts
Transaction Limits: Provider-specific and KYC-based limits
Vault System: Secure fund storage and management
Accounting Integration: QuickBooks and Xero sync
Dispute Management: Full dispute workflow and resolution
Fee Bumping: Automatic Stellar transaction fee adjustment

Developer Experience

TypeScript: Full type safety and IntelliSense
Docker Support: Development and production containers
Database Migrations: Automated schema management
Comprehensive Testing: Unit, integration, E2E, and load tests
CI/CD: GitHub Actions with automated testing and deployment
API Documentation: OpenAPI/Swagger specs
Webhook Support: Zapier/Make.com integration

Stellar Protocol Support (SEP)

SEP-10: Stellar Web Authentication
SEP-12: KYC API
SEP-24: Hosted Deposit and Withdrawal
SEP-31: Cross-Border Payments
SEP-38: Quotes and Price Streams

📋 Prerequisites

Node.js 20+ (LTS recommended)
PostgreSQL 16+
Redis 7+
Docker (optional, for containerized development)

🛠️ Installation

1. Clone the Repository

git clone https://github.com/sublime247/mobile-money.git
cd mobile-money

2. Install Dependencies

npm install

3. Environment Configuration

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mobilemoney

# Redis
REDIS_URL=redis://localhost:6379

# Stellar Network
STELLAR_NETWORK=testnet  # or 'mainnet'
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_ISSUER_SECRET=S...  # Your Stellar secret key

# Mobile Money Providers
MTN_API_KEY=your_mtn_api_key
MTN_API_SECRET=your_mtn_secret
AIRTEL_API_KEY=your_airtel_key
ORANGE_API_KEY=your_orange_key

# Security
JWT_SECRET=your_jwt_secret_min_32_chars
SESSION_SECRET=your_session_secret

# Optional: Email notifications
SENDGRID_API_KEY=your_sendgrid_key
FROM_EMAIL=noreply@yourdomain.com

# Optional: SMS notifications
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_PHONE_NUMBER=+1234567890

4. Database Setup

# Run migrations
npm run migrate:up

# Seed development data (optional)
NODE_ENV=development npm run seed

🏃 Running the Application

Development Mode

npm run dev

Server starts at http://localhost:3000

Production Mode

npm run build
npm start

Docker Development

# Start all services (app, PostgreSQL, Redis)
npm run docker:dev

# Stop services
npm run docker:dev:down

Includes hot reload and debugger on port 9229.

Docker Production

docker-compose up -d

🧪 Testing

Run All Tests

npm test

Test Coverage

npm run test:coverage

Minimum coverage requirements: 70% (branches, functions, lines, statements)

Watch Mode

npm run test:watch

End-to-End Tests

npm run test:e2e

Load Testing

# Basic load test
npm run test:load

# Stress test
npm run test:load:stress

# Transaction-focused test
npm run test:load:transactions

Mutation Testing

npm run test:mutation

📚 API Documentation

Base URL

http://localhost:3000/api

Authentication

Most endpoints require authentication via JWT token:

Authorization: Bearer <your_jwt_token>

Or API key for admin operations:

X-API-Key: <your_api_key>

Core Endpoints

Health Checks

GET /health              # Service health status
GET /ready               # Readiness probe (checks DB and Redis)

Transactions

POST   /api/transactions/deposit      # Deposit from mobile money to Stellar
POST   /api/transactions/withdraw     # Withdraw from Stellar to mobile money
GET    /api/transactions              # List transactions (paginated)
GET    /api/transactions/:id          # Get transaction details
POST   /api/transactions/:id/cancel   # Cancel pending transaction
POST   /api/transactions/:id/dispute  # Create dispute

User Management

POST   /api/auth/register             # Register new user
POST   /api/auth/login                # Login
POST   /api/auth/logout               # Logout
POST   /api/auth/2fa/enable           # Enable 2FA
POST   /api/auth/2fa/verify           # Verify 2FA code
GET    /api/users/profile             # Get user profile
PUT    /api/users/profile             # Update profile

KYC

POST   /api/kyc/submit                # Submit KYC documents
GET    /api/kyc/status                # Check KYC status
POST   /api/kyc/upload                # Upload document

Vaults

POST   /api/vaults                    # Create vault
GET    /api/vaults                    # List user vaults
GET    /api/vaults/:id                # Get vault details
POST   /api/vaults/:id/transfer       # Deposit/withdraw from vault

Admin

GET    /api/admin/users               # List all users
GET    /api/admin/transactions        # All transactions
POST   /api/admin/fees/configurations # Create fee config
GET    /api/stats                     # System statistics

GraphQL API

POST /graphql

GraphQL Playground available at http://localhost:3000/graphql in development.

Example query:

query {
  transactions(limit: 10) {
    id
    amount
    status
    provider
    createdAt
  }
}

mutation {
  createDeposit(input: {
    amount: "10000"
    phoneNumber: "+237670000000"
    provider: MTN
  }) {
    id
    status
    referenceNumber
  }
}

Webhooks

Configure webhooks to receive real-time notifications:

POST   /api/webhooks                  # Create webhook
GET    /api/webhooks                  # List webhooks
DELETE /api/webhooks/:id              # Delete webhook

Supported events:

transaction.completed
transaction.failed
transaction.pending
kyc.approved
kyc.rejected

🔐 Security Features

Transaction Limits

Per-Transaction Limits

Limit	Amount	Purpose
Minimum	100 XAF	Prevent spam
Maximum	1,000,000 XAF	Fraud prevention

KYC-Based Daily Limits

KYC Level	Daily Limit	Requirements
Unverified	10,000 XAF	Email verification only
Basic	100,000 XAF	ID document + selfie
Full	1,000,000 XAF	Proof of address + video verification

Provider-Specific Limits

Provider	Min	Max	Notes
MTN	100 XAF	500,000 XAF	Most common
Airtel	100 XAF	1,000,000 XAF	Higher limits
Orange	500 XAF	750,000 XAF	Higher minimum

AML Monitoring

Automatic flagging of suspicious transactions:

Single transaction > 1,000,000 XAF
24-hour total > 5,000,000 XAF
Rapid structuring (3+ mixed transactions in 15 minutes)

Rate Limiting

Export endpoints: 5 requests/hour
API endpoints: Configurable per endpoint
GraphQL: Query complexity limits

🏗️ Architecture

Technology Stack

Backend

Node.js + TypeScript
Express.js (REST API)
Apollo Server (GraphQL)
PostgreSQL (primary database)
Redis (caching, sessions, queues)

Blockchain

Stellar SDK
Horizon API integration
Custom asset support

Background Jobs

BullMQ (job queues)
Node-cron (scheduled tasks)

Security

Helmet (HTTP headers)
Bcrypt (password hashing)
JWT (authentication)
Speakeasy (2FA)
Casbin (RBAC)

Monitoring

Datadog APM
Sentry (error tracking)
Prometheus metrics
Custom health checks

Project Structure

mobile-money/
├── src/
│   ├── auth/              # Authentication & authorization
│   ├── config/            # Configuration files
│   ├── controllers/       # Request handlers
│   ├── crypto/            # HSM and encryption
│   ├── graphql/           # GraphQL schema & resolvers
│   ├── jobs/              # Background jobs
│   ├── middleware/        # Express middleware
│   ├── models/            # Database models
│   ├── queue/             # Job queue management
│   ├── routes/            # API routes
│   ├── scripts/           # Utility scripts
│   ├── services/          # Business logic
│   │   ├── mobilemoney/   # Mobile money integrations
│   │   └── stellar/       # Stellar blockchain services
│   ├── stellar/           # Stellar SEP implementations
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Helper functions
│   ├── websocket/         # WebSocket server
│   └── index.ts           # Application entry point
├── tests/                 # Test files
│   ├── e2e/              # End-to-end tests
│   ├── integration/      # Integration tests
│   ├── load/             # Load tests
│   └── unit/             # Unit tests
├── migrations/           # Database migrations
├── contracts/            # Stellar smart contracts
├── .github/              # GitHub Actions workflows
└── docker/               # Docker configurations

🔄 Database Migrations

Create Migration

npm run migrate:create -- migration_name

Run Migrations

npm run migrate:up

Rollback

npm run migrate:down

Check Status

npm run migrate:status

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Quality

Pre-commit hooks automatically run:

ESLint (linting)
Prettier (formatting)
TypeScript type checking
Tests

Bypass hooks (not recommended):

git commit --no-verify

Good First Issues

Check out issues labeled good first issue for beginner-friendly tasks.

📊 Monitoring & Observability

Metrics

Prometheus metrics available at /metrics:

Transaction counts by status
API response times
Queue depths
Error rates
Provider availability

Health Checks

# Liveness probe
curl http://localhost:3000/health

# Readiness probe (checks dependencies)
curl http://localhost:3000/ready

Logging

Structured JSON logging with levels:

error: Critical errors
warn: Warnings and anomalies
info: General information
debug: Detailed debugging (dev only)

Error Tracking

Sentry integration for production error monitoring:

SENTRY_DSN=your_sentry_dsn

🚢 Deployment

Environment Variables

Required for production:

NODE_ENV=production
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
STELLAR_NETWORK=mainnet
STELLAR_ISSUER_SECRET=S...
JWT_SECRET=...
SESSION_SECRET=...

Docker Deployment

docker build -t mobile-money:latest .
docker run -p 3000:3000 --env-file .env mobile-money:latest

Kubernetes

Example deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mobile-money
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mobile-money
  template:
    metadata:
      labels:
        app: mobile-money
    spec:
      containers:
      - name: mobile-money
        image: mobile-money:latest
        ports:
        - containerPort: 3000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: mobile-money-secrets
              key: database-url
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000

📈 Performance

Benchmarks

API Response Time: < 100ms (p95)
Transaction Processing: < 5s (end-to-end)
Throughput: 1000+ req/s
Database Queries: < 50ms (p95)

Optimization Tips

Enable Redis caching
Use connection pooling
Implement CDN for static assets
Enable compression middleware
Use database indexes
Implement query result caching

🐛 Troubleshooting

Common Issues

Database connection fails

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Verify DATABASE_URL format
postgresql://user:password@host:port/database

Redis connection fails

# Check Redis is running
redis-cli ping

# Should return: PONG

Stellar transactions fail

# Verify network configuration
echo $STELLAR_NETWORK  # Should be 'testnet' or 'mainnet'

# Check Horizon connectivity
curl https://horizon-testnet.stellar.org

Tests failing

# Clear test database
npm run migrate:down
npm run migrate:up

# Clear Jest cache
npm test -- --clearCache

📝 License

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

🙏 Acknowledgments

Stellar Development Foundation for blockchain infrastructure
Mobile money providers (MTN, Airtel, Orange) for API access
Open source community for amazing tools and libraries

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🗺️ Roadmap

Built with ❤️ for financial inclusion in Africa

Name		Name	Last commit message	Last commit date
Latest commit History 738 Commits
.github		.github
.vscode		.vscode
contracts		contracts
database		database
docs		docs
elk		elk
examples		examples
k8s		k8s
migrations		migrations
scripts		scripts
src		src
terraform		terraform
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
README.md		README.md
codecov.yml		codecov.yml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
jest.config.js		jest.config.js
jest.stryker.config.js		jest.stryker.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
sonar-project.properties		sonar-project.properties
stryker.conf.json		stryker.conf.json
tsconfig.json		tsconfig.json
validate-webhooks.js		validate-webhooks.js
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

Mobile Money to Stellar Bridge

🌟 What We're Building

Real-World Use Cases

🚀 Key Features

Core Functionality

Security & Compliance

Financial Features

Developer Experience

Stellar Protocol Support (SEP)

📋 Prerequisites

🛠️ Installation

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

4. Database Setup

🏃 Running the Application

Development Mode

Production Mode

Docker Development

Docker Production

🧪 Testing

Run All Tests

Test Coverage

Watch Mode

End-to-End Tests

Load Testing

Mutation Testing

📚 API Documentation

Base URL

Authentication

Core Endpoints

Health Checks

Transactions

User Management

KYC

Vaults

Admin

GraphQL API

Webhooks

🔐 Security Features

Transaction Limits

Per-Transaction Limits

KYC-Based Daily Limits

Provider-Specific Limits

AML Monitoring

Rate Limiting

🏗️ Architecture

Technology Stack

Project Structure

🔄 Database Migrations

Create Migration

Run Migrations

Rollback

Check Status

🤝 Contributing

Development Workflow

Code Quality

Good First Issues

📊 Monitoring & Observability

Metrics

Health Checks

Logging

Error Tracking

🚢 Deployment

Environment Variables

Docker Deployment

Kubernetes

📈 Performance

Benchmarks

Optimization Tips

🐛 Troubleshooting

Common Issues

📝 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

Packages