lightning 10.22.2 → 10.23.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Versions
 
-## 10.22.2
+## 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/grpc/protos/lightning.proto

@@ -643,6 +643,8 @@ message SendCustomMessageRequest {
 }
 
 message SendCustomMessageResponse {
+    // The status of the send operation.
+    string status = 1;
 }
 
 message Utxo {
@@ -755,11 +757,35 @@ message GetTransactionsRequest {
 
     // An optional filter to only include transactions relevant to an account.
     string account = 3;
+
+    /*
+    The index of a transaction that will be used in a query to determine which
+    transaction should be returned in the response.
+    */
+    uint32 index_offset = 4;
+
+    /*
+    The maximal number of transactions returned in the response to this query.
+    This value should be set to 0 to return all transactions.
+    */
+    uint32 max_transactions = 5;
 }
 
 message TransactionDetails {
     // The list of transactions relevant to the wallet.
     repeated Transaction transactions = 1;
+
+    /*
+    The index of the last item in the set of returned transactions. This can be
+    used to seek further, pagination style.
+    */
+    uint64 last_index = 2;
+
+    /*
+    The index of the last item in the set of returned transactions. This can be
+    used to seek backwards, pagination style.
+    */
+    uint64 first_index = 3;
 }
 
 message FeeLimit {
@@ -1317,6 +1343,8 @@ message ConnectPeerRequest {
     uint64 timeout = 3;
 }
 message ConnectPeerResponse {
+    // The status of the connect operation.
+    string status = 1;
 }
 
 message DisconnectPeerRequest {
@@ -1324,6 +1352,8 @@ message DisconnectPeerRequest {
     string pub_key = 1;
 }
 message DisconnectPeerResponse {
+    // The status of the disconnect operation.
+    string status = 1;
 }
 
 message HTLC {
@@ -3542,6 +3572,8 @@ message NetworkInfo {
 message StopRequest {
 }
 message StopResponse {
+    // The status of the stop operation.
+    string status = 1;
 }
 
 message GraphTopologySubscription {
@@ -4366,9 +4398,13 @@ message DeleteAllPaymentsRequest {
 }
 
 message DeletePaymentResponse {
+    // The status of the delete operation.
+    string status = 1;
 }
 
 message DeleteAllPaymentsResponse {
+    // The status of the delete operation.
+    string status = 1;
 }
 
 message AbandonChannelRequest {
@@ -4385,6 +4421,8 @@ message AbandonChannelRequest {
 }
 
 message AbandonChannelResponse {
+    // The status of the abandon operation.
+    string status = 1;
 }
 
 message DebugLevelRequest {
@@ -4544,6 +4582,15 @@ message PolicyUpdateRequest {
     // Optional inbound fee. If unset, the previously set value will be
     // retained [EXPERIMENTAL].
     InboundFee inbound_fee = 10;
+
+    // Under unknown circumstances a channel can exist with a missing edge in
+    // the graph database. This can cause an 'edge not found' error when calling
+    // `getchaninfo` and/or cause the default channel policy to be used during
+    // forwards. Setting this flag will recreate the edge if not found, allowing
+    // updating this channel policy and fixing the missing edge problem for this
+    // channel permanently. For fields not set in this command, the default
+    // policy will be created.
+    bool create_missing_edge = 11;
 }
 
 enum UpdateFailure {
@@ -4724,12 +4771,15 @@ message RestoreChanBackupRequest {
     }
 }
 message RestoreBackupResponse {
+    // The number of channels successfully restored.
+    uint32 num_restored = 1;
 }
 
 message ChannelBackupSubscription {
 }
 
 message VerifyChanBackupResponse {
+    repeated string chan_points = 1;
 }
 
 message MacaroonPermission {

package/grpc/protos/router.proto

@@ -1064,13 +1064,9 @@ message ForwardHtlcInterceptResponse {
     // the resumed HTLC. This field is ignored if the action is not
     // RESUME_MODIFIED.
     //
-    // If this map is populated, it will overwrite any of the wire custom
-    // records set by LND. It is the caller's responsibility to copy any desired
-    // records across. If the map is empty, no action will be taken and existing
-    // custom records will be propagated.
-    //
-    // The API does not currently support deleting custom records, unless they
-    // are overwritten by a new set.
+    // This map will merge with the existing set of custom records (if any),
+    // replacing any conflicting types. Note that there currently is no support
+    // for deleting existing custom records (they can only be replaced).
     map<uint64, bytes> out_wire_custom_records = 8;
 }
 

package/grpc/protos/walletkit.proto

@@ -414,6 +414,8 @@ message ReleaseOutputRequest {
 }
 
 message ReleaseOutputResponse {
+    // The status of the release operation.
+    string status = 1;
 }
 
 message KeyReq {
@@ -699,6 +701,8 @@ message ImportPublicKeyRequest {
     AddressType address_type = 2;
 }
 message ImportPublicKeyResponse {
+    // The status of the import operation.
+    string status = 1;
 }
 
 message ImportTapscriptRequest {
@@ -1318,6 +1322,8 @@ message LabelTransactionRequest {
 }
 
 message LabelTransactionResponse {
+    // The status of the label operation.
+    string status = 1;
 }
 
 // The possible change address types for default accounts and single imported
@@ -1388,6 +1394,12 @@ message FundPsbtRequest {
         input with.
         */
         uint64 sat_per_vbyte = 4;
+
+        /*
+        The fee rate, expressed in sat/kWU, that should be used to spend the
+        input with.
+        */
+        uint64 sat_per_kw = 11;
     }
 
     /*
@@ -1411,6 +1423,9 @@ message FundPsbtRequest {
 
     // The strategy to use for selecting coins during funding the PSBT.
     lnrpc.CoinSelectionStrategy coin_selection_strategy = 10;
+
+    // The max fee to total output amount ratio that this psbt should adhere to.
+    double max_fee_ratio = 12;
 }
 message FundPsbtResponse {
     /*

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/info/constants.json

@@ -47,6 +47,7 @@
     "b4e7131bdb47531ad2f00ce345ddcdb58935bba5": "0.15.3-beta",
     "bd0c46b4fcb027af1915bd67a3da70e8ca5c6efe": "0.14.3-beta",
     "c0a09209782b1c62c3393fcea0844e095c25046b": "0.15.5-beta",
+    "ddeb8351684a611f6c27f16f09be75d5c039f08c": "0.18.4-beta",
     "d176d2d65fc06e6631c4dc9478592be8545a21de": "0.12.0-beta",
     "d22b3937eae91d33cd8c035e8fa894e3793e1636": "0.18.2-beta",
     "d233f61383f2f950aa06f5b09da5b0e78e784fae": "0.12.1-beta",

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

@@ -7,14 +7,14 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.12.2",
+    "@grpc/grpc-js": "1.12.5",
     "@grpc/proto-loader": "0.7.13",
-    "@types/node": "22.9.1",
+    "@types/node": "22.10.5",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.13",
     "async": "3.2.6",
     "asyncjs-util": "1.2.12",
-    "bitcoinjs-lib": "6.1.6",
+    "bitcoinjs-lib": "6.1.7",
     "bn.js": "5.2.1",
     "bolt07": "1.9.4",
     "bolt09": "2.1.0",
@@ -22,12 +22,12 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.27.0"
+    "type-fest": "4.31.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
     "tsd": "0.31.2",
-    "typescript": "5.6.3"
+    "typescript": "5.7.2"
   },
   "engines": {
     "node": ">=18"
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.22.2"
+  "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;
+  });
+});