balanceofsatoshis 25.2.2 → 25.3.0

package/chain/get_closes_in_blocks.js

@@ -0,0 +1,81 @@
+const asyncAuto = require('async/auto');
+const asyncMapSeries = require('async/mapSeries');
+const {returnResult} = require('asyncjs-util');
+
+const getBlockTransactions = require('./get_block_transactions');
+
+const flatten = arr => [].concat(...arr);
+const {isArray} = Array;
+const uniq = arr => Array.from(new Set(arr));
+
+/** Get close transactions out of the blocks they were confirmed in
+
+  When a block can't be retrieved, its close transactions are not returned
+
+  {
+    channels: [{
+      close_confirm_height: <Close Confirmed At Height Number>
+      close_transaction_id: <Close Transaction Id Hex String>
+    }]
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    transactions: [{
+      id: <Close Transaction Id Hex String>
+      transaction: <Raw Close Transaction Hex String>
+    }]
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isArray(args.channels)) {
+          return cbk([400, 'ExpectedChannelsToGetClosesInBlocks']);
+        }
+
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedLndToGetClosesInBlocks']);
+        }
+
+        return cbk();
+      },
+
+      // Get the close transactions out of each block
+      getBlocks: ['validate', ({}, cbk) => {
+        // Closes that confirmed in the same block share a single block fetch
+        const heights = uniq(args.channels.map(n => n.close_confirm_height));
+
+        return asyncMapSeries(heights, (height, cbk) => {
+          const ids = args.channels
+            .filter(n => n.close_confirm_height === height)
+            .map(n => n.close_transaction_id);
+
+          return getBlockTransactions({
+            height,
+            ids,
+            lnd: args.lnd,
+          },
+          (err, res) => {
+            // Exit early when the block can't be retrieved, leaving it unknown
+            if (!!err) {
+              return cbk(null, []);
+            }
+
+            return cbk(null, res.transactions);
+          });
+        },
+        cbk);
+      }],
+
+      // Close transactions found in the blocks
+      transactions: ['getBlocks', ({getBlocks}, cbk) => {
+        return cbk(null, {transactions: flatten(getBlocks)});
+      }],
+    },
+    returnResult({reject, resolve, of: 'transactions'}, cbk));
+  });
+};

package/chain/get_spending_transaction.js

@@ -0,0 +1,90 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+const {subscribeToChainSpend} = require('ln-service');
+
+const defaultTimeoutMs = 1000 * 10;
+
+/** Get the transaction that spent an output using the LND chain notifier
+
+  When the spend is not found before the timeout, no transaction is returned
+
+  {
+    lnd: <Authenticated LND API Object>
+    min_height: <Look For The Spend Starting At Block Height Number>
+    output_script: <Spent Output Script Hex String>
+    [timeout]: <Stop Looking For The Spend After Milliseconds Number>
+    transaction_id: <Spent Output Transaction Id Hex String>
+    transaction_vout: <Spent Output Transaction Output Index Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    [transaction]: <Raw Spending Transaction Hex String>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedLndToGetSpendingTransaction']);
+        }
+
+        if (!args.min_height) {
+          return cbk([400, 'ExpectedMinHeightToGetSpendingTransaction']);
+        }
+
+        if (!args.output_script) {
+          return cbk([400, 'ExpectedOutputScriptToGetSpendingTransaction']);
+        }
+
+        if (!args.transaction_id) {
+          return cbk([400, 'ExpectedTransactionIdToGetSpendingTransaction']);
+        }
+
+        if (args.transaction_vout === undefined) {
+          return cbk([400, 'ExpectedTransactionVoutToGetSpendingTransaction']);
+        }
+
+        return cbk();
+      },
+
+      // Wait for LND to find the spend of the output
+      getSpend: ['validate', ({}, cbk) => {
+        const sub = subscribeToChainSpend({
+          lnd: args.lnd,
+          min_height: args.min_height,
+          output_script: args.output_script,
+          transaction_id: args.transaction_id,
+          transaction_vout: args.transaction_vout,
+        });
+
+        const finished = (err, res) => {
+          clearTimeout(timer);
+
+          sub.removeAllListeners();
+
+          return cbk(err, res);
+        };
+
+        // Stop looking when the spend is not found in time
+        const timer = setTimeout(() => {
+          return finished(null, {});
+        },
+        args.timeout || defaultTimeoutMs);
+
+        sub.once('confirmation', ({transaction}) => {
+          return finished(null, {transaction});
+        });
+
+        sub.once('end', () => finished(null, {}));
+
+        sub.once('error', err => {
+          return finished([503, 'UnexpectedErrorGettingSpend', {err}]);
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getSpend'}, cbk));
+  });
+};

package/chain/input_weight.js

@@ -0,0 +1,43 @@
+const {numberAsCompactInt} = require('@alexbosworth/blockchain');
+
+const byteCountOutpoint = 36;
+const byteCountSequence = 4;
+const compactIntSize = n => numberAsCompactInt({number: n}).encoded.length;
+const hexByteLength = hex => hex.length / 2;
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const witnessScaling = 4;
+
+/** Calculate the weight contributed by a transaction input
+
+  {
+    script: <ScriptSig Script Hex String>
+    [witness]: [<Script Stack Element Hex String>]
+  }
+
+  @returns
+  <Input Weight Units Number>
+*/
+module.exports = ({script, witness}) => {
+  const scriptBytes = hexByteLength(script);
+
+  const base = [
+    byteCountOutpoint,
+    compactIntSize(scriptBytes),
+    scriptBytes,
+    byteCountSequence,
+  ];
+
+  // Non-witness bytes count four times as much as witness bytes
+  const baseWeight = sumOf(base) * witnessScaling;
+
+  // Exit early when there is no witness data for the input
+  if (!witness) {
+    return baseWeight;
+  }
+
+  const items = witness.map(n => {
+    return compactIntSize(hexByteLength(n)) + hexByteLength(n);
+  });
+
+  return baseWeight + compactIntSize(witness.length) + sumOf(items);
+};

package/chain/is_contract_spend.js

@@ -0,0 +1,26 @@
+/** Determine if a transaction input spends one of a set of contract outputs
+
+  Contract outputs without an output index refer to all outputs of the tx
+
+  {
+    id: <Input Spends Transaction Id Hex String>
+    outputs: [{
+      id: <Contract Transaction Id Hex String>
+      [vout]: <Contract Transaction Output Index Number>
+    }]
+    vout: <Input Spends Transaction Output Index Number>
+  }
+
+  @returns
+  <Input Spends A Contract Output Bool>
+*/
+module.exports = args => {
+  return !!args.outputs.find(output => {
+    // Exit early when the input does not spend the contract transaction
+    if (output.id !== args.id) {
+      return false;
+    }
+
+    return output.vout === undefined || output.vout === args.vout;
+  });
+};

package/chain/link_payment_stages.js

@@ -0,0 +1,119 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+/** Link HTLC payment resolutions that resolve over two stages
+
+  An HTLC on a local commitment is first spent into a second level transaction
+  and then the second level output is spent. LND keeps a first stage report as
+  well as the report of the second stage, so the second stage is linked to the
+  first stage to get the final outcome of the HTLC.
+
+  A second level transaction can spend multiple HTLCs. Each HTLC output in it
+  is at the same index as the HTLC input that funds it.
+
+  {
+    close_payments: [{
+      is_outgoing: <Payment Is Outgoing Bool>
+      is_paid: <Payment Is Claimed With Preimage Bool>
+      is_pending: <Payment Resolution Is Pending Bool>
+      is_refunded: <Payment Timed Out And Went Back To Payer Bool>
+      [spent_by]: <Spent By Transaction Id Hex String>
+      tokens: <Associated Tokens Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+    transactions: [{
+      id: <Transaction Id Hex String>
+      [transaction]: <Raw Transaction Hex String>
+    }]
+  }
+
+  @returns
+  {
+    payments: [{
+      is_outgoing: <Payment Is Outgoing Bool>
+      is_paid: <Payment Is Claimed With Preimage Bool>
+      is_pending: <Payment Resolution Is Pending Bool>
+      is_refunded: <Payment Timed Out And Went Back To Payer Bool>
+      [spent_by]: <Final Spent By Transaction Id Hex String>
+      tokens: <Associated Tokens Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+  }
+*/
+module.exports = args => {
+  // First stage reports are pending spends into a second level transaction
+  const firstStages = args.close_payments.filter(payment => {
+    return !!payment.is_pending && !!payment.spent_by;
+  });
+
+  // Find the second stage report for each first stage report
+  const links = firstStages.map(firstStage => {
+    const isSameDirection = n => n.is_outgoing === firstStage.is_outgoing;
+
+    const secondStages = args.close_payments
+      .filter(n => n.transaction_id === firstStage.spent_by)
+      .filter(isSameDirection);
+
+    const otherFirstStages = firstStages
+      .filter(n => n !== firstStage)
+      .filter(n => n.spent_by === firstStage.spent_by)
+      .filter(isSameDirection);
+
+    // Exit early when no other HTLC like this is in the second level tx
+    if (!otherFirstStages.length) {
+      const [secondStage] = secondStages;
+
+      return {firstStage, secondStage};
+    }
+
+    const [secondLevelTx] = args.transactions
+      .filter(n => !!n.transaction)
+      .filter(n => n.id === firstStage.spent_by)
+      .map(({transaction}) => componentsOfTransaction({transaction}));
+
+    // Exit early when the second level tx is not known to pair the outputs
+    if (!secondLevelTx) {
+      return {firstStage};
+    }
+
+    const vout = secondLevelTx.inputs.findIndex(input => {
+      if (input.id !== firstStage.transaction_id) {
+        return false;
+      }
+
+      return input.vout === firstStage.transaction_vout;
+    });
+
+    const secondStage = secondStages.find(n => n.transaction_vout === vout);
+
+    return {firstStage, secondStage};
+  });
+
+  const linked = links.filter(link => !!link.secondStage);
+
+  // Second stages are folded into the first stage that they continue
+  const payments = args.close_payments
+    .filter(payment => !linked.find(n => n.secondStage === payment))
+    .map(payment => {
+      const link = linked.find(n => n.firstStage === payment);
+
+      // Exit early when there is no second stage to link
+      if (!link) {
+        return payment;
+      }
+
+      return {
+        is_outgoing: payment.is_outgoing,
+        is_paid: link.secondStage.is_paid,
+        is_pending: link.secondStage.is_pending,
+        is_refunded: link.secondStage.is_refunded,
+        spent_by: link.secondStage.spent_by,
+        tokens: payment.tokens,
+        transaction_id: payment.transaction_id,
+        transaction_vout: payment.transaction_vout,
+      };
+    });
+
+  return {payments};
+};

package/chain/payment_outcome.js

@@ -0,0 +1,28 @@
+/** Describe the outcome of a closed channel HTLC payment output
+
+  {
+    [is_paid]: <Payment Is Claimed With Preimage Bool>
+    [is_pending]: <Payment Resolution Is Pending Bool>
+    [is_refunded]: <Payment Timed Out And Went Back To Payer Bool>
+  }
+
+  @returns
+  {
+    outcome: <Payment Outcome String>
+  }
+*/
+module.exports = args => {
+  if (!!args.is_paid) {
+    return {outcome: 'paid'};
+  }
+
+  if (!!args.is_refunded) {
+    return {outcome: 'refunded'};
+  }
+
+  if (!!args.is_pending) {
+    return {outcome: 'pending'};
+  }
+
+  return {outcome: 'unclaimed'};
+};

package/chain/resolution_fee.js

@@ -0,0 +1,86 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+const inputWeight = require('./input_weight');
+const isContractSpend = require('./is_contract_spend');
+const transactionFee = require('./transaction_fee');
+
+const {round} = Math;
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+
+/** Calculate the share of a resolving tx fee attributable to a channel
+
+  A resolving transaction may also spend outputs of other channels, in which
+  case the fee is pro-rated by the weight of the inputs that spend the
+  channel's own contract outputs. Inputs that spend neither are fee funding
+  inputs and are not counted against the channel's share.
+
+  Contract outputs without an output index refer to all outputs of the tx.
+  A second level transaction can be shared between channels so its outputs
+  are referred to individually.
+
+  {
+    contract_outputs: [{
+      id: <Channel Contract Transaction Id Hex String>
+      [vout]: <Channel Contract Transaction Output Index Number>
+    }]
+    id: <Resolving Transaction Id Hex String>
+    other_contract_outputs: [{
+      id: <Other Channel Contract Transaction Id Hex String>
+      [vout]: <Other Channel Contract Transaction Output Index Number>
+    }]
+    transactions: [{
+      [fee]: <Wallet Reported Fee Tokens Number>
+      id: <Transaction Id Hex String>
+      [transaction]: <Raw Transaction Hex String>
+    }]
+  }
+
+  @returns
+  {
+    [fee]: <Attributable Fee Tokens Number>
+  }
+*/
+module.exports = args => {
+  const tx = args.transactions.find(n => n.id === args.id);
+
+  // Exit early when the resolving transaction is not known
+  if (!tx || !tx.transaction) {
+    return {};
+  }
+
+  const {inputs} = componentsOfTransaction({transaction: tx.transaction});
+
+  const own = inputs.filter(({id, vout}) => {
+    return isContractSpend({id, vout, outputs: args.contract_outputs});
+  });
+
+  const other = inputs.filter(({id, vout}) => {
+    return isContractSpend({id, vout, outputs: args.other_contract_outputs});
+  });
+
+  // Exit early when the transaction does not spend the channel's outputs
+  if (!own.length) {
+    return {};
+  }
+
+  const {fee} = transactionFee({
+    fee: tx.fee,
+    transaction: tx.transaction,
+    transactions: args.transactions,
+  });
+
+  // Exit early when the total fee of the transaction is not known
+  if (fee === undefined) {
+    return {};
+  }
+
+  // Exit early when the fee is not shared with other channels
+  if (!other.length) {
+    return {fee};
+  }
+
+  const ownWeight = sumOf(own.map(inputWeight));
+  const otherWeight = sumOf(other.map(inputWeight));
+
+  return {fee: round(fee * ownWeight / (ownWeight + otherWeight))};
+};

package/chain/split_fee.js

@@ -0,0 +1,40 @@
+const baseTxVbytes = 9;
+const changeOutputVbytes = 43;
+const {ceil} = Math;
+const compactVbytes = 1;
+const countVbytes = n => n <= maxCompactCount ? compactVbytes : wideVbytes;
+const maxCompactCount = 252;
+const splitOutputVbytes = 31;
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const wideVbytes = 3;
+
+/** Fee for a split transaction, rounding up so that the fee is not too low
+
+  Virtual sizes are upper bounds of the sizes the wallet estimates with
+
+  {
+    [has_change]: <Transaction Has a Change Output Bool>
+    inputs: <Inputs Count Number>
+    outputs: <Split Outputs Count Number>
+    rate: <Fee Tokens Per Virtual Byte Number>
+    vbytes: <Inputs Virtual Bytes Number>
+  }
+
+  @returns
+  <Fee Tokens Number>
+*/
+module.exports = args => {
+  const changeVbytes = !!args.has_change ? changeOutputVbytes : Number();
+  const outputsCount = args.outputs + Number(!!args.has_change);
+
+  const vbytes = sumOf([
+    baseTxVbytes,
+    changeVbytes,
+    countVbytes(args.inputs),
+    countVbytes(outputsCount),
+    args.outputs * splitOutputVbytes,
+    args.vbytes,
+  ]);
+
+  return ceil(vbytes * args.rate);
+};