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

Adds --route_hints flag to sendpayment for --keysend and --amp payments.
CLI will error if neither is specified. Hints should be JSON encoded
(see usage for example).

Adds --route_hints flag to queryroutes (no restrictions).

Adds integration tests for query routes over RPC, and manual
keysend/amp over RPC to emulate the new feature. Testing revealed route
hinting did not work for standard payment (w/ or w/o --pay_addr).

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,15 @@ 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 for reaching the destination of a" +
+				" manual --keysend or --amp payment. eg: " +
+				`[{"hop_hints":[{"node_id":"A","chan_id":1,` +
+				`"fee_base_msat":2,` +
+				`"fee_proportional_millionths":3,` +
+				`"cltv_expiry_delta":4}]}]`,
+		},
 	),
 	Action: SendPayment,
 }
@@ -473,6 +483,28 @@ func SendPayment(ctx *cli.Context) error {
 
 	req.PaymentAddr = payAddr
 
+	if ctx.IsSet("route_hints") {
+		// Route hints can only be used with a manual keysend or amp
+		// payment.
+		if !ctx.Bool("keysend") && !ctx.Bool(ampFlag.Name) {
+			return fmt.Errorf("--route_hints can only be used " +
+				"with --keysend or --amp and should not be" +
+				" used with --pay_req")
+		}
+
+		// Parse the route hints JSON.
+		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 +1186,15 @@ var queryRoutesCommand = cli.Command{
 		blindedBaseFlag,
 		blindedPPMFlag,
 		blindedCLTVFlag,
+		cli.StringFlag{
+			Name: "route_hints",
+			Usage: "route hints for searching through private " +
+				"channels. eg: " +
+				`[{"hop_hints":[{"node_id":"A","chan_id":1,` +
+				`"fee_base_msat":2,` +
+				`"fee_proportional_millionths":3,` +
+				`"cltv_expiry_delta":4}]}]`,
+		},
 	},
 	Action: actionDecorator(queryRoutes),
 }
@@ -1248,6 +1289,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

docs/release-notes/release-notes-0.20.0.md

@@ -28,6 +28,10 @@
 
 ## lncli Additions
 
+* [`lncli sendpayment --keysend/--amp` and `lncli queryroutes` now support the
+  `--route_hints` flag](https://github.com/lightningnetwork/lnd/pull/9721) to
+  support routing through private channels.
+
 # Improvements
 ## Functional Updates
 

itest/list_on_test.go

@@ -327,6 +327,10 @@ var allTestCases = []*lntest.TestCase{
 		Name:     "query routes",
 		TestFunc: testQueryRoutes,
 	},
+	{
+		Name:     "query routes routehints",
+		TestFunc: testQueryRoutesRouteHints,
+	},
 	{
 		Name:     "route fee cutoff",
 		TestFunc: testRouteFeeCutoff,
@@ -411,6 +415,14 @@ var allTestCases = []*lntest.TestCase{
 		Name:     "send payment keysend mpp fail",
 		TestFunc: testSendPaymentKeysendMPPFail,
 	},
+	{
+		Name:     "send payment routehints keysend",
+		TestFunc: testSendPaymentRouteHintsKeysend,
+	},
+	{
+		Name:     "send payment routehints amp",
+		TestFunc: testSendPaymentRouteHintsAMP,
+	},
 	{
 		Name:     "forward interceptor dedup htlcs",
 		TestFunc: testForwardInterceptorDedupHtlc,

itest/lnd_payment_test.go

@@ -22,6 +22,7 @@ import (
 	"github.com/lightningnetwork/lnd/lntypes"
 	"github.com/lightningnetwork/lnd/lnwire"
 	"github.com/lightningnetwork/lnd/record"
+	"github.com/lightningnetwork/lnd/routing"
 	"github.com/stretchr/testify/require"
 )
 
@@ -1396,3 +1397,218 @@ func testSendPaymentKeysendMPPFail(ht *lntest.HarnessTest) {
 	_, err = ht.ReceivePaymentUpdate(client)
 	require.Error(ht, err)
 }
+
+// testSendPaymentRouteHintsKeysend tests sending a keysend payment using
+// manually provided route hints derived from a private channel.
+func testSendPaymentRouteHintsKeysend(ht *lntest.HarnessTest) {
+	// Setup a three-node network: Alice -> Bob -> Carol.
+	// The Bob->Carol channel is private.
+	const chanAmt = btcutil.Amount(1_000_000)
+	alice, bob, carol, _, bobCarolCP, cleanup := setupThreeNodeNetwork(
+		ht, chanAmt, true,
+	)
+	defer cleanup()
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolCP)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+	hints := createRouteHintFromChannel(bob, bobChan)
+
+	// Prepare Keysend payment details.
+	preimage := ht.RandomPreimage()
+	payHash := preimage.Hash()
+	destBytes, err := hex.DecodeString(carol.PubKeyStr)
+	require.NoError(ht, err)
+
+	sendReq := &routerrpc.SendPaymentRequest{
+		Dest:           destBytes,
+		Amt:            10_000,
+		PaymentHash:    payHash[:],
+		FinalCltvDelta: int32(routing.MinCLTVDelta),
+		DestCustomRecords: map[uint64][]byte{
+			record.KeySendType: preimage[:],
+		},
+		// RouteHints omitted initially.
+		FeeLimitSat:    int64(chanAmt),
+		TimeoutSeconds: 30,
+	}
+
+	// Attempt keysend payment without hints - should fail.
+	ht.AssertPaymentStatusFromStream(
+		alice.RPC.SendPayment(sendReq),
+		lnrpc.Payment_FAILED,
+	)
+
+	// Now, add the hints and try again - should succeed.
+	sendReq.RouteHints = hints
+	ht.AssertPaymentStatusFromStream(
+		alice.RPC.SendPayment(sendReq),
+		lnrpc.Payment_SUCCEEDED,
+	)
+}
+
+// testSendPaymentRouteHintsAMP tests sending an AMP payment using
+// manually provided route hints derived from a private channel.
+func testSendPaymentRouteHintsAMP(ht *lntest.HarnessTest) {
+	// Setup a three-node network: Alice -> Bob -> Carol.
+	// The Bob->Carol channel is private.
+	const chanAmt = btcutil.Amount(1_000_000)
+	alice, bob, carol, _, bobCarolCP, cleanup := setupThreeNodeNetwork(
+		ht, chanAmt, true,
+	)
+	defer cleanup()
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolCP)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+	hints := createRouteHintFromChannel(bob, bobChan)
+
+	// Carol creates an AMP invoice
+	const paymentAmtSat = 10_000
+	carolDestBytes, err := hex.DecodeString(carol.PubKeyStr)
+	require.NoError(ht, err)
+
+	invoiceTemplate := &lnrpc.Invoice{
+		Value:   paymentAmtSat,
+		Private: true,
+		IsAmp:   true,
+	}
+	addInvoiceResp := carol.RPC.AddInvoice(invoiceTemplate)
+
+	// We need to decode to get CltvExpiry.
+	decodedPayReq := alice.RPC.DecodePayReq(addInvoiceResp.PaymentRequest)
+
+	sendReq := &routerrpc.SendPaymentRequest{
+		Dest: carolDestBytes,
+		Amt:  paymentAmtSat,
+		// PaymentHash is omitted for AMP
+		PaymentAddr:    addInvoiceResp.PaymentAddr,
+		FinalCltvDelta: int32(decodedPayReq.CltvExpiry),
+		Amp:            true,
+		// RouteHints omitted initially.
+		FeeLimitSat:    int64(chanAmt),
+		TimeoutSeconds: 30,
+	}
+
+	// Attempt AMP payment without hints - should fail.
+	ht.AssertPaymentStatusFromStream(
+		alice.RPC.SendPayment(sendReq),
+		lnrpc.Payment_FAILED,
+	)
+
+	// Now, add the hints and try again - should succeed.
+	sendReq.RouteHints = hints
+	ht.AssertPaymentStatusFromStream(
+		alice.RPC.SendPayment(sendReq),
+		lnrpc.Payment_SUCCEEDED,
+	)
+}
+
+// testQueryRoutesRouteHints tests that QueryRoutes successfully
+// finds a route through a private channel when provided with route hints.
+func testQueryRoutesRouteHints(ht *lntest.HarnessTest) {
+	// Setup a three-node network: Alice -> Bob -> Carol.
+	// The Bob->Carol channel is private.
+	const chanAmt = btcutil.Amount(1_000_000)
+	alice, bob, carol, _, bobCarolCP, cleanup := setupThreeNodeNetwork(
+		ht, chanAmt, true,
+	)
+	defer cleanup()
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolCP)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+	hints := createRouteHintFromChannel(bob, bobChan)
+
+	queryReq := &lnrpc.QueryRoutesRequest{
+		PubKey:         carol.PubKeyStr,
+		Amt:            10_000,
+		FinalCltvDelta: int32(routing.MinCLTVDelta),
+		// RouteHints omitted initially.
+		UseMissionControl: true, // Use MC for realistic pathfinding
+	}
+
+	// Query routes without hints - should fail (find no routes).
+	// Call the client directly to check the error without halting the test.
+	_, err := alice.RPC.LN.QueryRoutes(ht.Context(), queryReq)
+	require.Error(ht, err,
+		"QueryRoutes without hints should return an error")
+
+	// Now add the hints and query again - should succeed.
+	// Use the helper function here as we expect success.
+	queryReq.RouteHints = hints
+	routes := alice.RPC.QueryRoutes(queryReq)
+
+	// Assert that a route was found and it goes Alice -> Bob -> Carol.
+	require.NotEmpty(ht, routes.Routes,
+		"QueryRoutes with hints should find a route")
+	require.Len(ht, routes.Routes[0].Hops, 2, "Route should have 2 hops")
+
+	hop1 := routes.Routes[0].Hops[0]
+	hop2 := routes.Routes[0].Hops[1]
+
+	require.Equal(ht, bob.PubKeyStr, hop1.PubKey, "Hop 1 should be Bob")
+	require.Equal(ht, carol.PubKeyStr, hop2.PubKey, "Hop 2 should be Carol")
+}
+
+// createRouteHintFromChannel takes a source node and a channel object and
+// constructs a RouteHint slice containing a single hop hint for that channel.
+func createRouteHintFromChannel(sourceNode *node.HarnessNode,
+	channel *lnrpc.Channel) []*lnrpc.RouteHint {
+
+	return []*lnrpc.RouteHint{{HopHints: []*lnrpc.HopHint{
+		{
+			NodeId:                    sourceNode.PubKeyStr,
+			ChanId:                    channel.ChanId,
+			FeeBaseMsat:               1000,
+			FeeProportionalMillionths: 1,
+			CltvExpiryDelta:           routing.MinCLTVDelta,
+		}}},
+	}
+}
+
+// setupThreeNodeNetwork sets up a standard three-node network topology:
+// Alice -> Bob -> Carol. It creates the nodes, connects them, funds Alice and
+// Bob, opens a channel between Alice and Bob, and optionally opens a private
+// channel between Bob and Carol. It returns the nodes, channel points, and a
+// cleanup function.
+func setupThreeNodeNetwork(ht *lntest.HarnessTest, chanAmt btcutil.Amount,
+	bobCarolPrivate bool) (*node.HarnessNode, *node.HarnessNode,
+	*node.HarnessNode, *lnrpc.ChannelPoint, *lnrpc.ChannelPoint, func()) {
+
+	// Create nodes.
+	alice := ht.NewNode("Alice", nil)
+	bob := ht.NewNode("Bob", nil)
+	carol := ht.NewNode("Carol", nil)
+
+	// Connect nodes.
+	ht.ConnectNodes(alice, bob)
+	ht.ConnectNodes(bob, carol)
+
+	// Fund nodes.
+	ht.FundCoins(btcutil.SatoshiPerBitcoin, alice)
+	ht.FundCoins(btcutil.SatoshiPerBitcoin, bob)
+
+	// Open Alice -> Bob channel (public).
+	aliceBobChanPoint := ht.OpenChannel(
+		alice, bob, lntest.OpenChannelParams{Amt: chanAmt},
+	)
+
+	// Open Bob -> Carol channel (potentially private).
+	bobCarolParams := lntest.OpenChannelParams{
+		Amt:     chanAmt,
+		Private: bobCarolPrivate,
+	}
+	bobCarolChanPoint := ht.OpenChannel(bob, carol, bobCarolParams)
+
+	// Define cleanup function.
+	cleanup := func() {
+		ht.CloseChannel(alice, aliceBobChanPoint)
+		ht.CloseChannel(bob, bobCarolChanPoint)
+		ht.Shutdown(alice)
+		ht.Shutdown(bob)
+		ht.Shutdown(carol)
+	}
+
+	return alice, bob, carol, aliceBobChanPoint, bobCarolChanPoint, cleanup
+}