lncli: Add --route_hints flag to sendpayment, queryroutes (fixes #6601)

Adds an integration test to verify SendPayment successfully uses
invoice route hints for payments involving private channels.

Author: appilon

cmd/commands/cmd_payments.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"crypto/rand"
 	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -254,6 +255,13 @@ var SendPaymentCommand = cli.Command{
 			Name:  "keysend",
 			Usage: "will generate a pre-image and encode it in the sphinx packet, a dest must be set [experimental]",
 		},
+		cli.StringFlag{
+			Name: "route_hints",
+			Usage: "route hints to reach the destination, " +
+				"encoded as a JSON string. " +
+				"See the RouteHint struct in the RPC " +
+				"definition for the full format.",
+		},
 	),
 	Action: SendPayment,
 }
@@ -362,6 +370,19 @@ func SendPayment(ctx *cli.Context) error {
 
 		req.PaymentAddr = payAddr
 
+		if ctx.IsSet("route_hints") {
+			routeHintsJSON := ctx.String("route_hints")
+			var routeHints []*lnrpc.RouteHint
+
+			err := json.Unmarshal([]byte(routeHintsJSON), &routeHints)
+			if err != nil {
+				return fmt.Errorf("error unmarshaling route_hints "+
+					"json: %w", err)
+			}
+
+			req.RouteHints = routeHints
+		}
+
 		return SendPaymentRequest(
 			ctx, req, conn, conn, routerRPCSendPayment,
 		)
@@ -473,6 +494,19 @@ func SendPayment(ctx *cli.Context) error {
 
 	req.PaymentAddr = payAddr
 
+	if ctx.IsSet("route_hints") {
+		routeHintsJSON := ctx.String("route_hints")
+		var routeHints []*lnrpc.RouteHint
+
+		err := json.Unmarshal([]byte(routeHintsJSON), &routeHints)
+		if err != nil {
+			return fmt.Errorf("error unmarshaling route_hints "+
+				"json: %w", err)
+		}
+
+		req.RouteHints = routeHints
+	}
+
 	return SendPaymentRequest(ctx, req, conn, conn, routerRPCSendPayment)
 }
 
@@ -928,6 +962,19 @@ func payInvoice(ctx *cli.Context) error {
 		Cancelable:        ctx.Bool(cancelableFlag.Name),
 	}
 
+	if ctx.IsSet("route_hints") {
+		routeHintsJSON := ctx.String("route_hints")
+		var routeHints []*lnrpc.RouteHint
+
+		err := json.Unmarshal([]byte(routeHintsJSON), &routeHints)
+		if err != nil {
+			return fmt.Errorf("error unmarshaling route_hints "+
+				"json: %w", err)
+		}
+
+		req.RouteHints = routeHints
+	}
+
 	return SendPaymentRequest(ctx, req, conn, conn, routerRPCSendPayment)
 }
 
@@ -1154,6 +1201,13 @@ var queryRoutesCommand = cli.Command{
 		blindedBaseFlag,
 		blindedPPMFlag,
 		blindedCLTVFlag,
+		cli.StringFlag{
+			Name: "route_hints",
+			Usage: "route hints to reach the destination, " +
+				"encoded as a JSON string. " +
+				"See the RouteHint struct in the RPC " +
+				"definition for the full format.",
+		},
 	},
 	Action: actionDecorator(queryRoutes),
 }
@@ -1248,6 +1302,19 @@ func queryRoutes(ctx *cli.Context) error {
 		BlindedPaymentPaths: blindedRoutes,
 	}
 
+	if ctx.IsSet("route_hints") {
+		routeHintsJSON := ctx.String("route_hints")
+		var routeHints []*lnrpc.RouteHint
+
+		err := json.Unmarshal([]byte(routeHintsJSON), &routeHints)
+		if err != nil {
+			return fmt.Errorf("error unmarshaling route_hints "+
+				"json: %w", err)
+		}
+
+		req.RouteHints = routeHints
+	}
+
 	route, err := client.QueryRoutes(ctxc, req)
 	if err != nil {
 		return err

itest/list_on_test.go

@@ -177,6 +177,10 @@ var allTestCases = []*lntest.TestCase{
 		Name:     "send direct payment simple taproot",
 		TestFunc: testSendDirectPaymentSimpleTaproot,
 	},
+	{
+		Name:     "sendpayment with route hints",
+		TestFunc: testSendPaymentWithRouteHints,
+	},
 	{
 		Name:     "immediate payment after channel opened",
 		TestFunc: testPaymentFollowingChannelOpen,

itest/lnd_payment_test.go

@@ -1396,3 +1396,48 @@ func testSendPaymentKeysendMPPFail(ht *lntest.HarnessTest) {
 	_, err = ht.ReceivePaymentUpdate(client)
 	require.Error(ht, err)
 }
+
+// testSendPaymentWithRouteHints tests sending a payment using route hints
+// derived from a private channel.
+func testSendPaymentWithRouteHints(ht *lntest.HarnessTest) {
+	// Setup a three-node network: Alice -> Bob -> Carol.
+	alice := ht.NewNode("Alice", nil)
+	defer ht.Shutdown(alice)
+	bob := ht.NewNode("Bob", nil)
+	defer ht.Shutdown(bob)
+	carol := ht.NewNode("Carol", nil)
+	defer ht.Shutdown(carol)
+
+	ht.ConnectNodes(alice, bob)
+	ht.ConnectNodes(bob, carol)
+
+	// Fund Alice and Bob.
+	ht.FundCoins(btcutil.SatoshiPerBitcoin, alice)
+	ht.FundCoins(btcutil.SatoshiPerBitcoin, bob)
+
+	// Open channels: Alice -> Bob (public), Bob -> Carol (private).
+	const chanAmt = btcutil.Amount(1_000_000)
+	aliceBobChanPoint := ht.OpenChannel(
+		alice, bob, lntest.OpenChannelParams{Amt: chanAmt},
+	)
+	defer ht.CloseChannel(alice, aliceBobChanPoint)
+	bobCarolChanPoint := ht.OpenChannel(bob, carol,
+		lntest.OpenChannelParams{Amt: chanAmt, Private: true},
+	)
+	defer ht.CloseChannel(bob, bobCarolChanPoint)
+
+	sendReq := &routerrpc.SendPaymentRequest{
+		PaymentRequest: carol.RPC.AddInvoice(&lnrpc.Invoice{
+			Value:   10_000,
+			Private: true, // include route hints
+		}).PaymentRequest,
+		FeeLimitSat:    int64(chanAmt),
+		TimeoutSeconds: 60,
+	}
+
+	// Send payment and assert success.
+	ht.AssertPaymentStatusFromStream(
+		alice.RPC.SendPayment(sendReq),
+		lnrpc.Payment_SUCCEEDED,
+	)
+}