@alexbosworth/fiat 2.0.0 → 3.0.0

package/chain/estimates/remember_estimate.js

@@ -0,0 +1,83 @@
+const rounded = n => Math.round(n * 1e3) / 1e3;
+
+/** Remember a price estimate with the known estimates
+
+  {
+    estimate: {
+      [agreement]: <Spike Strengths Agreement With Template Weights Number>
+      [blocks]: [<First Block Height Number>, <Last Block Height Number>]
+      cents: <USD Cents Per BTC Number>
+      [confidence]: <Best Position Score Over Best Alias Score Number>
+      date: <Day YYYY-MM-DD String>
+      [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>
+      [hash]: <Last Block Hash Hex String>
+      [is_provisional]: <Price Is For An Incomplete Day Bool>
+      [is_sample]: <Price Is A Rough Estimate From Sample Blocks Bool>
+      [is_unguided]: <Price Was Estimated Without a Neighboring Guide Bool>
+      [is_unsettled]: <Refinement Was Still Moving After Its Last Pass Bool>
+      [outputs]: <Payment Outputs Considered Count Number>
+      [payments]: <Estimated Round USD Payments Count Number>
+      [rivalry]: <Best Rival Position Score Over Best Score Number>
+      [round_shift]: <Price Change If Round BTC Values Were Counted Number>
+      [stability]: <Largest Price Change From Perturbed Refinement Number>
+      [version]: <Method Version String>
+    }
+    estimates: {
+      priors: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      provisional: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+      rates: {<Day YYYY-MM-DD String>: <Estimate Object>}
+    }
+  }
+
+  @returns
+  {
+    estimates: {
+      priors: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      provisional: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+      rates: {<Day YYYY-MM-DD String>: <Estimate Object>}
+    }
+  }
+*/
+module.exports = ({estimate, estimates}) => {
+  const {blocks, cents, date, hash, version} = estimate;
+
+  // Exit early when the estimate is provisional
+  if (!!estimate.is_provisional) {
+    estimates.provisional[date] = {blocks, cents, hash, version};
+
+    return {estimates};
+  }
+
+  // Exit early when the estimate is only a rough guide
+  if (!!estimate.is_sample) {
+    estimates.priors[date] = {blocks, cents, hash, version};
+
+    return {estimates};
+  }
+
+  estimates.rates[date] = {
+    blocks,
+    cents,
+    hash,
+    version,
+    agreement: rounded(estimate.agreement),
+    confidence: rounded(estimate.confidence),
+    dispersion: rounded(estimate.dispersion),
+    drift: estimate.drift === undefined ? undefined : rounded(estimate.drift),
+    evidence: rounded(estimate.evidence),
+    is_unguided: estimate.is_unguided || undefined,
+    is_unsettled: estimate.is_unsettled || undefined,
+    outputs: estimate.outputs,
+    payments: estimate.payments,
+    rivalry: rounded(estimate.rivalry),
+    round_shift: rounded(estimate.round_shift),
+    stability: rounded(estimate.stability),
+  };
+
+  // A full day rate replaces the prior estimate of its day
+  delete estimates.priors[date];
+
+  return {estimates};
+};

package/chain/estimates/store_estimate.js

@@ -0,0 +1,198 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {centsPerDollar} = require('./../constants');
+const currentEstimates = require('./current_estimates');
+const {putPricesFile} = require('./../../storage');
+const rememberEstimate = require('./remember_estimate');
+const {sampleLogInterval} = require('./../constants');
+
+const {assign} = Object;
+const dollars = cents => (cents / centsPerDollar).toFixed(2);
+const rounded = n => Math.round(n * 1e3) / 1e3;
+
+/** Store a price estimate with the known estimates and in the prices file
+
+  {
+    estimate: {
+      [agreement]: <Spike Strengths Agreement With Prior Weights Number>
+      blocks: [<First Block Height Number>, <Last Block Height Number>]
+      cents: <USD Cents Per BTC Number>
+      [confidence]: <Best Position Score Over Best Alias Score Number>
+      date: <Day YYYY-MM-DD String>
+      [hash]: <Last Block Hash Hex String>
+      [is_provisional]: <Price Is For An Incomplete Day Bool>
+      [is_sample]: <Price Is A Rough Estimate From Sample Blocks Bool>
+      [is_unguided]: <Price Was Estimated Without a Neighboring Guide Bool>
+      [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 Rival Position Score Over Best Score Number>
+      [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+      [drift]: <Second Half Price Change From First Half Price Number>
+      [stability]: <Largest Price Change From Perturbed Refinement Number>
+      [version]: <Method Version String>
+    }
+    estimates: {
+      priors: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      provisional: {<Day YYYY-MM-DD String>: {cents: <USD Cents Number>}}
+      rates: {<Day YYYY-MM-DD String>: <Estimate Object>}
+      samples: <Count of Sample Estimates Stored Number>
+    }
+    fs: {
+      getFile: <Read File Contents Function> (path, cbk) => {}
+      makeDirectory: <Make Directory Function> (path, cbk) => {}
+      renameFile: <Rename File Function> (from, to, cbk) => {}
+      writeFile: <Write File Contents Function> (path, contents, cbk) => {}
+    }
+    [logger]: <Winston Logger Object>
+    path: <Prices File Path String>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = ({estimate, estimates, fs, logger, path}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!estimate) {
+          return cbk([400, 'ExpectedEstimateToStoreEstimate']);
+        }
+
+        if (!estimates) {
+          return cbk([400, 'ExpectedKnownEstimatesToStoreEstimate']);
+        }
+
+        if (!fs) {
+          return cbk([400, 'ExpectedFileSystemMethodsToStoreEstimate']);
+        }
+
+        if (!path) {
+          return cbk([400, 'ExpectedPricesFilePathToStoreEstimate']);
+        }
+
+        return cbk();
+      },
+
+      // Log the estimate
+      log: ['validate', ({}, cbk) => {
+        const {blocks, cents, date, drift, outputs, payments} = estimate;
+
+        // Exit early when there is no logger
+        if (!logger) {
+          return cbk();
+        }
+
+        const price = dollars(cents);
+        const widened = estimate.is_widened || undefined;
+
+        if (!!estimate.is_provisional) {
+          logger.info({
+            chain_price: {
+              date,
+              price,
+              is_provisional: true,
+              is_widened: widened,
+            },
+          });
+
+          return cbk();
+        }
+
+        if (!!estimate.is_sample) {
+          estimates.samples++;
+
+          if (!(estimates.samples % sampleLogInterval) || !!widened) {
+            logger.info({
+              chain_price: {
+                date,
+                price,
+                is_sample: true,
+                is_widened: widened,
+              },
+            });
+          }
+
+          return cbk();
+        }
+
+        // A full day price estimated without a guide is a starting point
+        if (!!estimate.is_unguided) {
+          logger.info({chain_price: {starting_from: date}});
+        }
+
+        logger.info({
+          chain_price: {
+            date,
+            outputs,
+            payments,
+            price,
+            agreement: rounded(estimate.agreement),
+            blocks: blocks[1] - blocks[0] + 1,
+            confidence: rounded(estimate.confidence),
+            dispersion: rounded(estimate.dispersion),
+            drift: estimate.drift === undefined ? undefined : rounded(drift),
+            is_unsettled: estimate.is_unsettled || undefined,
+            is_widened: widened,
+            rivalry: rounded(estimate.rivalry),
+            stability: rounded(estimate.stability),
+          },
+        });
+
+        return cbk();
+      }],
+
+      // The known estimates with the estimate, kept apart until it is stored
+      remember: ['log', ({}, cbk) => {
+        const updated = {
+          priors: assign({}, estimates.priors),
+          provisional: assign({}, estimates.provisional),
+          rates: assign({}, estimates.rates),
+        };
+
+        return cbk(null, rememberEstimate({estimate, estimates: updated}));
+      }],
+
+      // Write the estimate to the prices file
+      write: ['remember', ({remember}, cbk) => {
+        return putPricesFile({
+          fs,
+          path,
+          priors: remember.estimates.priors,
+          provisional: remember.estimates.provisional,
+          rates: remember.estimates.rates,
+        },
+        cbk);
+      }],
+
+      // Keep the current prices that are now in the file
+      update: ['remember', 'write', ({remember, write}, cbk) => {
+        // Prices in the file from other versions of the method are not used
+        const current = currentEstimates({
+          priors: write.priors,
+          provisional: write.provisional,
+          rates: write.rates,
+        });
+
+        estimates.priors = current.priors;
+        estimates.provisional = current.provisional;
+        estimates.rates = current.rates;
+
+        // Exit early when the estimate is not a provisional price
+        if (!estimate.is_provisional) {
+          return cbk();
+        }
+
+        // A later provisional price in the file may not be usable here
+        const {date} = estimate;
+
+        estimates.provisional[date] = remember.estimates.provisional[date];
+
+        return cbk();
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/chain/histogram/best_position.js

@@ -0,0 +1,63 @@
+const parabolaPeak = require('./parabola_peak');
+const positionScore = require('./position_score');
+
+const {log10} = Math;
+const {round} = Math;
+
+/** Find the best scoring dollar position among positions under a weighting
+
+  {
+    amounts: [<Round USD Amount Number>]
+    bins: [<Dollar Position Bin Number>]
+    bins_per_decade: <Bins Per Factor of Ten Number>
+    min_bin: <Lowest Observable Bin Number>
+    noise: [<Spike Strength From Noise Alone At Bin Number>]
+    strengths: [<Spike Strength At Bin Number>]
+    weights: [<Amount Weight Number>]
+  }
+
+  @returns
+  {
+    bin: <Best Scoring Dollar Position Bin Number>
+    delta: <Peak Offset From the Best Bin In Bins Number>
+    score: <Best Score Number>
+  }
+*/
+module.exports = args => {
+  const {noise, strengths, weights} = args;
+
+  // The bins of the amounts above a dollar bin are the same at every position
+  const shifts = args.amounts.map(usd => {
+    return round(log10(usd) * args.bins_per_decade);
+  });
+
+  const scores = args.bins.map(bin => {
+    const {score} = positionScore({
+      noise,
+      shifts,
+      strengths,
+      weights,
+      dollar_bin: bin,
+      min_bin: args.min_bin,
+    });
+
+    return {bin, score};
+  });
+
+  // The first of the highest scores is the best
+  const best = scores.reduce((lead, n) => n.score > lead.score ? n : lead);
+
+  const index = scores.indexOf(best);
+
+  // The peak is between the best bin and its neighbors
+  const above = scores[index + 1] || best;
+  const below = scores[index - 1] || best;
+
+  const {delta} = parabolaPeak({
+    above: above.score,
+    below: below.score,
+    center: best.score,
+  });
+
+  return {delta, bin: best.bin, score: best.score};
+};

package/chain/histogram/histogram_excess.js

@@ -0,0 +1,50 @@
+const sortedNeighbors = require('./sorted_neighbors');
+
+const defaultExclude = 2;
+const defaultRadius = 12;
+const {isArray} = Array;
+const {max} = Math;
+
+/** Get the excess of each histogram bin over its local background
+
+  {
+    bins: [<Share of Outputs in Bin Number>]
+    [exclude]: <Bins Next to the Bin to Leave Out of the Background Number>
+    [radius]: <Bins On Either Side to Take the Background From Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    background: [<Local Background Share Number>]
+    excess: [<Share of Outputs Above Local Background Number>]
+  }
+*/
+module.exports = ({bins, exclude, radius}) => {
+  if (!isArray(bins)) {
+    throw new Error('ExpectedHistogramBinsToCalculateHistogramExcess');
+  }
+
+  const {values} = sortedNeighbors({
+    bins,
+    exclude: exclude === undefined ? defaultExclude : exclude,
+    min_bin: Number(),
+    radius: radius === undefined ? defaultRadius : radius,
+    value: sorted => {
+      // Exit early when there is no background to compare against
+      if (!sorted.length) {
+        return Number();
+      }
+
+      // The median neighbor, rounded down to the lower middle of an even count
+      return sorted[(sorted.length - 1) >>> 1];
+    },
+  });
+
+  return {
+    background: values,
+    excess: bins.map((share, bin) => max(0, share - values[bin])),
+  };
+};

package/chain/histogram/histogram_peak.js

@@ -0,0 +1,87 @@
+const {half} = require('./../constants');
+const histogramExcess = require('./histogram_excess');
+const parabolaPeak = require('./parabola_peak');
+const paymentsNearPosition = require('./payments_near_position');
+const peakWidth = require('./peak_width');
+const smoothBins = require('./smooth_bins');
+
+const {abs} = Math;
+const {ceil} = Math;
+const {max} = Math;
+const range = (a, b) => [...Array(b - a).keys()].map(i => a + i);
+const {round} = Math;
+const {sqrt} = Math;
+
+/** Find the peak in a fine histogram of implied prices
+
+  {
+    counts: [<Implied Prices In Bin Count Number>]
+    exclude: <Bins Next to a Bin to Leave Out of Its Background Number>
+    kernel: <Smoothing Kernel Half Width in Bins Number>
+    weighted: [<Weighted Implied Prices In Bin Number>]
+  }
+
+  @returns
+  {
+    delta: <Peak Offset From the Peak Bin In Bins Number>
+    noise: <Largest Payments Count Away From the Peak Number>
+    payments: <Estimated Round Payments In the Peak Number>
+    peak: <Peak Bin Index Number>
+    significance: <Peak Payments Beyond Noise In Standard Deviations Number>
+    width: <Peak Width At Half of Its Height in Bins Number>
+  }
+*/
+module.exports = ({counts, exclude, kernel, weighted}) => {
+  const radius = counts.length;
+
+  const {excess} = histogramExcess({exclude, radius, bins: weighted});
+
+  // Smoothing the excess gathers the peak into one place
+  const {smoothed} = smoothBins({half: kernel, bins: excess});
+
+  const peak = smoothed.indexOf(max(...smoothed));
+
+  const after = smoothed[peak + 1];
+  const before = smoothed[peak - 1];
+  const center = smoothed[peak];
+
+  const {delta} = parabolaPeak({
+    center,
+    above: after === undefined ? center : after,
+    below: before === undefined ? center : before,
+  });
+
+  const {background} = histogramExcess({exclude, radius, bins: counts});
+
+  const {width} = peakWidth({peak, bins: smoothed});
+
+  const {above, observed} = paymentsNearPosition({
+    background,
+    counts,
+    kernel,
+    position: peak,
+  });
+
+  // Every other position that does not overlap the peak is a noise peak
+  const apart = ceil(width * half) + kernel;
+
+  const noise = range(Number(), counts.length)
+    .filter(position => abs(position - peak) > apart)
+    .map(position => {
+      return paymentsNearPosition({background, counts, kernel, position});
+    })
+    .map(payments => payments.above)
+    .reduce((largest, n) => max(largest, n), Number());
+
+  // Significance is the payments beyond noise in standard deviations
+  const beyond = max(Number(), above - noise);
+
+  return {
+    delta,
+    peak,
+    width,
+    noise: round(noise),
+    payments: max(Number(), round(above)),
+    significance: !observed ? Number() : beyond / sqrt(observed),
+  };
+};

package/chain/histogram/implied_prices_histogram.js

@@ -0,0 +1,53 @@
+const {half} = require('./../constants');
+const {tokensPerBigUnit} = require('./../constants');
+
+const {log10} = Math;
+const {pow} = Math;
+const {round} = Math;
+
+/** Make a fine histogram of the prices implied by outputs near round amounts
+
+  {
+    amounts: [<Round USD Amount Number>]
+    bins_per_decade: <Bins Per Factor of Ten Number>
+    outputs: [<Output Tokens Number>]
+    price: <Rough USD Price Number>
+    reach: <Bins On Either Side of the Rough Price Number>
+    weights: [<Round USD Amount Weight Number>]
+  }
+
+  @returns
+  {
+    counts: [<Implied Prices In Bin Count Number>]
+    weighted: [<Weighted Implied Prices In Bin Number>]
+  }
+*/
+module.exports = args => {
+  const {amounts, outputs, price, reach, weights} = args;
+
+  const binsPerDecade = args.bins_per_decade;
+  const counts = Array(reach * 2 + 1).fill(Number());
+  const maxRatio = pow(10, (reach + half) / args.bins_per_decade);
+  const weighted = Array(reach * 2 + 1).fill(Number());
+
+  // Round amounts are further apart than the reach, so an output fits one
+  outputs.forEach(tokens => {
+    const paid = price * tokens / tokensPerBigUnit;
+
+    return amounts.forEach((usd, index) => {
+      const ratio = usd / paid;
+
+      // Exit early when the output is not near this round amount
+      if (ratio >= maxRatio || ratio <= 1 / maxRatio) {
+        return;
+      }
+
+      const bin = reach + round(log10(ratio) * binsPerDecade);
+
+      counts[bin]++;
+      weighted[bin] += weights[index];
+    });
+  });
+
+  return {counts, weighted};
+};

package/chain/histogram/index.js

@@ -0,0 +1,33 @@
+const bestPosition = require('./best_position');
+const histogramExcess = require('./histogram_excess');
+const histogramPeak = require('./histogram_peak');
+const impliedPricesHistogram = require('./implied_prices_histogram');
+const isRoundTokens = require('./is_round_tokens');
+const kernelWidth = require('./kernel_width');
+const lowerBound = require('./lower_bound');
+const noiseStrength = require('./noise_strength');
+const noiseStrengths = require('./noise_strengths');
+const outputsHistogram = require('./outputs_histogram');
+const peakWidth = require('./peak_width');
+const scorePosition = require('./score_position');
+const smoothBins = require('./smooth_bins');
+const spikeStrengths = require('./spike_strengths');
+const templateAgreement = require('./template_agreement');
+
+module.exports = {
+  bestPosition,
+  histogramExcess,
+  histogramPeak,
+  impliedPricesHistogram,
+  isRoundTokens,
+  kernelWidth,
+  lowerBound,
+  noiseStrength,
+  noiseStrengths,
+  outputsHistogram,
+  peakWidth,
+  scorePosition,
+  smoothBins,
+  spikeStrengths,
+  templateAgreement,
+};

package/chain/histogram/is_round_tokens.js

@@ -0,0 +1,26 @@
+const {roundTokensMultiple} = require('./../constants');
+
+const roundMantissas = [1, 2, 5];
+
+/** Determine if a tokens amount is a round amount of BTC
+
+  {
+    tokens: <Tokens Number>
+  }
+
+  @returns
+  {
+    is_round: <Tokens Are A Round Amount Bool>
+  }
+*/
+module.exports = ({tokens}) => {
+  // Exit early when the amount is a multiple of a thousand sats
+  if (!(tokens % roundTokensMultiple)) {
+    return {is_round: true};
+  }
+
+  // Smaller amounts are round as a one, two or five followed by zeros
+  const digits = String(tokens).replace(/0+$/, '');
+
+  return {is_round: roundMantissas.includes(Number(digits))};
+};

package/chain/histogram/kernel_width.js

@@ -0,0 +1,25 @@
+const peakWidth = require('./peak_width');
+const smoothBins = require('./smooth_bins');
+
+const spike = 1;
+
+/** Measure the width that smoothing alone gives a single bin spike
+
+  {
+    half: <Kernel Half Width in Bins Number>
+  }
+
+  @returns
+  {
+    width: <Smoothed Single Bin Spike Width At Half Height in Bins Number>
+  }
+*/
+module.exports = ({half}) => {
+  const positions = [...Array(half * 2 + 1).keys()];
+
+  const bins = positions.map(i => i === half ? spike : 0);
+
+  const {smoothed} = smoothBins({half, bins});
+
+  return {width: peakWidth({peak: half, bins: smoothed}).width};
+};

package/chain/histogram/lower_bound.js

@@ -0,0 +1,28 @@
+/** Find the first index in a sorted array that is not less than a value
+
+  {
+    sorted: [<Sorted Number>]
+    value: <Value Number>
+  }
+
+  @returns
+  {
+    index: <Index of First Element Not Less Than Value Number>
+  }
+*/
+module.exports = ({sorted, value}) => {
+  const bounds = {high: sorted.length, low: Number()};
+
+  // Halve the range until it has narrowed to a single index
+  while (bounds.low < bounds.high) {
+    const mid = (bounds.low + bounds.high) >>> 1;
+
+    if (sorted[mid] < value) {
+      bounds.low = mid + 1;
+    } else {
+      bounds.high = mid;
+    }
+  }
+
+  return {index: bounds.low};
+};

package/chain/histogram/noise_of_neighbors.js

@@ -0,0 +1,28 @@
+const {ceil} = Math;
+const noiseTrimShare = 0.2;
+const spikeKernelSum = 3;
+
+/** Get the strength that noise alone would give a spike from its neighbors
+
+  {
+    sorted: [<Neighbor Share In Ascending Order Number>]
+  }
+
+  @returns
+  {
+    noise: <Spike Strength From Noise Alone Number>
+  }
+*/
+module.exports = ({sorted}) => {
+  // The highest shares nearby are left out, they can be other spikes
+  const keep = ceil(sorted.length * (1 - noiseTrimShare));
+
+  // Exit early when there are no neighbors to measure noise from
+  if (!keep) {
+    return {noise: Number()};
+  }
+
+  const sum = sorted.reduce((total, n, i) => i < keep ? total + n : total, 0);
+
+  return {noise: spikeKernelSum * (sum / keep)};
+};