balanceofsatoshis 25.2.3 → 25.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Versions
 
+## 25.3.0
+
+- `closed`: Avoid using external chain data lookups to derive resolution info
+- `closed`: Include anchor and HTLC resolution fees in closing fees paid
+- `closed`: Pro-rate the fees of sweeps that are shared with other channels
+- `closed`: Count the value of an anchor output that was not swept as a fee
+
 ## 25.2.3
 
 - `telegram`: Indicate when a cooperative close was initiated by the peer

package/bos

@@ -490,8 +490,7 @@ prog
 
   // Determine the outcomes of channel closings
   .command('closed', 'Get the status of a channel closings')
-  .help('Channel closes with chain-transaction derived resolution details')
-  .help('Privacy note: this requests tx data from third parties')
+  .help('Channel closes with resolution details of the closing outputs')
   .option('--limit [limit]', 'Limit of closings to get', INT, 20)
   .option('--no-color', 'Mute all colors')
   .option('--node <node_name>', 'Get channel closes from saved node')
@@ -501,7 +500,6 @@ prog
         return chain.getChannelCloses({
           limit: options.limit,
           lnd: (await lnd.authenticatedLnd({logger, node: options.node})).lnd,
-          request: commands.simpleRequest,
         },
         responses.returnObject({logger, reject, resolve}));
       } catch (err) {

package/chain/anchor_outcome.js

@@ -0,0 +1,23 @@
+/** Describe the outcome of a closed channel anchor output
+
+  {
+    [is_confirmed]: <Anchor Output Spend Is Confirmed Bool>
+    [is_pending]: <Anchor Output Spend Is Pending Confirmation Bool>
+  }
+
+  @returns
+  {
+    outcome: <Anchor Outcome String>
+  }
+*/
+module.exports = args => {
+  if (!!args.is_confirmed) {
+    return {outcome: 'swept'};
+  }
+
+  if (!!args.is_pending) {
+    return {outcome: 'pending'};
+  }
+
+  return {outcome: 'unclaimed'};
+};

package/chain/anchor_output.js

@@ -0,0 +1,86 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+const anchorOutputScript = require('./anchor_output_script');
+const fundingKeys = require('./funding_keys');
+
+/** Find our anchor output in a close transaction
+
+  {
+    [anchor_vout]: <LND Reported Anchor Output Index Number>
+    [close_balance_spent_by]: <Close Balance Spent By Id Hex String>
+    [close_balance_vout]: <Close Balance Output Index Number>
+    close_payments: [{
+      transaction_id: <HTLC Transaction Id Hex String>
+      transaction_vout: <HTLC Transaction Output Index Number>
+    }]
+    close_transaction_id: <Close Transaction Id Hex String>
+    [is_cooperative_close]: <Channel Was Cooperatively Closed Bool>
+    [transaction]: <Raw Close Transaction Hex String>
+  }
+
+  @returns
+  {
+    [vout]: <Anchor Output Index Number>
+  }
+*/
+module.exports = args => {
+  // Exit early when LND reported the anchor output
+  if (args.anchor_vout !== undefined) {
+    return {vout: args.anchor_vout};
+  }
+
+  // Exit early when there are no anchors in a cooperative close
+  if (!!args.is_cooperative_close || !args.transaction) {
+    return {};
+  }
+
+  const {inputs, outputs} = componentsOfTransaction({
+    transaction: args.transaction,
+  });
+
+  const [fundingSpend] = inputs;
+
+  const {keys} = fundingKeys({witness: fundingSpend.witness});
+
+  // Exit early when the funding keys that anchors are derived from are unknown
+  if (!keys) {
+    return {};
+  }
+
+  const anchorScripts = keys.map(key => anchorOutputScript({key}).script);
+
+  // Outputs that resolved as the balance or as HTLCs are not anchors
+  const htlcVouts = args.close_payments
+    .filter(n => n.transaction_id === args.close_transaction_id)
+    .map(n => n.transaction_vout);
+
+  const balanceVout = args.close_balance_vout;
+
+  const knownVouts = []
+    .concat(balanceVout !== undefined ? [balanceVout] : [])
+    .concat(htlcVouts);
+
+  const anchors = outputs
+    .map(({script, tokens}, vout) => ({script, tokens, vout}))
+    .filter(n => !knownVouts.includes(n.vout))
+    .filter(n => anchorScripts.includes(n.script));
+
+  // Exit early when there are no anchor outputs
+  if (!anchors.length) {
+    return {};
+  }
+
+  const [anchor, otherAnchor] = anchors;
+
+  // Exit early when both sides have an anchor, one of them is ours
+  if (!!otherAnchor) {
+    return {vout: anchor.vout};
+  }
+
+  // Exit early when a single anchor is ours as we had outputs to protect
+  if (!!args.close_balance_spent_by || !!args.close_payments.length) {
+    return {vout: anchor.vout};
+  }
+
+  return {};
+};

package/chain/anchor_output_script.js

@@ -0,0 +1,43 @@
+const {createHash} = require('node:crypto');
+
+const {p2wshOutputScript} = require('@alexbosworth/blockchain');
+const {scriptElementsAsScript} = require('@alexbosworth/blockchain');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const OP_16 = 96;
+const OP_CHECKSEQUENCEVERIFY = 178;
+const OP_CHECKSIG = 172;
+const OP_ENDIF = 104;
+const OP_IFDUP = 115;
+const OP_NOTIF = 100;
+const sha256 = preimage => createHash('sha256').update(preimage).digest();
+
+/** Derive the anchor output script for a funding public key
+
+  {
+    key: <Funding Public Key Hex String>
+  }
+
+  @returns
+  {
+    script: <Anchor P2WSH Output Script Hex String>
+  }
+*/
+module.exports = ({key}) => {
+  const {script} = scriptElementsAsScript({
+    elements: [
+      hexAsBuffer(key),
+      OP_CHECKSIG,
+      OP_IFDUP,
+      OP_NOTIF,
+      OP_16,
+      OP_CHECKSEQUENCEVERIFY,
+      OP_ENDIF,
+    ],
+  });
+
+  const hash = sha256(hexAsBuffer(script));
+
+  return {script: bufferAsHex(p2wshOutputScript({hash}).script)};
+};

package/chain/close_fee_payer.js

@@ -0,0 +1,48 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+const simpleCloseSequence = 0xfffffffd;
+
+/** Determine which side paid the fee of a channel close transaction
+
+  {
+    [is_cooperative_close]: <Channel Was Cooperatively Closed Bool>
+    [is_partner_closed]: <Channel Was Closed By Peer Bool>
+    [is_partner_initiated]: <Channel Was Opened By Peer Bool>
+    [transaction]: <Raw Close Transaction Hex String>
+  }
+
+  @returns
+  {
+    [is_peer_paying]: <Peer Paid The Close Transaction Fee Bool>
+  }
+*/
+module.exports = args => {
+  const isPeerClosed = args.is_partner_closed;
+  const isPeerOpened = args.is_partner_initiated;
+
+  // Exit early when the channel was force closed, the opener paid for that
+  if (!args.is_cooperative_close) {
+    return {is_peer_paying: isPeerOpened};
+  }
+
+  const isOpenerClosing = isPeerOpened === isPeerClosed;
+
+  // Exit early when the opener also closed, they paid in either protocol
+  if (isPeerOpened !== undefined && isOpenerClosing) {
+    return {is_peer_paying: isPeerOpened};
+  }
+
+  // Exit early when the close protocol is unknown without the close tx
+  if (!args.transaction) {
+    return {};
+  }
+
+  const {inputs} = componentsOfTransaction({transaction: args.transaction});
+
+  const [fundingSpend] = inputs;
+
+  // The closer pays for a simple close, otherwise the opener pays
+  const isSimpleClose = fundingSpend.sequence === simpleCloseSequence;
+
+  return {is_peer_paying: isSimpleClose ? isPeerClosed : isPeerOpened};
+};

package/chain/close_resolutions.js

@@ -0,0 +1,114 @@
+const {componentsOfTransaction} = require('@alexbosworth/blockchain');
+
+const anchorOutcome = require('./anchor_outcome');
+const linkPaymentStages = require('./link_payment_stages');
+const paymentOutcome = require('./payment_outcome');
+const {sortBy} = require('./../arrays');
+
+const sortByVout = arr => sortBy({array: arr, attribute: 'vout'}).sorted;
+
+/** Derive the resolutions of closed channel outputs from LND close details
+
+  Output values for balance and anchor outputs are only known when the close
+  transaction is present in the wallet transactions
+
+  {
+    [anchor_is_confirmed]: <Anchor Output Spend Is Confirmed Bool>
+    [anchor_is_pending]: <Anchor Output Spend Is Pending Confirmation Bool>
+    [anchor_spent_by]: <Anchor Sweep Transaction Id Hex String>
+    [anchor_vout]: <Anchor Output Index Number>
+    [close_balance_spent_by]: <Balance Sweep Transaction Id Hex String>
+    [close_balance_vout]: <Balance Output Index Number>
+    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]: <Close Transaction Spent By Transaction Id Hex String>
+      tokens: <Associated Tokens Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+    close_transaction_id: <Close Transaction Id Hex String>
+    transactions: [{
+      id: <Transaction Id Hex String>
+      [transaction]: <Raw Transaction Hex String>
+    }]
+  }
+
+  @returns
+  {
+    resolutions: [{
+      [transaction_id]: <Latest Resolving Transaction Id Hex String>
+      type: <Resolution Type String>
+      [value]: <Output Value Tokens Number>
+    }]
+  }
+*/
+module.exports = args => {
+  // Output values are only known when the close tx is in the wallet
+  const [closeTx] = args.transactions
+    .filter(n => !!n.transaction)
+    .filter(n => n.id === args.close_transaction_id)
+    .map(({transaction}) => componentsOfTransaction({transaction}));
+
+  const outputs = !!closeTx ? closeTx.outputs : [];
+
+  const tokensAt = vout => !outputs[vout] ? undefined : outputs[vout].tokens;
+
+  const anchorResolution = anchorOutcome({
+    is_confirmed: args.anchor_is_confirmed,
+    is_pending: args.anchor_is_pending,
+  });
+
+  const anchor = {
+    transaction_id: args.anchor_spent_by,
+    type: `anchor_${anchorResolution.outcome}`,
+    value: tokensAt(args.anchor_vout),
+    vout: args.anchor_vout,
+  };
+
+  const balance = {
+    transaction_id: args.close_balance_spent_by,
+    type: 'balance_swept',
+    value: tokensAt(args.close_balance_vout),
+    vout: args.close_balance_vout,
+  };
+
+  // HTLCs resolved over two stages are linked to get their final outcome
+  const {payments} = linkPaymentStages({
+    close_payments: args.close_payments,
+    transactions: args.transactions,
+  });
+
+  const htlcs = payments.map(payment => {
+    const direction = !!payment.is_outgoing ? 'outgoing' : 'incoming';
+
+    const {outcome} = paymentOutcome({
+      is_paid: payment.is_paid,
+      is_pending: payment.is_pending,
+      is_refunded: payment.is_refunded,
+    });
+
+    return {
+      transaction_id: payment.spent_by,
+      type: `${direction}_htlc_${outcome}`,
+      value: payment.tokens,
+      vout: payment.transaction_vout,
+    };
+  });
+
+  // Anchor and balance resolutions are only present when LND reported them
+  const resolutions = []
+    .concat(args.anchor_vout !== undefined ? [anchor] : [])
+    .concat(!!args.close_balance_spent_by ? [balance] : [])
+    .concat(htlcs);
+
+  return {
+    resolutions: sortByVout(resolutions).map(resolution => ({
+      transaction_id: resolution.transaction_id || undefined,
+      type: resolution.type,
+      value: resolution.value,
+    })),
+  };
+};

package/chain/closing_fees.js

@@ -1,51 +1,158 @@
 const {componentsOfTransaction} = require('@alexbosworth/blockchain');
 
+const closeFeePayer = require('./close_fee_payer');
+const linkPaymentStages = require('./link_payment_stages');
+const resolutionFee = require('./resolution_fee');
+
+const outputsOf = tx => componentsOfTransaction({transaction: tx}).outputs;
 const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const uniq = arr => Array.from(new Set(arr));
 
 /** Calculate channel closing fees paid
 
+  Fees are only returned when every fee that may have been paid is known.
+
+  Fees include the close transaction fee when it was paid by this side, the
+  fees of our own transactions that resolve the outputs of the close, and the
+  value of an anchor output that was never swept and so is lost.
+
+  When a resolving transaction also spends the outputs of other channels, the
+  fee is pro-rated by the weight of the inputs spending this channel's outputs.
+
   {
+    [anchor_is_confirmed]: <Anchor Sweep Is Confirmed Bool>
+    [anchor_is_pending]: <Anchor Sweep Is Pending Confirmation Bool>
+    [anchor_spent_by]: <Anchor Sweep Transaction Id Hex String>
+    [anchor_vout]: <Anchor Output Index Number>
     [capacity]: <Channel Capacity Tokens Number>
     [close_balance_spent_by]: <Close Balance Spent By Id Hex String>
+    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>
+    }]
     close_transaction_id: <Close Transaction Id Hex String>
-    is_partner_initiated: <Channel is Initiated By Peer Bool>
+    [is_cooperative_close]: <Channel Was Cooperatively Closed Bool>
+    [is_partner_closed]: <Channel Was Closed By Peer Bool>
+    [is_partner_initiated]: <Channel is Initiated By Peer Bool>
+    other_contract_outputs: [{
+      id: <Other Channel Contract Transaction Id Hex String>
+      [vout]: <Other Channel Contract Transaction Output Index Number>
+    }]
     transactions: [{
       [fee]: <Paid Transaction Fee Tokens Number>
+      id: <Transaction Id Hex String>
       [transaction]: <Raw Transaction Hex String>
     }]
   }
 
   @returns
   {
-    fees: <Closing Fees Paid Number>
+    [fees]: <Known Closing Fees Paid Tokens Number>
   }
 */
 module.exports = args => {
-  const closer = args.transactions
+  const [closeTx] = args.transactions
     .filter(n => !!n.transaction)
-    .find(n => n.id === args.close_transaction_id);
+    .filter(n => n.id === args.close_transaction_id);
+
+  const closeTransaction = !!closeTx ? closeTx.transaction : undefined;
+
+  const payer = closeFeePayer({
+    is_cooperative_close: args.is_cooperative_close,
+    is_partner_closed: args.is_partner_closed,
+    is_partner_initiated: args.is_partner_initiated,
+    transaction: closeTransaction,
+  });
+
+  // Exit early when it is not known which side paid the close tx fee
+  if (payer.is_peer_paying === undefined) {
+    return {};
+  }
+
+  // Payments resolved over two stages are linked to find their final status
+  const {payments} = linkPaymentStages({
+    close_payments: args.close_payments,
+    transactions: args.transactions,
+  });
+
+  // Exit early when a resolution is still pending, fees are not yet final
+  if (!!args.anchor_is_pending || !!payments.find(n => !!n.is_pending)) {
+    return {};
+  }
+
+  // Close outputs are spent in resolving transactions that may be our own
+  const ownSpends = args.close_payments
+    .filter(n => !!n.spent_by)
+    .filter(payment => {
+      // Exit early when the spend is a first stage second level transaction
+      if (!!payment.is_pending) {
+        return true;
+      }
+
+      return !!payment.is_outgoing ? !!payment.is_refunded : !!payment.is_paid;
+    })
+    .map(n => n.spent_by);
+
+  const resolvingIds = uniq([]
+    .concat(!!args.close_balance_spent_by ? [args.close_balance_spent_by] : [])
+    .concat(!!args.anchor_spent_by ? [args.anchor_spent_by] : [])
+    .concat(ownSpends));
 
-  const balanceSpend = args.transactions
-    .find(n => n.id === args.close_balance_spent_by);
+  // Close tx outputs and specific second level tx outputs are this channel's
+  const contractOutputs = []
+    .concat({id: args.close_transaction_id})
+    .concat(args.close_payments.map(payment => ({
+      id: payment.transaction_id,
+      vout: payment.transaction_vout,
+    })));
 
-  // Exit early when the partner was responsible for close fees
-  if (args.is_partner_initiated === true) {
-    return {fees: !!balanceSpend ? balanceSpend.fee : Number()};
+  const resolvingFees = resolvingIds.map(id => {
+    return resolutionFee({
+      id,
+      contract_outputs: contractOutputs,
+      other_contract_outputs: args.other_contract_outputs,
+      transactions: args.transactions,
+    }).fee;
+  });
+
+  // Exit early when the fee of a resolving transaction is not known
+  if (resolvingFees.includes(undefined)) {
+    return {};
   }
 
-  // Exit early when the closing transaction isn't known
-  if (!args.capacity || !closer || !closer.transaction) {
+  const closeOutputs = !closeTransaction ? [] : outputsOf(closeTransaction);
+
+  const anchor = closeOutputs[args.anchor_vout];
+
+  // An anchor output that was never swept is lost and counted as a fee
+  const isAnchorLost = args.anchor_vout !== undefined && !args.anchor_spent_by;
+
+  // Exit early when the value of a lost anchor output is not known
+  if (!!isAnchorLost && !anchor) {
     return {};
   }
 
-  // Calculate the value of the outputs in the tx that spends the capacity
-  const {outputs} = componentsOfTransaction({transaction: closer.transaction});
+  const lostTokens = !isAnchorLost ? Number() : anchor.tokens;
 
-  const outValue = sumOf(outputs.map(n => n.tokens));
+  const resolvingTokens = sumOf(resolvingFees) + lostTokens;
+
+  // Exit early when the peer paid the close tx fee
+  if (!!payer.is_peer_paying) {
+    return {fees: resolvingTokens};
+  }
+
+  // Exit early when the close tx fee was paid but the close tx is not known
+  if (!args.capacity || !closeTransaction) {
+    return {};
+  }
 
-  const fees = []
-    .concat(args.capacity - outValue)
-    .concat(!!balanceSpend ? balanceSpend.fee : Number());
+  const closeFee = args.capacity - sumOf(closeOutputs.map(n => n.tokens));
 
-  return {fees: sumOf(fees)};
+  return {fees: closeFee + resolvingTokens};
 };

package/chain/contract_outputs.js

@@ -0,0 +1,30 @@
+/** Derive the contract outputs of a channel from its close details
+
+  The outputs of the close transaction all belong to the channel, while HTLC
+  outputs are referred to specifically as a second level transaction may be
+  shared with other channels.
+
+  {
+    [close_transaction_id]: <Close Transaction Id Hex String>
+    payments: [{
+      transaction_id: <HTLC Transaction Id Hex String>
+      transaction_vout: <HTLC Transaction Output Index Number>
+    }]
+  }
+
+  @returns
+  [{
+    id: <Contract Transaction Id Hex String>
+    [vout]: <Contract Transaction Output Index Number>
+  }]
+*/
+module.exports = args => {
+  const id = args.close_transaction_id;
+
+  const closeOutputs = !id ? [] : [{id}];
+
+  return closeOutputs.concat(args.payments.map(payment => ({
+    id: payment.transaction_id,
+    vout: payment.transaction_vout,
+  })));
+};

package/chain/funded_outputs.js

@@ -0,0 +1,58 @@
+const splitFee = require('./split_fee');
+
+const minimumOutputCount = 1;
+
+/** Count the split outputs that selected inputs can fund to reach a count
+
+  Every counted utxo that is spent has to be replaced by a new utxo
+
+  {
+    counted: <Spending Counted UTXOs Count Number>
+    inputs: <Spending Inputs Count Number>
+    needed: <Needed Additional UTXOs Count Number>
+    rate: <Fee Tokens Per Virtual Byte Number>
+    size: <Split Output Tokens Number>
+    tokens: <Spending Inputs Tokens Number>
+    vbytes: <Spending Inputs Virtual Bytes Number>
+  }
+
+  @returns
+  {
+    [outputs]: <Split Outputs Count Number>
+  }
+*/
+module.exports = args => {
+  const outputs = args.needed + args.counted;
+
+  // When the change is large enough it can be one of the new utxos
+  const withChange = outputs - minimumOutputCount;
+
+  const changeFee = splitFee({
+    has_change: true,
+    inputs: args.inputs,
+    outputs: withChange,
+    rate: args.rate,
+    vbytes: args.vbytes,
+  });
+
+  const change = args.tokens - (withChange * args.size) - changeFee;
+
+  // Exit early when the change will be large enough to count as a new utxo
+  if (withChange >= minimumOutputCount && change >= args.size) {
+    return {outputs: withChange};
+  }
+
+  const fee = splitFee({
+    outputs,
+    inputs: args.inputs,
+    rate: args.rate,
+    vbytes: args.vbytes,
+  });
+
+  // Exit early when the inputs cannot pay for all of the outputs
+  if (args.tokens < (outputs * args.size) + fee) {
+    return {};
+  }
+
+  return {outputs};
+};

package/chain/funding_keys.js

@@ -0,0 +1,59 @@
+const {scriptAsScriptElements} = require('@alexbosworth/blockchain');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const fundingScriptElementsCount = 5;
+const {isBuffer} = Buffer;
+const OP_2 = 82;
+const OP_CHECKMULTISIG = 174;
+const publicKeyByteLength = 33;
+
+/** Derive the funding public keys from the witness of the funding output spend
+
+  A close transaction spends the funding output with a 2 of 2 multisig witness
+  script that commits to both funding public keys.
+
+  {
+    [witness]: [<Witness Stack Element Hex String>]
+  }
+
+  @returns
+  {
+    [keys]: [<Funding Public Key Hex String>]
+  }
+*/
+module.exports = ({witness}) => {
+  // Exit early when there is no witness script to look at
+  if (!witness || !witness.length) {
+    return {};
+  }
+
+  const [script] = [].concat(witness).reverse();
+
+  // Witness elements are always hex, a malformed script has no elements
+  const {elements} = scriptAsScriptElements({script});
+
+  // Exit early when the script is not shaped like a 2 of 2 multisig
+  if (!elements || elements.length !== fundingScriptElementsCount) {
+    return {};
+  }
+
+  const [op2, key1, key2, op2Again, opCheckMultisig] = elements;
+
+  // Exit early when the script is not a 2 of 2 multisig
+  if (op2 !== OP_2 || op2Again !== OP_2) {
+    return {};
+  }
+
+  if (opCheckMultisig !== OP_CHECKMULTISIG) {
+    return {};
+  }
+
+  const keys = [key1, key2];
+
+  // Exit early when the keys are not public keys
+  if (!!keys.find(n => !isBuffer(n) || n.length !== publicKeyByteLength)) {
+    return {};
+  }
+
+  return {keys: keys.map(bufferAsHex)};
+};