ln-service 59.3.7 → 59.4.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Versions
 
+## 59.4.0
+
+- `sendMessage`: Add method to send a network onion message
+- `subscribeToMessages`: Add method to listen to network onion messages
+
 ## 59.3.7
 
 - Add support for LND 0.21.3

package/README.md

@@ -257,6 +257,7 @@ for `unlocker` methods.
 - [restrictMacaroon](#restrictmacaroon) - Add limitations to a macaroon
 - [revokeAccess](#revokeaccess) - Revoke all access macaroons given to an id
 - [routeFromChannels](#routefromchannels) - Convert channel series to a route
+- [sendMessage](#sendmessage) - Send a network onion message
 - [sendMessageToPeer](#sendmessagetopeer) - Send a custom message to a peer
 - [sendToChainAddress](#sendtochainaddress) - Send on-chain to an address
 - [sendToChainAddresses](#sendtochainaddresses) - Send on-chain to addresses
@@ -281,6 +282,7 @@ for `unlocker` methods.
 - [subscribeToGraph](#subscribetograph) - Subscribe to network graph updates
 - [subscribeToInvoice](#subscribetoinvoice) - Subscribe to invoice updates
 - [subscribeToInvoices](#subscribetoinvoices) - Subscribe to all invoices
+- [subscribeToMessages](#subscribetomessages) - Subscribe to network messages
 - [subscribeToOpenRequests](#subscribetoopenrequests) - Approve open requests
 - [subscribeToPastPayment](#subscribetopastpayment) - Subscribe to a payment
 - [subscribeToPastPayments](#subscribetopastpayments) - Subscribe to all sent
@@ -5140,6 +5142,53 @@ const res = routeFromChannels({channels, destination, height, mtokens});
 const {route} = res;
 ```
 
+### sendMessage
+
+Send a generic message over the network
+
+The receiver of the message needs to first publish an inbound path to them,
+this is supplied via `inbound`. To send, add a series of relaying node ids
+that support message passing, to a landmark node provided by the receiver.
+
+This method is not supported in LND 0.20.4 and below
+
+    {
+      inbound: [{
+        encrypted_data: <Encrypted Data Hex String>
+        relay_key: <Blinded Relaying Public Key Into Destination Hex String>
+      }]
+      key: <Message Path Key Hex String>
+      lnd: <Authenticated LND API Object>
+      [message]: {
+        type: <Message Payload Record Type Number String>
+        value: <Message Payload Hex String>
+      }
+      outbound: [<Relaying Node Public Key Out of Source Hex String>]
+      [reply]: [<Reply Path Relaying Node Public Key Back To Sender Hex String>]
+    }
+
+    @returns via cbk or Promise
+    {
+      [reply]: <Reply Identifier Hex String>
+    }
+
+Example:
+
+```node
+const {sendMessage} = require('ln-service');
+
+const {reply} = await sendMessage({
+  lnd,
+  inbound: blindedPath.path,
+  key: blindedPath.key,
+  outbound: [peer.public_key, blindedPath.introduction_node],
+  message: {type, value},
+  reply: [peer.public_key, own.public_key],
+});
+
+// Wait for message reply on `reply` id
+```
+
 ### sendMessageToPeer
 
 Send a custom message to a connected peer
@@ -6165,6 +6214,67 @@ const sub = subscribeToInvoices({lnd});
 const [lastUpdatedInvoice] = await once(sub, 'invoice_updated');
 ```
 
+### subscribeToMessages
+
+Subscribe to received onion messages
+
+Requires `offchain:read` permission
+
+This method is not supported in LND 0.20.4 and below
+
+    {
+      lnd: <Authenticated LND API Object>
+    }
+
+    @returns
+    <EventEmitter Object>
+
+    @event 'message_received'
+    {
+      encrypted: <Encrypted Data Hex String>
+      key: <Path Key Hex String>
+      [message]: {
+        type: <Message Payload Record Type Number String>
+        value: <Message Payload Hex String>
+      }
+      onion: <Onion Packet Hex String>
+      [reply]: {
+        inbound: [{
+          encrypted_data: <Encrypted Data Hex String>
+          relay_key: <Blinded Relay Key Hex String>
+        }]
+        [introduction_edge]: <Introduction Node Edge Format Channel Id String>
+        [introduction_node]: <Introduction Node Public Key Hex String>
+        key: <Path Key Hex String>
+      }
+      via: <Message Received Via Peer with Id Public Key Hex String>
+    }
+
+```node
+const {decryptBlindedPath} = require('bolt04');
+const {diffieHellmanComputeSecret} = require('ln-service');
+const {subscribeToMessages} = require('ln-service');
+
+const sub = subscribeToMessages({lnd});
+
+sub.on('message_received', async ({custom, encrypted, key}) => {
+  // The message id is encrypted
+  const {secret} = await diffieHellmanComputeSecret({
+    lnd,
+    partner_public_key: key,
+  });
+
+  const decrypted = decryptBlindedPath({encrypted, key, secret});
+
+  // The received id should be equal to the one given out
+  if (decrypted.id !== blindedPath.id) {
+    return;
+  }
+
+  // Message to path received
+});
+```
+
 ### subscribeToOpenRequests
 
 Subscribe to inbound channel open requests

package/index.js

@@ -112,6 +112,7 @@ const {requestChainFeeIncrease} = require('lightning');
 const {restrictMacaroon} = require('./macaroons');
 const {revokeAccess} = require('lightning');
 const {routeFromChannels} = require('bolt07');
+const {sendMessage} = require('lightning');
 const {sendMessageToPeer} = require('lightning');
 const {sendToChainAddress} = require('lightning');
 const {sendToChainAddresses} = require('lightning');
@@ -134,6 +135,7 @@ const {subscribeToForwards} = require('lightning');
 const {subscribeToGraph} = require('lightning');
 const {subscribeToInvoice} = require('lightning');
 const {subscribeToInvoices} = require('lightning');
+const {subscribeToMessages} = require('lightning');
 const {subscribeToOpenRequests} = require('lightning');
 const {subscribeToPastPayment} = require('lightning');
 const {subscribeToPastPayments} = require('lightning');
@@ -279,6 +281,7 @@ module.exports = {
   restrictMacaroon,
   revokeAccess,
   routeFromChannels,
+  sendMessage,
   sendMessageToPeer,
   sendToChainAddress,
   sendToChainAddresses,
@@ -301,6 +304,7 @@ module.exports = {
   subscribeToGraph,
   subscribeToInvoice,
   subscribeToInvoices,
+  subscribeToMessages,
   subscribeToOpenRequests,
   subscribeToPastPayment,
   subscribeToPastPayments,

package/package.json

@@ -14,25 +14,23 @@
   "dependencies": {
     "bolt07": "2.0.0",
     "invoices": "6.1.4",
-    "lightning": "12.2.11",
+    "lightning": "12.3.0",
     "macaroon": "3.0.4"
   },
   "description": "Interaction helper for your Lightning Network daemon",
   "devDependencies": {
-    "@alexbosworth/blockchain": "4.7.2",
+    "@alexbosworth/blockchain": "4.8.0",
     "async": "3.2.6",
     "asyncjs-util": "1.2.12",
     "bip32": "5.0.1",
     "bip66": "2.0.0",
-    "bn.js": "5.2.5",
-    "bs58check": "4.0.0",
-    "ecpair": "3.0.1",
-    "ln-docker-daemons": "8.0.4",
+    "bolt04": "1.0.0",
+    "ecpair": "3.0.2",
+    "ln-docker-daemons": "8.0.5",
     "p2tr": "3.0.0",
     "portfinder": "1.0.38",
     "psbt": "6.0.3",
-    "tiny-secp256k1": "2.2.4",
-    "varuint-bitcoin": "2.0.0"
+    "tiny-secp256k1": "2.2.4"
   },
   "engines": {
     "node": ">=22"
@@ -63,5 +61,5 @@
     "integration-test-0.20.0": "DOCKER_LND_VERSION=v0.20.0-beta npm run test",
     "test": "echo $DOCKER_LND_VERSION && node test/runner"
   },
-  "version": "59.3.7"
+  "version": "59.4.0"
 }

package/test/integration/test_subscribe_to_messages.js

@@ -0,0 +1,180 @@
+const {equal} = require('node:assert').strict;
+const test = require('node:test');
+
+const asyncRetry = require('async/retry');
+const {blindedPathFromHops} = require('bolt04');
+const {decryptBlindedPath} = require('bolt04');
+const {setupChannel} = require('ln-docker-daemons');
+const {spawnLightningCluster} = require('ln-docker-daemons');
+
+const {diffieHellmanComputeSecret} = require('./../../');
+const {sendMessage} = require('./../../');
+const {subscribeToMessages} = require('./../../');
+
+const capacity = 1e6;
+const interval = 10;
+const size = 5;
+const times = 1000;
+const type = '805805';
+const value = Buffer.from('hello world').toString('hex');
+
+// Subscribing to messages should surface message events
+test('Subscribe to messages', async t => {
+  const {kill, nodes} = await spawnLightningCluster({size});
+  const messages = {};
+
+  const [control, alice, bob, charlie, dave] = nodes;
+
+  const {generate, lnd} = control;
+
+  try {
+    // Dave creates a blinded path into their node, given out of band to CTRL
+    const blindedPath = (() => {
+      const hops = [bob.id, charlie.id, dave.id];
+
+      const {id, key, path} = blindedPathFromHops({hops});
+
+      return {id, key, path, introduction_node: bob.id};
+    })();
+
+    // Control listens for a reply to their message
+    const subReply = subscribeToMessages({lnd});
+
+    subReply.on('message_received', async ({encrypted, key, message})=> {
+      // The message id is encrypted
+      const {secret} = await diffieHellmanComputeSecret({
+        lnd,
+        partner_public_key: key,
+      });
+
+      const decrypted = decryptBlindedPath({encrypted, key, secret});
+
+      messages.reply = {received_value: message.value, reply_id: decrypted.id};
+
+      return;
+    });
+
+    // Dave listens for a message to be received on their blinded path
+    const sub = subscribeToMessages({lnd: dave.lnd});
+
+    sub.on('message_received', async ({encrypted, key, message, reply}) => {
+      const {secret} = await diffieHellmanComputeSecret({
+        lnd: dave.lnd,
+        partner_public_key: key,
+      });
+
+      const decrypted = decryptBlindedPath({key, encrypted, secret});
+
+      // The received id should be equal to the one given out
+      if (decrypted.id !== blindedPath.id) {
+        return;
+      }
+
+      await sendMessage({
+        lnd: dave.lnd,
+        inbound: reply.inbound.map(hop => ({
+          encrypted_data: hop.encrypted_data,
+          relay_key: hop.relay_key,
+        })),
+        key: reply.key,
+        message: {type, value: message.value + message.value},
+        outbound: [charlie.id, bob.id, reply.introduction_node],
+      });
+    });
+
+    // Make channels between all nodes so they will relay messages
+    {
+      await asyncRetry({interval, times}, async () => {
+        await generate({});
+
+        await setupChannel({
+          capacity,
+          generate,
+          lnd,
+          to: alice,
+        });
+      });
+
+      // Make sure that send message is supported by LND
+      try {
+        await sendMessage({
+          lnd,
+          inbound: blindedPath.path,
+          key: blindedPath.key,
+          message: {type, value},
+          outbound: [alice.id, blindedPath.introduction_node],
+          reply: [alice.id, control.id],
+        });
+      } catch (err) {
+        await kill({});
+
+        const [code, message] = err;
+
+        equal(code, 501, 'Method not supported');
+        equal(message, 'SendOnionMessageMethodUnsupported', 'Unknown method');
+
+        return;
+      }
+
+      await asyncRetry({interval, times}, async () => {
+        await alice.generate({});
+
+        await setupChannel({
+          capacity,
+          generate: alice.generate,
+          lnd: alice.lnd,
+          to: bob,
+        });
+      });
+
+      await asyncRetry({interval, times}, async () => {
+        await bob.generate({});
+
+        await setupChannel({
+          capacity,
+          generate: bob.generate,
+          lnd: bob.lnd,
+          to: charlie,
+        });
+      });
+
+      await asyncRetry({interval, times}, async () => {
+        await charlie.generate({});
+
+        await setupChannel({
+          capacity,
+          generate: charlie.generate,
+          lnd: charlie.lnd,
+          to: dave,
+        });
+      });
+    }
+
+    const {reply} = await sendMessage({
+      lnd,
+      inbound: blindedPath.path,
+      key: blindedPath.key,
+      message: {type, value},
+      outbound: [alice.id, blindedPath.introduction_node],
+      reply: [alice.id, control.id],
+    });
+
+    // Wait for the message send and response
+    await asyncRetry({interval, times}, async () => {
+      if (!messages.reply) {
+        throw new Error('ExpectedMessageReplyReceived');
+      }
+
+      return;
+    });
+
+    equal(messages.reply.reply_id, reply, 'Got correct message reply id');
+    equal(messages.reply.received_value, value + value, 'Got message reply');
+
+    await kill({});
+  } catch (err) {
+    await kill({});
+
+    throw err;
+  }
+});

package/test/walletrpc-integration/test_get_master_public_keys.js

@@ -3,7 +3,7 @@ const {equal} = require('node:assert').strict;
 const test = require('node:test');
 
 const bip32 = require('bip32');
-const bs58check = require('bs58check').default;
+const {decodeBase58} = require('@alexbosworth/blockchain');
 const ecc = require('tiny-secp256k1')
 const {spawnLightningCluster} = require('ln-docker-daemons');
 
@@ -60,10 +60,12 @@ test(`Get master public keys`, async () => {
     const masterIdentityKey = keys.find(n => n.named === identityKeyName);
 
     // Convert the key from base58 into its raw form
-    const rawKey = bs58check.decode(masterIdentityKey.extended_public_key);
+    const {payload} = decodeBase58({
+      encoded: masterIdentityKey.extended_public_key,
+    });
 
-    const chainCode = Buffer.from(chainCodeFromMasterPublicKey(rawKey));
-    const publicKey = Buffer.from(publicKeyFromMasterPublicKey(rawKey));
+    const chainCode = chainCodeFromMasterPublicKey(payload);
+    const publicKey = publicKeyFromMasterPublicKey(payload);
 
     // Make a bip32 object to derive from
     const masterKey = fromPublicKey(publicKey, chainCode);

package/test/macros/script_buffers_as_script.js

@@ -1,32 +0,0 @@
-const BN = require('bn.js');
-
-const {encode} = require('varuint-bitcoin');
-
-const decBase = 10;
-const {isBuffer} = Buffer;
-
-/** Convert an array of script buffer elements to a fully formed script
-
-  @param
-  [<Script Element Buffer>, <Script OP_CODE Decimal Number>]
-
-  @throws
-  <Error> when a script element length exceeds maximum
-
-  @returns
-  <Script Hex>
-*/
-module.exports = scriptElements => {
-   // Convert numbers to buffers and hex data to pushdata
-  const fullScript = scriptElements
-    .map(element => {
-      if (isBuffer(element)) {
-        return Buffer.concat([encode(element.length), element]);
-      } else {
-        return new BN(element, decBase).toArrayLike(Buffer);
-      }
-    })
-    .reduce((element, script) => Buffer.concat([element, script]));
-
-  return fullScript.toString('hex');
-};