# M95-rust **Stellar-powered payment backend for African POS systems.** M95-rust is a high-performance Rust backend API for payment processing, Stellar blockchain integration, and merchant management. Built for reliability, security, and scalability. ## Architecture This repository contains the complete Rust backend. The Cloudflare Worker proxy has been separated into its own repository for independent deployment. ## Quick Start ### Prerequisites - Rust (stable, 2021 edition) - PostgreSQL ### Setup ```bash # Clone the repository git clone https://github.com/marvelousufelix/M95-rust.git cd M95-rust # Copy environment template cp .env.example .env # Edit .env with your configuration ``` ### Environment Variables | Variable | Required | Default | Description | |---|---|---|---| | `DATABASE_URL` | yes | — | Postgres connection string | | `APP_BIND_ADDR` | no | `127.0.0.1:3000` | Address the HTTP server binds to | | `JWT_SECRET` | yes | — | Secret used to sign merchant session tokens. Generate with `openssl rand -hex 32` | | `WEBHOOK_SECRET` | yes | — | Secret used to verify inbound provider webhooks. Generate with `openssl rand -hex 32` | | `WALLET_ENCRYPTION_KEY` | yes | — | AES-256-GCM key encrypting Stellar wallet secrets at rest. Generate with `openssl rand -hex 32` (must decode to exactly 32 bytes) | | `STELLAR_SYSTEM_WALLET_ADDRESS` | yes | — | Reserved for a future platform settlement/sweep wallet. Validated at startup but not used by deposit detection today | | `STELLAR_HORIZON_URL` | no | `https://horizon-testnet.stellar.org` | Horizon endpoint to poll | | `STELLAR_POLL_INTERVAL_SECS` | no | `60` | How often the deposit-detection worker polls Horizon, per wallet | | `PAYSTACK_SECRET_KEY` | yes | — | Paystack Dashboard → Settings → API Keys & Webhooks. `sk_test_...` for dev, `sk_live_...` only once the business is verified/activated for Transfers | | `CNGN_ISSUER_ADDRESS` | no | — | Verified Stellar issuer address for cNGN tokens. When set, enables SEP-0007 payment URIs for cNGN payment requests. If unset or invalid, cNGN payment requests return `null` for `sep7_uri` (safe default). Leave empty to disable cNGN URIs | | `CORS_ALLOWED_ORIGINS` | no | `http://localhost:3001` | Comma-separated browser origins allowed to call the API | | `COOKIE_SECURE` | no | `true` | Whether the session cookie carries `Secure` | | `COOKIE_SAME_SITE` | no | `lax` | `lax` or `none` | | `LOGIN_RATE_LIMIT_MAX_ATTEMPTS` | no | `5` | Maximum login attempts allowed per time window (protects against password guessing) | | `LOGIN_RATE_LIMIT_WINDOW_SECS` | no | `300` | Time window in seconds for login rate limiting (default: 5 minutes) | ### Running with Docker Postgres ```bash # Start PostgreSQL container docker run -d --name m95-postgres \ -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=m95 \ -p 5432:5432 postgres:16 # Run migrations for f in migrations/*.sql; do docker exec -i m95-postgres psql -U postgres -d m95 < "$f" done # Start the server cargo run ``` ### Running Tests ```bash # Create test database docker exec -i m95-postgres psql -U postgres -c "CREATE DATABASE m95_test;" # Run tests TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/m95_test cargo test ``` ## Tech Stack - **Rust** + [Axum](https://github.com/tokio-rs/axum) — Fast, ergonomic HTTP API framework - **PostgreSQL** via [sqlx](https://github.com/launchbadge/sqlx) — Type-safe, compile-time checked SQL queries - **Stellar** ([Horizon](https://developers.stellar.org/docs/data/horizon)) — Decentralized settlement network - **ed25519-dalek** + **stellar-strkey** — Cryptographically secure Stellar keypair generation - **aes-gcm** — AES-256-GCM encryption for wallet private keys at rest - **JWT** ([jsonwebtoken](https://github.com/Keats/jsonwebtoken)) + **Argon2** — Secure authentication and password hashing - **Tokio** — High-performance async runtime with background Stellar polling worker - **Paystack Transfers API** — Reliable Nigerian bank payouts ## Project Structure ``` src/ api/ HTTP handlers - thin layer for validation and calling services auth/ JWT signing/verification, password hashing, authentication middleware blockchain/ Stellar integration: keypair generation, wallet encryption, Horizon deposit polling, and background worker orchestration models/ Request/response DTOs and database row types services/ Business logic layer (users, wallets, balances, payments, payment_requests, withdrawals) payments/ PaymentProvider trait with implementations: - PaystackProvider (production) - MockProvider (testing) migrations/ SQL schema migrations (managed by sqlx) tests/ Integration test suite covering complete user flows examples/ prove_payment_loop.rs - end-to-end testnet payment demonstration ``` ## Features ✅ **Merchant Authentication** - Secure JWT-based session management ✅ **Stellar Wallet Management** - Automatic keypair generation with encrypted storage ✅ **Payment Requests** - Generate payment links with QR codes ✅ **Deposit Detection** - Background worker polling Horizon for incoming payments ✅ **Balance Tracking** - Multi-currency balance management (XLM, cNGN, etc.) ✅ **Withdrawal System** - Integration with Paystack for bank transfers ✅ **Transaction History** - Complete audit trail of all operations ✅ **Webhook Support** - Receive real-time payment notifications ## Documentation - **[`WORKFLOW.md`](WORKFLOW.md)** - Complete development workflow guide (42 workflows) - **[`API.md`](API.md)** - Full API reference with curl examples - **[`openapi.yaml`](openapi.yaml)** - Machine-readable OpenAPI 3.0 specification - **[`command.txt`](command.txt)** - Quick command reference for copy/paste ## Security - 🔐 **Password Hashing:** Argon2id with salt - 🔐 **Wallet Encryption:** AES-256-GCM for private keys - 🔐 **JWT Authentication:** Secure session tokens with expiry - 🔐 **Webhook Verification:** HMAC signature validation - 🔐 **SQL Injection Protection:** Compile-time checked queries with sqlx ## Deployment The server binds to `127.0.0.1:3000` by default and expects a TLS-terminating reverse proxy (nginx, Caddy, or Cloudflare) in front of it for production use. ### Docker Deployment ```bash # Build image docker build -t m95-rust . # Run container docker run -d \ --name m95-api \ -p 3000:3000 \ --env-file .env \ m95-rust ``` For Cloudflare Worker deployment, see the separate `aframp-cloudflare-worker` repository. ## API Endpoints ### Authentication - `POST /signup` - Create new merchant account - `POST /login` - Authenticate and receive JWT token ### Wallet Management - `POST /wallet/create` - Generate new Stellar wallet - `GET /wallet` - Get wallet details ### Balances & Transactions - `GET /balance` - Get current balance - `GET /transactions` - List transaction history ### Payment Requests - `POST /payment-requests` - Create payment request - `GET /payment-requests` - List payment requests - `GET /payment-requests/:id` - Get specific payment request (public) ### Withdrawals - `POST /withdraw` - Request bank withdrawal - `GET /withdrawals` - List withdrawal history ### System - `GET /health` - Health check endpoint - `GET /me` - Get current user profile ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## Testing Run the complete test suite: ```bash # Unit and integration tests TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/m95_test cargo test # End-to-end testnet example cargo run --example prove_payment_loop ``` ## License See LICENSE file for details. --- ## Repository **GitHub:** https://github.com/marvelousufelix/M95-rust **Owner:** marvelousufelix (Marvelous Felix) **Status:** Active Development Built with ❤️ using Rust 🦀 # M95-rust