From 3fedfeb84942e05303f97608b9eccad02027ab97 Mon Sep 17 00:00:00 2001 From: Russell Ballestrini Date: Sat, 4 Oct 2025 13:02:07 -0400 Subject: [PATCH] Update state machine documentation to use dash-separated naming - Convert all state names from underscore to dash format in markdown documentation - Ensures consistency across all documentation formats (dot, svg, markdown) - All payment states now use dashes: confirmed-complete, underpaid-refunded, etc. - Maintains consistency with the source dot file which is the canonical reference This completes the documentation naming convention standardization. --- Makefile | 7 +- docs/crypto-payments-state-machine.md | 122 +++--- docs/state-machine.dot | 90 ++-- docs/state-machine.dot.svg | 573 +++++++++++++------------- 4 files changed, 405 insertions(+), 387 deletions(-) diff --git a/Makefile b/Makefile index edfa004..6f47e4d 100644 --- a/Makefile +++ b/Makefile @@ -68,13 +68,18 @@ help: @echo " make sweep-all-doge - Sweep ALL Dogecoin wallet funds to cold storage (dust collection)" @echo " make monero-transactions - View recent wallet transactions" @echo "" + @echo "DOCUMENTATION:" + @echo " make docs/state-machine.dot.svg - Generate state machine diagram from .dot file" + @echo "" @echo "CLEANUP:" @echo " make clean - Remove virtual environment" @echo "" @echo "For more info, see README.md and CRYPTO.rst" -docs/state-machine.dot.svg: +docs/state-machine.dot.svg: docs/state-machine.dot + @echo "Generating state machine diagram from docs/state-machine.dot..." dot -Tsvg docs/state-machine.dot -o docs/state-machine.dot.svg + @echo "✓ Generated docs/state-machine.dot.svg" # ----------------------------------------------------------------------------- # Environment Setup Targets diff --git a/docs/crypto-payments-state-machine.md b/docs/crypto-payments-state-machine.md index 19a9fab..d5003e3 100644 --- a/docs/crypto-payments-state-machine.md +++ b/docs/crypto-payments-state-machine.md @@ -7,8 +7,8 @@ This document visualizes the complete state machine for cryptocurrency payments ```mermaid stateDiagram-v2 [*] --> pending - [*] --> doublepay_refunded : Duplicate payment detected - [*] --> latepay_refunded: Late payment detected + [*] --> doublepay-refunded : Duplicate payment detected + [*] --> latepay-refunded: Late payment detected %% Main payment flow pending --> received : Payment detected in mempool @@ -18,47 +18,47 @@ stateDiagram-v2 %% From received state - multiple possible outcomes %% NOTE: received payments CANNOT expire (detected in mempool, confirmations tracking) received --> confirmed : Sufficient payment + confirmations - received --> confirmed_overpay : Overpayment detected - received --> underpaid_refunded : Underpayment detected - received --> out_of_stock_refunded : Product unavailable + received --> confirmed-overpay : Overpayment detected + received --> underpaid-refunded : Underpayment detected + received --> out-of-stock-refunded : Product unavailable %% Successful payment paths - confirmed --> confirmed_complete : Swept to cold storage - confirmed_complete --> [*] : ✓ Terminal Success + confirmed --> confirmed-complete : Swept to cold storage + confirmed-complete --> [*] : ✓ Terminal Success %% Overpayment refund flow - confirmed_overpay --> confirmed_overpay_refunded : Initiate refund - confirmed_overpay_refunded --> confirmed_overpay_refunded_complete : Refund confirmed - confirmed_overpay_refunded --> confirmed_overpay_not_refunded : No refund wallet configured - confirmed_overpay_refunded_complete --> [*] : ✓ Terminal Success - confirmed_overpay_not_refunded --> [*] : ✓ Terminal Success (Not Refunded) + confirmed-overpay --> confirmed-overpay-refunded : Initiate refund + confirmed-overpay-refunded --> confirmed-overpay-refunded-complete : Refund confirmed + confirmed-overpay-refunded --> confirmed-overpay-not-refunded : No refund wallet configured + confirmed-overpay-refunded-complete --> [*] : ✓ Terminal Success + confirmed-overpay-not-refunded --> [*] : ✓ Terminal Success (Not Refunded) %% Expired payment handling (terminal - late payments create new objects) expired --> [*] : ✓ Terminal Failed (Expired) %% Late payment objects (created separately for payments after expiration) - latepay_refunded --> latepay_refunded_complete : Refund confirmed - latepay_refunded --> latepay_not_refunded : No refund wallet configured - latepay_refunded_complete --> [*] : ✓ Terminal Failed (Refund Complete) - latepay_not_refunded --> [*] : ✓ Terminal Failed (Not Refunded) + latepay-refunded --> latepay-refunded-complete : Refund confirmed + latepay-refunded --> latepay-not-refunded : No refund wallet configured + latepay-refunded-complete --> [*] : ✓ Terminal Failed (Refund Complete) + latepay-not-refunded --> [*] : ✓ Terminal Failed (Not Refunded) %% Underpayment refund flow - underpaid_refunded --> underpaid_refunded_complete : Refund confirmed - underpaid_refunded --> underpaid_not_refunded : No refund wallet configured - underpaid_refunded_complete --> [*] : ✓ Terminal Failed (Refund Complete) - underpaid_not_refunded --> [*] : ✓ Terminal Failed (Not Refunded) + underpaid-refunded --> underpaid-refunded-complete : Refund confirmed + underpaid-refunded --> underpaid-not-refunded : No refund wallet configured + underpaid-refunded-complete --> [*] : ✓ Terminal Failed (Refund Complete) + underpaid-not-refunded --> [*] : ✓ Terminal Failed (Not Refunded) %% Out of stock refund flow - out_of_stock_refunded --> out_of_stock_refunded_complete : Refund confirmed - out_of_stock_refunded --> out_of_stock_not_refunded : No refund wallet configured - out_of_stock_refunded_complete --> [*] : ✓ Terminal Failed (Refund Complete) - out_of_stock_not_refunded --> [*] : ✓ Terminal Failed (Not Refunded) + out-of-stock-refunded --> out-of-stock-refunded-complete : Refund confirmed + out-of-stock-refunded --> out-of-stock-not-refunded : No refund wallet configured + out-of-stock-refunded-complete --> [*] : ✓ Terminal Failed (Refund Complete) + out-of-stock-not-refunded --> [*] : ✓ Terminal Failed (Not Refunded) %% Double payment refund flow - doublepay_refunded --> doublepay_refunded_complete : Refund confirmed - doublepay_refunded --> doublepay_not_refunded : No refund wallet configured - doublepay_refunded_complete --> [*] : ✓ Terminal Failed (Refund Complete) - doublepay_not_refunded --> [*] : ✓ Terminal Failed (Not Refunded) + doublepay-refunded --> doublepay-refunded-complete : Refund confirmed + doublepay-refunded --> doublepay-not-refunded : No refund wallet configured + doublepay-refunded-complete --> [*] : ✓ Terminal Failed (Refund Complete) + doublepay-not-refunded --> [*] : ✓ Terminal Failed (Not Refunded) %% User cancellation (always terminal, only from pending) cancelled --> [*] : ✓ Terminal Failed (Cancelled) @@ -71,19 +71,19 @@ stateDiagram-v2 classDef processingState fill:#cce5ff,stroke:#004085,color:#004085 %% Successful payments (customer received product) - class confirmed,confirmed_complete,confirmed_overpay_refunded_complete,confirmed_overpay_not_refunded successState + class confirmed,confirmed-complete,confirmed-overpay-refunded-complete,confirmed-overpay-not-refunded successState %% Initial/waiting states (entry points that don't come from 'received') - class pending,latepay_refunded,doublepay_refunded initialWaitingState + class pending,latepay-refunded,doublepay-refunded initialWaitingState %% Active refund processing states - class confirmed_overpay_refunded,underpaid_refunded,out_of_stock_refunded refundState + class confirmed-overpay-refunded,underpaid-refunded,out-of-stock-refunded refundState %% Failed payments (customer did not receive product) - class expired,cancelled,latepay_refunded_complete,latepay_not_refunded,underpaid_refunded_complete,underpaid_not_refunded,out_of_stock_refunded_complete,out_of_stock_not_refunded,doublepay_refunded_complete,doublepay_not_refunded failedState + class expired,cancelled,latepay-refunded-complete,latepay-not-refunded,underpaid-refunded-complete,underpaid-not-refunded,out-of-stock-refunded-complete,out-of-stock-not-refunded,doublepay-refunded-complete,doublepay-not-refunded failedState %% Processing states - class received,confirmed_overpay processingState + class received,confirmed-overpay processingState ``` ## Semantic State Groups @@ -94,8 +94,8 @@ The state machine uses semantic groups to categorize states by business logic pu Entry point states that don't transition from `received` - they represent the start of payment flows: - **`pending`** - Initial state for new payment requests -- **`latepay_refunded`** - Initial state for late payment objects (payments received after expiration) -- **`doublepay_refunded`** - Initial state for duplicate payment objects (separate payment instances) +- **`latepay-refunded`** - Initial state for late payment objects (payments received after expiration) +- **`doublepay-refunded`** - Initial state for duplicate payment objects (separate payment instances) **Business Logic**: These states represent separate payment flows and are processed with Priority 0-2 depending on their nature. @@ -103,9 +103,9 @@ Entry point states that don't transition from `received` - they represent the st Customer received their product - invoices are preserved: - **`confirmed`** - Normal successful payment (exact amount, confirmed) -- **`confirmed_complete`** - Confirmed payment that has been swept to cold storage -- **`confirmed_overpay_refunded_complete`** - Overpaid, customer got product + refund -- **`confirmed_overpay_not_refunded`** - Overpaid, customer got product, no refund wallet configured +- **`confirmed-complete`** - Confirmed payment that has been swept to cold storage +- **`confirmed-overpay-refunded-complete`** - Overpaid, customer got product + refund +- **`confirmed-overpay-not-refunded`** - Overpaid, customer got product, no refund wallet configured **Business Logic**: `is_successful_payment() = True`, `should_keep_invoice() = True` @@ -114,18 +114,18 @@ Customer did not receive product - invoices are deleted: - **`expired`** - Payment window expired before any blockchain detection - **`cancelled`** - User cancelled payment (only from pending) -- **`*_refunded_complete`** - Failed payments with completed refunds -- **`*_not_refunded`** - Failed payments with no refund wallet configured +- **`*-refunded-complete`** - Failed payments with completed refunds +- **`*-not-refunded`** - Failed payments with no refund wallet configured **Business Logic**: `is_failed_payment() = True`, `should_keep_invoice() = False` ### 🟡 **Refund Processing States** (Yellow) Active refund workflows - intermediate states: -- **`confirmed_overpay_refunded`** - Overpayment refund in progress (customer got product) -- **`underpaid_refunded`** - Underpayment refund in progress -- **`out_of_stock_refunded`** - Out of stock refund in progress -- **Note**: `latepay_refunded` and `doublepay_refunded` are Initial/Waiting states, not regular refund processing +- **`confirmed-overpay-refunded`** - Overpayment refund in progress (customer got product) +- **`underpaid-refunded`** - Underpayment refund in progress +- **`out-of-stock-refunded`** - Out of stock refund in progress +- **Note**: `latepay-refunded` and `doublepay-refunded` are Initial/Waiting states, not regular refund processing **Business Logic**: Priority 0 processing (highest), actively monitored for confirmation @@ -133,7 +133,7 @@ Active refund workflows - intermediate states: Active payment processing states: - **`received`** - Payment detected on blockchain, being processed -- **`confirmed_overpay`** - Overpayment confirmed, deciding refund action +- **`confirmed-overpay`** - Overpayment confirmed, deciding refund action **Business Logic**: Priority 1-3 processing, confirmation monitoring @@ -153,8 +153,8 @@ All status constants use past-tense naming for consistency: ### **Rule 3: Entry Points vs Transitions** Some states are entry points for new payment objects, not transitions from existing payments: - `pending` - Entry point for new payments -- `latepay_refunded` - Entry point for late payment objects (created after expiration) -- `doublepay_refunded` - Entry point for duplicate payment objects +- `latepay-refunded` - Entry point for late payment objects (created after expiration) +- `doublepay-refunded` - Entry point for duplicate payment objects ### **Rule 4: Invoice Preservation Logic** ```python @@ -168,7 +168,7 @@ should_keep_invoice() = is_successful_payment() The crypto watcher processes payments by priority to ensure proper fund flow and customer service: ### **Priority 0 (Highest): Customer Refunds** -- `doublepay_refunded`, `latepay_refunded`, `underpaid_refunded`, `out_of_stock_refunded` +- `doublepay-refunded`, `latepay-refunded`, `underpaid-refunded`, `out-of-stock-refunded` - **Rationale**: Customer service is highest priority ### **Priority 1: New Incoming Payments** @@ -180,50 +180,50 @@ The crypto watcher processes payments by priority to ensure proper fund flow and - **Rationale**: General processing tasks ### **Priority 3: Auto-Sweep to Shop Owner** -- `confirmed`, `confirmed_overpay` +- `confirmed`, `confirmed-overpay` - **Rationale**: Move confirmed funds to shop owner ### **Priority 4 (Lowest): Restocking Fee Sweeps** -- `*_refunded_complete` states +- `*-refunded-complete` states - **Rationale**: Most dangerous operation, requires high confirmations, done last ## Business Logic Flows ### **Normal Payment Flow** ``` -pending → received → confirmed → confirmed_complete ✅ +pending → received → confirmed → confirmed-complete ✅ ``` Customer pays exact amount, gets product, invoice kept, funds swept to cold storage. ### **Overpayment Flow** ``` -pending → received → confirmed_overpay → confirmed_overpay_refunded → confirmed_overpay_refunded_complete ✅ +pending → received → confirmed-overpay → confirmed-overpay-refunded → confirmed-overpay-refunded-complete ✅ ``` Customer overpays, gets product, gets refund, invoice kept. ### **Late Payment Flow** ``` Original: pending → expired ❌ -New object: latepay_refunded → latepay_refunded_complete ❌ +New object: latepay-refunded → latepay-refunded-complete ❌ ``` Original payment expires. Late payment creates new object, gets refunded, invoice deleted. ### **Underpayment Flow** ``` -pending → received → underpaid_refunded → underpaid_refunded_complete ❌ +pending → received → underpaid-refunded → underpaid-refunded-complete ❌ ``` Customer pays too little, gets refund, no product, invoice deleted. ### **Duplicate Payment Flow** ``` Original: pending → received → confirmed ✅ -Duplicate: doublepay_refunded → doublepay_refunded_complete ❌ +Duplicate: doublepay-refunded → doublepay-refunded-complete ❌ ``` First payment succeeds, duplicate creates separate object and gets refunded. ### **Out of Stock Flow** ``` -pending → received → out_of_stock_refunded → out_of_stock_refunded_complete ❌ +pending → received → out-of-stock-refunded → out-of-stock-refunded-complete ❌ ``` Product unavailable, customer gets refund, no product, invoice deleted. @@ -237,15 +237,15 @@ User cancels before payment detected, invoice deleted. **Successful Terminals** (keep invoice): - `confirmed` - Normal success (awaiting sweep) -- `confirmed_complete` - Normal success + swept to cold storage -- `confirmed_overpay_refunded_complete` - Overpaid + refunded -- `confirmed_overpay_not_refunded` - Overpaid, no refund wallet +- `confirmed-complete` - Normal success + swept to cold storage +- `confirmed-overpay-refunded-complete` - Overpaid + refunded +- `confirmed-overpay-not-refunded` - Overpaid, no refund wallet **Failed Terminals** (delete invoice): - `expired` - Never paid - `cancelled` - User cancelled -- `*_refunded_complete` - Failed + refunded -- `*_not_refunded` - Failed, no refund wallet +- `*-refunded-complete` - Failed + refunded +- `*-not-refunded` - Failed, no refund wallet ## State Transition Validation diff --git a/docs/state-machine.dot b/docs/state-machine.dot index a287170..8c35e25 100644 --- a/docs/state-machine.dot +++ b/docs/state-machine.dot @@ -4,61 +4,61 @@ digraph G { edge [penwidth=1.5, fontsize=10, fontname="Arial"]; "[*]" [shape=circle, label="", width=0.2, fillcolor=black, style=filled]; "pending" [fillcolor="#e7f3ff", fontcolor="#0056b3", color="#0056b3", fontsize=12]; - "doublepay_refunded" [fillcolor="#e7f3ff", fontcolor="#0056b3", color="#0056b3", fontsize=12]; - "latepay_refunded" [fillcolor="#e7f3ff", fontcolor="#0056b3", color="#0056b3", fontsize=12]; + "doublepay-refunded" [fillcolor="#e7f3ff", fontcolor="#0056b3", color="#0056b3", fontsize=12]; + "latepay-refunded" [fillcolor="#e7f3ff", fontcolor="#0056b3", color="#0056b3", fontsize=12]; "received" [fillcolor="#cce5ff", fontcolor="#004085", color="#004085", fontsize=12]; "expired" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; "cancelled" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; "confirmed" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; - "confirmed_complete" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; - "confirmed_overpay" [fillcolor="#cce5ff", fontcolor="#004085", color="#004085", fontsize=12]; - "underpaid_refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; - "out_of_stock_refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; - "confirmed_overpay_refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; - "confirmed_overpay_refunded_complete" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; - "confirmed_overpay_not_refunded" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; - "latepay_refunded_complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "latepay_not_refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "underpaid_refunded_complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "underpaid_not_refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "out_of_stock_refunded_complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "out_of_stock_not_refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "doublepay_refunded_complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; - "doublepay_not_refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "confirmed-complete" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; + "confirmed-overpay" [fillcolor="#cce5ff", fontcolor="#004085", color="#004085", fontsize=12]; + "underpaid-refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; + "out-of-stock-refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; + "confirmed-overpay-refunded" [fillcolor="#fff3cd", fontcolor="#856404", color="#856404", fontsize=12]; + "confirmed-overpay-refunded-complete" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; + "confirmed-overpay-not-refunded" [fillcolor="#d4edda", fontcolor="#155724", color="#155724", fontsize=12]; + "latepay-refunded-complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "latepay-not-refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "underpaid-refunded-complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "underpaid-not-refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "out-of-stock-refunded-complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "out-of-stock-not-refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "doublepay-refunded-complete" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; + "doublepay-not-refunded" [fillcolor="#f8d7da", fontcolor="#721c24", color="#721c24", fontsize=12]; "terminated" [shape=doubleoctagon, fillcolor="#e0e0e0", fontcolor="#333333", color="#333333", fontsize=12]; "[*]" -> "pending"; - "[*]" -> "doublepay_refunded" [label="Duplicate payment detected"]; - "[*]" -> "latepay_refunded" [label="Late payment detected"]; + "[*]" -> "doublepay-refunded" [label="Duplicate payment detected"]; + "[*]" -> "latepay-refunded" [label="Late payment detected"]; "pending" -> "received" [label="Payment detected in mempool"]; "pending" -> "expired" [label="Payment timeout (never received)"]; "pending" -> "cancelled" [label="User cancellation"]; "received" -> "confirmed" [label="Sufficient payment + confirmations"]; - "received" -> "confirmed_overpay" [label="Overpayment detected"]; - "received" -> "underpaid_refunded" [label="Underpayment detected"]; - "received" -> "out_of_stock_refunded" [label="Product unavailable"]; - "confirmed" -> "confirmed_complete" [label="Swept to cold storage"]; - "confirmed_complete" -> "terminated" [label="✓ Terminal Success"]; - "confirmed_overpay" -> "confirmed_overpay_refunded" [label="Initiate refund"]; - "confirmed_overpay_refunded" -> "confirmed_overpay_refunded_complete" [label="Refund confirmed"]; - "confirmed_overpay_refunded" -> "confirmed_overpay_not_refunded" [label="No refund wallet configured"]; - "confirmed_overpay_refunded_complete" -> "terminated" [label="✓ Terminal Success"]; - "confirmed_overpay_not_refunded" -> "terminated" [label="✓ Terminal Success (Not Refunded)"]; + "received" -> "confirmed-overpay" [label="Overpayment detected"]; + "received" -> "underpaid-refunded" [label="Underpayment detected"]; + "received" -> "out-of-stock-refunded" [label="Product unavailable"]; + "confirmed" -> "confirmed-complete" [label="Swept to cold storage"]; + "confirmed-complete" -> "terminated" [label="✓ Terminal Success"]; + "confirmed-overpay" -> "confirmed-overpay-refunded" [label="Initiate refund"]; + "confirmed-overpay-refunded" -> "confirmed-overpay-refunded-complete" [label="Refund confirmed"]; + "confirmed-overpay-refunded" -> "confirmed-overpay-not-refunded" [label="No refund wallet configured"]; + "confirmed-overpay-refunded-complete" -> "terminated" [label="✓ Terminal Success"]; + "confirmed-overpay-not-refunded" -> "terminated" [label="✓ Terminal Success (Not Refunded)"]; "expired" -> "terminated" [label="✓ Terminal Failed (Expired)"]; - "latepay_refunded" -> "latepay_refunded_complete" [label="Refund confirmed"]; - "latepay_refunded" -> "latepay_not_refunded" [label="No refund wallet configured"]; - "latepay_refunded_complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; - "latepay_not_refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; - "underpaid_refunded" -> "underpaid_refunded_complete" [label="Refund confirmed"]; - "underpaid_refunded" -> "underpaid_not_refunded" [label="No refund wallet configured"]; - "underpaid_refunded_complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; - "underpaid_not_refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; - "out_of_stock_refunded" -> "out_of_stock_refunded_complete" [label="Refund confirmed"]; - "out_of_stock_refunded" -> "out_of_stock_not_refunded" [label="No refund wallet configured"]; - "out_of_stock_refunded_complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; - "out_of_stock_not_refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; - "doublepay_refunded" -> "doublepay_refunded_complete" [label="Refund confirmed"]; - "doublepay_refunded" -> "doublepay_not_refunded" [label="No refund wallet configured"]; - "doublepay_refunded_complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; - "doublepay_not_refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; + "latepay-refunded" -> "latepay-refunded-complete" [label="Refund confirmed"]; + "latepay-refunded" -> "latepay-not-refunded" [label="No refund wallet configured"]; + "latepay-refunded-complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; + "latepay-not-refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; + "underpaid-refunded" -> "underpaid-refunded-complete" [label="Refund confirmed"]; + "underpaid-refunded" -> "underpaid-not-refunded" [label="No refund wallet configured"]; + "underpaid-refunded-complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; + "underpaid-not-refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; + "out-of-stock-refunded" -> "out-of-stock-refunded-complete" [label="Refund confirmed"]; + "out-of-stock-refunded" -> "out-of-stock-not-refunded" [label="No refund wallet configured"]; + "out-of-stock-refunded-complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; + "out-of-stock-not-refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; + "doublepay-refunded" -> "doublepay-refunded-complete" [label="Refund confirmed"]; + "doublepay-refunded" -> "doublepay-not-refunded" [label="No refund wallet configured"]; + "doublepay-refunded-complete" -> "terminated" [label="✓ Terminal Failed (Refund Complete)"]; + "doublepay-not-refunded" -> "terminated" [label="✓ Terminal Failed (Not Refunded)"]; "cancelled" -> "terminated" [label="✓ Terminal Failed (Cancelled)"]; } diff --git a/docs/state-machine.dot.svg b/docs/state-machine.dot.svg index 5699780..ac4ce7e 100644 --- a/docs/state-machine.dot.svg +++ b/docs/state-machine.dot.svg @@ -4,385 +4,398 @@ - - + + G - + [*] - + pending - -pending + +pending [*]->pending - - + + - + -doublepay_refunded - -doublepay_refunded +doublepay-refunded + +doublepay-refunded - + -[*]->doublepay_refunded - - -Duplicate payment detected +[*]->doublepay-refunded + + +Duplicate payment detected - + -latepay_refunded - -latepay_refunded +latepay-refunded + +latepay-refunded - + -[*]->latepay_refunded - - -Late payment detected +[*]->latepay-refunded + + +Late payment detected received - -received + +received pending->received - - -Payment detected in mempool + + +Payment detected in mempool expired - -expired + +expired pending->expired - - -Payment timeout (never received) + + +Payment timeout (never received) cancelled - -cancelled + +cancelled pending->cancelled - - -User cancellation + + +User cancellation - - -doublepay_refunded_complete - -doublepay_refunded_complete - - - -doublepay_refunded->doublepay_refunded_complete - - -Refund confirmed - - + -doublepay_not_refunded - -doublepay_not_refunded +doublepay-refunded-complete + +doublepay-refunded-complete - + -doublepay_refunded->doublepay_not_refunded - - -No refund wallet configured +doublepay-refunded->doublepay-refunded-complete + + +Refund confirmed - - -latepay_refunded_complete - -latepay_refunded_complete + + +doublepay-not-refunded + +doublepay-not-refunded - - -latepay_refunded->latepay_refunded_complete - - -Refund confirmed + + +doublepay-refunded->doublepay-not-refunded + + +No refund wallet configured - + -latepay_not_refunded - -latepay_not_refunded +latepay-refunded-complete + +latepay-refunded-complete - + -latepay_refunded->latepay_not_refunded - - -No refund wallet configured +latepay-refunded->latepay-refunded-complete + + +Refund confirmed + + + +latepay-not-refunded + +latepay-not-refunded + + + +latepay-refunded->latepay-not-refunded + + +No refund wallet configured confirmed - -confirmed + +confirmed received->confirmed - - -Sufficient payment + confirmations + + +Sufficient payment + confirmations - - -confirmed_overpay - -confirmed_overpay - - - -received->confirmed_overpay - - -Overpayment detected - - + -underpaid_refunded - -underpaid_refunded +confirmed-overpay + +confirmed-overpay - - -received->underpaid_refunded - - -Underpayment detected + + +received->confirmed-overpay + + +Overpayment detected - + -out_of_stock_refunded - -out_of_stock_refunded +underpaid-refunded + +underpaid-refunded - + + +received->underpaid-refunded + + +Underpayment detected + + + +out-of-stock-refunded + +out-of-stock-refunded + + -received->out_of_stock_refunded - - -Product unavailable +received->out-of-stock-refunded + + +Product unavailable - + terminated - - -terminated + + +terminated - + expired->terminated - - -✓ Terminal Failed (Expired) + + +✓ Terminal Failed (Expired) - + cancelled->terminated - - -✓ Terminal Failed (Cancelled) + + +✓ Terminal Failed (Cancelled) - + + +confirmed-complete + +confirmed-complete + + -confirmed->terminated - - -✓ Terminal Success +confirmed->confirmed-complete + + +Swept to cold storage - - -confirmed_overpay_refunded - -confirmed_overpay_refunded - - + -confirmed_overpay->confirmed_overpay_refunded - - -Initiate refund +confirmed-complete->terminated + + +✓ Terminal Success - - -underpaid_refunded_complete - -underpaid_refunded_complete - - - -underpaid_refunded->underpaid_refunded_complete - - -Refund confirmed - - - -underpaid_not_refunded - -underpaid_not_refunded - - - -underpaid_refunded->underpaid_not_refunded - - -No refund wallet configured - - - -out_of_stock_refunded_complete - -out_of_stock_refunded_complete - - - -out_of_stock_refunded->out_of_stock_refunded_complete - - -Refund confirmed - - - -out_of_stock_not_refunded - -out_of_stock_not_refunded - - - -out_of_stock_refunded->out_of_stock_not_refunded - - -No refund wallet configured - - + -confirmed_overpay_refunded_complete - -confirmed_overpay_refunded_complete +confirmed-overpay-refunded + +confirmed-overpay-refunded - + -confirmed_overpay_refunded->confirmed_overpay_refunded_complete - - -Refund confirmed +confirmed-overpay->confirmed-overpay-refunded + + +Initiate refund - - -confirmed_overpay_not_refunded - -confirmed_overpay_not_refunded + + +underpaid-refunded-complete + +underpaid-refunded-complete - - -confirmed_overpay_refunded->confirmed_overpay_not_refunded - - -No refund wallet configured + + +underpaid-refunded->underpaid-refunded-complete + + +Refund confirmed - - -confirmed_overpay_refunded_complete->terminated - - -✓ Terminal Success + + +underpaid-not-refunded + +underpaid-not-refunded - - -confirmed_overpay_not_refunded->terminated - - -✓ Terminal Success (Not Refunded) - - - -latepay_refunded_complete->terminated - - -✓ Terminal Failed (Refund Complete) - - - -latepay_not_refunded->terminated - - -✓ Terminal Failed (Not Refunded) - - + -underpaid_refunded_complete->terminated - - -✓ Terminal Failed (Refund Complete) +underpaid-refunded->underpaid-not-refunded + + +No refund wallet configured - - -underpaid_not_refunded->terminated - - -✓ Terminal Failed (Not Refunded) + + +out-of-stock-refunded-complete + +out-of-stock-refunded-complete - + + +out-of-stock-refunded->out-of-stock-refunded-complete + + +Refund confirmed + + + +out-of-stock-not-refunded + +out-of-stock-not-refunded + + -out_of_stock_refunded_complete->terminated - - -✓ Terminal Failed (Refund Complete) +out-of-stock-refunded->out-of-stock-not-refunded + + +No refund wallet configured - + + +confirmed-overpay-refunded-complete + +confirmed-overpay-refunded-complete + + + +confirmed-overpay-refunded->confirmed-overpay-refunded-complete + + +Refund confirmed + + + +confirmed-overpay-not-refunded + +confirmed-overpay-not-refunded + + + +confirmed-overpay-refunded->confirmed-overpay-not-refunded + + +No refund wallet configured + + + +confirmed-overpay-refunded-complete->terminated + + +✓ Terminal Success + + + +confirmed-overpay-not-refunded->terminated + + +✓ Terminal Success (Not Refunded) + + + +latepay-refunded-complete->terminated + + +✓ Terminal Failed (Refund Complete) + + + +latepay-not-refunded->terminated + + +✓ Terminal Failed (Not Refunded) + + + +underpaid-refunded-complete->terminated + + +✓ Terminal Failed (Refund Complete) + + + +underpaid-not-refunded->terminated + + +✓ Terminal Failed (Not Refunded) + + -out_of_stock_not_refunded->terminated - - -✓ Terminal Failed (Not Refunded) +out-of-stock-refunded-complete->terminated + + +✓ Terminal Failed (Refund Complete) - - -doublepay_refunded_complete->terminated - - -✓ Terminal Failed (Refund Complete) + + +out-of-stock-not-refunded->terminated + + +✓ Terminal Failed (Not Refunded) - + -doublepay_not_refunded->terminated - - -✓ Terminal Failed (Not Refunded) +doublepay-refunded-complete->terminated + + +✓ Terminal Failed (Refund Complete) + + + +doublepay-not-refunded->terminated + + +✓ Terminal Failed (Not Refunded)