lightning 10.9.1 → 10.10.0

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Versions
 
-## 10.9.1
+## 10.10.0
+
+- `getPendingSweeps`: Add method to get the list of pending outpoints to sweep
+- `requestBatchedFeeIncrease`: Add method to batch a CPFP sweep of an outpoint
+
+## 10.9.2
 
 - Add support for LND v0.17.5-beta
 

package/README.md

@@ -220,6 +220,8 @@ variables set:
     details of opening or closing channels.
 - [getPendingPayments](https://github.com/alexbosworth/ln-service#getpendingpayments): List out
     past pending payments.
+- [getPendingSweeps](https://github.com/alexbosworth/ln-service#getpendingsweeps):
+    List out queued outpoints that are being swept
 - [getPublicKey](https://github.com/alexbosworth/ln-service#getpublickey): Derive a public key at
     a given index.
 - [getRouteConfidence](https://github.com/alexbosworth/ln-service#getrouteconfidence): Check a
@@ -277,6 +279,8 @@ variables set:
     Remove a LN p2p network socket from the node advertisement
 - [removePeer](https://github.com/alexbosworth/ln-service#removepeer): Disconnect from a
     connected peer.
+- [requestBatchedFeeIncrease](https://github.com/alexbosworth/ln-service#requestbatchedfeeincrease):
+    Ask for a batched CPFP chain fee rate increase on a pending confirm UTXO
 - [requestChainFeeIncrease](https://github.com/alexbosworth/ln-service#requestchainfeeincrease):
     Ask for a CPFP chain fee rate increase on a pending confirm UTXO.
 - [revokeAccess](https://github.com/alexbosworth/ln-service#revokeaccess): Remove the access

package/grpc/protos/lightning.proto

@@ -4231,6 +4231,10 @@ message DeleteAllPaymentsRequest {
     Only delete failed HTLCs from payments, not the payment itself.
     */
     bool failed_htlcs_only = 2;
+
+    // Delete all payments. NOTE: Using this option requires careful
+    // consideration as it is a destructive operation.
+    bool all_payments = 3;
 }
 
 message DeletePaymentResponse {
@@ -4307,6 +4311,8 @@ enum FeatureBit {
     ANCHORS_OPT = 21;
     ANCHORS_ZERO_FEE_HTLC_REQ = 22;
     ANCHORS_ZERO_FEE_HTLC_OPT = 23;
+    ROUTE_BLINDING_REQUIRED = 24;
+    ROUTE_BLINDING_OPTIONAL = 25;
     AMP_REQ = 30;
     AMP_OPT = 31;
 }

package/grpc/protos/walletkit.proto

@@ -242,31 +242,34 @@ service WalletKit {
     rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);
 
     /* lncli: `wallet bumpfee`
-    BumpFee bumps the fee of an arbitrary input within a transaction. This RPC
-    takes a different approach than bitcoind's bumpfee command. lnd has a
-    central batching engine in which inputs with similar fee rates are batched
-    together to save on transaction fees. Due to this, we cannot rely on
-    bumping the fee on a specific transaction, since transactions can change at
-    any point with the addition of new inputs. The list of inputs that
-    currently exist within lnd's central batching engine can be retrieved
-    through the PendingSweeps RPC.
-
-    When bumping the fee of an input that currently exists within lnd's central
-    batching engine, a higher fee transaction will be created that replaces the
-    lower fee transaction through the Replace-By-Fee (RBF) policy. If it
+    BumpFee is an endpoint that allows users to interact with lnd's sweeper
+    directly. It takes an outpoint from an unconfirmed transaction and sends it
+    to the sweeper for potential fee bumping. Depending on whether the outpoint
+    has been registered in the sweeper (an existing input, e.g., an anchor
+    output) or not (a new input, e.g., an unconfirmed wallet utxo), this will
+    either be an RBF or CPFP attempt.
+
+    When receiving an input, lnd’s sweeper needs to understand its time
+    sensitivity to make economical fee bumps - internally a fee function is
+    created using the deadline and budget to guide the process. When the
+    deadline is approaching, the fee function will increase the fee rate and
+    perform an RBF.
+
+    When a force close happens, all the outputs from the force closing
+    transaction will be registered in the sweeper. The sweeper will then handle
+    the creation, publish, and fee bumping of the sweeping transactions.
+    Everytime a new block comes in, unless the sweeping transaction is
+    confirmed, an RBF is attempted. To interfere with this automatic process,
+    users can use BumpFee to specify customized fee rate, budget, deadline, and
+    whether the sweep should happen immediately. It's recommended to call
+    `ListSweeps` to understand the shape of the existing sweeping transaction
+    first - depending on the number of inputs in this transaction, the RBF
+    requirements can be quite different.
 
     This RPC also serves useful when wanting to perform a Child-Pays-For-Parent
     (CPFP), where the child transaction pays for its parent's fee. This can be
     done by specifying an outpoint within the low fee transaction that is under
     the control of the wallet.
-
-    The fee preference can be expressed either as a specific fee rate or a delta
-    of blocks in which the output should be swept on-chain within. If a fee
-    preference is not explicitly specified, then an error is returned.
-
-    Note that this RPC currently doesn't perform any validation checks on the
-    fee preference being provided. For now, the responsibility of ensuring that
-    the new fee preference is sufficient is delegated to the user.
     */
     rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse);
 
@@ -280,7 +283,7 @@ service WalletKit {
     /* lncli: `wallet labeltx`
     LabelTransaction adds a label to a transaction. If the transaction already
     has a label the call will fail unless the overwrite bool is set. This will
-    overwrite the exiting transaction label. Labels must not be empty, and
+    overwrite the existing transaction label. Labels must not be empty, and
     cannot exceed 500 characters.
     */
     rpc LabelTransaction (LabelTransactionRequest)
@@ -1105,33 +1108,56 @@ message PendingSweep {
     uint32 broadcast_attempts = 5;
 
     /*
+    Deprecated.
     The next height of the chain at which we'll attempt to broadcast the
     sweep transaction of the output.
     */
-    uint32 next_broadcast_height = 6;
+    uint32 next_broadcast_height = 6 [deprecated = true];
 
-    // The requested confirmation target for this output.
-    uint32 requested_conf_target = 8;
+    /*
+    Deprecated, use immediate.
+    Whether this input must be force-swept. This means that it is swept
+    immediately.
+    */
+    bool force = 7 [deprecated = true];
+
+    /*
+    Deprecated, use deadline.
+    The requested confirmation target for this output, which is the deadline
+    used by the sweeper.
+    */
+    uint32 requested_conf_target = 8 [deprecated = true];
 
     // Deprecated, use requested_sat_per_vbyte.
     // The requested fee rate, expressed in sat/vbyte, for this output.
     uint32 requested_sat_per_byte = 9 [deprecated = true];
 
     /*
-    The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee
-    rate is only determined once a sweeping transaction for the output is
-    created, so it's possible for this to be 0 before this.
+    The current fee rate we'll use to sweep the output, expressed in sat/vbyte.
+    The fee rate is only determined once a sweeping transaction for the output
+    is created, so it's possible for this to be 0 before this.
     */
     uint64 sat_per_vbyte = 10;
 
-    // The requested fee rate, expressed in sat/vbyte, for this output.
+    // The requested starting fee rate, expressed in sat/vbyte, for this
+    // output. When not requested, this field will be 0.
     uint64 requested_sat_per_vbyte = 11;
 
     /*
-    Whether this input must be force-swept. This means that it is swept even
-    if it has a negative yield.
+    Whether this input will be swept immediately.
     */
-    bool force = 7;
+    bool immediate = 12;
+
+    /*
+    The budget for this sweep, expressed in satoshis. This is the maximum amount
+    that can be spent as fees to sweep this output.
+    */
+    uint64 budget = 13;
+
+    /*
+    The deadline height used for this output when perform fee bumping.
+    */
+    uint32 deadline_height = 14;
 }
 
 message PendingSweepsRequest {
@@ -1148,7 +1174,9 @@ message BumpFeeRequest {
     // The input we're attempting to bump the fee of.
     lnrpc.OutPoint outpoint = 1;
 
-    // The target number of blocks that the input should be spent within.
+    // Optional. The deadline in number of blocks that the input should be spent
+    // within. When not set, for new inputs, the default value (1008) is used;
+    // for existing inputs, their current values will be retained.
     uint32 target_conf = 2;
 
     /*
@@ -1159,16 +1187,35 @@ message BumpFeeRequest {
     uint32 sat_per_byte = 3 [deprecated = true];
 
     /*
-    Whether this input must be force-swept. This means that it is swept even
-    if it has a negative yield.
+    Deprecated, use immediate.
+    Whether this input must be force-swept. This means that it is swept
+    immediately.
     */
-    bool force = 4;
+    bool force = 4 [deprecated = true];
 
     /*
-    The fee rate, expressed in sat/vbyte, that should be used to spend the input
-    with.
+    Optional. The starting fee rate, expressed in sat/vbyte, that will be used
+    to spend the input with initially. This value will be used by the sweeper's
+    fee function as its starting fee rate. When not set, the sweeper will use
+    the estimated fee rate using the `target_conf` as the starting fee rate.
     */
     uint64 sat_per_vbyte = 5;
+
+    /*
+    Optional. Whether this input will be swept immediately. When set to true,
+    the sweeper will sweep this input without waiting for the next batch.
+    */
+    bool immediate = 6;
+
+    /*
+    Optional. The max amount in sats that can be used as the fees. Setting this
+    value greater than the input's value may result in CPFP - one or more wallet
+    utxos will be used to pay the fees specified by the budget. If not set, for
+    new inputs, by default 50% of the input's value will be treated as the
+    budget for fee bumping; for existing inputs, their current budgets will be
+    retained.
+    */
+    uint64 budget = 7;
 }
 
 message BumpFeeResponse {

package/index.js

@@ -71,6 +71,7 @@ const {getPeers} = require('./lnd_methods');
 const {getPendingChainBalance} = require('./lnd_methods');
 const {getPendingChannels} = require('./lnd_methods');
 const {getPendingPayments} = require('./lnd_methods');
+const {getPendingSweeps} = require('./lnd_methods');
 const {getPublicKey} = require('./lnd_methods');
 const {getRouteConfidence} = require('./lnd_methods');
 const {getRouteThroughHops} = require('./lnd_methods');
@@ -100,6 +101,7 @@ const {recoverFundsFromChannels} = require('./lnd_methods');
 const {removeAdvertisedFeature} = require('./lnd_methods');
 const {removeExternalSocket} = require('./lnd_methods');
 const {removePeer} = require('./lnd_methods');
+const {requestBatchedFeeIncrease} = require('./lnd_methods');
 const {requestChainFeeIncrease} = require('./lnd_methods');
 const {revokeAccess} = require('./lnd_methods');
 const {sendMessageToPeer} = require('./lnd_methods');
@@ -228,6 +230,7 @@ module.exports = {
   getPendingChainBalance,
   getPendingChannels,
   getPendingPayments,
+  getPendingSweeps,
   getPublicKey,
   getRouteConfidence,
   getRouteThroughHops,
@@ -257,6 +260,7 @@ module.exports = {
   removeAdvertisedFeature,
   removeExternalSocket,
   removePeer,
+  requestBatchedFeeIncrease,
   requestChainFeeIncrease,
   revokeAccess,
   sendMessageToPeer,

package/lnd_methods/index.js

@@ -70,6 +70,7 @@ const {getPeers} = require('./peers');
 const {getPendingChainBalance} = require('./onchain');
 const {getPendingChannels} = require('./offchain');
 const {getPendingPayments} = require('./offchain');
+const {getPendingSweeps} = require('./onchain');
 const {getPublicKey} = require('./address');
 const {getRouteConfidence} = require('./generic');
 const {getRouteThroughHops} = require('./offchain');
@@ -100,6 +101,7 @@ const {recoverFundsFromChannels} = require('./offchain');
 const {removeAdvertisedFeature} = require('./peers');
 const {removeExternalSocket} = require('./peers');
 const {removePeer} = require('./peers');
+const {requestBatchedFeeIncrease} = require('./onchain');
 const {requestChainFeeIncrease} = require('./onchain');
 const {revokeAccess} = require('./macaroon');
 const {sendMessageToPeer} = require('./offchain');
@@ -226,6 +228,7 @@ module.exports = {
   getPendingChainBalance,
   getPendingChannels,
   getPendingPayments,
+  getPendingSweeps,
   getPublicKey,
   getRouteConfidence,
   getRouteThroughHops,
@@ -256,6 +259,7 @@ module.exports = {
   removeAdvertisedFeature,
   removeExternalSocket,
   removePeer,
+  requestBatchedFeeIncrease,
   requestChainFeeIncrease,
   revokeAccess,
   sendMessageToPeer,

package/lnd_methods/macaroon/methods.json

@@ -280,6 +280,10 @@
     "method": "ListPayments",
     "type": "default"
   },
+  "getPendingSweeps": {
+    "method": "PendingSweeps",
+    "type": "wallet"
+  },
   "getPublicKey": {
     "methods": ["DeriveKey", "DeriveNextKey"],
     "type": "wallet"
@@ -400,6 +404,11 @@
     "method": "DisconnectPeer",
     "type": "default"
   },
+  "requestBatchedFeeIncrease": {
+    "depends_on": ["getHeight"],
+    "method": "BumpFee",
+    "type": "wallet"
+  },
   "requestChainFeeIncrease": {
     "method": "BumpFee",
     "type": "wallet"

package/lnd_methods/offchain/delete_payments.js

@@ -30,7 +30,7 @@ module.exports = ({lnd}, cbk) => {
 
       // Delete all payments
       deletePayments: ['validate', ({}, cbk) => {
-        return lnd[type][method]({}, err => {
+        return lnd[type][method]({all_payments: true}, err => {
           if (!!err) {
             return cbk([503, 'UnexpectedErrorDeletingAllPayments', {err}]);
           }

package/lnd_methods/onchain/fund_psbt.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  UtxoSelection,
 } from '../../typescript';
 import {MergeExclusive} from 'type-fest';
 
@@ -57,6 +58,8 @@ export type FundPsbtResult = {
   }[];
   /** Unsigned PSBT Hex */
   psbt: string;
+  /** Select UTXOs Using Method String */
+  utxo_selection?: UtxoSelection;
 };
 
 /**
@@ -73,6 +76,8 @@ export type FundPsbtResult = {
  * This method is not supported in LND 0.11.1 and below
  *
  * Specifying 0 for `min_confirmations` is not supported in LND 0.13.0 and below
+ *
+ * `utxo_selection` is not supported in LND 0.17.5 and below
  */
 export const fundPsbt: AuthenticatedLightningMethod<
   FundPsbtArgs,

package/lnd_methods/onchain/get_chain_fee_estimate.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  UtxoSelection,
 } from '../../typescript';
 
 export type GetChainFeeEstimateArgs = AuthenticatedLightningArgs<{
@@ -14,6 +15,8 @@ export type GetChainFeeEstimateArgs = AuthenticatedLightningArgs<{
   target_confirmations?: number;
   /** Minimum Confirmations for UTXO Selection */
   utxo_confirmations?: number;
+  /** Select UTXOs Using Method String */
+  utxo_selection?: UtxoSelection;
 }>;
 
 export type GetChainFeeEstimateResult = {
@@ -27,6 +30,8 @@ export type GetChainFeeEstimateResult = {
  * Get a chain fee estimate for a prospective chain send
  *
  * Requires `onchain:read` permission
+ *
+ * `utxo_selection` is not supported in LND 0.17.5 and below
  */
 export const getChainFeeEstimate: AuthenticatedLightningMethod<
   GetChainFeeEstimateArgs,

package/lnd_methods/onchain/get_pending_sweeps.js

@@ -0,0 +1,81 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+const {Transaction} = require('bitcoinjs-lib');
+
+const {isLnd} = require('./../../lnd_requests');
+const {rpcSweepAsSweep} = require('./../../lnd_responses');
+
+const {fromHex} = Transaction;
+const {isArray} = Array;
+const method = 'pendingSweeps';
+const notSupportedError = 'unknown service walletrpc.WalletKit';
+const type = 'wallet';
+
+/** Get pending self-transfer spends
+
+  Requires `onchain:read` permission
+
+  Requires LND built with `walletrpc` build tag
+
+  This method is not supported in LND 0.17.5 or below
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    sweeps: [{
+      broadcasts_count: <Total Sweep Broadcast Attempts Count Number>
+      [current_fee_rate]: <Current Chain Fee Rate Tokens Per VByte Number>
+      [initial_fee_rate]: <Requested Chain Fee Rate Tokens per VByte Number>
+      is_batching: <Requested Waiting For Batching Bool>
+      [max_fee]: <Maximum Total Fee Tokens Allowed Number>
+      [max_height]: <Targeted Maximum Confirmation Height Number>
+      tokens: <Sweep Outpoint Tokens Value Number>
+      transaction_id: <Sweeping Outpoint Transaction Id Hex String>
+      transaction_vout: <Sweeping Outpoint Transaction Output Index Number>
+      type: <Outpoint Constraint Script Type String>
+    }]
+  }
+*/
+module.exports = ({lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndToGetPendingSweeps']);
+        }
+
+        return cbk();
+      },
+
+      // Get sweep transaction ids
+      getSweeps: ['validate', ({}, cbk) => {
+        return lnd[type][method]({}, (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedGetPendingSweepsError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseToGetPendingSweepsRequest']);
+          }
+
+          if (!isArray(res.pending_sweeps)) {
+            return cbk([503, 'ExpectedArrayOfPendingSweepsInSweepsResponse']);
+          }
+
+          try {
+            const sweeps = res.pending_sweeps.map(rpcSweepAsSweep);
+
+            return cbk(null, {sweeps});
+          } catch (err) {
+            return cbk([503, err.message]);
+          }
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getSweeps'}, cbk));
+  });
+};

package/lnd_methods/onchain/index.js

@@ -15,6 +15,7 @@ const getChainTransactions = require('./get_chain_transactions');
 const getLockedUtxos = require('./get_locked_utxos');
 const getMasterPublicKeys = require('./get_master_public_keys');
 const getPendingChainBalance = require('./get_pending_chain_balance');
+const getPendingSweeps = require('./get_pending_sweeps');
 const getSweepTransactions = require('./get_sweep_transactions');
 const getUtxos = require('./get_utxos');
 const lockUtxo = require('./lock_utxo');
@@ -23,6 +24,7 @@ const openChannels = require('./open_channels');
 const partiallySignPsbt = require('./partially_sign_psbt');
 const prepareForChannelProposal = require('./prepare_for_channel_proposal');
 const proposeChannel = require('./propose_channel');
+const requestBatchedFeeIncrease = require('./request_batched_fee_increase');
 const requestChainFeeIncrease = require('./request_chain_fee_increase');
 const sendToChainAddress = require('./send_to_chain_address');
 const sendToChainAddresses = require('./send_to_chain_addresses');
@@ -56,6 +58,7 @@ module.exports = {
   getLockedUtxos,
   getMasterPublicKeys,
   getPendingChainBalance,
+  getPendingSweeps,
   getSweepTransactions,
   getUtxos,
   lockUtxo,
@@ -64,6 +67,7 @@ module.exports = {
   partiallySignPsbt,
   prepareForChannelProposal,
   proposeChannel,
+  requestBatchedFeeIncrease,
   requestChainFeeIncrease,
   sendToChainAddress,
   sendToChainAddresses,

package/lnd_methods/onchain/request_batched_fee_increase.js

@@ -0,0 +1,108 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {getHeight} = require('./../generic');
+const {isLnd} = require('./../../lnd_requests');
+
+const defaultTargetConfirmations = 1008;
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const isNumber = n => !isNaN(n);
+const messageExternalUtxo = 'the passed output does not belong to the wallet';
+const method = 'bumpFee';
+const positive = number => number > 0 ? number : 1;
+const type = 'wallet';
+
+/** Request batched CPFP fee bumping of an unconfirmed outpoint on a deadline
+
+  Requires `onchain:write` permission
+
+  Requires LND built with `walletrpc` build tag
+
+  This method is unsupported on LND 0.17.5 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+    [max_fee]: <Maximum Tokens to Pay Into Chain Fees Number>
+    [max_height]: <Maximum Height To Reach a Confirmation Number>
+    transaction_id: <Unconfirmed UTXO Transaction Id Hex String>
+    transaction_vout: <Unconfirmed UTXO Transaction Index Number>
+  }
+
+  @returns via cbk or Promise
+*/
+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, 'ExpectedLndToRequestChainFeeIncrease']);
+        }
+
+        if (!isHash(args.transaction_id)) {
+          return cbk([400, 'ExpectedTransactionIdToRequestChainFeeIncrease']);
+        }
+
+        if (!isNumber(args.transaction_vout)) {
+          return cbk([400, 'ExpectedTransactionOutputIndexToRequestFeeBump']);
+        }
+
+        return cbk();
+      },
+
+      // Get the current height to adjust max height to a conf target delta
+      getHeight: ['validate', ({}, cbk) => {
+        // Exit early when there is no max height specified
+        if (!args.max_height) {
+          return cbk();
+        }
+
+        return getHeight({lnd: args.lnd}, cbk);
+      }],
+
+      // Determine the confirmation target
+      targetConf: ['getHeight', ({getHeight}, cbk) => {
+        // Exit early when there is no max height
+        if (!getHeight) {
+          return cbk(null, defaultTargetConfirmations);
+        }
+
+        const currentBlockHeight = getHeight.current_block_height;
+
+        return cbk(null, positive(args.max_height - currentBlockHeight));
+      }],
+
+      // Make the request to submit the input to the batch sweeper
+      request: ['targetConf', ({targetConf}, cbk) => {
+        return args.lnd[type][method]({
+          budget: args.max_fee,
+          outpoint: {
+            output_index: args.transaction_vout,
+            txid_str: args.transaction_id,
+          },
+          target_conf: targetConf,
+        },
+        (err, res) => {
+          if (!!err && err.details === messageExternalUtxo) {
+            return cbk([404, 'SpecifiedUtxoNotFoundInWalletUtxos']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorRequestingBatchIncrease', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseToBatchedFeeIncreaseRequest']);
+          }
+
+          if (res.status === undefined) {
+            return cbk([503, 'ExpectedStatusOfBatchedFeeIncrease']);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/onchain/request_chain_fee_increase.js

@@ -69,6 +69,7 @@ module.exports = (args, cbk) => {
       request: ['feeRate', ({feeRate}, cbk) => {
         return args.lnd[type][method]({
           force: true,
+          immediate: true,
           outpoint: {
             output_index: args.transaction_vout,
             txid_str: args.transaction_id,

package/lnd_methods/onchain/send_to_chain_address.d.ts

@@ -3,6 +3,7 @@ import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
   LightningError,
+  UtxoSelection,
 } from '../../typescript';
 import {MergeExclusive} from 'type-fest';
 
@@ -38,6 +39,8 @@ export type SendToChainAddressArgs = AuthenticatedLightningArgs<
     target_confirmations?: number;
     /** Minimum Confirmations for UTXO Selection */
     utxo_confirmations?: number;
+    /** Select UTXOs Using Method String */
+    utxo_selection?: UtxoSelection;
   } & ExpectedNoTokensSpecifiedWhenSendingAllFunds &
     ExpectedLogFunctionForChainSendSocketAnnounce
 >;
@@ -61,6 +64,8 @@ export type SendToChainAddressResult = {
  * 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.5 and below
  */
 export const sendToChainAddress: AuthenticatedLightningMethod<
   SendToChainAddressArgs,

package/lnd_methods/onchain/send_to_chain_addresses.d.ts

@@ -3,6 +3,7 @@ import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
   LightningError,
+  UtxoSelection,
 } from '../../typescript';
 import {MergeExclusive} from 'type-fest';
 
@@ -32,6 +33,8 @@ export type SendToChainAddressesArgs = AuthenticatedLightningArgs<
     target_confirmations?: number;
     /** Minimum Confirmations for UTXO Selection */
     utxo_confirmations?: number;
+    /** Select UTXOs Using Method String */
+    utxo_selection?: UtxoSelection;
   } & ExpectedLogForChainSendWebSocketAnnouncement
 >;
 
@@ -54,6 +57,8 @@ export type SendToChainAddressesResult = {
  * 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.5 and below
  */
 export const sendToChainAddresses: AuthenticatedLightningMethod<
   SendToChainAddressesArgs,

package/lnd_methods/onchain/send_to_chain_output_scripts.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  UtxoSelection,
 } from '../../typescript';
 import {MergeExclusive} from 'type-fest';
 
@@ -17,6 +18,8 @@ export type SendToChainOutputScriptsArgs = AuthenticatedLightningArgs<{
   }[];
   /** Minimum Confirmations for UTXO Selection Number */
   utxo_confirmations?: number;
+  /** Select UTXOs Using Method String */
+  utxo_selection?: UtxoSelection;
 }>;
 
 export type SendToChainOutputScriptsResult = {
@@ -40,6 +43,8 @@ export type SendToChainOutputScriptsResult = {
  * Requires `onchain:write` permission
  *
  * Requires LND compiled with `walletrpc` build tag
+ *
+ * `utxo_selection` is not supported in LND 0.17.5 and below
  */
 export const sendToChainOutputScripts: AuthenticatedLightningMethod<
   SendToChainOutputScriptsArgs,

package/lnd_responses/index.js

@@ -38,6 +38,7 @@ const rpcPeerMessageAsMessage = require('./rpc_peer_message_as_message');
 const rpcRequestUpdateAsEvent = require('./rpc_request_update_as_event');
 const rpcResolutionAsResolution = require('./rpc_resolution_as_resolution');
 const rpcRouteAsRoute = require('./rpc_route_as_route');
+const rpcSweepAsSweep = require('./rpc_sweep_as_sweep');
 const rpcTxAsTransaction = require('./rpc_tx_as_transaction');
 const rpcUtxoAsUtxo = require('./rpc_utxo_as_utxo');
 const rpcWalletStateAsState = require('./rpc_wallet_state_as_state');
@@ -83,6 +84,7 @@ module.exports = {
   rpcRequestUpdateAsEvent,
   rpcResolutionAsResolution,
   rpcRouteAsRoute,
+  rpcSweepAsSweep,
   rpcTxAsTransaction,
   rpcUtxoAsUtxo,
   rpcWalletStateAsState,

package/lnd_responses/rpc_sweep_as_sweep.js

@@ -0,0 +1,96 @@
+const isBoolean = n => n === false || n === true;
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const isNumber = n => !isNaN(n);
+
+/** Convert an RPC sweep into a sweep
+
+  {
+    amount_sat: <Outpoint Value Tokens Number>
+    broadcast_attempts: <Count of Past Sweep Broadcasts Number>
+    budget: <Maximum Fee Tokens to Spend On Sweeping String>
+    deadline_height: <Maximum Confirmation Height Number>
+    immediate: <Sweep Was Specified To Skip Waiting For Batching Bool>
+    outpoint: {
+      output_index: <Transaction Output Index Number>
+      txid_str: <Transaction Id Hex String>
+    }
+    requested_sat_per_vbyte: <Requested Chain Fee Rate Tokens Per VByte String>
+    sat_per_vbyte: <Current Sweeping Chain Fee Rate Tokens Per VByte String>
+    witness_type: <Witness Type String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    broadcasts_count: <Total Sweep Broadcast Attempts Count Number>
+    [current_fee_rate]: <Current Chain Fee Rate Tokens Per VByte Number>
+    [initial_fee_rate]: <Requested Chain Fee Rate Tokens per VByte Number>
+    is_batching: <Requested Waiting For Batching Bool>
+    [max_fee]: <Maximum Total Fee Tokens Allowed Number>
+    [max_height]: <Targeted Maximum Confirmation Height Number>
+    tokens: <Sweep Outpoint Tokens Value Number>
+    transaction_id: <Sweeping Outpoint Transaction Id Hex String>
+    transaction_vout: <Sweeping Outpoint Transaction Output Index Number>
+    type: <Outpoint Constraint Script Type String>
+  }
+*/
+module.exports = args => {
+  if (!args) {
+    throw new Error('ExpectedSweepDetailsToDerivePendingSweep');
+  }
+
+  if (args.amount_sat === undefined) {
+    throw new Error('ExpectedSweepOutpointValueAmountInPendingSweep');
+  }
+
+  if (!isNumber(args.broadcast_attempts)) {
+    throw new Error('ExpectedBroadcastAttemptsForSweepInPendingSweep');
+  }
+
+  if (!args.budget) {
+    throw new Error('ExpectedSweepBudgetAmountForSweepInPendingSweeps');
+  }
+
+  if (!isNumber(args.deadline_height)) {
+    throw new Error('ExpectedSweepConfirmationDeadlineHeightInPendingSweep');
+  }
+
+  if (!isBoolean(args.immediate)) {
+    throw new Error('ExpectedImmediateStatusOfSweepInPendingSweeps');
+  }
+
+  if (!args.outpoint) {
+    throw new Error('ExpectedUnspentOutpointOfSweepInPendingSweeps');
+  }
+
+  if (!isNumber(args.outpoint.output_index)) {
+    throw new Error('ExpectedOutputIndexOfSweepInPendingSweeps');
+  }
+
+  if (!isHash(args.outpoint.txid_str)) {
+    throw new Error('ExpectedOutpointTransactionIdHexStringInSweep');
+  }
+
+  if (!args.requested_sat_per_vbyte) {
+    throw new Error('ExpectedRequestedSatPerVByteForSweepInPendingSweeps');
+  }
+
+  if (!args.sat_per_vbyte) {
+    throw new Error('ExpectedSatPerVByteForSweepInPendingSweeps');
+  }
+
+  return {
+    broadcasts_count: args.broadcast_attempts,
+    current_fee_rate: Number(args.sat_per_vbyte) || undefined,
+    initial_fee_rate: Number(args.requested_sat_per_vbyte) || undefined,
+    is_batching: !args.immediate,
+    max_fee: Number(args.budget) || undefined,
+    max_height: args.deadline_height || undefined,
+    tokens: args.amount_sat,
+    transaction_id: args.outpoint.txid_str,
+    transaction_vout: args.outpoint.output_index,
+    type: args.witness_type.toLowerCase(),
+  };
+};

package/package.json

@@ -7,9 +7,9 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.10.6",
-    "@grpc/proto-loader": "0.7.12",
-    "@types/node": "20.12.7",
+    "@grpc/grpc-js": "1.10.7",
+    "@grpc/proto-loader": "0.7.13",
+    "@types/node": "20.12.8",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.10",
     "async": "3.2.5",
@@ -17,12 +17,12 @@
     "bitcoinjs-lib": "6.1.5",
     "bn.js": "5.2.1",
     "bolt07": "1.8.4",
-    "bolt09": "2.0.0",
+    "bolt09": "2.1.0",
     "ecpair": "2.1.0",
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.16.0"
+    "type-fest": "4.18.1"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.9.1"
+  "version": "10.10.0"
 }

package/test/lnd_methods/onchain/test_get_pending_sweeps.js

@@ -0,0 +1,92 @@
+const {strictEqual} = require('node:assert').strict;
+const {rejects} = require('node:assert').strict;
+const test = require('node:test');
+
+const {getPendingSweeps} = require('./../../../lnd_methods');
+
+const tests = [
+  {
+    args: {},
+    description: 'LND Object is required to get pending sweeps',
+    error: [400, 'ExpectedLndToGetPendingSweeps'],
+  },
+  {
+    args: {lnd: {wallet: {pendingSweeps: ({}, cbk) => cbk('err')}}},
+    description: 'Errors are passed back from method',
+    error: [503, 'UnexpectedGetPendingSweepsError', {err: 'err'}],
+  },
+  {
+    args: {lnd: {wallet: {pendingSweeps: ({}, cbk) => cbk()}}},
+    description: 'A result is expected from the method',
+    error: [503, 'ExpectedResponseToGetPendingSweepsRequest'],
+  },
+  {
+    args: {lnd: {wallet: {pendingSweeps: ({}, cbk) => cbk(null, {})}}},
+    description: 'An array of sweeps is expected in response',
+    error: [503, 'ExpectedArrayOfPendingSweepsInSweepsResponse'],
+  },
+  {
+    args: {
+      lnd: {
+        wallet: {
+          pendingSweeps: ({}, cbk) => cbk(null, {pending_sweeps: [null]}),
+        },
+      },
+    },
+    description: 'An array of sweeps is expected in response',
+    error: [503, 'ExpectedSweepDetailsToDerivePendingSweep'],
+  },
+  {
+    args: {
+      lnd: {
+        wallet: {
+          pendingSweeps: ({}, cbk) => cbk(null, {
+            pending_sweeps: [{
+              amount_sat: 0,
+              broadcast_attempts: 0,
+              budget: '0',
+              deadline_height: 0,
+              immediate: true,
+              outpoint: {
+                output_index: 0,
+                txid_str: Buffer.alloc(32).toString('hex'),
+              },
+              requested_sat_per_vbyte: '0',
+              sat_per_vbyte: '0',
+              witness_type: 'witness_type',
+            }],
+          }),
+        },
+      },
+    },
+    description: 'Pending sweeps are returned',
+    expected: {
+      sweeps: [{
+        broadcasts_count: 0,
+        current_fee_rate: undefined,
+        initial_fee_rate: undefined,
+        is_batching: false,
+        max_fee: undefined,
+        max_height: undefined,
+        tokens: 0,
+        transaction_id: Buffer.alloc(32).toString('hex'),
+        transaction_vout: 0,
+        type: 'witness_type',
+      }],
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async () => {
+    if (!!error) {
+      await rejects(() => getPendingSweeps(args), error, 'Got expected error');
+    } else {
+      const res = await getPendingSweeps(args);
+
+      strictEqual(res.chain_balance, expected.chain_balance, 'Got balance');
+    }
+
+    return;
+  });
+});

package/test/lnd_methods/onchain/test_request_batched_fee_increase.js

@@ -0,0 +1,111 @@
+const EventEmitter = require('events');
+const {rejects} = require('node:assert').strict;
+const test = require('node:test');
+
+const {requestBatchedFeeIncrease} = require('./../../../lnd_methods');
+
+const makeLnd = overrides => {
+  const res = {status: 'status'};
+
+  Object.keys(overrides).forEach(k => res[k] = overrides[k]);
+
+  return {
+    chain: {
+      registerBlockEpochNtfn: ({}) => {
+        const emitter = new EventEmitter();
+
+        emitter.cancel = () => {};
+
+        process.nextTick(() => emitter.emit('data', {
+          hash: Buffer.alloc(32),
+          height: 500,
+        }));
+
+        return emitter;
+      },
+    },
+    wallet: {bumpFee: (args, cbk) => cbk(null, res)},
+  };
+};
+
+const makeArgs = overrides => {
+  const args = {
+    lnd: makeLnd({}),
+    transaction_id: Buffer.alloc(32).toString('hex'),
+    transaction_vout: 0,
+  };
+
+  Object.keys(overrides).forEach(key => args[key] = overrides[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'An LND object is required',
+    error: [400, 'ExpectedLndToRequestChainFeeIncrease'],
+  },
+  {
+    args: makeArgs({transaction_id: undefined}),
+    description: 'A transaction id is required',
+    error: [400, 'ExpectedTransactionIdToRequestChainFeeIncrease'],
+  },
+  {
+    args: makeArgs({transaction_vout: undefined}),
+    description: 'A tx output index is required',
+    error: [400, 'ExpectedTransactionOutputIndexToRequestFeeBump'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        wallet: {
+          bumpFee: ({}, cbk) => cbk({
+            details: 'the passed output does not belong to the wallet',
+          }),
+        },
+      },
+    }),
+    description: 'Unknown UTXO error is passed back',
+    error: [404, 'SpecifiedUtxoNotFoundInWalletUtxos'],
+  },
+  {
+    args: makeArgs({lnd: {wallet: {bumpFee: ({}, cbk) => cbk('err')}}}),
+    description: 'Errors are passed back',
+    error: [503, 'UnexpectedErrorRequestingBatchIncrease', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: {wallet: {bumpFee: ({}, cbk) => cbk()}}}),
+    description: 'A response is expected',
+    error: [503, 'ExpectedResponseToBatchedFeeIncreaseRequest'],
+  },
+  {
+    args: makeArgs({lnd: {wallet: {bumpFee: ({}, cbk) => cbk(null, {})}}}),
+    description: 'A response status is expected',
+    error: [503, 'ExpectedStatusOfBatchedFeeIncrease'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Fee bump is requested',
+  },
+  {
+    args: makeArgs({max_height: 1000}),
+    description: 'Fee bump is requested with a height',
+  },
+  {
+    args: makeArgs({max_height: 2}),
+    description: 'Fee bump is requested with a low height',
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async () => {
+    if (!!error) {
+      await rejects(requestBatchedFeeIncrease(args), error, 'Got error');
+    } else {
+      await requestBatchedFeeIncrease(args);
+    }
+
+    return;
+  });
+});

package/test/lnd_responses/test_rpc_sweep_as_sweep.js

@@ -0,0 +1,135 @@
+const {deepEqual} = require('node:assert').strict;
+const test = require('node:test');
+const {throws} = require('node:assert').strict;
+
+const {rpcSweepAsSweep} = require('./../../lnd_responses');
+
+const makeArgs = overrides => {
+  const response = {
+    amount_sat: 0,
+    broadcast_attempts: 0,
+    budget: '0',
+    deadline_height: 0,
+    immediate: true,
+    outpoint: {
+      output_index: 0,
+      txid_str: Buffer.alloc(32).toString('hex'),
+    },
+    requested_sat_per_vbyte: '0',
+    sat_per_vbyte: '0',
+    witness_type: 'witness_type',
+  };
+
+  Object.keys(overrides || {}).forEach(key => response[key] = overrides[key]);
+
+  return response;
+};
+
+
+const makeExpected = overrides => {
+  const expected = {
+    broadcasts_count: 0,
+    current_fee_rate: undefined,
+    initial_fee_rate: undefined,
+    is_batching: false,
+    max_fee: undefined,
+    max_height: undefined,
+    tokens: 0,
+    transaction_id: Buffer.alloc(32).toString('hex'),
+    transaction_vout: 0,
+    type: 'witness_type',
+  };
+
+  Object.keys(overrides || {}).forEach(key => expected[key] = overrides[key]);
+
+  return expected;
+};
+
+const tests = [
+  {
+    description: 'Pending sweep details are expected',
+    error: 'ExpectedSweepDetailsToDerivePendingSweep',
+  },
+  {
+    args: makeArgs({amount_sat: undefined}),
+    description: 'The sweep amount is expected',
+    error: 'ExpectedSweepOutpointValueAmountInPendingSweep',
+  },
+  {
+    args: makeArgs({broadcast_attempts: undefined}),
+    description: 'The broadcasts count is expected',
+    error: 'ExpectedBroadcastAttemptsForSweepInPendingSweep',
+  },
+  {
+    args: makeArgs({budget: undefined}),
+    description: 'The sweep budget is expected',
+    error: 'ExpectedSweepBudgetAmountForSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({deadline_height: undefined}),
+    description: 'The target deadline is expected',
+    error: 'ExpectedSweepConfirmationDeadlineHeightInPendingSweep',
+  },
+  {
+    args: makeArgs({immediate: undefined}),
+    description: 'The immediate status is expected',
+    error: 'ExpectedImmediateStatusOfSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({outpoint: undefined}),
+    description: 'The outpoint being swept is expected',
+    error: 'ExpectedUnspentOutpointOfSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({outpoint: {}}),
+    description: 'The outpoint vout being swept is expected',
+    error: 'ExpectedOutputIndexOfSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({outpoint: {output_index: 0}}),
+    description: 'The outpoint transaction id being swept is expected',
+    error: 'ExpectedOutpointTransactionIdHexStringInSweep',
+  },
+  {
+    args: makeArgs({requested_sat_per_vbyte: undefined}),
+    description: 'The requested sweeping chain fee rate is expected',
+    error: 'ExpectedRequestedSatPerVByteForSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({sat_per_vbyte: undefined}),
+    description: 'The sweeping chain fee rate is expected',
+    error: 'ExpectedSatPerVByteForSweepInPendingSweeps',
+  },
+  {
+    args: makeArgs({}),
+    description: 'RPC sweep is mapped to pending sweep details',
+    expected: makeExpected({}),
+  },
+  {
+    args: makeArgs({
+      budget: '1',
+      deadline_height: 1,
+      requested_sat_per_vbyte: '1',
+      sat_per_vbyte: '1',
+    }),
+    description: 'RPC sweep with all details is mapped to pending sweep ',
+    expected: makeExpected({
+      current_fee_rate: 1,
+      initial_fee_rate: 1,
+      max_fee: 1,
+      max_height: 1,
+    }),
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, (t, end) => {
+    if (!!error) {
+      throws(() => rpcSweepAsSweep(args), new Error(error), 'Got err');
+    } else {
+      deepEqual(rpcSweepAsSweep(args), expected, 'RPC sweep mapped');
+    }
+
+    return end();
+  });
+});

package/typescript/shared.d.ts

@@ -118,3 +118,5 @@ export type RouteNode = {
 export type Route = RouteNode[]
 
 export type Routes = Route[]
+
+export type UtxoSelection = "largest" | "random";