✦ Lumipay

Manage every subscription. Pay in any currency. Powered by Stellar.

Lumipay is an open-source subscription management platform for general consumers. Connect your Stellar wallet, add your subscriptions, and let Lumipay handle recurring payments automatically — converting currencies on the fly via Stellar's built-in DEX. No hidden bank fees. No missed renewals. Full transparency.

---

Why Lumipay?

Most people pay 5–12 subscriptions every month across different currencies and billing cycles. Banks charge opaque conversion fees. Payments fail silently. There's no single view of what you're actually spending.

Lumipay fixes this by sitting on top of the Stellar network:

• Unified dashboard — all subscriptions in one place
• Auto-pay — Soroban smart contracts trigger payments on schedule
• Any currency — Stellar's AMM converts at the best available rate
• Transparent fees — Lumipay charges a flat 0.5% on conversions only. No surprises.

---

Tech Stack

Layer	Technology
Blockchain	Stellar (Testnet + Mainnet)
Smart contracts	Soroban (Rust)
Backend	Node.js + Express
Job scheduler	BullMQ + Redis
Database	PostgreSQL
Frontend	Next.js 14 (App Router)
Wallet	Freighter SDK
Monorepo	pnpm workspaces

---

Repository Structure

lumipay/
├── README.md
├── .env.example
├── docker-compose.yml
├── pnpm-workspace.yaml
│
└── packages/
    ├── contracts/                  # Soroban smart contracts (Rust)
    │   └── subscription/
    │       ├── src/
    │       │   └── lib.rs          # Recurring payment contract
    │       └── Cargo.toml
    │
    ├── backend/                    # Node.js API server
    │   ├── src/
    │   │   ├── stellar/
    │   │   │   ├── horizon.js      # Horizon API client
    │   │   │   ├── pathPayment.js  # Conversion + fee logic
    │   │   │   └── keypair.js      # Wallet utilities
    │   │   ├── scheduler/
    │   │   │   ├── queue.js        # BullMQ queue setup
    │   │   │   └── worker.js       # Payment job processor
    │   │   ├── routes/
    │   │   │   ├── subscriptions.js
    │   │   │   ├── wallets.js
    │   │   │   └── payments.js
    │   │   └── db/
    │   │       ├── models.js
    │   │       └── migrations/
    │   ├── package.json
    │   └── .env.example
    │
    └── frontend/                   # Next.js app
        ├── src/
        │   ├── app/
        │   │   ├── dashboard/      # Main subscription view
        │   │   ├── add/            # Add subscription flow
        │   │   └── history/        # Payment history
        │   ├── components/
        │   │   ├── SubscriptionCard.tsx
        │   │   ├── WalletConnect.tsx
        │   │   └── SpendingSummary.tsx
        │   └── lib/
        │       ├── freighter.ts    # Wallet integration
        │       └── api.ts          # Backend client
        └── package.json

---

How the Fee Model Works

Lumipay earns revenue on currency conversion. When a user pays a subscription in a different currency than their wallet holds, the payment routes through Stellar's DEX path payment operation.

Lumipay takes 0.5% of the converted amount before it settles to the merchant.

User wallet (XLM)
      │
      ▼
  Fee deducted (0.5%)  ──▶  Lumipay fee wallet
      │
      ▼
 Path payment via Stellar DEX
      │
      ▼
 Merchant receives (USDC / EUR / target asset)

All fee collection is on-chain and visible to the user. No hidden charges.

// packages/backend/src/stellar/pathPayment.js

const FEE_RATE   = 0.005;                          // 0.5%
const FEE_WALLET = process.env.LUMIPAY_FEE_WALLET;

export async function paySubscription({ sourceKeypair, destAddress, amount, sourceCurrency, destCurrency }) {
  const fee = (parseFloat(amount) * FEE_RATE).toFixed(7);
  const net = (parseFloat(amount) - parseFloat(fee)).toFixed(7);

  // Collect fee first, then send net via path payment
  const pathPaymentOp = Operation.pathPaymentStrictSend({
    sendAsset:   new Asset(sourceCurrency, issuer),
    sendAmount:  net,
    destination: destAddress,
    destAsset:   new Asset(destCurrency, issuer),
    destMin:     (net * 0.98).toFixed(7), // 2% slippage tolerance
    path:        [],
  });
}

---

Getting Started

Prerequisites

• Node.js 18+
• pnpm 8+
• Docker + Docker Compose
• Rust + stellar-cli (for contract development)
• Freighter wallet browser extension

1. Clone the repo

git clone https://github.com/your-username/lumipay.git
cd lumipay

2. Install dependencies

pnpm install

3. Configure environment

cp .env.example .env

Fill in the following in .env:

# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
LUMIPAY_FEE_WALLET=G...              # Your Stellar public key for fees
LUMIPAY_FEE_WALLET_SECRET=S...       # Keep this safe — never commit

# Database
DATABASE_URL=postgresql://lumipay:lumipay@localhost:5432/lumipay

# Redis (for BullMQ)
REDIS_URL=redis://localhost:6379

4. Start local services

docker-compose up -d    # starts PostgreSQL + Redis

5. Run the backend

cd packages/backend
pnpm dev

6. Run the frontend

cd packages/frontend
pnpm dev

Open http://localhost:3000 and connect your Freighter testnet wallet.

---

Stellar Testnet Setup

1. Create a testnet keypair at Stellar Laboratory
2. Fund it using the Friendbot
3. Paste the keypair into your .env
4. The app will use Horizon testnet by default — no real funds needed during development

---

Smart Contract (Soroban)

The subscription contract lives in packages/contracts/subscription. It stores the payment schedule on-chain and can be invoked by the backend scheduler on each billing date.

# Build the contract
cd packages/contracts/subscription
cargo build --target wasm32-unknown-unknown --release

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/subscription.wasm \
  --source YOUR_SECRET_KEY \
  --network testnet

---

Roadmap

Phase 1 — MVP (Weeks 1–6)

• Freighter wallet connect
• Add / edit / delete subscriptions
• Manual one-click payment with fee applied
• Dashboard: all subscriptions + total monthly spend
• Payment history log

Phase 2 — Automation (Weeks 7–12)

• Soroban recurring payment contract
• BullMQ scheduler triggers payments on due date
• Email + push notifications before renewal
• Failed payment retry logic

Phase 3 — Growth (Weeks 13+)

• Multi-wallet support
• Spend analytics by category and currency
• Merchant API (services pull payments directly)
• Mobile app (React Native)
• Lumipay Pro tier — advanced analytics + priority support

---

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m 'Add your feature'
4. Push and open a pull request

Please follow the existing code style and include tests where applicable.

---

License

MIT © Lumipay Contributors

---

Acknowledgements

Built on the Stellar network. Wallet integration via Freighter. Smart contracts powered by Soroban.

---

Lumipay is in active development. Use testnet only until the security audit is complete.