@hackerhouse/xpub-scan 1.0.0

package/lib/configuration/currencies.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currencies = exports.DerivationMode = void 0;
+const coininfo_1 = __importDefault(require("coininfo"));
+var DerivationMode;
+(function (DerivationMode) {
+    DerivationMode["LEGACY"] = "Legacy";
+    DerivationMode["NATIVE"] = "Native SegWit";
+    DerivationMode["SEGWIT"] = "SegWit";
+    DerivationMode["TAPROOT"] = "Taproot";
+    DerivationMode["BCH"] = "Bitcoin Cash";
+    DerivationMode["ETHEREUM"] = "Ethereum";
+    DerivationMode["DOGECOIN"] = "Dogecoin";
+    DerivationMode["UNKNOWN"] = "Unknown";
+})(DerivationMode || (exports.DerivationMode = DerivationMode = {}));
+exports.currencies = {
+    btc: {
+        name: "Bitcoin",
+        symbol: "BTC",
+        network_mainnet: coininfo_1.default.bitcoin.main.toBitcoinJS(),
+        network_testnet: coininfo_1.default.bitcoin.test.toBitcoinJS(),
+        derivationModes: [
+            DerivationMode.NATIVE,
+            DerivationMode.TAPROOT,
+            DerivationMode.SEGWIT,
+            DerivationMode.LEGACY,
+        ],
+        precision: Math.pow(10, 8),
+        utxo_based: true,
+    },
+    bch: {
+        name: "Bitcoin Cash",
+        symbol: "BCH",
+        network_mainnet: coininfo_1.default.bitcoincash.main.toBitcoinJS(),
+        network_testnet: coininfo_1.default.bitcoincash.test.toBitcoinJS(),
+        derivationModes: [DerivationMode.BCH],
+        precision: Math.pow(10, 8),
+        utxo_based: true,
+    },
+    ltc: {
+        name: "Litecoin",
+        symbol: "LTC",
+        network_mainnet: coininfo_1.default.litecoin.main.toBitcoinJS(),
+        network_testnet: coininfo_1.default.litecoin.test.toBitcoinJS(),
+        derivationModes: [
+            DerivationMode.NATIVE,
+            DerivationMode.SEGWIT,
+            DerivationMode.LEGACY,
+        ],
+        precision: Math.pow(10, 8),
+        utxo_based: true,
+    },
+    eth: {
+        name: "Ethereum",
+        symbol: "ETH",
+        precision: Math.pow(10, 18),
+        utxo_based: false,
+        derivationModes: [DerivationMode.ETHEREUM],
+    },
+    doge: {
+        name: "Dogecoin",
+        symbol: "DOGE",
+        network_mainnet: coininfo_1.default.dogecoin.main.toBitcoinJS(),
+        network_testnet: coininfo_1.default.dogecoin.test.toBitcoinJS(),
+        precision: Math.pow(10, 8),
+        utxo_based: true,
+        derivationModes: [DerivationMode.DOGECOIN],
+    },
+};

package/lib/configuration/settings.d.ts

@@ -0,0 +1,51 @@
+import { Currency } from "../models/currency";
+declare const VERBOSE = false;
+declare const ETH_FIXED_PRECISION = 10;
+declare const DEFAULT_API_URLS: {
+    general: string;
+    bch: string;
+    eth: string;
+};
+declare const CRYPTOAPIS_URL = "https://rest.cryptoapis.io/v2/blockchain-data/{currency}/{network}";
+declare const DERIVATION_SCOPE: {
+    quick_search: {
+        account: {
+            min: number;
+            max: number;
+        };
+        index: {
+            min: number;
+            max: number;
+        };
+    };
+    deep_search: {
+        account: {
+            min: number;
+            max: number;
+        };
+        index: {
+            min: number;
+            max: number;
+        };
+    };
+};
+declare const EXTERNAL_EXPLORERS_URLS: {
+    general: string;
+    bch: string;
+    eth: string;
+};
+export declare const configuration: {
+    currency: Currency;
+    testnet: boolean;
+    specificDerivationMode: string;
+    externalProviderURL: string;
+    APIKey: string | undefined;
+    providerType: string;
+    silent: boolean;
+    quiet: boolean;
+    commandLineMode: boolean;
+    gap_limit: string | number;
+    augmentedImport: boolean;
+    blockHeightUpperLimit: number;
+};
+export { DEFAULT_API_URLS, CRYPTOAPIS_URL, VERBOSE, ETH_FIXED_PRECISION, DERIVATION_SCOPE, EXTERNAL_EXPLORERS_URLS, };

package/lib/configuration/settings.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTERNAL_EXPLORERS_URLS = exports.DERIVATION_SCOPE = exports.ETH_FIXED_PRECISION = exports.VERBOSE = exports.CRYPTOAPIS_URL = exports.DEFAULT_API_URLS = exports.configuration = void 0;
+const dotenv = __importStar(require("dotenv"));
+const currency_1 = require("../models/currency");
+// ┏━━━━━━━━━┓
+// ┃ GENERAL ┃
+// ┗━━━━━━━━━┛
+const VERBOSE = false;
+exports.VERBOSE = VERBOSE;
+const ETH_FIXED_PRECISION = 10; // Decimal places for ETH (recommended for Crypto APIs provider: 10)
+exports.ETH_FIXED_PRECISION = ETH_FIXED_PRECISION;
+// max number of addresses to probe when checking a possible gap between derivation indices
+// (that is: range of indices not used for derivation)
+const DEFAULT_GAP_LIMIT = 20;
+// ┏━━━━━━━━━━━┓
+// ┃ PROVIDERS ┃
+// ┗━━━━━━━━━━━┛
+// use {currency} and {address} as placeholders for the currency name and the address;
+// {type} for the transaction type, and {item} for either an address or a transaction
+const DEFAULT_API_URLS = {
+    general: "https://blockstream.info/{network}/api/address/{address}",
+    bch: "https://rest.bitcoin.com/v2/address/{type}/bitcoincash:{address}",
+    eth: "https://api.blockcypher.com/v1/eth/main/{type}/{item}",
+};
+exports.DEFAULT_API_URLS = DEFAULT_API_URLS;
+// use {currency} and {network} as placeholders for the currency name and the network (mainnet v. testnet)
+const CRYPTOAPIS_URL = "https://rest.cryptoapis.io/v2/blockchain-data/{currency}/{network}";
+exports.CRYPTOAPIS_URL = CRYPTOAPIS_URL;
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ XPUB <=> ADDRESS COMPARISON ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+// scope of the derivation for the comparison
+// only concerning xpub-search
+const DERIVATION_SCOPE = {
+    // _quick search_
+    // the common range from which addresses
+    // are generally derived
+    quick_search: {
+        account: {
+            min: 0,
+            max: 4,
+        },
+        index: {
+            min: 0,
+            max: 1000,
+        },
+    },
+    // _deep search_
+    // an extended range for a deeper analysis,
+    // initiated when quick search fails
+    deep_search: {
+        account: {
+            min: 0,
+            max: 1000,
+        },
+        index: {
+            min: 0,
+            max: 100000,
+        },
+    },
+};
+exports.DERIVATION_SCOPE = DERIVATION_SCOPE;
+// ┏━━━━━━━━━━━━━┓
+// ┃ HTML REPORT ┃
+// ┗━━━━━━━━━━━━━┛
+const EXTERNAL_EXPLORERS_URLS = {
+    general: "https://live.blockcypher.com/{currency}/{type}/{item}",
+    bch: "https://blockchair.com/{currency}/{type}/{item}",
+    eth: "https://etherscan.io/{type}/{item}",
+};
+exports.EXTERNAL_EXPLORERS_URLS = EXTERNAL_EXPLORERS_URLS;
+// ┏━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ CONFIGURATION OBJECT ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━┛
+dotenv.config();
+exports.configuration = {
+    currency: new currency_1.Currency(),
+    testnet: false,
+    specificDerivationMode: "",
+    externalProviderURL: "",
+    APIKey: process.env.XPUB_SCAN_CUSTOM_API_KEY_V2,
+    providerType: "default",
+    silent: false,
+    quiet: false,
+    commandLineMode: false,
+    gap_limit: process.env.GAP_LIMIT || DEFAULT_GAP_LIMIT,
+    augmentedImport: false,
+    blockHeightUpperLimit: 0, // comparison mode: block height limit
+};

package/lib/display.d.ts

@@ -0,0 +1,12 @@
+import { Address } from "./models/address";
+import { Operation } from "./models/operation";
+import { Summary } from "./types";
+import { DerivationMode } from "./configuration/currencies";
+import BigNumber from "bignumber.js";
+declare function updateAddressDetails(address: Address): void;
+declare function showSortedOperations(sortedOperations: Array<Operation>): void;
+declare function showSummary(derivationMode: DerivationMode, totalBalance: BigNumber): void;
+declare function logStatus(status: string): void;
+declare function transientLine(message?: string): void;
+declare function showResults(sortedUTXOs: Array<Address>, sortedOperations: Array<Operation>, summary: Array<Summary>, balanceOnly: boolean): void;
+export { showSummary, logStatus, updateAddressDetails, showSortedOperations, transientLine, showResults, };

package/lib/display.js

@@ -0,0 +1,251 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.showResults = exports.transientLine = exports.showSortedOperations = exports.updateAddressDetails = exports.logStatus = exports.showSummary = void 0;
+const readline_1 = __importDefault(require("readline"));
+const chalk_1 = __importDefault(require("chalk"));
+const settings_1 = require("./configuration/settings");
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+function renderAmount(amount) {
+    // Currently, this function does not convert the amounts
+    // into relevant units. But in the future, if the API
+    // changes, it would allow to change the unit
+    // depending on the network.
+    // For example:
+    // if (configuration.currency.symbol === currencies.btc.symbol) {
+    //   return sb.toAccountUnit(amount);
+    // }
+    if (amount.isZero()) {
+        return String(amount);
+    }
+    else {
+        // 8 digital places max without trailing 0s
+        return amount.toFixed(8);
+    }
+}
+// display the active/probed address with its stats
+function updateAddressDetails(address) {
+    // silent mode: do not display anything
+    if (settings_1.configuration.silent) {
+        return;
+    }
+    // quiet mode: only display full information, once
+    if (settings_1.configuration.quiet && typeof address.getStats() === "undefined") {
+        return;
+    }
+    const derivationMode = address.getDerivationMode();
+    const account = address.getDerivation().account;
+    const index = address.getDerivation().index;
+    const derivationPath = "m/"
+        .concat(String(account))
+        .concat("/")
+        .concat(String(index));
+    const addressStats = address.getStats();
+    // _type_  path  address ...
+    let stats = "";
+    if (settings_1.configuration.currency.utxo_based) {
+        //    _{derivation mode}_  {derivation path}  {address}  [{cash address}]...
+        stats = stats
+            .concat(chalk_1.default.italic(derivationMode.padEnd(16, " ")))
+            .concat(derivationPath.padEnd(12, " "));
+    }
+    else {
+        stats = stats.concat("\t");
+    }
+    const cashAddress = address.asCashAddress();
+    if (typeof cashAddress !== "undefined") {
+        stats = stats
+            .concat(address.toString().padEnd(36, " "))
+            .concat(cashAddress.padEnd(46, " "));
+    }
+    else {
+        stats = stats.concat(address.toString().padEnd(46, " "));
+    }
+    if (typeof address.getStats() === "undefined") {
+        // if no stats, display just half of the line
+        if (settings_1.configuration.commandLineMode) {
+            process.stdout.write(stats);
+        }
+        return;
+    }
+    else {
+        // else, display the full line
+        const balance = address.getBalance();
+        const fundedSum = renderAmount(addressStats.funded);
+        transientLine( /* delete line to display complete info */);
+        // ... +{total funded} ←
+        stats = stats
+            .concat(balance.toString().padEnd(16, " "))
+            .concat("+")
+            .concat(fundedSum.padEnd(14, " ")) // an active address has necessarily been funded,
+            .concat(" ←"); // thus this information is mandatory
+    }
+    // optional: spent sum
+    if (typeof addressStats.spent !== "undefined") {
+        const spentSum = renderAmount(addressStats.spent);
+        // ... -{total spent} →
+        stats = stats.concat("\t-").concat(spentSum.padEnd(14, " ")).concat(" →");
+    }
+    console.log(stats);
+}
+exports.updateAddressDetails = updateAddressDetails;
+// display the list of UTXOs sorted by date (reverse chronological order)
+function showSortedUTXOs(sortedUTXOs) {
+    if (settings_1.configuration.silent || !settings_1.configuration.currency.utxo_based) {
+        return;
+    }
+    console.log(chalk_1.default.bold("\nUTXOs\n"));
+    if (sortedUTXOs.length === 0) {
+        console.log(chalk_1.default.gray("(no UTXO)"));
+        return;
+    }
+    sortedUTXOs.forEach((utxo) => {
+        updateAddressDetails(utxo);
+    });
+}
+// display the list of operations sorted by date (reverse chronological order)
+function showSortedOperations(sortedOperations) {
+    if (settings_1.configuration.silent) {
+        return;
+    }
+    process.stdout.write(chalk_1.default.bold("\nOperations History"));
+    if (typeof settings_1.configuration.APIKey === "undefined") {
+        // warning related to the limitations of the default provider
+        process.stdout.write(chalk_1.default.redBright(" (only the last ~50 operations by address are displayed)\n"));
+    }
+    else {
+        process.stdout.write("\n");
+    }
+    const header = "\ndate\t\t\tblock\t\taddress\t\t\t\t\t\treceived (←) [as change from non-sibling (c)] | sent (→) to self (⮂) or sibling (↺)";
+    console.log(chalk_1.default.grey(header));
+    sortedOperations.forEach((op) => {
+        const amount = renderAmount(op.amount).padEnd(12, " ");
+        // {date} {block} {address} [{cash address}]
+        let status = op.date
+            .padEnd(20, " ")
+            .concat("\t")
+            .concat(String(op.block).padEnd(8, " "));
+        const address = op.address;
+        const cashAddress = op.cashAddress;
+        if (typeof cashAddress !== "undefined") {
+            status = status
+                .concat(address.padEnd(36, " "))
+                .concat(cashAddress.padEnd(46, " "));
+        }
+        else {
+            status = status.concat("\t").concat(address.padEnd(42, " ")).concat("\t");
+        }
+        if (op.operationType.includes("Received")) {
+            // ... +{amount} ←
+            status = status.concat("+").concat(amount.padEnd(14, " ")).concat(" ←");
+            if (op.operationType === "Received (non-sibling to change)") {
+                status = status.concat(" c");
+            }
+        }
+        else {
+            // ... -{amount} →|⮂|↺
+            status = status.concat("-").concat(amount.padEnd(14, " "));
+            const operationType = op.getOperationType();
+            if (operationType === "Sent to self") {
+                // case 1. Sent to the same address
+                status = status.concat(" ⮂");
+            }
+            else if (operationType === "Sent to sibling") {
+                // case 2. Sent to a sibling address
+                // (different non-change address belonging to same xpub)
+                status = status.concat(" ↺");
+            }
+            else if (operationType === "Failed to send") {
+                // case 3. Failed to send (Ethereum)
+                status = status.concat(" x");
+            }
+            else {
+                // case 4. Sent to external address
+                status = status.concat(" →");
+            }
+        }
+        if (op.operationType.includes("token")) {
+            // Token (Ethereum)
+            status = status.concat(" token");
+        }
+        if (op.operationType.includes("dapp")) {
+            // Token (Ethereum)
+            status = status.concat(" dapp");
+        }
+        if (op.operationType.includes("Swapped")) {
+            // Swapped (Ethereum)
+            status = status.concat(" Swapped");
+        }
+        if (op.operationType.includes("SCI")) {
+            // SCI (Ethereum)
+            status = status.concat(" sci");
+        }
+        console.log(status);
+    });
+    console.log(chalk_1.default.bold("\nNumber of transactions\n"));
+    console.log(chalk_1.default.whiteBright(sortedOperations.length));
+}
+exports.showSortedOperations = showSortedOperations;
+// display the summary: total balance by address type
+function showSummary(derivationMode, totalBalance) {
+    if (settings_1.configuration.silent) {
+        return;
+    }
+    const derivation = derivationMode.toString();
+    const balance = renderAmount(new bignumber_js_1.default(totalBalance));
+    if (balance === "0") {
+        console.log(chalk_1.default.grey(derivation.padEnd(16, " ").concat(balance.padEnd(12, " "))));
+    }
+    else {
+        console.log(chalk_1.default
+            .whiteBright(derivation.padEnd(16, " "))
+            .concat(chalk_1.default.greenBright(balance.padEnd(12, " "))));
+    }
+}
+exports.showSummary = showSummary;
+function logStatus(status) {
+    if (settings_1.configuration.silent) {
+        return;
+    }
+    console.log(chalk_1.default.dim(status));
+}
+exports.logStatus = logStatus;
+// overwrite last displayed line
+// (no message: delete the line)
+//
+// note: if this implementation is modified,
+// always check the resulting behavior in
+// Docker
+function transientLine(message) {
+    if (settings_1.configuration.silent || settings_1.configuration.quiet) {
+        return;
+    }
+    readline_1.default.cursorTo(process.stdout, 0);
+    if (typeof message !== "undefined") {
+        process.stdout.write(message);
+    }
+    else {
+        // blank line
+        // ! solution implemented this way to be
+        // ! compatible with Docker
+        process.stdout.write("".padEnd(140, " "));
+        readline_1.default.cursorTo(process.stdout, 0);
+    }
+}
+exports.transientLine = transientLine;
+function showResults(sortedUTXOs, sortedOperations, summary, balanceOnly) {
+    if (settings_1.configuration.silent) {
+        return;
+    }
+    showSortedUTXOs(sortedUTXOs);
+    if (!balanceOnly) {
+        showSortedOperations(sortedOperations);
+    }
+    console.log(chalk_1.default.bold("\nSummary\n"));
+    for (const total of summary) {
+        showSummary(total.derivationMode, total.balance);
+    }
+}
+exports.showResults = showResults;

package/lib/helpers.d.ts

@@ -0,0 +1,27 @@
+import BigNumber from "bignumber.js";
+declare function getJSON<T>(url: string, APIKey?: string, { retries, retryDelayMS }?: {
+    retries?: number;
+    retryDelayMS?: number;
+}): Promise<T>;
+declare function retry<T>(job: () => Promise<T>, { retries, retryDelayMS }?: {
+    retries?: number | undefined;
+    retryDelayMS?: number | undefined;
+}): Promise<T>;
+declare function setNetwork(xpub: string, currency?: string, testnet?: boolean): void;
+declare function init(xpub: string, silent?: boolean, quiet?: boolean, currency?: string, testnet?: boolean, derivationMode?: string): void;
+declare function toUnprefixedCashAddress(address: string): string | undefined;
+/**
+ * Convert from unit of account to base unit (e.g. bitcoins to satoshis)
+ * @param amount the amount (in unit of account) to convert
+ * @returns the converted amount, in base unit
+ */
+declare function toBaseUnit(amount: BigNumber): string;
+/**
+ * Convert from base unit to unit of account (e.g. satoshis to bitcoins)
+ * @param amount the amount (in base unit) to convert
+ * @param decimalPlaces (optional) decimal precision
+ * @returns the converted amount, in unit of account
+ */
+declare function toAccountUnit(amount: BigNumber, decimalPlaces?: number): string;
+declare function getNetworkLabel(): "ropsten" | "testnet" | "mainnet";
+export { init, getJSON, getNetworkLabel, retry, setNetwork, toUnprefixedCashAddress, toBaseUnit, toAccountUnit, };