@hackerhouse/xpub-scan 1.0.0

package/lib/actions/scanner.d.ts

@@ -0,0 +1,15 @@
+import { ScannerArguments, ScanResult } from "../types";
+export declare class Scanner {
+    args: ScannerArguments;
+    scanLimits: import("../models/scanLimits").ScanLimits | undefined;
+    address: string | undefined;
+    currency: string | undefined;
+    testnet: boolean | undefined;
+    derivationMode: string | undefined;
+    itemToScan: string;
+    balanceOnly: boolean;
+    now: Date;
+    exitCode: number;
+    constructor(args: ScannerArguments);
+    scan(): Promise<ScanResult>;
+}

package/lib/actions/scanner.js

@@ -0,0 +1,152 @@
+"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.Scanner = void 0;
+const checkBalances = __importStar(require("./checkBalance"));
+const compare = __importStar(require("./checkAddress"));
+const display = __importStar(require("../display"));
+const processTransactions_1 = require("./processTransactions");
+const diffs_1 = require("../comparison/diffs");
+const compareOperations_1 = require("../comparison/compareOperations");
+const importOperations_1 = require("../input/importOperations");
+const saveAnalysis_1 = require("./saveAnalysis");
+const settings_1 = require("../configuration/settings");
+const helpers_1 = require("../helpers");
+// eslint-disable-next-line
+const { version } = require("../../package.json"); // do not modify: get the version of Xpub Scan from `package.json`
+class Scanner {
+    constructor(args) {
+        this.now = new Date();
+        this.exitCode = 0;
+        this.args = args;
+        this.scanLimits = args.scanLimits;
+        this.address = args.address;
+        this.currency = args.currency;
+        this.testnet = args.testnet;
+        this.derivationMode = args.derivationMode;
+        this.itemToScan = args.itemToScan; // xpub or address
+        this.balanceOnly = args.balanceOnly;
+        (0, helpers_1.init)(this.itemToScan, args.silent, args.quiet, this.currency, this.testnet, this.derivationMode);
+    }
+    scan() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // library mode: suppress all outputs
+            if (!settings_1.configuration.commandLineMode) {
+                /* eslint-disable */
+                console.log = function () { };
+                /* eslint-enable */
+                settings_1.configuration.silent = true;
+            }
+            if (this.address) {
+                // mode A: `--address {address}`:
+                // an address has been provided by the user: check whether its belongs or not to the xpub
+                compare.run(this.itemToScan, this.address);
+                return { exitCode: this.exitCode };
+            }
+            else {
+                // mode B: scan mode
+                let importedTransactions;
+                if (this.args.operations) {
+                    // a file path has been provided: import its transactions
+                    importedTransactions = (0, importOperations_1.importOperations)(this.args.operations);
+                }
+                const scanResult = yield checkBalances.run(this.itemToScan, this.balanceOnly, this.scanLimits);
+                const actualAddresses = scanResult.addresses; // active addresses belonging to the xpub
+                const actualUTXOs = (0, processTransactions_1.getSortedUTXOS)(actualAddresses); // UTXOs (if any) belonging to the xpub
+                const summary = scanResult.summary; // summary: balance per derivation path
+                const actualTransactions = (0, processTransactions_1.getSortedOperations)(actualAddresses); // transactions related to the xpub
+                display.showResults(actualUTXOs, actualTransactions, summary, this.balanceOnly);
+                const partialScan = typeof this.scanLimits !== "undefined";
+                let comparisonResults;
+                if (typeof importedTransactions !== "undefined") {
+                    // transactions have been imported: comparison mode enabled
+                    // — compare imported transactions with actual ones
+                    comparisonResults = (0, compareOperations_1.checkImportedOperations)(importedTransactions, actualTransactions, actualAddresses, // scan limits
+                    partialScan);
+                }
+                // full v. partial scan
+                let mode;
+                if (typeof this.args.account !== "undefined" &&
+                    typeof this.args.index !== "undefined") {
+                    mode = `Specific derivation path - m/${this.args.account}/${this.args.index}`;
+                }
+                else if (typeof this.scanLimits !== "undefined") {
+                    let upperLimit = "∞";
+                    if (typeof this.scanLimits.indexTo !== "undefined") {
+                        upperLimit = this.scanLimits.indexTo;
+                    }
+                    mode = `Partial range — account ${this.scanLimits.account}, indices ${this.scanLimits.indexFrom}⟶${upperLimit}`;
+                }
+                else {
+                    mode = "Full scan";
+                }
+                // (special mode for Custom W)
+                if (settings_1.configuration.augmentedImport) {
+                    // Augmented import mode:
+                    // Use of an augmented JSON to compare smart contract interactions
+                    mode += " | Augmented Import";
+                }
+                // balance only mode
+                if (this.balanceOnly) {
+                    // Balance only mode
+                    mode += " | Balance Only";
+                }
+                const meta = {
+                    xpub: this.itemToScan,
+                    date: this.now,
+                    version,
+                    mode,
+                    preDerivationSize: this.args.preDerivationSize,
+                    derivationMode: settings_1.configuration.specificDerivationMode,
+                    balanceOnly: this.balanceOnly,
+                };
+                const data = {
+                    summary,
+                    addresses: actualAddresses,
+                    transactions: actualTransactions,
+                    comparisons: comparisonResults,
+                };
+                if (this.args.save || this.args.save === "" /* allow empty arg */) {
+                    (0, saveAnalysis_1.save)(meta, data, this.args.save);
+                }
+                if (this.args.diff || this.args.balance || this.args.balance === "0") {
+                    const actualBalance = summary.reduce((accumulator, s) => accumulator + s.balance.toNumber(), 0);
+                    this.exitCode = (0, diffs_1.showDiff)(actualBalance, this.args.balance, comparisonResults, this.args.diff);
+                }
+                return { meta, data, exitCode: this.exitCode };
+            }
+        });
+    }
+}
+exports.Scanner = Scanner;

package/lib/api/customProvider.d.ts

@@ -0,0 +1,19 @@
+import { Address } from "../models/address";
+/**
+ * fetch the structured 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
+ */
+declare function getStats(address: Address, balanceOnly: boolean): Promise<void>;
+/**
+ * get all structured transactions related to an address
+ * @param address the address being analyzed
+ */
+declare function getTransactions(address: Address): void;
+/**
+ * get all normalized transactions related to an account-based address
+ * @param address an account-based address (typically Ethereum)
+ */
+declare function getAccountBasedTransactions(address: Address): void;
+export { getStats, getTransactions, getAccountBasedTransactions };

package/lib/api/customProvider.js

@@ -0,0 +1,434 @@
+"use strict";
+// Here, the raw data is fetched from Crypto APIs (i.e., Crypto APIs):
+//  - balance,
+//  - total spent and received, and
+//  - operations
+// per address
+//
+// Crypto APIs 2.0 <https://cryptoapis.io/>
+// https://developers.cryptoapis.io/technical-documentation/general-information/overview
+//
+// In order to enable Crypto APIs, an API key has to be provided (see: README.md)
+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.getAccountBasedTransactions = exports.getTransactions = exports.getStats = void 0;
+const helpers = __importStar(require("../helpers"));
+const currencies_1 = require("../configuration/currencies");
+const settings_1 = require("../configuration/settings");
+const transaction_1 = require("../models/transaction");
+const operation_1 = require("../models/operation");
+const date_fns_1 = require("date-fns");
+const bchaddrjs_1 = __importDefault(require("bchaddrjs"));
+const bignumber_js_1 = __importDefault(require("bignumber.js"));
+const object_hash_1 = __importDefault(require("object-hash"));
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ FETCH RAW DATA FROM CRYPTO APIS ┃
+// ┃ just fetch the JSON responses   ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+/**
+ * fetch the response associated with the request (basic data, transactions)
+ * @param currency the currency being analyzed
+ * @param address the address being analyzed
+ * @param endpoint the endpoint to call
+ * @returns an array of transactions (if any)
+ */
+function fetchPayloads(currency, address, endpoint) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // limit the number of transactions per request
+        const maxItemsPerRequest = 50;
+        const payloads = [];
+        const getTxsURLTemplate = settings_1.configuration.externalProviderURL
+            .concat("/addresses/")
+            .concat(address.toString())
+            .replace("{currency}", currency)
+            .concat(endpoint
+            .concat("?limit=")
+            .concat(maxItemsPerRequest.toString())
+            .concat("&offset={offset}"));
+        // to handle large number of transactions by address, use the index+limit logic
+        // offered by Crypto APIs
+        let offset = 0;
+        let itemsRemainingToBeFetched = true;
+        while (itemsRemainingToBeFetched) {
+            const url = getTxsURLTemplate.replace("{offset}", String(offset));
+            const txs = yield helpers.getJSON(url, settings_1.configuration.APIKey);
+            const payload = txs.data.items;
+            // when the limit includes the total number of transactions,
+            // no need to go further
+            if (payload.length === 0) {
+                itemsRemainingToBeFetched = false;
+                break;
+            }
+            payloads.push(payload);
+            offset += maxItemsPerRequest;
+        }
+        return payloads;
+    });
+}
+/**
+ * fetch the transactions associated with a transaction hash
+ * @param currency the currency being analyzed
+ * @param transactionHash a transaction hash
+ * @returns the transactions associated with a transaction hash
+ */
+function fetchTransactionPayload(currency, transactionHash) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const url = settings_1.configuration.externalProviderURL
+            .replace("{currency}", currency)
+            .concat("/transactions/")
+            .concat(transactionHash);
+        // important: a valid API key has to be provided
+        const txs = yield helpers.getJSON(url, settings_1.configuration.APIKey);
+        return txs.data.item;
+    });
+}
+/**
+ * fetch the raw basic stats (balance, transactions count...) associated with an address
+ * @param currency the currency being analyzed
+ * @param address the address being analyzed
+ * @returns the basic data associated with an address
+ */
+function fetchOperationsPayloads(currency, address) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return fetchPayloads(currency, address.toString(), "/transactions");
+    });
+}
+/**
+ * fetch the raw token-related transactions related to an address
+ * @param currency the currency being analyzed (account-based; typically Ethereum)
+ * @param address the address being analyzed (account-based; typically Ethereum)
+ * @returns the token-related transactions related to an address
+ */
+function fetchTokenPayloads(currency, address) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const rawTokenOperations = yield fetchPayloads(currency, address.toString(), "/tokens-transfers");
+        const tokenOperations = [].concat(...rawTokenOperations);
+        // augment token operations with transaction data
+        for (const tokenOperation of tokenOperations) {
+            const transaction = yield fetchTransactionPayload(currency, tokenOperation.transactionHash);
+            // add data related to recipients and senders
+            tokenOperation.recipients = transaction.recipients;
+            tokenOperation.senders = transaction.senders;
+            tokenOperation.fee = transaction.fee;
+        }
+        return tokenOperations;
+    });
+}
+/**
+ * fetch the raw internal transactions related to an address
+ * @param currency the currency being analyzed (account-based; typically Ethereum)
+ * @param address the address being analyzed (account-based; typically Ethereum)
+ * @returns the internal transactions related to an address
+ */
+function fetchInternalTransactionsPayloads(currency, address) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return fetchPayloads(currency, address.toString(), "/internal");
+    });
+}
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ NORMALIZE TRANSACTIONS FROM CRYPTO APIS           ┃
+// ┃ transform JSONs into stats and Operations objects ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+/**
+ * fetch the structured 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
+ */
+function getStats(address, balanceOnly) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // important: currency name is required to be lower case for Crypto APIs
+        const currency = settings_1.configuration.currency.name.toLowerCase().replace(" ", "-");
+        const url = settings_1.configuration.externalProviderURL
+            .concat("/addresses/")
+            .concat(address.toString())
+            .replace("{currency}", currency);
+        const res = yield helpers.getJSON(url, settings_1.configuration.APIKey);
+        const item = res.data.item;
+        const fundedSum = item.totalReceived.amount;
+        const spentSum = item.totalSpent.amount;
+        const balance = item.confirmedBalance.amount;
+        const txCount = item.transactionsCount;
+        address.setStats(txCount, fundedSum, spentSum);
+        address.setBalance(balance);
+        // get transactions (when applicable)
+        if (!balanceOnly) {
+            let payloads = yield fetchOperationsPayloads(currency, address);
+            // Ethereum: add token-related and internal transactions
+            if (settings_1.configuration.currency.symbol === currencies_1.currencies.eth.symbol) {
+                payloads = payloads.concat(yield fetchTokenPayloads(currency, address));
+                payloads = payloads.concat(payloads, yield fetchInternalTransactionsPayloads(currency, address));
+            }
+            // flatten the payloads
+            const rawTransactions = [].concat(...payloads);
+            // Remove duplicates
+            // (related to a bug from Crypto APIs)
+            const uniqueRawTransactions = [];
+            for (let i = rawTransactions.length - 1; i >= 0; i--) {
+                const transaction = rawTransactions[i];
+                const h = (0, object_hash_1.default)(transaction);
+                if (!uniqueRawTransactions.includes(h)) {
+                    uniqueRawTransactions.push(h);
+                }
+                else {
+                    // remove duplicate
+                    rawTransactions.splice(i, 1);
+                }
+            }
+            address.setRawTransactions(rawTransactions);
+        }
+    });
+}
+exports.getStats = getStats;
+/**
+ * get all structured transactions related to an address
+ * @param address the address being analyzed
+ */
+function getTransactions(address) {
+    const rawTransactions = address.getRawTransactions();
+    const transactions = [];
+    // Bitcoin Cash addresses are expressed as cash addresses by Crypto APIs:
+    // they have to be converted into legacy ones (if needed)
+    const processAddress = (originalAddress) => {
+        if (settings_1.configuration.currency.symbol === currencies_1.currencies.bch.symbol) {
+            return bchaddrjs_1.default.toLegacyAddress(originalAddress);
+        }
+        else {
+            return originalAddress;
+        }
+    };
+    // transforms raw transactions associated with an address
+    // into an array of processed transactions:
+    // [ { blockHeight, txid, ins: [ { address, value }... ], outs: [ { address, value }...] } ]
+    rawTransactions.forEach((tx) => {
+        const ins = [];
+        const outs = [];
+        // identify whether the address belongs to the list of transactors or not
+        const addressBelongsToTransactors = (transactors) => {
+            return transactors.some((t) => processAddress(t.address).includes(address.toString()));
+        };
+        // the address currently being analyzed is a — recipient —
+        if (addressBelongsToTransactors(tx.recipients)) {
+            for (const recipient of tx.recipients) {
+                if (processAddress(recipient.address).includes(address.toString())) {
+                    // add one operation per sender
+                    for (const sender of tx.senders) {
+                        const op = new operation_1.Operation(String(tx.timestamp), new bignumber_js_1.default(recipient.amount));
+                        op.setAddress(processAddress(sender.address));
+                        op.setTxid(tx.transactionId);
+                        op.setOperationType("Received");
+                        ins.push(op);
+                    }
+                }
+            }
+        }
+        // the address currently being analyzed is a — sender —
+        if (addressBelongsToTransactors(tx.senders)) {
+            for (let i = 0; i < tx.recipients.length; i++) {
+                const recipient = tx.recipients[i];
+                // note: the amount sent is specified in blockchainSpecific.vout
+                // _at the same index as the recipient_
+                const op = new operation_1.Operation(String(tx.timestamp), new bignumber_js_1.default(tx.blockchainSpecific.vout[i].value));
+                op.setAddress(processAddress(recipient.address));
+                op.setTxid(tx.transactionId);
+                op.setOperationType("Sent");
+                outs.push(op);
+            }
+        }
+        transactions.push(new transaction_1.Transaction(tx.minedInBlockHeight, (0, date_fns_1.format)(new Date(tx.timestamp * 1000), "yyyy-MM-dd HH:mm:ss"), tx.transactionId, ins, outs));
+    });
+    address.setTransactions(transactions);
+}
+exports.getTransactions = getTransactions;
+/**
+ * get all normalized transactions related to an account-based address
+ * @param address an account-based address (typically Ethereum)
+ */
+function getAccountBasedTransactions(address) {
+    const rawTransactions = address.getRawTransactions();
+    rawTransactions.forEach((tx) => {
+        // skip non-basic operations
+        if (typeof tx.blockchainSpecific === "undefined") {
+            return;
+        }
+        const isSender = tx.senders.some((t) => t.address.toLowerCase() === address.toString().toLowerCase());
+        const isRecipient = tx.recipients.some((t) => t.address.toLowerCase() === address.toString().toLowerCase());
+        const isFailedOperation = tx.blockchainSpecific.transactionStatus !== "0x1";
+        // ignore failed *incoming* transactions
+        if (isFailedOperation && isRecipient) {
+            return;
+        }
+        const timestamp = (0, date_fns_1.format)(new Date(tx.timestamp * 1000), "yyyy-MM-dd HH:mm:ss");
+        // the address currently being analyzed is a — recipient —
+        if (isRecipient) {
+            const amount = tx.recipients.reduce((a, b) => +a + +b.amount, 0);
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.transactionId);
+            op.setOperationType("Received");
+            op.setBlockNumber(tx.minedInBlockHeight);
+            address.addFundedOperation(op);
+        }
+        // the address currently being analyzed is a — sender —
+        if (isSender) {
+            const amount = new bignumber_js_1.default(tx.recipients.reduce((a, b) => +a + +b.amount, 0));
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.transactionId);
+            if (!isFailedOperation) {
+                op.setOperationType(isRecipient ? "Sent to self" : "Sent");
+            }
+            else {
+                // failed outgoing operation
+                op.setOperationType("Failed to send");
+            }
+            op.setBlockNumber(tx.minedInBlockHeight);
+            address.addSentOperation(op);
+        }
+    });
+    getTokenTransactions(address);
+    getInternalTransactions(address);
+}
+exports.getAccountBasedTransactions = getAccountBasedTransactions;
+/**
+ * get all normalized token-related transactions associated with an account-based address
+ * @param address an account-based address (typically Ethereum)
+ */
+function getTokenTransactions(address) {
+    const rawTransactions = address.getRawTransactions();
+    rawTransactions.forEach((tx) => {
+        // skip non-token operations
+        if (typeof tx.senderAddress === "undefined") {
+            return;
+        }
+        const isSender = tx.senderAddress.toLocaleLowerCase() ===
+            address.toString().toLocaleLowerCase();
+        const isRecipient = tx.recipientAddress.toLocaleLowerCase() ===
+            address.toString().toLocaleLowerCase();
+        const tokenAmount = new bignumber_js_1.default(tx.tokensAmount);
+        const tokenName = tx.tokenName;
+        const tokenSymbol = tx.tokenSymbol;
+        const timestamp = (0, date_fns_1.format)(new Date(tx.transactionTimestamp * 1000), "yyyy-MM-dd HH:mm:ss");
+        // compute amount
+        // (note: the dualities isSender/isRecipient and has sent/has received do not necessarily
+        //        overlap (e.g., a recipient can also have sent in the swapping context)
+        const fees = new bignumber_js_1.default(tx.fee.amount);
+        let amount = new bignumber_js_1.default(0);
+        let hasSent = false;
+        // the address currently being analyzed is a — recipient —
+        for (const recipient of tx.recipients) {
+            if (recipient.address.toLocaleLowerCase() ===
+                address.toString().toLocaleLowerCase()) {
+                amount = amount.plus(recipient.amount);
+            }
+        }
+        // the address currently being analyzed is a — sender —
+        for (const sender of tx.senders) {
+            if (sender.address.toLocaleLowerCase() ===
+                address.toString().toLocaleLowerCase()) {
+                amount = amount.minus(sender.amount);
+                hasSent = true;
+            }
+        }
+        if (hasSent) {
+            amount = amount.plus(fees); // if has sent, add fees
+        }
+        // the address currently being analyzed is a — recipient —
+        if (isRecipient) {
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.transactionHash);
+            // operation type: if is recipient but has sent: swap operation
+            op.setOperationType(hasSent ? "Swapped" : "Received (token)");
+            op.setBlockNumber(tx.minedInBlockHeight);
+            op.addToken(tokenSymbol, tokenName, tokenAmount);
+            address.addFundedOperation(op);
+        }
+        // the address currently being analyzed is a — sender —
+        if (isSender) {
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.transactionHash);
+            op.setOperationType("Sent (token)");
+            op.setBlockNumber(tx.minedInBlockHeight);
+            op.addToken(tokenSymbol, tokenName, tokenAmount);
+            address.addSentOperation(op);
+        }
+    });
+}
+/**
+ * get all normalized internal transactions associated with an account-based address
+ * @param address an account-based address (typically Ethereum)
+ */
+function getInternalTransactions(address) {
+    const rawTransactions = address.getRawTransactions();
+    rawTransactions.forEach((tx) => {
+        // skip non-internal transactions
+        if (typeof tx.operationType === "undefined") {
+            return;
+        }
+        const isSender = tx.sender.toLocaleLowerCase() === address.toString().toLocaleLowerCase();
+        const isRecipient = tx.recipient.toLocaleLowerCase() ===
+            address.toString().toLocaleLowerCase();
+        const amount = new bignumber_js_1.default(0);
+        const timestamp = (0, date_fns_1.format)(new Date(tx.timestamp * 1000), "yyyy-MM-dd HH:mm:ss");
+        // the address currently being analyzed is a — recipient —
+        if (isRecipient) {
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.parentHash);
+            op.setOperationType("SCI (recipient)");
+            op.setBlockNumber(tx.minedInBlockHeight);
+            address.addFundedOperation(op);
+        }
+        // the address currently being analyzed is a — sender —
+        if (isSender) {
+            const fixedAmount = amount.toFixed(settings_1.ETH_FIXED_PRECISION);
+            const op = new operation_1.Operation(timestamp, new bignumber_js_1.default(fixedAmount)); // ETH: use fixed-point notation
+            op.setAddress(address.toString());
+            op.setTxid(tx.parentHash);
+            op.setOperationType("SCI (caller)");
+            op.setBlockNumber(tx.minedInBlockHeight);
+            address.addSentOperation(op);
+        }
+    });
+}

package/lib/api/defaultProvider.d.ts

@@ -0,0 +1,23 @@
+import { Address } from "../models/address";
+/**
+ * fetch the structured basic stats related to an address
+ * its balance, funded and spend sums and counts
+ * @param address the address being analyzed
+ */
+declare function getStats(address: Address): Promise<void>;
+/**
+ * get all structured transactions related to an address
+ * @param address the address being analyzed
+ */
+declare function getTransactions(address: Address): void;
+/**
+ * get all structured transactions related to a Bitcoin Cash address
+ * @param address the address being analyzed
+ */
+declare function getBitcoinCashTransactions(address: Address): void;
+/**
+ * get all structured transactions related to an account-based address (generally Ethereum)
+ * @param address the address being analyzed
+ */
+declare function getAccountBasedTransactions(address: Address): void;
+export { getStats, getTransactions, getBitcoinCashTransactions, getAccountBasedTransactions, };