lightning 5.13.1 → 5.14.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Versions
 
+## 5.14.0
+
+- `getRouteToDestination`, `isDestinationPayable`, `pay`,
+    `payViaPaymentDetails`, `payViaPaymentRequest`, `probeForRoute`,
+    `subscribeToPayViaDetails`, `subscribeToPayViaRequest`,
+    `subscribeToProbeForRoute` - add support for pathfinding `confidence`
+
 ## 5.13.1
 
 - `signTransaction`: Fix multi-input signing for upcoming Taproot API changes

package/grpc/protos/lightning.proto

@@ -2692,6 +2692,12 @@ message QueryRoutesRequest {
     fallback.
     */
     repeated lnrpc.FeatureBit dest_features = 17;
+
+    /*
+    The time preference for this payment. Set to -1 to optimize for fees
+    only, to 1 to optimize for reliability only or a value inbetween for a mix.
+    */
+    double time_pref = 18;
 }
 
 message NodePair {
@@ -2786,6 +2792,9 @@ message Hop {
     to drop off at each hop within the onion.
     */
     map<uint64, bytes> custom_records = 11;
+
+    // The payment metadata to send along with the payment to the payee.
+    bytes metadata = 13;
 }
 
 message MPPRecord {

package/grpc/protos/router.proto

@@ -284,6 +284,12 @@ message SendPaymentRequest {
     If set, an AMP-payment will be attempted.
     */
     bool amp = 22;
+
+    /*
+    The time preference for this payment. Set to -1 to optimize for fees
+    only, to 1 to optimize for reliability only or a value inbetween for a mix.
+    */
+    double time_pref = 23;
 }
 
 message TrackPaymentRequest {

package/lnd_methods/info/get_route_to_destination.js

@@ -17,6 +17,7 @@ const {pathNotFoundErrors} = require('./constants');
 const {routeHintFromRoute} = require('./../../lnd_requests');
 const {routesFromQueryRoutes} = require('./../../lnd_responses');
 
+const asTimePreference = n => n === undefined ? n : ((n * 2) - 1e6) / 1e6;
 const bufFromHex = hex => !hex ? null : Buffer.from(hex, 'hex');
 const {concat} = Buffer;
 const defaultRetryInterval = retryCount => 50 * Math.pow(2, retryCount);
@@ -24,6 +25,7 @@ const defaultMaxFee = Number.MAX_SAFE_INTEGER;
 const errorFilter = err => Array.isArray(err) && err.slice().shift() === 429;
 const internalServerError = /internal.server.error/i;
 const {isArray} = Array;
+const isConfidence = n => !isNaN(n) && n >= 0 && n <= 1e6;
 const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 const mtokensByteLength = 8;
 const networkBusyError = /device.or.resource.busy/;
@@ -41,8 +43,11 @@ const trimByte = 0;
 
   Requires `info:read` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Final Send Destination Hex Encoded Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -112,6 +117,10 @@ module.exports = (args, cbk) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
+        if (args.confidence !== undefined && !isConfidence(args.confidence)) {
+          return cbk([400, 'ExpectedConfidenceInPartsPerMillionForQuery']);
+        }
+
         if (!args.destination || !isHex(args.destination)) {
           return cbk([400, 'ExpectedDestinationKeyToGetRouteToDestination']);
         }
@@ -261,6 +270,7 @@ module.exports = (args, cbk) => {
             pub_key: args.destination,
             route_hints: routeHints || undefined,
             source_pub_key: args.start || undefined,
+            time_pref: asTimePreference(args.confidence),
             use_mission_control: !args.is_ignoring_past_failures,
           },
           (err, response) => {

package/lnd_methods/offchain/is_destination_payable.js

@@ -9,8 +9,11 @@ const defaultTokens = 1;
 
   Requires `offchain:write` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Pay to Node with Public Key Hex String>
     [incoming_peer]: <Pay Through Specific Final Hop Public Key Hex String>
     lnd: <Authenticated LND API Object>
@@ -57,6 +60,7 @@ module.exports = (args, cbk) => {
 
         const sub = subscribeToPayViaDetails({
           cltv_delta: args.cltv_delta,
+          confidence: args.confidence,
           destination: args.destination,
           lnd: args.lnd,
           max_fee: args.max_fee,

package/lnd_methods/offchain/pay.js

@@ -17,7 +17,10 @@ const payViaRoutes = require('./pay_via_routes');
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [incoming_peer]: <Pay Through Specific Final Hop Public Key Hex String>
     lnd: <Authenticated LND API Object>
     [max_fee]: <Maximum Additional Fee Tokens To Pay Number>
@@ -124,6 +127,7 @@ module.exports = (args, cbk) => {
         }
 
         return payViaPaymentRequest({
+          confidence: args.confidence,
           incoming_peer: args.incoming_peer,
           lnd: args.lnd,
           max_fee: args.max_fee,

package/lnd_methods/offchain/pay_via_payment_details.js

@@ -19,8 +19,11 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -109,6 +112,7 @@ module.exports = (args, cbk) => {
         try {
           const sub = subscribeToPayViaDetails({
             cltv_delta: args.cltv_delta,
+            confidence: args.confidence,
             destination: args.destination,
             features: args.features,
             id: args.id,

package/lnd_methods/offchain/pay_via_payment_request.js

@@ -14,7 +14,10 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [incoming_peer]: <Pay Through Specific Final Hop Public Key Hex String>
     lnd: <Authenticated LND API Object>
     [max_fee]: <Maximum Fee Tokens To Pay Number>
@@ -89,6 +92,7 @@ module.exports = (args, cbk) => {
       // Pay payment request
       pay: ['validate', ({}, cbk) => {
         const sub = subscribeToPayViaRequest({
+          confidence: args.confidence,
           incoming_peer: args.incoming_peer,
           lnd: args.lnd,
           max_fee: args.max_fee,

package/lnd_methods/offchain/probe_for_route.js

@@ -17,8 +17,11 @@ const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 
   Requires `offchain:write` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key Hex String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -117,6 +120,7 @@ module.exports = (args, cbk) => {
 
         const sub = subscribeToProbeForRoute({
           cltv_delta: args.cltv_delta,
+          confidence: args.confidence,
           destination: args.destination,
           features: args.features,
           ignore: args.ignore,

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -16,6 +16,7 @@ const {routeHintFromRoute} = require('./../../lnd_requests');
 const {safeTokens} = require('./../../bolt00');
 const {states} = require('./payment_states');
 
+const asTimePreference = n => n === undefined ? n : ((n * 2) - 1e6) / 1e6;
 const cltvBuf = 3;
 const cltvLimit = (limit, height) => !limit ? undefined : limit - height;
 const cltvLimitErr = /cltv limit \d+ should be greater than \d+/;
@@ -24,6 +25,7 @@ const defaultMaxPaths = 1;
 const defaultTimeoutSeconds = 25;
 const hexToBuf = hex => !hex ? undefined : Buffer.from(hex, 'hex');
 const {isArray} = Array;
+const isConfidence = n => !isNaN(n) && n >= 0 && n <= 1e6;
 const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 const maxTokens = '4294967296';
 const method = 'sendPaymentV2';
@@ -42,8 +44,11 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [destination]: <Destination Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -208,6 +213,10 @@ module.exports = args => {
     throw new Error('UnexpectedCltvDeltaWhenSubscribingToPayPaymentRequest');
   }
 
+  if (args.confidence !== undefined && !isConfidence(args.confidence)) {
+    throw new Error('ExpectedConfidencePartsPerMillionForPaymentReq');
+  }
+
   if (!args.destination && !args.request) {
     throw new Error('ExpectedDestinationWhenPaymentRequestNotSpecified');
   }
@@ -378,6 +387,7 @@ module.exports = args => {
         payment_hash: !args.id ? undefined : hexToBuf(args.id),
         payment_request: !args.request ? undefined : args.request,
         route_hints: !hints.length ? undefined : hints,
+        time_pref: asTimePreference(args.confidence),
         timeout_seconds: timeoutSecs || defaultTimeoutSeconds,
       });
     }],

package/lnd_methods/offchain/subscribe_to_pay_via_details.js

@@ -17,8 +17,11 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -191,6 +194,7 @@ module.exports = args => {
 
   return subscribeToPay({
     cltv_delta: args.cltv_delta || defaultCltvDelta,
+    confidence: args.confidence,
     destination: args.destination,
     features: args.features,
     id: args.id || randomId(),

package/lnd_methods/offchain/subscribe_to_pay_via_request.js

@@ -10,7 +10,10 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [incoming_peer]: <Pay Through Specific Final Hop Public Key Hex String>
     lnd: <Authenticated LND API Object>
     [max_fee]: <Maximum Fee Tokens To Pay Number>
@@ -167,6 +170,7 @@ module.exports = args => {
   }
 
   return subscribeToPay({
+    confidence: args.confidence,
     incoming_peer: args.incoming_peer,
     lnd: args.lnd,
     max_fee: args.max_fee,

package/lnd_methods/offchain/subscribe_to_probe_for_route.js

@@ -20,8 +20,11 @@ const {nextTick} = process;
 
   Requires `offchain:write` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key Hex String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -241,6 +244,7 @@ module.exports = args => {
           return getRouteToDestination({
             mtokens,
             cltv_delta: args.cltv_delta,
+            confidence: args.confidence,
             destination: args.destination,
             features: args.features,
             ignore: ignore.concat(temporaryChannelFailures),

package/package.json

@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "5.13.1"
+  "version": "5.14.0"
 }