balanceofsatoshis 24.2.2 → 25.0.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Versions
 
+## 25.0.0
+
+- `pending`: Add command to show pending channels and in-flight HTLCs
+
+### Breaking Changes
+
+- Remove `price` command
+
 ## 24.2.2
 
 - `open`: Adhere to BIP 69 when ordering funding outputs with equal amounts

package/README.md

@@ -147,8 +147,8 @@ bos pay "payment_request"
 # Show channel-connected peers
 bos peers
 
-# Output the price of BTC
-bos price
+# Show pending channels and in-flight HTLCs
+bos pending
 
 # Test if funds can be sent to a destination
 bos probe "payment_request/public_key"

package/bos

@@ -14,7 +14,6 @@ const {writeFile} = require('fs');
 const importLazy = require('import-lazy')(require);
 
 const accounting = importLazy('ln-accounting');
-const fiat = importLazy('@alexbosworth/fiat');
 const lnService = importLazy('ln-service');
 const lnSync = importLazy('ln-sync');
 const paidServices = importLazy('paid-services');
@@ -1613,28 +1612,28 @@ prog
     });
   })
 
-  // Get the current fiat exchange price
-  .command('price', 'Get the price')
-  .help('Price is denominated in cents or equivalent')
-  .help('Rate provider options: coinbase, coindesk, or coingecko')
-  .argument('[symbols...]', 'Desired fiat tickers')
-  .option('--file <path>', 'Write the output to a JSON file at desired path')
-  .option('--from <provider>', 'Rate provider', priceProviders, 'coindesk')
+  // Get pending channels and in-flight HTLCs
+  .command('pending', 'Show pending channels and in-flight HTLCs')
+  .help('Channels waiting to open or close, forwarding and probing HTLCs')
+  .help('Multiple --node arguments are supported to show items across nodes')
+  .help('Use --verbose to also show the raw details of the pending items')
+  .option('--show-relays <count>', 'Relaying peers to show in paths', INT, 0)
   .option('--no-color', 'Mute all colors')
+  .option('--node <node_name>', 'Node to get pending items for', REPEATABLE)
   .action((args, options, logger) => {
-    return new Promise((resolve, reject) => {
-      return fiat.getPrices({
-        from: options.from,
-        request: commands.simpleRequest,
-        symbols: args.symbols.map(n => n.toUpperCase()),
-      },
-      responses.returnObject({
-        logger,
-        reject,
-        resolve,
-        file: options.file,
-        write: writeFile,
-      }));
+    return new Promise(async (resolve, reject) => {
+      try {
+        return network.getPending({
+          logger,
+          fs: {getFile: readFile},
+          is_monochrome: !!options.noColor,
+          lnds: (await lnd.getLnds({logger, nodes: options.node})).lnds,
+          max_relays: options.showRelays,
+        },
+        responses.returnOutput({logger, reject, resolve}));
+      } catch (err) {
+        return logger.error({err}) && reject();
+      }
     });
   })
 

package/commands/interrogate.js

@@ -1,3 +1,6 @@
+const exitCodeSigint = 130;
+const isForceClose = err => !!err && err.name === 'ExitPromptError';
+
 /** Get ask function
 
   {}
@@ -9,6 +12,17 @@ module.exports = ({}) => {
   return new Promise(async resolve => {
     const inquirer = (await import('inquirer')).default;
 
-    return resolve((n, cbk) => inquirer.prompt([n]).then(res => cbk(res)));
+    return resolve((n, cbk) => {
+      return inquirer.prompt([n])
+        .then(res => cbk(res))
+        .catch(err => {
+          // Exit quietly when the user presses ctrl+c
+          if (isForceClose(err)) {
+            return process.exit(exitCodeSigint);
+          }
+
+          throw err;
+        });
+    });
   });
 };

package/network/get_node_pending.js

@@ -0,0 +1,329 @@
+const asyncAuto = require('async/auto');
+const asyncMap = require('async/map');
+const {getChannels} = require('ln-service');
+const {getNodeAlias} = require('ln-sync');
+const {getPendingChannels} = require('ln-service');
+const {getWalletInfo} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const getPendingPaths = require('./get_pending_paths');
+const pendingPayments = require('./pending_payments');
+const {sortBy} = require('./../arrays');
+
+const flatten = arr => [].concat(...arr);
+const lookupTimeoutMs = 1000 * 10;
+const uniq = arr => Array.from(new Set(arr));
+
+/** Get pending channels and in-flight HTLCs for a node
+
+  Items are sorted oldest first, by their creation time when it is known and
+  otherwise by the blocks remaining until they resolve
+
+  Debug details of pending channels, HTLCs and payments are logged in verbose
+
+  {
+    lnd: <Authenticated LND API Object>
+    logger: <Winston Logger Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    closing: [{
+      [blocks_until_recovery]: <Blocks Until Pending Balance Recovers Number>
+      [close_transaction_id]: <Closing Transaction Id Hex String>
+      [peer_alias]: <Peer Alias String>
+      peer_public_key: <Peer Public Key Hex String>
+      [pending_balance]: <Pending Recovery Tokens Number>
+    }]
+    forwarding: [{
+      fee: <Routing Fee Tokens Number>
+      [in_peer_alias]: <Inbound Peer Alias String>
+      in_peer_public_key: <Inbound Peer Public Key Hex String>
+      [out_peer_alias]: <Outbound Peer Alias String>
+      out_peer_public_key: <Outbound Peer Public Key Hex String>
+      tokens: <Forwarding Tokens Number>
+    }]
+    opening: [{
+      capacity: <Channel Capacity Tokens Number>
+      is_partner_initiated: <Peer Is Opening The Channel Bool>
+      [peer_alias]: <Peer Alias String>
+      peer_public_key: <Peer Public Key Hex String>
+      transaction_id: <Funding Transaction Id Hex String>
+    }]
+    sending: [{
+      [fee]: <Routing Fee Tokens Number>
+      hops: [{
+        [alias]: <Hop Node Alias String>
+        public_key: <Hop Node Public Key Hex String>
+      }]
+      is_rebalance: <Payment Is Going Back To The Node Itself Bool>
+      tokens: <Sending Tokens Number>
+    }]
+    [alias]: <Node Alias String>
+    public_key: <Node Identity Public Key Hex String>
+  }
+*/
+module.exports = ({lnd, logger}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetNodePendingItems']);
+        }
+
+        if (!logger) {
+          return cbk([400, 'ExpectedLoggerToGetNodePendingItems']);
+        }
+
+        return cbk();
+      },
+
+      // Get channels to look for in-flight HTLCs
+      getChannels: ['validate', ({}, cbk) => getChannels({lnd}, cbk)],
+
+      // Get the node identity
+      getInfo: ['validate', ({}, cbk) => getWalletInfo({lnd}, cbk)],
+
+      // Get pending channels
+      getPending: ['validate', ({}, cbk) => getPendingChannels({lnd}, cbk)],
+
+      // Derive the HTLCs that are forwarding or sending
+      htlcs: ['getChannels', ({getChannels}, cbk) => {
+        return cbk(null, pendingPayments({channels: getChannels.channels}));
+      }],
+
+      // Look up the in-flight payments behind the outgoing HTLCs
+      getPayments: ['htlcs', ({htlcs}, cbk) => {
+        return asyncMap(uniq(htlcs.sending.map(n => n.id)), (id, cbk) => {
+          return getPendingPaths({id, lnd, timeout_ms: lookupTimeoutMs}, cbk);
+        },
+        cbk);
+      }],
+
+      // Log the raw details behind the pending items for debugging
+      debug: [
+        'getPayments',
+        'getPending',
+        'htlcs',
+        ({getPayments, getPending, htlcs}, cbk) =>
+      {
+        const hasHtlcs = !!htlcs.forwarding.length || !!htlcs.sending.length;
+
+        // Exit early when there is nothing pending to debug
+        if (!hasHtlcs && !getPending.pending_channels.length) {
+          return cbk();
+        }
+
+        logger.debug({
+          forwarding_htlcs: htlcs.forwarding,
+          outgoing_htlcs: htlcs.sending,
+          payments: getPayments.map(payment => ({
+            id: payment.id,
+            created_at: payment.created_at,
+            paths: payment.paths.map(path => ({
+              hops: path.hops.map(hop => `${hop.channel} ${hop.public_key}`),
+              timeout: path.timeout,
+              tokens: path.tokens,
+            })),
+          })),
+          pending_channels: getPending.pending_channels.map(channel => ({
+            blocks_until_expiry: channel.blocks_until_expiry,
+            capacity: channel.capacity,
+            close_transaction_id: channel.close_transaction_id,
+            is_closing: channel.is_closing,
+            is_opening: channel.is_opening,
+            is_partner_initiated: channel.is_partner_initiated,
+            is_timelocked: channel.is_timelocked,
+            local_balance: channel.local_balance,
+            partner_public_key: channel.partner_public_key,
+            pending_balance: channel.pending_balance,
+            pending_payments: channel.pending_payments,
+            remote_balance: channel.remote_balance,
+            timelock_blocks: channel.timelock_blocks,
+            timelock_expiration: channel.timelock_expiration,
+            transaction_id: channel.transaction_id,
+            transaction_vout: channel.transaction_vout,
+          })),
+        });
+
+        return cbk();
+      }],
+
+      // Outgoing HTLCs are matched to the paths of their in-flight payments
+      routes: ['getPayments', 'htlcs', ({getPayments, htlcs}, cbk) => {
+        const paths = flatten(getPayments.map(payment => {
+          return payment.paths.map(path => ({
+            path,
+            created_at: payment.created_at,
+            id: payment.id,
+          }));
+        }));
+
+        // Every path can only be the route of a single outgoing HTLC
+        const {routes} = htlcs.sending.reduce((sum, htlc) => {
+          // An HTLC has the hash, first hop, amount and expiry of its route
+          const match = sum.unmatched.find(({id, path}) => {
+            const [firstHop] = path.hops;
+
+            const isSameAmount = path.tokens === htlc.tokens;
+            const isSameExpiry = path.timeout === htlc.timeout;
+            const isSameHash = id === htlc.id;
+            const isSameOutPeer = firstHop.public_key === htlc.out_peer;
+
+            return isSameHash && isSameAmount && isSameExpiry && isSameOutPeer;
+          });
+
+          // Exit early when there are no payment details for the HTLC
+          if (!match) {
+            const hop = {forward: htlc.tokens, public_key: htlc.out_peer};
+
+            return {
+              routes: sum.routes.concat({hops: [hop]}),
+              unmatched: sum.unmatched,
+            };
+          }
+
+          const route = {
+            created_at: match.created_at,
+            fee: match.path.fee,
+            hops: match.path.hops,
+          };
+
+          return {
+            routes: sum.routes.concat(route),
+            unmatched: sum.unmatched.filter(n => n !== match),
+          };
+        },
+        {routes: [], unmatched: paths});
+
+        return cbk(null, routes);
+      }],
+
+      // Get the aliases of the peers involved in pending items
+      getAliases: [
+        'getPending',
+        'htlcs',
+        'routes',
+        ({getPending, htlcs, routes}, cbk) =>
+      {
+        const hops = flatten(routes.map(n => n.hops));
+
+        const peers = []
+          .concat(getPending.pending_channels.map(n => n.partner_public_key))
+          .concat(htlcs.forwarding.map(n => n.in_peer))
+          .concat(htlcs.forwarding.map(n => n.out_peer))
+          .concat(hops.map(n => n.public_key));
+
+        return asyncMap(uniq(peers), (id, cbk) => {
+          return getNodeAlias({id, lnd}, cbk);
+        },
+        cbk);
+      }],
+
+      // Assemble the pending items
+      pending: [
+        'getAliases',
+        'getInfo',
+        'getPending',
+        'htlcs',
+        'routes',
+        ({getAliases, getInfo, getPending, htlcs, routes}, cbk) =>
+      {
+        const alias = id => {
+          return getAliases.find(n => n.id === id).alias || undefined;
+        };
+
+        const pending = getPending.pending_channels;
+
+        // Closes waiting on a timelock are ordered by their remaining blocks
+        const timelocked = sortBy({
+          array: pending.filter(n => !!n.is_closing && !!n.is_timelocked),
+          attribute: 'timelock_blocks',
+        });
+
+        // Closes that are not timelocked yet are the newest closes
+        const waiting = pending.filter(n => n.is_closing && !n.is_timelocked);
+
+        const closes = [].concat(timelocked.sorted).concat(waiting);
+
+        // Channels that are closing, which may be waiting on funds recovery
+        const closing = closes.map(channel => {
+          // A timelock may hold the funds for some blocks before recovery
+          const blocks = channel.timelock_blocks || Number();
+
+          return {
+            blocks_until_recovery: blocks > Number() ? blocks : undefined,
+            close_transaction_id: channel.close_transaction_id,
+            peer_alias: alias(channel.partner_public_key),
+            peer_public_key: channel.partner_public_key,
+            pending_balance: channel.pending_balance || undefined,
+          };
+        });
+
+        // HTLCs that are being relayed from one peer to another
+        const forwards = sortBy({
+          array: htlcs.forwarding,
+          attribute: 'timeout',
+        });
+
+        const forwarding = forwards.sorted.map(forward => ({
+          fee: forward.fee,
+          in_peer_alias: alias(forward.in_peer),
+          in_peer_public_key: forward.in_peer,
+          out_peer_alias: alias(forward.out_peer),
+          out_peer_public_key: forward.out_peer,
+          tokens: forward.tokens,
+        }));
+
+        // Channels that are waiting for funding confirmation
+        const opens = sortBy({
+          array: pending.filter(n => !!n.is_opening),
+          attribute: 'blocks_until_expiry',
+        });
+
+        const opening = opens.sorted.map(channel => ({
+          capacity: channel.capacity,
+          is_partner_initiated: channel.is_partner_initiated,
+          peer_alias: alias(channel.partner_public_key),
+          peer_public_key: channel.partner_public_key,
+          transaction_id: channel.transaction_id,
+        }));
+
+        // Payments with known creation dates are ordered by their dates
+        const dated = sortBy({
+          array: routes.filter(n => !!n.created_at),
+          attribute: 'created_at',
+        });
+
+        // HTLCs that have no payment details are the newest payments
+        const undated = routes.filter(n => !n.created_at);
+
+        // Payments or probes that are going out through peers
+        const sending = [].concat(dated.sorted).concat(undated).map(route => {
+          const [finalHop] = route.hops.slice().reverse();
+
+          return {
+            fee: route.fee,
+            hops: route.hops.map(hop => ({
+              alias: alias(hop.public_key),
+              public_key: hop.public_key,
+            })),
+            is_rebalance: finalHop.public_key === getInfo.public_key,
+            tokens: finalHop.forward,
+          };
+        });
+
+        return cbk(null, {
+          closing,
+          forwarding,
+          opening,
+          sending,
+          alias: getInfo.alias || undefined,
+          public_key: getInfo.public_key,
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'pending'}, cbk));
+  });
+};

package/network/get_pending.js

@@ -0,0 +1,81 @@
+const asyncAuto = require('async/auto');
+const asyncMap = require('async/map');
+const {returnResult} = require('asyncjs-util');
+
+const {getIcons} = require('./../display');
+const getNodePending = require('./get_node_pending');
+const pendingSummary = require('./pending_summary');
+
+const {isArray} = Array;
+
+/** Get a summary of pending channels and in-flight HTLCs
+
+  When there are multiple nodes, pending items are grouped by node
+
+  {
+    fs: {
+      getFile: <Read File Contents Function> (path, cbk) => {}
+    }
+    [is_monochrome]: <Mute Colors Bool>
+    lnds: [<Authenticated LND API Object>]
+    logger: <Winston Logger Object>
+    [max_relays]: <Maximum Relaying Peers of a Path to Show Number>
+  }
+
+  @returns via cbk or Promise
+  <Pending Items Summary String>
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!args.fs) {
+          return cbk([400, 'ExpectedFileSystemMethodsToGetPendingItems']);
+        }
+
+        if (!isArray(args.lnds)) {
+          return cbk([400, 'ExpectedArrayOfLndsToGetPendingItems']);
+        }
+
+        if (!args.lnds.length) {
+          return cbk([400, 'ExpectedAnLndToGetPendingItems']);
+        }
+
+        if (!args.logger) {
+          return cbk([400, 'ExpectedLoggerToGetPendingItems']);
+        }
+
+        if (args.max_relays !== undefined && args.max_relays < 0) {
+          return cbk([400, 'ExpectedNonNegativeMaxRelaysCountToShow']);
+        }
+
+        return cbk();
+      },
+
+      // Get the tag icons for nodes
+      getIcons: ['validate', ({}, cbk) => getIcons({fs: args.fs}, cbk)],
+
+      // Get the pending items for every node
+      getNodes: ['validate', ({}, cbk) => {
+        return asyncMap(args.lnds, (lnd, cbk) => {
+          return getNodePending({lnd, logger: args.logger}, cbk);
+        },
+        cbk);
+      }],
+
+      // Summarize the pending items
+      summary: ['getIcons', 'getNodes', ({getIcons, getNodes}, cbk) => {
+        const {summary} = pendingSummary({
+          is_monochrome: args.is_monochrome,
+          max_relays: args.max_relays,
+          nodes: getNodes,
+          tagged: getIcons.nodes,
+        });
+
+        return cbk(null, summary);
+      }],
+    },
+    returnResult({reject, resolve, of: 'summary'}, cbk));
+  });
+};

package/network/get_pending_paths.js

@@ -0,0 +1,96 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+const {subscribeToPastPayment} = require('ln-service');
+
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const notFound = 404;
+
+/** Get the pending paths of an in-flight payment
+
+  {
+    id: <Payment Hash Hex String>
+    lnd: <Authenticated LND API Object>
+    timeout_ms: <Give Up Waiting For Payment Details After Milliseconds Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    [created_at]: <Payment Created At ISO 8601 Date String>
+    id: <Payment Hash Hex String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        forward: <Forward Tokens Number>
+        public_key: <Public Key Hex String>
+      }]
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Tokens Pending Number>
+    }]
+  }
+*/
+module.exports = ({id, lnd, timeout_ms}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isHash(id)) {
+          return cbk([400, 'ExpectedPaymentHashToGetPendingPaths']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetPendingPaths']);
+        }
+
+        if (!timeout_ms) {
+          return cbk([400, 'ExpectedTimeoutMillisecondsToGetPendingPaths']);
+        }
+
+        return cbk();
+      },
+
+      // Subscribe to the payment to get its current state
+      getPaths: ['validate', ({}, cbk) => {
+        const sub = subscribeToPastPayment({id, lnd});
+
+        // Removing the listeners cancels the subscription to the payment
+        const finished = (err, res) => {
+          clearTimeout(timeout);
+
+          sub.removeAllListeners();
+
+          return cbk(err, res);
+        };
+
+        // Payments that are not in flight have no pending paths
+        const noPaths = () => finished(null, {id, paths: []});
+
+        const timeout = setTimeout(noPaths, timeout_ms);
+
+        sub.once('confirmed', noPaths);
+        sub.once('end', noPaths);
+        sub.once('failed', noPaths);
+
+        sub.once('error', err => {
+          // Exit early when the payment is not a known payment
+          if (err[0] === notFound) {
+            return noPaths();
+          }
+
+          return finished(err);
+        });
+
+        sub.once('paying', pending => {
+          return finished(null, {
+            id,
+            created_at: pending.created_at,
+            paths: pending.paths,
+          });
+        });
+
+        return;
+      }],
+    },
+    returnResult({reject, resolve, of: 'getPaths'}, cbk));
+  });
+};

package/network/index.js

@@ -3,6 +3,7 @@ const executeProbe = require('./execute_probe');
 const getForwards = require('./get_forwards');
 const getGraphEntry = require('./get_graph_entry');
 const getPeers = require('./get_peers');
+const getPending = require('./get_pending');
 const multiPathPayment = require('./multi_path_payment');
 const multiPathProbe = require('./multi_path_probe');
 const networks = require('./networks');
@@ -24,6 +25,7 @@ module.exports = {
   getForwards,
   getGraphEntry,
   getPeers,
+  getPending,
   multiPathPayment,
   multiPathProbe,
   networks,