lightning 10.18.0 → 10.19.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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/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/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/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/package.json

@@ -9,10 +9,10 @@
   "dependencies": {
     "@grpc/grpc-js": "1.11.1",
     "@grpc/proto-loader": "0.7.13",
-    "@types/node": "22.2.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.24.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.18.0"
+  "version": "10.19.0"
 }

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',