lnrpc+payments+routing: expose attributable failure hold times via RPC

Add a hold_times field to the Failure proto message so that callers of
SendPaymentV2 can see per-hop hold times reported via attributable
errors. The hold times are persisted in the KV store (backward
compatible via trailing optional read) and populated in both the
database and streaming RPC paths.

Changes:
- lnrpc/lightning.proto: add repeated uint32 hold_times = 10
- payments/db: add HoldTimes to HTLCFailInfo + KV serialization
- routing: copy HoldTimes from ForwardingError to HTLCFailInfo
- lnrpc/routerrpc: populate HoldTimes in both marshallHtlcFailure
  and marshallError

Author: GeorgeTsagk

lnrpc/lightning.pb.go

@@ -5142,6 +5142,15 @@ message Failure {
 
     // A failure type-dependent block height.
     uint32 height = 9;
+
+    /*
+    An array of hold times (in 100ms units) as reported by the nodes along
+    the route via attributable errors. The first element corresponds to the
+    first hop after the sender, with greater indices indicating nodes
+    further along the route. Multiply by 100 to get milliseconds. This
+    field is only populated when the error includes attribution data.
+    */
+    repeated uint32 hold_times = 10;
 }
 
 message ChannelUpdate {

lnrpc/lightning.proto

@@ -5127,6 +5127,14 @@
           "type": "integer",
           "format": "int64",
           "description": "A failure type-dependent block height."
+        },
+        "hold_times": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "description": "An array of hold times (in 100ms units) as reported by the nodes along\nthe route via attributable errors. The first element corresponds to the\nfirst hop after the sender, with greater indices indicating nodes\nfurther along the route. Multiply by 100 to get milliseconds. This\nfield is only populated when the error includes attribution data."
         }
       }
     },

lnrpc/lightning.swagger.json

@@ -860,6 +860,14 @@
           "type": "integer",
           "format": "int64",
           "description": "A failure type-dependent block height."
+        },
+        "hold_times": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "description": "An array of hold times (in 100ms units) as reported by the nodes along\nthe route via attributable errors. The first element corresponds to the\nfirst hop after the sender, with greater indices indicating nodes\nfurther along the route. Multiply by 100 to get milliseconds. This\nfield is only populated when the error includes attribution data."
         }
       }
     },

lnrpc/routerrpc/router.swagger.json

@@ -1546,6 +1546,7 @@ func marshallHtlcFailure(failure *paymentsdb.HTLCFailInfo) (*lnrpc.Failure,
 
 	rpcFailure := &lnrpc.Failure{
 		FailureSourceIndex: failure.FailureSourceIndex,
+		HoldTimes:          failure.HoldTimes,
 	}
 
 	switch failure.Reason {
@@ -1614,6 +1615,7 @@ func marshallError(sendError error) (*lnrpc.Failure, error) {
 	fErr, ok := rtErr.(*htlcswitch.ForwardingError)
 	if ok {
 		response.FailureSourceIndex = uint32(fErr.FailureSourceIdx)
+		response.HoldTimes = fErr.HoldTimes
 	}
 
 	return response, nil

lnrpc/routerrpc/router_backend.go

@@ -2071,7 +2071,25 @@ func serializeHTLCFailInfo(w io.Writer, f *HTLCFailInfo) error {
 		return err
 	}
 
-	return WriteElements(w, byte(f.Reason), f.FailureSourceIndex)
+	err := WriteElements(w, byte(f.Reason), f.FailureSourceIndex)
+	if err != nil {
+		return err
+	}
+
+	// Write hold times count followed by each value. This is appended
+	// after the original fields for backward compatibility — old readers
+	// will simply stop reading at the end of FailureSourceIndex.
+	numHoldTimes := uint16(len(f.HoldTimes))
+	if err := WriteElements(w, numHoldTimes); err != nil {
+		return err
+	}
+	for _, ht := range f.HoldTimes {
+		if err := WriteElements(w, ht); err != nil {
+			return err
+		}
+	}
+
+	return nil
 }
 
 // deserializeHTLCFailInfo deserializes the details of a failed htlc including
@@ -2117,5 +2135,28 @@ func deserializeHTLCFailInfo(r io.Reader) (*HTLCFailInfo, error) {
 	}
 	f.Reason = HTLCFailReason(reason)
 
+	// Read hold times if present. Old data won't have this field, so we
+	// treat EOF as "no hold times".
+	var numHoldTimes uint16
+	if err := ReadElements(r, &numHoldTimes); err != nil {
+		// If there's no more data, this is old format — return
+		// without hold times.
+		if errors.Is(err, io.EOF) ||
+			errors.Is(err, io.ErrUnexpectedEOF) {
+
+			return f, nil
+		}
+
+		return nil, err
+	}
+	if numHoldTimes > 0 {
+		f.HoldTimes = make([]uint32, numHoldTimes)
+		for i := range f.HoldTimes {
+			if err := ReadElements(r, &f.HoldTimes[i]); err != nil {
+				return nil, err
+			}
+		}
+	}
+
 	return f, nil
 }

payments/db/kv_store.go

@@ -298,6 +298,12 @@ type HTLCFailInfo struct {
 	// field will be populated when the failure reason is either
 	// HTLCFailMessage or HTLCFailUnknown.
 	FailureSourceIndex uint32
+
+	// HoldTimes is an array of hold times (in 100ms units) as reported by
+	// nodes along the route via attributable errors. The first element
+	// corresponds to the first hop after the sender. This field is only
+	// populated when the error includes attribution data.
+	HoldTimes []uint32
 }
 
 // MPPaymentState wraps a series of info needed for a given payment, which is

payments/db/payment.go

@@ -484,7 +484,7 @@ func testKVStoreSubscribeFail(t *testing.T, registerAttempt bool) {
 		if err != nil {
 			t.Fatalf("unable to fail htlc: %v", err)
 		}
-		if *htlcAttempt.Failure != failInfo {
+		if !reflect.DeepEqual(*htlcAttempt.Failure, failInfo) {
 			t.Fatalf("unexpected fail info returned")
 		}
 	}

routing/control_tower_test.go

@@ -1096,6 +1096,7 @@ func marshallError(sendError error, time time.Time) *paymentsdb.HTLCFailInfo {
 	ok = errors.As(rtErr, &fErr)
 	if ok {
 		response.FailureSourceIndex = uint32(fErr.FailureSourceIdx)
+		response.HoldTimes = fErr.HoldTimes
 	}
 
 	return response