lightning 5.14.0 → 5.15.0

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/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.14.0"
+  "version": "5.15.0"
 }

package/test/lnd_methods/signer/test_begin_group_signing_session.js

@@ -0,0 +1,134 @@
+const {test} = require('@alexbosworth/tap');
+
+const {beginGroupSigningSession} = require('./../../../');
+
+const makeLnd = (err, res) => {
+  return {
+    signer: {
+      muSig2CreateSession: ({}, cbk) => cbk(err, res)
+    },
+    wallet: {
+      deriveKey: ({}, cbk) => cbk(null, {
+        key_loc: {key_index: 0},
+        raw_key_bytes: Buffer.alloc(1),
+      }),
+    },
+  };
+};
+
+const makeArgs = override => {
+  const args = {
+    lnd: makeLnd(null, {
+      combined_key: Buffer.alloc(32),
+      local_public_nonces: Buffer.alloc(66),
+      session_id: Buffer.alloc(32),
+      taproot_internal_key: Buffer.alloc(0),
+    }),
+    key_family: 0,
+    key_index: 0,
+    public_keys: [Buffer.alloc(33, 2).toString('hex')],
+  };
+
+  Object.keys(override || {}).forEach(key => args[key] = override[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND object is required',
+    error: [400, 'ExpectedAuthenticatedLndToStartMuSig2Session'],
+  },
+  {
+    args: makeArgs({key_family: undefined}),
+    description: 'A key family is required',
+    error: [400, 'ExpectedKeyFamilyToStartMuSig2Session'],
+  },
+  {
+    args: makeArgs({key_index: undefined}),
+    description: 'The key index is required',
+    error: [400, 'ExpectedKeyIndexToStartMuSig2Session'],
+  },
+  {
+    args: makeArgs({public_keys: undefined}),
+    description: 'Public keys are required',
+    error: [400, 'ExpectedArrayOfPublicKeysForMuSig2SessionStart'],
+  },
+  {
+    args: makeArgs({public_keys: []}),
+    description: 'Remote public keys are required',
+    error: [400, 'ExpectedOtherPublicKeysForMuSig2SessionStart'],
+  },
+  {
+    args: makeArgs({root_hash: 'root_hash'}),
+    description: 'Root hash must be valid',
+    error: [400, 'ExpectedHashWhenSpecifyingMuSig2ScriptRootHash'],
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({
+        details: 'unknown method MuSig2CreateSession for service signrpc.Signer',
+      }),
+    }),
+    description: 'MuSig2 must be supported',
+    error: [501, 'MuSig2BeginSigningSessionNotSupported'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd('err')}),
+    description: 'Unexpected errors are passed back',
+    error: [503, 'UnexpectedErrorCreatingMuSig2Session', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd(null, {})}),
+    description: 'A valid response is expected',
+    error: [503, 'ExpectedCombinedPublicKeyInMuSig2SessionResponse'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'A group signing session is started',
+    expected: {
+      external_key: '0000000000000000000000000000000000000000000000000000000000000000',
+      id: '0000000000000000000000000000000000000000000000000000000000000000',
+      internal_key: undefined,
+      nonce: '000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+    },
+  },
+  {
+    args: makeArgs({
+      public_keys: [Buffer.alloc(32, 1).toString('hex')],
+      root_hash: Buffer.alloc(32).toString('hex'),
+    }),
+    description: 'A group signing session is started with a root hash',
+    expected: {
+      external_key: '0000000000000000000000000000000000000000000000000000000000000000',
+      id: '0000000000000000000000000000000000000000000000000000000000000000',
+      internal_key: undefined,
+      nonce: '000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+    },
+  },
+  {
+    args: makeArgs({is_key_spend: true}),
+    description: 'A group signing session is started with a key spend',
+    expected: {
+      external_key: '0000000000000000000000000000000000000000000000000000000000000000',
+      id: '0000000000000000000000000000000000000000000000000000000000000000',
+      internal_key: undefined,
+      nonce: '000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(beginGroupSigningSession(args), error, 'Got expected err');
+    } else {
+      const res = await beginGroupSigningSession(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/signer/test_diffie_hellman_compute_secret.js

@@ -33,7 +33,9 @@ const tests = [
       override: {
         lnd: {
           signer: {
-            deriveSharedKey: ({}, cbk) => cbk({details: 'unknown service signrpc.Signer'}),
+            deriveSharedKey: ({}, cbk) => cbk({
+              details: 'unknown service signrpc.Signer',
+            }),
           },
         },
       },

package/test/lnd_methods/signer/test_end_group_signing_session.js

@@ -0,0 +1,93 @@
+const {test} = require('@alexbosworth/tap');
+
+const {endGroupSigningSession} = require('./../../../');
+
+const makeLnd = ({cleanErr, combineErr, combineRes}) => {
+  return {
+    signer: {
+      muSig2Cleanup: ({}, cbk) => cbk(cleanErr),
+      muSig2CombineSig: ({}, cbk) => cbk(combineErr, combineRes),
+    },
+  };
+};
+
+const makeArgs = override => {
+  const args = {
+    id: Buffer.alloc(32).toString('hex'),
+    lnd: makeLnd({combineRes: {final_signature: Buffer.alloc(64)}}),
+    signatures: [Buffer.alloc(64).toString('hex')],
+  };
+
+  Object.keys(override || {}).forEach(key => args[key] = override[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({id: undefined}),
+    description: 'A session id is required',
+    error: [400, 'ExpectedSessionIdToFinishMuSig2Session'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'An authenticated lnd is required',
+    error: [400, 'ExpectedAuthenticatedLndToFinishMuSig2Session'],
+  },
+  {
+    args: makeArgs({signatures: []}),
+    description: 'Signatures are required',
+    error: [400, 'ExpectedPartialSignaturesToCombineToEndSession'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({cleanErr: 'err'}), signatures: undefined}),
+    description: 'A cleanup error is passed back',
+    error: [503, 'UnexpectedErrorCleaningUpMuSig2Session', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({combineErr: 'err'})}),
+    description: 'A combine error is passed back',
+    error: [503, 'UnexpectedErrorFinishingMuSig2Session', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({combineRes: null})}),
+    description: 'A combine response is expected',
+    error: [503, 'ExpectedResponseForMuSig2CombineRequest'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({combineRes: {have_all_signatures: false}})}),
+    description: 'A combine success response is expected',
+    error: [400, 'ExpectedAllSignaturesProvidedForSession'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({combineRes: {}})}),
+    description: 'A combined signature is expected',
+    error: [503, 'ExpectedFinalSignatureInCombineResponse'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'A group signing session is ended',
+    expected: {
+      signature: '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+    },
+  },
+  {
+    args: makeArgs({signatures: undefined}),
+    description: 'A group signing session is canceled',
+    expected: {},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(endGroupSigningSession(args), error, 'Got expected err');
+    } else {
+      const res = await endGroupSigningSession(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/signer/test_update_group_signing_session.js

@@ -0,0 +1,108 @@
+const {test} = require('@alexbosworth/tap');
+
+const {updateGroupSigningSession} = require('./../../../');
+
+const makeLnd = ({noncesErr, noncesRes, signErr, signRes}) => {
+  return {
+    signer: {
+      muSig2RegisterNonces: ({}, cbk) => cbk(noncesErr, noncesRes),
+      muSig2Sign: ({}, cbk) => cbk(signErr, signRes),
+    },
+  };
+};
+
+const makeArgs = override => {
+  const args = {
+    hash: Buffer.alloc(32).toString('hex'),
+    id: Buffer.alloc(32).toString('hex'),
+    lnd: makeLnd({
+      noncesRes: {have_all_nonces: true},
+      signRes: {local_partial_signature: Buffer.alloc(64)},
+    }),
+    nonces: [Buffer.alloc(66).toString('hex')],
+  };
+
+  Object.keys(override || {}).forEach(key => args[key] = override[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({hash: undefined}),
+    description: 'A hash to sign is required',
+    error: [400, 'ExpectedHashToSignToUpdateMuSig2Session'],
+  },
+  {
+    args: makeArgs({id: undefined}),
+    description: 'A signing group id is required',
+    error: [400, 'ExpectedSessionIdToUpdateMuSig2Session'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND object is required',
+    error: [400, 'ExpectedAuthenticatedLndToUpdateMuSig2Session'],
+  },
+  {
+    args: makeArgs({nonces: undefined}),
+    description: 'Nonces are required',
+    error: [400, 'ExpectedArrayOfNoncesToUpdateMuSig2Session'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({noncesErr: 'err'})}),
+    description: 'Update nonces errors are passed back',
+    error: [503, 'UnexpectedErrorUpdatingMuSig2Session', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({noncesRes: null})}),
+    description: 'An update response is expected',
+    error: [503, 'ExpectedResultOfRegisterNoncesRequest'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({noncesRes: {}})}),
+    description: 'A successful update response is expected',
+    error: [400, 'ExpectedAllNoncesForRegisterNoncesRequest'],
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({noncesRes: {have_all_nonces: true}, signErr: 'err'}),
+    }),
+    description: 'Sign errors are passed back',
+    error: [503, 'UnexpectedErrorSigningMuSig2Session', {err: 'err'}],
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({noncesRes: {have_all_nonces: true}, signRes: null}),
+    }),
+    description: 'Sign response is expected',
+    error: [503, 'ExpectedResultForMuSig2SignRequest'],
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({noncesRes: {have_all_nonces: true}, signRes: {}}),
+    }),
+    description: 'A partial signature is expected',
+    error: [503, 'ExpectedPartialSignatureForMuSig2SignRequest'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'A group signing session is updated',
+    expected: {
+      signature: '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(updateGroupSigningSession(args), error, 'Got expected err');
+    } else {
+      const res = await updateGroupSigningSession(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});