BuildRoute

BuildRoute builds a fully specified route based on a list of hop public keys. It retrieves the relevant channel policies from the graph in order to calculate the correct fees and time locks. Note that LND will use its default final_cltv_delta if no value is supplied. Make sure to add the correct final_cltv_delta depending on the invoice restriction. Moreover the caller has to make sure to provide the payment_addr if the route is paying an invoice which signaled it.

Source: routerrpc/router.proto

gRPC

rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);

REST

HTTP Method	Path
POST	/v2/router/route

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'routerrpc/router.proto'], loaderOptions);
const routerrpc = grpc.loadPackageDefinition(packageDefinition).routerrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new routerrpc.Router(GRPC_HOST, creds);
let request = {
  amt_msat: <int64>,
  final_cltv_delta: <int32>,
  outgoing_chan_id: <uint64>,
  hop_pubkeys: <bytes>,
  payment_addr: <bytes>,
  first_hop_custom_records: <FirstHopCustomRecordsEntry>,
};
client.buildRoute(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "route": <Route>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the routerrpc/router.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import router_pb2 as routerrpc, router_pb2_grpc as routerstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = routerstub.RouterStub(channel)
request = routerrpc.BuildRouteRequest(
  amt_msat=<int64>,
  final_cltv_delta=<int32>,
  outgoing_chan_id=<uint64>,
  hop_pubkeys=<bytes>,
  payment_addr=<bytes>,
  first_hop_custom_records=<FirstHopCustomRecordsEntry>,
)
response = stub.BuildRoute(request)
print(response)
# {
#    "route": <Route>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  amt_msat: <string>, // <int64> 
  final_cltv_delta: <integer>, // <int32> 
  outgoing_chan_id: <string>, // <uint64> 
  hop_pubkeys: <array>, // <bytes> (base64 encoded)
  payment_addr: <string>, // <bytes> (base64 encoded)
  first_hop_custom_records: <object>, // <FirstHopCustomRecordsEntry> 
};
let options = {
  url: `https://${REST_HOST}/v2/router/route`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "route": <object>, // <Route> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/router/route'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'amt_msat': <int64>,
  'final_cltv_delta': <int32>,
  'outgoing_chan_id': <uint64>,
  'hop_pubkeys': base64.b64encode(<bytes>),
  'payment_addr': base64.b64encode(<bytes>),
  'first_hop_custom_records': <FirstHopCustomRecordsEntry>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "route": <Route>,
# }

Shell

$ lncli buildroute --help

NAME:
   lncli buildroute - Build a route from a list of hop pubkeys.

USAGE:
   lncli buildroute [command options] [arguments...]

CATEGORY:
   Payments

DESCRIPTION:
   
  Builds a sphinx route for the supplied hops (public keys). Make sure to
  use a custom final_cltv_delta to create the route depending on the
  restrictions in the invoice otherwise LND will use its default specified
  via the bitcoin.timelockdelta setting (default 80).
  If the final_cltv_delta mismatch you will likely see the error
  INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS returned by the receiving node.

  Moreover a payment_addr has to be provided if the invoice supplied it as
  well otherwise the payment will be rejected by the receiving node.
  

OPTIONS:
   --amt value               the amount to send expressed in satoshis. Ifnot set, the minimum routable amount is used (default: 0)
   --final_cltv_delta value  number of blocks the last hop has to reveal the preimage; if not set the default lnd final_cltv_delta is used (default: 0)
   --hops value              comma separated hex pubkeys
   --outgoing_chan_id value  short channel id of the outgoing channel to use for the first hop of the payment (default: 0)
   --payment_addr value      hex encoded payment address to set in the last hop's mpp record
   

Messages

routerrpc.BuildRouteRequest

Source: routerrpc/router.proto

Field	gRPC Type	REST Type	REST Placement
amt_msat The amount to send expressed in msat. If set to zero, the minimum routable amount is used.	int64	string	body
final_cltv_delta CLTV delta from the current height that should be used for the timelock of the final hop	int32	integer	body
outgoing_chan_id The channel id of the channel that must be taken to the first hop. If zero, any channel may be used.	uint64	string	body
hop_pubkeys A list of hops that defines the route. This does not include the source hop pubkey.	bytes[]	array	body
payment_addr An optional payment addr to be included within the last hop of the route. This is also called payment secret in specifications (e.g. BOLT 11).	bytes	string	body
first_hop_custom_records An optional field that can be used to pass an arbitrary set of TLV records to the first hop peer of this payment. This can be used to pass application specific data during the payment attempt. Record types are required to be in the custom range >= 65536. When using REST, the values must be encoded as base64.	FirstHopCustomRecordsEntry[]	object	body

routerrpc.BuildRouteResponse

Source: routerrpc/router.proto

Field	gRPC Type	REST Type
route Fully specified route that can be used to execute the payment.	Route	object

Nested Messages

lnrpc.AMPRecord

Field	gRPC Type	REST Type
root_share	bytes	string
set_id	bytes	string
child_index	uint32	integer

lnrpc.Hop

Field	gRPC Type	REST Type
chan_id The unique channel ID for the channel. The first 3 bytes are the block height, the next 3 the index within the block, and the last 2 bytes are the output index for the channel.	uint64	string
chan_capacity	int64	string
amt_to_forward	int64	string
fee	int64	string
expiry	uint32	integer
amt_to_forward_msat	int64	string
fee_msat	int64	string
pub_key An optional public key of the hop. If the public key is given, the payment can be executed without relying on a copy of the channel graph.	string	string
tlv_payload If set to true, then this hop will be encoded using the new variable length TLV format. Note that if any custom tlv_records below are specified, then this field MUST be set to true for them to be encoded properly.	bool	boolean
mpp_record An optional TLV record that signals the use of an MPP payment. If present, the receiver will enforce that the same mpp_record is included in the final hop payload of all non-zero payments in the HTLC set. If empty, a regular single-shot payment is or was attempted.	MPPRecord	object
amp_record An optional TLV record that signals the use of an AMP payment. If present, the receiver will treat all received payments including the same (payment_addr, set_id) pair as being part of one logical payment. The payment will be settled by XORing the root_share's together and deriving the child hashes and preimages according to BOLT XX. Must be used in conjunction with mpp_record.	AMPRecord	object
custom_records An optional set of key-value TLV records. This is useful within the context of the SendToRoute call as it allows callers to specify arbitrary K-V pairs to drop off at each hop within the onion.	CustomRecordsEntry[]	object
metadata The payment metadata to send along with the payment to the payee.	bytes	string
blinding_point Blinding point is an optional blinding point included for introduction nodes in blinded paths. This field is mandatory for hops that represents the introduction point in a blinded path.	bytes	string
encrypted_data Encrypted data is a receiver-produced blob of data that provides hops in a blinded route with forwarding data. As this data is encrypted by the recipient, we will not be able to parse it - it is essentially an arbitrary blob of data from our node's perspective. This field is mandatory for all hops in a blinded path, including the introduction node.	bytes	string
total_amt_msat The total amount that is sent to the recipient (possibly across multiple HTLCs), as specified by the sender when making a payment to a blinded path. This value is only set in the final hop payload of a blinded payment. This value is analogous to the MPPRecord that is used for regular (non-blinded) MPP payments.	uint64	string

lnrpc.Hop.CustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown

lnrpc.MPPRecord

Field	gRPC Type	REST Type
payment_addr A unique, random identifier used to authenticate the sender as the intended payer of a multi-path payment. The payment_addr must be the same for all subpayments, and match the payment_addr provided in the receiver's invoice. The same payment_addr must be used on all subpayments. This is also called payment secret in specifications (e.g. BOLT 11).	bytes	string
total_amt_msat The total amount in milli-satoshis being sent as part of a larger multi-path payment. The caller is responsible for ensuring subpayments to the same node and payment_hash sum exactly to total_amt_msat. The same total_amt_msat must be used on all subpayments.	int64	string

lnrpc.Route

Field	gRPC Type	REST Type
total_time_lock The cumulative (final) time lock across the entire route. This is the CLTV value that should be extended to the first hop in the route. All other hops will decrement the time-lock as advertised, leaving enough time for all hops to wait for or present the payment preimage to complete the payment.	uint32	integer
total_fees The sum of the fees paid at each hop within the final route. In the case of a one-hop payment, this value will be zero as we don't need to pay a fee to ourselves.	int64	string
total_amt The total amount of funds required to complete a payment over this route. This value includes the cumulative fees at each hop. As a result, the HTLC extended to the first-hop in the route will need to have at least this many satoshis, otherwise the route will fail at an intermediate node due to an insufficient amount of fees.	int64	string
hops Contains details concerning the specific forwarding details at each hop.	Hop[]	array
total_fees_msat The total fees in millisatoshis.	int64	string
total_amt_msat The total amount in millisatoshis.	int64	string
first_hop_amount_msat The actual on-chain amount that was sent out to the first hop. This value is only different from the total_amt_msat field if this is a custom channel payment and the value transported in the HTLC is different from the BTC amount in the HTLC. If this value is zero, then this is an old payment that didn't have this value yet and can be ignored.	int64	string
custom_channel_data Custom channel data that might be populated in custom channels.	bytes	string

routerrpc.BuildRouteRequest.FirstHopCustomRecordsEntry

Field	gRPC Type	REST Type
key	uint64	unknown
value	bytes	unknown