@hackerhouse/xpub-scan 1.0.0

package/lib/actions/checkAddress.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = exports._private = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const deriveAddresses_1 = require("./deriveAddresses");
+const settings_1 = require("../configuration/settings");
+const helpers_1 = require("../helpers");
+function showError(message, derived, provided) {
+    let errorMessage = chalk_1.default.red("[Comparison error] ".concat(message));
+    if (typeof derived !== "undefined") {
+        const comparison = "\nProvided address:\t"
+            .concat(String(provided))
+            .concat("\nFirst derived address:  ")
+            .concat(String(derived));
+        errorMessage = errorMessage.concat(chalk_1.default.redBright(comparison));
+    }
+    console.log(errorMessage);
+}
+// TODO?: export in a dedicated module (display.ts)?
+function showComparisonResult(xpub, address, result) {
+    console.log("\nXpub:", chalk_1.default.whiteBright(xpub));
+    console.log("Provided address:", chalk_1.default.whiteBright(address));
+    if (Object.keys(result).length === 0) {
+        // no match
+        console.log(chalk_1.default.redBright("The address does not seem to have been derived from this xpub!"));
+    }
+    else {
+        const derivationPath = "m/"
+            .concat(String(result.account))
+            .concat("/")
+            .concat(String(result.index));
+        if (typeof result.partial === "undefined") {
+            // full match
+            console.log(chalk_1.default.greenBright("The address has been derived from this xpub using derivation path ".concat(chalk_1.default.bold(derivationPath))));
+        }
+        else {
+            // partial match
+            console.log("Derived address: ", chalk_1.default.whiteBright(result.partial));
+            console.log(chalk_1.default.blueBright("There is a partial match between the provided address and the one derived using derivation path ".concat(chalk_1.default.bold(derivationPath))));
+        }
+    }
+}
+// partial match, using '?' as wildcards
+function partialMatch(derived, provided) {
+    for (let i = 0; i < derived.length; ++i) {
+        if (provided[i] === "?") {
+            continue;
+        }
+        if (provided[i] !== derived[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * identify whether an address provided by the user belongs or not to the xpub
+ * @param xpub the xpub from which the address may have been derived
+ * @param providedAddress the address provided by the user
+ * @param range the range of the search (i.e., accounts and indices ranges)
+ * @param searchType indication of the type of search (quick/deep)
+ * @returns a match or an empty object (i.e., non-match)
+ */
+function search(xpub, providedAddress, range, searchType) {
+    const derivationMode = (0, deriveAddresses_1.getDerivationMode)(providedAddress);
+    const partialSearch = providedAddress.includes("?");
+    (0, helpers_1.setNetwork)(xpub);
+    for (let account = range.account.min; account < range.account.max; ++account) {
+        for (let index = range.index.min; index < range.index.max; ++index) {
+            const derivedAddress = (0, deriveAddresses_1.deriveAddress)(derivationMode, xpub, account, index);
+            // m/{account}/{index}
+            const derivationPath = "m/"
+                .concat(account.toFixed())
+                .concat("/")
+                .concat(index.toFixed());
+            // quick|deep search    {derivation path}  {derived address}
+            const status = searchType
+                .padEnd(18, " ")
+                .concat(derivationPath.padEnd(14, " "))
+                .concat(derivedAddress);
+            const derived = derivedAddress.toUpperCase();
+            const provided = providedAddress.toUpperCase();
+            // perfect match (case insensitive)
+            if (derived === provided) {
+                console.log(chalk_1.default.green(status));
+                return {
+                    account,
+                    index,
+                };
+            }
+            // partial match (if enabled)
+            if (partialSearch && partialMatch(derived, provided)) {
+                console.log(chalk_1.default.blueBright(status));
+                return {
+                    partial: derivedAddress,
+                    account,
+                    index,
+                };
+            }
+            console.log(status);
+        }
+    }
+    return {};
+}
+function run(xpub, providedAddress) {
+    if (typeof settings_1.DERIVATION_SCOPE === "undefined") {
+        showError("DERIVATION_SCOPE setting is not defined");
+    }
+    const quickSearchRange = settings_1.DERIVATION_SCOPE.quick_search;
+    let result = search(xpub, providedAddress, quickSearchRange, "quick search");
+    if (Object.keys(result).length === 0) {
+        const deepSearchRange = settings_1.DERIVATION_SCOPE.deep_search;
+        result = search(xpub, providedAddress, deepSearchRange, "deep search");
+    }
+    showComparisonResult(xpub, providedAddress, result);
+}
+exports.run = run;
+exports._private = {
+    search,
+};

package/lib/actions/checkBalance.d.ts

@@ -0,0 +1,20 @@
+import { Address } from "../models/address";
+import { ScanLimits } from "../models/scanLimits";
+import { DerivationMode } from "../configuration/currencies";
+import BigNumber from "bignumber.js";
+/**
+ * Run the analysis
+ * @param itemToScan ITEM TO SCAN can be an xpub or an address
+ *                   (that is why it is named `itemToScan` instead of xpub)
+ * @param balanceOnly option to fetch the balance only—not the transactions
+ * @param scanLimits option to limit the scan to a certain account and indices range
+ * @returns a list of active addresses and a summary (total balance per derivation mode)
+ */
+declare function run(itemToScan: string, balanceOnly: boolean, scanLimits?: ScanLimits): Promise<{
+    addresses: Address[];
+    summary: {
+        derivationMode: DerivationMode;
+        balance: BigNumber;
+    }[];
+}>;
+export { run };

package/lib/actions/checkBalance.js

@@ -0,0 +1,300 @@
+"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;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const display = __importStar(require("../display"));
+const address_1 = require("../models/address");
+const ownAddresses_1 = require("../models/ownAddresses");
+const settings_1 = require("../configuration/settings");
+const currencies_1 = require("../configuration/currencies");
+const processTransactions_1 = require("./processTransactions");
+const deriveAddresses_1 = require("../actions/deriveAddresses");
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+/**
+ * derive and scan all active addresses _for a given derivation mode_
+ * note: an ACTIVE ADDRESS is an address with > 0 transactions
+ * @param derivationMode a derivation mode (enum)
+ * @param xpub the xpub to scan
+ * @param balanceOnly option to fetch the balance only—not the transactions
+ * @param scanLimits option to limit the scan to a certain account and indices range
+ * @returns an object containing the total balance for the derivation mode as well as
+ *          a list of active addresses associated with it
+ */
+function deriveAndScanAddressesByDerivationMode(derivationMode, xpub, balanceOnly, scanLimits) {
+    return __awaiter(this, void 0, void 0, function* () {
+        display.logStatus("Scanning ".concat(chalk_1.default.bold(derivationMode)).concat(" addresses..."));
+        const ownAddresses = new ownAddresses_1.OwnAddresses();
+        let totalBalance = new bignumber_js_1.default(0);
+        let txCounter = 0;
+        const addresses = [];
+        let accountSpan = undefined;
+        let indexFromSpan = undefined;
+        let indexToSpan = undefined;
+        let preDerivationSize = undefined;
+        if (scanLimits) {
+            accountSpan = scanLimits.account;
+            indexFromSpan = scanLimits.indexFrom;
+            indexToSpan = scanLimits.indexTo;
+            preDerivationSize = scanLimits.preDerivationSize;
+            // crucial step in limited scan mode: precompute the addresses belonging
+            // to the same xpub in order to perform transaction analysis further
+            // down the flow. `preDerivationSize` define the number of addresses to pre-derive.
+            for (let a = 0; a < 2; a++) {
+                for (let i = 0; i < preDerivationSize; i++) {
+                    ownAddresses.addAddress(new address_1.Address(xpub, derivationMode, a, i));
+                }
+            }
+        }
+        // loop over derivation path accounts: `m/{account}/{index}`
+        // note: we limit ourselves to accounts 0 and 1
+        // but the scope could be extended further if needed
+        for (let account = 0; account < 2; ++account) {
+            // if limited scan mode is enabled and the current account is outside the scope, skip it
+            if (typeof accountSpan != "undefined" && account !== accountSpan) {
+                continue;
+            }
+            // account 0 == external addresses
+            // account 1 == internal (aka change) addresses
+            const typeAccount = account === 1 ? "internal" : "external";
+            display.logStatus("- scanning " + chalk_1.default.italic(typeAccount) + " addresses -");
+            txCounter = 0;
+            for (let index = 0 /* scan all active indices */;; ++index) {
+                // if limited scan mode is enabled and the current index is _below_ the range, skip it
+                // ______(current index)_______[     LIMITED SCAN RANGE     ]____________________________
+                if (typeof indexFromSpan !== "undefined" && index < indexFromSpan) {
+                    continue;
+                }
+                // if limited scan mode is enabled and the current index is _beyond_ the range, stop the scan
+                // ____________________________[     LIMITED SCAN RANGE     ]______(current index)_______
+                if (typeof indexToSpan !== "undefined" && index > indexToSpan) {
+                    break;
+                }
+                // get address derived according to:
+                // - its xpub (by definition),
+                // - the current derivation mode (legacy, SegWit, etc.)
+                // - the derivation path characteristics: `m/{account:0|1}/{index:0|∞}`
+                const address = new address_1.Address(xpub, derivationMode, account, index);
+                display.updateAddressDetails(address);
+                const status = txCounter === 0 ? "analyzing" : "probing address gap";
+                if (!settings_1.configuration.silent && !settings_1.configuration.quiet) {
+                    process.stdout.write(chalk_1.default.yellow(status + "..."));
+                }
+                // fetch (from external provider) the basic data regarding the address
+                // (balance, transactions count, etc.)
+                yield (0, processTransactions_1.getStats)(address, balanceOnly);
+                const addressStats = address.getStats();
+                // here, evaluate if the address needs further analysis
+                if (addressStats.txsCount.isZero()) {
+                    // no transaction associated with the address:
+                    // perform address gap probing
+                    // GAP PROBE: check whether an address is active in a certain range
+                    //
+                    // for instance:
+                    // ┌┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┐
+                    // ┊ m/0/0 — active (10 transactions)           ┊
+                    // ┊ m/0/1 — active (2 transactions)            ┊
+                    // ┊                                  ┐         ┊
+                    // ┊ m/0/2 — inactive (0 transaction) │         ┊
+                    // ┊ m/0/3 — inactive (0 transaction) │ GAP     ┊
+                    // ┊ m/0/4 — inactive (0 transaction) │         ┊
+                    // ┊                                  ┘         ┊
+                    // ┊ m/0/5 — active (4 transactions)            ┊
+                    // └┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┘
+                    //
+                    // in this example, the gap probing allows to detect that
+                    // `m/0/5` is an active address
+                    //
+                    // note: the scope of the gap probing is 20 addresses by
+                    // default (check `DEFAULT_GAP_LIMIT`) but can be configured
+                    // using the `GAP_LIMIT` environment variable
+                    txCounter++;
+                    display.transientLine( /* delete address as it is not an active one */);
+                    if (account === 1 || txCounter >= Number(settings_1.configuration.gap_limit)) {
+                        // all active addresses have been scanned and the gap limit reached:
+                        // stop the scan for this specific derivation mode
+                        display.transientLine( /* delete last probing info */);
+                        display.logStatus("- " + chalk_1.default.italic(typeAccount) + " addresses scanned -");
+                        break;
+                    }
+                    continue;
+                }
+                else {
+                    txCounter = 0;
+                }
+                // convert address balance into satoshis (or equivalent unit)
+                // in order to avoid issue with floats addition
+                totalBalance = totalBalance.plus(address.getBalance());
+                display.updateAddressDetails(address);
+                // important step: add the active address to the
+                // list of own addresses in order to perform
+                // transaction analysis further down the flow
+                ownAddresses.addAddress(address);
+                addresses.push(address);
+            }
+        }
+        // process transactions
+        display.transientLine(chalk_1.default.yellowBright("Processing transactions..."));
+        if (!balanceOnly) {
+            addresses.forEach((address) => {
+                (0, processTransactions_1.getTransactions)(address, ownAddresses);
+            });
+        }
+        display.transientLine( /* delete address */);
+        display.logStatus(derivationMode.concat(" addresses scanned\n"));
+        return {
+            balance: totalBalance,
+            addresses,
+        };
+    });
+}
+/**
+ * Scan an address (account-based mode)
+ * @param itemToScan xpub from which an address will be derived, or directly an address
+ * @param balanceOnly option to fetch the balance only—not the transactions
+ * @returns an array containing this address and a summary that includes the total balance
+ *          (TODO: simplify in order to normalize with xpub analysis)
+ */
+function addressAnalysis(itemToScan, balanceOnly) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!settings_1.configuration.silent) {
+            console.log(chalk_1.default.bold("\nScanned address\n"));
+        }
+        let address;
+        if (itemToScan.substring(0, 4).toLocaleLowerCase() === "xpub") {
+            // the item to scan appears to be an xpub: derive just the first address
+            const derivationMode = settings_1.configuration.currency.derivationModes[0] || currencies_1.DerivationMode.UNKNOWN;
+            address = new address_1.Address((0, deriveAddresses_1.deriveAddress)(derivationMode, itemToScan));
+        }
+        else {
+            // the item to scan is directly an address: construct it
+            address = new address_1.Address(itemToScan);
+        }
+        if (typeof address === "undefined") {
+            throw new Error(`Address cannot be instantiated from "${itemToScan}"`);
+        }
+        display.updateAddressDetails(address);
+        // fetch (from external provider) the basic data regarding the address
+        // (balance, transactions count, etc.)
+        yield (0, processTransactions_1.getStats)(address, balanceOnly);
+        if (!balanceOnly) {
+            // also (if applicable), fetch (from the external provider) the raw transactions
+            // associated with the address
+            (0, processTransactions_1.getTransactions)(address);
+        }
+        display.updateAddressDetails(address);
+        const summary = [
+            {
+                derivationMode: currencies_1.DerivationMode.ETHEREUM,
+                balance: new bignumber_js_1.default(address.getBalance()),
+            },
+        ];
+        return {
+            addresses: [address],
+            summary,
+        };
+    });
+}
+/**
+ * Run the analysis
+ * @param itemToScan ITEM TO SCAN can be an xpub or an address
+ *                   (that is why it is named `itemToScan` instead of xpub)
+ * @param balanceOnly option to fetch the balance only—not the transactions
+ * @param scanLimits option to limit the scan to a certain account and indices range
+ * @returns a list of active addresses and a summary (total balance per derivation mode)
+ */
+function run(itemToScan, balanceOnly, scanLimits) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (settings_1.configuration.currency.utxo_based) {
+            // if the currency is UTXOs based (e.g., Bitcoin):
+            // the item to scan is an xpub
+            return xpubAnalysis(itemToScan, balanceOnly, scanLimits);
+        }
+        else {
+            // otherwise, the currency is account-based (e.g., Ethereum):
+            // the item to scan is an address
+            return addressAnalysis(itemToScan, balanceOnly);
+        }
+    });
+}
+exports.run = run;
+/**
+ * scan an xpub (UTXO-based mode)
+ * @param xpub the xpub to scan
+ * @param balanceOnly option to fetch the balance only—not the transactions
+ * @param scanLimits option to limit the scan to a certain account and indices range
+ * @returns a list of active addresses and a summary (total balance per derivation mode)
+ */
+function xpubAnalysis(xpub, balanceOnly, scanLimits) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let activeAddresses = [];
+        const summary = [];
+        // get all derivation modes associated with the currency type
+        // (e.g., for Bitcoin: legacy, SegWit, native SegWit, and taproot)
+        let derivationModes = settings_1.configuration.currency.derivationModes;
+        if (settings_1.configuration.specificDerivationMode) {
+            // if a specific derivation mode is set, limit the scan to this mode
+            derivationModes = derivationModes.filter((derivation) => derivation
+                .toString()
+                .toLocaleLowerCase()
+                .startsWith(settings_1.configuration.specificDerivationMode.toLocaleLowerCase()));
+        }
+        if (!settings_1.configuration.silent) {
+            console.log(chalk_1.default.bold("\nActive addresses\n"));
+        }
+        for (const derivationMode of derivationModes) {
+            // loop over the derivation modes and `scan` the addresses belonging to
+            // the current derivation mode
+            // (that is: derive them and identify the active ones)
+            const results = yield deriveAndScanAddressesByDerivationMode(derivationMode, xpub, balanceOnly, scanLimits);
+            activeAddresses = activeAddresses.concat(results.addresses);
+            summary.push({
+                derivationMode,
+                balance: results.balance,
+            });
+            // Stop scanning other derivation modes if we found active addresses
+            // (an xpub will only have addresses in one derivation mode)
+            if (results.addresses.length > 0) {
+                break;
+            }
+        }
+        return {
+            addresses: activeAddresses,
+            summary,
+        };
+    });
+}

package/lib/actions/deriveAddresses.d.ts

@@ -0,0 +1,17 @@
+import { DerivationMode } from "../configuration/currencies";
+/**
+ * derive an address at a given account and index positions
+ * @param derivationMode the derivation mode used to derive the address
+ * @param xpub the xpub from which to derive the address
+ * @param account account number from which to derive the address
+ * @param index index number from which to derive the address
+ * @returns the derived address
+ */
+declare function deriveAddress(derivationMode: DerivationMode, xpub: string, account?: number, index?: number): string;
+/**
+ * infer the derivation mode from the address syntax
+ * @param address any address (Bitcoin, Ethereum, etc.)
+ * @returns the derivation mode associated with the address
+ */
+declare function getDerivationMode(address: string): DerivationMode.LEGACY | DerivationMode.NATIVE | DerivationMode.SEGWIT | DerivationMode.TAPROOT | DerivationMode.DOGECOIN;
+export { getDerivationMode, deriveAddress };