lightning 10.17.0 → 10.19.0

package/CHANGELOG.md

@@ -1,9 +1,21 @@
 # Versions
 
+## 10.19.0
+
+- `createInvoice`: add `is_encrypting_routes` to enable blinded paths feature
+
+- `pay`, `subscribeToPastPayment`, `subscribeToPayViaDetails`,
+    `subscribeToPayViaRequest`, `subscribeToPayments`: Add `is_canceled` for
+    when the payment loop was explicitly canceled.
+
+## 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/lightning.proto

@@ -1190,9 +1190,8 @@ message SendCoinsRequest {
     int64 sat_per_byte = 5 [deprecated = true];
 
     /*
-    If set, then the amount field will be ignored, and lnd will attempt to
-    send all the coins under control of the internal wallet to the specified
-    address.
+    If set, the amount field should be unset. It indicates lnd will send all
+    wallet coins or all selected coins to the specified address.
     */
     bool send_all = 6;
 
@@ -1208,6 +1207,9 @@ message SendCoinsRequest {
 
     // The strategy to use for selecting coins.
     CoinSelectionStrategy coin_selection_strategy = 10;
+
+    // A list of selected outpoints as inputs for the transaction.
+    repeated OutPoint outpoints = 11;
 }
 message SendCoinsResponse {
     // The transaction ID of the transaction
@@ -3836,6 +3838,48 @@ message Invoice {
     Note: Output only, don't specify for creating an invoice.
     */
     map<string, AMPInvoiceState> amp_invoice_state = 28;
+
+    /*
+    Signals that the invoice should include blinded paths to hide the true
+    identity of the recipient.
+    */
+    bool is_blinded = 29;
+
+    /*
+    Config values to use when creating blinded paths for this invoice. These
+    can be used to override the defaults config values provided in by the
+    global config. This field is only used if is_blinded is true.
+    */
+    BlindedPathConfig blinded_path_config = 30;
+}
+
+message BlindedPathConfig {
+    /*
+    The minimum number of real hops to include in a blinded path. This doesn't
+    include our node, so if the minimum is 1, then the path will contain at
+    minimum our node along with an introduction node hop. If it is zero then
+    the shortest path will use our node as an introduction node.
+    */
+    optional uint32 min_num_real_hops = 1;
+
+    /*
+    The number of hops to include in a blinded path. This doesn't include our
+    node, so if it is 1, then the path will contain our node along with an
+    introduction node or dummy node hop. If paths shorter than NumHops is
+    found, then they will be padded using dummy hops.
+    */
+    optional uint32 num_hops = 2;
+
+    /*
+    The maximum number of blinded paths to select and add to an invoice.
+    */
+    optional uint32 max_num_paths = 3;
+
+    /*
+    A list of node IDs of nodes that should not be used in any of our generated
+    blinded paths.
+    */
+    repeated bytes node_omission_list = 4;
 }
 
 enum InvoiceHTLCState {
@@ -4044,6 +4088,11 @@ enum PaymentFailureReason {
     Insufficient local balance.
     */
     FAILURE_REASON_INSUFFICIENT_BALANCE = 5;
+
+    /*
+    The payment was canceled.
+    */
+    FAILURE_REASON_CANCELED = 6;
 }
 
 message Payment {
@@ -4289,6 +4338,7 @@ message PayReq {
     bytes payment_addr = 11;
     int64 num_msat = 12;
     map<uint32, Feature> features = 13;
+    repeated BlindedPaymentPath blinded_paths = 14;
 }
 
 enum FeatureBit {

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/info/get_wallet_info.d.ts

@@ -26,6 +26,8 @@ export type GetWalletInfoResult = {
   }[];
   /** Is Synced To Chain */
   is_synced_to_chain: boolean;
+  /** Is Synced To Network Graph */
+  is_synced_to_graph?: boolean;
   /** Latest Known Block At Date */
   latest_block_at: string;
   /** Peer Count */
@@ -34,6 +36,8 @@ export type GetWalletInfoResult = {
   pending_channels_count: number;
   /** Public Key */
   public_key: string;
+  /** The URIs of the Node */
+  uris?: string[];
   /** Version String */
   version: string;
 };

package/lnd_methods/invoices/create_invoice.js

@@ -31,6 +31,7 @@ const type = 'default';
     [description]: <Invoice Description String>
     [description_hash]: <Hashed Description of Payment Hex String>
     [expires_at]: <Expires At ISO 8601 Date String>
+    [is_encrypting_routes]: <Use Blinded Paths For Inbound Routes Bool>
     [is_fallback_included]: <Is Fallback Address Included Bool>
     [is_fallback_nested]: <Is Fallback Address Nested Bool>
     [is_including_private_channels]: <Invoice Includes Private Channels Bool>
@@ -161,6 +162,7 @@ module.exports = (args, cbk) => {
           description_hash: hexAsBuffer(args.description_hash),
           expiry: !expiryMs ? defaultExpirySec : round(expiryMs / msPerSec),
           fallback_addr: fallbackAddress,
+          is_blinded: !!args.is_encrypting_routes,
           memo: args.description,
           private: !!args.is_including_private_channels,
           r_preimage: preimage || undefined,

package/lnd_methods/offchain/finished_payment.js

@@ -39,6 +39,7 @@ const {returnResult} = require('asyncjs-util');
       tokens: <Total Tokens Paid Rounded Down Number>
     }
     [failed]: {
+      is_canceled: <Payment Canceled Bool>
       is_insufficient_balance: <Failed Due To Lack of Balance Bool>
       is_invalid_payment: <Failed Due to Invalid Payment Bool>
       is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>
@@ -114,6 +115,10 @@ module.exports = ({confirmed, failed}, cbk) => {
           return cbk();
         }
 
+        if (!!failed.is_canceled) {
+          return cbk([503, 'PaymentExecutionCanceled']);
+        }
+
         if (!!failed.is_insufficient_balance) {
           return cbk([503, 'InsufficientBalanceToAttemptPayment']);
         }

package/lnd_methods/offchain/subscribe_to_past_payment.js

@@ -78,6 +78,7 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
   @event 'failed'
   {
     id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Payment Rejected At Destination Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -128,6 +128,7 @@ const unsupportedFeatures = [30, 31];
   @event 'failed'
   {
     id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay_via_details.js

@@ -98,6 +98,7 @@ const type = 'router';
   @event 'failed'
   {
     id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay_via_request.js

@@ -78,6 +78,7 @@ const type = 'router';
   @event 'failed'
   {
     id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_payments.js

@@ -64,6 +64,7 @@ const type = 'router';
   @event 'failed'
   {
     id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Payment Rejected At Destination Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/onchain/get_minimum_relay_fee.d.ts

@@ -0,0 +1,25 @@
+import type {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type GetMinimumRelayFeeArgs = AuthenticatedLightningArgs;
+
+export interface GetMinimumRelayFeeResult {
+  /** Minimum Relayable Tokens Per Virtual Byte Number */
+  tokens_per_vbyte: number;
+}
+
+/**
+ * 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
+ */
+export const getMinimumRelayFee: AuthenticatedLightningMethod<
+  GetMinimumRelayFeeArgs,
+  GetMinimumRelayFeeResult
+>;

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.d.ts

@@ -15,6 +15,7 @@ export * from './get_chain_transaction';
 export * from './get_chain_transactions';
 export * from './get_locked_utxos';
 export * from './get_master_public_keys';
+export * from './get_minimum_relay_fee';
 export * from './get_pending_chain_balance';
 export * from './get_pending_sweeps';
 export * from './get_sweep_transactions';

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_methods/onchain/send_to_chain_address.js

@@ -29,6 +29,10 @@ const unconfirmedConfCount = 0;
     address: <Destination Chain Address String>
     [description]: <Transaction Label String>
     [fee_tokens_per_vbyte]: <Chain Fee Tokens Per Virtual Byte Number>
+    [inputs]: [{
+      transaction_id: <Unspent Transaction Id Hex String>
+      transaction_vout: <Unspent Transaction Output Index Number>
+    }]
     [is_send_all]: <Send All Funds Bool>
     lnd: <Authenticated LND API Object>
     [log]: <Log Function>

package/lnd_responses/constants.json

@@ -29,6 +29,7 @@
   },
   "defaultChannelType": "UNKNOWN_COMMITMENT_TYPE",
   "failureReason": {
+    "canceled": "FAILURE_REASON_CANCELED",
     "invalid_payment": "FAILURE_REASON_INCORRECT_PAYMENT_DETAILS",
     "insufficient_balance": "FAILURE_REASON_INSUFFICIENT_BALANCE",
     "pathfinding_timeout_failed": "FAILURE_REASON_TIMEOUT",

package/lnd_responses/failure_from_payment.js

@@ -14,11 +14,12 @@ const is256Hex = n => !!n && /^[0-9A-F]{64}$/i.test(n);
 
   @returns
   {
-     id: <Payment Hash Hex String>
-     is_insufficient_balance: <Payment Failed Due to Insufficient Balance Bool>
-     is_invalid_payment: <Payment Failed Due to Invalid Details Rejection Bool>
-     is_pathfinding_timeout: <Failure Due To Pathfinding Timeout Failure Bool>
-     is_route_not_found: <Failure Due to No Route To Destination Found Bool>
+    id: <Payment Hash Hex String>
+    is_canceled: <Payment Was Canceled Bool>
+    is_insufficient_balance: <Payment Failed Due to Insufficient Balance Bool>
+    is_invalid_payment: <Payment Failed Due to Invalid Details Rejection Bool>
+    is_pathfinding_timeout: <Failure Due To Pathfinding Timeout Failure Bool>
+    is_route_not_found: <Failure Due to No Route To Destination Found Bool>
   }
 */
 module.exports = payment => {
@@ -30,6 +31,7 @@ module.exports = payment => {
 
   return {
     id: payment.payment_hash,
+    is_canceled: state === failureReason.canceled,
     is_insufficient_balance: state === failureReason.insufficient_balance,
     is_invalid_payment: state === failureReason.invalid_payment,
     is_pathfinding_timeout: state === failureReason.pathfinding_timeout_failed,

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,10 +9,10 @@
   "dependencies": {
     "@grpc/grpc-js": "1.11.1",
     "@grpc/proto-loader": "0.7.13",
-    "@types/node": "22.1.0",
+    "@types/node": "22.5.0",
     "@types/request": "2.48.12",
     "@types/ws": "8.5.12",
-    "async": "3.2.5",
+    "async": "3.2.6",
     "asyncjs-util": "1.2.12",
     "bitcoinjs-lib": "6.1.6",
     "bn.js": "5.2.1",
@@ -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.25.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -45,7 +45,7 @@
     "url": "https://github.com/alexbosworth/lightning.git"
   },
   "scripts": {
-    "test": "npx nyc@15.1.0 node --experimental-test-coverage --test && npm run test:types",
+    "test": "npx nyc@17.0.0 node --experimental-test-coverage --test && npm run test:types",
     "test:types": "tsd",
     "unit-tests": "node --test && npm run test:types"
   },
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.17.0"
+  "version": "10.19.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_failure_from_payment.js

@@ -9,6 +9,7 @@ const id = Buffer.alloc(32).toString('hex')
 const makeExpected = overrides => {
   const expected = {
     id,
+    is_canceled: false,
     is_insufficient_balance: false,
     is_invalid_payment: false,
     is_pathfinding_timeout: false,
@@ -53,6 +54,14 @@ const tests = [
     description: 'Timeout is mapped',
     expected: makeExpected({is_pathfinding_timeout: true}),
   },
+  {
+    args: {
+      failure_reason: 'FAILURE_REASON_CANCELED',
+      payment_hash: id,
+    },
+    description: 'Cancel is mapped',
+    expected: makeExpected({is_canceled: true}),
+  },
   {
     args: {payment_hash: undefined},
     description: 'A payment hash is expected',

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}) => {