ln-service 59.4.1 → 59.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Versions
 
+## 59.6.0
+
+- `payViaRoutes`, `subscribeToPayViaRoutes`: Add support for routes into
+    blinded paths: `encrypted_data` on blinded path hops and `path_key` on the
+    introduction node hop
+- `probeForRoute`, `subscribeToProbeForRoute`: Add `paths` to probe to blinded
+    paths: find a route to a path introduction node and return a route that
+    continues into the blinded path
+
+## 59.5.0
+
+- `createSignedRequest`: Add support for signing BLIP39 path payment requests
+- `createUnsignedRequest`: Add support for specifying BLIP39 payment req paths
+- `parsePaymentRequest`: Add support for parsing BLIP39 payment request paths
+
 ## 59.4.1
 
 - `subscribeToForwardRequests`: Invalid requests to forward more than the

package/README.md

@@ -4576,6 +4576,7 @@ Requires `offchain:write` permission
         fee_mtokens: <Total Fee Millitokens To Pay String>
         hops: [{
           channel: <Standard Format Channel Id String>
+          [encrypted_data]: <Blinded Path Encrypted Data Hex String>
           fee: <Fee Number>
           fee_mtokens: <Fee Millitokens String>
           forward: <Forward Tokens Number>
@@ -4584,6 +4585,7 @@ Requires `offchain:write` permission
             type: <Message Type Number String>
             value: <Message Raw Value Hex Encoded String>
           }]
+          [path_key]: <Blinded Path Key Hex String>
           [public_key]: <Public Key Hex String>
           timeout: <Timeout Block Height Number>
         }]
@@ -4592,19 +4594,21 @@ Requires `offchain:write` permission
           value: <Message Raw Value Hex Encoded String>
         }]
         mtokens: <Total Millitokens To Pay String>
+        [payment]: <Payment Identifier Hex String>
         timeout: <Expiration Block Height Number>
         tokens: <Total Tokens To Pay Number>
+        [total_mtokens]: <Total Millitokens String>
       }]
     }
 
     @returns via cbk or Promise
     {
+      confirmed_at: <Payment Confirmed At ISO 8601 Date String>
       failures: [[
         <Failure Code Number>
         <Failure Code Message String>
         <Failure Code Details Object>
       ]]
-      confirmed_at: <Payment Confirmed At ISO 8601 Date String>
       fee: <Fee Paid Tokens Number>
       fee_mtokens: <Fee Paid Millitokens String>
       hops: [{
@@ -4697,10 +4701,12 @@ Requires `offchain:write` permission
 
 Preferred `confidence` is not supported on LND 0.14.5 and below
 
+`paths` are blinded paths. If using, `destination` is not required.
+
     {
       [cltv_delta]: <Final CLTV Delta Number>
       [confidence]: <Preferred Route Confidence Number Out of One Million Number>
-      destination: <Destination Public Key Hex String>
+      [destination]: <Destination Public Key Hex String>
       [features]: [{
         bit: <Feature Bit Number>
       }]
@@ -4722,10 +4728,23 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
       [mtokens]: <Millitokens to Pay String>
       [outgoing_channel]: <Outgoing Channel Id String>
       [path_timeout_ms]: <Time to Spend On A Path Milliseconds Number>
+      [paths]: [{
+        base_fee_mtokens: <Accumulated Base Fee Millitokens String>
+        cltv_delta: <Accumulated CLTV Expiry Delta Number>
+        fee_rate: <Accumulated Fee Rate Millitokens Per Million Number>
+        hops: [{
+          encrypted_data: <Encrypted Recipient Data Hex String>
+          relay_key: <Relaying Node Public Key Hex String>
+        }]
+        [introduction_node]: <Introduction Node Public Key Hex String>
+        key: <First Hop Path Key Public Key Hex String>
+        [max_htlc_mtokens]: <Maximum HTLC Millitokens String>
+        [min_htlc_mtokens]: <Minimum HTLC Millitokens String>
+      }]
       [payment]: <Payment Identifier Hex String>
       [probe_timeout_ms]: <Probe Timeout Milliseconds Number>
       [routes]: [[{
-        [base_fee_mtokens]: <Base Routing Fee In Millitokens Number String>
+        [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
         [channel]: <Standard Format Channel Id String>
         [cltv_delta]: <CLTV Blocks Delta Number>
         [fee_rate]: <Fee Rate In Millitokens Per Million Number>
@@ -4743,10 +4762,12 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
         fee_mtokens: <Route Fee Millitokens String>
         hops: [{
           channel: <Standard Format Channel Id String>
+          [encrypted_data]: <Blinded Path Encrypted Data Hex String>
           fee: <Fee Number>
           fee_mtokens: <Fee Millitokens String>
           forward: <Forward Tokens Number>
           forward_mtokens: <Forward Millitokens String>
+          [path_key]: <Blinded Path Key Hex String>
           public_key: <Forward Edge Public Key Hex String>
           timeout: <Timeout Block Height Number>
         }]
@@ -6835,13 +6856,14 @@ Requires `offchain:write` permission
 
     {
       [id]: <Payment Hash Hex String>
-      lnd: <Authenticated LND gRPC API Object>
+      lnd: <Authenticated LND API Object>
       [pathfinding_timeout]: <Time to Spend Finding a Route Milliseconds Number>
       routes: [{
         fee: <Total Fee Tokens To Pay Number>
         fee_mtokens: <Total Fee Millitokens To Pay String>
         hops: [{
           channel: <Standard Format Channel Id String>
+          [encrypted_data]: <Blinded Path Encrypted Data Hex String>
           fee: <Fee Number>
           fee_mtokens: <Fee Millitokens String>
           forward: <Forward Tokens Number>
@@ -6850,6 +6872,7 @@ Requires `offchain:write` permission
             type: <Message Type Number String>
             value: <Message Raw Value Hex Encoded String>
           }]
+          [path_key]: <Blinded Path Key Hex String>
           public_key: <Public Key Hex String>
           timeout: <Timeout Block Height Number>
         }]
@@ -6858,8 +6881,10 @@ Requires `offchain:write` permission
           value: <Message Raw Value Hex Encoded String>
         }]
         mtokens: <Total Millitokens To Pay String>
+        [payment]: <Payment Identifier Hex String>
         timeout: <Expiration Block Height Number>
         tokens: <Total Tokens To Pay Number>
+        [total_mtokens]: <Total Millitokens String>
       }]
     }
 
@@ -6876,6 +6901,7 @@ Requires `offchain:write` permission
         <Failure Message String>
         {
           channel: <Standard Format Channel Id String>
+          [index]: <Failure Hop Index Number>
           [mtokens]: <Millitokens String>
           [policy]: {
             base_fee_mtokens: <Base Fee Millitokens String>
@@ -6920,6 +6946,7 @@ Requires `offchain:write` permission
     @event 'routing_failure'
     {
       [channel]: <Standard Format Channel Id String>
+      [height]: <Failure Height Context Number>
       [index]: <Failure Hop Index Number>
       [mtokens]: <Failure Related Millitokens String>
       [policy]: {
@@ -6945,11 +6972,11 @@ Requires `offchain:write` permission
           timeout: <Timeout Block Height Number>
         }]
         mtokens: <Total Millitokens To Pay String>
+        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
+        safe_tokens: <Payment Tokens Rounded Up Number>
         timeout: <Expiration Block Height Number>
         tokens: <Total Tokens To Pay Number>
       }
-      safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
-      safe_tokens: <Payment Tokens Rounded Up Number>
       [timeout_height]: <Failure Related CLTV Timeout Height Number>
       [update]: {
         chain: <Chain Id Hex String>
@@ -6988,6 +7015,8 @@ Requires `offchain:write` permission
           timeout: <Timeout Block Height Number>
         }]
         mtokens: <Total Millitokens To Pay String>
+        safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
+        safe_tokens: <Payment Tokens Rounded Up Number>
         timeout: <Expiration Block Height Number>
         tokens: <Total Tokens To Pay Number>
       }
@@ -7195,10 +7224,12 @@ Requires `offchain:write` permission
 
 Preferred `confidence` is not supported on LND 0.14.5 and below
 
+`paths` are blinded paths. If using, `destination` is not required.
+
     {
       [cltv_delta]: <Final CLTV Delta Number>
       [confidence]: <Preferred Route Confidence Number Out of One Million Number>
-      destination: <Destination Public Key Hex String>
+      [destination]: <Destination Public Key Hex String>
       [features]: [{
         bit: <Feature Bit Number>
       }]
@@ -7218,6 +7249,19 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
       [mtokens]: <Millitokens to Probe String>
       [outgoing_channel]: <Outgoing Channel Id String>
       [path_timeout_ms]: <Skip Individual Path Attempt After Milliseconds Number>
+      [paths]: [{
+        base_fee_mtokens: <Accumulated Base Fee Millitokens String>
+        cltv_delta: <Accumulated CLTV Expiry Delta Number>
+        fee_rate: <Accumulated Fee Rate Millitokens Per Million Number>
+        hops: [{
+          encrypted_data: <Encrypted Recipient Data Hex String>
+          relay_key: <Relaying Node Public Key Hex String>
+        }]
+        [introduction_node]: <Introduction Node Public Key Hex String>
+        key: <First Hop Path Key Public Key Hex String>
+        [max_htlc_mtokens]: <Maximum HTLC Millitokens String>
+        [min_htlc_mtokens]: <Minimum HTLC Millitokens String>
+      }]
       [payment]: <Payment Identifier Hex String>
       [probe_timeout_ms]: <Fail Entire Probe After Milliseconds Number>
       [routes]: [[{
@@ -7245,10 +7289,12 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
         fee_mtokens: <Total Fee Millitokens To Pay String>
         hops: [{
           channel: <Standard Format Channel Id String>
+          [encrypted_data]: <Blinded Path Encrypted Data Hex String>
           fee: <Fee Number>
           fee_mtokens: <Fee Millitokens String>
           forward: <Forward Tokens Number>
           forward_mtokens: <Forward Millitokens String>
+          [path_key]: <Blinded Path Key Hex String>
           public_key: <Public Key Hex String>
           timeout: <Timeout Block Height Number>
         }]
@@ -7298,6 +7344,7 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
     @event 'routing_failure'
     {
       [channel]: <Standard Format Channel Id String>
+      index: <Failure Index Number>
       [mtokens]: <Millitokens String>
       [policy]: {
         base_fee_mtokens: <Base Fee Millitokens String>
@@ -7306,8 +7353,10 @@ Preferred `confidence` is not supported on LND 0.14.5 and below
         [is_disabled]: <Channel is Disabled Bool>
         max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
         min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
+        [public_key]: <Public Key Hex String>
+        [updated_at]: <Updated At ISO 8601 Date String>
       }
-      public_key: <Public Key Hex String>
+      [public_key]: <Public Key Hex String>
       reason: <Failure Reason String>
       route: {
         [confidence]: <Route Confidence Score Out Of One Million Number>

package/package.json

@@ -13,8 +13,8 @@
   },
   "dependencies": {
     "bolt07": "2.0.0",
-    "invoices": "6.1.4",
-    "lightning": "12.3.1",
+    "invoices": "6.2.0",
+    "lightning": "12.4.0",
     "macaroon": "3.0.4"
   },
   "description": "Interaction helper for your Lightning Network daemon",
@@ -24,7 +24,7 @@
     "asyncjs-util": "1.2.12",
     "bip32": "5.0.1",
     "bip66": "2.0.0",
-    "bolt04": "1.0.0",
+    "bolt04": "1.2.0",
     "ecpair": "3.0.2",
     "ln-docker-daemons": "8.0.5",
     "p2tr": "3.0.0",
@@ -35,6 +35,11 @@
   "engines": {
     "node": ">=22"
   },
+  "files": [
+    "CHANGELOG.md",
+    "index.js",
+    "macaroons"
+  ],
   "keywords": [
     "bitcoin",
     "grpc",
@@ -61,5 +66,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.4.1"
+  "version": "59.6.0"
 }

package/.gitattributes

@@ -1 +0,0 @@
-package-lock.json binary

package/.tm_properties

@@ -1 +0,0 @@
-exclude = '{$exclude,node_modules}'

package/test/autopilotrpc-integration/test_autopilot.js

@@ -1,87 +0,0 @@
-const {strictEqual} = require('node:assert').strict;
-const test = require('node:test');
-
-const {setupChannel} = require('ln-docker-daemons');
-const {spawnLightningCluster} = require('ln-docker-daemons');
-
-const {addPeer} = require('./../../');
-const {getAutopilot} = require('./../../');
-const {setAutopilot} = require('./../../');
-
-const avg = array => array.reduce((a, b) => a + b) / array.length;
-const confirmationCount = 6;
-const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
-const maxScore = 1e8;
-const score = 50000000;
-const size = 2;
-
-// Adjusting autopilot should result in changed autopilot status
-test(`Autopilot`, async () => {
-  const {kill, nodes} = await spawnLightningCluster({size});
-
-  const [control, target] = nodes;
-
-  const cluster = {control, target};
-
-  const {lnd} = cluster.control;
-
-  await setupChannel({lnd, generate: control.generate, to: cluster.target});
-
-  strictEqual(
-    (await getAutopilot({lnd})).is_enabled,
-    false,
-    'Autopilot starts off'
-  );
-
-  await Promise.all([
-    cluster.control.generate({count: confirmationCount}),
-    delay(3000),
-    setAutopilot({lnd, is_enabled: true}),
-  ]);
-
-  await addPeer({
-    lnd,
-    public_key: cluster.target.id,
-    socket: cluster.target.socket,
-  });
-
-  strictEqual(
-    (await getAutopilot({lnd})).is_enabled,
-    true,
-    'Autopilot turned on'
-  );
-
-  await setAutopilot({lnd, is_enabled: false});
-
-  strictEqual(
-    (await getAutopilot({lnd})).is_enabled,
-    false,
-    'Autopilot turned off'
-  );
-
-  const pubKey = cluster.control.id;
-
-  await setAutopilot({
-    lnd,
-    candidate_nodes: [{public_key: pubKey, score}],
-    is_enabled: true,
-  });
-
-  const autopilot = await getAutopilot({lnd, node_scores: [pubKey]});
-
-  strictEqual(autopilot.is_enabled, true, 'Autopilot was enable');
-
-  const [node] = autopilot.nodes;
-
-  strictEqual(node.local_preferential_score, maxScore, 'Local score');
-  strictEqual(node.local_score, score, 'Local score is represented');
-  strictEqual(node.preferential_score, maxScore, 'Global preferential score');
-  strictEqual(node.public_key, pubKey, 'Candidate node public key');
-  strictEqual(node.score, score, 'External score is represented');
-  strictEqual(node.weighted_local_score, avg([maxScore, score]), 'Weight avg');
-  strictEqual(node.weighted_score, avg([maxScore, score]), 'Norm Weight avg');
-
-  await kill({});
-
-  return;
-});

package/test/chainrpc-integration/test_get_block.js

@@ -1,58 +0,0 @@
-const {strictEqual} = require('node:assert').strict;
-const test = require('node:test');
-
-const {idForBlock} = require('@alexbosworth/blockchain');
-const {spawnLightningCluster} = require('ln-docker-daemons');
-
-const {getBlock} = require('./../../');
-const {getHeight} = require('./../../');
-
-// Get height should return height
-test(`Get height`, async () => {
-  const {nodes} = await spawnLightningCluster({});
-
-  const [{chain, generate, kill, lnd}] = nodes;
-
-  const blockchain = await getHeight({lnd});
-
-  const hash = blockchain.current_block_hash;
-  const height = blockchain.current_block_height;
-
-  // Try getting a block by the hash
-  try {
-    const {block} = await getBlock({lnd, id: blockchain.current_block_hash});
-
-    strictEqual(idForBlock({block}).id, hash, 'Got block');
-  } catch (err) {
-    const [code, message] = err;
-
-    strictEqual(code, 501, 'Got expected code');
-    strictEqual(message, 'GetBlockMethodNotSupported', 'Got expected message');
-
-    await kill({});
-
-    return;
-  }
-
-  // Try getting a block by the height
-  try {
-    const {block} = await getBlock({height, lnd});
-
-    strictEqual(idForBlock({block}).id, hash, 'Got block for height');
-  } catch (err) {
-    strictEqual(err, null, 'Expected no error');
-  }
-
-  // Try getting the chain tip block
-  try {
-    const {block} = await getBlock({lnd});
-
-    strictEqual(idForBlock({block}).id, hash, 'Got chain tip block');
-  } catch (err) {
-    strictEqual(err, null, 'Expected no error');
-  }
-
-  await kill({});
-
-  return;
-});

package/test/chainrpc-integration/test_get_block_header.js

@@ -1,62 +0,0 @@
-const {strictEqual} = require('node:assert').strict;
-const test = require('node:test');
-
-const {spawnLightningCluster} = require('ln-docker-daemons');
-
-const {getBlockHeader} = require('./../../');
-const {getHeight} = require('./../../');
-
-const headerHexLength = 80 * 2;
-
-// Get block header should return the block header
-test(`Get block header`, async () => {
-  const {nodes} = await spawnLightningCluster({});
-
-  const [{chain, generate, kill, lnd}] = nodes;
-
-  const blockchain = await getHeight({lnd});
-
-  const hash = blockchain.current_block_hash;
-  const height = blockchain.current_block_height;
-
-  // Try getting a block header by the hash
-  try {
-    const {header} = await getBlockHeader({
-      lnd,
-      id: blockchain.current_block_hash,
-    });
-
-    strictEqual(header.length, headerHexLength, 'Got header');
-  } catch (err) {
-    const [code, message] = err;
-
-    strictEqual(code, 501, 'Got expected code');
-    strictEqual(message, 'GetBlockHeaderMethodNotSupported', 'Got error');
-
-    await kill({});
-
-    return;
-  }
-
-  // Try getting a block header by the height
-  try {
-    const {header} = await getBlockHeader({height, lnd});
-
-    strictEqual(header.length, headerHexLength, 'Got header');
-  } catch (err) {
-    strictEqual(err, null, 'Expected no error');
-  }
-
-  // Try getting the chain tip block header
-  try {
-    const {header} = await getBlockHeader({lnd});
-
-    strictEqual(header.length, headerHexLength, 'Got header');
-  } catch (err) {
-    strictEqual(err, null, 'Expected no error');
-  }
-
-  await kill({});
-
-  return;
-});

package/test/chainrpc-integration/test_get_height.js

@@ -1,42 +0,0 @@
-const {strictEqual} = require('node:assert').strict;
-const test = require('node:test');
-
-const asyncRetry = require('async/retry');
-const {spawnLightningCluster} = require('ln-docker-daemons');
-
-const {getHeight} = require('./../../');
-
-const confirmationCount = 6;
-const interval = 100;
-const times = 100;
-
-// Get height should return height
-test(`Get height`, async () => {
-  const {nodes} = await spawnLightningCluster({});
-
-  const [{chain, generate, kill, lnd}] = nodes;
-
-  const startHeight = (await getHeight({lnd})).current_block_height;
-
-  await asyncRetry({interval, times}, async () => {
-    await generate({});
-
-    const endHeight = (await getHeight({lnd})).current_block_height;
-
-    if (endHeight - startHeight < confirmationCount) {
-      throw new Error('ExpectedHeightIncreaseReflected');
-    }
-
-    strictEqual(
-      endHeight - startHeight >= confirmationCount,
-      true,
-      'Got height'
-    );
-
-    return;
-  });
-
-  await kill({});
-
-  return;
-});

package/test/chainrpc-integration/test_subscribe_to_blocks.js

@@ -1,97 +0,0 @@
-const EventEmitter = require('node:events');
-const {once} = require('node:events');
-const {strictEqual} = require('node:assert').strict;
-const test = require('node:test');
-
-const asyncRetry = require('async/retry');
-const {spawnLightningCluster} = require('ln-docker-daemons');
-
-const {createChainAddress} = require('./../../');
-const {getHeight} = require('./../../');
-const {getChainBalance} = require('./../../');
-const {getWalletInfo} = require('./../../');
-const {subscribeToBlocks} = require('./../../');
-
-const confirmationCount = 6;
-const interval = 50;
-const race = promises => Promise.race(promises);
-const times = 4000;
-
-// Subscribers to blocks should receive block notifications
-test(`Subscribe to blocks`, async () => {
-  const blocks = [];
-  const {kill, nodes} = await spawnLightningCluster({});
-
-  const [{generate, lnd}] = nodes;
-
-  // Try to make sure that the chain notifier RPC is ready
-  await asyncRetry({interval, times}, async () => {
-    const wallet = await getWalletInfo({lnd});
-
-    await generate({});
-
-    if (!wallet.is_synced_to_chain) {
-      throw new Error('NotSyncedToChain');
-    }
-  });
-
-  const gotHeight = await asyncRetry({interval, times}, async () => {
-    const subBlocks = subscribeToBlocks({lnd});
-
-    const [event] = await race([
-      once(subBlocks, 'block'),
-      once(subBlocks, 'error'),
-    ]);
-
-    if (!event.height) {
-      throw new Error('ExpectedBlockEvent');
-    }
-
-    return !!event.height;
-  });
-
-  strictEqual(gotHeight, true, 'Got the block height');
-
-  try {
-    // Wait for chainrpc to be active
-    await asyncRetry({interval, times}, async () => {
-      if (!!(await getChainBalance({lnd})).chain_balance) {
-        return;
-      }
-
-      await generate({});
-
-      await getHeight({lnd});
-
-      throw new Error('ExpectedChainBalance');
-    });
-
-    const sub = subscribeToBlocks({lnd});
-    const startHeight = (await getHeight({lnd})).current_block_height;
-
-    sub.on('block', data => blocks.push(data));
-    sub.on('error', err => {});
-
-    const {address} = await createChainAddress({lnd});
-
-    await asyncRetry({interval, times}, async () => {
-      await generate({});
-
-      if (blocks.length < confirmationCount) {
-        throw new Error('ExpectedAdditionalBlocks');
-      }
-    });
-
-    blocks.forEach(({height, id}) => {
-      strictEqual(!!height, true, 'Got expected block height');
-      strictEqual(id.length, 64, 'Got expected block hash length');
-      return;
-    });
-  } catch (err) {
-    strictEqual(err, null, 'Expected no error');
-  } finally {
-    await kill({});
-
-    return;
-  }
-});