lightning 10.8.1 → 10.9.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Versions
 
+## 10.9.0
+
+- `fundPsbt`, `getChainFeeEstimate`, `sendToChainAddress`,
+    `sendToChainAddresses`, `sendToChainOutputScripts`: Add `utxo_selection` to
+    specify preferred coin selection behavior.
+
+## 10.8.2
+
+- `pay` and payment via request methods: disallow features 30/31 from payments
+
 ## 10.8.1
 
 - `removeAdvertisedFeature`: Add method to remove a feature bit support ad

package/grpc/protos/lightning.proto

@@ -1091,6 +1091,18 @@ message LightningAddress {
     string host = 2;
 }
 
+enum CoinSelectionStrategy {
+    // Use the coin selection strategy defined in the global configuration
+    // (lnd.conf).
+    STRATEGY_USE_GLOBAL_CONFIG = 0;
+
+    // Select the largest available coins first during coin selection.
+    STRATEGY_LARGEST = 1;
+
+    // Randomly select the available coins during coin selection.
+    STRATEGY_RANDOM = 2;
+}
+
 message EstimateFeeRequest {
     // The map from addresses to amounts for the transaction.
     map<string, int64> AddrToAmount = 1;
@@ -1105,6 +1117,9 @@ message EstimateFeeRequest {
 
     // Whether unconfirmed outputs should be used as inputs for the transaction.
     bool spend_unconfirmed = 4;
+
+    // The strategy to use for selecting coins during fees estimation.
+    CoinSelectionStrategy coin_selection_strategy = 5;
 }
 
 message EstimateFeeResponse {
@@ -1145,6 +1160,9 @@ message SendManyRequest {
 
     // Whether unconfirmed outputs should be used as inputs for the transaction.
     bool spend_unconfirmed = 8;
+
+    // The strategy to use for selecting coins during sending many requests.
+    CoinSelectionStrategy coin_selection_strategy = 9;
 }
 message SendManyResponse {
     // The id of the transaction
@@ -1187,6 +1205,9 @@ message SendCoinsRequest {
 
     // Whether unconfirmed outputs should be used as inputs for the transaction.
     bool spend_unconfirmed = 9;
+
+    // The strategy to use for selecting coins.
+    CoinSelectionStrategy coin_selection_strategy = 10;
 }
 message SendCoinsResponse {
     // The transaction ID of the transaction
@@ -2115,6 +2136,9 @@ message BatchOpenChannelRequest {
 
     // An optional label for the batch transaction, limited to 500 characters.
     string label = 6;
+
+    // The strategy to use for selecting coins during batch opening channels.
+    CoinSelectionStrategy coin_selection_strategy = 7;
 }
 
 message BatchOpenChannel {
@@ -3330,6 +3354,9 @@ message RoutingPolicy {
 
     // Custom channel update tlv records.
     map<uint64, bytes> custom_records = 8;
+
+    int32 inbound_fee_base_msat = 9;
+    int32 inbound_fee_rate_milli_msat = 10;
 }
 
 /*
@@ -3545,8 +3572,11 @@ message BlindedPaymentPath {
     // The base fee for the blinded path provided, expressed in msat.
     uint64 base_fee_msat = 2;
 
-    // The proportional fee for the blinded path provided, expressed in msat.
-    uint64 proportional_fee_msat = 3;
+    /*
+    The proportional fee for the blinded path provided, expressed in parts
+    per million.
+    */
+    uint32 proportional_fee_rate = 3;
 
     /*
     The total CLTV delta for the blinded path provided, including the
@@ -4306,7 +4336,15 @@ message ChannelFeeReport {
     // The effective fee rate in milli-satoshis. Computed by dividing the
     // fee_per_mil value by 1 million.
     double fee_rate = 4;
+
+    // The base fee charged regardless of the number of milli-satoshis sent.
+    int32 inbound_base_fee_msat = 6;
+
+    // The amount charged per milli-satoshis transferred expressed in
+    // millionths of a satoshi.
+    int32 inbound_fee_per_mil = 7;
 }
+
 message FeeReportResponse {
     // An array of channel fee reports which describes the current fee schedule
     // for each channel.
@@ -4357,7 +4395,11 @@ message PolicyUpdateRequest {
 
     // If true, min_htlc_msat is applied.
     bool min_htlc_msat_specified = 8;
+
+    int32 inbound_base_fee_msat = 10;
+    int32 inbound_fee_rate_ppm = 11;
 }
+
 enum UpdateFailure {
     UPDATE_FAILURE_UNKNOWN = 0;
     UPDATE_FAILURE_PENDING = 1;

package/grpc/protos/walletkit.proto

@@ -813,6 +813,9 @@ message SendOutputsRequest {
 
     // Whether unconfirmed outputs should be used as inputs for the transaction.
     bool spend_unconfirmed = 5;
+
+    // The strategy to use for selecting coins during sending the outputs.
+    lnrpc.CoinSelectionStrategy coin_selection_strategy = 6;
 }
 message SendOutputsResponse {
     /*
@@ -1308,6 +1311,9 @@ message FundPsbtRequest {
     // accounts, no change type should be provided as the coin selection key
     // scope will always be used to generate the change address.
     ChangeAddressType change_type = 8;
+
+    // The strategy to use for selecting coins during funding the PSBT.
+    lnrpc.CoinSelectionStrategy coin_selection_strategy = 10;
 }
 message FundPsbtResponse {
     /*

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -4,6 +4,7 @@ const EventEmitter = require('events');
 const asyncAuto = require('async/auto');
 const {chanFormat} = require('bolt07');
 const {chanNumber} = require('bolt07');
+const {parsePaymentRequest} = require('invoices');
 
 const {confirmedFromPayment} = require('./../../lnd_responses');
 const {confirmedFromPaymentStatus} = require('./../../lnd_responses');
@@ -37,6 +38,7 @@ const {round} = Math;
 const sha256 = preimage => createHash('sha256').update(preimage).digest();
 const type = 'router';
 const unknownServiceErr = 'unknown service verrpc.Versioner';
+const unsupportedFeatures = [30, 31];
 
 /** Initiate and subscribe to the outcome of a payment
 
@@ -252,6 +254,14 @@ module.exports = args => {
     throw new Error('ExpectedTokenAmountToPayWhenPaymentRequestNotSpecified');
   }
 
+  if (!!args.request) {
+    try {
+      parsePaymentRequest({request: args.request});
+    } catch (err) {
+      throw new Error('ExpectedValidPaymentRequestToMakePayment');
+    }
+  }
+
   if (!!args.routes && !isArray(args.routes)) {
     throw new Error('UnexpectedFormatForRoutesWhenSubscribingToPayment');
   }
@@ -296,6 +306,23 @@ module.exports = args => {
   const finalCltv = !args.cltv_delta ? defaultCltvDelta : args.cltv_delta;
 
   asyncAuto({
+    // Determine what features would be used with the payment
+    featureBits: cbk => {
+      // Exit early when there are no features to look at
+      if (!args.features && !args.request) {
+        return cbk(null, []);
+      }
+
+      // Exit early when feature bits are specified directly
+      if (!!features) {
+        return cbk(null, features);
+      }
+
+      const request = parsePaymentRequest({request: args.request});
+
+      return cbk(null, request.features.map(n => n.bit));
+    },
+
     // Determine the block height to figure out the height delta
     getHeight: cbk => {
       // Exit early when there is no max timeout restriction
@@ -325,6 +352,17 @@ module.exports = args => {
       }));
     },
 
+    // Validate the payment request features
+    checkFeatures: ['featureBits', ({featureBits}, cbk) => {
+      const bit = featureBits.find(n => unsupportedFeatures.includes(n));
+
+      if (!!bit) {
+        return cbk([501, 'UnsupportedPaymentFeatureInPayRequest', {bit}]);
+      }
+
+      return cbk();
+    }],
+
     // Determine the maximum CLTV delta
     maxCltvDelta: ['getHeight', ({getHeight}, cbk) => {
       if (!args.max_timeout_height) {
@@ -394,7 +432,7 @@ module.exports = args => {
     }],
 
     // Send payment
-    send: ['params', ({params}, cbk) => {
+    send: ['checkFeatures', 'params', ({params}, cbk) => {
       const sub = args.lnd.router.sendPaymentV2(params);
 
       sub.on('data', data => emitPayment({data, emitter}));

package/lnd_methods/onchain/fund_psbt.js

@@ -16,6 +16,7 @@ const {isArray} = Array;
 const {isBuffer} = Buffer;
 const method = 'fundPsbt';
 const notSupported = /unknown.*walletrpc.WalletKit/;
+const strategy = type => !type ? undefined : `STRATEGY_${type.toUpperCase()}`;
 const type = 'wallet';
 const txIdFromBuffer = buffer => buffer.slice().reverse().toString('hex');
 const txIdFromHash = hash => hash.reverse().toString('hex');
@@ -26,6 +27,8 @@ const txIdFromHash = hash => hash.reverse().toString('hex');
 
   If there are no inputs passed, internal UTXOs will be selected and locked
 
+  `utxo_selection` methods: 'largest', 'random'
+
   Requires `onchain:write` permission
 
   Requires LND built with `walletrpc` tag
@@ -34,6 +37,8 @@ const txIdFromHash = hash => hash.reverse().toString('hex');
 
   Specifying 0 for `min_confirmations` is not supported in LND 0.13.0 and below
 
+  `utxo_selection` is not supported in LND 0.17.4 and below
+
   {
     [fee_tokens_per_vbyte]: <Chain Fee Tokens Per Virtual Byte Number>
     [inputs]: [{
@@ -48,6 +53,7 @@ const txIdFromHash = hash => hash.reverse().toString('hex');
     }]
     [target_confirmations]: <Confirmations To Wait Number>
     [psbt]: <Existing PSBT Hex String>
+    [utxo_selection]: <Select UTXOs Using Method String>
   }
 
   @returns via cbk or Promise
@@ -158,6 +164,7 @@ module.exports = (args, cbk) => {
       fund: ['fee', 'funding', 'minConfs', ({fee, funding, minConfs}, cbk) => {
         return args.lnd[type][method]({
           change_type: defaultChangeType,
+          coin_selection_strategy: strategy(args.utxo_selection),
           min_confs: minConfs !== undefined ? minConfs : undefined,
           psbt: !!args.psbt ? Buffer.from(args.psbt, 'hex') : undefined,
           raw: funding || undefined,

package/lnd_methods/onchain/get_chain_fee_estimate.js

@@ -7,15 +7,20 @@ const hasNumber = n => !!n && n !== '0';
 const {isArray} = Array;
 const method = 'estimateFee';
 const notFound = -1;
+const strategy = type => !type ? undefined : `STRATEGY_${type.toUpperCase()}`;
 const type = 'default';
 const unconfirmedConfCount = 0;
 
 /** Get a chain fee estimate for a prospective chain send
 
+  `utxo_selection` methods: 'largest', 'random'
+
   Requires `onchain:read` permission
 
   Specifying 0 for `utxo_confirmations` is not supported in LND 0.13.0 or below
 
+  `utxo_selection` is not supported in LND 0.17.4 and below
+
   {
     lnd: <Authenticated LND API Object>
     send_to: [{
@@ -24,6 +29,7 @@ const unconfirmedConfCount = 0;
     }]
     [target_confirmations]: <Target Confirmations Number>
     [utxo_confirmations]: <Minimum Confirmations for UTXO Selection Number>
+    [utxo_selection]: <Select UTXOs Using Method String>
   }
 
   @returns via cbk or Promise
@@ -68,6 +74,7 @@ module.exports = (args, cbk) => {
 
         return args.lnd[type][method]({
           AddrToAmount,
+          coin_selection_strategy: strategy(args.utxo_selection),
           target_conf: args.target_confirmations || undefined,
           min_confs: args.utxo_confirmations || undefined,
           spend_unconfirmed: args.utxo_confirmations === unconfirmedConfCount,

package/lnd_methods/onchain/send_to_chain_address.js

@@ -9,16 +9,21 @@ const {isInteger} = Number;
 const lowBalanceErr = 'insufficient funds available to construct transaction';
 const method = 'sendCoins';
 const OPEN = 1;
+const strategy = type => !type ? undefined : `STRATEGY_${type.toUpperCase()}`;
 const {stringify} = JSON;
 const type = 'default';
 const unconfirmedConfCount = 0;
 
 /** Send tokens in a blockchain transaction.
 
+  `utxo_selection` methods: 'largest', 'random'
+
   Requires `onchain:write` permission
 
   `utxo_confirmations` is not supported on LND 0.11.1 or below
 
+  `utxo_selection` is not supported in LND 0.17.4 and below
+
   {
     address: <Destination Chain Address String>
     [description]: <Transaction Label String>
@@ -29,6 +34,7 @@ const unconfirmedConfCount = 0;
     [target_confirmations]: <Confirmations To Wait Number>
     [tokens]: <Tokens To Send Number>
     [utxo_confirmations]: <Minimum Confirmations for UTXO Selection Number>
+    [utxo_selection]: <Select UTXOs Using Method String>
     [wss]: [<Web Socket Server Object>]
   }
 
@@ -82,6 +88,7 @@ module.exports = (args, cbk) => {
         return args.lnd.default.sendCoins({
           addr: args.address,
           amount: args.tokens || undefined,
+          coin_selection_strategy: strategy(args.utxo_selection),
           min_confs: args.utxo_confirmations || undefined,
           label: args.description || undefined,
           sat_per_byte: args.fee_tokens_per_vbyte || undefined,

package/lnd_methods/onchain/send_to_chain_addresses.js

@@ -8,15 +8,20 @@ const {isArray} = Array;
 const method = 'sendMany';
 const OPEN = 1;
 const unconfirmedConfCount = 0;
+const strategy = type => !type ? undefined : `STRATEGY_${type.toUpperCase()}`;
 const {stringify} = JSON;
 const type = 'default';
 
 /** Send tokens to multiple destinations in a blockchain transaction.
 
+  `utxo_selection` methods: 'largest', 'random'
+
   Requires `onchain:write` permission
 
   `utxo_confirmations` is not supported on LND 0.11.1 or below
 
+  `utxo_selection` is not supported in LND 0.17.4 and below
+
   {
     [description]: <Transaction Label String>
     [fee_tokens_per_vbyte]: <Chain Fee Tokens Per Virtual Byte Number>
@@ -28,6 +33,7 @@ const type = 'default';
     }]
     [target_confirmations]: <Confirmations To Wait Number>
     [utxo_confirmations]: <Minimum Confirmations for UTXO Selection Number>
+    [utxo_selection]: <Select UTXOs Using Method String>
     [wss]: [<Web Socket Server Object>]
   }
 
@@ -76,6 +82,7 @@ module.exports = (args, cbk) => {
 
         const send = {
           AddrToAmount,
+          coin_selection_strategy: strategy(args.utxo_selection),
           label: args.description || undefined,
           min_confs: args.utxo_confirmations || undefined,
           sat_per_byte: args.fee_tokens_per_vbyte || undefined,

package/lnd_methods/onchain/send_to_chain_output_scripts.js

@@ -12,17 +12,22 @@ const {isArray} = Array;
 const {isBuffer} = Buffer;
 const method = 'sendOutputs';
 const minFeeRate = 1;
-const unconfirmedConfCount = 0;
+const strategy = type => !type ? undefined : `STRATEGY_${type.toUpperCase()}`;
 const type = 'wallet';
+const unconfirmedConfCount = 0;
 const weightPerKWeight = 1e3;
 const weightPerVByte = 4;
 
 /** Send on-chain funds to multiple output scripts
 
+  `utxo_selection` methods: 'largest', 'random'
+
   Requires `onchain:write` permission
 
   Requires LND compiled with `walletrpc` build tag
 
+  `utxo_selection` is not supported in LND 0.17.4 and below
+
   {
     [description]: <Transaction Label String>
     [fee_tokens_per_vbyte]: <Chain Fee Tokens Per Virtual Byte Number>
@@ -32,6 +37,7 @@ const weightPerVByte = 4;
       tokens: <Tokens Number>
     }]
     [utxo_confirmations]: <Minimum Confirmations for UTXO Selection Number>
+    [utxo_selection]: <Select UTXOs Using Method String>
   }
 
   @returns via cbk or Promise
@@ -66,6 +72,7 @@ module.exports = (args, cbk) => {
         const feePerKw = feePerVByte * weightPerKWeight / weightPerVByte;
 
         return args.lnd[type][method]({
+          coin_selection_strategy: strategy(args.utxo_selection),
           label: args.description || undefined,
           min_confs: args.utxo_confirmations || undefined,
           outputs: args.send_to.map(output => ({

package/package.json

@@ -7,9 +7,9 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.10.3",
-    "@grpc/proto-loader": "0.7.10",
-    "@types/node": "20.11.30",
+    "@grpc/grpc-js": "1.10.6",
+    "@grpc/proto-loader": "0.7.12",
+    "@types/node": "20.12.7",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.10",
     "async": "3.2.5",
@@ -22,12 +22,12 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.13.1"
+    "type-fest": "4.15.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
-    "tsd": "0.30.7",
-    "typescript": "5.4.3"
+    "tsd": "0.31.0",
+    "typescript": "5.4.5"
   },
   "engines": {
     "node": ">=18"
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.8.1"
+  "version": "10.9.0"
 }

package/test/lnd_methods/onchain/test_fund_psbt.js

@@ -169,6 +169,11 @@ const tests = [
     description: 'PSBT funding can specify conf target',
     expected: makeExpected({}),
   },
+  {
+    args: makeArgs({utxo_selection: 'largest'}),
+    description: 'PSBT funding can select largest coins',
+    expected: makeExpected({}),
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/onchain/test_get_chain_fee_estimate.js

@@ -113,6 +113,24 @@ const tests = [
     description: 'Sat per vbyte result is supported',
     expected: {fee: 1, tokens_per_vbyte: 2},
   },
+  {
+    args: {
+      lnd: {
+        default: {
+          estimateFee: ({}, cbk) => cbk(null, {
+            fee_sat: '1',
+            feerate_sat_per_byte: '1',
+            sat_per_vbyte: '2',
+          }),
+        },
+      },
+      send_to: [{address: 'address', tokens: 1}],
+      utxo_confirmations: 0,
+      utxo_selection: 'largest',
+    },
+    description: 'Coin selection can be specified',
+    expected: {fee: 1, tokens_per_vbyte: 2},
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/onchain/test_send_to_chain_address.js

@@ -146,6 +146,17 @@ const tests = [
       tokens: 1,
     },
   },
+  {
+    args: makeArgs({utxo_selection: 'random'}),
+    description: 'Send coins with coin selection',
+    expected: {
+      confirmation_count: 0,
+      id: Buffer.alloc(32).toString('hex'),
+      is_confirmed: false,
+      is_outgoing: true,
+      tokens: 1,
+    },
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/onchain/test_send_to_chain_addresses.js

@@ -130,6 +130,17 @@ const tests = [
       tokens: 1,
     },
   },
+  {
+    args: makeArgs({utxo_selection: 'random'}),
+    description: 'Send coins with coin selection',
+    expected: {
+      confirmation_count: 0,
+      id: Buffer.alloc(32).toString('hex'),
+      is_confirmed: false,
+      is_outgoing: true,
+      tokens: 1,
+    },
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/onchain/test_send_to_chain_output_scripts.js

@@ -61,6 +61,18 @@ const tests = [
       transaction: '01000000000000000000',
     },
   },
+  {
+    args: makeArgs({utxo_selection: 'random'}),
+    description: 'Send coins with coin selection',
+    expected: {
+      confirmation_count: 0,
+      id: 'd21633ba23f70118185227be58a63527675641ad37967e2aa461559f577aec43',
+      is_confirmed: false,
+      is_outgoing: true,
+      tokens: 1,
+      transaction: '01000000000000000000',
+    },
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {