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

Adds --route_hints flag to sendpayment for --keysend and --amp payments.
CLI will error if neither is specified or if --pay_req is specified
since bolt 11 already handles route hinting. 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,29 @@ 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. It should probably not be allowed with a payment
+		// request.
+		if ctx.IsSet("pay_req") ||
+			(!ctx.Bool("keysend") && !ctx.Bool(ampFlag.Name)) {
+			return fmt.Errorf("--route_hints can only be used " +
+				"with --keysend or --amp and not --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 +1187,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 +1290,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

@@ -322,6 +322,10 @@ var allTestCases = []*lntest.TestCase{
 		Name:     "query routes",
 		TestFunc: testQueryRoutes,
 	},
+	{
+		Name:     "query routes routehints",
+		TestFunc: testQueryRoutesRouteHints,
+	},
 	{
 		Name:     "route fee cutoff",
 		TestFunc: testRouteFeeCutoff,
@@ -406,6 +410,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,214 @@ 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.
+	alice := ht.NewNode("Alice", nil)
+	defer ht.Shutdown(alice)
+	bob := ht.NewNode("Bob", nil)
+	defer ht.Shutdown(bob)
+	// Ensure Carol accepts keysend payments.
+	carol := ht.NewNode("Carol", []string{"--accept-keysend"})
+	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)
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolChanPoint)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+
+	hints := []*lnrpc.RouteHint{{HopHints: []*lnrpc.HopHint{
+		{
+			NodeId:                    bob.PubKeyStr,
+			ChanId:                    bobChan.ChanId,
+			FeeBaseMsat:               1000,
+			FeeProportionalMillionths: 1,
+			CltvExpiryDelta:           routing.MinCLTVDelta,
+		}}},
+	}
+
+	// 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:     hints,
+		FeeLimitSat:    int64(chanAmt),
+		TimeoutSeconds: 60,
+	}
+
+	// Send keysend payment and assert success.
+	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.
+	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)
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolChanPoint)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+
+	hints := []*lnrpc.RouteHint{{HopHints: []*lnrpc.HopHint{
+		{
+			NodeId:                    bob.PubKeyStr,
+			ChanId:                    bobChan.ChanId,
+			FeeBaseMsat:               1000,
+			FeeProportionalMillionths: 1,
+			CltvExpiryDelta:           routing.MinCLTVDelta,
+		}}},
+	}
+
+	// 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:     hints,
+		FeeLimitSat:    int64(chanAmt),
+		TimeoutSeconds: 60,
+	}
+
+	// Send AMP payment and assert success
+	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.
+	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)
+
+	// Manually create route hints for the private Bob -> Carol channel.
+	bobChan := ht.GetChannelByChanPoint(bob, bobCarolChanPoint)
+	require.NotNil(ht, bobChan, "Bob should have channel with Carol")
+
+	hints := []*lnrpc.RouteHint{{HopHints: []*lnrpc.HopHint{
+		{
+			NodeId:                    bob.PubKeyStr,
+			ChanId:                    bobChan.ChanId,
+			FeeBaseMsat:               1000,
+			FeeProportionalMillionths: 1,
+			CltvExpiryDelta:           routing.MinCLTVDelta,
+		}}},
+	}
+
+	queryReq := &lnrpc.QueryRoutesRequest{
+		PubKey:            carol.PubKeyStr,
+		Amt:               10_000,
+		FinalCltvDelta:    int32(routing.MinCLTVDelta),
+		RouteHints:        hints,
+		UseMissionControl: true, // Use MC for realistic pathfinding
+	}
+
+	routes := alice.RPC.QueryRoutes(queryReq)
+
+	// Assert that a route was found and it goes Alice -> Bob -> Carol.
+	require.NotEmpty(ht, routes.Routes, "QueryRoutes 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")
+}