paid-services 3.2.0 → 3.3.0

package/capacity/assemble_replacement_tx.js

@@ -0,0 +1,171 @@
+const {address} = require('bitcoinjs-lib');
+const {networks} = require('bitcoinjs-lib');
+const {Transaction} = require('bitcoinjs-lib');
+
+const isOpenWitnessScript = require('./is_open_witness_script');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const {fromHex} = Transaction;
+const hashFromTxId = id => Buffer.from(id, 'hex').reverse();
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const sequence = 0;
+const {toOutputScript} = address;
+
+/** Put together the replacement transaction
+
+  {
+    [add_funds_transaction_id]: <Add Funds Transaction Id Hex String>
+    [add_funds_transaction_vout]: <Add Funds Transaction Output Index Number>
+    bitcoinjs_network: <BitcoinJs Network Name String>
+    close_transaction: <Force Closed Transaction Hex String>
+    decrease: [{
+      output: <Output Script Hex Encoded String>
+      tokens: <Decrease By Tokens Number>
+    }]
+    funding_address: <Replacement Channel Funding Address String>
+    funding_tokens: <Replacement Channel Funding Tokens Number>
+    transaction_id: <Original Channel Funding Transaction Id Hex String>
+    transaction_vout: <Original Channel Funding Output Index Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [add_funds_vin]: <Add Funds Input Index>
+    transaction: <Unsigned Transaction Hex String>
+    transaction_id: <Transaction Id Hex String>
+    transaction_vin: <Input Index of Original Channel Spend Number>
+    transaction_vout: <Replacement Channel Transaction Output Index Number>
+  }
+*/
+module.exports = args => {
+  if (!args.bitcoinjs_network) {
+    throw new Error('ExpectedBitcoinJsNetworkNameToAssembleReplacementTx');
+  }
+
+  if (!args.close_transaction) {
+    throw new Error('ExpectedCloseTransactionToAssembleReplacementTx');
+  }
+
+  if (!isArray(args.decrease)) {
+    throw new Error('ExpectedArrayOfDecreasesToAssembleReplacementTx');
+  }
+
+  if (!args.funding_address) {
+    throw new Error('ExpectedFundingAddressToAssembleReplacementTx');
+  }
+
+  if (!args.funding_tokens) {
+    throw new Error('ExpectedFundingTokensToAssembleReplacementTx');
+  }
+
+  if (!args.transaction_id) {
+    throw new Error('ExpectedFundingTransactionIdToAssembleReplacementTx');
+  }
+
+  if (args.transaction_vout === undefined) {
+    throw new Error('ExpectedFundingTransactionVoutToAssembleReplacementTx');
+  }
+
+  const replacement = new Transaction();
+
+  // The replacement will spend the same input as the close transaction
+  const [{witness}, secondInput] = fromHex(args.close_transaction).ins;
+
+  // Confirm that the witness stack is a 2:2
+  if (!isOpenWitnessScript({script: bufferAsHex(witness.slice().pop())})) {
+    throw new Error('ExpectedMultiSigWitnessInCloseTransaction');
+  }
+
+  if (!!secondInput) {
+    throw new Error('ExpectedOnlySingleInputForCloseTransaction');
+  }
+
+  // The replacement will spend the funding outpoint
+  const hash = hashFromTxId(args.transaction_id);
+  const index = args.transaction_vout;
+
+  // The new channel multi-sig will be the replacement output
+  const network = networks[args.bitcoinjs_network];
+
+  // The replacement spends to the channel funding output
+  const fundingOutput = {
+    script: toOutputScript(args.funding_address, network),
+    tokens: args.funding_tokens,
+  };
+
+  // There can also be other outputs attached
+  const decreaseOutputs = args.decrease.map(({output, tokens}) => ({
+    tokens,
+    script: hexAsBuffer(output),
+  }));
+
+  const outputs = [].concat(decreaseOutputs).concat(fundingOutput);
+
+  // Sort outputs by BIP 69
+  outputs.sort((a, b) => {
+    // Sort by tokens ascending when no tie breaker needed
+    if (a.tokens !== b.tokens) {
+      return a.tokens - b.tokens;
+    }
+
+    // Otherwise compare output scripts lexicographically ascending
+    return a.script.compare(b.script);
+  });
+
+  const respendOutputIndex = outputs.findIndex(out => {
+    return out.script.equals(fundingOutput.script);
+  });
+
+  // Add the outputs to the replacement transaction
+  outputs.forEach(({script, tokens}) => replacement.addOutput(script, tokens));
+
+  // Exit early when not adding more inputs to the transaction
+  if (!args.add_funds_transaction_id) {
+    replacement.addInput(hash, index, sequence);
+
+    return {
+      transaction: replacement.toHex(),
+      transaction_id: replacement.getId(),
+      transaction_vin: replacement.ins.findIndex(input => {
+        return input.hash.equals(hash) && input.index === index;
+      }),
+      transaction_vout: respendOutputIndex,
+    };
+  }
+
+  // An additional input needs to be added when adding funds
+  const add = {
+    hash: hashFromTxId(args.add_funds_transaction_id),
+    index: args.add_funds_transaction_vout,
+  };
+
+  // Adding funds means spending the channel output plus the transit one
+  const spends = [{hash, index}, add];
+
+  // Sort the spending inputs for BIP 69
+  spends.sort((a, b) => {
+    const aHash = bufferAsHex(a.hash);
+    const bHash = bufferAsHex(b.hash);
+
+    return aHash.localeCompare(bHash) || a.index - b.index;
+  });
+
+  // Add the spends as inputs to the replacement tx
+  spends.forEach(({hash, index}) => replacement.addInput(hash, index));
+
+  return {
+    add_funds_vin: replacement.ins.findIndex(input => {
+      return input.hash.equals(add.hash) && input.index === add.index;
+    }),
+    transaction: replacement.toHex(),
+    transaction_id: replacement.getId(),
+    transaction_vin: replacement.ins.findIndex(input => {
+      return input.hash.equals(hash) && input.index === index;
+    }),
+    transaction_vout: respendOutputIndex,
+  };
+};

package/capacity/capacity_change_requests.js

@@ -0,0 +1,76 @@
+/** Map change requests to requests considering local channels
+
+  {
+    channels: [{
+      capacity: <Channel Capacity Number>
+      [cooperative_close_address]: <Cooperative Close Locked Address String>
+      id: <Standard Format Channel Id String>
+      partner_public_key: <Peer Public Key Hex String>
+    }]
+    requests: [{
+      channel: <Standard Format Channel Id String>
+      [decrease]: <Reduce Capacity Tokens Number>
+      from: <From Node Public Key Id Hex String>
+      id: <Change Request Id Hex String>
+      [increase]: <Add Capacity Tokens Number>
+    }]
+  }
+
+  @returns
+  {
+    requests: [{
+      [address]: <Cooperative Close Address String>
+      capacity: <Channel Capacity Tokens Number>
+      channel: <Standard Format Channel Id String>
+      [decrease]: <Reduce Capacity Tokens Number>
+      from: <From Node Public Key Id Hex String>
+      id: <Change Request Id Hex String>
+      [increase]: <Add Capacity Tokens Number>
+    }]
+  }
+*/
+module.exports = ({channels, requests}) => {
+  // Change requests can only come from channels with the messaging peer
+  const capacityChangeRequests = requests.filter(request => {
+    const channel = channels.find(chan => chan.id === request.channel);
+
+    // Ignore requests from channels that aren't present
+    if (!channel) {
+      return false;
+    }
+
+    // The change request must come from the peer in the channel
+    return channel.partner_public_key === request.from;
+  });
+
+  const existing = {};
+
+  // Only consider one change request per channel
+  const changeRequests = capacityChangeRequests
+    .filter(({channel}) => {
+      // Exit early when the channel already has a change request
+      if (!!existing[channel]) {
+        return false;
+      }
+
+      // Do not allow more requests for this channel
+      existing[channel] = true;
+
+      return true;
+    })
+    .map(request => {
+      const channel = channels.find(chan => chan.id === request.channel);
+
+      return {
+        address: channel.cooperative_close_address,
+        capacity: channel.capacity,
+        channel: channel.id,
+        decrease: request.decrease,
+        from: channel.partner_public_key,
+        id: request.id,
+        increase: request.increase,
+      };
+    });
+
+  return {requests: changeRequests};
+};

package/capacity/change_channel_capacity.js

@@ -0,0 +1,183 @@
+const asyncAuto = require('async/auto');
+const asyncDetectSeries = require('async/detectSeries');
+const asyncRetry = require('async/retry');
+const {getIdentity} = require('ln-service');
+const {getNodeAlias} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+const {updateChannelFee} = require('ln-sync');
+
+const acceptCapacityChange = require('./accept_capacity_change');
+const getCapacityChangeRequests = require('./get_capacity_change_requests');
+const initiateCapacityChange = require('./initiate_capacity_change');
+
+const interval = 10 * 1000;
+const peerName = ({alias, id}) => `${alias} ${id.substring(0, 8)}`.trim();
+const times = 6 * 60 * 6;
+const tokensAsBigUnit = tokens => (tokens / 1e8).toFixed(8);
+const waitForCloseInterval = 1000 * 3;
+
+/** Change a channel's capacity
+
+  {
+    ask: <Ask Function>
+    [delay]: <Wait Time For Incoming Capacity Requests Milliseconds Number>
+    lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
+  }
+*/
+module.exports = ({ask, delay, lnd, logger}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!ask) {
+          return cbk([400, 'ExpectedAskFunctionToChangeCapacity']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToChangeCapacity']);
+        }
+
+        if (!logger) {
+          return cbk([400, 'ExpectedLoggerObjectToChangeCapacity']);
+        }
+
+        return cbk();
+      },
+
+      // Ask to confirm what will happen in a change capacity
+      askToConfirm: ['validate', ({}, cbk) => {
+        const details = [
+          'This is experimental. Channels may force-close instead of change.',
+          'Adding funds currently requires an extra confirmation wait.',
+          'Chain fees will be deducted from the changed capacity total.',
+          'Chain fees will be paid from the initiator local balance.',
+          'Forwards with the peer will be halted during capacity change.',
+        ];
+
+        // Show the warnings
+        logger.info({details});
+
+        return ask({type: 'confirm', name: 'ok', message: 'OK?'}, ({ok}) => {
+          if (!ok) {
+            return cbk([400, 'CanceledChannelCapacityChange']);
+          }
+
+          return cbk();
+        });
+      }],
+
+      // Get the public key of this node
+      getIdentity: ['validate', ({}, cbk) => getIdentity({lnd}, cbk)],
+
+      // Wait for an incoming capacity change request
+      waitForProposal: ['validate', ({}, cbk) => {
+        return getCapacityChangeRequests({delay, lnd}, cbk);
+      }],
+
+      // Ask for acceptance of a channel
+      askToSelectChange: [
+        'askToConfirm',
+        'waitForProposal',
+        ({waitForProposal}, cbk) =>
+      {
+        return asyncDetectSeries(waitForProposal.requests, (request, cbk) => {
+          return getNodeAlias({lnd, id: request.from}, (err, res) => {
+            if (!!err) {
+              return cbk(err);
+            }
+
+            const change = !!request.increase ? 'Increase' : 'Decrease';
+            const delta = request.decrease || request.increase;
+            const id = request.channel;
+            const peer = peerName(res);
+            const size = tokensAsBigUnit(request.capacity);
+
+            const action = `${change} capacity ${size} channel ${id}`;
+            const by = !!delta ? ` by ${tokensAsBigUnit(delta)}` : '';
+
+            return ask({
+              type: 'confirm',
+              name: 'accept',
+              message: `${action} with ${peer}${by}?`,
+            },
+            ({accept}) => {
+              if (!accept) {
+                return cbk(null, false);
+              }
+
+              // Fail changing when cooperative_close_address is set
+              if (!!request.address && !!request.increase) {
+                return cbk([400, 'ChannelHasLockedCoopCloseAddressSet']);
+              }
+
+              return cbk(null, true);
+            });
+          });
+        },
+        cbk);
+      }],
+
+      // Accept a capacity change proposal
+      acceptChange: ['askToSelectChange', ({askToSelectChange}, cbk) => {
+        // Exit early when there is no change proposal to accept
+        if (!askToSelectChange) {
+          return cbk();
+        }
+
+        return acceptCapacityChange({
+          lnd,
+          logger,
+          channel: askToSelectChange.channel,
+          from: askToSelectChange.from,
+          id: askToSelectChange.id,
+          increase: askToSelectChange.increase,
+        },
+        cbk);
+      }],
+
+      // Initiate a capacity change
+      initiateChange: ['askToSelectChange', ({askToSelectChange}, cbk) => {
+        if (!!askToSelectChange) {
+          return cbk();
+        }
+
+        return initiateCapacityChange({ask, lnd, logger}, cbk);
+      }],
+
+      // Reset the channel routing policies
+      adjustPolicy: [
+        'acceptChange',
+        'getIdentity',
+        'initiateChange',
+        ({acceptChange, getIdentity, initiateChange}, cbk) =>
+      {
+        const policy = acceptChange || initiateChange;
+
+        logger.info({restoring_routing_policy: true});
+
+        return asyncRetry({interval, times}, cbk => {
+          return updateChannelFee({
+            lnd,
+            base_fee_mtokens: policy.base_fee_mtokens,
+            cltv_delta: policy.cltv_delta,
+            fee_rate: policy.fee_rate,
+            from: getIdentity.public_key,
+            transaction_id: policy.transaction_id,
+            transaction_vout: policy.transaction_vout,
+          },
+          cbk);
+        },
+        cbk);
+      }],
+
+      // Capacity change complete
+      complete: ['adjustPolicy', ({}, cbk) => {
+        logger.info({channel_capacity_successfully_changed: true});
+
+        return cbk();
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/capacity/encode_change_request.js

@@ -0,0 +1,55 @@
+const {encodeBigSize} = require('bolt01');
+const {rawChanId} = require('bolt07');
+
+const channelIdRecordType = '2';
+const decreaseRecordType = '3';
+const increaseRecordType = '4';
+const requestIdRecordType = '1';
+
+/** Encode a request to change a channel capacity
+
+  {
+    channel: <Channel to Change Standard Format Id String>
+    [decrease]: <Remove Channel Funds By Tokens Number>
+    id: <Request Id Hex String>
+    increase: <Add Channel Funds By Tokens Number>
+  }
+
+  @returns
+  {
+    records: [{
+      type: <Record Type Number String>
+      value: <Record Value Hex Encoded String>
+    }]
+  }
+*/
+module.exports = ({channel, decrease, id, increase}) => {
+  const records = [
+    {
+      type: requestIdRecordType,
+      value: id,
+    },
+    {
+      type: channelIdRecordType,
+      value: rawChanId({channel}).id,
+    },
+  ];
+
+  if (!!decrease) {
+    // Add a record reflecting the decrease in the capacity
+    records.push({
+      type: decreaseRecordType,
+      value: encodeBigSize({number: decrease.toString()}).encoded,
+    });
+  }
+
+  if (!!increase) {
+    // Add a record reflecting the increase in the capacity
+    records.push({
+      type: increaseRecordType,
+      value: encodeBigSize({number: increase.toString()}).encoded,
+    });
+  }
+
+  return {records};
+};

package/capacity/encode_sign_capacity_response.js

@@ -0,0 +1,32 @@
+const idType = '0';
+const capacityChangeSignatureType = '1';
+
+/** Encode the response to a sign capacity request
+
+  {
+    id: <Capacity Change Id Hex String>
+    signature: <Replacement Transaction Signature Hex String>
+  }
+
+  @returns
+  {
+    records: [{
+      type: <Record Type Number String>
+      value: <Record Value Hex Encoded String>
+    }]
+  }
+*/
+module.exports = ({id, signature}) => {
+  return {
+    records: [
+      {
+        type: idType,
+        value: id,
+      },
+      {
+        type: capacityChangeSignatureType,
+        value: signature,
+      },
+    ],
+  };
+};

package/capacity/fee_for_replacement.js

@@ -0,0 +1,108 @@
+const {Transaction} = require('bitcoinjs-lib');
+
+const {ceil} = Math;
+const decreaseBuffer = 44;
+const dummyHash = Buffer.alloc(32);
+const dummyIncreaseIndex = 1;
+const dummyIndex = 0;
+const dummyMultiSigScript = Buffer.alloc(71);
+const dummyNullDummy = Buffer.alloc(1);
+const dummyP2wsh = Buffer.alloc(68);
+const dummyPublicKey = Buffer.alloc(33);
+const dummySignature = Buffer.alloc(74);
+const dummyTokens = 0;
+const dummyVout = 0;
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const increaseBuffer = 150;
+const {max} = Math;
+const weightAsVBytes = weight => weight / 4;
+
+/** Calculate the chain fee required for the capacity replacement tx
+
+  {
+    capacity: <Original Channel Capacity Tokens Number>
+    commit_transaction_fee: <Commit Transaction Fee Tokens Number>
+    commit_transaction_weight: <Commit Transaction Weight Units Number>
+    decrease: [{
+      output: <Output Script Hex String>
+      tokens: <Spend Value to Chain Address Tokens Number>
+    }]
+    [increase]: <Add Funds Tokens Number>
+    tokens_per_vbyte: <Minimal Fee Rate Tokens Per VByte Number>
+  }
+
+  @returns
+  {
+    fee: <Estimated Replacement Chain Fee Tokens Number>
+  }
+*/
+module.exports = args => {
+  // The cost to close is also known as the commit fee
+  const closeTransactionFee = args.commit_transaction_fee;
+
+  // The commitment transaction size will have to be paid for
+  const replaceSize = weightAsVBytes(args.commit_transaction_weight);
+
+  // Calculate the rate that the commitment tx is paying
+  const commitRate = closeTransactionFee / replaceSize;
+
+  // Create a dummy transaction which models the replacement
+  const tx = new Transaction();
+
+  // Add the decreases as outputs
+  args.decrease.forEach(({output, tokens}) => {
+    return tx.addOutput(hexAsBuffer(output), tokens);
+  });
+
+  // Add an output to represent the new channel output
+  tx.addOutput(dummyP2wsh, args.capacity);
+
+  args.decrease.forEach(({output}) => {
+    return tx.addOutput(hexAsBuffer(output), dummyTokens);
+  });
+
+  // Add an input to represent the old channel input
+  tx.addInput(dummyHash, dummyVout);
+
+  // Spending a channel close requires both signatures
+  const dummyWitnessStack = [
+    dummyNullDummy,
+    dummySignature,
+    dummySignature,
+    dummyMultiSigScript,
+  ];
+
+  // Add a witness to the input
+  tx.setWitness(dummyIndex, dummyWitnessStack);
+
+  // An increase means that there is an additional input
+  if (!!args.increase) {
+    tx.addInput(dummyHash, dummyVout);
+
+    // Add funds input spends from transit, which means signature + public key
+    tx.setWitness(dummyIncreaseIndex, [dummySignature, dummyPublicKey]);
+  }
+
+  // Add additional size for an additional input
+  const inputBuffer = !!args.increase ? increaseBuffer : dummyTokens;
+
+  // Add additional size for additional outputs
+  const outputBuffer = args.decrease.length * decreaseBuffer;
+
+  // Now that we have all inputs and outputs we can measure the virtual bytes
+  const size = tx.virtualSize() + inputBuffer + outputBuffer;
+
+  // The fee for the replacement tx must be above a minimum
+  const minFee = ceil(size * commitRate);
+
+  // The base fee for replacement is the fee of the replacement
+  const baseFee = args.commit_transaction_fee;
+
+  // There is an additional fee which is a relay fee to pay for the replaced tx
+  const deltaFee = ceil(replaceSize * args.tokens_per_vbyte);
+
+  // The new tx pays either min replacement fee or the min overall relay fee
+  const fee = max(minFee, closeTransactionFee + deltaFee);
+
+  return {fee};
+};

package/capacity/finalize_capacity_replacement.js

@@ -0,0 +1,67 @@
+const {script} = require('bitcoinjs-lib');
+const {Transaction} = require('bitcoinjs-lib');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const {decompile} = script;
+const encodeSig = (n, flag) => Buffer.concat([Buffer.from(n, 'hex'), flag]);
+const {fromHex} = Transaction;
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isBuffer} = Buffer;
+const nullDummyStackItem = Buffer.alloc(0);
+const signatureFlag = Buffer.from([Transaction.SIGHASH_ALL]);
+
+/** Add signaturess to a capacity replacement transaction
+
+  {
+    [add_funds_vin]: <Add Funds Input Index>
+    [add_funds_public_key]: <Add Funds Transit Public Key Hex String>
+    [add_funds_signature]: <Add Funds Signature Hex String>
+    local_public_key: <Local MultiSig Public Key Hex String>
+    local_signature: <Local Replacement Signature Hex String>
+    funding_spend_vin: <Funding Transaction Output Spend Input Index Number>
+    remote_signature: <Peer Signature Hex String>
+    transaction: <Unsigned Replacement Transaction Hex String>
+    witness_script: <Funding Witness Script Hex Encoded String>
+  }
+
+  @returns
+  {
+    transaction: <Fully Signed Transaction Hex String>
+  }
+*/
+module.exports = args => {
+  const funding = hexAsBuffer(args.witness_script);
+  const tx = fromHex(args.transaction);
+
+  const keys = decompile(funding).filter(isBuffer).map(bufferAsHex);
+
+  const signatures = [,];
+
+  // Find the indices to place the signatures
+  const localKeyIndex = keys.findIndex(n => n === args.local_public_key);
+  const remoteKeyIndex = keys.findIndex(n => n !== args.local_public_key);
+
+  // Add the local signature to the funding witness stack
+  signatures[localKeyIndex] = encodeSig(args.local_signature, signatureFlag);
+
+  // Add the remote signature to the funding witness stack
+  signatures[remoteKeyIndex] = encodeSig(args.remote_signature, signatureFlag);
+
+  const witness = []
+    .concat([nullDummyStackItem])
+    .concat(signatures)
+    .concat([funding]);
+
+  // Fill in the witness stack including the close spend
+  tx.setWitness(args.funding_spend_vin, witness);
+
+  // The increase in funds also needs a signature added
+  if (!!args.add_funds_signature) {
+    tx.setWitness(args.add_funds_vin, [
+      encodeSig(args.add_funds_signature, signatureFlag),
+      hexAsBuffer(args.add_funds_public_key),
+    ]);
+  }
+
+  return {transaction: tx.toHex()};
+};