balanceofsatoshis 25.5.0 → 25.6.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 25.6.0
+
+- `stream`: Add command to stream a payment to a lnurl or lightning address
+
 ## 25.5.0
 
 - `probe`: Add `--ignore-expiry` to probe expired payment requests

package/README.md

@@ -168,6 +168,9 @@ bos send
 # Run a server of paid services
 bos server
 
+# Stream a payment to a lnurl or lightning address in a series of payments
+bos stream "amount" --lnurl "lnurl/lightning_address"
+
 # Connect up to a Telegram bot
 bos telegram
 

package/bos

@@ -1954,6 +1954,53 @@ prog
     });
   })
 
+  // Stream a payment in a series of payments
+  .command('stream', 'Stream a payment in a series of payments')
+  .help('Each payment is sized to the most a single route can carry')
+  .help('--lnurl is required, it can stream above the max the service takes')
+  .help('--min-payment defaults to 100*k, a smaller remainder is not sent')
+  .help('--out can take a tag to make the first hop through any tagged peer')
+  .help('--out-filter is checked before every payment, skipping failing peers')
+  .help('--out-filter vars: CAPACITY/HEIGHTS/INBOUND_LIQUIDITY')
+  .help('--out-filter vars: OUTBOUND_LIQUIDITY/PENDING_PAYMENTS')
+  .help('--out-filter vars: INBOUND_BASE_FEE/INBOUND_FEE_RATE')
+  .help('Amounts can take m/k variables: 5*m for 5 million, 250*k = 0.0025')
+  .argument('<amount>', 'Total amount to stream')
+  .option('--avoid <avoid>', 'Avoid forwarding via node/chan/tag', REPEATABLE)
+  .option('--lnurl <url>', 'Lnurl/lightning address', STRING, undefined, true)
+  .option('--max-fee <max_fee>', 'Maximum total fee to pay', STRING, '1337')
+  .option('--max-fee-rate <ppm>', 'Max fee rate for all payments', INT, 1000)
+  .option('--max-payment <amount>', 'Largest single payment to make', STRING)
+  .option('--min-payment <amount>', 'Smallest single payment to make', STRING)
+  .option('--no-color', 'Mute all colors')
+  .option('--node <node_name>', 'Node to stream from')
+  .option('--out <peer_or_tag>', 'Make first hop through peer/tag', REPEATABLE)
+  .option('--out-filter <out_filter>', 'Filter outbound peer/tag', REPEATABLE)
+  .action((args, options, logger) => {
+    return new Promise(async (resolve, reject) => {
+      try {
+        return network.streamPayment({
+          logger,
+          amount: args.amount,
+          avoid: flatten([options.avoid].filter(n => !!n)),
+          fs: {getFile: readFile},
+          lnd: (await lndForNode(logger, options.node)).lnd,
+          lnurl: options.lnurl,
+          max_fee: options.maxFee,
+          max_fee_rate: options.maxFeeRate,
+          max_payment: options.maxPayment,
+          min_payment: options.minPayment,
+          out: flatten([options.out].filter(n => !!n)),
+          out_filters: flatten([options.outFilter].filter(n => !!n)),
+          request: commands.simpleRequest,
+        },
+        responses.returnObject({logger, reject, resolve}));
+      } catch (err) {
+        return logger.error({err}) && reject();
+      }
+    });
+  })
+
   // Get a swap API key or inspect an existing one
   .command('swap-api-key', 'Purchase a swap API key or inspect a swap API key')
   .visible(false)

package/display/describe_routing_failure.js

@@ -108,6 +108,7 @@ module.exports = ({index, lnd, reason, route, tagged}, cbk) => {
 
         const {display} = chartAliasForPeer({
           alias: getTo.alias,
+          icons: !!tag ? tag.icons : undefined,
           public_key: getTo.id,
         });
 
@@ -120,11 +121,14 @@ module.exports = ({index, lnd, reason, route, tagged}, cbk) => {
         'toName',
         ({fromName, toName}, cbk) =>
       {
-        const at = `on ${route.hops[index].channel}`;
+        const hop = route.hops[index];
+
+        // A failure at the destination is not on a channel out of it
+        const at = !hop ? '' : ` on ${hop.channel}`;
         const from = !fromName ? '' : `from ${fromName}`;
         const to = !toName ? '' : ` forwarding to ${toName}`;
 
-        return cbk(null, {description: `${reason} ${from} ${at}${to}`});
+        return cbk(null, {description: `${reason} ${from}${at}${to}`});
       }],
     },
     returnResult({reject, resolve, of: 'description'}, cbk));

package/lnurl/get_pay_request.js

@@ -3,6 +3,7 @@ const {parsePaymentRequest} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
 
 const errorStatus = 'ERROR';
+const timeoutMs = 1000 * 60;
 
 /** Get a payment request for a LNURL
 
@@ -45,9 +46,13 @@ module.exports = ({hash, mtokens, request, url}, cbk) => {
 
       // Get the payment request
       getRequest: ['validate', ({}, cbk) => {
-        const qs = {amount: mtokens};
-
-        return request({qs, url, json: true}, (err, r, json) => {
+        return request({
+          url,
+          json: true,
+          qs: {amount: mtokens},
+          timeout: timeoutMs,
+        },
+        (err, r, json) => {
           if (!!err) {
             return cbk([503, 'FailedToGetPaymentRequestFromService', {err}]);
           }

package/lnurl/get_pay_terms.js

@@ -15,6 +15,7 @@ const payRequestTag = 'payRequest';
 const sha256 = n => createHash('sha256').update(n).digest().toString('hex');
 const sslProtocol = 'https:';
 const textPlain = 'text/plain';
+const timeoutMs = 1000 * 60;
 const utf8AsBuffer = utf8 => Buffer.from(utf8, 'utf8');
 
 /** Get payment terms
@@ -51,7 +52,12 @@ module.exports = ({request, url}, cbk) => {
 
       // Get payment terms
       getTerms: ['validate', ({}, cbk) => {
-        return request({url, json: true}, (err, r, json) => {
+        return request({
+          url,
+          json: true,
+          timeout: timeoutMs,
+        },
+        (err, r, json) => {
           if (!!err) {
             return cbk([503, 'FailureGettingLnUrlDataFromUrl', {err}]);
           }
@@ -100,14 +106,17 @@ module.exports = ({request, url}, cbk) => {
             return cbk([503, 'ExpectedMetadataArrayInLnurlResponse', json]);
           }
 
-          const [, description] = parse(json.metadata)
+          const textEntry = parse(json.metadata)
             .filter(isArray)
             .find(([entry, text]) => entry === textPlain && !!text);
 
-          if (!description) {
+          // Exit early when there is no text/plain entry to describe the terms
+          if (!textEntry) {
             return cbk([503, 'ExpectedTextPlainEntryInLnurlResponse']);
           }
 
+          const [, description] = textEntry;
+
           if (!isNumber(json.minSendable)) {
             return cbk([503, 'ExpectedNumericValueForMinSendable']);
           }

package/lnurl/parse_url.js

@@ -3,9 +3,9 @@ const {bech32} = require('bech32');
 const asLnurl = n => n.substring(n.startsWith('lightning:') ? 10 : 0);
 const bech32CharLimit = 2000;
 const {decode} = bech32;
-const isEmail = n => /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$/.test(n);
+const isEmail = n => /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(n);
 const isOnion = n => /.onion$/.test(n);
-const isUsername = n => /^[a-z0-9_.]*$/.test(n);
+const isUsername = n => /^[a-z0-9_.-]*$/.test(n);
 const join = arr => arr.join('');
 const parseEmail = email => email.split('@');
 const prefix = 'lnurl';
@@ -46,7 +46,14 @@ module.exports = ({url}) => {
       throw new Error('LnurlOnionUrlsCurrentlyUnsupported');
     }
 
-    return {url: join([sslProtocol, domain, urlString, username])};
+    const addressUrl = join([sslProtocol, domain, urlString, username]);
+
+    // Exit with error when the lightning address does not make a valid URL
+    if (!URL.canParse(addressUrl)) {
+      throw new Error('ExpectedValidUrlForLightningAddress');
+    }
+
+    return {url: addressUrl};
   }
 
   if (decode(asLnurl(url), bech32CharLimit).prefix !== prefix) {
@@ -55,5 +62,12 @@ module.exports = ({url}) => {
 
   const {words} = decode(asLnurl(url), bech32CharLimit);
 
-  return {url: wordsAsUtf8(words)};
+  const decoded = wordsAsUtf8(words);
+
+  // Exit with error when the lnurl does not hold a valid URL
+  if (!URL.canParse(decoded)) {
+    throw new Error('ExpectedValidUrlInLnurl');
+  }
+
+  return {url: decoded};
 };

package/network/constants.json

@@ -2,6 +2,7 @@
   "emojiIcons": {
     "disabled": "🚫"
   },
+  "minStreamPaymentTokens": 100000,
   "peerSortOptions": [
     "alias",
     "fee_earnings",

package/network/execute_probe.js

@@ -1,13 +1,10 @@
 const asyncAuto = require('async/auto');
-const asyncMapSeries = require('async/mapSeries');
-const {getNode} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
-const {subscribeToProbe} = require('ln-service');
 const {subscribeToProbeForRoute} = require('ln-service');
 
-const {describeConfidence} = require('./../display');
 const {describeRoute} = require('./../display');
 const {describeRoutingFailure} = require('./../display');
+const lineWriter = require('./line_writer');
 
 const {now} = Date;
 const minutesAsMs = minutes => 1000 * 60 * minutes;
@@ -189,10 +186,14 @@ module.exports = (args, cbk) => {
           return cbk([400, 'FailedToStartProbeForRoute', {err}]);
         }
 
+        // Lines are written in the order of events, and all before finishing
+        const lines = lineWriter({logger: args.logger});
+
         const finished = (err, res) => {
           sub.removeAllListeners();
 
-          return cbk(err, res);
+          // Wait for lines that are being written so that they are not lost
+          return lines.wait().then(() => cbk(err, res));
         };
 
         // Finish without success
@@ -204,12 +205,12 @@ module.exports = (args, cbk) => {
         sub.on('error', err => finished(err));
 
         // Log failures encountered while trying to find a route
-        sub.on('routing_failure', async failure => {
+        sub.on('routing_failure', failure => {
           if (!!args.log_failure) {
             args.log_failure(null, failure);
           }
 
-          const {description} = await describeRoutingFailure({
+          const described = describeRoutingFailure({
             index: failure.index,
             lnd: args.lnd,
             reason: failure.reason,
@@ -217,7 +218,7 @@ module.exports = (args, cbk) => {
             tagged: args.tagged,
           });
 
-          return args.logger.info({failure: description});
+          return lines.write(described.then(n => ({failure: n.description})));
         });
 
         // Finish with successful probe
@@ -233,16 +234,18 @@ module.exports = (args, cbk) => {
         });
 
         // Log probing attempts
-        sub.on('probing', async ({route}) => {
+        sub.on('probing', ({route}) => {
           attemptedPaths.push(route);
 
-          const {description} = await describeRoute({
+          const described = describeRoute({
             route,
             lnd: args.lnd,
             tagged: args.tagged || undefined,
           });
 
-          return args.logger.info({evaluating: description});
+          const line = described.then(n => ({evaluating: n.description}));
+
+          return lines.write(line);
         });
 
         return;

package/network/get_out_channels.js

@@ -0,0 +1,128 @@
+const asyncAuto = require('async/auto');
+const asyncMapSeries = require('async/mapSeries');
+const asyncReflect = require('async/reflect');
+const {getChannels} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const getOutPeers = require('./get_out_peers');
+
+const flatten = arr => [].concat(...arr);
+const inactiveTagError = 'NoActivePeersFoundForOutTag';
+const {isArray} = Array;
+const noMatchError = 'NoPeerMatchesFoundToSatisfyOutboundFilter';
+const uniq = arr => Array.from(new Set(arr));
+
+/** Get the channels to route out through, applying out filters
+
+  Out peers that fail the filters or have no active channel are left out
+
+  {
+    [filters]: [<Outbound Peer Filter Formula String>]
+    [fs]: {
+      getFile: <Read File Contents Function> (path, cbk) => {}
+    }
+    lnd: <Authenticated LND API Object>
+    out: [<Out Through Peer With Public Key, Alias, or Tag String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    [channels]: [<Out Through Standard Format Channel Id String>]
+    public_keys: [<Out Through Peer Public Key Hex String>]
+  }
+*/
+module.exports = ({filters, fs, lnd, out}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetOutChannels']);
+        }
+
+        if (!isArray(out)) {
+          return cbk([400, 'ExpectedArrayOfOutPeersToGetOutChannels']);
+        }
+
+        // Filters narrow down out peers so there must be out peers to filter
+        if (!out.length && !!filters && !!filters.length) {
+          return cbk([400, noMatchError]);
+        }
+
+        return cbk();
+      },
+
+      // Find public keys to pay out through for each out peer or tag
+      getOuts: ['validate', ({}, cbk) => {
+        return asyncMapSeries(out, (query, cbk) => {
+          return asyncReflect(getOutPeers)({
+            filters,
+            fs,
+            lnd,
+            out: [query],
+          },
+          cbk);
+        },
+        cbk);
+      }],
+
+      // Out peers that pass the filters, leaving out the ones that do not and
+      // tags with no active peers
+      peers: ['getOuts', ({getOuts}, cbk) => {
+        const errors = getOuts.filter(n => !!n.error).map(n => n.error);
+        const leftOut = [inactiveTagError, noMatchError];
+
+        // An error other than an out peer being left out is passed back
+        const [err] = errors.filter(([, msg]) => !leftOut.includes(msg));
+
+        if (!!err) {
+          return cbk(err);
+        }
+
+        const found = getOuts.filter(n => !n.error).map(n => n.value);
+
+        return cbk(null, uniq(flatten(found.map(n => n.public_keys))));
+      }],
+
+      // Get channels with the out peers
+      getChannels: ['peers', ({}, cbk) => {
+        // Exit early when there is no outbound restriction
+        if (!out.length) {
+          return cbk();
+        }
+
+        return getChannels({lnd}, cbk);
+      }],
+
+      // Channels to go out through, with the out peers that have them
+      channels: ['getChannels', 'peers', ({getChannels, peers}, cbk) => {
+        // Exit early when there is no outbound restriction
+        if (!out.length) {
+          return cbk(null, {public_keys: []});
+        }
+
+        const withPeer = getChannels.channels
+          .filter(n => !!n.is_active)
+          .filter(n => peers.includes(n.partner_public_key));
+
+        // Exit with error when the filters left no out peer to go through
+        if (!withPeer.length && !!filters && !!filters.length) {
+          return cbk([400, noMatchError]);
+        }
+
+        // Exit with error when no out peer has an active channel
+        if (!withPeer.length) {
+          return cbk([404, 'NoActiveChannelWithOutgoingPeer']);
+        }
+
+        const keys = withPeer.map(n => n.partner_public_key);
+
+        return cbk(null, {
+          channels: withPeer.map(n => n.id),
+          public_keys: peers.filter(key => keys.includes(key)),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'channels'}, cbk));
+  });
+};

package/network/get_out_queries.js

@@ -0,0 +1,102 @@
+const asyncAuto = require('async/auto');
+const asyncMapSeries = require('async/mapSeries');
+const {findKey} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+
+const asKey = n => !n.public_key ? undefined : n.public_key.toLowerCase();
+const flatten = arr => [].concat(...arr);
+const {isArray} = Array;
+const uniq = arr => Array.from(new Set(arr));
+
+/** Get out queries with the aliases of out peers resolved to public keys
+
+  Tag queries are kept so that the peers of tags can be found again later
+
+  {
+    channels: [{
+      partner_public_key: <Peer Public Key Hex String>
+    }]
+    lnd: <Authenticated LND API Object>
+    out: [<Out Through Peer With Public Key, Alias, or Tag String>]
+    tags: [{
+      [alias]: <Tag Alias String>
+      id: <Tag Id Hex String>
+      nodes: [<Public Key Hex String>]
+    }]
+  }
+
+  @returns via cbk or Promise
+  {
+    public_keys: [<Out Peer Public Key Hex String>]
+    queries: [<Out Through Peer Public Key or Tag String>]
+  }
+*/
+module.exports = ({channels, lnd, out, tags}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isArray(channels)) {
+          return cbk([400, 'ExpectedArrayOfChannelsToGetOutQueries']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetOutQueries']);
+        }
+
+        if (!isArray(out)) {
+          return cbk([400, 'ExpectedArrayOfOutPeersToGetOutQueries']);
+        }
+
+        if (!isArray(tags)) {
+          return cbk([400, 'ExpectedArrayOfTagsToGetOutQueries']);
+        }
+
+        return cbk();
+      },
+
+      // Out queries with the tags that they match on alias or on id
+      outQueries: ['validate', ({}, cbk) => {
+        return cbk(null, out.map(n => String(n)).map(query => ({
+          query,
+          tags: tags.filter(tag => {
+            const alias = tag.alias || String();
+
+            const isAliasMatch = alias.toLowerCase() === query.toLowerCase();
+
+            return isAliasMatch || tag.id.startsWith(query);
+          }),
+        })));
+      }],
+
+      // Find the public keys of out peers, other than peers of tags
+      getKeys: ['outQueries', ({outQueries}, cbk) => {
+        return asyncMapSeries(outQueries, (outQuery, cbk) => {
+          // Exit early when the query is a tag, its peers are found later
+          if (!!outQuery.tags.length) {
+            return cbk(null, {});
+          }
+
+          return findKey({channels, lnd, query: outQuery.query}, cbk);
+        },
+        cbk);
+      }],
+
+      // Out queries with peer aliases replaced by peer public keys
+      queries: ['getKeys', 'outQueries', ({getKeys, outQueries}, cbk) => {
+        const keys = getKeys.map(asKey);
+        const peers = channels.map(n => n.partner_public_key);
+        const tagged = flatten(outQueries.map(n => n.tags));
+
+        // Out peers are the peers that are named and the peers in out tags
+        const outPeers = keys.concat(flatten(tagged.map(n => n.nodes)));
+
+        return cbk(null, {
+          public_keys: uniq(outPeers.filter(n => peers.includes(n))),
+          queries: outQueries.map((n, i) => keys[i] || n.query),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'queries'}, cbk));
+  });
+};

package/network/get_stream_invoice.js

@@ -0,0 +1,95 @@
+const asyncAuto = require('async/auto');
+const asyncReflect = require('async/reflect');
+const {formatTokens} = require('ln-sync');
+const {returnResult} = require('asyncjs-util');
+
+const getPayRequest = require('./../lnurl/get_pay_request');
+
+const {isArray} = Array;
+const mtokensAsTokens = n => Number(BigInt(n) / BigInt(1e3));
+const serviceDeclinedError = 'ServiceReturnedError';
+
+/** Get an invoice from a LNURL service for a payment of a stream
+
+  {
+    hash: <Description Hash Hex String>
+    logger: <Winston Logger Object>
+    mtokens: <Invoice Amount Millitokens String>
+    request: <Request Function>
+    url: <Service Callback URL String>
+  }
+
+  @returns via cbk or Promise
+  {
+    [is_amount_too_high]: <Service Turned Down The Amount Bool>
+    [request]: <BOLT 11 Payment Request String>
+  }
+*/
+module.exports = ({hash, logger, mtokens, request, url}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!hash) {
+          return cbk([400, 'ExpectedDescriptionHashToGetStreamInvoice']);
+        }
+
+        if (!logger) {
+          return cbk([400, 'ExpectedLoggerToGetStreamInvoice']);
+        }
+
+        if (!mtokens) {
+          return cbk([400, 'ExpectedMillitokensToGetStreamInvoice']);
+        }
+
+        if (!request) {
+          return cbk([400, 'ExpectedRequestFunctionToGetStreamInvoice']);
+        }
+
+        if (!url) {
+          return cbk([400, 'ExpectedServiceUrlToGetStreamInvoice']);
+        }
+
+        return cbk();
+      },
+
+      // The amount of the invoice to show
+      amount: ['validate', ({}, cbk) => {
+        return cbk(null, formatTokens({tokens: mtokensAsTokens(mtokens)}));
+      }],
+
+      // Ask the service for an invoice
+      getRequest: ['amount', ({amount}, cbk) => {
+        logger.info({requesting_invoice: amount.display});
+
+        const pay = {hash, mtokens, request, url};
+
+        return asyncReflect(getPayRequest)(pay, cbk);
+      }],
+
+      // Note the invoice, or that the service turned down the amount
+      invoice: ['amount', 'getRequest', ({amount, getRequest}, cbk) => {
+        const {error, value} = getRequest;
+
+        // Exit early when the service declined to make the invoice
+        if (isArray(error) && error[1] === serviceDeclinedError) {
+          const [,, details] = error;
+
+          logger.info({invoice_declined: amount.display, reason: details.err});
+
+          return cbk(null, {is_amount_too_high: true});
+        }
+
+        if (!!error) {
+          return cbk(error);
+        }
+
+        // The request is what the route search probes towards
+        logger.info({payment_request: value.request});
+
+        return cbk(null, {request: value.request});
+      }],
+    },
+    returnResult({reject, resolve, of: 'invoice'}, cbk));
+  });
+};