ln-service 54.0.0 → 54.1.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 54.1.0
+
+- `subscribeToPayments`: Add method to listen to all outgoing payments
+
 ## 54.0.0
 
 ### Breaking Changes

package/README.md

@@ -242,6 +242,7 @@ for `unlocker` methods.
 - [subscribeToPayViaDetails](#subscribetopayviadetails) - Pay using details
 - [subscribeToPayViaRequest](#subscribetopayviarequest) - Pay using a request
 - [subscribeToPayViaRoutes](#subscribetopayviaroutes) - Pay using routes
+- [subscribeToPayments](#subscribetopayments) - Subscribe to outgoing payments
 - [subscribeToPeerMessages](#subscribetopeermessages) - Listen to incoming
     custom messages
 - [subscribeToPeers](#subscribetopeers) - Subscribe to peers connectivity
@@ -6254,6 +6255,111 @@ const sub = subscribeToPayViaRoutes({lnd, routes: [route]});
 const [success] = await once(sub, 'success');
 ```
 
+### subscribeToPayments
+
+Subscribe to outgoing payments
+
+Requires `offchain:read` permission
+
+Note: Method not supported on LND 0.15.2 and below
+
+    {
+      lnd: <Authenticated LND API Object>
+    }
+
+    @throws
+    <Error>
+
+
+    @returns
+    <Subscription EventEmitter Object>
+
+    @event 'confirmed'
+    {
+      confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+      created_at: <Payment Created At ISO 8601 Date String>
+      destination: <Payment Destination Hex String>
+      fee: <Total Fee Tokens Paid Rounded Down Number>
+      fee_mtokens: <Total Fee Millitokens Paid String>
+      id: <Payment Hash Hex String>
+      mtokens: <Total Millitokens Paid String>
+      paths: [{
+        fee: <Total Fee Tokens Paid Number>
+        fee_mtokens: <Total Fee Millitokens Paid String>
+        hops: [{
+          channel: <Standard Format Channel Id String>
+          channel_capacity: <Channel Capacity Tokens Number>
+          fee: <Fee Tokens Rounded Down Number>
+          fee_mtokens: <Fee Millitokens String>
+          forward: <Forward Tokens Number>
+          forward_mtokens: <Forward Millitokens String>
+          public_key: <Public Key Hex String>
+          timeout: <Timeout Block Height Number>
+        }]
+        mtokens: <Total Millitokens Paid String>
+        safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+        safe_tokens: <Total Tokens Paid, Rounded Up Number>
+        timeout: <Expiration Block Height Number>
+      }]
+      [request]: <BOLT 11 Encoded Payment Request String>
+      safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+      safe_tokens: <Total Tokens Paid, Rounded Up Number>
+      secret: <Payment Preimage Hex String>
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Tokens Paid Rounded Down Number>
+    }
+
+    @event 'failed'
+    {
+      is_insufficient_balance: <Failed Due To Lack of Balance Bool>
+      is_invalid_payment: <Failed Due to Payment Rejected At Destination Bool>
+      is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>
+      is_route_not_found: <Failed Due to Absence of Path Through Graph Bool>
+    }
+
+    @event 'paying'
+    {
+      created_at: <Payment Created At ISO 8601 Date String>
+      destination: <Payment Destination Hex String>
+      id: <Payment Hash Hex String>
+      mtokens: <Total Millitokens Pending String>
+      paths: [{
+        fee: <Total Fee Tokens Pending Number>
+        fee_mtokens: <Total Fee Millitokens Pending String>
+        hops: [{
+          channel: <Standard Format Channel Id String>
+          channel_capacity: <Channel Capacity Tokens Number>
+          fee: <Fee Tokens Rounded Down Number>
+          fee_mtokens: <Fee Millitokens String>
+          forward: <Forward Tokens Number>
+          forward_mtokens: <Forward Millitokens String>
+          public_key: <Public Key Hex String>
+          timeout: <Timeout Block Height Number>
+        }]
+        mtokens: <Total Millitokens Pending String>
+        safe_fee: <Total Fee Tokens Pending Rounded Up Number>
+        safe_tokens: <Total Tokens Pending, Rounded Up Number>
+        timeout: <Expiration Block Height Number>
+      }]
+      [request]: <BOLT 11 Encoded Payment Request String>
+      safe_tokens: <Total Tokens Pending, Rounded Up Number>
+      [timeout]: <Expiration Block Height Number>
+      tokens: <Total Tokens Pending Rounded Down Number>
+    }
+
+Example:
+
+```node
+const {subscribeToPayments} = require('ln-service');
+
+const sub = subscribeToPayments({lnd});
+
+const payments = [];
+
+// Collect sent payments
+sub.on('confirmed', n => payments.push(n));
+```
+
 ### subscribeToPeerMessages
 
 Subscribe to incoming peer messages

package/index.js

@@ -125,6 +125,7 @@ const {subscribeToPastPayments} = require('lightning');
 const {subscribeToPayViaDetails} = require('lightning');
 const {subscribeToPayViaRequest} = require('lightning');
 const {subscribeToPayViaRoutes} = require('lightning');
+const {subscribeToPayments} = require('lightning');
 const {subscribeToPeerMessages} = require('lightning');
 const {subscribeToPeers} = require('lightning');
 const {subscribeToProbeForRoute} = require('lightning');
@@ -275,6 +276,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPayments,
   subscribeToPeerMessages,
   subscribeToPeers,
   subscribeToProbeForRoute,

package/package.json

@@ -11,7 +11,7 @@
     "cors": "2.8.5",
     "express": "4.18.1",
     "invoices": "2.2.0",
-    "lightning": "6.0.0",
+    "lightning": "6.1.0",
     "macaroon": "3.0.4",
     "morgan": "1.10.0",
     "ws": "8.9.0"
@@ -27,8 +27,8 @@
     "bitcoinjs-lib": "6.0.2",
     "bn.js": "5.2.1",
     "bs58check": "2.1.2",
-    "ecpair": "2.0.1",
-    "ln-docker-daemons": "3.0.0",
+    "ecpair": "2.1.0",
+    "ln-docker-daemons": "3.0.1",
     "p2tr": "1.3.2",
     "portfinder": "1.0.32",
     "psbt": "2.7.1",
@@ -71,5 +71,5 @@
     "integration-test-0.12.0": "DOCKER_LND_VERSION=v0.12.0-beta npm run test",
     "test": "echo $DOCKER_LND_VERSION && tap -j 2 --branches=1 --functions=1 --lines=1 --statements=1 -t 200 test/autopilotrpc-integration/*.js test/chainrpc-integration/*.js test/integration/*.js test/invoicesrpc-integration/*.js test/peersrpc-integration/*.js test/routerrpc-integration/*.js test/signerrpc-integration/*.js test/tower_clientrpc-integration/*.js test/tower_serverrpc-integration/*.js test/walletrpc-integration/*.js"
   },
-  "version": "54.0.0"
+  "version": "54.1.0"
 }

package/test/integration/test_restrict_macaroon.js

@@ -0,0 +1,93 @@
+const {spawnLightningCluster} = require('ln-docker-daemons');
+const {test} = require('@alexbosworth/tap');
+
+const {createChainAddress} = require('./../../');
+const {delay} = require('./../macros');
+const {grantAccess} = require('./../../');
+const {restrictMacaroon} = require('./../../');
+
+const format = 'p2wpkh';
+const ip = '127.0.0.1';
+const methods = ['createChainAddress'];
+const wrongIp = '203.0.113.0';
+
+// Restricting the macaroon credentials should result in access limitation
+test(`Restricted macaroons restrict access`, async ({end, equal, rejects}) => {
+  const [{lnd, kill, rpc}] = (await spawnLightningCluster({})).nodes;
+
+  try {
+    const create = await grantAccess({lnd, methods});
+
+    // A regular macaroon can create a chain address
+    await createChainAddress({
+      format,
+      lnd: rpc({macaroon: create.macaroon}).lnd,
+    });
+
+    // A macaroon that is ip limited to the wrong ip is rejected
+    {
+      const {macaroon} = restrictMacaroon({
+        ip: wrongIp,
+        macaroon: create.macaroon,
+      });
+
+      await rejects(
+        createChainAddress({format, lnd: rpc({macaroon}).lnd}),
+        [503, 'UnexpectedErrorCreatingAddress'],
+        'Does not allow incorrect ip'
+      );
+
+      const addRestriction = restrictMacaroon({ip, macaroon});
+
+      const addedLnd = rpc({macaroon: addRestriction.macaroon});
+
+      await rejects(
+        createChainAddress({format, lnd: addedLnd.lnd}),
+        [503, 'UnexpectedErrorCreatingAddress'],
+        'Does not allow extended ip'
+      );
+    }
+
+    // A macaroon that is time limited is allowed at first
+    {
+      const {macaroon} = restrictMacaroon({
+        expires_at: new Date(Date.now() + 1000).toISOString(),
+        macaroon: create.macaroon,
+      });
+
+      // A time-limited macaroon should work within its time frame
+      await createChainAddress({format, lnd: rpc({macaroon}).lnd});
+
+      // Wait until the macaroon expires
+      await delay(2000);
+
+      // A macaroon that is expired is not allowed
+      await rejects(
+        createChainAddress({format, lnd: rpc({macaroon}).lnd}),
+        [503, 'UnexpectedErrorCreatingAddress'],
+        'Does not allow expired macaroon'
+      );
+
+      // Try extending the time of the macaroon to get around the timer
+      const addTime = restrictMacaroon({
+        macaroon,
+        expires_at: new Date(Date.now() + 1000).toISOString(),
+      });
+
+      const addedLnd = rpc({macaroon: addTime.macaroon});
+
+      // Adding time is also not allowed
+      await rejects(
+        createChainAddress({format, lnd: addedLnd.lnd}),
+        [503, 'UnexpectedErrorCreatingAddress'],
+        'Does not allow extending expired macaroon'
+      );
+    }
+  } catch (err) {
+    equal(err, null, 'Expected no error restricting macaroon');
+  }
+
+  await kill({});
+
+  return end();
+});

package/test/routerrpc-integration/test_subscribe_to_payments.js

@@ -0,0 +1,101 @@
+const asyncRetry = require('async/retry');
+const {setupChannel} = require('ln-docker-daemons');
+const {spawnLightningCluster} = require('ln-docker-daemons');
+const {test} = require('@alexbosworth/tap');
+
+const {createInvoice} = require('./../../');
+const {delay} = require('./../macros');
+const {getPayment} = require('./../../');
+const {payViaPaymentRequest} = require('./../../');
+const {subscribeToForwards} = require('./../../');
+const {subscribeToPayments} = require('./../../');
+const {waitForRoute} = require('./../macros');
+
+const unsupported = 'unknown method TrackPayments for service routerrpc.Router';
+const size = 2;
+const tokens = 100;
+
+// Subscribing to payments should notify on a payment
+test(`Subscribe to payments`, async ({end, rejects, strictSame}) => {
+  const {kill, nodes} = await spawnLightningCluster({size});
+
+  const [{generate, lnd}, target] = nodes;
+
+  try {
+    const forwards = [];
+    const isLegacy = [];
+    const isPaying = [];
+    const payments = [];
+
+    const invoice = await createInvoice({tokens, lnd: target.lnd});
+
+    const {id} = invoice;
+
+    await setupChannel({generate, lnd, to: target});
+
+    const sub = subscribeToPayments({lnd});
+    const sub2 = subscribeToForwards({lnd});
+
+    sub2.on('forward', forward => forwards.push(forward));
+    sub.on('confirmed', payment => payments.push(payment));
+    sub.on('paying', payment => isPaying.push(payment));
+
+    sub.on('error', error => {
+      const [,, {err}] = error;
+
+      // subscribeToPayments is not supported on LND 0.15.2 and below
+      if (err.details === unsupported) {
+        return isLegacy.push(error);
+      }
+
+      return strictSame(error, null, 'Expected no error');
+    });
+
+    await payViaPaymentRequest({lnd, request: invoice.request});
+
+    const {payment} = await getPayment({id, lnd});
+
+    await asyncRetry({interval: 10, times: 1000}, async () => {
+      if (forwards.length !== 2) {
+        throw new Error('ExpectedForwardsEvents');
+      }
+
+      return;
+    });
+
+    // Exit early when this is a legacy LND
+    if (!!isLegacy.length) {
+      [sub, sub2].forEach(n => n.removeAllListeners());
+
+      await kill({});
+
+      return end();
+    }
+
+    const [got] = payments;
+
+    const sent = forwards.find(n => n.is_confirmed && n.is_send);
+
+    [sub, sub2].forEach(n => n.removeAllListeners());
+
+    strictSame(got, payment, 'Payment subscription notifies of payment');
+
+    const [pending] = isPaying;
+
+    strictSame(pending.created_at, payment.created_at, 'Got date');
+    strictSame(pending.destination, payment.destination, 'Got destination');
+    strictSame(pending.id, payment.id, 'Got id');
+    strictSame(pending.mtokens, payment.mtokens, 'Got mtokens');
+    strictSame(pending.paths.length, payment.paths.length, 'Got path');
+    strictSame(pending.request, payment.request, 'Got request');
+    strictSame(pending.safe_tokens, payment.safe_tokens, 'Got safe tokens');
+    strictSame(pending.timeout, payment.timeout, 'Got timeout');
+    strictSame(pending.tokens, payment.tokens, 'Got tokens');
+  } catch (err) {
+    strictSame(err, null, 'Expected no error');
+  }
+
+  await kill({});
+
+  return end();
+});

package/test/extra-integration/test_restrict_macaroon.js

@@ -1,122 +0,0 @@
-const {address} = require('bitcoinjs-lib');
-const {test} = require('@alexbosworth/tap');
-
-const {authenticatedLndGrpc} = require('./../../');
-const {createChainAddress} = require('./../../');
-const {delay} = require('./../macros');
-const {grantAccess} = require('./../../');
-const {restrictMacaroon} = require('./../../');
-const {spawnLnd} = require('./../macros');
-const {waitForTermination} = require('./../macros');
-
-const format = 'np2wpkh';
-const ip = '127.0.0.1';
-const p2shAddressVersion = 196;
-const pkHashByteLength = 20;
-const regtestBech32AddressHrp = 'bcrt';
-
-// Restricting the macaroon credentials should result in access limitation
-test(`Restricted macaroons restrict access`, async ({end, equal, rejects}) => {
-  const spawned = await spawnLnd({});
-
-  const {lnd, kill} = spawned;
-
-  const cert = spawned.lnd_cert;
-  const socket = spawned.lnd_socket;
-
-  // A regular macaroon can create a chain address
-  {
-    const macaroon = spawned.lnd_macaroon;
-
-    const {lnd} = authenticatedLndGrpc({cert, macaroon, socket});
-
-    await createChainAddress({format, lnd});
-  }
-
-  // A macaroon that is ip limited to the wrong ip is rejected
-  {
-    const {macaroon} = restrictMacaroon({
-      ip: '203.0.113.0',
-      macaroon: spawned.lnd_macaroon,
-    });
-
-    const {lnd} = authenticatedLndGrpc({cert, macaroon, socket});
-
-    rejects(
-      createChainAddress({format, lnd}),
-      [503, 'UnexpectedErrorCreatingAddress'],
-      'Does not allow incorrect ip'
-    );
-
-    const addRestriction = restrictMacaroon({macaroon, ip: '127.0.0.1'});
-
-    const addedLnd = authenticatedLndGrpc({
-      cert,
-      socket,
-      macaroon: addRestriction.macaroon,
-    });
-
-    rejects(
-      createChainAddress({format, lnd: addedLnd.lnd}),
-      [503, 'UnexpectedErrorCreatingAddress'],
-      'Does not allow extended ip'
-    );
-  }
-
-  // A macaroon that is ip limited to the right ip is allowed
-  {
-    const {macaroon} = restrictMacaroon({
-      ip: '127.0.0.1',
-      macaroon: spawned.lnd_macaroon,
-    });
-
-    const {lnd} = authenticatedLndGrpc({cert, macaroon, socket});
-
-    await createChainAddress({format, lnd});
-  }
-
-  // A macaroon that is time limited is allowed at first
-  {
-    const {macaroon} = restrictMacaroon({
-      expires_at: new Date(Date.now() + 1000).toISOString(),
-      macaroon: spawned.lnd_macaroon,
-    });
-
-    const {lnd} = authenticatedLndGrpc({cert, macaroon, socket});
-
-    await createChainAddress({format, lnd});
-
-    await delay(2000);
-
-    // A macaroon that is expired is not allowed
-    rejects(
-      createChainAddress({format, lnd}),
-      [503, 'UnexpectedErrorCreatingAddress'],
-      'Does not allow expired macaroon'
-    );
-
-    const addTime = restrictMacaroon({
-      macaroon,
-      expires_at: new Date(Date.now() + 1000).toISOString(),
-    });
-
-    const addedLnd = authenticatedLndGrpc({
-      cert,
-      socket,
-      macaroon: addTime.macaroon,
-    });
-
-    // Adding time is also not allowed
-    rejects(
-      createChainAddress({format, lnd: addedLnd.lnd}),
-      [503, 'UnexpectedErrorCreatingAddress'],
-      'Does not allow extending expired macaroon'
-    );
-  }
-
-  kill();
-
-  await waitForTermination({lnd});
-
-  return end();
-});