lightning 9.3.0 → 9.4.0

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Versions
 
-## 9.3.0
+## 9.4.0
+
+- `getChannels`: Add `description` to show the channel description
+- `openChannel`, `openChannels`, `proposeChannel`: Add `description` to set
+    the channel description
+- `subscribeToChannels`: Add `description` to `channel_opened`
+- `subscribeToRpcRequests`: Add `description` to `open_channel_request`
+
+## 9.3.1
 
 - `subscribeToPastPayment`, `subscribeToPayViaDetails`,
     `subscribeToPayViaRequest`, `subscribeToPayments`: Add `id` for `failed`

package/grpc/protos/lightning.proto

@@ -1543,6 +1543,13 @@ message Channel {
 
     // This is the peer SCID alias.
     uint64 peer_scid_alias = 35 [jstype = JS_STRING];
+
+    /*
+    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 = 36;
 }
 
 message ListChannelsRequest {
@@ -2272,6 +2279,13 @@ message OpenChannelRequest {
     be zero and is ignored.
     */
     bool fund_max = 26;
+
+    /*
+    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 = 27;
 }
 message OpenStatusUpdate {
     oneof update {

package/lnd_messages/open_channel_request.js

@@ -9,6 +9,7 @@ const minConfs = (isZero, confs) => isZero ? Number() : (confs || undefined);
     fee_rate: <Set Channel Routing Fee Rate Millitoken Per Millitokens String>
     fund_max: <Use Maximal Funding Bool>
     local_funding_amount: <Channel Capacity Tokens String>
+    memo: <Channel Description String>
     min_htlc_msat: <Minimum HTLC Millitokens String>
     node_pubkey: <Node Public Key Buffer Object>
     node_pubkey_string: <Node Public Key Hex String>
@@ -28,6 +29,7 @@ const minConfs = (isZero, confs) => isZero ? Number() : (confs || undefined);
     [base_fee_mtokens]: <Routing Base Fee Millitokens Charged String>
     [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
     [cooperative_close_address]: <Restrict Cooperative Close To Address String>
+    [description]: <Channel Description String>
     [fee_rate]: <Routing Fee Rate In Millitokens Per Million Number>
     [give_tokens]: <Tokens to Gift To Partner Number>
     [is_max_funding]: <Use Maximal Chain Funds For Local Funding Bool>
@@ -50,6 +52,7 @@ module.exports = args => {
     base_fee_mtokens: !!args.use_fee_rate ? args.base_fee : undefined,
     chain_fee_tokens_per_vbyte: chainFeeRate || undefined,
     cooperative_close_address: args.close_address || undefined,
+    description: args.memo || undefined,
     fee_rate: !!args.use_fee_rate ? Number(args.fee_rate) : undefined,
     give_tokens: Number(args.push_sat) || undefined,
     is_max_funding: !!args.fund_max || undefined,

package/lnd_methods/macaroon/subscribe_to_rpc_requests.js

@@ -24,6 +24,8 @@ const type = 'default';
 
   This method is not supported in LND 0.13.4 and below
 
+  `description` is not supported on LND 0.16.3 and below
+
   {
     [id]: <RPC Middleware Interception Name String>
     [is_intercepting_close_channel_requests]: <Intercept Channel Closes Bool>
@@ -67,6 +69,7 @@ const type = 'default';
       [base_fee_mtokens]: <Routing Base Fee Millitokens Charged String>
       [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
       [cooperative_close_address]: <Prefer Cooperative Close To Address String>
+      [description]: <Immutable Channel Description String>
       [fee_rate]: <Routing Fee Rate In Millitokens Per Million Number>
       [give_tokens]: <Tokens to Gift To Partner Number>
       [is_max_funding]: <Use Maximal Chain Funds For Local Funding Bool>

package/lnd_methods/offchain/get_channels.js

@@ -17,6 +17,8 @@ const type = 'default';
 
   `is_trusted_funding` is not supported on LND 0.15.0 and below
 
+  `description` is not supported on LND 0.16.3 and below
+
   {
     [is_active]: <Limit Results To Only Active Channels Bool> // false
     [is_offline]: <Limit Results To Only Offline Channels Bool> // false
@@ -34,6 +36,7 @@ const type = 'default';
       commit_transaction_weight: <Commit Transaction Weight Number>
       [cooperative_close_address]: <Coop Close Restricted to Address String>
       [cooperative_close_delay_height]: <Deny Coop Close Until Height Number>
+      [description]: <Channel Description String>
       id: <Standard Format Channel Id String>
       is_active: <Channel Active Bool>
       is_closing: <Channel Is Closing Bool>

package/lnd_methods/offchain/subscribe_to_channels.js

@@ -31,6 +31,8 @@ const updateOpening = 'pending_open_channel';
 
   `is_trusted_funding`, `other_ids` are not supported on LND 0.15.0 and below
 
+  `description` is not supported on LND 0.16.3 and below
+
   @throws
   <Error>
 
@@ -84,6 +86,7 @@ const updateOpening = 'pending_open_channel';
     commit_transaction_weight: <Commit Transaction Weight Number>
     [cooperative_close_address]: <Coop Close Restricted to Address String>
     [cooperative_close_delay_height]: <Prevent Coop Close Until Height Number>
+    [description]: <Channel Description String>
     id: <Standard Format Channel Id String>
     is_active: <Channel Active Bool>
     is_closing: <Channel Is Closing Bool>

package/lnd_methods/onchain/open_channel.d.ts

@@ -10,6 +10,8 @@ export type ChannelOpenOptions = {
   chain_fee_tokens_per_vbyte?: number;
   /** Restrict Cooperative Close To Address */
   cooperative_close_address?: string;
+  /** Immutable Channel Description */
+  description?: string;
   /** Routing Fee Rate In Millitokens Per Million Number */
   fee_rate?: number;
   /** Tokens to Gift To Partner */

package/lnd_methods/onchain/open_channel.js

@@ -6,6 +6,7 @@ const {isLnd} = require('./../../lnd_requests');
 
 const defaultMinConfs = 1;
 const defaultMinHtlcMtokens = '1';
+const errMemoLength = /^provided memo \(.*\) is of length \d*, exceeds (\d*)$/;
 const minChannelTokens = 20000;
 const method = 'openChannel';
 const type = 'default';
@@ -23,12 +24,15 @@ const type = 'default';
   `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.0 and below
+  `is_max_funding` is not supported on LND 0.16.3 and below
+
+  `description` is not supported on LND 0.16.3 and below
 
   {
     [base_fee_mtokens]: <Routing Base Fee Millitokens Charged String>
     [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
     [cooperative_close_address]: <Restrict Cooperative Close To Address String>
+    [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
     [is_max_funding]: <Use Maximal Chain Funds For Local Funding Bool>
@@ -104,6 +108,7 @@ module.exports = (args, cbk) => {
           fee_rate: args.fee_rate,
           fund_max: args.is_max_funding || undefined,
           local_funding_amount: args.local_tokens,
+          memo: args.description || undefined,
           min_confs: minConfs,
           min_htlc_msat: args.min_htlc_mtokens || defaultMinHtlcMtokens,
           node_pubkey: Buffer.from(args.partner_public_key, 'hex'),
@@ -197,6 +202,14 @@ module.exports = (args, cbk) => {
             return cbk([503, 'ChainUnsupported']);
           }
 
+          if (errMemoLength.test(n.details)) {
+            const [, maxLength] = n.details.match(errMemoLength);
+
+            const max = Number(maxLength);
+
+            return cbk([400, 'MaxChannelDescriptionLengthExceeded', {max}]);
+          }
+
           switch (n.details.toLowerCase()) {
           case 'cannot open channel to self':
             return cbk([400, 'CannotOpenChannelToOwnNode']);

package/lnd_methods/onchain/open_channels.d.ts

@@ -8,6 +8,7 @@ export type MultipleChannelOpenOptions = Pick<
   ChannelOpenOptions,
   | 'base_fee_mtokens'
   | 'cooperative_close_address'
+  | 'description'
   | 'fee_rate'
   | 'give_tokens'
   | 'is_private'

package/lnd_methods/onchain/open_channels.js

@@ -40,11 +40,14 @@ const type = 'default';
   `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
 
+  `description` is not supported on LND 0.16.3 and below
+
   {
     channels: [{
       [base_fee_mtokens]: <Routing Base Fee Millitokens Charged String>
       capacity: <Channel Capacity Tokens Number>
       [cooperative_close_address]: <Restrict Coop Close To Address String>
+      [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
       [is_private]: <Channel is Private Bool> // Defaults to false
@@ -99,6 +102,7 @@ module.exports = (args, cbk) => {
         return cbk(null, args.channels.map(channel => ({
           base_fee_mtokens: channel.base_fee_mtokens,
           capacity: channel.capacity,
+          description: channel.description,
           fee_rate: channel.fee_rate,
           id: makeId(),
           cooperative_close_address: channel.cooperative_close_address,
@@ -131,6 +135,7 @@ module.exports = (args, cbk) => {
               },
             },
             local_funding_amount: channel.capacity,
+            memo: channel.description || undefined,
             min_htlc_msat: channel.min_htlc_mtokens || defaultMinHtlcMtokens,
             node_pubkey: bufferFromHex(channel.partner_public_key),
             private: !!channel.is_private,

package/lnd_methods/onchain/propose_channel.d.ts

@@ -10,6 +10,8 @@ export type ProposeChannelArgs = AuthenticatedLightningArgs<{
   cooperative_close_address?: string;
   /** Cooperative Close Relative Delay */
   cooperative_close_delay?: number;
+  /** Immutable Channel Description */
+  description?: string;
   /** Tokens to Gift To Partner */
   give_tokens?: number;
   /** Pending Channel Id Hex */

package/lnd_methods/onchain/propose_channel.js

@@ -19,10 +19,13 @@ const type = 'default';
 
   Requires LND compiled with `walletrpc` build tag
 
+  `description` is not supported on LND 0.16.3 and below
+
   {
     capacity: <Channel Capacity Tokens Number>
     [cooperative_close_address]: <Restrict Cooperative Close To Address String>
     [cooperative_close_delay]: <Cooperative Close Relative Delay Number>
+    [description]: <Immutable Channel Description String>
     [give_tokens]: <Tokens to Gift To Partner Number> // Defaults to zero
     id: <Pending Channel Id Hex String>
     [is_private]: <Channel is Private Bool> // Defaults to false
@@ -109,6 +112,7 @@ module.exports = (args, cbk) => {
             },
           },
           local_funding_amount: args.capacity.toString(),
+          memo: args.description || undefined,
           node_pubkey: hexAsBuffer(args.partner_public_key),
           private: !!args.is_private,
           push_sat: (args.give_tokens || Number()).toString(),

package/lnd_methods/onchain/request_chain_fee_increase.js

@@ -6,6 +6,7 @@ const {isLnd} = require('./../../lnd_requests');
 const defaultConfirmations = 6;
 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 type = 'wallet';
 
@@ -76,6 +77,10 @@ module.exports = (args, cbk) => {
           target_conf: feeRate.target_conf,
         },
         (err, res) => {
+          if (!!err && err.details === messageExternalUtxo) {
+            return cbk([404, 'SpecifiedOutpointNotFoundInWalletUtxos']);
+          }
+
           if (!!err) {
             return cbk([500, 'UnexpectedErrorRequestingChainFeeBump', {err}]);
           }

package/lnd_responses/rpc_channel_as_channel.js

@@ -35,6 +35,7 @@ const outpointDelimiter = ':';
       min_htlc_msat: <Minimum Millitokens HTLC String>
     }
     num_updates: <Updated Channel Count String>
+    memo: <Channel Description String>
     pending_htlcs: [{
       amount: <HTLC Tokens Amount String>
       expiration_height: <CLTV Timeout Block Height Number>
@@ -74,6 +75,7 @@ const outpointDelimiter = ':';
     commit_transaction_weight: <Commit Transaction Weight Number>
     [cooperative_close_address]: <Coop Close Restricted to Address String>
     [cooperative_close_delay_height]: <Prevent Coop Close Until Height Number>
+    [description]: <Channel Description String>
     id: <Standard Format Channel Id String>
     is_active: <Channel Active Bool>
     is_closing: <Channel Is Closing Bool>
@@ -237,6 +239,7 @@ module.exports = args => {
     commit_transaction_weight: commitWeight,
     cooperative_close_address: args.close_address || undefined,
     cooperative_close_delay_height: height,
+    description: args.memo || undefined,
     id: chanFormat({number: channelId}).channel,
     is_active: args.active,
     is_closing: false,

package/package.json

@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "@grpc/grpc-js": "1.8.14",
-    "@grpc/proto-loader": "0.7.6",
+    "@grpc/proto-loader": "0.7.7",
     "@types/express": "4.17.17",
-    "@types/node": "18.16.3",
+    "@types/node": "20.2.3",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.4",
     "async": "3.2.4",
@@ -20,13 +20,13 @@
     "body-parser": "1.20.2",
     "bolt07": "1.8.3",
     "bolt09": "0.2.5",
-    "cbor": "8.1.0",
+    "cbor": "9.0.0",
     "ecpair": "2.1.0",
     "express": "4.18.2",
     "invoices": "2.2.3",
     "psbt": "2.7.2",
     "tiny-secp256k1": "2.2.1",
-    "type-fest": "3.9.0"
+    "type-fest": "3.11.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "9.3.0"
+  "version": "9.4.0"
 }

package/test/lnd_messages/test_open_channel_request.js

@@ -28,6 +28,7 @@ const makeExpected = overrides => {
     base_fee_mtokens: undefined,
     chain_fee_tokens_per_vbyte: 1,
     cooperative_close_address: 'close_address',
+    description: undefined,
     fee_rate: undefined,
     give_tokens: 1,
     is_max_funding: undefined,

package/test/lnd_methods/macaroon/test_handle_rpc_request_update.js

@@ -103,6 +103,7 @@ const tests = [
           base_fee_mtokens: undefined,
           chain_fee_tokens_per_vbyte: 1,
           cooperative_close_address: 'close_address',
+          description: undefined,
           fee_rate: undefined,
           give_tokens: 1,
           is_max_funding: undefined,

package/test/lnd_methods/macaroon/test_subscribe_to_rpc_requests.js

@@ -194,6 +194,7 @@ const tests = [
           base_fee_mtokens: undefined,
           chain_fee_tokens_per_vbyte: 1,
           cooperative_close_address: 'close_address',
+          description: undefined,
           fee_rate: undefined,
           give_tokens: 1,
           is_max_funding: undefined,

package/test/lnd_methods/offchain/test_get_channels.js

@@ -9,6 +9,7 @@ const makeExpected = overrides => {
     commit_transaction_weight: 1,
     cooperative_close_address: 'cooperative_close_address',
     cooperative_close_delay_height: undefined,
+    description: undefined,
     id: '0x0x1',
     is_active: true,
     is_closing: false,

package/test/lnd_methods/offchain/test_subscribe_to_channels.js

@@ -245,6 +245,7 @@ const tests = [
             commit_transaction_weight: 1,
             cooperative_close_address: undefined,
             cooperative_close_delay_height: undefined,
+            description: undefined,
             id: '0x0x1',
             is_active: false,
             is_closing: false,

package/test/lnd_methods/onchain/test_request_chain_fee_increase.js

@@ -43,6 +43,19 @@ const tests = [
     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, 'SpecifiedOutpointNotFoundInWalletUtxos'],
+  },
   {
     args: makeArgs({lnd: {wallet: {bumpFee: ({}, cbk) => cbk('err')}}}),
     description: 'Errors are passed back',

package/test/lnd_responses/test_rpc_channel_as_channel.js

@@ -68,6 +68,7 @@ const makeExpected = overrides => {
     commit_transaction_weight: 1,
     cooperative_close_address: undefined,
     cooperative_close_delay_height: undefined,
+    description: undefined,
     id: '0x0x1',
     is_active: true,
     is_closing: false,