ln-service 59.5.0 → 59.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Versions
 
+## 59.7.0
+
+- `signBytes`: Add `tag` to sign a BIP-340 tagged hash of the bytes with a
+    `schnorr` signature
+- `verifyBytesSignature`: Add `tag` to verify a `schnorr` signature over a
+    BIP-340 tagged hash of the bytes
+
+## 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

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>
         }]
@@ -5420,11 +5441,14 @@ Requires `signer:generate` permission
 
 `schnorr` signature type is not supported on LND 0.15.0 and below
 
+`tag` is not supported on LND 0.17.5 and below and requires `schnorr` type
+
     {
       key_family: <Key Family Number>
       key_index: <Key Index Number>
-      lnd: <Authenticated LND gRPC API Object>
+      lnd: <Authenticated LND API Object>
       preimage: <Bytes To Hash and Sign Hex Encoded String>
+      [tag]: <BIP-340 Tagged Hash Tag UTF8 String>
       [type]: <Signature Type String>
     }
 
@@ -5445,6 +5469,16 @@ const {signature} = await signBytes({
   key_index: 0,
   preimage: '00',
 });
+
+// Get a schnorr signature over a BIP-340 tagged hash of the preimage
+const tagged = await signBytes({
+  lnd,
+  key_family: 6,
+  key_index: 0,
+  preimage: '00',
+  tag: 'BIP0322-signed-message',
+  type: 'schnorr',
+});
 ```
 
 ### signChainAddressMessage
@@ -6835,13 +6869,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 +6885,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 +6894,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 +6914,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 +6959,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 +6985,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 +7028,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 +7237,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 +7262,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 +7302,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 +7357,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 +7366,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>
@@ -8005,11 +8067,14 @@ Requires `signer:read` permission
 
 Validating `schnorr` signatures is unsupported in LND 0.15.0 and below
 
+`tag` is not supported on LND 0.17.5 and below
+
     {
       lnd: <Authenticated LND API Object>
       preimage: <Message Preimage Bytes Hex Encoded String>
       public_key: <Signature Valid For Public Key Hex String>
       signature: <Signature Hex String>
+      [tag]: <BIP-340 Tagged Hash Tag UTF8 String>
     }
 
     @returns via cbk or Promise
@@ -8034,6 +8099,25 @@ const validity = await verifyBytesSignature({
   signature,
   public_key: (await getIdentity({lnd})).public_key,
 });
+
+// Sign a BIP-340 tagged hash of the preimage with a schnorr signature
+const tagged = await signBytes({
+  lnd,
+  preimage,
+  key_family: 6,
+  key_index: 0,
+  tag: 'BIP0322-signed-message',
+  type: 'schnorr',
+});
+
+// Verify the tagged hash signature using the x-only public key
+const taggedValidity = await verifyBytesSignature({
+  lnd,
+  preimage,
+  public_key: (await getIdentity({lnd})).public_key.slice(2),
+  signature: tagged.signature,
+  tag: 'BIP0322-signed-message',
+});
 ```
 
 ### verifyChainAddressMessage

package/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "bolt07": "2.0.0",
     "invoices": "6.2.0",
-    "lightning": "12.3.1",
+    "lightning": "12.5.0",
     "macaroon": "3.0.4"
   },
   "description": "Interaction helper for your Lightning Network daemon",
@@ -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.5.0"
+  "version": "59.7.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;
-});