paid-services 3.20.3 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Versions
 
+## Version 4.0.0
+
+- `createGroupChannel`: Add method to coordinate a channel group
+- `joinGroupChannel`: Add method to join a channel group
+
+### Breaking Changes
+
+- Node.js version 14 or higher is now required
+
+## Version 3.21.0
+
+- `manageSwap`: Add recovery for swap requests
+- `manageSwap`: Add support for experimental Lightning Loop MuSig2 Taproot swap
+
 ## Version 3.20.3
 
 - `manageGroupJoin`: Allow coordinating pair when funds are below the capacity

package/groups/create_group_channel.js

@@ -0,0 +1,184 @@
+const asyncAuto = require('async/auto');
+const asyncMap = require('async/map');
+const {getChainBalance} = require('ln-service');
+const {getIdentity} = require('ln-service');
+const {getMethods} = require('ln-service');
+const {getNodeAlias} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+const tinysecp = require('tiny-secp256k1');
+
+const assembleChannelGroup = require('./assemble_channel_group');
+
+const halfOf = n => n / 2;
+const isOdd = n => !!(n % 2);
+const join = arr => arr.join(', ');
+const maxGroupSize = 420;
+const minChannelSize = 2e4;
+const minGroupSize = 2;
+const niceName = ({alias, id}) => `${alias} ${id}`.trim();
+const signPsbtEndpoint = '/walletrpc.WalletKit/SignPsbt';
+
+/** Join a channel group
+
+  {
+    capacity: <Channel Capacity Tokens Number>
+    count: <Group Member Count Number>
+    lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
+    rate: <Opening Chain Fee Tokens Per VByte Rate Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    transaction_id: <Transaction Id Hex String>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Import ECPair library
+      ecp: async () => (await import('ecpair')).ECPairFactory(tinysecp),
+
+      // Check arguments
+      validate: cbk => {
+        if (!args.capacity) {
+          return cbk([400, 'ExpectedChannelCapacityToCreateChannelGroup']);
+        }
+
+        if (args.capacity < minChannelSize) {
+          return cbk([400, 'ExpectedCapacityGreaterThanMinSizeToCreateGroup']);
+        }
+
+        if (isOdd(args.capacity)) {
+          return cbk([400, 'ExpectedEvenChannelCapacityToCreateChannelGroup']);
+        }
+
+        if (!args.count) {
+          return cbk([400, 'ExpectedGroupSizeToCreateChannelGroup']);
+        }
+
+        if (args.count < minGroupSize || args.count > maxGroupSize) {
+          return cbk([400, 'ExpectedValidGroupSizeToCreateChannelGroup']);
+        }
+
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToCreateChannelGroup']);
+        }
+
+        if (!args.logger) {
+          return cbk([400, 'ExpectedWinstonLoggerToCreateChannelGroup']);
+        }
+
+        if (!args.rate) {
+          return cbk([400, 'ExpectedOpeningFeeRateToCreateChannelGroup']);
+        }
+
+        return cbk();
+      },
+
+      // Get the on-chain balance to sanity check group creation
+      getBalance: ['validate', ({}, cbk) => {
+        return getChainBalance({lnd: args.lnd}, cbk);
+      }],
+
+      // Get identity public key
+      getIdentity: ['validate', ({}, cbk) => getIdentity({lnd: args.lnd}, cbk)],
+
+      // Get methods to confim partial signing is supported
+      getMethods: ['validate', ({}, cbk) => getMethods({lnd: args.lnd}, cbk)],
+
+      // Sanity check the on-chain balance is reasonable to create a group
+      confirmBalance: ['getBalance', ({getBalance}, cbk) => {
+        // A pair group requires half the amount of capital
+        const isPair = args.count === minGroupSize;
+
+        if (!isPair && args.capacity > getBalance.chain_balance) {
+          return cbk([400, 'ExpectedCapacityLowerThanCurrentChainBalance']);
+        }
+
+        if (isPair && halfOf(args.capacity) > getBalance.chain_balance) {
+          return cbk([400, 'ExpectedCapacityLowerThanCurrentChainBalance']);
+        }
+
+        return cbk();
+      }],
+
+      // Make sure that partially signing a PSBT is a known method
+      confirmSigner: ['getMethods', ({getMethods}, cbk) => {
+        if (!getMethods.methods.find(n => n.endpoint === signPsbtEndpoint)) {
+          return cbk([400, 'ExpectedLndSupportingPartialPsbtSigning']);
+        }
+
+        return cbk();
+      }],
+
+      // Fund and assemble the group
+      create: [
+        'ecp',
+        'confirmBalance',
+        'confirmSigner',
+        'getBalance',
+        'getIdentity',
+        ({ecp, getIdentity}, cbk) =>
+      {
+        const coordinate = assembleChannelGroup({
+          ecp,
+          capacity: args.capacity,
+          count: args.count,
+          identity: getIdentity.public_key,
+          lnd: args.lnd,
+          rate: args.rate,
+        });
+
+        const code = getIdentity.public_key + coordinate.id;
+
+        args.logger.info({group_invite_code: code});
+
+        // The group must fill up with participants first
+        coordinate.events.once('filled', async ({ids}) => {
+          const members = ids.filter(n => n !== getIdentity.public_key);
+
+          const nodes = await asyncMap(members, async id => {
+            return niceName(await getNodeAlias({id, lnd: args.lnd}));
+          });
+
+          return args.logger.info({ready: join(nodes)});
+        });
+
+        // Once filled, members will connect with their partners
+        coordinate.events.once('connected', () => {
+          return args.logger.info({peered: true});
+        });
+
+        // Members will propose pending channels to each other
+        coordinate.events.once('proposed', () => {
+          return args.logger.info({proposed: true});
+        });
+
+        // Once all pending channels are in place, signatures will be received
+        coordinate.events.once('signed', () => {
+          return args.logger.info({signed: true});
+        });
+
+        // Finally the open channel tx will be broadcast
+        coordinate.events.once('broadcasting', broadcast => {
+          return args.logger.info({publishing: broadcast.transaction});
+        });
+
+        // After broadcasting the channels transaction needs to confirm
+        coordinate.events.once('broadcast', broadcast => {
+          coordinate.events.removeAllListeners();
+
+          return cbk(null, {transaction_id: broadcast.id});
+        });
+
+        coordinate.events.once('error', err => {
+          return cbk([503, 'UnexpectedErrorAssemblingChannelGroup', {err}]);
+        });
+
+        return;
+      }],
+    },
+    returnResult({reject, resolve, of: 'create'}, cbk));
+  });
+};

package/groups/get_join_details.js

@@ -0,0 +1,135 @@
+const asyncAuto = require('async/auto');
+const asyncRetry = require('async/retry');
+const {connectPeer} = require('ln-sync');
+const {getChainBalance} = require('ln-service');
+const {getNodeAlias} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+
+const {getGroupDetails} = require('./p2p');
+
+const coordinatorFromJoinCode = n => n.slice(0, 66);
+const groupIdFromJoinCode = n => n.slice(66);
+const interval = 500;
+const isCode = n => !!n && n.length === 98;
+const isPublicKey = n => !!n && /^0[2-3][0-9A-F]{64}$/i.test(n);
+const join = arr => arr.join(' ');
+const niceName = n => `${n.alias} ${n.id}`.trim();
+const times = 2 * 60;
+const tokensAsBigUnit = tokens => (tokens / 1e8).toFixed(8);
+
+/** Ask to confirm joining a group
+
+  {
+    code: <Group Invite Code String>
+    lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    capacity: <Channel Capacity Tokens Number>
+    coordinator: <Group Coordinator Identity Public Key Hex String>
+    count: <Group Members Count>
+    id: <Group Id Hex String>
+    rate: <Chain Fee Tokens Per VByte Number>
+  }
+*/
+module.exports = ({code, lnd, logger}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isCode(code)) {
+          return cbk([400, 'ExpectedChannelGroupInviteCodeToGetJoinDetails']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetJoinGroupDetails']);
+        }
+
+        if (!logger) {
+          return cbk([400, 'ExpectedWinstonLoggerObjectToGetJoinDetails']);
+        }
+
+        return cbk();
+      },
+
+      // Get the wallet balance to make sure there are enough funds to join
+      getBalance: ['validate', ({}, cbk) => getChainBalance({lnd}, cbk)],
+
+      // Parse the group join code
+      group: ['validate', ({}, cbk) => {
+        const coordinator = coordinatorFromJoinCode(code);
+
+        if (!isPublicKey(coordinator)) {
+          return cbk([400, 'ExpectedValidGroupJoinCodeToRequestGroupDetails']);
+        }
+
+        const id = groupIdFromJoinCode(code);
+
+        return cbk(null, {id, coordinator})
+      }],
+
+      // Connect to the coordinator
+      connect: ['group', ({group}, cbk) => {
+        return asyncRetry({interval, times}, cbk => {
+          return connectPeer({lnd, id: group.coordinator}, cbk);
+        },
+        cbk);
+      }],
+
+      // Get the coordinator node alias to log it out
+      getAlias: ['group', ({group}, cbk) => {
+        return getNodeAlias({lnd, id: group.coordinator}, cbk);
+      }],
+
+      // Get the group details from the coordinator
+      getDetails: ['group', ({group}, cbk) => {
+        return getGroupDetails({
+          lnd,
+          coordinator: group.coordinator,
+          id: group.id,
+        },
+        cbk);
+      }],
+
+      // Log the details of the group being joined
+      log: [
+        'getAlias',
+        'getBalance',
+        'getDetails',
+        ({getAlias, getBalance, getDetails}, cbk) =>
+      {
+        const coordinatedBy = `coordinated by ${niceName(getAlias)}`;
+        const members = `${getDetails.count} member group`;
+        const size = `with ${tokensAsBigUnit(getDetails.capacity)} channels`;
+        const rate = `and paying ${getDetails.rate}/vbyte chain fee`;
+
+        logger.info({joining: join([members, coordinatedBy, size, rate])});
+
+        // Check to make sure that there are on chain funds for this group
+        if (getBalance.chain_balance < getDetails.funding) {
+          return cbk([
+            400,
+            'InsufficientChainFundsAvailableToJoinGroup',
+            {chain_balance: getBalance.chain_balance},
+          ]);
+        }
+
+        return cbk();
+      }],
+
+      // Go ahead with the group join
+      join: ['getDetails', 'group', 'log', ({getDetails, group}, cbk) => {
+        return cbk(null, {
+          capacity: getDetails.capacity,
+          coordinator: group.coordinator,
+          count: getDetails.count,
+          id: group.id,
+          rate: getDetails.rate,
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'join'}, cbk));
+  });
+};

package/groups/index.js

@@ -1,3 +1,5 @@
+const createGroupChannel = require('./create_group_channel');
+const joinGroupChannel = require('./join_group_channel');
 const manageGroupJoin = require('./manage_group_join');
 
-module.exports = {manageGroupJoin};
+module.exports = {createGroupChannel, joinGroupChannel, manageGroupJoin};

package/groups/join_group_channel.js

@@ -0,0 +1,119 @@
+const asyncAuto = require('async/auto');
+const asyncMap = require('async/map');
+const {getMethods} = require('ln-service');
+const {getNodeAlias} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+
+const joinChannelGroup = require('./join_channel_group');
+const getJoinDetails = require('./get_join_details');
+
+const formatNodes = arr => arr.join(', ');
+const isCode = n => !!n && n.length === 98;
+const niceName = ({alias, id}) => `${alias} ${id}`.trim();
+const signPsbtEndpoint = '/walletrpc.WalletKit/SignPsbt';
+
+/** Join a channel group
+
+  {
+    code: <Group Invite Code String>
+    lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
+    max_rate: <Max Opening Chain Fee Tokens Per VByte Fee Rate Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    transaction_id: <Channel Funding Transaction Id Hex String>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isCode(args.code)) {
+          return cbk([400, 'ExpectedValidJoinCodeToJoinGroup']);
+        }
+
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToJoinGroup']);
+        }
+
+        if (!args.logger) {
+          return cbk([400, 'ExpectedWinstonLoggerToJoinGroupp']);
+        }
+
+        if (!args.max_rate) {
+          return cbk([400, 'ExpectedMaxOpeningFeeRateToJoinGroup']);
+        }
+
+        return cbk();
+      },
+
+      // Get methods to confim partial signing is supported
+      getMethods: ['validate', ({}, cbk) => getMethods({lnd: args.lnd}, cbk)],
+
+      // Make sure that partially signing a PSBT is valid
+      confirmSigner: ['getMethods', ({getMethods}, cbk) => {
+        if (!getMethods.methods.find(n => n.endpoint === signPsbtEndpoint)) {
+          return cbk([400, 'ExpectedLndSupportingPartialPsbtSigningToJoin']);
+        }
+
+        return cbk();
+      }],
+
+      // Decode the group invite code and get group details
+      getJoinDetails: ['confirmSigner', ({}, cbk) => {
+        return getJoinDetails({
+          code: args.code,
+          lnd: args.lnd,
+          logger: args.logger,
+        },
+        cbk);
+      }],
+
+      // Join the channel group
+      join: [
+        'confirmSigner',
+        'getMethods',
+        'getJoinDetails',
+        ({getJoinDetails}, cbk) =>
+      {
+        if (getJoinDetails.rate > args.max_rate) {
+          return cbk([400, 'ExpectedHigherMaxFeeRateToJoinGroup']);
+        }
+
+        args.logger.info({waiting_for_other_members: true});
+
+        const join = joinChannelGroup({
+          capacity: getJoinDetails.capacity,
+          coordinator: getJoinDetails.coordinator,
+          count: getJoinDetails.count,
+          id: getJoinDetails.id,
+          lnd: args.lnd,
+          rate: getJoinDetails.rate,
+        });
+
+        join.once('end', ({id}) => cbk(null, {transaction_id: id}));
+        join.once('error', err => cbk(err));
+
+        // After the group is filled the members are matched and peer up
+        join.once('peering', async ({inbound, outbound}) => {
+          const nodes = await asyncMap([inbound, outbound], async id => {
+            return niceName(await getNodeAlias({id, lnd: args.lnd}));
+          });
+
+          return args.logger.info({peering_with: formatNodes(nodes)});
+        });
+
+        // Once everyone is peered then the channel tx is made
+        join.once('publishing', ({refund, signed}) => {
+          return args.logger.info({refund, signed});
+        });
+
+        return;
+      }],
+    },
+    returnResult({reject, resolve, of: 'join'}, cbk));
+  });
+};

package/index.js

@@ -2,11 +2,13 @@ const {balancedOpenRequest} = require('./balanced');
 const {changeChannelCapacity} = require('./capacity');
 const {confirmServiceUse} = require('./client');
 const {createAnchoredTrade} = require('./trades');
+const {createGroupChannel} = require('./groups');
 const {decodeTrade} = require('./trades');
 const {encodeTrade} = require('./trades');
 const {getAnchoredTrade} = require('./trades');
 const {getServiceSchema} = require('./client');
 const {getServicesList} = require('./client');
+const {joinGroupChannel} = require('./groups');
 const {makePeerRequest} = require('./p2p');
 const {makeServiceRequest} = require('./client');
 const {manageGroupJoin} = require('./groups');
@@ -24,11 +26,13 @@ module.exports = {
   changeChannelCapacity,
   confirmServiceUse,
   createAnchoredTrade,
+  createGroupChannel,
   decodeTrade,
   encodeTrade,
   getAnchoredTrade,
   getServiceSchema,
   getServicesList,
+  joinGroupChannel,
   makePeerRequest,
   makeServiceRequest,
   manageGroupJoin,

package/package.json

@@ -13,24 +13,24 @@
     "bech32": "2.0.0",
     "bolt01": "1.2.5",
     "bolt07": "1.8.2",
-    "ecpair": "2.0.1",
-    "goldengate": "11.2.3",
-    "invoices": "2.1.0",
-    "ln-service": "53.20.0",
-    "ln-sync": "3.13.1",
+    "ecpair": "2.1.0",
+    "goldengate": "11.4.0",
+    "invoices": "2.2.0",
+    "ln-service": "54.2.0",
+    "ln-sync": "3.14.0",
     "psbt": "2.7.1",
-    "p2tr": "1.3.1",
+    "p2tr": "1.3.2",
     "tiny-secp256k1": "2.2.1"
   },
   "description": "Lightning Paid Services library",
   "devDependencies": {
     "@alexbosworth/tap": "15.0.11",
-    "ln-docker-daemons": "2.3.4",
-    "mock-lnd": "1.4.3",
+    "ln-docker-daemons": "3.1.0",
+    "mock-lnd": "1.4.4",
     "secp256k1": "4.0.3"
   },
   "engines": {
-    "node": ">=12.20"
+    "node": ">=14"
   },
   "keywords": [
     "lightning",
@@ -45,7 +45,7 @@
   },
   "scripts": {
     "integration-tests": "tap -j 2 --branches=1 --functions=1 --lines=1 --statements=1 -t 180 test/integration/*.js",
-    "test": "tap --branches=1 --functions=1 --lines=1 --statements=1 -t 60 test/actions/*.js test/balanced/*.js test/capacity/*.js test/client/*.js test/config/*.js test/p2p/*.js test/records/*.js test/respond/*.js test/server/*.js test/server/*.js test/services/*.js test/trades/*.js"
+    "test": "tap --branches=1 --functions=1 --lines=1 --statements=1 -t 60 test/actions/*.js test/balanced/*.js test/capacity/*.js test/client/*.js test/config/*.js test/p2p/*.js test/records/*.js test/respond/*.js test/server/*.js test/swaps/*.js test/services/*.js test/trades/*.js"
   },
-  "version": "3.20.3"
+  "version": "4.0.0"
 }