paid-services 3.16.3 → 3.17.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## Version 3.17.2
+
+- `manageGroupJoin`: Add method to coordinate or join a channels group
+
 ## Version 3.16.3
 
 - `manageSwap`: Add external funding, conf target setting, keysend pushes

package/groups/ask_for_group_details.js

@@ -0,0 +1,160 @@
+const asyncAuto = require('async/auto');
+const {getChainBalance} = require('ln-service');
+const {getChainFeeRate} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const defaultChannelCapacity = 5e6;
+const defaultGroupSize = 3;
+const {floor} = Math;
+const isNumber = n => !isNaN(n);
+const isOdd = n => !!(n % 2);
+const maxChannelSize = 21e14;
+const minChannelSize = 2e4;
+const maxGroupSize = 420;
+const minGroupSize = 3;
+const {round} = Math;
+
+/** Ask for new group details to create a group
+
+  {
+    ask: <Ask Function>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    capacity: <Channel Capacity Tokens Number>
+    count: <Group Members Number>
+    rate: <Chain Fee Tokens Per VByte Number>
+  }
+*/
+module.exports = ({ask, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!ask) {
+          return cbk([400, 'ExpectedAskFunctionToAskForGroupDetails']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToAskForGroupDetails']);
+        }
+
+        return cbk();
+      },
+
+      // Get the wallet balance to make sure there are enough funds to join
+      getBalance: ['validate', ({}, cbk) => getChainBalance({lnd}, cbk)],
+
+      // Ask for how big the channels should be
+      askForCapacity: ['getBalance', ({getBalance}, cbk) => {
+        return ask({
+          default: defaultChannelCapacity,
+          name: 'capacity',
+          message: 'Channel capacity?',
+          validate: input => {
+            if (!input || !isNumber(input)) {
+              return false;
+            }
+
+            if (round(Number(input)) !== Number(input)) {
+              return false;
+            }
+
+            if (Number(input) > getBalance.chain_balance) {
+              return `Current chain balance is ${getBalance.chain_balance}`;
+            }
+
+            if (Number(input) < minChannelSize) {
+              return `Minimum channel size is ${minChannelSize}`;
+            }
+
+            if (isOdd(Number(input))) {
+              return 'Channel capacity must be even';
+            }
+
+            return true;
+          },
+        },
+        ({capacity}) => cbk(null, Number(capacity)));
+      }],
+
+      // Get the chain fee rate to use for a default in the chain fee query
+      getFeeRate: ['validate', ({}, cbk) => getChainFeeRate({lnd}, cbk)],
+
+      // Ask for how many group members there should be
+      askForCount: ['askForCapacity', ({askForCapacity}, cbk) => {
+        return ask({
+          default: defaultGroupSize,
+          name: 'size',
+          message: 'Total number of group members?',
+          validate: input => {
+            if (!input || !isNumber(input)) {
+              return false;
+            }
+
+            // Do not allow fractional members
+            if (round(Number(input)) !== Number(input)) {
+              return false;
+            }
+
+            // Do not allow too many members
+            if (Number(input) > maxGroupSize) {
+              return `The maximum group size is ${maxGroupSize}`;
+            }
+
+            // Do not allow too few members
+            if (Number(input) < minGroupSize) {
+              return `The minimum group size is ${minGroupSize}`;
+            }
+
+            return true;
+          },
+        },
+        ({size}) => cbk(null, size));
+      }],
+
+      // Ask for a chain fee rate
+      askForFeeRate: [
+        'askForCount',
+        'getFeeRate',
+        ({askForCount, getFeeRate}, cbk) =>
+      {
+        return ask({
+          default: floor(getFeeRate.tokens_per_vbyte),
+          name: 'rate',
+          message: 'Chain fee per vbyte?',
+          validate: input => {
+            if (!input || !isNumber(input) || !Number(input)) {
+              return false;
+            }
+
+            // Do not allow fractional fee rates
+            if (round(Number(input)) !== Number(input)) {
+              return 'Fractional fee rate setting is not supported';
+            }
+
+            return true;
+          },
+        },
+        ({rate}) => cbk(null, rate));
+      }],
+
+      // Final group details
+      group: [
+        'askForCapacity',
+        'askForCount',
+        'askForFeeRate',
+        ({askForCapacity, askForCount, askForFeeRate}, cbk) =>
+      {
+        return cbk(null, {
+          capacity: askForCapacity,
+          count: askForCount,
+          rate: askForFeeRate,
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'group'}, cbk));
+  });
+};

package/groups/ask_to_confirm_group_join.js

@@ -0,0 +1,140 @@
+const asyncAuto = require('async/auto');
+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 isCode = n => !!n && n.length === 98;
+const isPublicKey = n => !!n && /^0[2-3][0-9A-F]{64}$/i.test(n);
+const niceName = n => `${n.alias} ${n.id}`.trim();
+const tokensAsBigUnit = tokens => (tokens / 1e8).toFixed(8);
+
+/** Ask to confirm joining a group
+
+  {
+    ask: <Ask Function>
+    lnd: <Authenticated LND API 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 = ({ask, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!ask) {
+          return cbk([400, 'ExpectedAskFunctionToConfirmGroupJoin']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToConfirmGroupJoin']);
+        }
+
+        return cbk();
+      },
+
+      // Ask for the group entry code
+      askForCode: ['validate', ({}, cbk) => {
+        return ask({
+          name: 'code',
+          message: 'Enter a group join code to join a group',
+          validate: input => !!isCode(input),
+        },
+        ({code}) => cbk(null, code));
+      }],
+
+      // 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: ['askForCode', ({askForCode}, cbk) => {
+        const coordinator = coordinatorFromJoinCode(askForCode);
+
+        if (!isPublicKey(coordinator)) {
+          return cbk([400, 'ExpectedValidGroupJoinCodeToRequestGroupDetails']);
+        }
+
+        const id = groupIdFromJoinCode(askForCode);
+
+        return cbk(null, {id, coordinator})
+      }],
+
+      // Connect to the coordinator
+      connect: ['group', ({group}, cbk) => {
+        return connectPeer({lnd, id: group.coordinator}, cbk);
+      }],
+
+      // Get the coordinator node alias
+      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);
+      }],
+
+      // Confirm the group join
+      ok: [
+        'getAlias',
+        'getBalance',
+        'getDetails',
+        ({getAlias, getBalance, getDetails}, cbk) =>
+      {
+        // Check to make sure that there are on chain funds for this group
+        if (getBalance.chain_balance < getDetails.capacity) {
+          return cbk([
+            400,
+            'InsufficientChainFundsAvailableToJoinGroup',
+            {channel_capacity: tokensAsBigUnit(getDetails.capacity)},
+          ]);
+        }
+
+        const coordinatedBy = `coordinated by ${niceName(getAlias)}`;
+        const members = `${getDetails.count} member group`;
+        const size = `with ${tokensAsBigUnit(getDetails.capacity)} channels`;
+        const rate = `${getDetails.rate}/vbyte chain fee`;
+
+        return ask({
+          name: 'join',
+          message: `Join ${members} ${size} at ${rate}, ${coordinatedBy}?`,
+          type: 'confirm',
+        },
+        ({join}) => cbk(null, join));
+      }],
+
+      // Go ahead with the group join
+      join: ['getDetails', 'group', 'ok', ({getDetails, group, ok}, cbk) => {
+        if (!ok) {
+          return cbk([400, 'CanceledGroupChannelJoin']);
+        }
+
+        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/assemble/assemble_unsigned_psbt.js

@@ -0,0 +1,169 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+const {createPsbt} = require('psbt');
+const {extendPsbt} = require('psbt');
+const tinysecp = require('tiny-secp256k1');
+const {Transaction} = require('bitcoinjs-lib');
+
+const {ceil} = Math;
+const dummyEcdsaSignature = Buffer.alloc(74);
+const dummyPublicKey = Buffer.alloc(33);
+const dummySchnorrSignature = Buffer.alloc(64);
+const dustValue = 330;
+const flatten = arr => [].concat(...arr);
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const isP2tr = n => n.startsWith('5120') && n.length === 68;
+const isP2wpkh = n => n.startsWith('0014') && n.length === 44;
+const {random} = Math;
+const sumOf = arr => arr.reduce((sum, n) => sum + n, 0);
+
+/** Assemble group channel unsigned PSBT
+
+  {
+    capacity: <Channel Capacity Tokens Number>
+    proposed: [{
+      [change]: <Change Output Hex String>
+      funding: <Funding Output Hex String>
+      utxos: [{
+        [non_witness_utxo]: <Spending Transaction Hex String>
+        transaction_id: <Transaction Id Hex String>
+        transaction_vout: <Transaction Output Index Number>
+        witness_utxo: {
+          script_pub: <Witness Output Script Hex String>
+          tokens: <Tokens Number>
+        }
+      }]
+    }]
+    rate: <Fee Rate Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    psbt: <Unsigned Funding Transaction PSBT Hex String>
+  }
+*/
+module.exports = ({capacity, proposed, rate}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Import ECPair library
+      ecp: async () => (await import('ecpair')).ECPairFactory(tinysecp),
+
+      // Check arguments
+      validate: cbk => {
+        if (!capacity) {
+          return cbk([400, 'ExpectedCapacityToAssembleUnsignedPsbt']);
+        }
+
+        if (!isArray(proposed)) {
+          return cbk([400, 'ExpectedChannelProposalsToAssembleUnsignedPsbt']);
+        }
+
+        if (!rate) {
+          return cbk([400, 'ExpectedChainFeeRateToAssembleUnsignedPsbt']);
+        }
+
+        return cbk();
+      },
+
+      // Derive funding transaction outputs
+      outputs: ['validate', ({}, cbk) => {
+        // Create a dummy tx to use for looking at vsize contributions
+        const tx = new Transaction();
+
+        // A tx has some base wrapper vbytes to pay for
+        const startSize = tx.virtualSize();
+
+        // Members should split the cost of the wrapper bytes
+        const wrapperShare = ceil(startSize / proposed.length);
+
+        const outputs = proposed.map(member => {
+          const tare = tx.virtualSize();
+
+          const inputsOffset = tx.ins.length;
+
+          [member.change, member.funding].filter(n => !!n).forEach(out => {
+            return tx.addOutput(hexAsBuffer(out), capacity);
+          });
+
+          member.utxos.forEach(utxo => {
+            return tx.addInput(
+              hexAsBuffer(utxo.transaction_id),
+              utxo.transaction_vout
+            );
+          });
+
+          member.utxos.forEach((utxo, i) => {
+            // Set a dummy signature stack on the input
+            if (isP2wpkh(utxo.witness_utxo.script_pub)) {
+              return tx.setWitness(
+                i + inputsOffset,
+                [dummyPublicKey, dummyEcdsaSignature]
+              );
+            }
+
+            if (isP2tr(utxo.witness_utxo.script_pub)) {
+              return tx.setWitness(i + inputsOffset, [dummySchnorrSignature]);
+            }
+
+            throw new Error('UnsupportedOutputType');
+          });
+
+          const vbytes = tx.virtualSize() - tare + wrapperShare;
+
+          const funded = sumOf(member.utxos.map(n => n.witness_utxo.tokens));
+
+          return [
+            {
+              script: member.funding,
+              tokens: capacity,
+            },
+            {
+              script: member.change,
+              tokens: funded - capacity - (vbytes * rate),
+            },
+          ];
+        });
+
+        // Collect outputs and shuffle them
+        const finalOutputs = flatten(outputs).filter(n => !!n.script)
+          .map(value => ({value, sort: random()}))
+          .sort((a, b) => a.sort - b.sort)
+          .map(({value}) => value);
+
+        return cbk(null, finalOutputs);
+      }],
+
+      // Assemble the funding for the group channel
+      funding: ['ecp', 'outputs', ({ecp, outputs}, cbk) => {
+        // Put together all inputs funding the transaction, shuffle inputs
+        const utxos = flatten(proposed.map(n => n.utxos))
+          .map(utxo => ({
+            id: utxo.transaction_id,
+            non_witness_utxo: utxo.non_witness_utxo,
+            vout: utxo.transaction_vout,
+            witness_utxo: utxo.witness_utxo,
+          }))
+          .map(value => ({value, sort: random()}))
+          .sort((a, b) => a.sort - b.sort)
+          .map(({value}) => value);
+
+        // Setup a baseline PSBT with the inputs and outputs
+        const fundingBase = createPsbt({outputs, utxos});
+
+        // Extend the base PSBT with the UTXO metadata
+        const extended = extendPsbt({
+          ecp,
+          inputs: utxos.map(utxo => ({
+            non_witness_utxo: utxo.non_witness_utxo,
+            witness_utxo: utxo.witness_utxo,
+          })),
+          psbt: fundingBase.psbt,
+        });
+
+        return cbk(null, {psbt: extended.psbt});
+      }],
+    },
+    returnResult({reject, resolve, of: 'funding'}, cbk));
+  });
+};