lightning 5.13.0 → 5.15.0

package/lnd_methods/offchain/probe_for_route.js

@@ -17,8 +17,11 @@ const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 
   Requires `offchain:write` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key Hex String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -117,6 +120,7 @@ module.exports = (args, cbk) => {
 
         const sub = subscribeToProbeForRoute({
           cltv_delta: args.cltv_delta,
+          confidence: args.confidence,
           destination: args.destination,
           features: args.features,
           ignore: args.ignore,

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -16,6 +16,7 @@ const {routeHintFromRoute} = require('./../../lnd_requests');
 const {safeTokens} = require('./../../bolt00');
 const {states} = require('./payment_states');
 
+const asTimePreference = n => n === undefined ? n : ((n * 2) - 1e6) / 1e6;
 const cltvBuf = 3;
 const cltvLimit = (limit, height) => !limit ? undefined : limit - height;
 const cltvLimitErr = /cltv limit \d+ should be greater than \d+/;
@@ -24,6 +25,7 @@ const defaultMaxPaths = 1;
 const defaultTimeoutSeconds = 25;
 const hexToBuf = hex => !hex ? undefined : Buffer.from(hex, 'hex');
 const {isArray} = Array;
+const isConfidence = n => !isNaN(n) && n >= 0 && n <= 1e6;
 const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 const maxTokens = '4294967296';
 const method = 'sendPaymentV2';
@@ -42,8 +44,11 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [destination]: <Destination Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -208,6 +213,10 @@ module.exports = args => {
     throw new Error('UnexpectedCltvDeltaWhenSubscribingToPayPaymentRequest');
   }
 
+  if (args.confidence !== undefined && !isConfidence(args.confidence)) {
+    throw new Error('ExpectedConfidencePartsPerMillionForPaymentReq');
+  }
+
   if (!args.destination && !args.request) {
     throw new Error('ExpectedDestinationWhenPaymentRequestNotSpecified');
   }
@@ -378,6 +387,7 @@ module.exports = args => {
         payment_hash: !args.id ? undefined : hexToBuf(args.id),
         payment_request: !args.request ? undefined : args.request,
         route_hints: !hints.length ? undefined : hints,
+        time_pref: asTimePreference(args.confidence),
         timeout_seconds: timeoutSecs || defaultTimeoutSeconds,
       });
     }],

package/lnd_methods/offchain/subscribe_to_pay_via_details.js

@@ -17,8 +17,11 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -191,6 +194,7 @@ module.exports = args => {
 
   return subscribeToPay({
     cltv_delta: args.cltv_delta || defaultCltvDelta,
+    confidence: args.confidence,
     destination: args.destination,
     features: args.features,
     id: args.id || randomId(),

package/lnd_methods/offchain/subscribe_to_pay_via_request.js

@@ -10,7 +10,10 @@ const type = 'router';
 
   `max_path_mtokens` is not supported in LND 0.12.0 or below
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     [incoming_peer]: <Pay Through Specific Final Hop Public Key Hex String>
     lnd: <Authenticated LND API Object>
     [max_fee]: <Maximum Fee Tokens To Pay Number>
@@ -167,6 +170,7 @@ module.exports = args => {
   }
 
   return subscribeToPay({
+    confidence: args.confidence,
     incoming_peer: args.incoming_peer,
     lnd: args.lnd,
     max_fee: args.max_fee,

package/lnd_methods/offchain/subscribe_to_probe_for_route.js

@@ -20,8 +20,11 @@ const {nextTick} = process;
 
   Requires `offchain:write` permission
 
+  Preferred `confidence` is not supported on LND 0.14.3 and below
+
   {
     [cltv_delta]: <Final CLTV Delta Number>
+    [confidence]: <Preferred Route Confidence Number Out of One Million Number>
     destination: <Destination Public Key Hex String>
     [features]: [{
       bit: <Feature Bit Number>
@@ -241,6 +244,7 @@ module.exports = args => {
           return getRouteToDestination({
             mtokens,
             cltv_delta: args.cltv_delta,
+            confidence: args.confidence,
             destination: args.destination,
             features: args.features,
             ignore: ignore.concat(temporaryChannelFailures),

package/lnd_methods/signer/begin_group_signing_session.js

@@ -0,0 +1,144 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const getPublicKey = require('./../address/get_public_key');
+const {isLnd} = require('./../../lnd_requests');
+const {rpcGroupSessionAsSession} = require('./../../lnd_responses');
+
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const method = 'muSig2CreateSession';
+const type = 'signer';
+const uniq = arr => Array.from(new Set(arr));
+const unsupportedMessage = 'unknown method MuSig2CreateSession for service signrpc.Signer';
+const xOnlyPublicKeyHexLength = 64;
+const xOnlyPublicKey = hexKey => hexKey.slice(2);
+
+/** Start a MuSig2 group signing session
+
+  Requires LND built with `signrpc`, `walletrpc` build tags
+
+  Requires `address:read`, `signer:generate` permissions
+
+  This method is not supported in LND 0.14.3 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+    [is_key_spend]: <Key Is BIP 86 Key Spend Key Bool>
+    key_family: <HD Seed Key Family Number>
+    key_index: <Key Index Number>
+    public_keys: [<External Public Key Hex String>]
+    [root_hash]: <Taproot Script Root Hash Hex String>
+  }
+
+  @returns via cbk or Promise
+  {
+    external_key: <Final Script or Top Level Public Key Hex String>
+    id: <Session Id Hex String>
+    [internal_key]: <Internal Top Level Public Key Hex String>
+    nonce: <Session Compound Nonces Hex String>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToStartMuSig2Session']);
+        }
+
+        if (args.key_family === undefined) {
+          return cbk([400, 'ExpectedKeyFamilyToStartMuSig2Session']);
+        }
+
+        if (args.key_index === undefined) {
+          return cbk([400, 'ExpectedKeyIndexToStartMuSig2Session']);
+        }
+
+        if (!isArray(args.public_keys)) {
+          return cbk([400, 'ExpectedArrayOfPublicKeysForMuSig2SessionStart']);
+        }
+
+        if (!args.public_keys.length) {
+          return cbk([400, 'ExpectedOtherPublicKeysForMuSig2SessionStart']);
+        }
+
+        if (!!args.root_hash && !isHash(args.root_hash)) {
+          return cbk([400, 'ExpectedHashWhenSpecifyingMuSig2ScriptRootHash']);
+        }
+
+        return cbk();
+      },
+
+      // Get the local public key to pass it to the session along with others
+      getKey: ['validate', ({}, cbk) => {
+        return getPublicKey({
+          family: args.key_family,
+          index: args.key_index,
+          lnd: args.lnd,
+        },
+        cbk);
+      }],
+
+      // Put together the Taproot tweak flags for top level signing
+      taprootTweak: ['validate', ({}, cbk) => {
+        // Spend should include a top level Taproot script commitment proof
+        if (!!args.root_hash) {
+          return cbk(null, {script_root: hexAsBuffer(args.root_hash)});
+        }
+
+        // Spend is absent a Taproot script, but is a top-level Taproot key
+        if (!!args.is_key_spend) {
+          return cbk(null, {key_spend_only: true});
+        }
+
+        return cbk();
+      }],
+
+      // Collect all public keys taking part in the signing session
+      publicKeys: ['getKey', ({getKey}, cbk) => {
+        // Trim public keys as necessary
+        const keys = [getKey.public_key].concat(args.public_keys).map(key => {
+          if (key.length === xOnlyPublicKeyHexLength) {
+            return key;
+          }
+
+          return xOnlyPublicKey(key);
+        });
+
+        return cbk(null, uniq(keys));
+      }],
+
+      // Create the signing session
+      create: [
+        'publicKeys',
+        'taprootTweak',
+        ({publicKeys, taprootTweak}, cbk) =>
+      {
+        return args.lnd[type][method]({
+          all_signer_pubkeys: publicKeys.map(hexAsBuffer),
+          key_loc: {key_family: args.key_family, key_index: args.key_index},
+          taproot_tweak: taprootTweak,
+        },
+        (err, res) => {
+          if (!!err && err.details === unsupportedMessage) {
+            return cbk([501, 'MuSig2BeginSigningSessionNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorCreatingMuSig2Session', {err}]);
+          }
+
+          try {
+            return cbk(null, rpcGroupSessionAsSession(res));
+          } catch (err) {
+            return cbk([503, err.message]);
+          }
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'create'}, cbk));
+  });
+};

package/lnd_methods/signer/end_group_signing_session.js

@@ -0,0 +1,102 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const {isBuffer} = Buffer;
+const method = 'muSig2CombineSig';
+const type = 'signer';
+
+/** Complete a MuSig2 signing session
+
+  Requires LND built with `signrpc` build tag
+
+  Requires `signer:generate` permission
+
+  This method is not supported in LND 0.14.3 and below
+
+  {
+    id: <Session Id Hex String>
+    lnd: <Authenticated LND API Object>
+    [signatures]: [<Combine External Partial Signature Hex String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    [signature]: <Combined Signature Hex String>
+  }
+*/
+module.exports = ({id, lnd, signatures}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!id) {
+          return cbk([400, 'ExpectedSessionIdToFinishMuSig2Session']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToFinishMuSig2Session']);
+        }
+
+        if (isArray(signatures) && !signatures.length) {
+          return cbk([400, 'ExpectedPartialSignaturesToCombineToEndSession']);
+        }
+
+        return cbk();
+      },
+
+      // Close out the signing session
+      endSession: ['validate', ({}, cbk) => {
+        // Exit early when there are signatures to combine
+        if (isArray(signatures)) {
+          return cbk();
+        }
+
+        return lnd[type].muSig2Cleanup({session_id: hexAsBuffer(id)}, err => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorCleaningUpMuSig2Session', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+
+      // Update the session with signatures
+      updateSignatures: ['validate', ({}, cbk) => {
+        // Exit early when there are no signatures to update
+        if (!isArray(signatures)) {
+          return cbk(null, {});
+        }
+
+        return lnd[type][method]({
+          other_partial_signatures: signatures.map(hexAsBuffer),
+          session_id: hexAsBuffer(id),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorFinishingMuSig2Session', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForMuSig2CombineRequest']);
+          }
+
+          if (res.have_all_signatures === false) {
+            return cbk([400, 'ExpectedAllSignaturesProvidedForSession']);
+          }
+
+          if (!isBuffer(res.final_signature)) {
+            return cbk([503, 'ExpectedFinalSignatureInCombineResponse']);
+          }
+
+          return cbk(null, {signature: bufferAsHex(res.final_signature)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'updateSignatures'}, cbk));
+  });
+};

package/lnd_methods/signer/index.js

@@ -1,11 +1,17 @@
+const beginGroupSigningSession = require('./begin_group_signing_session');
 const diffieHellmanComputeSecret = require('./diffie_hellman_compute_secret');
+const endGroupSigningSession = require('./end_group_signing_session');
 const signBytes = require('./sign_bytes');
 const signTransaction = require('./sign_transaction');
+const updateGroupSigningSession = require('./update_group_signing_session');
 const verifyBytesSignature = require('./verify_bytes_signature');
 
 module.exports = {
+  beginGroupSigningSession,
   diffieHellmanComputeSecret,
+  endGroupSigningSession,
   signBytes,
   signTransaction,
+  updateGroupSigningSession,
   verifyBytesSignature,
 };

package/lnd_methods/signer/sign_transaction.js

@@ -6,6 +6,7 @@ const {isLnd} = require('./../../lnd_requests');
 const bufferAsHex = buffer => buffer.toString('hex');
 const hexAsBuffer = hex => Buffer.from(hex, 'hex');
 const {isArray} = Array;
+const isV1 = scriptHex => scriptHex.length === 68 && /5120/.test(scriptHex);
 const method = 'signOutputRaw';
 const notFound = -1;
 const type = 'signer';
@@ -64,13 +65,27 @@ module.exports = ({inputs, lnd, spending, transaction}, cbk) => {
         return cbk();
       },
 
+      // Derive the previous outputs set
+      previousOutputs: ['validate', ({}, cbk) => {
+        const outputs = [].concat(inputs).concat(spending || []).map(utxo => ({
+          pk_script: hexAsBuffer(utxo.output_script),
+          value: utxo.output_tokens,
+        }));
+
+        const v1Spends = outputs.filter(n => isV1(bufferAsHex(n.pk_script)));
+
+        // Exit early when there is no need to provide prev outs, non-taproot
+        if (!v1Spends.length) {
+          return cbk();
+        }
+
+        return cbk(null, outputs);
+      }],
+
       // Get signatures
-      signTransaction: ['validate', ({}, cbk) => {
+      signTransaction: ['previousOutputs', ({previousOutputs}, cbk) => {
         return lnd[type][method]({
-          prev_outputs: [].concat(inputs).concat(spending || []).map(utxo => ({
-            pk_script: hexAsBuffer(utxo.output_script),
-            value: utxo.output_tokens,
-          })),
+          prev_outputs: previousOutputs,
           raw_tx_bytes: hexAsBuffer(transaction),
           sign_descs: inputs.map(input => ({
             input_index: input.vin,

package/lnd_methods/signer/update_group_signing_session.js

@@ -0,0 +1,110 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const {isBuffer} = Buffer;
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const method = 'muSig2RegisterNonces';
+const type = 'signer';
+
+/** Update a MuSig2 signing session with nonces and generate a partial sig
+
+  All remote nonces are expected to be passed
+
+  Requires LND built with `signrpc` build tag
+
+  Requires `signer:generate` permission
+
+  This method is not supported in LND 0.14.3 and below
+
+  {
+    hash: <Hash to Sign Hex String>
+    id: <MuSig2 Session Id Hex String>
+    lnd: <Authenticated LND API Object>
+    nonces: [<Nonce Hex String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    signature: <Partial Signature Hex String>
+  }
+*/
+module.exports = ({hash, id, lnd, nonces}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isHash(hash)) {
+          return cbk([400, 'ExpectedHashToSignToUpdateMuSig2Session']);
+        }
+
+        if (!id) {
+          return cbk([400, 'ExpectedSessionIdToUpdateMuSig2Session']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToUpdateMuSig2Session']);
+        }
+
+        if (!isArray(nonces)) {
+          return cbk([400, 'ExpectedArrayOfNoncesToUpdateMuSig2Session']);
+        }
+
+        return cbk();
+      },
+
+      // Update the session with the nonces
+      updateNonces: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          other_signer_public_nonces: nonces.map(hexAsBuffer),
+          session_id: hexAsBuffer(id),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorUpdatingMuSig2Session', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResultOfRegisterNoncesRequest']);
+          }
+
+          if (res.have_all_nonces !== true) {
+            return cbk([400, 'ExpectedAllNoncesForRegisterNoncesRequest']);
+          }
+
+          return cbk();
+        });
+      }],
+
+      // Partially sign the digest hash
+      sign: ['updateNonces', ({}, cbk) => {
+        return lnd[type].muSig2Sign({
+          message_digest: hexAsBuffer(hash),
+          session_id: hexAsBuffer(id),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorSigningMuSig2Session', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResultForMuSig2SignRequest']);
+          }
+
+          if (!isBuffer(res.local_partial_signature)) {
+            return cbk([503, 'ExpectedPartialSignatureForMuSig2SignRequest']);
+          }
+
+          return cbk(null, {
+            signature: bufferAsHex(res.local_partial_signature),
+          });
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'sign'}, cbk));
+  });
+};

package/lnd_responses/index.js

@@ -26,6 +26,7 @@ const rpcFailedPolicyAsFail = require('./rpc_failed_policy_as_fail');
 const rpcFeesAsChannelFees = require('./rpc_fees_as_channel_fees');
 const rpcForwardAsForward = require('./rpc_forward_as_forward');
 const rpcForwardAsForwardRequest = require('./rpc_forward_as_forward_request');
+const rpcGroupSessionAsSession = require('./rpc_group_session_as_session');
 const rpcHopAsHop = require('./rpc_hop_as_hop');
 const rpcInvoiceAsInvoice = require('./rpc_invoice_as_invoice');
 const rpcNetworkAsNetworkInfo = require('./rpc_network_as_network_info');
@@ -70,6 +71,7 @@ module.exports = {
   rpcFeesAsChannelFees,
   rpcForwardAsForward,
   rpcForwardAsForwardRequest,
+  rpcGroupSessionAsSession,
   rpcHopAsHop,
   rpcInvoiceAsInvoice,
   rpcNetworkAsNetworkInfo,

package/lnd_responses/rpc_group_session_as_session.js

@@ -0,0 +1,51 @@
+const bufferAsHex = buffer => buffer.toString('hex');
+const {isBuffer} = Buffer;
+
+/** Map RPC MuSig2 Session to a MuSig2 Session
+
+  {
+    combined_key: <Combined Public Key Buffer Object>
+    local_public_nonces: <Two Concatenated Local Signer Nonces Buffer Object>
+    session_id: <Session Id Buffer Object>
+    taproot_internal_key: <Taproot Internal Public Key Buffer Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    external_key: <Final Script or Top Level Public Key Hex String>
+    id: <Session Id Hex String>
+    [internal_key]: <Internal Top Level Public Key Hex String>
+    nonce: <Session Compound Nonces Hex String>
+  }
+*/
+module.exports = args => {
+  if (!args) {
+    throw new Error('ExpectedResponseForMuSig2SessionRequest');
+  }
+
+  if (!isBuffer(args.combined_key)) {
+    throw new Error('ExpectedCombinedPublicKeyInMuSig2SessionResponse');
+  }
+
+  if (!isBuffer(args.local_public_nonces)) {
+    throw new Error('ExpectedLocalPublicNoncesInMuSig2SessionResponse');
+  }
+
+  if (!isBuffer(args.session_id)) {
+    throw new Error('ExpectedMuSig2SigningSessionIdInSessionResponse');
+  }
+
+  if (!isBuffer(args.taproot_internal_key)) {
+    throw new Error('ExpectedTaprootInternalKeyInMuSig2SessionResponse');
+  }
+
+  return {
+    external_key: bufferAsHex(args.combined_key),
+    id: bufferAsHex(args.session_id),
+    internal_key: bufferAsHex(args.taproot_internal_key) || undefined,
+    nonce: bufferAsHex(args.local_public_nonces),
+  };
+};

package/package.json

@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "@grpc/grpc-js": "1.6.7",
-    "@grpc/proto-loader": "0.6.9",
+    "@grpc/proto-loader": "0.6.12",
     "@types/express": "4.17.13",
-    "@types/node": "17.0.25",
+    "@types/node": "17.0.31",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.3",
     "async": "3.2.3",
@@ -22,7 +22,7 @@
     "bolt09": "0.2.3",
     "cbor": "8.1.0",
     "ecpair": "2.0.1",
-    "express": "4.17.3",
+    "express": "4.18.1",
     "invoices": "2.0.6",
     "psbt": "2.0.1",
     "tiny-secp256k1": "2.2.1",
@@ -33,8 +33,8 @@
     "@alexbosworth/node-fetch": "2.6.2",
     "@alexbosworth/tap": "15.0.11",
     "tsd": "0.20.0",
-    "typescript": "4.6.3",
-    "ws": "8.5.0"
+    "typescript": "4.6.4",
+    "ws": "8.6.0"
   },
   "engines": {
     "node": ">=12.20"
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "5.13.0"
+  "version": "5.15.0"
 }