Add comprehensive MONERO.rst documentation

Document the amazing multi-tenant Monero cash register system:
- Multi-tenant architecture with account isolation
- Complete payment flow from checkout to cold storage
- Risk management with confirmation tiers
- Auto-sweep triggered by unlocked funds
- Database schema and payment tracking
- Benefits for all stakeholders

Fixed inaccuracies:
- Removed QR code references (not implemented yet)
- Corrected quote expiration to 60 minutes
- Fixed auto-sweep trigger (unlocked funds, not confirmations)
- Removed automatic quote renewal (quotes expire)
- Streamlined content focus
This commit is contained in:
Russell Ballestrini 2025-09-22 09:34:08 -04:00
parent 3f65ed86d3
commit a6d6860d2a

View file

@ -104,9 +104,9 @@ The complete payment lifecycle demonstrates the system's sophistication:
**2. Customer Checkout**
- Real-time XMR/USD rate fetched from CoinGecko
- Quote generated with 15-minute expiration
- Quote generated with 60-minute expiration
- Unique subaddress created for this specific payment
- Customer sees QR code + payment details
- Customer sees payment address + amount details
**3. Payment Monitoring**
- Crypto watcher polls every 20 seconds
@ -126,7 +126,7 @@ The complete payment lifecycle demonstrates the system's sophistication:
- Purchase and sale emails sent automatically
**5. Auto-Sweep to Cold Storage**
- Confirmed payments trigger automatic sweep
- 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
@ -162,72 +162,10 @@ Shop-configurable thresholds determine confirmation requirements:
**Quote Expiration**
--------------------
- Time-limited quotes prevent rate manipulation
- Configurable expiration (default: 15 minutes)
- Automatic quote renewal for valid payments
- Configurable expiration (default: 60 minutes)
- Quotes expire and require new checkout if time limit exceeded
- Expired payment refund system (when refund address available)
Technology Stack
================
**Infrastructure**
- **monero-wallet-rpc**: Official Monero wallet daemon
- **Remote Nodes**: Public Monero nodes (no local blockchain required)
- **Salt Stack**: Automated deployment and configuration management
- **systemd**: Service management with automatic restart
**Security Features**
- **Account Isolation**: Dedicated Monero accounts per shop
- **RPC Authentication**: Disabled for internal communication, secured by network isolation
- **Automatic Sweeping**: Immediate cold storage transfer
- **Network Hardening**: Localhost-only RPC binding
**Monitoring & Reliability**
- **Health Checks**: Automatic service monitoring via Salt
- **Error Recovery**: Graceful handling of network issues and daemon disconnects
- **Logging**: Comprehensive payment and sweep transaction logging
- **Backup Systems**: Database backups and wallet file protection
Configuration
=============
**Environment Variables**
.. code-block:: bash
# Payment method toggles
export MPS_PAYMENTS_MONERO_ENABLED=True
export MPS_PAYMENTS_STRIPE_ENABLED=True
# Monero RPC configuration
export MPS_MONERO_RPC_URL=http://127.0.0.1:18083/json_rpc
export MPS_MONERO_RPC_USER= # Empty - no auth required
export MPS_MONERO_RPC_PASS= # Empty - no auth required
# Confirmation requirements
export MPS_MONERO_CONFIRMATIONS_PETTY=2
export MPS_MONERO_CONFIRMATIONS_MID=10
export MPS_MONERO_CONFIRMATIONS_HIGH=20
**Salt State Management**
.. code-block:: bash
# Deploy Monero infrastructure
salt 'mps-servers*' state.apply monero
# Deploy payment watcher
salt 'mps-servers*' state.apply monero.crypto-watcher
**Service Management**
.. code-block:: bash
# Check Monero wallet status
systemctl status monero-wallet-rpc.service
# Check payment watcher
systemctl status mps-crypto-watcher.service
# View payment processing logs
journalctl -fu mps-crypto-watcher.service
Why This Is Amazing
===================