lightning 10.22.3 → 10.23.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 10.23.0
+
+- `getRoutingFeeEstimate`: Add method to estimate an offchain payment fee
+
 ## 10.22.3
 
 - `createFundedPsbt`: Add support for `change_format` for change address type

package/README.md

@@ -234,6 +234,8 @@ variables set:
     Calculate a route through specified nodes.
 - [getRouteToDestination](https://github.com/alexbosworth/ln-service#getroutetodestination):
     Calculate a route through the graph to a destination.
+- [getRoutingFeeEstimate](https://github.com/alexbosworth/ln-service#getroutingfeeestimate):
+    Make a test payment to find a working routing fee for a payment request
 - [getSettlementStatus](https://github.com/alexbosworth/ln-service#getsettlementstatus):
     Lookup the status of a received payment output
 - [getSweepTransactions](https://github.com/alexbosworth/ln-service#getsweeptransactions): List

package/index.js

@@ -78,6 +78,7 @@ const {getPublicKey} = require('./lnd_methods');
 const {getRouteConfidence} = require('./lnd_methods');
 const {getRouteThroughHops} = require('./lnd_methods');
 const {getRouteToDestination} = require('./lnd_methods');
+const {getRoutingFeeEstimate} = require('./lnd_methods');
 const {getSettlementStatus} = require('./lnd_methods');
 const {getSweepTransactions} = require('./lnd_methods');
 const {getTowerServerInfo} = require('./lnd_methods');
@@ -239,6 +240,7 @@ module.exports = {
   getRouteConfidence,
   getRouteThroughHops,
   getRouteToDestination,
+  getRoutingFeeEstimate,
   getSettlementStatus,
   getSweepTransactions,
   getTowerServerInfo,

package/lnd_methods/index.js

@@ -77,6 +77,7 @@ const {getPublicKey} = require('./address');
 const {getRouteConfidence} = require('./generic');
 const {getRouteThroughHops} = require('./offchain');
 const {getRouteToDestination} = require('./info');
+const {getRoutingFeeEstimate} = require('./offchain');
 const {getSettlementStatus} = require('./offchain');
 const {getSweepTransactions} = require('./onchain');
 const {getTowerServerInfo} = require('./info');
@@ -237,6 +238,7 @@ module.exports = {
   getRouteConfidence,
   getRouteThroughHops,
   getRouteToDestination,
+  getRoutingFeeEstimate,
   getSettlementStatus,
   getSweepTransactions,
   getTowerServerInfo,

package/lnd_methods/macaroon/methods.json

@@ -312,6 +312,10 @@
     "method": "QueryRoutes",
     "type": "default"
   },
+  "getRoutingFeeEstimate": {
+    "method": "EstimateRouteFee",
+    "type": "router"
+  },
   "getSettlementStatus": {
     "method": "LookupHtlcResolution",
     "type": "default"

package/lnd_methods/offchain/get_routing_fee_estimate.d.ts

@@ -0,0 +1,32 @@
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {
+    AuthenticatedLightningArgs,
+    AuthenticatedLightningMethod
+} from '../../typescript';
+
+export type GetRoutingFeeEstimateRequest = AuthenticatedLightningArgs<{
+    lnd: AuthenticatedLnd;
+    /** BOLT 11 Encoded Payment Request */
+    request: string;
+    /** Optional Timeout in Milliseconds */
+    timeout?: number;
+}>;
+
+export type GetRoutingFeeEstimateResponse = {
+    /** (Minimum Routing Fee Millitokens) */
+    fee_mtokens: string;
+    /** Timeout (Time Lock Delay) */
+    timeout: number;
+};
+
+/**
+ * Estimate routing fees based on an invoice.
+ *
+ * Requires `offchain:read` permission
+ *
+ * This method is not supported before LND 0.18.4
+ */
+export const getRoutingFeeEstimate: AuthenticatedLightningMethod<
+  GetRoutingFeeEstimateRequest,
+  GetRoutingFeeEstimateResponse
+>;

package/lnd_methods/offchain/get_routing_fee_estimate.js

@@ -0,0 +1,86 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const defaultTimeoutSeconds = 60;
+const method = 'estimateRouteFee';
+const msAsSecs = ms => Math.round(ms / 1e3);
+const type = 'router';
+
+/** Estimate routing fees and timeout required to pay a payment request
+
+  Requires `offchain:read` permission
+
+  This method is not supported on LND 0.18.3 and below
+
+ {
+    lnd: <Authenticated LND API Object>
+    request: <BOLT 11 Payment Request String>
+    [timeout]: <Maximum Route Pathfinding Time in Milliseconds Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    fee_mtokens: <Estimated Minimum Required Route Fee Millitokens String>
+    timeout: <Estimated Minimum Time Lock Block Height Delay Number>
+  }
+*/
+module.exports = ({lnd, request, timeout}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetRoutingFeeEstimate']);
+        }
+
+        if (!request) {
+          return cbk([400, 'ExpectedPaymentRequestToGetRoutingFeeEstimate']);
+        }
+
+        return cbk();
+      },
+
+      // Request a probe of the request to determine a needed fee and delay
+      getEstimate: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          payment_request: request,
+          timeout: msAsSecs(timeout) || defaultTimeoutSeconds,
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedGetRoutingFeeEstimateError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedGetRoutingFeeEstimateResponse']);
+          }
+
+          if (!res.routing_fee_msat) {
+            return cbk([503, 'ExpectedFeeInGetRoutingFeeEstimateResponse']);
+          }
+
+          if (!res.time_lock_delay) {
+            return cbk([503, 'ExpectedTimeoutInGetRouteFeeEstimateResponse']);
+          }
+
+          // Exit early with error when the estimate response has failure code
+          if (res.failure_reason !== 'FAILURE_REASON_NONE') {
+            return cbk([
+              404,
+              'RouteToDestinationNotFound',
+              {failure: res.failure_reason},
+            ]);
+          }
+
+          return cbk(null, {
+            fee_mtokens: res.routing_fee_msat,
+            timeout: Number(res.time_lock_delay),
+          });
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getEstimate'}, cbk));
+  });
+};

package/lnd_methods/offchain/index.d.ts

@@ -27,6 +27,7 @@ export * from './get_payments';
 export * from './get_pending_channels';
 export * from './get_pending_payments';
 export * from './get_route_through_hops';
+export * from './get_routing_fee_estimate';
 export * from './get_settlement_status';
 export * from './is_destination_payable';
 export * from './pay_via_payment_details';

package/lnd_methods/offchain/index.js

@@ -27,6 +27,7 @@ const getPayments = require('./get_payments');
 const getPendingChannels = require('./get_pending_channels');
 const getPendingPayments = require('./get_pending_payments');
 const getRouteThroughHops = require('./get_route_through_hops');
+const getRoutingFeeEstimate = require('./get_routing_fee_estimate');
 const getSettlementStatus = require('./get_settlement_status');
 const isDestinationPayable = require('./is_destination_payable');
 const pay = require('./pay');
@@ -86,6 +87,7 @@ module.exports = {
   getPendingChannels,
   getPendingPayments,
   getRouteThroughHops,
+  getRoutingFeeEstimate,
   getSettlementStatus,
   isDestinationPayable,
   pay,

package/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@grpc/grpc-js": "1.12.5",
     "@grpc/proto-loader": "0.7.13",
-    "@types/node": "22.10.2",
+    "@types/node": "22.10.5",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.13",
     "async": "3.2.6",
@@ -22,7 +22,7 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.30.2"
+    "type-fest": "4.31.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.22.3"
+  "version": "10.23.0"
 }

package/test/lnd_methods/offchain/test_get_routing_fee_estimate.js

@@ -0,0 +1,82 @@
+const {rejects, deepStrictEqual} = require('node:assert').strict;
+const test = require('node:test');
+const {getRoutingFeeEstimate} = require('../../../');
+
+const makeLnd = ({err, res}) => {
+  const r = {
+    routing_fee_msat: '1',
+    time_lock_delay: '1',
+    failure_reason: 'FAILURE_REASON_NONE',
+  };
+
+  return {
+    router: {
+      estimateRouteFee: ({}, cbk) => cbk(err, res !== undefined ? res : r),
+    },
+  };
+};
+
+const makeArgs = override => {
+  const args = {lnd: makeLnd({}), request: 'request'};
+
+  Object.keys(override || {}).forEach(key => args[key] = override[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required',
+    error: [400, 'ExpectedAuthenticatedLndToGetRoutingFeeEstimate'],
+  },
+  {
+    args: makeArgs({request: undefined}),
+    description: 'Request is required',
+    error: [400, 'ExpectedPaymentRequestToGetRoutingFeeEstimate'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'A route fee estimate is returned',
+    expected: {fee_mtokens: '1', timeout: 1},
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: 'err'})}),
+    description: 'An error is not expected',
+    error: [503, 'UnexpectedGetRoutingFeeEstimateError', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: null})}),
+    description: 'A result is expected',
+    error: [503, 'ExpectedGetRoutingFeeEstimateResponse'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: {}})}),
+    description: 'A result fee is expected',
+    error: [503, 'ExpectedFeeInGetRoutingFeeEstimateResponse'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: {routing_fee_msat: '1'}})}),
+    description: 'A result timeout is expected',
+    error: [503, 'ExpectedTimeoutInGetRouteFeeEstimateResponse'],
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({res: {routing_fee_msat: '1', time_lock_delay: '1'}}),
+    }),
+    description: 'A result non failure code is expected',
+    error: [404, 'RouteToDestinationNotFound', {failure: undefined}],
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async () => {
+    if (!!error) {
+      await rejects(getRoutingFeeEstimate(args), error, 'Got expected error');
+    } else {
+      deepStrictEqual(await getRoutingFeeEstimate(args), expected, 'Got res');
+    }
+
+    return;
+  });
+});