OpenPleb is a platform for matching users that want to pay a banking QR with bitcoin, and earners that want to earn bitcoin for paying the users offers.

This project is under construction, and we are working on it actively. It is not considered ready for production use.

• bond creation (use cashu tokens as bonds, to ensure incentives for both parties are aligned)
  • Issue bond tokens
  • store and handle bond tokens locally
• offer creation
  • offer creation UX (scan bank QR and enter amount)
  • offer validation (bond)
  • Lightning payment & validation
  • Mint and store ecash
  • List offer and persistence
  • offer live updates
  • offer expiry
• Claiming offers
  • claim UX (select offer)
  • claim validation (bond)
  • claim expiry
• paying offer
  • display payment details (payment out-of-band)
  • upload receipt UX
  • receipt live updates
• receipt aproval
  • Approve receipt UX
    • Dispurse funds to local wallet (cashu token)
    • auto withdraw (to ln adress)
  • Reject receipt UX
  • open dispute
• review system
  • user reviews
  • admin user/review inspection
• resolve conflicts
  • admin portal
  • Handle bonds
  • handle refunds
• admin portal
  • manage disputes
  • manage offers
  • manage wallet
  • manage users
  • manage subscriptions

The architecture is built on the monorepo pattern. All code can be found in the packages directory. The backend is written in TypeScript and uses bun.js as the runtime and elysia.js as the API framework. The frontend is written in SvelteKit. For persistence, PostgreSQL is used with drizzle as the ORM. Shared logic is placed in the common package.

The architecture contains 4 roles:

1. Maker: A user who wants to pay a banking QR with bitcoin.
2. Taker: An earner who wants to earn bitcoin for paying the users offers.
3. Server: Platform facilitating the matching between makers and takers.
4. Mint: Custodian while a match is in progress.

Fiat banking usually doesn't offer open protocols that would allow us to make atomic swaps. Thus, we have to rely on participants to act in their best intrest, to preserve their bonds. Disputes are handled in the following way:

• bun.js
• docker
• docker-compose

1. change the .env files accordingly (see .env.example for an example)
2. run docker-compose up to start the local database
3. navigate to packages/common and run bun i && bun run db:push to migrate the database schema
4. navigate to packages/backend and run bun i && bun run dev to start the backend server
5. navigate to packages/frontend and run bun i && bun run dev to start the frontend development server

IMPORTANT: WHEN RUNNING IN PRODUCTION, YOU NEED TO CONFIGURE THE ENVIRONMENT VARIABLES FOR YOUR OWN ENVIRONMENT! ESPACIALLY THE OPENPLEB_DATABASE_URL SHOULD BE CHANGED TO USE NON DEFAULT CREDENTIALS

OpenPleb requires several environment variables to be configured for proper operation. Below are instructions for configuring environment variables for both local development and Docker deployment.

For local development, you need to create .env files in each package directory by copying the corresponding .env.example files:

# For the backend
cp packages/backend/.env.example packages/backend/.env

# For the frontend
cp packages/frontend/.env.example packages/frontend/.env

# For common code
cp packages/common/.env.example packages/common/.env

The backend requires the following environment variables in packages/backend/.env:

# Database connection string
OPENPLEB_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres

# Frontend URL for CORS and other connectivity
OPENPLEB_FRONTEND_URL=localhost:5137

# Port on which the backend server will listen
OPENPLEB_PORT=3004

# Log file location
OPENPLEB_LOG_FILE_NAME="../../data/logs/app.log"

# Log level in the app: valid values: debug, info, error, warning, fatal
OPENPLEB_LOG_LEVEL=debug

# Seed phrase for Cashu wallet - KEEP THIS SECRET
OPENPLEB_CASHU_SEED_PHRASE="because oxygen subway review excuse elder coconut kingdom govern scrub enact minimum"

# Platform fee settings
OPENPLEB_PLATFORM_FEE_PERCENTAGE=1
OPENPLEB_PLATFORM_FEE_FLAT_RATE=100

# Taker fee settings
OPENPLEB_TAKER_FEE_PERCENTAGE=2
OPENPLEB_TAKER_FEE_FLAT_RATE=100

# Bond settings
OPENPLEB_BOND_PERCENTAGE=10
OPENPLEB_BOND_FLAT_RATE=500

# Mint service URL
OPENPLEB_MINT_URL=http://localhost:3338

# Currency settings
OPENPLEB_CURRENCY=KRW

# Maximum fiat amount allowed
OPENPLEB_MAX_FIAT_AMOUNT=100000

All these environment variables are required and checked at application startup. The service will not start if any of these variables are missing.

The frontend requires the following environment variables in packages/frontend/.env:

# Backend API URL
PUBLIC_BACKEND_URL=http://localhost:3004
# API version
PUBLIC_API_VERSION=v1

The common package requires the following environment variables in packages/common/.env:

OPENPLEB_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres

For Docker deployment, environment variables are configured in multiple places:

The docker-compose.yml file contains environment variables for each service. Here's a basic configuration:

Important notes for Docker Compose configuration:

• When working with Docker Compose, use service names as hostnames for internal service communication (e.g., postgres, backend, frontend, nutshell)
• Ensure all services are on the same network

The Dockerfile.frontend file contains the environment variables for the frontend.

When deploying with Docker, make sure to place your environment files under data/config:

data/config/
├── admin-frontend
│   └── .env
├── backend
│   └── .env
├── db
│   └── .env
└── frontend
    └── .env

Each service will automatically load its configuration from the corresponding .env file in this directory.

# Build and start all services
docker compose up --build
# OR just start all services without building again
docker compose up

# View logs
docker compose logs -f

# Stop all services
docker compose down