@alexbosworth/fiat 2.0.0 → 3.0.0

package/chain/estimates/get_price_from_blocks.js

@@ -0,0 +1,281 @@
+const asyncAuto = require('async/auto');
+const asyncMapLimit = require('async/mapLimit');
+const {returnResult} = require('asyncjs-util');
+
+const {centsPerDollar} = require('./../constants');
+const {defaultMaxPrice} = require('./../constants');
+const {defaultMinPrice} = require('./../constants');
+const {estimateFromOutputs} = require('./../outputs');
+const {fetchLimit} = require('./../constants');
+const {getBlockPayments} = require('./../blocks');
+const {minAliasMargin} = require('./../constants');
+const {priceFromOutputs} = require('./../outputs');
+
+const {assign} = Object;
+const driftReach = 1.09;
+const flatten = arr => [].concat(...arr);
+const {floor} = Math;
+const {isArray} = Array;
+const isHeight = n => Number.isInteger(n) && n >= 0;
+const logInterval = 24;
+const {max} = Math;
+const {min} = Math;
+const minDriftBlocks = 24;
+const widening = 2;
+
+/** Get the USD price of BTC implied by the payments in a set of blocks
+
+  {
+    [blocks]: <Retrieved Blocks By Height Map Object>
+    [date]: <Day the Blocks Are On YYYY-MM-DD String>
+    heights: [<Block Height Number>]
+    [is_capping_near_round]: <Cap Values Just Off Round BTC Amounts Too Bool>
+    lnd: <Authenticated LND API Object>
+    [logger]: <Winston Logger Object>
+    [max_price]: <Maximum Possible USD Price Number>
+    [min_price]: <Minimum Possible USD Price Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    agreement: <Spike Strengths Agreement With Prior Weights Number>
+    cents: <USD Cents Per BTC Number>
+    confidence: <Best Position Score Over Best Patterned Alias Score Number>
+    coverage: <Share of Spike Excess At Round USD Positions Number>
+    dispersion: <Peak Width Beyond Smoothing As Price Fraction Number>
+    [drift]: <Second Half Price Change From First Half Price Number>
+    evidence: <Share of Prior Weight Observable At the Price Number>
+    [is_unsettled]: <Refinement Was Still Moving After Its Last Pass Bool>
+    [is_widened]: <Search Was Widened Beyond the Price Window Bool>
+    outputs: <Payment Outputs Considered Count Number>
+    payments: <Estimated Round USD Payments Count Number>
+    rivalry: <Best Patterned Rival Position Score Over Best Score Number>
+    rough_cents: <Rough Estimate USD Cents Per BTC Number>
+    round_shift: <Price Change If Round BTC Values Were Counted Number>
+    significance: <Payment Peak Beyond Noise In Standard Deviations Number>
+    spikes: [{
+      strength: <Spike Strength Relative to the Strongest Spike Number>
+      usd: <Round USD Amount Number>
+    }]
+    stability: <Largest Price Change From Perturbed Refinement Number>
+    transactions: <Payment Transactions Considered Count Number>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isArray(args.heights) || !args.heights.length) {
+          return cbk([400, 'ExpectedBlockHeightsToGetPriceFromBlocks']);
+        }
+
+        if (!args.heights.every(isHeight)) {
+          return cbk([400, 'ExpectedBlockHeightNumbersToGetPriceFromBlocks']);
+        }
+
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedAuthenticatedLndToGetPriceFromBlocks']);
+        }
+
+        return cbk();
+      },
+
+      // Get the blocks and pull out the payment-like outputs
+      getBlocks: ['validate', ({}, cbk) => {
+        const heights = args.heights.slice().sort((a, b) => a - b);
+        const progress = {fetched: Number()};
+
+        const total = heights.length;
+
+        // Log the progress of fetching blocks like a progress bar
+        const log = fetched => {
+          // Exit early when there is no logger or the fetch is a short one
+          if (!args.logger || total < logInterval) {
+            return;
+          }
+
+          // Exit early when the progress is between marks
+          if (!!(fetched % logInterval) && fetched !== total) {
+            return;
+          }
+
+          return args.logger.info({
+            fetching_blocks: {date: args.date, blocks: `${fetched}/${total}`},
+          });
+        };
+
+        log(progress.fetched);
+
+        return asyncMapLimit(heights, fetchLimit, (height, cbk) => {
+          return getBlockPayments({
+            height,
+            blocks: args.blocks,
+            lnd: args.lnd,
+          },
+          (err, res) => {
+            if (!!err) {
+              return cbk(err);
+            }
+
+            log(++progress.fetched);
+
+            return cbk(null, res);
+          });
+        },
+        cbk);
+      }],
+
+      // Collect the payment outputs of every block
+      payments: ['getBlocks', ({getBlocks}, cbk) => {
+        const payments = getBlocks.map(block => block.outputs);
+
+        if (!flatten(payments).length) {
+          return cbk([503, 'ExpectedPaymentOutputsInBlocksToGetPrice']);
+        }
+
+        return cbk(null, payments);
+      }],
+
+      // Count the payment transactions
+      transactions: ['getBlocks', ({getBlocks}, cbk) => {
+        return cbk(null, getBlocks.reduce((sum, block) => {
+          return sum + block.transactions;
+        },
+        Number()));
+      }],
+
+      // Derive the price from the payment output values
+      price: ['payments', ({payments}, cbk) => {
+        const derived = (() => {
+          try {
+            return {
+              price: priceFromOutputs({
+                is_capping_near_round: args.is_capping_near_round,
+                max_price: args.max_price,
+                min_price: args.min_price,
+                outputs: flatten(payments),
+              }),
+            };
+          } catch (err) {
+            return {err};
+          }
+        })();
+
+        // Exit early when the outputs cannot be priced
+        if (!!derived.err) {
+          return cbk([503, 'FailedToDerivePriceFromOutputs', {
+            err: derived.err,
+          }]);
+        }
+
+        return cbk(null, derived.price);
+      }],
+
+      // Widen the search when the price does not fit well in the window
+      widen: ['payments', 'price', ({payments, price}, cbk) => {
+        // Exit early when there is no window to widen
+        if (!args.max_price || !args.min_price) {
+          return cbk(null, price);
+        }
+
+        const isConflict = price.confidence < minAliasMargin;
+
+        // Exit early when the price fits in the window
+        if (!price.is_at_edge && !isConflict) {
+          return cbk(null, price);
+        }
+
+        const maxPrice = min(defaultMaxPrice, args.max_price * widening);
+        const minPrice = max(defaultMinPrice, args.min_price / widening);
+
+        const widened = (() => {
+          try {
+            return {
+              price: priceFromOutputs({
+                is_capping_near_round: args.is_capping_near_round,
+                max_price: maxPrice,
+                min_price: minPrice,
+                outputs: flatten(payments),
+              }),
+            };
+          } catch (err) {
+            return {err};
+          }
+        })();
+
+        // Exit early when the outputs cannot be priced in the wider window
+        if (!!widened.err) {
+          return cbk([503, 'FailedToDerivePriceInWidenedWindow', {
+            err: widened.err,
+          }]);
+        }
+
+        return cbk(null, assign({is_widened: true}, widened.price));
+      }],
+
+      // Estimate the price in the first and second halves of the blocks
+      drift: ['payments', 'widen', ({payments, widen}, cbk) => {
+        // Exit early when there are too few blocks to split
+        if (payments.length < minDriftBlocks) {
+          return cbk();
+        }
+
+        const half = floor(payments.length / 2);
+        const price = widen.cents / centsPerDollar;
+
+        const halves = [payments.slice(Number(), half), payments.slice(half)];
+
+        const drift = (() => {
+          try {
+            const [first, second] = halves.map(blocks => estimateFromOutputs({
+              is_capping_near_round: args.is_capping_near_round,
+              is_quick: true,
+              max_price: price * driftReach,
+              min_price: price / driftReach,
+              outputs: flatten(blocks),
+            }));
+
+            return {drift: second.cents / first.cents - 1};
+          } catch (err) {
+            // A half without enough payments to price does not show a drift
+            return {};
+          }
+        })();
+
+        return cbk(null, drift);
+      }],
+
+      // The derived price
+      result: [
+        'drift',
+        'payments',
+        'transactions',
+        'widen',
+        ({drift, payments, transactions, widen}, cbk) =>
+      {
+        return cbk(null, {
+          transactions,
+          agreement: widen.agreement,
+          cents: widen.cents,
+          confidence: widen.confidence,
+          coverage: widen.coverage,
+          dispersion: widen.dispersion,
+          drift: !drift ? undefined : drift.drift,
+          evidence: widen.evidence,
+          is_unsettled: widen.is_unsettled,
+          is_widened: widen.is_widened,
+          outputs: flatten(payments).length,
+          payments: widen.payments,
+          rivalry: widen.rivalry,
+          rough_cents: widen.rough_cents,
+          round_shift: widen.round_shift,
+          significance: widen.significance,
+          spikes: widen.spikes,
+          stability: widen.stability,
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'result'}, cbk));
+  });
+};

package/chain/estimates/get_provisional_price.js

@@ -0,0 +1,163 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const estimateRecord = require('./estimate_record');
+const {getBlockHash} = require('./../blocks');
+const getPriceFromBlocks = require('./get_price_from_blocks');
+const isAliasRatio = require('./is_alias_ratio');
+const isSupportedEstimate = require('./is_supported_estimate');
+const nearestEstimate = require('./nearest_estimate');
+const priceWindow = require('./price_window');
+const rememberEstimate = require('./remember_estimate');
+const {unpricedErrors} = require('./../constants');
+
+/** Derive and remember a provisional price for an incomplete day
+
+  {
+    day: <Day YYYY-MM-DD String>
+    estimates: {
+      priors: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      provisional: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      rates: {<Day YYYY-MM-DD String>: <Estimate Object>}
+    }
+    heights: [<Block Height Number>]
+    lnd: <Authenticated LND API Object>
+    [logger]: <Winston Logger Object>
+    put_price: <Remember Price Function> (record, cbk) => (err)
+  }
+
+  @returns via cbk or Promise
+  {
+    cents: <USD Cents Per BTC Number>
+    is_provisional: <Price Is Provisional Bool>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // The nearest estimate guides the search
+      guide: cbk => {
+        const {estimate} = nearestEstimate({
+          day: args.day,
+          estimates: args.estimates,
+        });
+
+        return cbk(null, {estimate});
+      },
+
+      // Derive the price from the blocks
+      getPrice: ['guide', ({guide}, cbk) => {
+        const {estimate} = guide;
+
+        const bounds = !estimate ? {} : priceWindow({cents: estimate.cents});
+
+        return getPriceFromBlocks({
+          date: args.day,
+          heights: args.heights,
+          lnd: args.lnd,
+          logger: args.logger,
+          max_price: bounds.max_price,
+          min_price: bounds.min_price,
+        },
+        (err, res) => {
+          // Exit early when the blocks give no price at all
+          if (!!err && unpricedErrors.includes(err[1])) {
+            return cbk([503, 'FailedToFindSupportedProvisionalPrice', {
+              day: args.day,
+            }]);
+          }
+
+          return cbk(err, res);
+        });
+      }],
+
+      // Check that the data support the price
+      checkPrice: ['getPrice', 'guide', ({getPrice, guide}, cbk) => {
+        const {estimate} = guide;
+
+        const support = isSupportedEstimate({
+          confidence: getPrice.confidence,
+          evidence: getPrice.evidence,
+          is_unconstrained: !estimate || !!getPrice.is_widened,
+          payments: getPrice.payments,
+          rivalry: getPrice.rivalry,
+          significance: getPrice.significance,
+          spikes: getPrice.spikes,
+          stability: getPrice.stability,
+        });
+
+        if (!support.is_supported) {
+          return cbk([503, 'FailedToFindSupportedProvisionalPrice', {
+            day: args.day,
+          }]);
+        }
+
+        // Exit early when the price was not found beyond a guide window
+        if (!getPrice.is_widened || !estimate) {
+          return cbk();
+        }
+
+        const ratio = isAliasRatio({
+          cents: getPrice.cents,
+          other: estimate.cents,
+        });
+
+        // A price at an alias of its guide means one of them is wrong
+        if (!!ratio.is_alias) {
+          return cbk([503, 'FoundProvisionalPriceAtAliasOfGuidePrice', {
+            cents: getPrice.cents,
+            day: args.day,
+            neighbor: estimate.day,
+            neighbor_cents: estimate.cents,
+          }]);
+        }
+
+        return cbk();
+      }],
+
+      // Get the hash of the last block
+      getHash: ['checkPrice', ({}, cbk) => {
+        const [last] = args.heights.slice(-1);
+
+        return getBlockHash({height: last, lnd: args.lnd}, cbk);
+      }],
+
+      // Remember the provisional price
+      remember: ['getHash', 'getPrice', ({getHash, getPrice}, cbk) => {
+        const [first] = args.heights;
+        const [last] = args.heights.slice(-1);
+
+        const {record} = estimateRecord({
+          date: args.day,
+          estimate: {
+            agreement: getPrice.agreement,
+            blocks: [first, last],
+            cents: getPrice.cents,
+            confidence: getPrice.confidence,
+            coverage: getPrice.coverage,
+            dispersion: getPrice.dispersion,
+            drift: getPrice.drift,
+            evidence: getPrice.evidence,
+            hash: getHash.hash,
+            is_widened: getPrice.is_widened,
+            outputs: getPrice.outputs,
+            payments: getPrice.payments,
+            rivalry: getPrice.rivalry,
+            round_shift: getPrice.round_shift,
+            significance: getPrice.significance,
+            spikes: getPrice.spikes,
+            stability: getPrice.stability,
+          },
+          is_provisional: true,
+        });
+
+        rememberEstimate({estimate: record, estimates: args.estimates});
+
+        return args.put_price(record, err => {
+          return cbk(err, {cents: getPrice.cents, is_provisional: true});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'remember'}, cbk));
+  });
+};

package/chain/estimates/index.js

@@ -0,0 +1,25 @@
+const currentEstimates = require('./current_estimates');
+const estimateDayPrice = require('./estimate_day_price');
+const estimateRecord = require('./estimate_record');
+const forgetEstimates = require('./forget_estimates');
+const getChainPrice = require('./get_chain_price');
+const getPriceForDate = require('./get_price_for_date');
+const isAliasRatio = require('./is_alias_ratio');
+const isSupportedEstimate = require('./is_supported_estimate');
+const nearestEstimate = require('./nearest_estimate');
+const priceWindow = require('./price_window');
+const rememberEstimate = require('./remember_estimate');
+
+module.exports = {
+  currentEstimates,
+  estimateDayPrice,
+  estimateRecord,
+  forgetEstimates,
+  getChainPrice,
+  getPriceForDate,
+  isAliasRatio,
+  isSupportedEstimate,
+  nearestEstimate,
+  priceWindow,
+  rememberEstimate,
+};

package/chain/estimates/is_alias_ratio.js

@@ -0,0 +1,38 @@
+const {roundAmounts} = require('./../outputs');
+
+const {abs} = Math;
+const flatten = arr => [].concat(...arr);
+const {log10} = Math;
+const {max} = Math;
+const {min} = Math;
+const minAliasRatio = 2;
+const tolerance = Math.log10(1.06);
+
+/** Determine if the ratio between two prices is an alias ratio of the pattern
+
+  {
+    cents: <USD Cents Per BTC Number>
+    other: <Other USD Cents Per BTC Number>
+  }
+
+  @returns
+  {
+    is_alias: <Prices Are At An Alias Ratio Bool>
+  }
+*/
+module.exports = ({cents, other}) => {
+  const {amounts} = roundAmounts({});
+
+  // Ratios of two or more between round amounts are the pattern's aliases
+  const ratios = flatten(amounts.map(amount => {
+    const larger = amounts.filter(n => n >= amount * minAliasRatio);
+
+    return larger.map(n => n / amount);
+  }));
+
+  const distance = log10(max(cents, other) / min(cents, other));
+
+  const isNear = ratio => abs(log10(ratio) - distance) < tolerance;
+
+  return {is_alias: ratios.some(isNear)};
+};

package/chain/estimates/is_supported_estimate.js

@@ -0,0 +1,81 @@
+const {minAliasMargin} = require('./../constants');
+
+const clearMargin = 0.1;
+const {isArray} = Array;
+const maxRivalry = 0.9;
+const maxStability = 0.01;
+const minEvidence = 0.5;
+const minPayments = 100;
+const minSignificance = 4;
+const minSpikes = 3;
+const minSpikeStrength = 0.2;
+
+/** Determine if a price estimate is supported by the data behind it
+
+  {
+    confidence: <Best Position Score Over Best Patterned Alias Score Number>
+    evidence: <Share of Prior Weight Observable At the Price Number>
+    is_unconstrained: <Search Was Not Confined To a Window Bool>
+    payments: <Estimated Round USD Payments Count Number>
+    rivalry: <Best Patterned Rival Position Score Over Best Score Number>
+    significance: <Payment Peak Beyond Noise In Standard Deviations Number>
+    spikes: [{
+      strength: <Spike Strength Relative to the Strongest Spike Number>
+      usd: <Round USD Amount Number>
+    }]
+    stability: <Largest Price Change From Perturbed Refinement Number>
+  }
+
+  @returns
+  {
+    is_supported: <Estimate Is Supported By the Data Bool>
+  }
+*/
+module.exports = args => {
+  const {confidence, evidence, payments, rivalry, significance} = args;
+
+  // Exit early when there are no spikes to judge
+  if (!isArray(args.spikes)) {
+    return {is_supported: false};
+  }
+
+  const strong = args.spikes.filter(n => n.strength >= minSpikeStrength);
+
+  // Exit early when there is no pattern, one spike fits any round amount
+  if (strong.length < minSpikes) {
+    return {is_supported: false};
+  }
+
+  // Exit early when too few round payments formed the peak
+  if (!(payments >= minPayments)) {
+    return {is_supported: false};
+  }
+
+  // Exit early when the peak does not stand out beyond noise
+  if (!(significance >= minSignificance)) {
+    return {is_supported: false};
+  }
+
+  // Exit early when other starting points refine to another price
+  if (!(args.stability < maxStability)) {
+    return {is_supported: false};
+  }
+
+  // Exit early when another position or currency fits nearly as well
+  if (!(rivalry < maxRivalry)) {
+    return {is_supported: false};
+  }
+
+  // Exit early when too little of the pattern was observable
+  if (!(evidence >= minEvidence)) {
+    return {is_supported: false};
+  }
+
+  // Less observable evidence demands a larger margin over the aliases
+  const clear = minAliasMargin + clearMargin / evidence;
+
+  // Without a window around a known price only the prior excludes aliases
+  const minConfidence = !!args.is_unconstrained ? clear : minAliasMargin;
+
+  return {is_supported: confidence >= minConfidence};
+};

package/chain/estimates/nearest_estimate.js

@@ -0,0 +1,49 @@
+const {msPerDay} = require('./../constants');
+const {sortBy} = require('./../../arrays');
+
+const {abs} = Math;
+const dayStart = day => Date.parse(`${day}T00:00:00.000Z`);
+const flatten = arr => [].concat(...arr);
+const {keys} = Object;
+
+/** Find the known price estimate that is closest in time to a day
+
+  {
+    day: <Day YYYY-MM-DD String>
+    estimates: {
+      [priors]: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+      [provisional]: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+      [rates]: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+    }
+    [latest]: <Latest Day To Consider YYYY-MM-DD String>
+  }
+
+  @returns
+  {
+    [estimate]: {
+      cents: <USD Cents Per BTC Number>
+      day: <Day YYYY-MM-DD String>
+      distance: <Days Away Number>
+    }
+  }
+*/
+module.exports = ({day, estimates, latest}) => {
+  const sources = [estimates.rates, estimates.priors, estimates.provisional];
+
+  const isConsidered = known => !latest || known <= latest;
+
+  const known = flatten(sources.filter(n => !!n).map(source => {
+    return keys(source).filter(isConsidered).map(known => ({
+      cents: source[known].cents,
+      day: known,
+      distance: abs(dayStart(day) - dayStart(known)) / msPerDay,
+    }));
+  }));
+
+  // The nearest estimate, the earliest of them when two are as near
+  const byDay = sortBy({array: known, attribute: 'day'}).sorted;
+
+  const [estimate] = sortBy({array: byDay, attribute: 'distance'}).sorted;
+
+  return {estimate};
+};

package/chain/estimates/price_window.js

@@ -0,0 +1,25 @@
+const {centsPerDollar} = require('./../constants');
+
+const {round} = Math;
+const windowAbovePrior = 1.2;
+const windowBelowPrior = 0.62;
+
+/** Get the price window to search within given a nearby price estimate
+
+  {
+    cents: <Nearby Estimate USD Cents Per BTC Number>
+  }
+
+  @returns
+  {
+    max_price: <Maximum Possible USD Price Number>
+    min_price: <Minimum Possible USD Price Number>
+  }
+*/
+module.exports = ({cents}) => {
+  // Less than a factor of two wide, so aliases at two or more are outside
+  return {
+    max_price: round(cents * windowAbovePrior) / centsPerDollar,
+    min_price: round(cents * windowBelowPrior) / centsPerDollar,
+  };
+};