@alexbosworth/fiat 2.0.0 → 3.0.0

package/index.js

@@ -1,3 +1,4 @@
+const {chainRates} = require('./chain');
 const {getPrices} = require('./rates');
 
-module.exports = {getPrices};
+module.exports = {chainRates, getPrices};

package/package.json

@@ -1,32 +1,53 @@
 {
+  "allowScripts": {
+    "protobufjs@7.6.6": true
+  },
   "author": {
     "name": "Alex Bosworth",
-    "url": "https://twitter.com/alexbosworth"
+    "url": "https://x.com/alexbosworth"
   },
   "bugs": {
     "url": "https://github.com/alexbosworth/fiat/issues"
   },
   "dependencies": {
-    "async": "3.2.4",
-    "asyncjs-util": "1.2.12"
+    "@alexbosworth/blockchain": "4.12.0",
+    "async": "3.2.6",
+    "asyncjs-util": "1.2.12",
+    "ln-service": "60.1.7"
   },
   "description": "Fiat rates library",
   "engines": {
-    "node": ">=16"
+    "node": ">=22"
   },
+  "files": [
+    "CHANGELOG.md",
+    "arrays",
+    "chain",
+    "coinbase",
+    "coindesk",
+    "coingecko",
+    "dates",
+    "docs",
+    "index.js",
+    "rates",
+    "storage"
+  ],
   "keywords": [
     "currency",
     "rates"
   ],
   "license": "MIT",
-  "main": "index.js",
   "name": "@alexbosworth/fiat",
   "repository": {
     "type": "git",
-    "url": "https://github.com/alexbosworth/fiat.git"
+    "url": "git+https://github.com/alexbosworth/fiat.git"
   },
   "scripts": {
-    "test": "npx nyc@15.1 node --experimental-test-coverage --test"
+    "check-prices": "node scripts/check_prices.js",
+    "prepublishOnly": "node scripts/check_known_prices.js",
+    "test": "node --experimental-test-coverage --test test/arrays/*.js test/chain/*.js test/coinbase/*.js test/coindesk/*.js test/coingecko/*.js test/dates/*.js test/rates/*.js test/storage/*.js",
+    "test-all": "node --experimental-test-coverage --test test/arrays/*.js test/chain/*.js test/coinbase/*.js test/coindesk/*.js test/coingecko/*.js test/dates/*.js test/rates/*.js test/slow/*.js test/storage/*.js",
+    "update-known-prices": "node scripts/update_known_prices.js"
   },
-  "version": "2.0.0"
+  "version": "3.0.0"
 }

package/rates/get_prices.js

@@ -2,17 +2,21 @@ const asyncAuto = require('async/auto');
 const asyncMap = require('async/map');
 const {returnResult} = require('asyncjs-util');
 
-const getCurrentPrice = require('./get_current_price');
+const {getCoinbaseHistoricPrice} = require('./../coinbase');
 const {getCoingeckoRates} = require('./../coingecko');
+const getCurrentPrice = require('./get_current_price');
+const {timeOfDate} = require('./../dates');
 
 const currency = 'BTC';
 const defaultFiat = 'USD';
+const historicProvider = 'coinbase';
 const {isArray} = Array;
 const uniq = arr => Array.from(new Set(arr));
 
 /** Get exchange rates from a rate provider
 
   {
+    [date]: <Rates At the Hour of ISO 8601 Date String>
     from: <From Rate Provider String>
     request: <Request Function> {url}, (err, {statusCode}, body) => {}
     symbols: [<Fiat Symbol String>] // empty defaults to USD
@@ -21,13 +25,13 @@ const uniq = arr => Array.from(new Set(arr));
   @returns via cbk or Promise
   {
     tickers: [{
-      date: <Rate Updated At ISO 8601 Date String>
+      date: <Rate Updated At or Hour Priced At ISO 8601 Date String>
       rate: <Exchange Rate in Cents Number>
       ticker: <Ticker Symbol String>
     }]
   }
 */
-module.exports = ({from, request, symbols}, cbk) => {
+module.exports = ({date, from, request, symbols}, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
@@ -44,6 +48,15 @@ module.exports = ({from, request, symbols}, cbk) => {
           return cbk([400, 'ExpectedSymbolsToGetFiatExchangeRates']);
         }
 
+        if (date !== undefined && timeOfDate({date}).time === undefined) {
+          return cbk([400, 'ExpectedValidDateToGetExchangeRatesAtDate']);
+        }
+
+        // Coinbase has hourly prices back to 2015, for USD, EUR and GBP
+        if (date !== undefined && from !== historicProvider) {
+          return cbk([400, 'ExpectedCoinbaseRateProviderForRatesAtDate']);
+        }
+
         return cbk();
       },
 
@@ -60,10 +73,34 @@ module.exports = ({from, request, symbols}, cbk) => {
         return cbk(null, uniq(prices));
       }],
 
+      // Get the prices at the hour of the date
+      getHistoricPrices: ['priceSymbols', ({priceSymbols}, cbk) => {
+        // Exit early when the current prices are wanted
+        if (date === undefined) {
+          return cbk();
+        }
+
+        return asyncMap(priceSymbols, (fiat, cbk) => {
+          return getCoinbaseHistoricPrice({
+            date,
+            fiat,
+            request,
+          },
+          (err, res) => {
+            if (!!err) {
+              return cbk(err);
+            }
+
+            return cbk(null, {date: res.date, rate: res.cents, ticker: fiat});
+          });
+        },
+        cbk);
+      }],
+
       // Batch fetch prices
       getBatchPrices: ['priceSymbols', ({priceSymbols}, cbk) => {
-        // Exit early when batch rate lookups are supported
-        if (from !== 'coingecko') {
+        // Exit early when batch rate lookups are not supported
+        if (date !== undefined || from !== 'coingecko') {
           return cbk();
         }
 
@@ -72,8 +109,8 @@ module.exports = ({from, request, symbols}, cbk) => {
 
       // Fetch all the prices
       getPrices: ['priceSymbols', ({priceSymbols}, cbk) => {
-        // Exit early when batch rate lookups are supported
-        if (from === 'coingecko') {
+        // Exit early when the prices are at a date or are fetched in a batch
+        if (date !== undefined || from === 'coingecko') {
           return cbk();
         }
 
@@ -98,9 +135,15 @@ module.exports = ({from, request, symbols}, cbk) => {
       // Final set of prices
       prices: [
         'getBatchPrices',
+        'getHistoricPrices',
         'getPrices',
-        ({getBatchPrices, getPrices}, cbk) =>
+        ({getBatchPrices, getHistoricPrices, getPrices}, cbk) =>
       {
+        // Exit early when the prices are at a date
+        if (!!getHistoricPrices) {
+          return cbk(null, {tickers: getHistoricPrices});
+        }
+
         // Exit early when price fetching was batched
         if (!!getBatchPrices) {
           return cbk(null, getBatchPrices);

package/storage/constants.json

@@ -0,0 +1,4 @@
+{
+  "fileVersion": 1,
+  "fsMethods": ["getFile", "makeDirectory", "renameFile", "writeFile"]
+}

package/storage/get_prices_file.js

@@ -0,0 +1,169 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {fileVersion} = require('./constants');
+const {isCalendarDay} = require('./../dates');
+
+const isObject = n => !!n && typeof n === 'object' && !Array.isArray(n);
+const {keys} = Object;
+const missingFileCode = 'ENOENT';
+const {parse} = JSON;
+
+/** Get the prices stored in a prices file
+
+  {
+    fs: {
+      getFile: <Read File Contents Function> (path, cbk) => {}
+    }
+    path: <Prices File Path String>
+  }
+
+  @returns via cbk or Promise
+  {
+    priors: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+    provisional: {
+      <Day YYYY-MM-DD String>: {
+        blocks: [<First Block Height Number>, <Last Block Height Number>]
+        cents: <USD Cents Per BTC Number>
+        hash: <Last Block Hash Hex String>
+        version: <Method Version String>
+      }
+    }
+    rates: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+  }
+*/
+module.exports = ({fs, path}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!fs || typeof fs.getFile !== 'function') {
+          return cbk([400, 'ExpectedFileSystemMethodsToGetPricesFile']);
+        }
+
+        if (!path) {
+          return cbk([400, 'ExpectedPathToGetPricesFile']);
+        }
+
+        return cbk();
+      },
+
+      // Read the file
+      getFile: ['validate', ({}, cbk) => {
+        return fs.getFile(path, (err, res) => {
+          // Exit early when there is no file yet
+          if (!!err && err.code === missingFileCode) {
+            return cbk();
+          }
+
+          // An unreadable file is an error so that it is never written over
+          if (!!err) {
+            return cbk([503, 'FailedToReadPricesFile', {err}]);
+          }
+
+          // Exit early when there is nothing in the file
+          if (!res || !res.length) {
+            return cbk();
+          }
+
+          return cbk(null, res);
+        });
+      }],
+
+      // Parse the file contents
+      parseFile: ['getFile', ({getFile}, cbk) => {
+        // Exit early when there is no file yet
+        if (!getFile) {
+          return cbk(null, {});
+        }
+
+        const parsed = (() => {
+          try {
+            return {contents: parse(getFile.toString())};
+          } catch (err) {
+            return {err};
+          }
+        })();
+
+        // Exit early when the file is not JSON
+        if (!!parsed.err) {
+          return cbk([503, 'FailedToParsePricesFile', {err: parsed.err}]);
+        }
+
+        return cbk(null, parsed.contents);
+      }],
+
+      // Check the contents and pull out the prices
+      prices: ['getFile', 'parseFile', ({getFile, parseFile}, cbk) => {
+        // Exit early when there is no file yet
+        if (!getFile) {
+          return cbk(null, {priors: {}, provisional: {}, rates: {}});
+        }
+
+        if (!isObject(parseFile)) {
+          return cbk([503, 'ExpectedPricesObjectInPricesFile']);
+        }
+
+        const {version} = parseFile;
+
+        // The file format has a version of its own, apart from the method's
+        if (version !== undefined && version !== fileVersion) {
+          return cbk([503, 'UnsupportedPricesFileVersion']);
+        }
+
+        // Only the entries that are prices for days of the calendar are read
+        const read = section => {
+          const entries = isObject(section) ? section : {};
+
+          return keys(entries).reduce((sum, day) => {
+            const isDay = isCalendarDay({day}).is_calendar_day;
+
+            if (isDay && isObject(entries[day])) {
+              sum[day] = entries[day];
+            }
+
+            return sum;
+          },
+          {});
+        };
+
+        return cbk(null, {
+          priors: read(parseFile.priors),
+          provisional: read(parseFile.provisional),
+          rates: read(parseFile.rates),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'prices'}, cbk));
+  });
+};

package/storage/index.js

@@ -0,0 +1,4 @@
+const getPricesFile = require('./get_prices_file');
+const putPricesFile = require('./put_prices_file');
+
+module.exports = {getPricesFile, putPricesFile};

package/storage/is_prices.js

@@ -0,0 +1,31 @@
+const {isCalendarDay} = require('./../dates');
+
+const isDay = day => isCalendarDay({day}).is_calendar_day;
+const isObject = n => !!n && typeof n === 'object' && !Array.isArray(n);
+const {keys} = Object;
+const {values} = Object;
+
+/** Determine whether a value is a set of prices by day
+
+  {
+    prices: <Prices By Day Object>
+  }
+
+  @returns
+  {
+    is_prices: <Value Is a Set of Prices By Day Bool>
+  }
+*/
+module.exports = ({prices}) => {
+  // Exit early when the prices are not an object
+  if (!isObject(prices)) {
+    return {is_prices: false};
+  }
+
+  // Exit early when a price is not for a day of the calendar
+  if (!keys(prices).every(isDay)) {
+    return {is_prices: false};
+  }
+
+  return {is_prices: values(prices).every(isObject)};
+};

package/storage/put_prices_file.js

@@ -0,0 +1,252 @@
+const {dirname} = require('path');
+
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {fileVersion} = require('./constants');
+const {fsMethods} = require('./constants');
+const getPricesFile = require('./get_prices_file');
+const isPrices = require('./is_prices');
+const tempPath = require('./temp_path');
+
+const asJson = obj => JSON.stringify(obj, null, 2);
+const {assign} = Object;
+const {keys} = Object;
+const lastBlock = n => Array.isArray(n.blocks) ? n.blocks[1] : -Infinity;
+const provisionalDays = 2;
+const replaced = ['priors', 'provisional'];
+const types = ['priors', 'provisional', 'rates'];
+
+/** Store prices in a prices file
+
+  {
+    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) => {}
+    }
+    path: <Prices File Path String>
+    priors: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+    [provisional]: {
+      <Day YYYY-MM-DD String>: {
+        blocks: [<First Block Height Number>, <Last Block Height Number>]
+        cents: <USD Cents Per BTC Number>
+        hash: <Last Block Hash Hex String>
+        version: <Method Version String>
+      }
+    }
+    rates: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+    [removed]: [{
+      day: <Day YYYY-MM-DD String>
+      hash: <Last Block Hash Hex String>
+    }]
+  }
+
+  @returns via cbk or Promise
+  {
+    priors: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+    provisional: {
+      <Day YYYY-MM-DD String>: {
+        blocks: [<First Block Height Number>, <Last Block Height Number>]
+        cents: <USD Cents Per BTC Number>
+        hash: <Last Block Hash Hex String>
+        version: <Method Version String>
+      }
+    }
+    rates: {
+      <Day YYYY-MM-DD String>: {
+        [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>
+        [hash]: <Last Block Hash Hex String>
+        [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>
+        [dispersion]: <Peak Width Beyond Smoothing As Price Fraction Number>
+        [stability]: <Largest Price Change From Perturbed Refinement Number>
+        [version]: <Method Version String>
+      }
+    }
+  }
+*/
+module.exports = (args, cbk) => {
+  const {fs, path, priors, provisional, rates, removed} = args;
+
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!fs || !fsMethods.every(n => typeof fs[n] === 'function')) {
+          return cbk([400, 'ExpectedFileSystemMethodsToPutPricesFile']);
+        }
+
+        if (!path) {
+          return cbk([400, 'ExpectedPathToPutPricesFile']);
+        }
+
+        // Prices are keyed by days of the calendar as YYYY-MM-DD
+        if (!isPrices({prices: priors}).is_prices) {
+          return cbk([400, 'ExpectedPriorsToPutPricesFile']);
+        }
+
+        const isProvisional = isPrices({prices: provisional}).is_prices;
+
+        if (provisional !== undefined && !isProvisional) {
+          return cbk([400, 'ExpectedProvisionalPricesToPutPricesFile']);
+        }
+
+        if (!isPrices({prices: rates}).is_prices) {
+          return cbk([400, 'ExpectedRatesToPutPricesFile']);
+        }
+
+        if (removed !== undefined && !Array.isArray(removed)) {
+          return cbk([400, 'ExpectedRemovedPricesToPutPricesFile']);
+        }
+
+        return cbk();
+      },
+
+      // Make sure the directory exists, it may already be there
+      makeDirectory: ['validate', ({}, cbk) => {
+        return fs.makeDirectory(dirname(path), () => cbk());
+      }],
+
+      // Get the prices in the file, a file that cannot be read is not written
+      getFile: ['makeDirectory', ({}, cbk) => getPricesFile({fs, path}, cbk)],
+
+      // Merge with the prices that are already in the file
+      merge: ['getFile', ({getFile}, cbk) => {
+        const merged = {
+          priors: assign({}, priors),
+          provisional: assign({}, provisional),
+          rates: assign({}, rates),
+          version: fileVersion,
+        };
+
+        keys(getFile.rates).forEach(day => {
+          merged.rates[day] = merged.rates[day] || getFile.rates[day];
+        });
+
+        keys(getFile.priors).forEach(day => {
+          merged.priors[day] = merged.priors[day] || getFile.priors[day];
+        });
+
+        // The provisional price derived from the later blocks is kept
+        keys(getFile.provisional).forEach(day => {
+          const mine = merged.provisional[day];
+          const theirs = getFile.provisional[day];
+
+          if (!mine || lastBlock(theirs) > lastBlock(mine)) {
+            merged.provisional[day] = theirs;
+          }
+        });
+
+        // A full day rate replaces the other prices of its version
+        keys(merged.rates).forEach(day => {
+          const {version} = merged.rates[day];
+
+          const isSameVersion = type => {
+            const other = merged[type][day];
+
+            return !!other && other.version === version;
+          };
+
+          replaced.filter(isSameVersion).forEach(type => {
+            delete merged[type][day];
+          });
+        });
+
+        const days = keys(merged.provisional).sort();
+
+        // Only the provisional prices of the latest days are kept
+        days.slice(Number(), -provisionalDays).forEach(day => {
+          delete merged.provisional[day];
+        });
+
+        // A price from blocks that were replaced is removed for good
+        (removed || []).forEach(({day, hash}) => {
+          types.filter(type => {
+            return !!merged[type][day] && merged[type][day].hash === hash;
+          })
+          .forEach(type => delete merged[type][day]);
+        });
+
+        return cbk(null, merged);
+      }],
+
+      // Each write has its own temporary file
+      temp: ['merge', ({}, cbk) => cbk(null, tempPath({path}).path)],
+
+      // Write to a temporary file so a partial write is never seen
+      write: ['merge', 'temp', ({merge, temp}, cbk) => {
+        return fs.writeFile(temp, asJson(merge), err => {
+          if (!!err) {
+            return cbk([503, 'FailedToWritePricesFile', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+
+      // Atomically swap the temporary file in place of the prices file
+      swap: ['merge', 'temp', 'write', ({merge, temp}, cbk) => {
+        return fs.renameFile(temp, path, err => {
+          if (!!err) {
+            return cbk([503, 'FailedToReplacePricesFile', {err}]);
+          }
+
+          return cbk(null, merge);
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'swap'}, cbk));
+  });
+};

package/storage/temp_path.js

@@ -0,0 +1,22 @@
+const {randomBytes} = require('crypto');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const randomIdBytes = 4;
+
+/** Get the path of a temporary file of its own next to a file
+
+  {
+    path: <File Path String>
+  }
+
+  @returns
+  {
+    path: <Temporary File Path String>
+  }
+*/
+module.exports = ({path}) => {
+  // The pid and random bytes keep writers from sharing a temporary file
+  const id = bufferAsHex(randomBytes(randomIdBytes));
+
+  return {path: `${path}.${process.pid}.${id}`};
+};

package/.gitattributes

@@ -1 +0,0 @@
-package-lock.json binary

package/.tm_properties

@@ -1 +0,0 @@
-exclude = '{$exclude,node_modules,*~}'