balanceofsatoshis 25.2.2 → 25.3.0

package/chain/split_utxos.js

@@ -1,20 +1,33 @@
 const asyncAuto = require('async/auto');
+const asyncEach = require('async/each');
 const asyncMapSeries = require('async/mapSeries');
+const asyncReflect = require('async/reflect');
+const {broadcastChainTransaction} = require('ln-service');
 const {createChainAddress} = require('ln-service');
+const {fundPsbt} = require('ln-service');
+const {getChainFeeRate} = require('ln-service');
 const {getUtxos} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
-const {sendToChainAddresses} = require('ln-service');
+const {signPsbt} = require('ln-service');
+const {unlockUtxo} = require('ln-service');
 
-const consumedUtxoCount = 1;
-const decBase = 10;
-const format ='p2wpkh';
+const utxoSplitPlan = require('./utxo_split_plan');
+
+const asOutpoint = n => `${n.transaction_id}:${n.transaction_vout}`;
+const {ceil} = Math;
+const format = 'p2wpkh';
 const minimumUtxoTokens = 1e5;
 const newArrayOfSize = n => Array.from(Array(n));
 
 /** Ensure there are a certain number of utxos greater than or equal to a size
 
-  Note: this is not efficient with respect to inputs. It may result in
-  over-selected inputs in funding the transaction.
+  Spending a utxo that already counts removes it from the count, so the split
+  replaces spent counted utxos and counts the change when it is large enough.
+
+  The inputs to spend are selected so that the split reaches the count, and
+  when the funds cannot support the count, the split is rejected.
+
+  Only confirmed utxos are spent
 
   {
     count: <Count of UTXOs Number>
@@ -24,6 +37,13 @@ const newArrayOfSize = n => Array.from(Array(n));
     size: <UTXO Minimum Tokens Number>
     [tokens_per_vbyte]: <Fee Tokens Per Virtual Byte Number>
   }
+
+  @returns via cbk
+  {
+    needed_outputs: <Split Outputs Count Number>
+    sent_to: [<Split Output Address String>]
+    [transaction_id]: <Split Transaction Id Hex String>
+  }
 */
 module.exports = (args, cbk) => {
   return asyncAuto({
@@ -44,89 +64,182 @@ module.exports = (args, cbk) => {
       return cbk();
     },
 
-    // Get all the current confirmed UTXOs
-    getUtxos: ['validate', ({}, cbk) => getUtxos({lnd: args.lnd}, cbk)],
-
-    // Determine the missing count of utxos
-    outputCount: ['getUtxos', ({getUtxos}, cbk) => {
-      const {utxos} = getUtxos;
+    // Get the fee rate to pay for the split
+    feeRate: ['validate', ({}, cbk) => {
+      // Exit early when the fee rate is specified
+      if (!!args.tokens_per_vbyte) {
+        return cbk(null, args.tokens_per_vbyte);
+      }
 
-      const existing = utxos.filter(utxo => {
-        if (!!args.is_confirmed && !utxo.confirmation_count) {
-          return false;
+      return getChainFeeRate({lnd: args.lnd}, (err, res) => {
+        if (!!err) {
+          return cbk(err);
         }
 
-        return utxo.tokens >= args.size;
+        // Round up the estimated rate since the split pays whole rates
+        return cbk(null, ceil(res.tokens_per_vbyte));
       });
-
-      if (existing.length > args.count) {
-        return cbk(null, [].length);
-      }
-
-      return cbk(null, args.count - existing.length - consumedUtxoCount);
     }],
 
-    // UTXOs have to be of a certain size
-    checkFunds: ['getUtxos', 'outputCount', ({getUtxos, outputCount}, cbk) => {
-      // Exit early when there are no needed utxos
-      if (!outputCount) {
-        return cbk();
-      }
-
-      const utxos = getUtxos.utxos.filter(n => !!n.confirmation_count);
-
-      const tokens = utxos.reduce((sum, n) => sum + n.tokens, 0);
+    // Get all the current UTXOs
+    getUtxos: ['validate', ({}, cbk) => getUtxos({lnd: args.lnd}, cbk)],
 
-      if (outputCount * args.size > tokens) {
-        return cbk([400, 'InsufficientBalanceToSplitUtxos']);
+    // Select the inputs and the count of outputs that reach the count
+    plan: ['feeRate', 'getUtxos', ({feeRate, getUtxos}, cbk) => {
+      try {
+        const plan = utxoSplitPlan({
+          count: args.count,
+          fee_tokens_per_vbyte: feeRate,
+          is_confirmed: args.is_confirmed,
+          size: args.size,
+          utxos: getUtxos.utxos,
+        });
+
+        return cbk(null, plan);
+      } catch (err) {
+        return cbk([400, err.message]);
       }
-
-      return cbk();
     }],
 
     // Generate addresses
-    getAddresses: ['checkFunds', 'outputCount', ({outputCount}, cbk) => {
-      if (!!args.is_dry_run) {
+    getAddresses: ['plan', ({plan}, cbk) => {
+      // Exit early when not creating any outputs
+      if (!!args.is_dry_run || !plan.outputs) {
         return cbk(null, []);
       }
 
-      return asyncMapSeries(newArrayOfSize(outputCount), (_, cbk) => {
-       return createChainAddress({format, lnd: args.lnd}, cbk);
+      return asyncMapSeries(newArrayOfSize(plan.outputs), (_, cbk) => {
+        return createChainAddress({format, lnd: args.lnd}, cbk);
       },
       cbk);
     }],
 
-    // Send to multiple outputs
-    splitUtxos: [
+    // Fund the split outputs by spending the selected inputs
+    fund: [
+      'feeRate',
       'getAddresses',
-      'outputCount',
-      ({getAddresses, outputCount}, cbk) =>
+      'plan',
+      ({feeRate, getAddresses, plan}, cbk) =>
     {
-      if (!!args.is_dry_run) {
-        return cbk(null, {});
+      // Exit early when there are no outputs to fund
+      if (!getAddresses.length) {
+        return cbk();
       }
 
       const tokens = args.size;
 
-      return sendToChainAddresses({
-        fee_tokens_per_vbyte: args.tokens_per_vbyte || undefined,
+      return fundPsbt({
+        fee_tokens_per_vbyte: feeRate,
+        inputs: plan.inputs,
         lnd: args.lnd,
-        send_to: getAddresses.map(({address}) => ({address, tokens})),
+        outputs: getAddresses.map(({address}) => ({address, tokens})),
       },
       cbk);
     }],
 
+    // Make sure the funded split reaches the count before signing it
+    checkFunding: [
+      'fund',
+      'getUtxos',
+      asyncReflect(({fund, getUtxos}, cbk) =>
+    {
+      // Exit early when there is no funded split to check
+      if (!fund) {
+        return cbk();
+      }
+
+      const spending = fund.inputs.map(asOutpoint);
+
+      // Counted utxos that are not spent in the split remain counted
+      const remaining = getUtxos.utxos
+        .filter(n => !args.is_confirmed || !!n.confirmation_count)
+        .filter(n => n.tokens >= args.size)
+        .filter(n => !spending.includes(asOutpoint(n)));
+
+      // Split outputs and change that are large enough are counted
+      const created = fund.outputs.filter(n => n.tokens >= args.size);
+
+      // Exit early with an error when the split would not reach the count
+      if (remaining.length + created.length < args.count) {
+        return cbk([503, 'ExpectedFundedSplitToReachCountOfUtxos']);
+      }
+
+      return cbk();
+    })],
+
+    // Sign the funded split
+    sign: [
+      'checkFunding',
+      'fund',
+      asyncReflect(({checkFunding, fund}, cbk) =>
+    {
+      // Exit early when there is no funded split to sign
+      if (!fund || !!checkFunding.error) {
+        return cbk();
+      }
+
+      return signPsbt({lnd: args.lnd, psbt: fund.psbt}, cbk);
+    })],
+
+    // Broadcast the signed split
+    broadcast: ['sign', asyncReflect(({sign}, cbk) => {
+      // Exit early when there is no signed split to broadcast
+      if (!sign.value) {
+        return cbk();
+      }
+
+      return broadcastChainTransaction({
+        lnd: args.lnd,
+        transaction: sign.value.transaction,
+      },
+      cbk);
+    })],
+
+    // Release the locks on the inputs when the split is not broadcast
+    unlock: [
+      'broadcast',
+      'checkFunding',
+      'fund',
+      'sign',
+      ({broadcast, checkFunding, fund, sign}, cbk) =>
+    {
+      const error = checkFunding.error || sign.error || broadcast.error;
+
+      // Exit early when nothing stopped the split
+      if (!error) {
+        return cbk();
+      }
+
+      return asyncEach(fund.inputs, (input, cbk) => {
+        return unlockUtxo({
+          id: input.lock_id,
+          lnd: args.lnd,
+          transaction_id: input.transaction_id,
+          transaction_vout: input.transaction_vout,
+        },
+        () => {
+          // Ignore errors unlocking a UTXO, the lock will expire on its own
+          return cbk();
+        });
+      },
+      () => {
+        // Return the original error that stopped the split
+        return cbk(error);
+      });
+    }],
+
     // Utxos
     utxos: [
+      'broadcast',
       'getAddresses',
-      'outputCount',
-      'splitUtxos',
-      ({getAddresses, outputCount, splitUtxos}, cbk) =>
+      'plan',
+      'unlock',
+      ({broadcast, getAddresses, plan}, cbk) =>
     {
       return cbk(null, {
-        needed_outputs: outputCount,
+        needed_outputs: plan.outputs,
         sent_to: getAddresses.map(({address}) => address),
-        transaction_id: splitUtxos.id
+        transaction_id: !!broadcast.value ? broadcast.value.id : undefined,
       });
     }],
   },

package/chain/transaction_fee.js

@@ -0,0 +1,56 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+
+/** Calculate the fee paid by a transaction
+
+  The fee is known when the wallet reports it, or when every output that the
+  transaction spends is known from the raw transaction that created it.
+
+  {
+    [fee]: <Wallet Reported Fee Tokens Number>
+    transaction: <Raw Transaction Hex String>
+    transactions: [{
+      id: <Transaction Id Hex String>
+      [transaction]: <Raw Transaction Hex String>
+    }]
+  }
+
+  @returns
+  {
+    [fee]: <Fee Tokens Number>
+  }
+*/
+module.exports = args => {
+  // Exit early when the wallet knows the fee
+  if (!!args.fee) {
+    return {fee: args.fee};
+  }
+
+  const {inputs, outputs} = componentsOfTransaction({
+    transaction: args.transaction,
+  });
+
+  const spent = inputs.map(input => {
+    const [spending] = args.transactions
+      .filter(n => !!n.transaction)
+      .filter(n => n.id === input.id)
+      .map(({transaction}) => componentsOfTransaction({transaction}));
+
+    // Exit early when the transaction that created the input is not known
+    if (!spending) {
+      return undefined;
+    }
+
+    return spending.outputs[input.vout];
+  });
+
+  // Exit early when the value of a spent output is unknown
+  if (spent.includes(undefined)) {
+    return {};
+  }
+
+  const spentTokens = sumOf(spent.map(n => n.tokens));
+
+  return {fee: spentTokens - sumOf(outputs.map(n => n.tokens))};
+};

package/chain/utxo_split_plan.js

@@ -0,0 +1,142 @@
+const {sortBy} = require('./../arrays');
+
+const fundedOutputs = require('./funded_outputs');
+
+const {ceil} = Math;
+const inputVbytes = {np2wpkh: 92, p2tr: 58, p2wpkh: 69};
+const {isArray} = Array;
+const splitOutputVbytes = 31;
+const unknownInputVbytes = 92;
+
+/** Plan the inputs and outputs of a transaction that splits utxos
+
+  Spending a utxo that is already counted removes it from the count, so it has
+  to be replaced. Change counts as a new utxo when it is at least the size.
+
+  Confirmed utxos are spent, starting with the utxos that have the most value
+  beyond what they already count for, until the outputs reaching the count can
+  be funded.
+
+  {
+    count: <Count of UTXOs Number>
+    fee_tokens_per_vbyte: <Fee Tokens Per Virtual Byte Number>
+    [is_confirmed]: <Only Count Confirmed UTXOs Bool>
+    size: <UTXO Minimum Tokens Number>
+    utxos: [{
+      address_format: <Address Format String>
+      confirmation_count: <Confirmation Count Number>
+      tokens: <Unspent Tokens Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    inputs: [{
+      transaction_id: <Spend Transaction Id Hex String>
+      transaction_vout: <Spend Transaction Output Index Number>
+    }]
+    outputs: <Split Outputs Count Number>
+  }
+*/
+module.exports = args => {
+  if (!args.count) {
+    throw new Error('ExpectedCountOfUtxosToPlanUtxoSplit');
+  }
+
+  if (!args.fee_tokens_per_vbyte) {
+    throw new Error('ExpectedFeeRateToPlanUtxoSplit');
+  }
+
+  if (!args.size) {
+    throw new Error('ExpectedSizeOfUtxosToPlanUtxoSplit');
+  }
+
+  if (!isArray(args.utxos)) {
+    throw new Error('ExpectedArrayOfUtxosToPlanUtxoSplit');
+  }
+
+  const fee = vbytes => ceil(vbytes * args.fee_tokens_per_vbyte);
+  const isConfirmedEnough = n => !args.is_confirmed || !!n.confirmation_count;
+
+  const isCounted = n => isConfirmedEnough(n) && n.tokens >= args.size;
+
+  const counted = args.utxos.filter(isCounted);
+
+  // Exit early when there are already enough utxos
+  if (counted.length >= args.count) {
+    return {inputs: [], outputs: [].length};
+  }
+
+  // A counted utxo that is spent has to be replaced with a split output
+  const replacement = args.size + fee(splitOutputVbytes);
+
+  const candidates = args.utxos.filter(n => !!n.confirmation_count).map(n => {
+    const isReplaced = isCounted(n);
+    const vbytes = inputVbytes[n.address_format] || unknownInputVbytes;
+
+    const value = n.tokens - fee(vbytes);
+
+    return {
+      vbytes,
+      is_counted: isReplaced,
+      surplus: isReplaced ? value - replacement : value,
+      tokens: n.tokens,
+      transaction_id: n.transaction_id,
+      transaction_vout: n.transaction_vout,
+    };
+  });
+
+  // Only utxos that add value can help, so spend the most valuable ones first
+  const spending = sortBy({
+    array: candidates.filter(n => n.surplus > Number()),
+    attribute: 'surplus',
+  });
+
+  const spend = spending.sorted.reverse();
+
+  // Select the fewest inputs that fund enough outputs to reach the count
+  const selection = spend.reduce((sum, utxo, i) => {
+    // Exit early when enough inputs are already selected
+    if (sum.outputs !== undefined) {
+      return sum;
+    }
+
+    const selected = {
+      counted: sum.counted + Number(utxo.is_counted),
+      inputs: i + 1,
+      tokens: sum.tokens + utxo.tokens,
+      vbytes: sum.vbytes + utxo.vbytes,
+    };
+
+    const {outputs} = fundedOutputs({
+      counted: selected.counted,
+      inputs: selected.inputs,
+      needed: args.count - counted.length,
+      rate: args.fee_tokens_per_vbyte,
+      size: args.size,
+      tokens: selected.tokens,
+      vbytes: selected.vbytes,
+    });
+
+    return {...selected, outputs};
+  },
+  {counted: 0, inputs: 0, tokens: 0, vbytes: 0});
+
+  // Exit early with an error when the funds cannot reach the count of utxos
+  if (selection.outputs === undefined) {
+    throw new Error('InsufficientBalanceToSplitUtxos');
+  }
+
+  return {
+    inputs: spend.slice(0, selection.inputs).map(utxo => ({
+      transaction_id: utxo.transaction_id,
+      transaction_vout: utxo.transaction_vout,
+    })),
+    outputs: selection.outputs,
+  };
+};

package/package.json

@@ -15,7 +15,7 @@
     "url": "https://github.com/alexbosworth/balanceofsatoshis/issues"
   },
   "dependencies": {
-    "@alexbosworth/blockchain": "4.11.0",
+    "@alexbosworth/blockchain": "4.12.0",
     "@alexbosworth/caporal": "2.0.0",
     "@alexbosworth/fiat": "2.0.0",
     "@alexbosworth/formulas": "1.5.0",
@@ -25,7 +25,6 @@
     "asyncjs-util": "1.2.12",
     "bech32": "2.0.0",
     "bip66": "2.0.0",
-    "bolt03": "2.0.0",
     "bolt04": "1.3.0",
     "bolt07": "2.0.0",
     "cbor": "10.0.12",
@@ -104,5 +103,5 @@
     "postpublish": "docker buildx build --platform linux/amd64,linux/arm64 -t alexbosworth/balanceofsatoshis -t alexbosworth/balanceofsatoshis:$npm_package_version --push .",
     "test": "node --experimental-test-coverage --test test/arrays/*.js test/balances/*.js test/chain/*.js test/display/*.js test/encryption/*.js test/lnd/*.js test/network/*.js test/nodes/*.js test/offchain/*.js test/peers/*.js test/responses/*.js test/routing/*.js test/services/*.js test/swaps/*.js test/tags/*.js test/telegram/*.js test/wallets/*.js"
   },
-  "version": "25.2.2"
+  "version": "25.3.0"
 }