lightning 9.10.0 → 9.11.1

package/.github/workflows/unit-test.yml

@@ -11,10 +11,10 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node: ['14', '16', '18']
+        node: ['16', '18', '20']
     steps:
     - uses: actions/checkout@v2
     - uses: actions/setup-node@v2
     - run: npm install
     - name: Run unit tests
-      run: npm test
+      run: npm run unit-tests

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 9.11.1
+
+- `openChannel`: Add `inputs` to select inputs for channel open funding
+
 ## 9.10.0
 
 - `createInvoice`, `createHodlInvoice`: Add `routes` to customize the hop hints

package/grpc/protos/lightning.proto

@@ -2128,6 +2128,76 @@ message BatchOpenChannel {
     the remote peer supports explicit channel negotiation.
     */
     CommitmentType commitment_type = 9;
+
+    /*
+    The maximum amount of coins in millisatoshi that can be pending within
+    the channel. It only applies to the remote party.
+    */
+    uint64 remote_max_value_in_flight_msat = 10;
+
+    /*
+    The maximum number of concurrent HTLCs we will allow the remote party to add
+    to the commitment transaction.
+    */
+    uint32 remote_max_htlcs = 11;
+
+    /*
+    Max local csv is the maximum csv delay we will allow for our own commitment
+    transaction.
+    */
+    uint32 max_local_csv = 12;
+
+    /*
+    If this is true, then a zero-conf channel open will be attempted.
+    */
+    bool zero_conf = 13;
+
+    /*
+    If this is true, then an option-scid-alias channel-type open will be
+    attempted.
+    */
+    bool scid_alias = 14;
+
+    /*
+    The base fee charged regardless of the number of milli-satoshis sent.
+    */
+    uint64 base_fee = 15;
+
+    /*
+    The fee rate in ppm (parts per million) that will be charged in
+    proportion of the value of each forwarded HTLC.
+    */
+    uint64 fee_rate = 16;
+
+    /*
+    If use_base_fee is true the open channel announcement will update the
+    channel base fee with the value specified in base_fee. In the case of
+    a base_fee of 0 use_base_fee is needed downstream to distinguish whether
+    to use the default base fee value specified in the config or 0.
+    */
+    bool use_base_fee = 17;
+
+    /*
+    If use_fee_rate is true the open channel announcement will update the
+    channel fee rate with the value specified in fee_rate. In the case of
+    a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether
+    to use the default fee rate value specified in the config or 0.
+    */
+    bool use_fee_rate = 18;
+
+    /*
+    The number of satoshis we require the remote peer to reserve. This value,
+    if specified, must be above the dust limit and below 20% of the channel
+    capacity.
+    */
+    uint64 remote_chan_reserve_sat = 19;
+
+    /*
+    An optional note-to-self to go along with the channel containing some
+    useful information. This is only ever stored locally and in no way impacts
+    the channel's operation.
+    */
+    string memo = 20;
 }
 
 message BatchOpenChannelResponse {
@@ -2290,6 +2360,11 @@ message OpenChannelRequest {
     the channel's operation.
     */
     string memo = 27;
+
+    /*
+    A list of selected outpoints that are allocated for channel funding.
+    */
+    repeated OutPoint outpoints = 28;
 }
 message OpenStatusUpdate {
     oneof update {

package/lnd_methods/invoices/create_hodl_invoice.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  Routes,
 } from '../../typescript';
 
 export type CreateHodlInvoiceArgs = AuthenticatedLightningArgs<{
@@ -22,6 +23,7 @@ export type CreateHodlInvoiceArgs = AuthenticatedLightningArgs<{
   is_including_private_channels?: boolean;
   /** Millitokens */
   mtokens?: string;
+  routes?: Routes;
   /** Tokens */
   tokens?: number;
 }>;

package/lnd_methods/invoices/create_invoice.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  Routes,
 } from '../../typescript';
 
 export type CreateInvoiceArgs = AuthenticatedLightningArgs<{
@@ -22,6 +23,7 @@ export type CreateInvoiceArgs = AuthenticatedLightningArgs<{
   secret?: string;
   /** Millitokens */
   mtokens?: string;
+  routes?: Routes;
   /** Tokens */
   tokens?: number;
 }>;

package/lnd_methods/offchain/decode_payment_request.d.ts

@@ -1,6 +1,7 @@
 import type {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  Routes,
 } from '../../typescript';
 
 export type DecodePaymentRequestArgs = AuthenticatedLightningArgs<{
@@ -8,21 +9,6 @@ export type DecodePaymentRequestArgs = AuthenticatedLightningArgs<{
   request: string;
 }>;
 
-export type DecodePaymentRouteEdge = {
-  /** Base Routing Fee In Millitokens */
-  base_fee_mtokens?: string;
-  /** Standard Format Channel Id */
-  channel?: string;
-  /** CLTV Blocks Delta */
-  cltv_delta?: number;
-  /** Fees Charged in Millitokens Per Million */
-  fee_rate?: number;
-  /** Forward Edge Public Key Hex */
-  public_key: string;
-};
-
-export type DecodePaymentRoutes = DecodePaymentRouteEdge[][];
-
 export type DecodePaymentRequestResult = {
   /** Fallback Chain Address */
   chain_address: string;
@@ -52,7 +38,7 @@ export type DecodePaymentRequestResult = {
   mtokens: string;
   /** Payment Identifier Hex Encoded */
   payment?: string;
-  routes: DecodePaymentRoutes;
+  routes: Routes;
   /** Requested Tokens Rounded Up */
   safe_tokens: number;
   /** Requested Tokens Rounded Down */

package/lnd_methods/offchain/probe_for_route.d.ts

@@ -2,15 +2,15 @@ import type {MergeExclusive} from 'type-fest';
 import type {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  RouteNode,
 } from '../../typescript';
-import type {DecodePaymentRouteEdge} from './decode_payment_request';
 
-export type ProbeForRouteRouteEdge = DecodePaymentRouteEdge & {
+export type ProbeForRouteNode = RouteNode & {
   /** Channel Capacity Tokens Number */
   channel_capacity?: number;
 };
 
-export type ProbeForRouteRoutes = ProbeForRouteRouteEdge[][];
+export type ProbeForRouteRoutes = ProbeForRouteNode[][];
 
 export type ProbeForRouteArgs = AuthenticatedLightningArgs<
   {

package/lnd_methods/onchain/open_channel.d.ts

@@ -3,6 +3,13 @@ import {
   AuthenticatedLightningMethod,
 } from '../../typescript';
 
+export type ChannelOpenOptionsInput = {
+  /** Fund With Unspent Transaction Id Hex String */
+  transaction_id: string
+  /** Fund With Unspent Transaction Output Index Number */
+  transaction_vout: number
+}
+
 export type ChannelOpenOptions = {
   /** Routing Base Fee Millitokens Charged String */
   base_fee_mtokens?: string;
@@ -16,6 +23,9 @@ export type ChannelOpenOptions = {
   fee_rate?: number;
   /** Tokens to Gift To Partner */
   give_tokens?: number;
+  inputs?: ChannelOpenOptionsInput[]
+  /** Use Maximal Chain Funds For Local Funding Bool */
+  is_max_funding?: boolean;
   /** Channel is Private */
   is_private?: boolean;
   /** Peer Should Avoid Waiting For Confirmation */
@@ -26,10 +36,10 @@ export type ChannelOpenOptions = {
   min_confirmations?: number;
   /** Minimum HTLC Millitokens */
   min_htlc_mtokens?: string;
-  /** Public Key Hex */
-  partner_public_key: string;
   /** Peer Output CSV Delay */
   partner_csv_delay?: number;
+  /** Public Key Hex */
+  partner_public_key: string;
   /** Peer Connection Host:Port */
   partner_socket?: string;
 };
@@ -54,8 +64,18 @@ export type OpenChannelResult = {
  *
  * External funding requires LND compiled with `walletrpc` build tag
  *
+ * `is_trusted_funding` is not supported on LND 0.15.0 and below and requires
+ * `--protocol.option-scid-alias` and `--protocol.zero-conf` set on both sides
+ * as well as a channel open request listener to accept the trusted funding.
+ * 
  * `base_fee_mtokens` is not supported on LND 0.15.5 and below
  * `fee_rate` is not supported on LND 0.15.5 and below
+ * 
+ * `is_max_funding` is not supported on LND 0.16.4 and below
+ * 
+ * `description` is not supported on LND 0.16.4 and below
+ * 
+ * `inputs` is not supported on LND 0.16.4 and below
  */
 export const openChannel: AuthenticatedLightningMethod<
   OpenChannelArgs,

package/lnd_methods/onchain/open_channel.js

@@ -8,11 +8,11 @@ const anchors = 'ANCHORS';
 const defaultMinConfs = 1;
 const defaultMinHtlcMtokens = '1';
 const errMemoLength = /^provided memo \(.*\) is of length \d*, exceeds (\d*)$/;
+const {isArray} = Array;
 const minChannelTokens = 20000;
 const method = 'openChannel';
 const type = 'default';
 
-
 /** Open a new channel.
 
   The capacity of the channel is set with local_tokens
@@ -23,6 +23,10 @@ const type = 'default';
 
   External funding requires LND compiled with `walletrpc` build tag
 
+  `is_trusted_funding` is not supported on LND 0.15.0 and below and requires
+  `--protocol.option-scid-alias` and `--protocol.zero-conf` set on both sides
+  as well as a channel open request listener to accept the trusted funding.
+
   `base_fee_mtokens` is not supported on LND 0.15.5 and below
   `fee_rate` is not supported on LND 0.15.5 and below
 
@@ -30,9 +34,7 @@ const type = 'default';
 
   `description` is not supported on LND 0.16.4 and below
 
-  `is_trusted_funding` is not supported on LND 0.15.0 and below and requires
-  `--protocol.option-scid-alias` and `--protocol.zero-conf` set on both sides
-  as well as a channel open request listener to accept the trusted funding.
+  `inputs` is not supported on LND 0.16.4 and below
 
   {
     [base_fee_mtokens]: <Routing Base Fee Millitokens Charged String>
@@ -41,6 +43,10 @@ const type = 'default';
     [description]: <Immutable Channel Description String>
     [fee_rate]: <Routing Fee Rate In Millitokens Per Million Number>
     [give_tokens]: <Tokens to Gift To Partner Number> // Defaults to zero
+    [inputs]: [{
+      transaction_id: <Fund With Unspent Transaction Id Hex String>
+      transaction_vout: <Fund With Unspent Transaction Output Index Number>
+    }]
     [is_max_funding]: <Use Maximal Chain Funds For Local Funding Bool>
     [is_private]: <Channel is Private Bool> // Defaults to false
     [is_trusted_funding]: <Accept Funding as Trusted Bool>
@@ -76,6 +82,10 @@ module.exports = (args, cbk) => {
           return cbk([400, 'ExpectedLargerChannelSizeForChannelOpen']);
         }
 
+        if (!!args.inputs && !isArray(args.inputs)) {
+          return cbk([400, 'ExpectedArrayOfTransactionOutpointsAsInputs']);
+        }
+
         if (!args.partner_public_key) {
           return cbk([400, 'ExpectedPartnerPublicKeyForChannelOpen']);
         }
@@ -106,8 +116,28 @@ module.exports = (args, cbk) => {
         return cbk(null, args.min_confirmations);
       }],
 
+      // Determine which inputs should be used to fund the channel
+      outpoints: ['validate', ({}, cbk) => {
+        // Exit early when there are no specific UTXOs to spend
+        if (!args.inputs) {
+          return cbk();
+        }
+
+        const utxos = args.inputs.map(input => ({
+          output_index: input.transaction_vout,
+          txid_str: input.transaction_id,
+        }));
+
+        return cbk(null, utxos);
+      }],
+
       // Open the channel
-      openChannel: ['connect', 'minConfs', ({minConfs}, cbk) => {
+      openChannel: [
+        'connect',
+        'minConfs',
+        'outpoints',
+        ({minConfs, outpoints}, cbk) =>
+      {
         let isAnnounced = false;
 
         const options = {
@@ -120,6 +150,7 @@ module.exports = (args, cbk) => {
           min_confs: minConfs,
           min_htlc_msat: args.min_htlc_mtokens || defaultMinHtlcMtokens,
           node_pubkey: Buffer.from(args.partner_public_key, 'hex'),
+          outpoints: outpoints || undefined,
           private: !!args.is_private,
           remote_csv_delay: args.partner_csv_delay || undefined,
           spend_unconfirmed: !minConfs,

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.8.21",
+    "@grpc/grpc-js": "1.9.0",
     "@grpc/proto-loader": "0.7.8",
     "@types/express": "4.17.17",
-    "@types/node": "20.4.5",
+    "@types/node": "20.4.6",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.5",
     "async": "3.2.4",
@@ -52,11 +52,12 @@
   },
   "scripts": {
     "test": "npx nyc@15.1.0 node --experimental-test-coverage --test && npm run test:types",
-    "test:types": "tsd"
+    "test:types": "tsd",
+    "unit-tests": "node --test && npm run test:types"
   },
   "tsd": {
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "9.10.0"
+  "version": "9.11.1"
 }

package/test/lnd_methods/onchain/test_open_channel.js

@@ -121,6 +121,11 @@ const tests = [
     description: 'A public key is required',
     error: [400, 'ExpectedPartnerPublicKeyForChannelOpen'],
   },
+  {
+    args: makeArgs({inputs: 'inputs'}),
+    description: 'A channel is opened with a tx id set',
+    error: [400, 'ExpectedArrayOfTransactionOutpointsAsInputs'],
+  },
   {
     args: makeArgs({
       public_key: Buffer.alloc(33).toString('hex'),
@@ -129,6 +134,16 @@ const tests = [
     description: 'A peer is connected before opening',
     expected: {transaction_id: '04030201', transaction_vout: 0},
   },
+  {
+    args: makeArgs({
+      inputs: [{
+        transaction_id: Buffer.alloc(32).toString('hex'),
+        transaction_vout: 0,
+      }],
+    }),
+    description: 'A channel is opened with a tx id set',
+    expected: {transaction_id: '04030201', transaction_vout: 0},
+  },
   {
     args: makeArgs({}),
     description: 'A channel is opened',

package/test/typescript/create_hodl_invoice.test-d.ts

@@ -1,6 +1,7 @@
 import {expectError, expectType} from 'tsd';
 import {AuthenticatedLnd} from '../../lnd_grpc';
 import {createHodlInvoice, CreateHodlInvoiceResult} from '../../lnd_methods';
+import {Routes} from '../../typescript';
 
 const lnd = {} as AuthenticatedLnd;
 const cltv_delta = 1;
@@ -12,6 +13,13 @@ const is_fallback_nested = true;
 const is_including_private_channels = true;
 const mtokens = '1000';
 const tokens = 1;
+const routes: Routes = [[{
+  base_fee_mtokens: '1',
+  channel: '0',
+  cltv_delta: 1,
+  fee_rate: 1,
+  public_key: 'pubkey'
+}]];
 
 expectError(createHodlInvoice());
 expectError(createHodlInvoice({}));
@@ -29,13 +37,13 @@ expectType<CreateHodlInvoiceResult>(
     is_including_private_channels,
     mtokens,
     tokens,
-  })
+ })
 );
 
 expectType<void>(
   createHodlInvoice({lnd}, (error, result) => {
     expectType<CreateHodlInvoiceResult>(result);
-  })
+ })
 );
 expectType<void>(
   createHodlInvoice(
@@ -49,10 +57,11 @@ expectType<void>(
       is_fallback_nested,
       is_including_private_channels,
       mtokens,
+      routes,
       tokens,
-    },
+   },
     (error, result) => {
       expectType<CreateHodlInvoiceResult>(result);
-    }
+   }
   )
 );

package/test/typescript/create_invoice.test-d.ts

@@ -1,6 +1,7 @@
 import {expectError, expectType} from 'tsd';
 import {AuthenticatedLnd} from '../../lnd_grpc';
 import {createInvoice, CreateInvoiceResult} from '../../lnd_methods';
+import {Routes} from '../../typescript';
 
 const lnd = {} as AuthenticatedLnd;
 const cltv_delta = 1;
@@ -12,6 +13,13 @@ const is_including_private_channels = true;
 const secret = Buffer.alloc(32).toString('hex');
 const mtokens = '1000';
 const tokens = 1;
+const routes: Routes = [[{
+  base_fee_mtokens: '1',
+  channel: '0',
+  cltv_delta: 1,
+  fee_rate: 1,
+  public_key: 'pubkey'
+}]];
 
 expectError(createInvoice());
 expectError(createInvoice({}));
@@ -29,13 +37,13 @@ expectType<CreateInvoiceResult>(
     secret,
     mtokens,
     tokens,
-  })
+ })
 );
 
 expectType<void>(
   createInvoice({lnd}, (error, result) => {
     expectType<CreateInvoiceResult>(result);
-  })
+ })
 );
 expectType<void>(
   createInvoice(
@@ -49,10 +57,11 @@ expectType<void>(
       is_including_private_channels,
       secret,
       mtokens,
+      routes,
       tokens,
-    },
+   },
     (error, result) => {
       expectType<CreateInvoiceResult>(result);
-    }
+   }
   )
 );

package/test/typescript/open_channel.test-d.ts

@@ -10,6 +10,9 @@ const chain_fee_tokens_per_vbyte = 1;
 const cooperative_close_address = 'close_address';
 const give_tokens = 1;
 
+const is_max_funding = true;
+const inputs = [{transaction_id: 'id', transaction_vout: 0}];
+
 expectError(openChannel());
 expectError(openChannel({}));
 expectError(openChannel({local_tokens}));
@@ -29,6 +32,8 @@ expectType<OpenChannelResult>(
     chain_fee_tokens_per_vbyte,
     cooperative_close_address,
     give_tokens,
+    is_max_funding,
+    inputs,
   })
 );
 
@@ -46,6 +51,8 @@ expectType<void>(
       chain_fee_tokens_per_vbyte,
       cooperative_close_address,
       give_tokens,
+      is_max_funding,
+      inputs,
     },
     (error, result) => {
       expectType<OpenChannelResult>(result);

package/typescript/shared.d.ts

@@ -101,3 +101,20 @@ export type DateRangeFilterArgs = {
   /** Creation Date Before or Equal to ISO 8601 Date String */
   created_before?: string;
 };
+
+export type RouteNode = {
+  /** Base Routing Fee In Millitokens */
+  base_fee_mtokens?: string;
+  /** Standard Format Channel Id */
+  channel?: string;
+  /** CLTV Blocks Delta */
+  cltv_delta?: number;
+  /** Fees Charged in Millitokens Per Million */
+  fee_rate?: number;
+  /** Forward Edge Public Key Hex */
+  public_key: string;
+}
+
+export type Route = RouteNode[]
+
+export type Routes = Route[]