ProxyPay ↔ Stellar Bridge

A backend service that bridges African mobile money providers (MTN MoMo, Airtel Money, Orange Money) with the Stellar blockchain network — enabling low-cost cross-border payments and remittances across Africa and beyond.

🌟 The Problem

Sending money across African borders is expensive and slow. Traditional remittance services charge 7–10% in fees and take hours to days. Meanwhile, 500+ million people across Africa already use mobile money for everyday transactions — but mobile money stops at the border.

💡 The Solution

ProxyPay connects mobile money wallets to the Stellar blockchain, allowing users to:

Deposit mobile money (XAF) → receive Stellar tokens (XLM, USDC)
Transfer tokens across Stellar's network in ~5 seconds, for fractions of a cent
Withdraw Stellar tokens → receive mobile money in the destination country

The sender and recipient interact with their familiar mobile money apps. Stellar handles the cross-border settlement invisibly.

  📱 MTN MoMo (Cameroon)                           📱 Airtel Money (Kenya)
         │                                                  ▲
         ▼                                                  │
  ┌─────────────────────────────────────────────────────────────────┐
  │                       ProxyPay Bridge                          │
  │                                                                 │
  │   Deposit (XAF → USDC)  ──►  Stellar Network  ──►  Withdraw    │
  │                              (settles in ~5s)                   │
  └─────────────────────────────────────────────────────────────────┘

Use Cases

Remittances — Send money home across borders at ~1–2% vs 7–10% with traditional services
Cross-border B2B payments — Pay suppliers in other African countries without expensive wire transfers
Stable savings — Convert volatile local currency to USDC via mobile money
Merchant payments — Accept crypto, settle in local mobile money
Developer integrations — Build payment apps on top of our REST + GraphQL APIs

🚀 Key Features

Core Platform

Mobile Money Integration — MTN MoMo, Airtel Money, Orange Money with circuit breaker, failover, and batch payouts
Stellar Blockchain — XLM, USDC, and custom asset support via Stellar SDK + Horizon API
Dual API — REST (40+ endpoints) and GraphQL (queries, mutations, and real-time subscriptions)
Real-time Processing — BullMQ job queues with Redis, admin dashboard at /admin/queues
WebSocket — Live transaction updates with JWT auth, per-user rooms, and Redis pub/sub for horizontal scaling
Provider Mock Server — Full mock for MTN + Airtel APIs for local development without real credentials

Security & Compliance

Multi-tier KYC — Tiered identity verification with document upload (S3) and third-party verification (Entrust)
AML Monitoring — Auto-flagging of suspicious patterns (large transactions, rapid structuring, daily totals)
Travel Rule Compliance — FATF travel rule data collection for qualifying transactions
GDPR / Privacy — Data export, deletion, and consent management endpoints
Sanctions Screening — Automated screening against sanctions lists
2FA (TOTP) — Time-based one-time passwords via Speakeasy, required for withdrawals
RBAC — Role-based access control via Casbin
Rate Limiting & Audit Logging — Multi-layer rate limiting with full audit trail
PII Encryption — AES-256-GCM encryption for sensitive data at rest

Financial Engine

Dynamic Fee Engine — Configurable fee strategies with VIP tiers (25KB+ fee strategy engine)
Transaction Limits — Provider-specific and KYC-tiered daily limits
Vault System — Secure fund storage with distributed locking
Double-Entry Ledger — Internal accounting system with full transaction journal
Dispute Management — Complete dispute workflow with state machine
Monthly Statements — Automated PDF statement generation
Reconciliation — Provider reconciliation workflows

Stellar Protocol (SEP) Support

SEP-06 — Deposit and Withdrawal API
SEP-10 — Web Authentication (challenge-response)
SEP-12 — KYC API (customer CRUD with document upload)
SEP-24 — Interactive Deposit and Withdrawal (hosted flow)
SEP-31 — Cross-Border Payments (send-side anchor)

Smart Contracts

Escrow Contract — Soroban smart contract for escrowed payments (Rust)
HTLC Contract — Hash Time-Locked Contract for atomic cross-chain swaps (Rust)

Notifications

Email — SendGrid integration
SMS — Twilio integration
Push Notifications — Firebase Cloud Messaging
WhatsApp — Twilio WhatsApp channel
PagerDuty — Operational alerting

Developer Tools

CLI (momo-cli) — Admin tool for auth, status checks, and transaction retries
Kotlin SDK — Auto-generated from OpenAPI spec
Postman Collections — Pre-built API collections for testing
VS Code Extension — Transaction monitor with live WebSocket logs
Swagger UI — Auto-generated from Zod schemas at /docs (dev mode)

📋 Prerequisites

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

🛠️ Quick Start

1. Clone & Install

git clone https://github.com/sublime247/proxypay.git
cd proxypay
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your configuration (see .env.example for all ~470 configuration options):

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

# Redis
REDIS_URL=redis://localhost:6379

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

# Mobile Money Providers
MTN_API_KEY=your_mtn_api_key
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: Notifications
SENDGRID_API_KEY=your_sendgrid_key
TWILIO_ACCOUNT_SID=your_twilio_sid

3. Setup Database

npm run migrate:up
npm run seed  # Optional: development data

4. Run

Development (with provider mocks):

npm run docker:dev   # Starts app + Postgres + Redis + provider mock server

Development (standalone):

npm run dev

Production:

npm run build
npm start

Server starts at http://localhost:3000

🧪 Testing

npm test                    # Unit tests (Jest)
npm run test:coverage       # With coverage report
npm run test:watch          # Watch mode
npm run test:e2e            # End-to-end (Playwright)
npm run test:load           # Load testing (k6 / autocannon)
npm run test:mutation       # Mutation testing (Stryker)

Test infrastructure includes:

Unit & integration tests across controllers, services, middleware, routes
Pact consumer-driven contract tests for provider APIs
Playwright end-to-end tests
k6 load/stress tests with benchmarking against Go vs Node ingest services
Stryker mutation testing
Fuzz testing

Coverage reports upload to Codecov on every push to main.

📚 API Documentation

Interactive Docs (Development Only)

Start the dev server and visit:

Swagger UI: http://localhost:3000/docs
OpenAPI JSON: http://localhost:3000/docs/openapi.json

The API spec is auto-generated from Zod validation schemas at runtime — no manual YAML to maintain.

Core Endpoints

# Health
GET  /health                          # Liveness probe
GET  /ready                           # Readiness (DB + Redis)
GET  /health/lb                       # Load balancer health

# Transactions
POST /api/transactions/deposit        # Mobile money → Stellar
POST /api/transactions/withdraw       # Stellar → Mobile money
GET  /api/transactions                # List (paginated, filterable)
GET  /api/transactions/:id            # Transaction details
GET  /api/transactions/:id/invoice    # Download completed transaction invoice
POST /api/transactions/:id/cancel     # Cancel pending transaction
POST /api/transactions/:id/dispute    # Open dispute
POST /api/transactions/bulk           # Bulk operations

# Auth
POST /api/auth/register               # Register
POST /api/auth/login                  # Login (returns JWT)
POST /api/auth/2fa/enable             # Enable TOTP 2FA
POST /oauth/token                     # OAuth2 client credentials

# KYC
POST /api/kyc/submit                  # Submit documents
GET  /api/kyc/status                  # Check verification status

# Vaults
POST /api/vaults                      # Create vault
GET  /api/vaults                      # List vaults
POST /api/vaults/:id/transfer         # Deposit/withdraw funds

# Disputes
GET  /api/disputes                    # List disputes
PUT  /api/disputes/:id                # Update dispute status

# Compliance
GET  /api/v1/compliance/travel-rule   # Travel rule data
GET  /api/gdpr/export                 # GDPR data export
DELETE /api/gdpr/delete               # Right to be forgotten

# Stellar SEP Endpoints
POST /sep10/auth                      # SEP-10 authentication
GET  /sep12/customer                  # SEP-12 KYC
POST /sep24/transactions/deposit/interactive  # SEP-24 deposit
POST /sep31/transactions              # SEP-31 cross-border

# Admin
GET  /api/admin/*                     # Admin dashboard endpoints
GET  /api/stats                       # Transaction statistics
GET  /api/reconciliation              # Provider reconciliation
GET  /metrics                         # Prometheus metrics

GraphQL

POST /graphql

Playground: http://localhost:3000/graphql (dev only)

🔐 Security

Transaction Limits

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

KYC-Based Daily Limits

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

🏗️ Architecture

Tech Stack

Layer	Technology
API Server	Node.js, TypeScript, Express, Apollo Server (GraphQL)
Database	PostgreSQL 16 (primary + read replicas), Redis 7 (cache, sessions, pub/sub)
Blockchain	Stellar SDK, Horizon API, Soroban smart contracts (Rust)
Job Processing	BullMQ workers, node-cron scheduled jobs
Ingest (High-throughput)	Go service (fasthttp) + Node.js service (Fastify), Redis Streams, NATS JetStream
Security	Helmet, bcrypt, JWT, Speakeasy (TOTP), Casbin (RBAC), AES-256-GCM (PII)
Monitoring	Prometheus, Datadog (dd-trace), Sentry, PagerDuty
Logging	Structured JSON → Loki/Grafana (primary), ELK stack (secondary)
Edge	Cloudflare Workers (`.well-known` caching)
Infrastructure	Docker, Kubernetes (+ Helm, KEDA), Terraform (AWS)
CI/CD	GitHub Actions (lint, test, build, deploy, rollback)

Project Structure

proxypay/
├── src/
│   ├── auth/              # Authentication & authorization
│   ├── compliance/        # Travel rule, sanctions
│   ├── config/            # Centralized configuration
│   ├── constants/         # Error codes, enums
│   ├── controllers/       # Request handlers
│   ├── crypto/            # Encryption utilities
│   ├── graphql/           # Schema, resolvers, subscriptions, APQ cache
│   ├── jobs/              # Scheduled & background jobs
│   ├── locales/           # i18n translations
│   ├── middleware/        # Auth, RBAC, rate limiting, audit, error handling
│   ├── models/            # Database models (15 models)
│   ├── openapi/           # Auto-generated API docs (Zod → OpenAPI)
│   ├── queue/             # BullMQ job queue management
│   ├── reports/           # Statement & report generation
│   ├── routes/            # API routes (40+ route files, versioned)
│   ├── services/          # Business logic (58 service files)
│   │   ├── mobilemoney/   # MTN, Airtel, Orange providers + orchestration
│   │   └── stellar/       # Stellar operations, asset management, HSM
│   ├── stellar/           # SEP protocol implementations (6, 10, 12, 24, 31)
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Helpers & utilities
│   └── websocket/         # WebSocket server (JWT auth, Redis scaling)
├── contracts/             # Soroban smart contracts (Escrow, HTLC)
├── ingest-go/             # High-performance Go callback ingestion
├── ingest-node/           # Node.js baseline for benchmarking
├── workers/               # Cloudflare Workers (edge caching)
├── cli/                   # CLI admin tool (momo-cli)
├── sdk/                   # Auto-generated Kotlin SDK
├── benchmarks/            # k6 load testing suite
├── bridge-starter-node/   # Webhook bridge starter template
├── docs/                  # Extensive documentation (59 docs)
├── extensions/            # VS Code transaction monitor extension
├── postman/               # API testing collections
├── migrations/            # Database migrations (47 migrations)
├── k8s/                   # Kubernetes manifests + Helm chart
├── terraform/             # AWS infrastructure (VPC, ECS, RDS, ElastiCache)
├── elk/                   # ELK stack config (Filebeat, Logstash, Kibana)
├── logging/               # Loki + Grafana + Promtail config
├── scripts/               # Operational scripts (mock server, DB scrub, etc.)
└── tests/                 # Test suites (unit, integration, e2e, pact, fuzz)

🔄 Database

Migrations

npm run migrate:create -- migration_name  # Create
npm run migrate:up                        # Run all pending
npm run migrate:down                      # Rollback last
npm run migrate:status                    # Check status

🚢 Deployment

Docker

# Development (with mocks, hot reload, Grafana)
docker compose up

# Production build
docker build -t proxypay:latest .
docker run -p 3000:3000 --env-file .env proxypay:latest

Kubernetes

kubectl apply -f k8s/

Terraform (AWS)

cd terraform
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform plan -var-file=environments/production.tfvars
terraform apply

🛠️ Operations & Incident Response

Deployment & rollback: docs/BRIDGE_DEPLOYMENT_RUNBOOK.md
Incident runbooks: docs/runbooks/ — step-by-step diagnosis and mitigation for the top production incidents (provider down, database index bloat, high API latency, queue backlog, Redis outage, Horizon degradation, DB pool exhaustion, replica lag, ledger imbalance, elevated error rate).

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md.

Good First Issues

Check good first issue label.

📝 License

MIT License — see LICENSE file.

🙏 Acknowledgments

Stellar Development Foundation
Mobile money providers (MTN, Airtel, Orange)
Open source community

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ for financial inclusion in Africa

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
.kilo		.kilo
.pull_request		.pull_request
.vscode		.vscode
benchmarks		benchmarks
bridge-starter-node		bridge-starter-node
cli		cli
cloud-run		cloud-run
config		config
contracts		contracts
database		database
docs		docs
elk		elk
examples		examples
extensions/transaction-monitor		extensions/transaction-monitor
ingest-go		ingest-go
ingest-node		ingest-node
k8s		k8s
logging		logging
migrations		migrations
pacts		pacts
postman		postman
public/.well-known		public/.well-known
scratch		scratch
scripts		scripts
sdk		sdk
src		src
terraform		terraform
tests		tests
workers		workers
.dockerignore		.dockerignore
.env.config.example		.env.config.example
.env.example		.env.example
.gitguardian		.gitguardian
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
README.md		README.md
app.json		app.json
cloudbuild.yaml		cloudbuild.yaml
codecov.yml		codecov.yml
commitlint.config.js		commitlint.config.js
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
jest.migrations.config.js		jest.migrations.config.js
jest.pact.config.js		jest.pact.config.js
jest.stryker.config.js		jest.stryker.config.js
momo-cli		momo-cli
openapitools.json		openapitools.json
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
redis.conf		redis.conf
sdk-config-ts.yaml		sdk-config-ts.yaml
sdk-config.yaml		sdk-config.yaml
sonar-project.properties		sonar-project.properties
stellar.toml		stellar.toml
stryker.conf.json		stryker.conf.json
tsconfig.eslint.json		tsconfig.eslint.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
wrangler.toml		wrangler.toml

Latest commit

History

Folders and files

Repository files navigation