lightning 10.17.0 → 10.18.0

package/CHANGELOG.md

@@ -1,9 +1,13 @@
 # Versions
 
+## 10.18.0
+
+- `getMinimumRelayFee`: Add method to get the chain backend minimum relay fee
+
 ## 10.17.0
 
 - `getFeeRates`: Add support for `inbound_base_discount_mtokens`,
-    'inbound_rate_discount` for inbound fee policy discounts
+    `inbound_rate_discount` for inbound fee policy discounts
 
 ## 10.16.1
 

package/README.md

@@ -201,6 +201,8 @@ variables set:
     List out master seed derived extended public keys and derivation paths.
 - [getMethods](https://github.com/alexbosworth/ln-service#getmethods): List RPC methods and
     permissions required to use them.
+- [getMinimumRelayFee](https://github.com/alexbosworth/ln-service#getminimumrelayfee):
+    Get the minimum relayable fee for publishing a chain transaction
 - [getNetworkCentrality](https://github.com/alexbosworth/ln-service#getnetworkcentrality):
     Calculate the graph centrality score of a node.
 - [getNetworkGraph](https://github.com/alexbosworth/ln-service#getnetworkgraph): List all graph

package/grpc/protos/walletkit.proto

@@ -839,6 +839,9 @@ message EstimateFeeResponse {
     confirmation target in the request.
     */
     int64 sat_per_kw = 1;
+
+    // The current minimum relay fee based on our chain backend in sat/kw.
+    int64 min_relay_fee_sat_per_kw = 2;
 }
 
 enum WitnessType {

package/index.js

@@ -61,6 +61,7 @@ const {getInvoices} = require('./lnd_methods');
 const {getLockedUtxos} = require('./lnd_methods');
 const {getMasterPublicKeys} = require('./lnd_methods');
 const {getMethods} = require('./lnd_methods');
+const {getMinimumRelayFee} = require('./lnd_methods');
 const {getNetworkCentrality} = require('./lnd_methods');
 const {getNetworkGraph} = require('./lnd_methods');
 const {getNetworkInfo} = require('./lnd_methods');
@@ -221,6 +222,7 @@ module.exports = {
   getLockedUtxos,
   getMasterPublicKeys,
   getMethods,
+  getMinimumRelayFee,
   getNetworkCentrality,
   getNetworkGraph,
   getNetworkInfo,

package/lnd_methods/index.js

@@ -60,6 +60,7 @@ const {getInvoices} = require('./invoices');
 const {getLockedUtxos} = require('./onchain');
 const {getMasterPublicKeys} = require('./onchain');
 const {getMethods} = require('./info');
+const {getMinimumRelayFee} = require('./onchain');
 const {getNetworkCentrality} = require('./info');
 const {getNetworkGraph} = require('./info');
 const {getNetworkInfo} = require('./info');
@@ -219,6 +220,7 @@ module.exports = {
   getLockedUtxos,
   getMasterPublicKeys,
   getMethods,
+  getMinimumRelayFee,
   getNetworkCentrality,
   getNetworkGraph,
   getNetworkInfo,

package/lnd_methods/onchain/get_minimum_relay_fee.js

@@ -0,0 +1,66 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const method = 'estimateFee';
+const target = 6;
+const type = 'wallet';
+const weightPerKWeight = 1e3;
+const weightPerVByte = 4;
+
+/** Get the current minimum relay fee for the chain backend
+
+  Requires LND built with `walletrpc` tag
+
+  Requires `onchain:read` permission
+
+  This method is not supported on LND 0.18.2 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    tokens_per_vbyte: <Minimum Relayable Tokens Per Virtual Byte Number>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpecteAuthenticatedLndToGetMinRelayFeeRate']);
+        }
+
+        return cbk();
+      },
+
+      // Get the minimum relayable fee rate
+      getRate: ['validate', ({}, cbk) => {
+        return args.lnd[type][method]({conf_target: target}, (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorGettingMinRateFromLnd', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForMinFeeRateRequest']);
+          }
+
+          if (!res.min_relay_fee_sat_per_kw) {
+            return cbk([503, 'ExpectedMinPerKwResponseForMinFeeRateRequest']);
+          }
+
+          const minPerKw = Number(res.min_relay_fee_sat_per_kw);
+
+          const minPerVbyte = minPerKw * weightPerVByte / weightPerKWeight;
+
+          return cbk(null, {tokens_per_vbyte: minPerVbyte});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getRate'}, cbk));
+  });
+};

package/lnd_methods/onchain/index.js

@@ -15,6 +15,7 @@ const getChainTransaction = require('./get_chain_transaction');
 const getChainTransactions = require('./get_chain_transactions');
 const getLockedUtxos = require('./get_locked_utxos');
 const getMasterPublicKeys = require('./get_master_public_keys');
+const getMinimumRelayFee = require('./get_minimum_relay_fee');
 const getPendingChainBalance = require('./get_pending_chain_balance');
 const getPendingSweeps = require('./get_pending_sweeps');
 const getSweepTransactions = require('./get_sweep_transactions');
@@ -59,6 +60,7 @@ module.exports = {
   getChainTransactions,
   getLockedUtxos,
   getMasterPublicKeys,
+  getMinimumRelayFee,
   getPendingChainBalance,
   getPendingSweeps,
   getSweepTransactions,

package/lnd_responses/rpc_fees_as_channel_fees.js

@@ -15,6 +15,8 @@ const outpointDivider = ':';
     chan_id: <Numeric Format Channel Id String>
     channel_point: <Channel Funding Outpoint String>
     fee_per_mil: <Millitokens Per Million Fee Rate String>
+    inbound_base_fee_msat: <Inbound Base Fee Millitokens Number>
+    inbound_fee_per_mil: <Inbound Fee Rate PPM Number>
   }
 
   @returns

package/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@grpc/grpc-js": "1.11.1",
     "@grpc/proto-loader": "0.7.13",
-    "@types/node": "22.1.0",
+    "@types/node": "22.2.0",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.12",
     "async": "3.2.5",
@@ -22,7 +22,7 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.23.0"
+    "type-fest": "4.24.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.17.0"
+  "version": "10.18.0"
 }

package/test/lnd_methods/onchain/test_get_minimum_relay_fee.js

@@ -0,0 +1,71 @@
+const {rejects} = require('node:assert').strict;
+const {strictEqual} = require('node:assert').strict;
+const test = require('node:test');
+
+const {getMinimumRelayFee} = require('./../../../lnd_methods');
+
+const tests = [
+  {
+    args: {},
+    description: 'LND is required',
+    error: [400, 'ExpecteAuthenticatedLndToGetMinRelayFeeRate'],
+  },
+  {
+    args: {lnd: {}},
+    description: 'LND with wallet object is required',
+    error: [400, 'ExpecteAuthenticatedLndToGetMinRelayFeeRate'],
+  },
+  {
+    args: {lnd: {wallet: {}}},
+    description: 'LND with estimateFee method is required',
+    error: [400, 'ExpecteAuthenticatedLndToGetMinRelayFeeRate'],
+  },
+  {
+    args: {
+      lnd: {wallet: {estimateFee: ({}, cbk) => cbk('err')}},
+    },
+    description: 'Unexpected errors are passed back',
+    error: [503, 'UnexpectedErrorGettingMinRateFromLnd', {err: 'err'}],
+  },
+  {
+    args: {
+      lnd: {wallet: {estimateFee: ({}, cbk) => cbk()}},
+    },
+    description: 'A response is expected',
+    error: [503, 'ExpectedResponseForMinFeeRateRequest'],
+  },
+  {
+    args: {
+      lnd: {wallet: {estimateFee: ({}, cbk) => cbk(null, {})}},
+    },
+    description: 'A response is expected',
+    error: [503, 'ExpectedMinPerKwResponseForMinFeeRateRequest'],
+  },
+  {
+    args: {
+      lnd: {
+        wallet: {
+          estimateFee: ({}, cbk) => cbk(null, {
+            min_relay_fee_sat_per_kw: '250',
+          }),
+        },
+      },
+    },
+    description: 'Minimum tokens per vbyte are returned',
+    expected: {tokens_per_vbyte: 1},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async () => {
+    if (!!error) {
+      await rejects(getMinimumRelayFee(args), error, 'Got expected error');
+    } else {
+      const res = await getMinimumRelayFee(args);
+
+      strictEqual(res.tokens_per_vbyte, expected.tokens_per_vbyte, 'Got rate');
+    }
+
+    return;
+  });
+});

package/test/lnd_responses/test_rpc_fees_as_channel_fees.js

@@ -72,6 +72,23 @@ const tests = [
       transaction_vout: 0,
     },
   },
+  {
+    args: makeArgs({
+      inbound_base_fee_msat: -1,
+      inbound_fee_per_mil: -1,
+    }),
+    description: 'RPC channel fees are mapped to inverse channel fees',
+    expected: {
+      base_fee: 0,
+      base_fee_mtokens: '1',
+      fee_rate: 0,
+      id: '0x0x1',
+      inbound_base_discount_mtokens: '1',
+      inbound_rate_discount: 1,
+      transaction_id: Buffer.alloc(32).toString('hex'),
+      transaction_vout: 0,
+    },
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {