lnrpc: expose payment failure reason

lnrpc/routerrpc/router_backend.go

@@ -1143,6 +1143,13 @@ func (r *RouterBackend) MarshallPayment(payment *channeldb.MPPayment) (
 	paymentHash := payment.Info.PaymentHash
 	creationTimeNS := MarshalTimeNano(payment.Info.CreationTime)
 
+	failureReason, err := marshallPaymentFailureReason(
+		payment.FailureReason,
+	)
+	if err != nil {
+		return nil, err
+	}
+
 	return &lnrpc.Payment{
 		PaymentHash:     hex.EncodeToString(paymentHash[:]),
 		Value:           satValue,
@@ -1159,6 +1166,7 @@ func (r *RouterBackend) MarshallPayment(payment *channeldb.MPPayment) (
 		Status:          status,
 		Htlcs:           htlcs,
 		PaymentIndex:    payment.SequenceNum,
+		FailureReason:   failureReason,
 	}, nil
 }
 
@@ -1184,3 +1192,33 @@ func convertPaymentStatus(dbStatus channeldb.PaymentStatus) (
 		return 0, fmt.Errorf("unhandled payment status %v", dbStatus)
 	}
 }
+
+// marshallPaymentFailureReason marshalls the failure reason to the corresponding rpc
+// type.
+func marshallPaymentFailureReason(reason *channeldb.FailureReason) (
+	lnrpc.PaymentFailureReason, error) {
+
+	if reason == nil {
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_NONE, nil
+	}
+
+	switch *reason {
+
+	case channeldb.FailureReasonTimeout:
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_TIMEOUT, nil
+
+	case channeldb.FailureReasonNoRoute:
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_NO_ROUTE, nil
+
+	case channeldb.FailureReasonError:
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_ERROR, nil
+
+	case channeldb.FailureReasonPaymentDetails:
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_INCORRECT_PAYMENT_DETAILS, nil
+
+	case channeldb.FailureReasonInsufficientBalance:
+		return lnrpc.PaymentFailureReason_FAILURE_REASON_INSUFFICIENT_BALANCE, nil
+	}
+
+	return 0, errors.New("unknown failure reason")
+}

lnrpc/rpc.proto

@@ -3053,6 +3053,40 @@ message InvoiceSubscription {
     uint64 settle_index = 2;
 }
 
+enum PaymentFailureReason {
+    /**
+    Payment isn't failed (yet).
+    */
+    FAILURE_REASON_NONE = 0;
+
+    /**
+    There are more routes to try, but the payment timeout was exceeded.
+    */
+    FAILURE_REASON_TIMEOUT = 1;
+
+    /**
+    All possible routes were tried and failed permanently. Or were no
+    routes to the destination at all.
+    */
+    FAILURE_REASON_NO_ROUTE = 2;
+
+    /**
+    A non-recoverable error has occured.
+    */
+    FAILURE_REASON_ERROR = 3;
+
+    /**
+    Payment details incorrect (unknown hash, invalid amt or
+    invalid final cltv delta)
+    */
+    FAILURE_REASON_INCORRECT_PAYMENT_DETAILS = 4;
+
+    /**
+    Insufficient local balance.
+    */
+    FAILURE_REASON_INSUFFICIENT_BALANCE = 5;
+}
+
 message Payment {
     /// The payment hash
     string payment_hash = 1;
@@ -3109,6 +3143,8 @@ message Payment {
     older versions of lnd.
     */
     uint64 payment_index = 15;
+
+    PaymentFailureReason failure_reason = 16;
 }
 
 message HTLCAttempt {

lnrpc/rpc.swagger.json

@@ -3996,9 +3996,25 @@
           "type": "string",
           "format": "uint64",
           "description": "*\nThe creation index of this payment. Each payment can be uniquely identified\nby this index, which may not strictly increment by 1 for payments made in\nolder versions of lnd."
+        },
+        "failure_reason": {
+          "$ref": "#/definitions/lnrpcPaymentFailureReason"
         }
       }
     },
+    "lnrpcPaymentFailureReason": {
+      "type": "string",
+      "enum": [
+        "FAILURE_REASON_NONE",
+        "FAILURE_REASON_TIMEOUT",
+        "FAILURE_REASON_NO_ROUTE",
+        "FAILURE_REASON_ERROR",
+        "FAILURE_REASON_INCORRECT_PAYMENT_DETAILS",
+        "FAILURE_REASON_INSUFFICIENT_BALANCE"
+      ],
+      "default": "FAILURE_REASON_NONE",
+      "description": " - FAILURE_REASON_NONE: *\nPayment isn't failed (yet).\n - FAILURE_REASON_TIMEOUT: *\nThere are more routes to try, but the payment timeout was exceeded.\n - FAILURE_REASON_NO_ROUTE: *\nAll possible routes were tried and failed permanently. Or were no\nroutes to the destination at all.\n - FAILURE_REASON_ERROR: *\nA non-recoverable error has occured.\n - FAILURE_REASON_INCORRECT_PAYMENT_DETAILS: *\nPayment details incorrect (unknown hash, invalid amt or\ninvalid final cltv delta)\n - FAILURE_REASON_INSUFFICIENT_BALANCE: *\nInsufficient local balance."
+    },
     "lnrpcPeer": {
       "type": "object",
       "properties": {