@hackerhouse/xpub-scan 1.0.0

package/lib/actions/deriveAddresses.js

@@ -0,0 +1,239 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveAddress = exports.getDerivationMode = void 0;
+const bjs = __importStar(require("bitcoinjs-lib"));
+const bchaddrjs_1 = __importDefault(require("bchaddrjs"));
+const bitcore_lib_cash_1 = __importDefault(require("bitcore-lib-cash"));
+const ethereumjs_wallet_1 = __importDefault(require("ethereumjs-wallet"));
+const currencies_1 = require("../configuration/currencies");
+const settings_1 = require("../configuration/settings");
+const create_hmac_1 = __importDefault(require("create-hmac"));
+const bip32_1 = __importDefault(require("bip32"));
+const ecc = __importStar(require("tiny-secp256k1"));
+const bs58check_1 = __importDefault(require("bs58check"));
+const secp256k1_1 = require("secp256k1");
+const bip32 = (0, bip32_1.default)(ecc);
+// Initialize ECC library for Taproot (p2tr) support
+bjs.initEccLib(ecc);
+/**
+ * Convert a public key to x-only format (32 bytes) for Taproot
+ * Compressed public keys are 33 bytes (02/03 prefix + 32 bytes x-coordinate)
+ * X-only public keys are 32 bytes (just the x-coordinate)
+ */
+function toXOnly(pubKey) {
+    return pubKey.length === 32 ? pubKey : pubKey.subarray(1, 33);
+}
+class BIP32 {
+    constructor(publicKey, chainCode, network, depth = 0, index = 0) {
+        this.publicKey = publicKey;
+        this.chainCode = chainCode;
+        this.network = network;
+        this.depth = depth;
+        this.index = index;
+    }
+    derive(index) {
+        const data = Buffer.allocUnsafe(37);
+        this.publicKey.copy(data, 0);
+        data.writeUInt32BE(index, 33);
+        const I = (0, create_hmac_1.default)("sha512", this.chainCode).update(data).digest();
+        const IL = I.slice(0, 32);
+        const IR = I.slice(32);
+        const Ki = Buffer.from((0, secp256k1_1.publicKeyTweakAdd)(this.publicKey, IL));
+        return new BIP32(Ki, IR, this.network, this.depth + 1, index);
+    }
+}
+const getPubkeyAt = (xpub, account, index) => {
+    const buffer = Buffer.from(bs58check_1.default.decode(xpub));
+    const depth = buffer[4];
+    const i = buffer.readUInt32BE(9);
+    const chainCode = buffer.slice(13, 45);
+    const publicKey = buffer.slice(45, 78);
+    return new BIP32(publicKey, chainCode, settings_1.configuration.currency.network, depth, i)
+        .derive(account)
+        .derive(index).publicKey;
+};
+/**
+ * derive a legacy address at a given account and index positions
+ * @param xpub the xpub from which to derive the legacy address
+ * @param account account number from which to derive the legacy address
+ * @param index index number from which to derive the legacy address
+ * @returns the derived legacy address
+ */
+function getLegacyAddress(xpub, account, index) {
+    const publicKeyBuffer = getPubkeyAt(xpub, account, index);
+    const publicKeyHash160 = bjs.crypto.hash160(publicKeyBuffer);
+    return bjs.address.toBase58Check(publicKeyHash160, settings_1.configuration.currency.network.pubKeyHash);
+}
+/**
+ * derive a SegWit address at a given account and index positions
+ * @param xpub the xpub from which to derive the SegWit address
+ * @param account account number from which to derive the SegWit address
+ * @param index index number from which to derive the SegWit address
+ * @returns the derived SegWit address
+ */
+function getSegWitAddress(xpub, account, index) {
+    const { address } = bjs.payments.p2sh({
+        redeem: bjs.payments.p2wpkh({
+            pubkey: bip32
+                .fromBase58(xpub, settings_1.configuration.currency.network)
+                .derive(account)
+                .derive(index).publicKey,
+            network: settings_1.configuration.currency.network,
+        }),
+    });
+    return String(address);
+}
+/**
+ * derive a native SegWit address at a given account and index positions
+ * @param xpub the xpub from which to derive the native SegWit address
+ * @param account account number from which to derive the native SegWit address
+ * @param index index number from which to derive the native SegWit address
+ * @returns the derived native SegWit address
+ */
+function getNativeSegWitAddress(xpub, account, index) {
+    const { address } = bjs.payments.p2wpkh({
+        pubkey: bip32
+            .fromBase58(xpub, settings_1.configuration.currency.network)
+            .derive(account)
+            .derive(index).publicKey,
+        network: settings_1.configuration.currency.network,
+    });
+    return String(address);
+}
+/**
+ * derive a Taproot address at a given account and index positions
+ * @param xpub the xpub from which to derive the Taproot address
+ * @param account account number (0 = external/receiving, 1 = internal/change)
+ * @param index index number from which to derive the Taproot address
+ * @returns the derived Taproot address (bc1p... for mainnet, tb1p... for testnet)
+ */
+function getTaprootAddress(xpub, account, index) {
+    const childPubKey = bip32
+        .fromBase58(xpub, settings_1.configuration.currency.network)
+        .derive(account)
+        .derive(index).publicKey;
+    const { address } = bjs.payments.p2tr({
+        internalPubkey: toXOnly(childPubKey),
+        network: settings_1.configuration.currency.network,
+    });
+    return String(address);
+}
+/**
+ * derive a Bitcoin Cash address at a given account and index positions
+ * @param xpub the xpub from which to derive the Bitcoin Cash address
+ * @param account account number from which to derive the Bitcoin Cash address
+ * @param index index number from which to derive the Bitcoin Cash address
+ * @returns the derived Bitcoin Cash address
+ * note: based on https://github.com/go-faast/bitcoin-cash-payments/blob/54397eb97c7a9bf08b32e10bef23d5f27aa5ab01/index.js#L63-L73
+ */
+function getLegacyBitcoinCashAddress(xpub, account, index) {
+    const node = new bitcore_lib_cash_1.default.HDPublicKey(xpub);
+    const child = node.derive(account).derive(index);
+    const address = new bitcore_lib_cash_1.default.Address(child.publicKey, bitcore_lib_cash_1.default.Networks.livenet);
+    const addrstr = address.toString().split(":");
+    if (addrstr.length === 2) {
+        return bchaddrjs_1.default.toLegacyAddress(addrstr[1]);
+    }
+    else {
+        throw new Error("Unable to derive cash address for " + address);
+    }
+}
+/**
+ * derive a unique Ethereum address (the first one)
+ * @param xpub the xpub from which to derive the Ethereum address
+ * @returns the first derived Ethereum address
+ */
+function getEthereumAddress(xpub) {
+    return ethereumjs_wallet_1.default.fromExtendedPublicKey(xpub).getAddressString();
+}
+/**
+ * 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
+ */
+function deriveAddress(derivationMode, xpub, account, index) {
+    if (typeof account === "undefined") {
+        account = 0;
+    }
+    if (typeof index === "undefined") {
+        index = 0;
+    }
+    switch (derivationMode) {
+        case currencies_1.DerivationMode.LEGACY:
+            return getLegacyAddress(xpub, account, index);
+        case currencies_1.DerivationMode.SEGWIT:
+            return getSegWitAddress(xpub, account, index);
+        case currencies_1.DerivationMode.NATIVE:
+            return getNativeSegWitAddress(xpub, account, index);
+        case currencies_1.DerivationMode.TAPROOT:
+            return getTaprootAddress(xpub, account, index);
+        case currencies_1.DerivationMode.BCH:
+            return getLegacyBitcoinCashAddress(xpub, account, index);
+        case currencies_1.DerivationMode.DOGECOIN:
+            return getLegacyAddress(xpub, account, index);
+        case currencies_1.DerivationMode.ETHEREUM:
+            return getEthereumAddress(xpub);
+        case currencies_1.DerivationMode.UNKNOWN:
+        /* fallthrough */
+        default:
+            throw new Error("Unknown derivation mode");
+    }
+}
+exports.deriveAddress = deriveAddress;
+/**
+ * infer the derivation mode from the address syntax
+ * @param address any address (Bitcoin, Ethereum, etc.)
+ * @returns the derivation mode associated with the address
+ */
+function getDerivationMode(address) {
+    if (address.match("^(bc1q|tb1|ltc1).*")) {
+        return currencies_1.DerivationMode.NATIVE;
+    }
+    else if (address.match("^(bc1p|tb1p).*")) {
+        return currencies_1.DerivationMode.TAPROOT;
+    }
+    else if (address.match("^[32M].*")) {
+        return currencies_1.DerivationMode.SEGWIT;
+    }
+    else if (address.match("^[1nmL].*")) {
+        return currencies_1.DerivationMode.LEGACY;
+    }
+    else if (address.match("^(D).*")) {
+        return currencies_1.DerivationMode.DOGECOIN;
+    }
+    else {
+        throw new Error("INVALID ADDRESS: "
+            .concat(address)
+            .concat(" is not a valid or a supported address"));
+    }
+}
+exports.getDerivationMode = getDerivationMode;

package/lib/actions/processTransactions.d.ts

@@ -0,0 +1,29 @@
+import { Address } from "../models/address";
+import { OwnAddresses } from "../models/ownAddresses";
+import { Operation } from "../models/operation";
+/**
+ * fetch the processed basic stats related to an address
+ * its balance, funded and spend sums and counts
+ * @param address the address being analyzed
+ * @param balanceOnly an option to return only the balance (only for Crypto APIs)
+ */
+declare function getStats(address: Address, balanceOnly: boolean): Promise<void>;
+/**
+ * get all processed transactions related to an address
+ * @param address the address being analyzed
+ * @param ownAddresses (optional) list of addresses derived from the same xpub as `address`
+ */
+declare function getTransactions(address: Address, ownAddresses?: OwnAddresses): void;
+/**
+ * Returns an array of ordered operations
+ * @param {Array<Address>} addresses - all active addresses belonging to the xpub
+ * @returns {Array<Address>} Array of operations in reverse chronological order
+ */
+declare function getSortedOperations(addresses: Array<Address>): Array<Operation>;
+/**
+ * Returns an array of ordered UTXOs
+ * @param {Array<Address>} addresses - all active addresses belonging to the xpub
+ * @returns {Array<Address>} Array of UTXOs in reverse chronological order
+ */
+declare function getSortedUTXOS(addresses: Array<Address>): Array<Address>;
+export { getStats, getTransactions, getSortedOperations, getSortedUTXOS };

package/lib/actions/processTransactions.js

@@ -0,0 +1,289 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSortedUTXOS = exports.getSortedOperations = exports.getTransactions = exports.getStats = void 0;
+const settings_1 = require("../configuration/settings");
+const operation_1 = require("../models/operation");
+const defaultProvider = __importStar(require("../api/defaultProvider"));
+const customProvider = __importStar(require("../api/customProvider"));
+const currencies_1 = require("../configuration/currencies");
+/**
+ * fetch the processed basic stats related to an address
+ * its balance, funded and spend sums and counts
+ * @param address the address being analyzed
+ * @param balanceOnly an option to return only the balance (only for Crypto APIs)
+ */
+function getStats(address, balanceOnly) {
+    return __awaiter(this, void 0, void 0, function* () {
+        switch (settings_1.configuration.providerType) {
+            case "default":
+                yield defaultProvider.getStats(address);
+                break;
+            case "Crypto APIs":
+                yield customProvider.getStats(address, balanceOnly);
+                break;
+            default:
+                throw new Error("Should not be reachable: providerType should be 'default' or 'Crypto APIs'");
+        }
+    });
+}
+exports.getStats = getStats;
+/**
+ * get all transactions associated with an UTXO-based address
+ * @param address the UTXO-based address being analyzed
+ */
+function getUTXOBasedTransactions(address) {
+    switch (settings_1.configuration.providerType) {
+        case "default":
+            defaultProvider.getTransactions(address);
+            break;
+        case "Crypto APIs":
+            customProvider.getTransactions(address);
+            break;
+        default:
+            throw new Error("Should not be reachable: providerType should be 'default' or 'Crypto APIs'");
+    }
+}
+/**
+ * get all transactions associated with an account-based address (typically Ethereum)
+ * @param address the account-based address being analyzed
+ */
+function getAccountBasedTransactions(address) {
+    switch (settings_1.configuration.providerType) {
+        case "default":
+            defaultProvider.getAccountBasedTransactions(address);
+            break;
+        case "Crypto APIs":
+            customProvider.getAccountBasedTransactions(address);
+            break;
+        default:
+            throw new Error("Should not be reachable: providerType should be 'default' or 'Crypto APIs'");
+    }
+}
+/**
+ * get all processed transactions related to an address
+ * @param address the address being analyzed
+ * @param ownAddresses (optional) list of addresses derived from the same xpub as `address`
+ */
+function getTransactions(address, ownAddresses) {
+    if (settings_1.configuration.currency.utxo_based) {
+        // ┏━━━━━━━━━━━━━━━━━━━━━┓
+        // ┃ UTXO-BASED CURRENCY ┃
+        // ┗━━━━━━━━━━━━━━━━━━━━━┛
+        getUTXOBasedTransactions(address);
+        // important step: distinguish funded from sent transactions
+        processFundedTransactions(address, ownAddresses);
+        processSentTransactions(address, ownAddresses);
+    }
+    else {
+        // ┏━━━━━━━━━━━━━━━━━━━━━━━━┓
+        // ┃ ACCOUNT-BASED CURRENCY ┃
+        // ┗━━━━━━━━━━━━━━━━━━━━━━━━┛
+        getAccountBasedTransactions(address);
+    }
+}
+exports.getTransactions = getTransactions;
+/**
+ * identify _funded_ transactions among the address' transactions
+ * @param address the address being analyzed
+ * @param ownAddresses list of addresses derived from the same xpub as `address`
+ */
+function processFundedTransactions(address, ownAddresses) {
+    // all transactions associated with the address, without distinction
+    const transactions = address.getTransactions();
+    // all addresses derived from the same xpub as `address`
+    const allOwnAddresses = ownAddresses.getAllAddresses();
+    const accountNumber = address.getDerivation().account;
+    let isFunded;
+    for (const tx of transactions) {
+        isFunded = true;
+        if (typeof tx.ins !== "undefined" && tx.ins.length > 0) {
+            if (accountNumber === 1) {
+                // when account is internal (i.e., 1), and
+                //     - has a sibling as sender: not externally funded (expected behavior: sent to change)
+                //     - has no sibling as sender: process the operation (edge case: non-sibling to change)
+                for (const txin of tx.ins) {
+                    if (allOwnAddresses.includes(txin.address)) {
+                        // has a sibling as sender: not funded
+                        isFunded = false;
+                        break;
+                    }
+                }
+            }
+            if (isFunded) {
+                // this is a _funded_ operation...
+                const op = new operation_1.Operation(tx.date, tx.ins[0].amount);
+                op.setTxid(tx.txid);
+                op.setBlockNumber(tx.blockHeight);
+                // ... that has to be categorized:
+                // there are 2 types of received transaction:
+                // case 1 — received to an address that is NOT a change address: default received
+                // case 2 — received to a change address (account #1): received from non-sibling to change
+                op.setOperationType(accountNumber !== 1 ? "Received" : "Received (non-sibling to change)");
+                // associate this funded operation with the address
+                address.addFundedOperation(op);
+            }
+        }
+    }
+    if (settings_1.VERBOSE) {
+        console.log("FUNDED\t", address.getFundedOperations());
+    }
+}
+/**
+ * identify _sent_ transactions among the address' transactions
+ * @param address the address being analyzed
+ * @param ownAddresses list of addresses derived from the same xpub as `address`
+ */
+function processSentTransactions(address, ownAddresses) {
+    // all transactions associated with the address, without distinction
+    const transactions = address.getTransactions();
+    // addresses derived from the same xpub as `address`,
+    // either external or internal (i.e., change)
+    const externalAddresses = ownAddresses.getExternalAddresses();
+    const internalAddresses = ownAddresses.getInternalAddresses();
+    for (const tx of transactions) {
+        const outs = tx.outs;
+        outs.forEach((out) => {
+            // analyse all recipient addresses and identify whether they
+            // are external/internal/third-party addresses
+            const isInternalAddress = internalAddresses.includes(out.address);
+            const isExternalAddress = externalAddresses.includes(out.address);
+            // exclude internal addresses—by definition (i.e., change addresses)
+            if (!isInternalAddress) {
+                // at this stage, the recipient is either an external address or a
+                // third-party address (i.e., not belonging to the same xpub)...
+                const op = new operation_1.Operation(tx.date, out.amount);
+                op.setTxid(tx.txid);
+                op.setBlockNumber(tx.blockHeight);
+                // ... and has to be categorized:
+                // there are 3 types of sent transaction:
+                if (out.address === address.toString()) {
+                    // case 1 — sent to self: sent to same address
+                    op.setOperationType("Sent to self");
+                }
+                else if (isExternalAddress) {
+                    // case 2 — sent to a sibling: sent to an address belonging to the same xpub
+                    // _while not being a change address_
+                    op.setOperationType("Sent to sibling");
+                }
+                else {
+                    // case 3 — sent to an address not belonging to the xpub
+                    op.setOperationType("Sent");
+                }
+                // associate this sent operation with the address
+                address.addSentOperation(op);
+            }
+        });
+    }
+    if (settings_1.VERBOSE) {
+        console.log("SENT\t", address.getSentOperations());
+    }
+}
+/**
+ * sort by block number and, _then, if needed_, by date
+ * @param A first operation
+ * @param B second operation
+ * @returns -1|0|1, depending on the ordering
+ */
+function compareOpsByBlockThenDate(A, B) {
+    // block number
+    if (A.block > B.block) {
+        return -1;
+    }
+    if (A.block < B.block) {
+        return 1;
+    }
+    // date
+    if (A.date > B.date) {
+        return -1;
+    }
+    if (A.date < B.date) {
+        return 1;
+    }
+    return 0;
+}
+/**
+ * Returns an array of ordered operations
+ * @param {Array<Address>} addresses - all active addresses belonging to the xpub
+ * @returns {Array<Address>} Array of operations in reverse chronological order
+ */
+function getSortedOperations(addresses) {
+    const operations = [];
+    const processedTxids = [];
+    // flatten the array of arrays in one dimension, and loop over
+    [].concat(addresses).forEach((address) => {
+        address.getFundedOperations().forEach((op) => {
+            op.setAddress(address.toString());
+            if (settings_1.configuration.currency.symbol === currencies_1.currencies.bch.symbol) {
+                op.setCashAddress(address.asCashAddress());
+            }
+            operations.push(op);
+        });
+        address.getSentOperations().forEach((op) => {
+            // only process a given txid once
+            if (!processedTxids.includes(op.txid)) {
+                op.setAddress(address.toString());
+                if (settings_1.configuration.currency.symbol === currencies_1.currencies.bch.symbol) {
+                    op.setCashAddress(address.asCashAddress());
+                }
+                operations.push(op);
+                processedTxids.push(op.txid);
+            }
+        });
+    });
+    // reverse chronological order
+    operations.sort(compareOpsByBlockThenDate);
+    return operations;
+}
+exports.getSortedOperations = getSortedOperations;
+/**
+ * Returns an array of ordered UTXOs
+ * @param {Array<Address>} addresses - all active addresses belonging to the xpub
+ * @returns {Array<Address>} Array of UTXOs in reverse chronological order
+ */
+// (reverse chronological order)
+function getSortedUTXOS(addresses) {
+    // note: no need to explicitely sort the UTXOs as they inherit
+    //       the order from the addresses themselves
+    const utxos = [];
+    // flatten the array of arrays in one dimension, and loop over
+    [].concat(addresses).forEach((address) => {
+        if (address.isUTXO()) {
+            // if the address is an UTXO, just add it to the list of UTXOs
+            utxos.push(address);
+        }
+    });
+    return utxos;
+}
+exports.getSortedUTXOS = getSortedUTXOS;

package/lib/actions/saveAnalysis.d.ts

@@ -0,0 +1,2 @@
+declare function save(meta: any, data: any, directory: string): void;
+export { save };