@alexbosworth/fiat 2.0.0 → 3.0.0

package/chain/outputs/price_for_dollar_bin.js

@@ -0,0 +1,21 @@
+const {tokensPerBigUnit} = require('./../constants');
+
+const {pow} = Math;
+
+/** Get the USD price at which one dollar lands in a histogram bin
+
+  {
+    bin: <Fractional Bin Where One Dollar Lands Number>
+    bins_per_decade: <Bins Per Factor of Ten Number>
+  }
+
+  @returns
+  {
+    price: <USD Price Number>
+  }
+*/
+module.exports = args => {
+  const decades = args.bin / args.bins_per_decade;
+
+  return {price: tokensPerBigUnit / pow(10, decades)};
+};

package/chain/outputs/price_from_outputs.js

@@ -0,0 +1,98 @@
+const {defaultMaxPrice} = require('./../constants');
+const {defaultMinPrice} = require('./../constants');
+const estimateFromOutputs = require('./estimate_from_outputs');
+const {isRoundTokens} = require('./../histogram');
+
+const {abs} = Math;
+const {isArray} = Array;
+const isTokens = n => Number.isSafeInteger(n) && n > 0;
+
+/** Estimate the USD price of BTC from the values of payment outputs
+
+  {
+    [is_capping_near_round]: <Cap Values Just Off Round BTC Amounts Too Bool>
+    [max_price]: <Maximum Possible USD Price Number>
+    [min_price]: <Minimum Possible USD Price Number>
+    outputs: [<Output Tokens Number>]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    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>
+    evidence: <Share of Prior Weight Observable At the Price Number>
+    is_at_edge: <Best Position Is At the Edge of the Price Window Bool>
+    [is_unsettled]: <Refinement Was Still Moving After Its Last Pass Bool>
+    noise: <Largest Payments Count Away From the Peak 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>
+  }
+*/
+module.exports = args => {
+  if (!isArray(args.outputs) || !args.outputs.length) {
+    throw new Error('ExpectedOutputTokenValuesToDerivePriceFromOutputs');
+  }
+
+  const maxPrice = args.max_price || defaultMaxPrice;
+  const minPrice = args.min_price || defaultMinPrice;
+
+  if (!(minPrice > 0) || !(maxPrice > minPrice)) {
+    throw new Error('ExpectedValidPriceRangeToDerivePriceFromOutputs');
+  }
+
+  const outputs = args.outputs.filter(isTokens);
+
+  if (!outputs.some(tokens => !isRoundTokens({tokens}).is_round)) {
+    throw new Error('ExpectedNonRoundOutputValuesToDerivePriceFromOutputs');
+  }
+
+  // Round USD payments line up at the price, see docs/METHODOLOGY.md
+  const estimate = estimateFromOutputs({
+    outputs,
+    is_capping_near_round: args.is_capping_near_round,
+    max_price: maxPrice,
+    min_price: minPrice,
+  });
+
+  // Counting round BTC values in full shows what the correction changes
+  const counted = estimateFromOutputs({
+    outputs,
+    is_counting_round: true,
+    is_quick: true,
+    max_price: maxPrice,
+    min_price: minPrice,
+  });
+
+  return {
+    agreement: estimate.agreement,
+    cents: estimate.cents,
+    confidence: estimate.confidence,
+    coverage: estimate.coverage,
+    dispersion: estimate.dispersion,
+    evidence: estimate.evidence,
+    is_at_edge: estimate.is_at_edge,
+    is_unsettled: estimate.is_unsettled,
+    noise: estimate.noise,
+    payments: estimate.payments,
+    rivalry: estimate.rivalry,
+    rough_cents: estimate.rough_cents,
+    round_shift: abs(counted.cents / estimate.cents - 1),
+    significance: estimate.significance,
+    spikes: estimate.spikes,
+    stability: estimate.stability || Number(),
+  };
+};

package/chain/outputs/refine_price.js

@@ -0,0 +1,73 @@
+const peakAroundPrice = require('./peak_around_price');
+
+const {abs} = Math;
+const defaultReach = 37;
+const maxIterations = 5;
+const settledBins = 0.5;
+
+/** Refine a rough price to the center of the peak of round payments
+
+  {
+    amounts: [<Round USD Amount Number>]
+    outputs: [<Output Tokens Number>]
+    price: <Rough USD Price Number>
+    [reach]: <Fine Bins On Either Side of the Price to Consider Number>
+    weights: [<Round USD Amount Weight Number>]
+  }
+
+  @returns
+  {
+    dispersion: <Peak Width Beyond Smoothing As Price Fraction Number>
+    is_at_edge: <Peak Is At the Edge of the Refinement Range Bool>
+    [is_unsettled]: <Peak Was Still Moving After the Last Pass Bool>
+    iterations: <Recentering Passes Count Number>
+    noise: <Largest Payments Count Away From the Peak Number>
+    payments: <Estimated Round Payments In the Peak Number>
+    price: <Refined USD Price Number>
+    significance: <Peak Payments Beyond Noise In Standard Deviations Number>
+    spread: <Smoothed Peak Width At Half Height As a Fraction of Price Number>
+  }
+*/
+module.exports = ({amounts, outputs, price, reach, weights}) => {
+  const reachBins = reach || defaultReach;
+
+  // Recenter on the peak until it settles
+  const passes = [...Array(maxIterations).keys()].reduce(passes => {
+    const [latest] = passes;
+
+    const isSettled = !!latest && abs(latest.offset) < settledBins;
+
+    // Exit early when the peak has settled or cannot be followed
+    if (isSettled || (!!latest && latest.is_at_edge)) {
+      return passes;
+    }
+
+    const pass = peakAroundPrice({
+      amounts,
+      outputs,
+      weights,
+      price: !latest ? price : latest.price,
+      reach: reachBins,
+    });
+
+    return [pass].concat(passes);
+  },
+  []);
+
+  const [final] = passes;
+
+  // A peak still moving after the last pass did not settle
+  const isUnsettled = !final.is_at_edge && abs(final.offset) >= settledBins;
+
+  return {
+    dispersion: final.dispersion,
+    is_at_edge: final.is_at_edge,
+    is_unsettled: isUnsettled || undefined,
+    iterations: passes.length,
+    noise: final.noise,
+    payments: final.payments,
+    price: final.price,
+    significance: final.significance,
+    spread: final.spread,
+  };
+};

package/chain/outputs/round_amounts.js

@@ -0,0 +1,49 @@
+const {half} = require('./../constants');
+const {sortBy} = require('./../../arrays');
+const template = require('./template');
+
+const {exp} = Math;
+const flatten = arr => [].concat(...arr);
+const {log10} = Math;
+const {pow} = Math;
+const range = (a, b) => [...Array(b - a).keys()].map(i => a + i);
+
+/** Get the round USD amounts people pay and the prior weight of each
+
+  {}
+
+  @returns
+  {
+    amounts: [<Round USD Amount Number>]
+    weights: [<Prior Weight Number>]
+  }
+*/
+module.exports = ({}) => {
+  const {decades, envelope, mantissas} = template;
+
+  // Each weight is how common the digits are, times an envelope over decades
+  const center = log10(envelope.center_usd);
+  const width = envelope.width_decades;
+
+  const amounts = flatten(range(decades.min, decades.max + 1).map(decade => {
+    return mantissas.map(mantissa => ({
+      usd: mantissa.value * pow(10, decade),
+      weight: mantissa.weight,
+    }));
+  }));
+
+  const rounds = sortBy({
+    array: amounts.filter(amount => amount.usd <= template.max_usd),
+    attribute: 'usd',
+  })
+  .sorted;
+
+  return {
+    amounts: rounds.map(amount => amount.usd),
+    weights: rounds.map(amount => {
+      const distance = (log10(amount.usd) - center) / width;
+
+      return amount.weight * exp(-half * distance * distance);
+    }),
+  };
+};

package/chain/outputs/template.json

@@ -0,0 +1,22 @@
+{
+  "decades": {
+    "max": 5,
+    "min": 0
+  },
+  "envelope": {
+    "center_usd": 100,
+    "width_decades": 1
+  },
+  "mantissas": [
+    {"value": 1, "weight": 1},
+    {"value": 1.5, "weight": 0.2},
+    {"value": 2, "weight": 0.6},
+    {"value": 2.5, "weight": 0.25},
+    {"value": 3, "weight": 0.2},
+    {"value": 4, "weight": 0.12},
+    {"value": 5, "weight": 0.75},
+    {"value": 6, "weight": 0.1},
+    {"value": 7.5, "weight": 0.1}
+  ],
+  "max_usd": 100000
+}

package/coinbase/constants.json

@@ -0,0 +1,5 @@
+{
+  "msPerSecond": 1000,
+  "secondsPerDay": 86400,
+  "supportedFiats": ["EUR", "GBP", "USD"]
+}

package/coinbase/get_coinbase_day_candles.js

@@ -0,0 +1,155 @@
+const asyncAuto = require('async/auto');
+const asyncRetry = require('async/retry');
+const {returnResult} = require('asyncjs-util');
+
+const {isCalendarDay} = require('./../dates');
+const {msPerSecond} = require('./constants');
+const {name} = require('./../package');
+const {secondsPerDay} = require('./constants');
+const {sortBy} = require('./../arrays');
+const {supportedFiats} = require('./constants');
+const {version} = require('./../package');
+
+const api = 'https://api.exchange.coinbase.com/products/';
+const candleFields = 6;
+const dayStartSeconds = day => Date.parse(`${day}T00:00:00Z`) / msPerSecond;
+const defaultFiat = 'USD';
+const granularitySeconds = 60 * 60;
+const interval = n => (1 + Math.random()) * 1000 * Math.pow(2, n);
+const {isArray} = Array;
+const isNumber = n => typeof n === 'number' && !isNaN(n);
+const isRateLimited = err => err[1] === 'CoinbaseRateLimitedCandlesRequest';
+const lastSecond = day => `${day}T23:59:59.000Z`;
+const rateLimitedCode = 429;
+const remoteServiceTimeoutMs = 1000 * 30;
+const times = 5;
+const userAgent = `${name}/${version} (+https://github.com/alexbosworth/fiat)`;
+
+/** Get the hourly BTC candles of a UTC day from Coinbase Exchange
+
+  {
+    date: <Day YYYY-MM-DD String>
+    [fiat]: <Fiat Currency Code String> // default USD
+    request: <Request Function> {headers, url}, (err, r, body) => {}
+  }
+
+  @returns via cbk or Promise
+  {
+    candles: [{
+      close: <Last Trade Fiat Price Number>
+      high: <Highest Trade Fiat Price Number>
+      low: <Lowest Trade Fiat Price Number>
+      open: <First Trade Fiat Price Number>
+      time: <Candle Start Epoch Seconds Number>
+      volume: <BTC Traded Number>
+    }]
+  }
+*/
+module.exports = ({date, fiat, request}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isCalendarDay({day: date}).is_calendar_day) {
+          return cbk([400, 'ExpectedYyyyMmDdDateToGetCoinbaseDayCandles']);
+        }
+
+        if (!!fiat && !supportedFiats.includes(fiat)) {
+          return cbk([400, 'UnsupportedFiatToGetCoinbaseDayCandles']);
+        }
+
+        if (!request) {
+          return cbk([400, 'ExpectedRequestFunctionToGetCoinbaseDayCandles']);
+        }
+
+        return cbk();
+      },
+
+      // Fetch the candles, retrying when rate limited
+      getCandles: ['validate', ({}, cbk) => {
+        const product = `BTC-${fiat || defaultFiat}`;
+
+        const query = [
+          `granularity=${granularitySeconds}`,
+          `start=${date}T00:00:00.000Z`,
+          `end=${lastSecond(date)}`,
+        ];
+
+        const retry = {interval, times, errorFilter: isRateLimited};
+
+        return asyncRetry(retry, cbk => {
+          return request({
+            headers: {'user-agent': userAgent},
+            json: true,
+            timeout: remoteServiceTimeoutMs,
+            url: `${api}${product}/candles?${query.join('&')}`,
+          },
+          (err, r, json) => {
+            if (!!err) {
+              return cbk([503, 'UnexpectedErrorGettingCoinbaseCandles', {
+                err,
+              }]);
+            }
+
+            // Exit early to retry when the request was rate limited
+            if (!!r && r.statusCode === rateLimitedCode) {
+              return cbk([503, 'CoinbaseRateLimitedCandlesRequest']);
+            }
+
+            // Coinbase Exchange explains its own refusals with a message
+            if (!!json && !isArray(json) && !!json.message) {
+              return cbk([503, 'CoinbaseRefusedCandlesRequest', {
+                err: json.message,
+              }]);
+            }
+
+            return cbk(null, json);
+          });
+        },
+        cbk);
+      }],
+
+      // Pull out the candles of the day
+      candles: ['getCandles', ({getCandles}, cbk) => {
+        if (!isArray(getCandles)) {
+          return cbk([503, 'ExpectedArrayOfCandlesInCoinbaseResponse']);
+        }
+
+        const isCandle = candle => {
+          const isComplete = isArray(candle) && candle.length >= candleFields;
+
+          return isComplete && candle.every(isNumber);
+        };
+
+        if (!getCandles.every(isCandle)) {
+          return cbk([503, 'ExpectedCandleValuesInCoinbaseResponse']);
+        }
+
+        const start = dayStartSeconds(date);
+
+        // Only candles that start within the day belong to it
+        const dayCandles = getCandles
+          .filter(([time]) => time >= start && time < start + secondsPerDay)
+          .map(([time, low, high, opening, closing, volume]) => ({
+            high,
+            low,
+            time,
+            volume,
+            close: closing,
+            open: opening,
+          }));
+
+        // An hour without trades has no candle
+        const candles = sortBy({array: dayCandles, attribute: 'time'}).sorted;
+
+        // Exit early when there were no trades, as before a market opened
+        if (!candles.length) {
+          return cbk([503, 'ExpectedCandlesForDayInCoinbaseResponse']);
+        }
+
+        return cbk(null, {candles});
+      }],
+    },
+    returnResult({reject, resolve, of: 'candles'}, cbk));
+  });
+};

package/coinbase/get_coinbase_historic_price.js

@@ -0,0 +1,135 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {dayLength} = require('./../dates/constants');
+const getCoinbaseDayCandles = require('./get_coinbase_day_candles');
+const {msPerSecond} = require('./constants');
+const {secondsPerDay} = require('./constants');
+const {sortBy} = require('./../arrays');
+const {supportedFiats} = require('./constants');
+const {timeOfDate} = require('./../dates');
+
+const {abs} = Math;
+const centsPerUnit = 100;
+const dayStartSeconds = day => Date.parse(`${day}T00:00:00Z`) / msPerSecond;
+const {floor} = Math;
+const knownDays = new WeakMap();
+const {round} = Math;
+const secondsPerHour = 60 * 60;
+const settleSeconds = 60 * 60;
+const typicalPrice = n => (n.high + n.low + n.close) / 3;
+
+/** Get the price of BTC at the hour of a date on Coinbase Exchange
+
+  {
+    date: <ISO 8601 Date String>
+    fiat: <Fiat Currency Code String>
+    request: <Request Function> {headers, url}, (err, r, body) => {}
+  }
+
+  @returns via cbk or Promise
+  {
+    cents: <Cents Per BTC Number>
+    date: <Start of the Hour Priced At ISO 8601 Date String>
+  }
+*/
+module.exports = ({date, fiat, request}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (timeOfDate({date}).time === undefined) {
+          return cbk([400, 'ExpectedDateToGetCoinbaseHistoricPrice']);
+        }
+
+        if (!supportedFiats.includes(fiat)) {
+          return cbk([400, 'UnsupportedFiatToGetCoinbaseHistoricPrice']);
+        }
+
+        if (!request) {
+          return cbk([400, 'ExpectedRequestToGetCoinbaseHistoricPrice']);
+        }
+
+        return cbk();
+      },
+
+      // Get the candles of the day of the date, sharing them across lookups
+      getCandles: ['validate', ({}, cbk) => {
+        // A time without an offset is taken to be in UTC
+        const {time} = timeOfDate({date});
+
+        const day = new Date(time).toISOString().slice(Number(), dayLength);
+
+        // Days are kept with the request function that they were fetched with
+        if (!knownDays.has(request)) {
+          knownDays.set(request, new Map());
+        }
+
+        const days = knownDays.get(request);
+        const key = `${fiat}:${day}`;
+
+        const known = days.get(key);
+
+        // Exit early when the candles of the day are already known
+        if (!!known && !!known.candles) {
+          return cbk(null, {candles: known.candles});
+        }
+
+        // Exit early when the candles of the day are already being fetched
+        if (!!known) {
+          known.waiting.push(cbk);
+
+          return;
+        }
+
+        const waiting = [cbk];
+
+        days.set(key, {waiting});
+
+        const dayEnd = dayStartSeconds(day) + secondsPerDay;
+
+        // The candles of a day are settled once it has been over for an hour
+        const isSettled = dayEnd + settleSeconds <= Date.now() / msPerSecond;
+
+        return getCoinbaseDayCandles({
+          fiat,
+          request,
+          date: day,
+        },
+        (err, res) => {
+          // A failed fetch or a day that is not settled is fetched again later
+          if (!!err || !isSettled) {
+            days.delete(key);
+          } else {
+            days.set(key, {candles: res.candles});
+          }
+
+          return waiting.forEach(cbk => !!err ? cbk(err) : cbk(null, res));
+        });
+      }],
+
+      // The typical price of the hour of the date, or the nearest with trades
+      price: ['getCandles', ({getCandles}, cbk) => {
+        const seconds = timeOfDate({date}).time / msPerSecond;
+
+        const hour = floor(seconds / secondsPerHour) * secondsPerHour;
+
+        const distances = getCandles.candles.map(candle => {
+          return {candle, distance: abs(candle.time - hour)};
+        });
+
+        const [{candle}] = sortBy({
+          array: distances,
+          attribute: 'distance',
+        })
+        .sorted;
+
+        return cbk(null, {
+          cents: round(typicalPrice(candle) * centsPerUnit),
+          date: new Date(candle.time * msPerSecond).toISOString(),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'price'}, cbk));
+  });
+};

package/coinbase/index.js

@@ -1,3 +1,9 @@
 const getCoinbaseCurrentPrice = require('./get_coinbase_current_price');
+const getCoinbaseDayCandles = require('./get_coinbase_day_candles');
+const getCoinbaseHistoricPrice = require('./get_coinbase_historic_price');
 
-module.exports = {getCoinbaseCurrentPrice};
+module.exports = {
+  getCoinbaseCurrentPrice,
+  getCoinbaseDayCandles,
+  getCoinbaseHistoricPrice,
+};

package/dates/constants.json

@@ -0,0 +1,3 @@
+{
+  "dayLength": 10
+}

package/dates/day_of_date.js

@@ -0,0 +1,26 @@
+const {dayLength} = require('./constants');
+const timeOfDate = require('./time_of_date');
+
+const isoDay = time => new Date(time).toISOString().slice(Number(), dayLength);
+
+/** Get the day in UTC of an ISO 8601 date
+
+  {
+    date: <ISO 8601 Date String>
+  }
+
+  @returns
+  {
+    [day]: <Day In UTC YYYY-MM-DD String>
+  }
+*/
+module.exports = ({date}) => {
+  const {time} = timeOfDate({date});
+
+  // Exit early when the date cannot be read
+  if (time === undefined) {
+    return {};
+  }
+
+  return {day: isoDay(time)};
+};

package/dates/index.js

@@ -0,0 +1,5 @@
+const dayOfDate = require('./day_of_date');
+const isCalendarDay = require('./is_calendar_day');
+const timeOfDate = require('./time_of_date');
+
+module.exports = {dayOfDate, isCalendarDay, timeOfDate};

package/dates/is_calendar_day.js

@@ -0,0 +1,16 @@
+const dayOfDate = require('./day_of_date');
+
+/** Determine whether a day is a day of the calendar written as YYYY-MM-DD
+
+  {
+    day: <Day YYYY-MM-DD String>
+  }
+
+  @returns
+  {
+    is_calendar_day: <Day Is a Day of the Calendar Bool>
+  }
+*/
+module.exports = ({day}) => {
+  return {is_calendar_day: !!day && dayOfDate({date: day}).day === day};
+};

package/dates/time_of_date.js

@@ -0,0 +1,61 @@
+const {dayLength} = require('./constants');
+
+const clockFormat = /^((?:[01]\d|2[0-3]):\d{2}(?::\d{2}(?:\.\d+)?)?)(.*)$/;
+const dateFormat = /^(\d{4}-\d{2}-\d{2})(?:[Tt ](.*))?$/;
+const isoDay = time => new Date(time).toISOString().slice(Number(), dayLength);
+const {isInteger} = Number;
+const offsetFormat = /^(?:[Zz]|[+-]\d{2}:?\d{2})?$/;
+
+/** Get the time of an ISO 8601 date
+
+  {
+    date: <ISO 8601 Date String>
+  }
+
+  @returns
+  {
+    [time]: <Epoch Time Milliseconds Number>
+  }
+*/
+module.exports = ({date}) => {
+  // Exit early when there is no date to read
+  if (typeof date !== 'string') {
+    return {};
+  }
+
+  const [, day, rest] = dateFormat.exec(date) || [];
+
+  // Exit early when the date does not start with a day
+  if (!day) {
+    return {};
+  }
+
+  const start = Date.parse(`${day}T00:00:00.000Z`);
+
+  // Exit early when the day is not a day of the calendar
+  if (!isInteger(start) || isoDay(start) !== day) {
+    return {};
+  }
+
+  // Exit early when the date is only a day
+  if (rest === undefined) {
+    return {time: start};
+  }
+
+  const [, clock, offset] = clockFormat.exec(rest) || [];
+
+  // Exit early when the time of day or its offset is not written as one
+  if (!clock || !offsetFormat.test(offset)) {
+    return {};
+  }
+
+  // A time without an offset is in UTC, so it is the same on every machine
+  const time = Date.parse(`${day}T${clock}${(offset || 'Z').toUpperCase()}`);
+
+  // Exit early when the time of day or the offset is not a real one
+  if (!isInteger(time)) {
+    return {};
+  }
+
+  return {time};
+};