lightning 4.10.1 → 4.10.5

package/lnd_methods/macaroon/subscribe_to_rpc_requests.js

@@ -6,25 +6,29 @@ const {returnResult} = require('asyncjs-util');
 
 const {emitSubscriptionError} = require('./../../grpc');
 const {handleRemoveListener} = require('./../../grpc');
+const handleRpcRequestUpdate = require('./handle_rpc_request_update');
 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 minIdLength = 5;
 const type = 'default';
 
 /** Subscribe to RPC requests and their responses
 
+  `accept` and `reject` methods can be used with cbk or Promise syntax
+
   Requires `macaroon:write` permission
 
-  LND must be running with rpc middleware enabled: `rpcmiddleware.enable=1`
+  LND must be running with "RPC middleware" enabled: `rpcmiddleware.enable=1`
 
   This method is not supported in LND 0.13.3 and below
 
   {
+    [id]: <RPC Middleware Interception Name String>
+    [is_intercepting_close_channel_requests]: <Intercept Channel Closes Bool>
+    [is_intercepting_open_channel_requests]: <Intercept Channel Opens Bool>
+    [is_intercepting_pay_via_routes_requests]: <Intercept Pay Via Route Bool>
     lnd: <Authenticated LND API Object>
   }
 
@@ -33,6 +37,77 @@ const type = 'default';
     subscription: <RPC Request Subscription EventEmitter Object>
   }
 
+  // A channel close request was intercepted: by default it will be rejected
+  @event 'close_channel_request'
+  {
+    accept: ({}, [cbk]) => {}
+    id: <Request Id Number>
+    macaroon: <Base64 Encoded Macaroon String>
+    reject: ({message: <Rejection String>}, [cbk]) => {}
+    request: {
+      [address]: <Request Sending Local Channel Funds To Address String>
+      [is_force_close]: <Is Force Close Bool>
+      [target_confirmations]: <Confirmation Target Number>
+      [tokens_per_vbyte]: <Tokens Per Virtual Byte Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }
+    uri: <RPC URI String>
+  }
+
+  // A channel open request was intercepted: by default it will be rejected
+  @event 'open_channel_request'
+  {
+    accept: ({}, [cbk]) => {}
+    id: <Request Id Number>
+    macaroon: <Base64 Encoded Macaroon String>
+    reject: ({message: <Rejection String>}, [cbk]) => {}
+    request: {
+      [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
+      [cooperative_close_address]: <Prefer Cooperative Close To Address String>
+      [give_tokens]: <Tokens to Gift To Partner Number>
+      [is_private]: <Channel is Private Bool>
+      local_tokens: <Local Tokens Number>
+      [min_confirmations]: <Spend UTXOs With Minimum Confirmations Number>
+      [min_htlc_mtokens]: <Minimum HTLC Millitokens String>
+      partner_public_key: <Public Key Hex String>
+      [partner_csv_delay]: <Peer Output CSV Delay Number>
+    }
+    uri: <RPC URI String>
+  }
+
+  // A pay to route request was intercepted: by default it will be rejected
+  @event 'pay_via_route_request'
+  {
+    accept: ({}, [cbk]) => {}
+    id: <Request Id Number>
+    macaroon: <Base64 Encoded Macaroon String>
+    reject: ({message: <Rejection String>}, [cbk]) => {}
+    request: {
+      id: <Payment Hash Hex String>
+      route: {
+        fee: <Route Fee Tokens Number>
+        fee_mtokens: <Route Fee Millitokens String>
+        hops: [{
+          channel: <Standard Format Channel Id String>
+          channel_capacity: <Channel Capacity Tokens Number>
+          fee: <Fee Tokens Number>
+          fee_mtokens: <Fee Millitokens String>
+          forward: <Forward Tokens Number>
+          forward_mtokens: <Forward Millitokens String>
+          public_key: <Forward Edge Public Key Hex String>
+          [timeout]: <Timeout Block Height Number>
+        }]
+        mtokens: <Total Fee-Inclusive Millitokens String>
+        [payment]: <Payment Identifier Hex String>
+        [timeout]: <Timeout Block Height Number>
+        tokens: <Total Fee-Inclusive Tokens Number>
+        [total_mtokens]: <Total Payment Millitokens String>
+      }
+    }
+    uri: <RPC URI String>
+  }
+
   @event 'request'
   {
     id: <Request Id Number>
@@ -47,65 +122,91 @@ const type = 'default';
     [uri]: <RPC URI String>
   }
 */
-module.exports = ({lnd}, cbk) => {
+module.exports = (args, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!isLnd({lnd, method, type})) {
+        if (!!args.id && args.id.length < minIdLength) {
+          return cbk([400, 'ExpectedLongerIdLengthToSpecifyMiddlewareName']);
+        }
+
+        if (!isLnd({method, type, lnd: args.lnd})) {
           return cbk([400, 'ExpectedLndToSubscribeToRpcRequests']);
         }
 
         return cbk();
       },
 
-      // Intercept RPC requests
-      intercept: ['validate', ({}, cbk) => {
+      // Initialize subscription
+      init: ['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}]);
+        const isInterceptCloses = args.is_intercepting_close_channel_requests;
+        const isInterceptOpens = args.is_intercepting_open_channel_requests;
+        const isInterceptRoute = args.is_intercepting_pay_via_routes_requests;
+        const subscription = args.lnd[type][method]({});
+
+        const events = [
+          'close_channel_request',
+          'open_channel_request',
+          'pay_via_route_request',
+          'request',
+          'response',
+        ];
+
+        const errored = emitSubscriptionError({emitter, subscription});
+
+        // Terminate subscription when all listeners are removed
+        handleRemoveListener({subscription, emitter, events});
+
+        subscription.on('end', () => emitter.emit('end'));
+        subscription.on('error', err => errored(err));
+        subscription.on('status', n => emitter.emit('status', n));
+
+        subscription.on('data', update => {
+          try {
+            const {accept, data, event} = handleRpcRequestUpdate({
+              subscription,
+              update,
+              is_intercepting_close_channel_requests: isInterceptCloses,
+              is_intercepting_open_channel_requests: isInterceptOpens,
+              is_intercepting_pay_via_routes_requests: isInterceptRoute,
+              lnd: args.lnd,
+            });
+
+            // Notify listeners of the RPC update
+            emitter.emit(event, data);
+
+            // Exit early when accepting/rejecting is left to the caller
+            if (!accept) {
+              return;
             }
 
-            return cbk(null, {subscription: emitter});
-          });
-
-          handleRemoveListener({subscription, emitter, events});
-
-          const errored = emitSubscriptionError({emitter, subscription});
+            // Accept traffic by default
+            return accept({}, err => !!err ? errored(err) : undefined);
+          } catch (err) {
+            return errored([503, err.message]);
+          }
+        });
 
-          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]);
-            }
-          });
+        return cbk(null, {emitter, subscription});
+      }],
 
-          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}]);
-        }
+      // Start the interception of RPC requests
+      intercept: ['init', ({init}, cbk) => {
+        return init.subscription.write({
+          register: {
+            middleware_name: args.id || makeId(),
+            read_only_mode: true,
+          },
+        },
+        err => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrInterceptingRpcRequests', {err}]);
+          }
+
+          return cbk(null, {subscription: init.emitter});
+        });
       }],
     },
     returnResult({reject, resolve, of: 'intercept'}, cbk));

package/lnd_methods/macaroon/uris_for_method.js

@@ -1,10 +1,11 @@
 const methods = require('./methods');
 
+const {packageTypes} = require('./../../grpc');
 const {serviceTypes} = require('./../../grpc');
 
 const flatten = arr => arr.flat(Infinity);
 const type = n => [methods[n]].concat((methods[n].depends_on || []).map(type));
-const uriForMethod = (service, method) => `/lnrpc.${service}/${method}`;
+const uriForMethod = (rpc, service, method) => `/${rpc}.${service}/${method}`;
 
 /** Given a method, derive URI macaroon permission strings required
 
@@ -31,19 +32,21 @@ module.exports = ({method}) => {
 
   const requiredMethods = flatten(type(method)).filter(({type}) => type);
 
-  const uris = requiredMethods.map(({method, methods, type}) => {
+  const uris = flatten(requiredMethods.map(({method, methods, type}) => {
     const service = serviceTypes[type];
 
     if (!service) {
       throw new Error('ExpectedKnownMethodServiceToDeriveMacaroonUris');
     }
 
+    const rpc = packageTypes[service];
+
     return (methods || [method]).map(methodName => {
-      return uriForMethod(service, methodName);
+      return uriForMethod(rpc, service, methodName);
     });
-  });
+  }));
 
   uris.sort();
 
-  return {uris: flatten(uris)};
+  return {uris};
 };

package/lnd_methods/offchain/get_failed_payments.js

@@ -0,0 +1,190 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+const {rpcPaymentAsPayment} = require('./../../lnd_responses');
+const {sortBy} = require('./../../arrays');
+
+const defaultLimit = 250;
+const {isArray} = Array;
+const isFailed = payment => !!payment && payment.status === 'FAILED';
+const lastPageFirstIndexOffset = 1;
+const method = 'listPayments';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'default';
+
+/** Get failed payments made through channels.
+
+  Requires `offchain:read` permission
+
+  {
+    [limit]: <Page Result Limit Number>
+    lnd: <Authenticated LND API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    payments: [{
+      attempts: [{
+        [failure]: {
+          code: <Error Type Code Number>
+          [details]: {
+            [channel]: <Standard Format Channel Id String>
+            [height]: <Error Associated Block Height Number>
+            [index]: <Failed Hop Index Number>
+            [mtokens]: <Error Millitokens String>
+            [policy]: {
+              base_fee_mtokens: <Base Fee Millitokens String>
+              cltv_delta: <Locktime Delta Number>
+              fee_rate: <Fees Charged in Millitokens Per Million Number>
+              [is_disabled]: <Channel is Disabled Bool>
+              max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
+              min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
+              updated_at: <Updated At ISO 8601 Date String>
+            }
+            [timeout_height]: <Error CLTV Timeout Height Number>
+            [update]: {
+              chain: <Chain Id Hex String>
+              channel_flags: <Channel Flags Number>
+              extra_opaque_data: <Extra Opaque Data Hex String>
+              message_flags: <Message Flags Number>
+              signature: <Channel Update Signature Hex String>
+            }
+          }
+          message: <Error Message String>
+        }
+        [index]: <Payment Add Index Number>
+        [confirmed_at]: <Payment Confirmed At ISO 8601 Date String>
+        is_confirmed: <Payment Attempt Succeeded Bool>
+        is_failed: <Payment Attempt Failed Bool>
+        is_pending: <Payment Attempt is Waiting For Resolution Bool>
+        route: {
+          fee: <Route Fee Tokens Number>
+          fee_mtokens: <Route Fee Millitokens String>
+          hops: [{
+            channel: <Standard Format Channel Id String>
+            channel_capacity: <Channel Capacity Tokens Number>
+            fee: <Fee Number>
+            fee_mtokens: <Fee Millitokens String>
+            forward: <Forward Tokens Number>
+            forward_mtokens: <Forward Millitokens String>
+            [public_key]: <Forward Edge Public Key Hex String>
+            [timeout]: <Timeout Block Height Number>
+          }]
+          mtokens: <Total Fee-Inclusive Millitokens String>
+          [payment]: <Payment Identifier Hex String>
+          timeout: <Timeout Block Height Number>
+          tokens: <Total Fee-Inclusive Tokens Number>
+          [total_mtokens]: <Total Millitokens String>
+        }
+      }]
+      created_at: <Payment at ISO-8601 Date String>
+      [destination]: <Destination Node Public Key Hex String>
+      id: <Payment Preimage Hash String>
+      [index]: <Payment Add Index Number>
+      is_confirmed: <Payment is Confirmed Bool>
+      is_outgoing: <Transaction Is Outgoing Bool>
+      mtokens: <Millitokens Attempted to Pay to Destination String>
+      [request]: <BOLT 11 Payment Request String>
+      safe_tokens: <Payment Tokens Attempted to Pay Rounded Up Number>
+      tokens: <Rounded Down Tokens Attempted to Pay to Destination Number>
+    }]
+    [next]: <Next Opaque Paging Token String>
+  }
+*/
+module.exports = ({limit, lnd, token}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!!limit && !!token) {
+          return cbk([400, 'ExpectedNoLimitWhenPagingPayFailuresWithToken']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndForGetFailedPaymentsRequest']);
+        }
+
+        return cbk();
+      },
+
+      // Get all payments
+      listPayments: ['validate', ({}, cbk) => {
+        let offset;
+        let resultsLimit = limit || defaultLimit;
+
+        if (!!token) {
+          try {
+            const pagingToken = parse(token);
+
+            offset = pagingToken.offset;
+            resultsLimit = pagingToken.limit;
+          } catch (err) {
+            return cbk([400, 'ExpectedValidPagingTokenForGetFailed', {err}]);
+          }
+        }
+
+        return lnd[type][method]({
+          include_incomplete: true,
+          index_offset: offset || Number(),
+          max_payments: resultsLimit,
+          reversed: true,
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedGetFailedPaymentsError', {err}]);
+          }
+
+          if (!res || !isArray(res.payments)) {
+            return cbk([503, 'ExpectedFailedPaymentsInListPaymentsResponse']);
+          }
+
+          if (typeof res.last_index_offset !== 'string') {
+            return cbk([503, 'ExpectedLastIndexOffsetWhenRequestingFailed']);
+          }
+
+          const lastOffset = Number(res.last_index_offset);
+          const offset = Number(res.first_index_offset);
+
+          const token = stringify({offset, limit: resultsLimit});
+
+          return cbk(null, {
+            payments: res.payments.filter(isFailed),
+            token: offset === lastPageFirstIndexOffset ? undefined : token,
+          });
+        });
+      }],
+
+      // Check and map payments
+      foundPayments: ['listPayments', ({listPayments}, cbk) => {
+        try {
+          const payments = listPayments.payments.map(rpcPaymentAsPayment);
+
+          return cbk(null, payments);
+        } catch (err) {
+          return cbk([503, err.message]);
+        }
+      }],
+
+      // Final found failed payments
+      payments: [
+        'foundPayments',
+        'listPayments',
+        ({foundPayments, listPayments}, cbk) =>
+      {
+        const payments = sortBy({
+          array: foundPayments,
+          attribute: 'created_at',
+        });
+
+        return cbk(null, {
+          next: listPayments.token || undefined,
+          payments: payments.sorted.reverse(),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'payments'}, cbk));
+  });
+};

package/lnd_methods/offchain/get_payments.js

@@ -131,8 +131,6 @@ module.exports = ({limit, lnd, token}, cbk) => {
           }
         }
 
-        const start = Date.now();
-
         return lnd[type][method]({
           include_incomplete: false,
           index_offset: offset || Number(),
@@ -187,8 +185,8 @@ module.exports = ({limit, lnd, token}, cbk) => {
         });
 
         return cbk(null, {
-          payments: payments.sorted.reverse(),
           next: !!foundPayments.length ? listPayments.token : undefined,
+          payments: payments.sorted.reverse(),
         });
       }],
     },

package/lnd_methods/offchain/index.js

@@ -14,6 +14,7 @@ const getChannelBalance = require('./get_channel_balance');
 const getChannels = require('./get_channels');
 const getClosedChannels = require('./get_closed_channels');
 const getConnectedWatchtowers = require('./get_connected_watchtowers');
+const getFailedPayments = require('./get_failed_payments');
 const getFeeRates = require('./get_fee_rates');
 const getForwardingConfidence = require('./get_forwarding_confidence');
 const getForwardingReputations = require('./get_forwarding_reputations');
@@ -65,6 +66,7 @@ module.exports = {
   getChannels,
   getClosedChannels,
   getConnectedWatchtowers,
+  getFailedPayments,
   getFeeRates,
   getForwardingConfidence,
   getForwardingReputations,

package/lnd_methods/offchain/probe_for_route.js

@@ -10,6 +10,11 @@ const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 
 /** Probe to find a successful route
 
+  When probing to a payment request, make sure to specify the fields encoded in
+  the payment request such as `cltv_delta`.
+
+  If `total_mtokens` are specified, a `payment` nonce is required.
+
   Requires `offchain:write` permission
 
   {

package/lnd_responses/rpc_invoice_as_invoice.js

@@ -3,6 +3,7 @@ const {featureFlagDetails} = require('bolt09');
 const htlcAsPayment = require('./htlc_as_payment');
 
 const dateFrom = epoch => new Date(1e3 * epoch).toISOString();
+const emptyHash = Buffer.alloc(32).toString('hex');
 const {isArray} = Array;
 const {keys} = Object;
 const msPerSec = 1e3;
@@ -178,12 +179,13 @@ module.exports = args => {
   const createdAtEpochTime = Number(args.creation_date);
   const descHash = args.description_hash;
   const expiresInMs = Number(args.expiry) * msPerSec;
-  const isAmpPush = !args.request && !!args.is_amp;
+  const isAmpPush = !args.payment_request && !!args.is_amp;
   const mtok = (BigInt(args.value) * mtokensPerToken).toString();
   const payment = args.payment_addr.toString('hex');
   const settleDate = args.settle_date;
 
   const createdAtMs = createdAtEpochTime * msPerSec;
+  const hasPaymentId = !!payment && payment !== emptyHash;
 
   return {
     chain_address: args.fallback_addr || undefined,
@@ -208,7 +210,7 @@ module.exports = args => {
     is_private: args.private,
     is_push: isAmpPush || args.is_keysend || undefined,
     mtokens: args.value_msat === '0' ? mtok : args.value_msat,
-    payment: payment || undefined,
+    payment: hasPaymentId ? payment : undefined,
     payments: args.htlcs.map(htlcAsPayment),
     received: Number(args.amt_paid_sat),
     received_mtokens: args.amt_paid_msat,