@alexbosworth/fiat 2.0.0 → 3.0.0

package/chain/histogram/noise_strength.js

@@ -0,0 +1,35 @@
+const {kernelBins} = require('./../constants');
+const noiseOfNeighbors = require('./noise_of_neighbors');
+const {noiseRadius} = require('./../constants');
+
+const {max} = Math;
+const {min} = Math;
+
+/** Get the strength that noise alone would give a spike at a center
+
+  {
+    center: <Spike Center Bin Number>
+    excess: [<Share of Outputs Above Local Background Number>]
+    min_bin: <Lowest Observable Bin Number>
+  }
+
+  @returns
+  {
+    noise: <Spike Strength From Noise Alone Number>
+  }
+*/
+module.exports = args => {
+  const {center, excess} = args;
+
+  const start = max(Number(), args.min_bin, center - noiseRadius);
+
+  const end = max(start, min(excess.length, center + noiseRadius + 1));
+
+  // The neighbors on each side, leaving out the spike itself
+  const below = excess.slice(start, max(start, center - kernelBins));
+  const above = excess.slice(max(start, center + kernelBins + 1), end);
+
+  const sorted = below.concat(above).sort((a, b) => a - b);
+
+  return noiseOfNeighbors({sorted});
+};

package/chain/histogram/noise_strengths.js

@@ -0,0 +1,29 @@
+const {kernelBins} = require('./../constants');
+const noiseOfNeighbors = require('./noise_of_neighbors');
+const {noiseRadius} = require('./../constants');
+const sortedNeighbors = require('./sorted_neighbors');
+
+/** Get the strength that noise alone would give a spike at each bin
+
+  {
+    excess: [<Share of Outputs Above Local Background Number>]
+    min_bin: <Lowest Observable Bin Number>
+  }
+
+  @returns
+  {
+    noise: [<Spike Strength From Noise Alone Number>]
+  }
+*/
+module.exports = args => {
+  // The neighbors of a bin are near it, leaving out the spike itself
+  const {values} = sortedNeighbors({
+    bins: args.excess,
+    exclude: kernelBins,
+    min_bin: args.min_bin,
+    radius: noiseRadius,
+    value: sorted => noiseOfNeighbors({sorted}).noise,
+  });
+
+  return {noise: values};
+};

package/chain/histogram/outputs_histogram.js

@@ -0,0 +1,80 @@
+const isRoundTokens = require('./is_round_tokens');
+const lowerBound = require('./lower_bound');
+const {maxTokens} = require('./../constants');
+const {minTokens} = require('./../constants');
+const {roundTokensMultiple} = require('./../constants');
+
+const binsPerDecade = 200;
+const {ceil} = Math;
+const {floor} = Math;
+const {log10} = Math;
+const {max} = Math;
+const {min} = Math;
+const minNeighborhood = 20;
+const neighborhoodShare = 0.001;
+const {round} = Math;
+
+/** Make a normalized log scale histogram of output values
+
+  {
+    [is_counting_round]: <Count Round Values In Full Bool>
+    outputs: [<Output Tokens Number>]
+  }
+
+  @returns
+  {
+    bins: [<Share of Outputs in Bin Number>]
+    bins_per_decade: <Bins Per Factor of Ten Number>
+  }
+*/
+module.exports = args => {
+  const {outputs} = args;
+
+  const binFor = tokens => round(log10(tokens) * binsPerDecade);
+  const counts = Array(round(log10(maxTokens) * binsPerDecade) + 1).fill(0);
+  const rounded = new Map();
+
+  const included = outputs.filter(n => n >= minTokens && n <= maxTokens);
+
+  const plain = included.filter(tokens => {
+    // Exit early when the value is not round or round values count in full
+    if (!!args.is_counting_round || !isRoundTokens({tokens}).is_round) {
+      return true;
+    }
+
+    rounded.set(tokens, (rounded.get(tokens) || Number()) + 1);
+
+    return false;
+  });
+
+  plain.forEach(tokens => counts[binFor(tokens)]++);
+
+  const sorted = Float64Array.from(plain).sort();
+
+  // A round value counts for no more than its neighboring values suggest
+  rounded.forEach((count, tokens) => {
+    const reach = max(minNeighborhood, round(tokens * neighborhoodShare));
+
+    const high = tokens + reach;
+    const low = tokens - reach;
+
+    const start = lowerBound({sorted, value: low}).index;
+    const end = lowerBound({sorted, value: high + 1}).index;
+
+    const highRound = floor(high / roundTokensMultiple);
+    const lowRound = ceil(low / roundTokensMultiple);
+
+    const values = reach * 2 + 1 - (highRound - lowRound + 1);
+
+    const expected = (end - start) / max(1, values);
+
+    counts[binFor(tokens)] += min(count, expected);
+  });
+
+  const total = counts.reduce((sum, count) => sum + count, Number());
+
+  return {
+    bins: counts.map(count => !total ? 0 : count / total),
+    bins_per_decade: binsPerDecade,
+  };
+};

package/chain/histogram/parabola_peak.js

@@ -0,0 +1,28 @@
+const {half} = require('./../constants');
+
+const twice = 2;
+
+/** Find the peak of a parabola fit through three evenly spaced points
+
+  {
+    above: <Value After Center Number>
+    below: <Value Before Center Number>
+    center: <Center Value Number>
+  }
+
+  @returns
+  {
+    delta: <Peak Offset From Center In Units of Point Spacing Number>
+  }
+*/
+module.exports = ({above, below, center}) => {
+  const curvature = below - twice * center + above;
+
+  // Exit early when the points do not form a peak
+  if (curvature >= 0) {
+    return {delta: 0};
+  }
+
+  // A negative zero is normalized to zero
+  return {delta: half * (below - above) / curvature || 0};
+};

package/chain/histogram/payments_near_position.js

@@ -0,0 +1,31 @@
+const {max} = Math;
+const {min} = Math;
+const range = (a, b) => [...Array(b - a).keys()].map(i => a + i);
+
+/** Count the implied prices above the background around a position
+
+  {
+    background: [<Background Count In Bin Number>]
+    counts: [<Implied Prices In Bin Count Number>]
+    kernel: <Smoothing Kernel Half Width in Bins Number>
+    position: <Bin Index Number>
+  }
+
+  @returns
+  {
+    above: <Counts Above the Background Number>
+    observed: <Counts Observed Number>
+  }
+*/
+module.exports = ({background, counts, kernel, position}) => {
+  const start = max(Number(), position - kernel);
+  const end = min(counts.length, position + kernel + 1);
+
+  return range(start, end).reduce((sum, bin) => {
+    return {
+      above: sum.above + counts[bin] - background[bin],
+      observed: sum.observed + counts[bin],
+    };
+  },
+  {above: Number(), observed: Number()});
+};

package/chain/histogram/peak_width.js

@@ -0,0 +1,37 @@
+const {half} = require('./../constants');
+
+/** Measure the width of a peak in histogram bins at half of its height
+
+  {
+    bins: [<Bin Value Number>]
+    peak: <Peak Bin Index Number>
+  }
+
+  @returns
+  {
+    width: <Contiguous Bins At or Above Half the Peak Height Count Number>
+  }
+*/
+module.exports = ({bins, peak}) => {
+  const threshold = (bins[peak] || 0) * half;
+
+  // Exit early when there is no peak
+  if (!threshold) {
+    return {width: Number()};
+  }
+
+  const isHigh = bin => bins[bin] !== undefined && bins[bin] >= threshold;
+
+  const lower = bins.slice(Number(), peak).reverse();
+
+  const left = lower.findIndex((value, gap) => !isHigh(peak - gap - 1));
+
+  const higher = bins.slice(peak + 1);
+
+  const right = higher.findIndex((value, gap) => !isHigh(peak + gap + 1));
+
+  const before = left === -1 ? peak : left;
+  const after = right === -1 ? bins.length - peak - 1 : right;
+
+  return {width: before + after + 1};
+};

package/chain/histogram/position_score.js

@@ -0,0 +1,38 @@
+const {kernelBins} = require('./../constants');
+
+/** Score a dollar position by the strength of its spikes above their noise
+
+  {
+    dollar_bin: <Bin Where One Dollar Lands Number>
+    min_bin: <Lowest Observable Bin Number>
+    noise: [<Spike Strength From Noise Alone At Bin Number>]
+    shifts: [<Bins Above the Dollar Bin of Round USD Amount Number>]
+    strengths: [<Spike Strength At Bin Number>]
+    weights: [<Amount Weight Number>]
+  }
+
+  @returns
+  {
+    score: <Weighted Strength of Observable Spikes Above Noise Number>
+  }
+*/
+module.exports = args => {
+  const {noise, shifts, strengths, weights} = args;
+
+  const score = shifts.reduce((sum, shift, index) => {
+    const center = args.dollar_bin + shift;
+
+    const isAbove = center + kernelBins >= strengths.length;
+    const isBelow = center - kernelBins < args.min_bin;
+
+    // Exit early when the whole spike of the amount is not in the histogram
+    if (isAbove || isBelow) {
+      return sum;
+    }
+
+    return sum + (strengths[center] - noise[center]) * weights[index];
+  },
+  Number());
+
+  return {score};
+};

package/chain/histogram/score_position.js

@@ -0,0 +1,94 @@
+const {kernelBins} = require('./../constants');
+
+const {isArray} = Array;
+const {log10} = Math;
+const {max} = Math;
+const minPatternSpikes = 3;
+const minPatternStrength = 0.2;
+const {round} = Math;
+
+/** Score a dollar position of the round USD pattern against histogram excess
+
+  {
+    amounts: [<Round USD Amount Number>]
+    bins_per_decade: <Bins Per Factor of Ten Number>
+    dollar_bin: <Bin Where One Dollar Lands 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>]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    evidence: <Share of Weight That Was Observable Number>
+    is_pattern: <Position Shows a Multi-Denomination Pattern Bool>
+    observable: [<Amount Is Observable Bool>]
+    score: <Weighted Strength of Observable Spikes Above Noise Number>
+    strengths: [<Observable Spike Strength Above Noise or Zero Number>]
+  }
+*/
+module.exports = args => {
+  if (!isArray(args.strengths)) {
+    throw new Error('ExpectedSpikeStrengthsToScorePosition');
+  }
+
+  if (!isArray(args.noise)) {
+    throw new Error('ExpectedNoiseStrengthsToScorePosition');
+  }
+
+  if (args.noise.length !== args.strengths.length) {
+    throw new Error('ExpectedNoiseStrengthOfEveryBinToScorePosition');
+  }
+
+  const {amounts, strengths, weights} = args;
+
+  const binsPerDecade = args.bins_per_decade;
+  const dollarBin = args.dollar_bin;
+
+  const centers = amounts.map(usd => {
+    return dollarBin + round(log10(usd) * binsPerDecade);
+  });
+
+  // An amount is observable when its whole spike is within the histogram
+  const observable = centers.map(center => {
+    const high = center + kernelBins < strengths.length;
+    const low = center - kernelBins >= args.min_bin;
+
+    return high && low;
+  });
+
+  // Spike strengths above the strength that noise alone would give them
+  const above = centers.map((center, index) => {
+    // Exit early when the amount cannot be seen at this position
+    if (!observable[index]) {
+      return Number();
+    }
+
+    return strengths[center] - args.noise[center];
+  });
+
+  const observedWeight = weights.reduce((sum, weight, index) => {
+    return sum + (!observable[index] ? 0 : weight);
+  },
+  Number());
+
+  const totalWeight = weights.reduce((sum, weight) => sum + weight, Number());
+
+  const observed = above.map(n => max(Number(), n));
+
+  const strongest = max(...observed);
+
+  const spikes = observed.filter(n => n >= strongest * minPatternStrength);
+
+  return {
+    observable,
+    evidence: !totalWeight ? 0 : observedWeight / totalWeight,
+    is_pattern: !!strongest && spikes.length >= minPatternSpikes,
+    score: above.reduce((sum, n, i) => sum + n * weights[i], Number()),
+    strengths: observed,
+  };
+};

package/chain/histogram/smooth_bins.js

@@ -0,0 +1,29 @@
+const {abs} = Math;
+const range = (a, b) => [...Array(b - a).keys()].map(i => a + i);
+
+/** Smooth histogram bins with a triangular kernel
+
+  {
+    bins: [<Bin Value Number>]
+    half: <Kernel Half Width in Bins Number>
+  }
+
+  @returns
+  {
+    smoothed: [<Smoothed Bin Value Number>]
+  }
+*/
+module.exports = ({bins, half}) => {
+  const offsets = range(-half, half + 1);
+
+  const smoothed = bins.map((value, bin) => {
+    return offsets.reduce((sum, offset) => {
+      const weight = 1 - abs(offset) / (half + 1);
+
+      return sum + weight * (bins[bin + offset] || 0);
+    },
+    Number());
+  });
+
+  return {smoothed};
+};

package/chain/histogram/sorted_neighbors.js

@@ -0,0 +1,89 @@
+const lowerBound = require('./lower_bound');
+
+const {abs} = Math;
+const {max} = Math;
+const {min} = Math;
+const range = (a, b) => [...Array(b - a).keys()].map(i => a + i);
+
+/** Get a value from the sorted shares of the neighbors of each bin
+
+  {
+    bins: [<Share Number>]
+    exclude: <Bins Next to a Bin to Leave Out of Its Neighbors Number>
+    min_bin: <Lowest Bin That Can Be a Neighbor Number>
+    radius: <Bins On Either Side to Take Neighbors From Number>
+    value: <Value From Sorted Neighbor Shares Function> (sorted) => <Value>
+  }
+
+  @returns
+  {
+    values: [<Value From the Sorted Shares of the Neighbors of the Bin>]
+  }
+*/
+module.exports = args => {
+  const {bins, exclude, radius, value} = args;
+
+  const first = max(Number(), args.min_bin);
+
+  // The shares of the neighbors of a bin, kept in order from bin to bin
+  const sorted = [];
+
+  // Moving on to a bin only changes the bins at the edges of its reach and at
+  // the edges of the bins left out around it
+  const edges = [-1 - radius, -1 - exclude, exclude, radius]
+    .filter((offset, i, offsets) => offsets.indexOf(offset) === i);
+
+  // A neighbor of a bin is within its reach and beyond the bins left out
+  const isNeighbor = (index, bin) => {
+    const distance = abs(index - bin);
+
+    const isBin = index >= first && index < bins.length;
+
+    return isBin && distance > exclude && distance <= radius;
+  };
+
+  // Put the share of a bin in its place among the sorted shares
+  const add = index => {
+    const at = lowerBound({sorted, value: bins[index]}).index;
+
+    return sorted.splice(at, Number(), bins[index]);
+  };
+
+  // Take the share of a bin out of the sorted shares
+  const drop = index => {
+    const at = lowerBound({sorted, value: bins[index]}).index;
+
+    return sorted.splice(at, 1);
+  };
+
+  // Move the neighbors on from the bin before a bin to the bin
+  const step = bin => {
+    return edges.map(offset => bin + offset).forEach(index => {
+      const isNeighborNow = isNeighbor(index, bin);
+      const wasNeighbor = isNeighbor(index, bin - 1);
+
+      // Exit early when the bin is still a neighbor, or still is not one
+      if (isNeighborNow === wasNeighbor) {
+        return;
+      }
+
+      return isNeighborNow ? add(index) : drop(index);
+    });
+  };
+
+  // The first bin starts out with all of its neighbors
+  range(Number(), min(bins.length, radius + 1))
+    .filter(index => isNeighbor(index, Number()))
+    .forEach(add);
+
+  const values = bins.map((share, bin) => {
+    // A bin after the first moves the neighbors on from the bin before it
+    if (!!bin) {
+      step(bin);
+    }
+
+    return value(sorted);
+  });
+
+  return {values};
+};

package/chain/histogram/spike_strengths.js

@@ -0,0 +1,33 @@
+const {spikeKernel} = require('./../constants');
+
+const half = (spikeKernel.length - 1) / 2;
+const {isArray} = Array;
+
+/** Measure the strength of a spike centered at each bin of a histogram
+
+  {
+    excess: [<Share of Outputs Above Local Background Number>]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    strengths: [<Spike Strength At Bin Number>]
+  }
+*/
+module.exports = ({excess}) => {
+  if (!isArray(excess)) {
+    throw new Error('ExpectedHistogramExcessToMeasureSpikeStrengths');
+  }
+
+  const strengths = excess.map((share, center) => {
+    return spikeKernel.reduce((sum, weight, offset) => {
+      return sum + weight * (excess[center + offset - half] || 0);
+    },
+    0);
+  });
+
+  return {strengths};
+};

package/chain/histogram/template_agreement.js

@@ -0,0 +1,27 @@
+const dotProduct = (a, b) => a.reduce((sum, n, i) => sum + n * b[i], Number());
+const magnitude = arr => Math.sqrt(arr.reduce((sum, n) => sum + n * n, 0));
+
+/** Measure how well measured spike strengths agree with the template weights
+
+  {
+    strengths: [<Spike Strength Number>]
+    weights: [<Template Weight Number>]
+  }
+
+  @returns
+  {
+    agreement: <Cosine Similarity Number>
+  }
+*/
+module.exports = ({strengths, weights}) => {
+  const dot = dotProduct(strengths, weights);
+  const strengthsNorm = magnitude(strengths);
+  const weightsNorm = magnitude(weights);
+
+  // Exit early when there are no spikes to compare
+  if (!strengthsNorm || !weightsNorm) {
+    return {agreement: Number()};
+  }
+
+  return {agreement: dot / (strengthsNorm * weightsNorm)};
+};

package/chain/index.js

@@ -0,0 +1,3 @@
+const chainRates = require('./chain_rates');
+
+module.exports = {chainRates};

package/chain/known/earliest_supported_day.js

@@ -0,0 +1,12 @@
+const earliestDay = '2021-10-20';
+
+/** Get the earliest day that prices are derived for
+
+  {}
+
+  @returns
+  {
+    day: <Earliest Supported Day YYYY-MM-DD String>
+  }
+*/
+module.exports = ({}) => ({day: earliestDay});

package/chain/known/index.js

@@ -0,0 +1,11 @@
+const earliestSupportedDay = require('./earliest_supported_day');
+const knownPrices = require('./known_prices');
+const methodVersion = require('./method_version');
+const parseKnownPrices = require('./parse_known_prices');
+
+module.exports = {
+  earliestSupportedDay,
+  knownPrices,
+  methodVersion,
+  parseKnownPrices,
+};

package/chain/known/known_prices.js

@@ -0,0 +1,43 @@
+const {join} = require('path');
+const {readFileSync} = require('fs');
+
+const methodVersion = require('./method_version');
+const parseKnownPrices = require('./parse_known_prices');
+
+const fileName = 'known_prices.json';
+const loaded = new Map();
+
+/** Get the prices that were shipped with the method
+
+  {}
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    rates: {
+      <Day YYYY-MM-DD String>: {
+        cents: <USD Cents Per BTC Number>
+        version: <Method Version String>
+      }
+    }
+  }
+*/
+module.exports = ({}) => {
+  // Exit early when the prices were already read
+  if (loaded.has(fileName)) {
+    return {rates: loaded.get(fileName)};
+  }
+
+  const text = readFileSync(join(__dirname, fileName), 'utf8');
+
+  const {rates, version} = parseKnownPrices({text});
+
+  // Prices derived by another version of the method are not used
+  const current = version === methodVersion({}).version ? rates : {};
+
+  loaded.set(fileName, current);
+
+  return {rates: current};
+};