lightning 5.14.0 → 5.15.2

package/lnd_methods/peers/update_color.d.ts

@@ -0,0 +1,11 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript/shared';
+
+export type UpdateColorArgs = AuthenticatedLightningArgs<{
+  /** Node Color String */
+  color: string;
+}>;
+
+export const updateColor: AuthenticatedLightningMethod<UpdateColorArgs>;

package/lnd_methods/signer/begin_group_signing_session.d.ts

@@ -0,0 +1,33 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript/shared';
+
+export type BeginGroupSigningSessionArgs = AuthenticatedLightningArgs<{
+  /** Key Is BIP 86 Key Spend Key Bool */
+  is_key_spend?: boolean;
+  /** HD Seed Key Family Number */
+  key_family: number;
+  /** Key Index Number */
+  key_index: number;
+  /** External Public Key Hex String */
+  public_keys: string[];
+  /** Taproot Script Root Hash Hex String */
+  root_hash?: string;
+}>;
+
+export type BeginGroupSigningSessionResult = {
+  /** Final Script or Top Level Public Key Hex String */
+  external_key: string;
+  /** Session Id Hex String */
+  id: string;
+  /** Internal Top Level Public Key Hex String */
+  internal_key?: string;
+  /** Session Compound Nonces Hex String */
+  nonce: string;
+};
+
+export const beginGroupSigningSession: AuthenticatedLightningMethod<
+  BeginGroupSigningSessionArgs,
+  BeginGroupSigningSessionResult
+>;

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.d.ts

@@ -0,0 +1,21 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript/shared';
+
+export type EndGroupSigningSessionArgs = AuthenticatedLightningArgs<{
+  /** Session Id Hex String */
+  id: string;
+  /** Combine External Partial Signature Hex Strings */
+  signatures?: string[];
+}>;
+
+export type EndGroupSigningSessionResult = {
+  /** Combined Signature Hex String */
+  signature?: string;
+};
+
+export const endGroupSigningSession: AuthenticatedLightningMethod<
+  EndGroupSigningSessionArgs,
+  EndGroupSigningSessionResult
+>;

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.d.ts

@@ -1,4 +1,7 @@
+export * from './begin_group_signing_session';
 export * from './diffie_hellman_compute_secret';
+export * from './end_group_signing_session';
 export * from './sign_bytes';
 export * from './sign_transaction';
+export * from './update_group_signing_session';
 export * from './verify_bytes_signature';

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/update_group_signing_session.d.ts

@@ -0,0 +1,23 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript/shared';
+
+export type UpdateGroupSigningSessionArgs = AuthenticatedLightningArgs<{
+  /** Hash to Sign Hex String */
+  hash: string;
+  /** MuSig2 Session Id Hex String */
+  id: string;
+  /** Nonce Hex Strings */
+  nonces: string[];
+}>;
+
+export type UpdateGroupSigningSessionResult = {
+  /** Partial Signature Hex String */
+  signature: string;
+};
+
+export const updateGroupSigningSession: AuthenticatedLightningMethod<
+  UpdateGroupSigningSessionArgs,
+  UpdateGroupSigningSessionResult
+>;

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_attempt_htlc_as_attempt.js

@@ -61,7 +61,9 @@ const nsAsMs = ns => Number(BigInt(ns) / BigInt(1e6));
 
   @returns
   {
-    confirmed_at: <Payment Succeeded At ISO 8601 Date String>
+    [confirmed_at]: <Payment Attempt Succeeded At ISO 8601 Date String>
+    created_at: <Attempt Was Started At ISO 8601 Date String>
+    [failed_at]: <Payment Attempt Failed At ISO 8601 Date String>
     is_confirmed: <Payment Attempt Succeeded Bool>
     is_failed: <Payment Attempt Failed Bool>
     is_pending: <Payment Attempt is Waiting For Resolution Bool>
@@ -91,6 +93,10 @@ module.exports = attempt => {
     throw new Error('ExpectedRpcAttemptDetailsToDeriveAttempt');
   }
 
+  if (!attempt.attempt_time_ns) {
+    throw new Error('ExpectedRpcAttemptStartTimeNs');
+  }
+
   if (!attempt.resolve_time_ns) {
     throw new Error('ExpectedRpcAttemptResolveTimeNs');
   }
@@ -103,11 +109,39 @@ module.exports = attempt => {
     throw new Error('ExpectedAttemptStatusInRpcAttemptDetails');
   }
 
+  const route = rpcRouteAsRoute(attempt.route);
+
+  if (attempt.status === attemptStates.confirmed) {
+    return {
+      route,
+      confirmed_at: new Date(nsAsMs(attempt.resolve_time_ns)).toISOString(),
+      created_at: new Date(nsAsMs(attempt.attempt_time_ns)).toISOString(),
+      failed_at: undefined,
+      is_confirmed: true,
+      is_failed: false,
+      is_pending: false,
+    };
+  }
+
+  if (attempt.status === attemptStates.failed) {
+    return {
+      route,
+      confirmed_at: undefined,
+      created_at: new Date(nsAsMs(attempt.attempt_time_ns)).toISOString(),
+      failed_at: new Date(nsAsMs(attempt.resolve_time_ns)).toISOString(),
+      is_confirmed: false,
+      is_failed: true,
+      is_pending: false,
+    };
+  }
+
   return {
-    confirmed_at: new Date(nsAsMs(attempt.resolve_time_ns)).toISOString(),
-    is_confirmed: attempt.status === attemptStates.confirmed,
-    is_failed: attempt.status === attemptStates.failed,
+    route,
+    confirmed_at: undefined,
+    created_at: new Date(nsAsMs(attempt.attempt_time_ns)).toISOString(),
+    failed_at: undefined,
+    is_confirmed: false,
+    is_failed: false,
     is_pending: attempt.status === attemptStates.pending,
-    route: rpcRouteAsRoute(attempt.route),
   };
 };

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/lnd_responses/rpc_payment_as_payment.js

@@ -81,6 +81,9 @@ const routePublicKeys = route => route.hops.map(n => n.public_key);
   @returns
   {
     attempts: [{
+      [confirmed_at]: <Payment Attempt Succeeded At ISO 8601 Date String>
+      created_at: <Attempt Was Started At ISO 8601 Date String>
+      [failed_at]: <Payment Attempt Failed At ISO 8601 Date String>
       [failure]: {
         code: <Error Type Code Number>
         [details]: {
@@ -108,6 +111,9 @@ const routePublicKeys = route => route.hops.map(n => n.public_key);
         }
         message: <Error Message String>
       }
+      [confirmed_at]: <Payment Attempt Succeeded At ISO 8601 Date String>
+      created_at: <Attempt Was Started At ISO 8601 Date String>
+      [failed_at]: <Payment Attempt Failed At ISO 8601 Date String>
       is_confirmed: <Payment Attempt Succeeded Bool>
       is_failed: <Payment Attempt Failed Bool>
       is_pending: <Payment Attempt is Waiting For Resolution Bool>

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.32",
     "@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.14.0"
+  "version": "5.15.2"
 }