engineering/make_post_sell
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases 2 Packages Wiki Activity Actions
make_post_sell/docs/MONERO.rst

200 lines
No EOL
8.3 KiB
ReStructuredText
Raw Blame History

=====================================
Make Post Sell Monero Cash Register
=====================================
**The Ultimate Multi-Tenant Cryptocurrency Payment System**
Overview
========
Make Post Sell's Monero integration provides a **revolutionary multi-tenant cryptocurrency cash register** that enables any shop to accept Monero payments with enterprise-grade security, automatic fund management, and real-time payment tracking.
Our system is **truly amazing** because it solves the complex challenges of cryptocurrency commerce:
- ✅ **Zero-configuration setup** - Shops enable Monero payments with one click
- ✅ **Automatic account isolation** - Each shop gets its own dedicated Monero account
- ✅ **Real-time payment tracking** - Live confirmation monitoring with risk-based thresholds
- ✅ **Automatic fund sweeping** - Hot wallet funds automatically swept to cold storage
- ✅ **Multi-tenant security** - Complete financial isolation between shops
- ✅ **Production-ready scaling** - Handle unlimited shops and payments
Architecture Overview
=====================
Our Monero payment system consists of four key components:
**1. Hot Wallet Infrastructure**
- Single `monero-wallet-rpc` service manages all shops
- Each shop gets a dedicated Monero account (isolated finances)
- Remote node connectivity (no 150GB+ blockchain storage required)
- Secure RPC communication with authentication disabled for internal use
**2. Multi-Tenant Account Management**
- **Account Creation**: Automatic Monero account creation per shop
- **Labeling System**: Clean UUID-based labels for machine identification
- **Tagging System**: Human-readable shop names for easy management
- **Database Tracking**: Account indices stored in `mps_crypto_processor` table
**3. Payment Processing Pipeline**
- **Quote Generation**: Real-time XMR/USD exchange rates with time-limited quotes
- **Payment Monitoring**: 20-second polling cycle checking for incoming payments
- **Confirmation Tracking**: Risk-based confirmation requirements (petty/mid/high tiers)
- **Invoice Finalization**: Automatic product unlocking and email notifications
**4. Auto-Sweep Security**
- **Pooled Sweeping**: Multiple payments swept together for efficiency
- **Account Isolation**: Funds never mix between shops (dedicated accounts)
- **Cold Storage**: Automatic transfer to shop-configured cold wallet addresses
- **Network Fee Tracking**: Comprehensive fee monitoring for accounting
Multi-Tenant Magic
==================
What makes our system **truly amazing** is the multi-tenant architecture:
**Account Isolation**
---------------------
Each shop operates in complete financial isolation:
.. code-block:: text
Wallet Structure:
├── Account 0: Primary (system)
├── Account 1: Shop A (media.unturf.com)
├── Account 2: Shop B (example-store.com)
├── Account 3: Shop C (crypto-shop.net)
└── Account N: Shop N...
**Database Schema**
-------------------
.. code-block:: sql
-- Shop crypto processor configuration
CREATE TABLE mps_crypto_processor (
id UUID PRIMARY KEY,
shop_id UUID NOT NULL,
coin_type VARCHAR(32) NOT NULL, -- 'XMR'
wallet_label VARCHAR(128) NOT NULL, -- Account index: "1", "2", "3"...
sweep_to_address VARCHAR(256) NOT NULL, -- Cold wallet address
enabled BOOLEAN DEFAULT TRUE
);
-- Individual payment tracking
CREATE TABLE mps_crypto_payment (
id UUID PRIMARY KEY,
invoice_id UUID NOT NULL,
account_index INTEGER NOT NULL, -- Links to wallet account
expected_amount BIGINT NOT NULL, -- Atomic units (piconero)
received_amount BIGINT DEFAULT 0,
current_confirmations INTEGER DEFAULT 0,
status VARCHAR(32), -- pending/received/confirmed
swept_amount BIGINT, -- Amount swept to cold storage
swept_tx_hash VARCHAR(128) -- Sweep transaction hash
);
**Payment Flow**
================
The complete payment lifecycle demonstrates the system's sophistication:
**1. Shop Setup (One-Time)**
- Shop owner enters cold wallet address
- System creates dedicated Monero account automatically
- Account tagged with shop domain for identification
**2. Customer Checkout**
- Real-time XMR/USD rate fetched from CoinGecko
- Quote generated with 60-minute expiration
- Unique subaddress created for this specific payment
- Customer sees payment address + amount details
**3. Payment Monitoring**
- Crypto watcher polls every 20 seconds
- Checks all pending payments across all shops
- Updates confirmation counts as blocks are found
- Applies risk-based confirmation requirements:
- **Petty** (< $10): 2 confirmations
- **Mid** ($10-$100): 10 confirmations
- **High** (> $100): 20 confirmations
**4. Payment Confirmation**
- Payment status: ``pending`` → ``received`` → ``confirmed``
- Invoice automatically finalized when confirmed
- Digital products unlocked instantly
- Physical products trigger inventory deduction
- Purchase and sale emails sent automatically
**5. Auto-Sweep to Cold Storage**
- Unlocked funds trigger automatic sweep (funds unlock ~10 blocks after confirmation)
- All unlocked funds in shop's account swept together
- Efficient: Not 1:1 payment-to-sweep mapping
- Secure: Funds immediately moved to shop's cold wallet
- Trackable: Sweep transaction hash recorded
Risk Management
===============
Our system implements sophisticated risk management:
**Confirmation Tiers**
----------------------
Shop-configurable thresholds determine confirmation requirements:
.. code-block:: ini
# Shop settings (per-shop configuration)
payment_risk_threshold_mid_cents = 1000 # $10.00
payment_risk_threshold_high_cents = 10000 # $100.00
# Global Monero confirmation requirements
monero.confirmations.petty = 2 # < $10: Fast confirmation
monero.confirmations.mid = 10 # $10-$100: Standard security
monero.confirmations.high = 20 # > $100: Maximum security
**Overpayment Handling**
------------------------
- Automatic overpayment detection
- Optional refund to customer-provided address
- Graceful handling when no refund address provided
- Status tracking: ``confirmed_overpaid`` for accounting
**Quote Expiration**
--------------------
- Time-limited quotes prevent rate manipulation
- Configurable expiration (default: 60 minutes)
- Quotes expire and require new checkout if time limit exceeded
- Expired payment refund system (when refund address available)
Why This Is Amazing
===================
**For Shop Owners**
- **Zero Crypto Knowledge Required**: Enable Monero payments with one click
- **Complete Financial Control**: Direct payments to your cold wallet
- **Instant Setup**: No wallet management or blockchain syncing
- **Enterprise Security**: Bank-grade isolation and automatic fund management
- **Global Reach**: Accept payments from anywhere, anytime
**For Customers**
- **True Privacy**: Monero's built-in privacy features
- **Low Fees**: Minimal network fees compared to traditional payments
- **Fast Confirmation**: Risk-based confirmation for quick small purchases
- **Global Access**: No geographic restrictions or banking requirements
**For Developers**
- **Production Ready**: Handle unlimited shops and payment volume
- **Clean Architecture**: Well-separated concerns and modular design
- **Comprehensive APIs**: Full payment lifecycle management
- **Monitoring Built-in**: Real-time payment tracking and status updates
- **Extensible Design**: Easy to add new cryptocurrencies
**For Platform Operators**
- **Single Infrastructure**: One wallet serves unlimited shops
- **Automatic Scaling**: No per-shop setup or maintenance required
- **Security by Design**: Account isolation prevents fund mixing
- **Operational Excellence**: Automated deployment and monitoring
The Result: A truly **amazing** multi-tenant cryptocurrency cash register that makes Monero payments as easy as traditional payment processing, while maintaining the privacy, security, and decentralization that makes cryptocurrency revolutionary.
**Welcome to the future of commerce.** 🚀
Reference in a new issue View git blame Copy permalink