Lumina

"Stripe for crypto payments — powered by Stellar."

Lumina is an open-source, global crypto payment infrastructure that lets businesses and developers accept payments in multiple cryptocurrencies, automatically convert them to stablecoins, settle instantly on the Stellar network, and withdraw to bank accounts.

Overview

What Lumina Does

Feature	Description
Payment Gateway	Accept BTC, ETH, USDC, XLM; auto-convert to USDC on Stellar
On-Ramp	Fiat → USDC via card or bank transfer
Off-Ramp	USDC → bank account
Escrow	Smart contract escrow for freelance/marketplace use cases
Payment Splits	Auto-split payments to multiple addresses
Subscriptions	Recurring billing on-chain
Merchant Dashboard	Analytics, balances, API keys, withdrawals
Developer API/SDK	REST API + JS/Python/Go SDKs

Settlement Layer

All payments settle as USDC on the Stellar network via Soroban smart contracts.

Architecture

Users / Customers
        │
        ▼
Frontend (Next.js + TypeScript)
        │  REST / WebSocket
        ▼
Backend Gateway (NestJS)
        │
        ├── Payment Service       → create, track, settle payments
        ├── Ramp Service          → fiat on/off ramp processing
        ├── Conversion Engine     → BTC/ETH → USDC conversion
        ├── Blockchain Listener   → watch Stellar transactions
        └── Notification Service → webhooks, email, alerts
        │
        ▼
Stellar Network (Testnet → Mainnet)
        │
        ▼
Soroban Smart Contracts
        ├── payment_registry_contract
        ├── merchant_vault_contract
        ├── escrow_contract
        ├── payment_split_contract
        ├── subscription_contract
        └── fee_manager_contract

Repository Structure

Lumina/
│
├── contracts/                        # Soroban smart contracts (Rust)
│   ├── escrow_contract/
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── types.rs
│   │   │   ├── storage.rs
│   │   │   └── logic.rs
│   │   └── Cargo.toml
│   ├── payment_split_contract/
│   ├── subscription_contract/
│   ├── merchant_vault_contract/
│   ├── payment_registry_contract/
│   └── fee_manager_contract/
│
├── backend/                          # NestJS backend services
│   ├── api_gateway/
│   ├── payment_service/
│   ├── ramp_service/
│   ├── blockchain_listener/
│   ├── conversion_engine/
│   └── notification_service/
│
├── frontend/                         # Next.js frontend
│   ├── app/
│   ├── components/
│   ├── dashboard/
│   ├── checkout/
│   ├── hooks/
│   └── services/
│
├── docs/                             # Documentation
├── .github/
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── CONTRIBUTING.md
└── README.md

Getting Started

Prerequisites

Tool	Version
Node.js	>= 18
Rust	Latest stable
Soroban CLI	Latest
Docker	>= 20
pnpm	>= 8

1. Clone the Repository

git clone  https://github.com/StellarLumina/Lumina.git
cd Lumina

2. Install Frontend Dependencies

cd frontend
npm install

3. Install Backend Dependencies

cd backend
npm install

4. Set Up Smart Contract Environment

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Soroban CLI
cargo install --locked soroban-cli

# Add the WASM target
rustup target add wasm32-unknown-unknown

5. Configure Environment Variables

cp .env.example .env
# Fill in values — see Environment Variables section below

6. Run Local Development

# Start all services with Docker Compose
docker-compose up

# Or run individually
cd frontend && pnpm dev          # http://localhost:3000
cd backend && pnpm start:dev     # http://localhost:4000

Smart Contracts (Soroban)

Each contract is a standalone Rust crate. They are modular — one contract, one responsibility.

Contracts

Contract	Purpose
`payment_registry_contract`	Ledger of all payment records
`merchant_vault_contract`	Holds and manages merchant funds
`escrow_contract`	Holds funds until conditions are met
`payment_split_contract`	Splits a payment across multiple parties
`subscription_contract`	Manages recurring billing
`fee_manager_contract`	Calculates and collects platform fees

Build Contracts

cd contracts/escrow_contract
cargo build --target wasm32-unknown-unknown --release

Deploy to Testnet

soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/escrow_contract.wasm \
  --source <YOUR_SECRET_KEY> \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"

Run Contract Tests

cd contracts/escrow_contract
cargo test

Backend Services

The backend is a NestJS monorepo with independent services.

Service	Port	Responsibility
`api_gateway`	4000	Route requests, auth, rate limiting
`payment_service`	4001	Payment creation and tracking
`ramp_service`	4002	Fiat on/off ramp
`blockchain_listener`	4003	Monitor Stellar transactions
`conversion_engine`	4004	Crypto-to-USDC conversion
`notification_service`	4005	Webhooks and email

Key API Endpoints

POST   /api/payments            → create a payment
GET    /api/payments/:id        → get payment status
POST   /api/ramp/onramp         → initiate on-ramp
POST   /api/ramp/offramp        → initiate off-ramp
POST   /api/webhooks/register   → register webhook URL
GET    /api/merchants/balance   → get merchant balance

Monitoring & Observability

The backend exposes Prometheus metrics at GET /metrics (HTTP request rate/latency/errors, database query duration, external service call latency, queue depth/throughput, and business metrics like payment volume and success rate — see backend/src/common/metrics).

Directory	Purpose
`prometheus/`	Scrape config, retention, alerting rules
`grafana/`	Auto-provisioned dashboards (system, API, database, queues, business)
`alertmanager/`	Alert routing to Slack/email/PagerDuty, grouping, on-call escalation

Start the whole stack, including monitoring, with docker-compose up, then open:

Tool	URL
Prometheus	http://localhost:9090
Alertmanager	http://localhost:9093
Grafana	http://localhost:3001

Before deploying anywhere shared, populate the alert notification secrets in alertmanager/secrets/ (see alertmanager/README.md).

Frontend

Built with Next.js 14 + TypeScript + Tailwind CSS.

Key Pages

Route	Description
`/checkout/[id]`	Customer payment checkout page
`/dashboard`	Merchant overview and analytics
`/dashboard/payments`	Payment history
`/dashboard/withdrawals`	Withdrawal management
`/dashboard/api-keys`	API key management
`/dashboard/settings`	Merchant settings

Environment Variables

# Stellar
STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
STELLAR_TREASURY_ADDRESS=

# Contracts
PAYMENT_REGISTRY_CONTRACT_ID=
MERCHANT_VAULT_CONTRACT_ID=
ESCROW_CONTRACT_ID=
PAYMENT_SPLIT_CONTRACT_ID=
SUBSCRIPTION_CONTRACT_ID=
FEE_MANAGER_CONTRACT_ID=

# Database
DATABASE_URL=postgresql://localhost:5432/Lumina

# Auth
JWT_SECRET=
API_KEY_SALT=

# Exchange / Conversion
EXCHANGE_API_KEY=
PRICE_ORACLE_URL=

# Notifications
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=

# App
NEXT_PUBLIC_API_URL=http://localhost:4000

Running Tests

# Smart contract tests
cd contracts/escrow_contract && cargo test

# Backend unit tests
cd backend && pnpm test

# Backend e2e tests
cd backend && pnpm test:e2e

# Frontend tests
cd frontend && pnpm test

Contributing

We welcome all contributors! Please read CONTRIBUTING.md before submitting a pull request.

Key areas where you can help:

Soroban smart contracts (Rust)
Backend API services (TypeScript / NestJS)
Frontend UI components (React / Next.js)
Documentation
Testing

Tech Stack

Layer	Technology
Blockchain	Stellar + Soroban
Smart Contracts	Rust
Backend	NestJS (TypeScript)
Frontend	Next.js 14 (TypeScript)
Database	PostgreSQL
Cache	Redis
Queue	BullMQ
Styling	Tailwind CSS
Testing	Vitest, Jest, cargo test

Latest commit

History

Folders and files

Repository files navigation

Lumina

Table of Contents

Overview

What Lumina Does

Settlement Layer

Architecture

Repository Structure

Getting Started

Prerequisites

1. Clone the Repository

2. Install Frontend Dependencies

3. Install Backend Dependencies

4. Set Up Smart Contract Environment

5. Configure Environment Variables

6. Run Local Development

Smart Contracts (Soroban)

Contracts

Build Contracts

Deploy to Testnet

Run Contract Tests

Backend Services

Key API Endpoints

Monitoring & Observability

Frontend

Key Pages

Environment Variables

Running Tests

Contributing

Tech Stack

Roadmap

MVP (v1.0)

v1.1

v2.0

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages