diff --git a/docs/CRYPTO_PROBLEMS.rst b/docs/CRYPTO_PROBLEMS.rst index 4b56a95..ea921cf 100644 --- a/docs/CRYPTO_PROBLEMS.rst +++ b/docs/CRYPTO_PROBLEMS.rst @@ -91,17 +91,27 @@ Transaction Failure Scenarios **Current Behavior**: - First payment completes order -- Second payment automatically swept to shop's cold wallet (✓ RESOLVED) +- Second payment automatically refunded minus 9% restocking fee (✓ RESOLVED) +- Multiple duplicate payments handled correctly (✓ RESOLVED - see "The MONERO DOOM Scenario") **Implemented Solutions**: - ✓ Refund address collected at checkout for potential refunds -- ✓ Auto-sweep prevents duplicate payments from accumulating +- ✓ Duplicate payments detected and marked as STATUS_DOUBLEPAY_REFUND +- ✓ Automatic refund minus 9% restocking fee +- ✓ Safe restocking fee collection using min(balance, expected_fee) logic +- ✓ Priority system ensures refunds complete before fee collection + +**The MONERO DOOM Scenario (✓ RESOLVED)**: +Multiple duplicate payments to same address exposed a critical design flaw where restocking fee sweeps +could steal funds from other payments sharing the same subaddress. The solution implemented: +- Each restocking fee sweep only takes min(balance, expected_fee) +- Prevents fund theft between payments +- 9% fee is exact (network fees deducted from refund, not restocking) +- Priority 4 (lowest) for restocking sweeps with mid-tier confirmation requirements **Remaining Solutions Needed**: -- Detect and flag duplicate payments within time window -- Auto-refund second payment if refund address known - **WANT**: Email notification about duplicate payment -- Add "payment already received" status check +- Add "payment already received" status check in UI 6. Network/Mempool Congestion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -258,11 +268,12 @@ General Solutions Architecture **Auto-Sweep Process**: - Executes immediately after required confirmations are reached - - Uses "sweep_all" to transfer entire account balance to cold wallet + - Sweeps exact payment amounts to cold wallet (not entire balance) - Each shop has dedicated Monero account (prevents cross-shop fund mixing) - Account isolation: Shop A uses account 0, Shop B uses account 1, etc. - - Each payment swept individually using subaddress isolation - - 1:1 payment-to-sweep mapping for clear audit trail and accounting + - Each payment swept individually using precise amount accounting + - 1:1 payment-to-sweep mapping for clear audit trail + - Restocking fees use min(balance, expected_fee) to prevent fund theft - Insufficient balance handling: Payment retries later until funds unlock - Failed sweeps are logged but don't block order fulfillment