lightning 4.9.0 → 4.10.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Versions
 
+## 4.10.0
+
+- `getChannels`: Add `past_states` to reflect the number of updates
+- `subscribeToChannels`: Add `past_states` to reflect to number of updates
+
 ## 4.9.0
 
 - `grantAccess`: Add support for specifying `methods` for permissions

package/grpc/handle_remove_listener.js

@@ -0,0 +1,25 @@
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+
+/** Get a function that emits an error from a gRPC subscription proxy
+
+  {
+    emitter: <EventEmitter Subscription Proxy Object>
+    events: [<Event Name String>]
+    subscription: <gRPC Subscription Object>
+  }
+*/
+module.exports = ({emitter, events, subscription}) => {
+  // Cancel the subscription when all listeners are removed
+  emitter.on('removeListener', () => {
+    const counts = events.map(n => emitter.listenerCount(n));
+
+    // Exit early when there are still active listeners
+    if (!!sumOf(counts)) {
+      return;
+    }
+
+    subscription.cancel();
+
+    return;
+  });
+};

package/grpc/index.js

@@ -1,6 +1,7 @@
 const {defaultSocket} = require('./grpc_services');
 const emitSubscriptionError = require('./emit_subscription_error');
 const {grpcSslCipherSuites} = require('./grpc_services');
+const handleRemoveListener = require('./handle_remove_listener');
 const {maxReceiveMessageLength} = require('./grpc_services');
 const {packageTypes} = require('./grpc_services');
 const {protoFiles} = require('./grpc_services');
@@ -13,6 +14,7 @@ module.exports = {
   defaultSocket,
   emitSubscriptionError,
   grpcSslCipherSuites,
+  handleRemoveListener,
   maxReceiveMessageLength,
   packageTypes,
   protoFiles,

package/lnd_methods/index.js

@@ -111,6 +111,7 @@ const {subscribeToPayViaRequest} = require('./offchain');
 const {subscribeToPayViaRoutes} = require('./offchain');
 const {subscribeToPeers} = require('./peers');
 const {subscribeToProbeForRoute} = require('./offchain');
+const {subscribeToRpcRequests} = require('./macaroon');
 const {subscribeToTransactions} = require('./onchain');
 const {subscribeToWalletStatus} = require('./unauthenticated');
 const {unlockUtxo} = require('./onchain');
@@ -239,6 +240,7 @@ module.exports = {
   subscribeToPayViaRoutes,
   subscribeToPeers,
   subscribeToProbeForRoute,
+  subscribeToRpcRequests,
   subscribeToTransactions,
   subscribeToWalletStatus,
   unlockUtxo,

package/lnd_methods/macaroon/grant_access.js

@@ -14,6 +14,7 @@ const method = 'bakeMacaroon';
 const notSupported = 'unknown service lnrpc.Lightning';
 const permissionSeparator = ':';
 const type = 'default';
+const uniq = arr => Array.from(new Set(arr));
 const uriAsPermission = uri => `uri:${uri}`;
 
 /** Give access to the node by making a macaroon access credential
@@ -80,11 +81,13 @@ module.exports = (args, cbk) => {
       // Derive URI permissions
       uris: ['validate', ({}, cbk) => {
         try {
-          const permissions = (args.methods || []).map(method => {
-            return urisForMethod({method}).uris.map(uriAsPermission);
+          const uris = (args.methods || []).map(method => {
+            return urisForMethod({method}).uris;
           });
 
-          return cbk(null, flatten(permissions));
+          const permissions = uniq(flatten(uris)).map(uriAsPermission);
+
+          return cbk(null, permissions);
         } catch (err) {
           return cbk([400, err.message]);
         }

package/lnd_methods/macaroon/index.js

@@ -1,6 +1,13 @@
 const getAccessIds = require('./get_access_ids');
 const grantAccess = require('./grant_access');
 const revokeAccess = require('./revoke_access');
+const subscribeToRpcRequests = require('./subscribe_to_rpc_requests');
 const verifyAccess = require('./verify_access');
 
-module.exports = {getAccessIds, grantAccess, revokeAccess, verifyAccess};
+module.exports = {
+  getAccessIds,
+  grantAccess,
+  revokeAccess,
+  subscribeToRpcRequests,
+  verifyAccess,
+};

package/lnd_methods/macaroon/methods.json

@@ -449,6 +449,10 @@
       "subscribeToPayViaRoutes"
     ]
   },
+  "subscribeToRpcRequests": {
+    "method": "RegisterRPCMiddleware",
+    "type": "default"
+  },
   "subscribeToTransactions": {
     "method": "SubscribeTransactions",
     "type": "default"

package/lnd_methods/macaroon/subscribe_to_rpc_requests.js

@@ -0,0 +1,113 @@
+const EventEmitter = require('events');
+const {randomBytes} = require('crypto');
+
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {emitSubscriptionError} = require('./../../grpc');
+const {handleRemoveListener} = require('./../../grpc');
+const {isLnd} = require('./../../lnd_requests');
+const {rpcRequestUpdateAsEvent} = require('./../../lnd_responses');
+
+const cancelError = 'Cancelled on client';
+const events = ['request', 'response'];
+const makeId = () => randomBytes(32).toString('hex');
+const method = 'RegisterRPCMiddleware';
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const type = 'default';
+
+/** Subscribe to RPC requests and their responses
+
+  Requires `macaroon:write` permission
+
+  LND must be running with rpc middleware enabled: `rpcmiddleware.enable=1`
+
+  This method is not supported in LND 0.13.2 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    subscription: <RPC Request Subscription EventEmitter Object>
+  }
+
+  @event 'request'
+  {
+    id: <Request Id Number>
+    [macaroon]: <Base64 Encoded Macaroon String>
+    [uri]: <RPC URI String>
+  }
+
+  @event 'response'
+  {
+    id: <Request Id Number>
+    [macaroon]: <Base64 Encoded Macaroon String>
+    [uri]: <RPC URI String>
+  }
+*/
+module.exports = ({lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndToSubscribeToRpcRequests']);
+        }
+
+        return cbk();
+      },
+
+      // Intercept RPC requests
+      intercept: ['validate', ({}, cbk) => {
+        const emitter = new EventEmitter();
+
+        try {
+          const subscription = lnd[type][method]({});
+
+          subscription.write({
+            register: {middleware_name: makeId(), read_only_mode: true},
+          },
+          err => {
+            if (!!err) {
+              return cbk([503, 'UnexpectedErrInterceptingRpcRequests', {err}]);
+            }
+
+            return cbk(null, {subscription: emitter});
+          });
+
+          handleRemoveListener({subscription, emitter, events});
+
+          const errored = emitSubscriptionError({emitter, subscription});
+
+          subscription.on('data', update => {
+            try {
+              const details = rpcRequestUpdateAsEvent(update);
+
+              emitter.emit(details.event, {
+                id: details.id,
+                macaroon: details.macaroon,
+                uri: details.uri,
+              });
+
+              return subscription.write({
+                feedback: {replace_response: false},
+                request_id: details.id,
+              });
+            } catch (err) {
+              return errored([503, err.message]);
+            }
+          });
+
+          subscription.on('end', () => emitter.emit('end'));
+          subscription.on('error', err => errored(err));
+          subscription.on('status', n => emitter.emit('status', n));
+        } catch (err) {
+          return cbk([503, 'UnexpectedErrorSubscribingToRpcRequests', {err}]);
+        }
+      }],
+    },
+    returnResult({reject, resolve, of: 'intercept'}, cbk));
+  });
+};

package/lnd_methods/offchain/get_channels.d.ts

@@ -60,6 +60,8 @@ export type GetChannelsResult = {
     local_reserve: number;
     /** Channel Partner Public Key */
     partner_public_key: string;
+    /** Past Channel States Count */
+    past_states: number;
     pending_payments: {
       /** Payment Preimage Hash Hex */
       id: string;

package/lnd_methods/offchain/get_channels.js

@@ -50,6 +50,7 @@ const type = 'default';
       [local_min_htlc_mtokens]: <Local Minimum HTLC Millitokens String>
       local_reserve: <Local Reserved Tokens Number>
       partner_public_key: <Channel Partner Public Key String>
+      past_states: <Total Count of Past Channel States Number>
       pending_payments: [{
         id: <Payment Preimage Hash Hex String>
         [in_channel]: <Forward Inbound From Channel Id String>

package/lnd_methods/offchain/subscribe_to_channels.d.ts

@@ -99,6 +99,8 @@ export type SubscribeToChannelsChannelOpenedEvent = {
   local_reserve: number;
   /** Channel Partner Public Key */
   partner_public_key: string;
+  /** Total Count of Past Channel States */
+  past_states: number;
   pending_payments: {
     /** Payment Preimage Hash Hex */
     id: string;

package/lnd_methods/offchain/subscribe_to_channels.js

@@ -94,6 +94,7 @@ const updateOpening = 'pending_open_channel';
     local_given: <Local Initially Pushed Tokens Number>
     local_reserve: <Local Reserved Tokens Number>
     partner_public_key: <Channel Partner Public Key String>
+    past_states: <Total Count of Past Channel States Number>
     pending_payments: [{
       id: <Payment Preimage Hash Hex String>
       is_outgoing: <Payment Is Outgoing Bool>

package/lnd_methods/onchain/open_channel.js

@@ -1,7 +1,7 @@
-const {addPeer} = require('./../peers');
 const asyncAuto = require('async/auto');
 const {returnResult} = require('asyncjs-util');
 
+const {addPeer} = require('./../peers');
 const {isLnd} = require('./../../lnd_requests');
 
 const defaultMinConfs = 1;

package/lnd_responses/index.js

@@ -31,6 +31,7 @@ const rpcNodeAsNode = require('./rpc_node_as_node');
 const rpcOutpointAsUpdate = require('./rpc_outpoint_as_update');
 const rpcPaymentAsPayment = require('./rpc_payment_as_payment');
 const rpcPeerAsPeer = require('./rpc_peer_as_peer');
+const rpcRequestUpdateAsEvent = require('./rpc_request_update_as_event');
 const rpcResolutionAsResolution = require('./rpc_resolution_as_resolution');
 const rpcRouteAsRoute = require('./rpc_route_as_route');
 const rpcTxAsTransaction = require('./rpc_tx_as_transaction');
@@ -71,6 +72,7 @@ module.exports = {
   rpcOutpointAsUpdate,
   rpcPaymentAsPayment,
   rpcPeerAsPeer,
+  rpcRequestUpdateAsEvent,
   rpcResolutionAsResolution,
   rpcRouteAsRoute,
   rpcTxAsTransaction,

package/lnd_responses/rpc_channel_as_channel.js

@@ -90,6 +90,7 @@ const outpointDelimiter = ':';
     local_min_htlc_mtokens: <Local Minimum HTLC Millitokens String>
     local_reserve: <Local Reserved Tokens Number>
     partner_public_key: <Channel Partner Public Key String>
+    past_states: <Total Count of Past States Number>
     pending_payments: [{
       id: <Payment Preimage Hash Hex String>
       [in_channel]: <Forwarding from Channel Id String>
@@ -144,10 +145,6 @@ module.exports = args => {
     throw new Error('ExpectedCommitWeightInChannelMessage');
   }
 
-  if (!args.commitment_type) {
-    throw new Error('ExpectedCommitmentTypeInChannelMessage');
-  }
-
   if (args.fee_per_kw === undefined) {
     throw new Error('ExpectedFeePerKwInChannelMessage');
   }
@@ -243,6 +240,7 @@ module.exports = args => {
     local_min_htlc_mtokens: own.min_htlc_msat,
     local_reserve: Number(own.chan_reserve_sat),
     partner_public_key: args.remote_pubkey,
+    past_states: Number(args.num_updates),
     pending_payments: args.pending_htlcs.map(rpcHtlcAsPayment),
     received: Number(args.total_satoshis_received),
     remote_balance: Number(args.remote_balance),

package/lnd_responses/rpc_request_update_as_event.js

@@ -0,0 +1,121 @@
+const bufferAsBase64 = n => !!n.length ? n.toString('base64') : undefined;
+const {isBuffer} = Buffer;
+const request = 'request';
+const response = 'response';
+const streamAuth = 'stream_auth';
+
+/** Derive request details from an RPC request update
+
+  {
+    request_id: <Request Id Number String>
+    raw_macaroon: <Raw Macaroon Buffer Object>
+    custom_caveat_condition: <Custom Caveat Condition String>
+    [request]: {
+      method_full_uri: <Method URI String>
+      stream_rpc: <Is String RPC Bool>
+      type_name: <RPC Message Type String>
+      serialized: <Raw Protobuf Request Buffer Object>
+    }
+    [response]: {
+      method_full_uri: <Method URI String>
+      stream_rpc: <Is String RPC Bool>
+      type_name: <RPC Message Type String>
+      serialized: <Raw Protobuf Response Buffer Object>
+    }
+    [stream_auth]: {
+      method_full_uri: <Method URI String>
+    }
+    intercept_type: <RPC Update Type String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [event]: <Event Type String>
+    id: <Request Id Number>
+    [macaroon]: <Base64 Encoded Macaroon String>
+    [uri]: <RPC URI String>
+  }
+*/
+module.exports = args => {
+  if (!args) {
+    throw new Error('ExpectedRpcRequestUpdateDetailsToDeriveUpdateEvent');
+  }
+
+  if (args.custom_caveat_condition === undefined) {
+    throw new Error('ExpectedCustomCaveatConditionInRpcRequestUpdate');
+  }
+
+  if (args.intercept_type === undefined) {
+    throw new Error('ExpectedInterceptTypeInRpcRequestUpdate');
+  }
+
+  if (!isBuffer(args.raw_macaroon)) {
+    throw new Error('ExpectedCompleteMacaroonCredentialsInRequestUpdate');
+  }
+
+  if (args.request_id === undefined) {
+    throw new Error('ExpectedRequestIdInRpcRequestUpdate');
+  }
+
+  const id = Number(args.request_id);
+
+  switch (args.intercept_type) {
+  // New subscription
+  case streamAuth:
+    if (!args[streamAuth]) {
+      throw new Error('ExpectedStreamAuthDetailsInRpcRequestUpdate');
+    }
+
+    if (!args[streamAuth].method_full_uri) {
+      throw new Error('ExpectedFullUriForStreamAuthRpcRequestUpdate');
+    }
+
+    return {
+      id,
+      event: request,
+      macaroon: bufferAsBase64(args.raw_macaroon),
+      uri: args[streamAuth].method_full_uri,
+    };
+
+  // New request
+  case request:
+    if (!args[request]) {
+      throw new Error('ExpectedRequestDetailsInRpcRequestUpdate');
+    }
+
+    if (!args[request].method_full_uri) {
+      throw new Error('ExpectedFullUriForRequestRpcRequestUpdate');
+    }
+
+    return {
+      id,
+      event: request,
+      macaroon: bufferAsBase64(args.raw_macaroon),
+      uri: args[request].method_full_uri,
+    };
+
+  // Response to past request
+  case response:
+    if (!args[response]) {
+      throw new Error('ExpectedResponseDetailsInRpcRequestUpdate');
+    }
+
+    if (!args[response].method_full_uri) {
+      throw new Error('ExpectedFullUriForResponseRpcRequestUpdate');
+    }
+
+    return {
+      id,
+      event: response,
+      macaroon: bufferAsBase64(args.raw_macaroon),
+      uri: args[response].method_full_uri,
+    };
+
+  // Unknown update
+  default:
+    return {id, macaroon: bufferAsBase64(args.raw_macaroon)};
+  }
+};

package/package.json

@@ -31,7 +31,7 @@
     "@alexbosworth/tap": "15.0.10",
     "tsd": "0.17.0",
     "typescript": "4.4.3",
-    "ws": "8.2.2"
+    "ws": "8.2.3"
   },
   "engines": {
     "node": ">=12"
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.9.0"
+  "version": "4.10.0"
 }

package/test/grpc/test_handle_remove_listener.js

@@ -0,0 +1,34 @@
+const {test} = require('@alexbosworth/tap');
+
+const {handleRemoveListener} = require('./../../grpc');
+
+const tests = [
+  {
+    args: {
+      emitter: {listenerCount: () => 0, on: (eventName, cbk) => cbk()},
+      events: ['event'],
+      subscription: {cancel: () => {}},
+    },
+    description: 'An error is emitted',
+  },
+  {
+    args: {
+      emitter: {listenerCount: () => 1, on: (eventName, cbk) => cbk()},
+      events: ['event'],
+      subscription: {
+        cancel: () => {
+          throw new Error('SubscriptionShouldNotBeCanceled');
+        },
+      },
+    },
+    description: 'An error is emitted',
+  },
+];
+
+tests.forEach(({args, description, expected}) => {
+  return test(description, ({end, equal}) => {
+    handleRemoveListener(args);
+
+    return end();
+  });
+});

package/test/lnd_methods/offchain/test_get_channels.js

@@ -27,6 +27,7 @@ const makeExpected = overrides => {
     local_max_pending_mtokens: '1',
     local_reserve: 1,
     partner_public_key: 'b',
+    past_states: 1,
     pending_payments: [{
       id: '0000000000000000000000000000000000000000000000000000000000000000',
       in_channel: undefined,

package/test/lnd_methods/offchain/test_subscribe_to_channels.js

@@ -260,6 +260,7 @@ const tests = [
             local_min_htlc_mtokens: '1',
             local_reserve: 1,
             partner_public_key: '000000000000000000000000000000000000000000000000000000000000000000',
+            past_states: 1,
             pending_payments: [],
             received: 1,
             remote_balance: 1,

package/test/lnd_responses/test_rpc_channel_as_channel.js

@@ -85,6 +85,7 @@ const makeExpected = overrides => {
     local_min_htlc_mtokens: '1',
     local_reserve: 1,
     partner_public_key: '00',
+    past_states: 1,
     pending_payments: [{
       id: '0000000000000000000000000000000000000000000000000000000000000000',
       in_channel: undefined,
@@ -150,11 +151,6 @@ const tests = [
     description: 'Channel commit weight is expected',
     error: 'ExpectedCommitWeightInChannelMessage',
   },
-  {
-    args: makeArgs({commitment_type: undefined}),
-    description: 'Channel commit type is expected',
-    error: 'ExpectedCommitmentTypeInChannelMessage',
-  },
   {
     args: makeArgs({fee_per_kw: undefined}),
     description: 'Channel fee per kw is expected',

package/test/lnd_responses/test_rpc_request_update_as_event.js

@@ -0,0 +1,130 @@
+const {test} = require('@alexbosworth/tap');
+
+const method = require('./../../lnd_responses/rpc_request_update_as_event');
+
+const makeArgs = overrides => {
+  const args = {
+    request_id: '1',
+    raw_macaroon: Buffer.alloc(0),
+    custom_caveat_condition: '',
+    intercept_type: 'unknown type',
+  };
+
+  Object.keys(overrides).forEach(k => args[k] = overrides[k]);
+
+  return args;
+};
+
+const makeExpected = overrides => {
+  const expected = {id: 1, macaroon: undefined};
+
+  Object.keys(overrides).forEach(k => expected[k] = overrides[k]);
+
+  return expected;
+};
+
+const tests = [
+  {
+    args: undefined,
+    description: 'Request details expected',
+    error: 'ExpectedRpcRequestUpdateDetailsToDeriveUpdateEvent',
+  },
+  {
+    args: makeArgs({custom_caveat_condition: undefined}),
+    description: 'A custom caveat is expected',
+    error: 'ExpectedCustomCaveatConditionInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: undefined}),
+    description: 'An intercept type is expected',
+    error: 'ExpectedInterceptTypeInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({raw_macaroon: undefined}),
+    description: 'A raw macaroon is expected',
+    error: 'ExpectedCompleteMacaroonCredentialsInRequestUpdate',
+  },
+  {
+    args: makeArgs({request_id: undefined}),
+    description: 'A request id is expected',
+    error: 'ExpectedRequestIdInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'stream_auth'}),
+    description: 'Stream auth details are expected',
+    error: 'ExpectedStreamAuthDetailsInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'stream_auth', stream_auth: {}}),
+    description: 'Stream auth URI is expected',
+    error: 'ExpectedFullUriForStreamAuthRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'request'}),
+    description: 'Request details are expected',
+    error: 'ExpectedRequestDetailsInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'request', request: {}}),
+    description: 'Request URI is expected',
+    error: 'ExpectedFullUriForRequestRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'response'}),
+    description: 'Response details are expected',
+    error: 'ExpectedResponseDetailsInRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({intercept_type: 'response', response: {}}),
+    description: 'Response URI is expected',
+    error: 'ExpectedFullUriForResponseRpcRequestUpdate',
+  },
+  {
+    args: makeArgs({}),
+    description: 'Request mapped to event details',
+    expected: makeExpected({}),
+  },
+  {
+    args: makeArgs({raw_macaroon: Buffer.alloc(1)}),
+    description: 'Raw macaroon is returned',
+    expected: makeExpected({macaroon: 'AA=='}),
+  },
+  {
+    args: makeArgs({
+      intercept_type: 'stream_auth',
+      stream_auth: {method_full_uri: 'uri'},
+    }),
+    description: 'Stream request mapped to event details',
+    expected: makeExpected({event: 'request', uri: 'uri'}),
+  },
+  {
+    args: makeArgs({
+      intercept_type: 'request',
+      request: {method_full_uri: 'uri'},
+    }),
+    description: 'Request mapped to event details',
+    expected: makeExpected({event: 'request', uri: 'uri'}),
+  },
+  {
+    args: makeArgs({
+      intercept_type: 'response',
+      response: {method_full_uri: 'uri'},
+    }),
+    description: 'Response mapped to event details',
+    expected: makeExpected({event: 'response', uri: 'uri'}),
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    if (!!error) {
+      throws(() => method(args), new Error(error), 'Error');
+    } else {
+      const res = method(args);
+
+      strictSame(res, expected, 'RPC request update as event');
+    }
+
+    return end();
+  });
+});