lightning 9.9.1 → 9.11.0

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,13 @@
 # Versions
 
+## 9.11.0
+
+- `openChannel`: Add `inputs` to select inputs for channel open funding
+
+## 9.10.0
+
+- `createInvoice`, `createHodlInvoice`: Add `routes` to customize the hop hints
+
 ## 9.9.1
 
 - `openChannel`: Add `is_trusted_funding` to support skipping confirmation wait

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/info/get_route_to_destination.js

@@ -221,7 +221,7 @@ module.exports = (args, cbk) => {
         }
 
         const hints = args.routes.map(route => {
-          return {hop_hints: routeHintFromRoute({route}).hops}
+          return {hop_hints: routeHintFromRoute({route}).hops};
         });
 
         return cbk(null, hints);

package/lnd_methods/invoices/create_hodl_invoice.js

@@ -7,6 +7,7 @@ const {returnResult} = require('asyncjs-util');
 
 const {createChainAddress} = require('./../address');
 const {isLnd} = require('./../../lnd_requests');
+const {routeHintFromRoute} = require('./../../lnd_requests');
 
 const hexAsBuffer = hex => !!hex ? Buffer.from(hex, 'hex') : undefined;
 const {isArray} = Array;
@@ -41,6 +42,13 @@ const type = 'invoices';
     [is_including_private_channels]: <Invoice Includes Private Channels Bool>
     lnd: <Authenticated LND API Object>
     [mtokens]: <Millitokens String>
+    [routes]: [[{
+      [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
+      [channel]: <Standard Format Channel Id String>
+      [cltv_delta]: <CLTV Blocks Delta Number>
+      [fee_rate]: <Fee Rate In Millitokens Per Million Number>
+      public_key: <Forward Edge Public Key Hex String>
+    }]]
     [tokens]: <Tokens Number>
   }
 
@@ -65,6 +73,10 @@ module.exports = (args, cbk) => {
           return cbk([400, 'ExpectedInvoicesLndToCreateHodlInvoice']);
         }
 
+        if (!!args.routes && !isArray(args.routes)) {
+          return cbk([400, 'ExpectedArrayOfHopHintPathsForRoutes']);
+        }
+
         return cbk();
       },
 
@@ -80,6 +92,20 @@ module.exports = (args, cbk) => {
         return createChainAddress({format, lnd: args.lnd}, cbk);
       }],
 
+      // Determine the route hints
+      hints: ['validate', ({}, cbk) => {
+        // Exit early when there are no route hints for the invoice
+        if (!args.routes) {
+          return cbk();
+        }
+
+        const hints = args.routes.map(route => {
+          return {hop_hints: routeHintFromRoute({route}).hops};
+        });
+
+        return cbk(null, hints);
+      }],
+
       // Generate id if needed
       invoiceId: ['validate', ({}, cbk) => {
         if (!!args.id) {
@@ -97,8 +123,9 @@ module.exports = (args, cbk) => {
       // Add invoice
       addInvoice: [
         'addAddress',
+        'hints',
         'invoiceId',
-        ({addAddress, invoiceId}, cbk) =>
+        ({addAddress, hints, invoiceId}, cbk) =>
       {
         const fallbackAddress = !addAddress ? undefined : addAddress.address;
         const createdAt = new Date();
@@ -117,6 +144,7 @@ module.exports = (args, cbk) => {
           hash: Buffer.from(invoiceId.id, 'hex'),
           memo: args.description,
           private: !!args.is_including_private_channels,
+          route_hints: hints || undefined,
           value: args.tokens || undefined,
           value_msat: args.mtokens || undefined,
         },

package/lnd_methods/invoices/create_invoice.js

@@ -6,6 +6,7 @@ const {createChainAddress} = require('./../address');
 const getInvoice = require('./get_invoice');
 const {isLnd} = require('./../../lnd_requests');
 const {mtokensAmount} = require('./../../bolt00');
+const {routeHintFromRoute} = require('./../../lnd_requests');
 
 const defaultExpirySec = 60 * 60 * 3;
 const hexAsBuffer = hex => !!hex ? Buffer.from(hex, 'hex') : undefined;
@@ -36,6 +37,13 @@ const type = 'default';
     lnd: <Authenticated LND API Object>
     [secret]: <Payment Preimage Hex String>
     [mtokens]: <Millitokens String>
+    [routes]: [[{
+      [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
+      [channel]: <Standard Format Channel Id String>
+      [cltv_delta]: <CLTV Blocks Delta Number>
+      [fee_rate]: <Fee Rate In Millitokens Per Million Number>
+      public_key: <Forward Edge Public Key Hex String>
+    }]]
     [tokens]: <Tokens Number>
   }
 
@@ -86,6 +94,10 @@ module.exports = (args, cbk) => {
           }
         }
 
+        if (!!args.routes && !isArray(args.routes)) {
+          return cbk([400, 'ExpectedArrayOfHopHintPathsForRoutes']);
+        }
+
         return cbk();
       },
 
@@ -101,6 +113,20 @@ module.exports = (args, cbk) => {
         return createChainAddress({format, lnd: args.lnd}, cbk);
       }],
 
+      // Determine the route hints
+      hints: ['validate', ({}, cbk) => {
+        // Exit early when there are no route hints for the invoice
+        if (!args.routes) {
+          return cbk();
+        }
+
+        const hints = args.routes.map(route => {
+          return {hop_hints: routeHintFromRoute({route}).hops};
+        });
+
+        return cbk(null, hints);
+      }],
+
       // Determine the value of the invoice
       mtokens: ['validate', ({}, cbk) => {
         // Exit early when there are no mtokens
@@ -119,9 +145,10 @@ module.exports = (args, cbk) => {
       // Add invoice
       addInvoice: [
         'addAddress',
+        'hints',
         'mtokens',
         'preimage',
-        ({addAddress, mtokens, preimage}, cbk) =>
+        ({addAddress, hints, mtokens, preimage}, cbk) =>
       {
         const fallbackAddress = !addAddress ? String() : addAddress.address;
         const createdAt = new Date();
@@ -137,6 +164,7 @@ module.exports = (args, cbk) => {
           memo: args.description,
           private: !!args.is_including_private_channels,
           r_preimage: preimage || undefined,
+          route_hints: hints || undefined,
           value_msat: mtokens,
         },
         (err, response) => {

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.19",
+    "@grpc/grpc-js": "1.9.0",
     "@grpc/proto-loader": "0.7.8",
     "@types/express": "4.17.17",
-    "@types/node": "20.4.4",
+    "@types/node": "20.4.6",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.5",
     "async": "3.2.4",
@@ -26,7 +26,7 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.0.0"
+    "type-fest": "4.1.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -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.9.1"
+  "version": "9.11.0"
 }

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