REFACTOR: paid flag -> PaymentResult object

cashu/lightning/base.py

@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from typing import AsyncGenerator, Coroutine, Optional, Union
+from enum import Enum
 
 from pydantic import BaseModel
 
@@ -33,36 +34,79 @@ class InvoiceResponse(BaseModel):
     payment_request: Optional[str] = None
     error_message: Optional[str] = None
 
+class PaymentResult(Enum):
+    FAILED = 0
+    SETTLED = 1
+    PENDING = 2
+
+    UNKNOWN = 3
+
+    def __str__(self):
+        return self.name
+
+    # We assume `None` is `FAILED`
+    @classmethod
+    def from_paid_flag(cls, paid: Optional[bool]):
+        if paid is None or paid == False:
+            return cls.FAILED
+        elif paid == True:
+            return cls.SETTLED
 
 class PaymentResponse(BaseModel):
+    result: PaymentResult
     ok: Optional[bool] = None  # True: paid, False: failed, None: pending or unknown
     checking_id: Optional[str] = None
     fee: Optional[Amount] = None
     preimage: Optional[str] = None
     error_message: Optional[str] = None
 
+    @property
+    def pending(self) -> bool:
+        return self.result == PaymentResult.PENDING
+
+    @property
+    def settled(self) -> bool:
+        return self.result == PaymentResult.SETTLED
+
+    @property
+    def failed(self) -> bool:
+        return self.result == PaymentResult.FAILED
+
+    @property
+    def unknown(self) -> bool:
+        return self.result == PaymentResult.UNKNOWN
 
 class PaymentStatus(BaseModel):
+    result: PaymentResult
     paid: Optional[bool] = None
     fee: Optional[Amount] = None
     preimage: Optional[str] = None
+    error_message: Optional[str] = None
 
     @property
     def pending(self) -> bool:
-        return self.paid is not True
+        return self.result == PaymentResult.PENDING
+
+    @property
+    def settled(self) -> bool:
+        return self.result == PaymentResult.SETTLED
 
     @property
     def failed(self) -> bool:
-        return self.paid is False
+        return self.result == PaymentResult.FAILED
+
+    @property
+    def unknown(self) -> bool:
+        return self.result == PaymentResult.UNKNOWN
 
     def __str__(self) -> str:
-        if self.paid is True:
+        if self.result == PaymentResult.SETTLED:
             return "settled"
-        elif self.paid is False:
+        elif self.result == PaymentResult.FAILED:
             return "failed"
-        elif self.paid is None:
+        elif self.result == PaymentResult.PENDING:
             return "still pending"
-        else:
+        else: # self.result == PaymentResult.UNKNOWN:
             return "unknown (should never happen)"
 
 

cashu/lightning/clnrest.py

@@ -23,8 +23,33 @@
     PaymentStatus,
     StatusResponse,
     Unsupported,
+    PaymentResult,
 )
 
+# https://docs.corelightning.org/reference/lightning-pay
+PAYMENT_STATUSES = {
+    "complete": True,
+    "pending": None,
+    "failed": False,
+}
+PAYMENT_RESULT_MAP = {
+    "complete": PaymentResult.SETTLED,
+    "pending": PaymentResult.PENDING,
+    "failed": PaymentResult.FAILED,
+}
+
+# https://docs.corelightning.org/reference/lightning-listinvoices
+INVOICE_STATUSES = {
+    "paid": True,
+    "unpaid": None,
+    "expired": False,
+}
+INVOICE_RESULT_MAP = {
+    "paid": PaymentResult.SETTLED,
+    "unpaid": PaymentResult.PENDING,
+    "expired": PaymentResult.FAILED,
+}
+
 
 class CLNRestWallet(LightningBackend):
     supported_units = set([Unit.sat, Unit.msat])
@@ -169,6 +194,7 @@ async def pay_invoice(
             invoice = decode(quote.request)
         except Bolt11Exception as exc:
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -179,6 +205,7 @@ async def pay_invoice(
         if not invoice.amount_msat or invoice.amount_msat <= 0:
             error_message = "0 amount invoices are not allowed"
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -205,6 +232,7 @@ async def pay_invoice(
                 error_message = "mint does not support MPP"
                 logger.error(error_message)
                 return PaymentResponse(
+                    result=PaymentResult.FAILED,
                     ok=False,
                     checking_id=None,
                     fee=None,
@@ -220,6 +248,7 @@ async def pay_invoice(
             except Exception:
                 error_message = r.text
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -229,21 +258,13 @@ async def pay_invoice(
 
         data = r.json()
 
-        if data["status"] != "complete":
-            return PaymentResponse(
-                ok=False,
-                checking_id=None,
-                fee=None,
-                preimage=None,
-                error_message="payment failed",
-            )
-
         checking_id = data["payment_hash"]
         preimage = data["payment_preimage"]
         fee_msat = data["amount_sent_msat"] - data["amount_msat"]
 
         return PaymentResponse(
-            ok=self.statuses.get(data["status"]),
+            result=PAYMENT_RESULT_MAP[data["status"]],
+            ok=PAYMENT_STATUSES[data["status"]],
             checking_id=checking_id,
             fee=Amount(unit=Unit.msat, amount=fee_msat) if fee_msat else None,
             preimage=preimage,
@@ -261,10 +282,13 @@ async def get_invoice_status(self, checking_id: str) -> PaymentStatus:
 
             if r.is_error or "message" in data or data.get("invoices") is None:
                 raise Exception("error in cln response")
-            return PaymentStatus(paid=self.statuses.get(data["invoices"][0]["status"]))
+            return PaymentStatus(
+                result=INVOICE_RESULT_MAP[data["invoices"][0]["status"]],
+                paid=INVOICE_STATUSES[data["invoices"][0]["status"]],
+            )
         except Exception as e:
             logger.error(f"Error getting invoice status: {e}")
-            return PaymentStatus(paid=None)
+            return PaymentStatus(result=PaymentResult.UNKNOWN, paid=None)
 
     async def get_payment_status(self, checking_id: str) -> PaymentStatus:
         r = await self.client.post(
@@ -293,13 +317,14 @@ async def get_payment_status(self, checking_id: str) -> PaymentStatus:
                 preimage = pay["preimage"]
 
             return PaymentStatus(
-                paid=self.statuses.get(pay["status"]),
+                result=PAYMENT_RESULT_MAP[pay["status"]],
+                paid=PAYMENT_STATUSES[pay["status"]],
                 fee=Amount(unit=Unit.msat, amount=fee_msat) if fee_msat else None,
                 preimage=preimage,
             )
         except Exception as e:
             logger.error(f"Error getting payment status: {e}")
-            return PaymentStatus(paid=None)
+            return PaymentStatus(result=PaymentResult.UNKNOWN, paid=None)
 
     async def paid_invoices_stream(self) -> AsyncGenerator[str, None]:
         # call listinvoices to determine the last pay_index

cashu/lightning/corelightningrest.py

@@ -22,9 +22,33 @@
     PaymentStatus,
     StatusResponse,
     Unsupported,
+    PaymentResult,
 )
 from .macaroon import load_macaroon
 
+# https://docs.corelightning.org/reference/lightning-pay
+PAYMENT_STATUSES = {
+    "complete": True,
+    "pending": None,
+    "failed": False,
+}
+PAYMENT_RESULT_MAP = {
+    "complete": PaymentResult.SETTLED,
+    "pending": PaymentResult.PENDING,
+    "failed": PaymentResult.FAILED,
+}
+
+# https://docs.corelightning.org/reference/lightning-listinvoices
+INVOICE_STATUSES = {
+    "paid": True,
+    "unpaid": None,
+    "expired": False,
+}
+INVOICE_RESULT_MAP = {
+    "paid": PaymentResult.SETTLED,
+    "unpaid": PaymentResult.PENDING,
+    "expired": PaymentResult.FAILED,
+}
 
 class CoreLightningRestWallet(LightningBackend):
     supported_units = set([Unit.sat, Unit.msat])
@@ -162,6 +186,7 @@ async def pay_invoice(
             invoice = decode(quote.request)
         except Bolt11Exception as exc:
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -172,6 +197,7 @@ async def pay_invoice(
         if not invoice.amount_msat or invoice.amount_msat <= 0:
             error_message = "0 amount invoices are not allowed"
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -197,6 +223,7 @@ async def pay_invoice(
             except Exception:
                 error_message = r.text
             return PaymentResponse(
+                result=PaymentResult.FAILED,
                 ok=False,
                 checking_id=None,
                 fee=None,
@@ -206,21 +233,13 @@ async def pay_invoice(
 
         data = r.json()
 
-        if data["status"] != "complete":
-            return PaymentResponse(
-                ok=False,
-                checking_id=None,
-                fee=None,
-                preimage=None,
-                error_message="payment failed",
-            )
-
         checking_id = data["payment_hash"]
         preimage = data["payment_preimage"]
         fee_msat = data["amount_sent_msat"] - data["amount_msat"]
 
         return PaymentResponse(
-            ok=self.statuses.get(data["status"]),
+            result=PAYMENT_RESULT_MAP[data["status"]],
+            ok=PAYMENT_STATUSES[data["status"]],
             checking_id=checking_id,
             fee=Amount(unit=Unit.msat, amount=fee_msat) if fee_msat else None,
             preimage=preimage,
@@ -238,10 +257,13 @@ async def get_invoice_status(self, checking_id: str) -> PaymentStatus:
 
             if r.is_error or "error" in data or data.get("invoices") is None:
                 raise Exception("error in cln response")
-            return PaymentStatus(paid=self.statuses.get(data["invoices"][0]["status"]))
+            return PaymentStatus(
+                result=INVOICE_RESULT_MAP[data["invoices"][0]["status"]],
+                paid=INVOICE_STATUSES[data["invoices"][0]["status"]],
+            )
         except Exception as e:
             logger.error(f"Error getting invoice status: {e}")
-            return PaymentStatus(paid=None)
+            return PaymentStatus(result=PaymentResult.UNKNOWN, paid=None)
 
     async def get_payment_status(self, checking_id: str) -> PaymentStatus:
         r = await self.client.get(
@@ -270,13 +292,14 @@ async def get_payment_status(self, checking_id: str) -> PaymentStatus:
                 preimage = pay["preimage"]
 
             return PaymentStatus(
-                paid=self.statuses.get(pay["status"]),
+                result=INVOICE_RESULT_MAP[pay["status"]],
+                paid=INVOICE_STATUSES[pay["status"]],
                 fee=Amount(unit=Unit.msat, amount=fee_msat) if fee_msat else None,
                 preimage=preimage,
             )
         except Exception as e:
             logger.error(f"Error getting payment status: {e}")
-            return PaymentStatus(paid=None)
+            return PaymentStatus(result=PaymentResult.UNKNOWN, paid=None)
 
     async def paid_invoices_stream(self) -> AsyncGenerator[str, None]:
         # call listinvoices to determine the last pay_index

cashu/lightning/fake.py

@@ -25,6 +25,7 @@
     PaymentResponse,
     PaymentStatus,
     StatusResponse,
+    PaymentResult,
 )
 
 
@@ -158,14 +159,17 @@ async def pay_invoice(self, quote: MeltQuote, fee_limit: int) -> PaymentResponse
                 raise ValueError("Invoice already paid")
 
             return PaymentResponse(
+                result=PaymentResult.SETTLED,
                 ok=True,
                 checking_id=invoice.payment_hash,
                 fee=Amount(unit=self.unit, amount=1),
                 preimage=self.payment_secrets.get(invoice.payment_hash) or "0" * 64,
             )
         else:
             return PaymentResponse(
-                ok=False, error_message="Only internal invoices can be used!"
+                result=PaymentResult.FAILED,
+                ok=False,
+                error_message="Only internal invoices can be used!",
             )
 
     async def get_invoice_status(self, checking_id: str) -> PaymentStatus:
@@ -176,10 +180,16 @@ async def get_invoice_status(self, checking_id: str) -> PaymentStatus:
         else:
             paid = False
 
-        return PaymentStatus(paid=paid)
+        return PaymentStatus(
+            result=PaymentResult.from_paid_flag(paid),
+            paid=paid,
+        )
 
     async def get_payment_status(self, _: str) -> PaymentStatus:
-        return PaymentStatus(paid=settings.fakewallet_payment_state)
+        return PaymentStatus(
+            result=PaymentResult.from_paid_flag(settings.fakewallet_payment_state),
+            paid=settings.fakewallet_payment_state,
+        )
 
     async def get_payment_quote(
         self, melt_quote: PostMeltQuoteRequest