crypttrace 0.29.0__tar.gz → 0.31.0__tar.gz

{crypttrace-0.29.0/src/crypttrace.egg-info → crypttrace-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.29.0
+Version: 0.31.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -15,14 +15,14 @@ Classifier: Intended Audience :: Information Technology
 Classifier: Intended Audience :: Legal Industry
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Utilities
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typer>=0.12
@@ -42,7 +42,7 @@ Dynamic: license-file
 Open-source OSINT toolkit for crypto investigations. Give it a suspicious
 address; it pulls the public on-chain history, labels known entities (exchanges,
 mixers, sanctioned wallets), scores risk, and maps where the funds moved —
-across Ethereum, Bitcoin, Tron, Solana, TON and more.
+across Ethereum, Bitcoin, Tron, Solana, TON, Litecoin, Dogecoin and more.
 
 Built for the investigation that actually happens: *someone's crypto was stolen,
 here's the wallet — where did the money go, and where can it still be stopped?*
@@ -66,7 +66,7 @@ pipx install "crypttrace[web]"     # or: pip install "crypttrace[web]"
 ```
 
 `[web]` also installs Flask for the web UI; leave it off for the terminal tool
-alone. Python 3.9 or newer. To work on the code instead:
+alone. Python 3.10 or newer. To work on the code instead:
 
 ```bash
 git clone https://github.com/bobslayerX/crypttrace
@@ -80,7 +80,7 @@ python selftest.py                 # offline checks, no API keys needed
 | | Needed? | How to get it |
 |---|---|---|
 | **EVM chains** (Ethereum, BSC, Polygon, Arbitrum, Optimism, Base) | **Required** | Free key at [etherscan.io/myapikey](https://etherscan.io/myapikey) covers Ethereum, Polygon and Arbitrum. BSC, Optimism and Base need a paid Etherscan plan; on a free key crypttrace says so instead of showing an empty wallet. |
-| **Bitcoin, Tron, Solana, TON** | **Not required** | Work out of the box via public endpoints. |
+| **Bitcoin, Litecoin, Dogecoin, Tron, Solana, TON** | **Not required** | Work out of the box via public endpoints. Dogecoin reads BlockCypher's free tier, about 100 requests an hour, so it reads the latest 200 transactions of an address. |
 
 ```bash
 export ETHERSCAN_API_KEY=xxxx           # required for EVM chains only
@@ -122,6 +122,8 @@ the number either way.
 |---|---|---|---|
 | Ethereum, BSC, Polygon, Arbitrum, Optimism, Base | `eth` `bsc` `polygon` `arbitrum` `optimism` `base` | Etherscan v2 (BSC, Optimism, Base: paid plan) | account |
 | Bitcoin | `btc` | mempool.space | UTXO |
+| Litecoin | `ltc` | litecoinspace.org | UTXO |
+| Dogecoin | `doge` | BlockCypher | UTXO |
 | Tron (TRX + USDT-TRC20) | `tron` | TronGrid | account |
 | Solana (SOL + SPL) | `sol` | public JSON-RPC | account |
 | TON (TON + jettons, e.g. USDT) | `ton` | toncenter v3 | account |
@@ -472,7 +474,7 @@ with an `nfts` column in the CSV. Failed (aborted) NFT transfers are not counted
 
 ### Bitcoin clustering (common-input-ownership)
 
-Bitcoin's UTXO model enables the strongest clustering heuristic in blockchain
+Bitcoin's UTXO model (Litecoin's and Dogecoin's too) enables the strongest clustering heuristic in blockchain
 forensics: if several addresses sign the inputs of one transaction, one party
 almost certainly controls all of them. `cluster` surfaces those co-signers,
 turning a single address into a set of wallets belonging to the same owner. A

{crypttrace-0.29.0 → crypttrace-0.31.0}/README.md

@@ -8,7 +8,7 @@
 Open-source OSINT toolkit for crypto investigations. Give it a suspicious
 address; it pulls the public on-chain history, labels known entities (exchanges,
 mixers, sanctioned wallets), scores risk, and maps where the funds moved —
-across Ethereum, Bitcoin, Tron, Solana, TON and more.
+across Ethereum, Bitcoin, Tron, Solana, TON, Litecoin, Dogecoin and more.
 
 Built for the investigation that actually happens: *someone's crypto was stolen,
 here's the wallet — where did the money go, and where can it still be stopped?*
@@ -32,7 +32,7 @@ pipx install "crypttrace[web]"     # or: pip install "crypttrace[web]"
 ```
 
 `[web]` also installs Flask for the web UI; leave it off for the terminal tool
-alone. Python 3.9 or newer. To work on the code instead:
+alone. Python 3.10 or newer. To work on the code instead:
 
 ```bash
 git clone https://github.com/bobslayerX/crypttrace
@@ -46,7 +46,7 @@ python selftest.py                 # offline checks, no API keys needed
 | | Needed? | How to get it |
 |---|---|---|
 | **EVM chains** (Ethereum, BSC, Polygon, Arbitrum, Optimism, Base) | **Required** | Free key at [etherscan.io/myapikey](https://etherscan.io/myapikey) covers Ethereum, Polygon and Arbitrum. BSC, Optimism and Base need a paid Etherscan plan; on a free key crypttrace says so instead of showing an empty wallet. |
-| **Bitcoin, Tron, Solana, TON** | **Not required** | Work out of the box via public endpoints. |
+| **Bitcoin, Litecoin, Dogecoin, Tron, Solana, TON** | **Not required** | Work out of the box via public endpoints. Dogecoin reads BlockCypher's free tier, about 100 requests an hour, so it reads the latest 200 transactions of an address. |
 
 ```bash
 export ETHERSCAN_API_KEY=xxxx           # required for EVM chains only
@@ -88,6 +88,8 @@ the number either way.
 |---|---|---|---|
 | Ethereum, BSC, Polygon, Arbitrum, Optimism, Base | `eth` `bsc` `polygon` `arbitrum` `optimism` `base` | Etherscan v2 (BSC, Optimism, Base: paid plan) | account |
 | Bitcoin | `btc` | mempool.space | UTXO |
+| Litecoin | `ltc` | litecoinspace.org | UTXO |
+| Dogecoin | `doge` | BlockCypher | UTXO |
 | Tron (TRX + USDT-TRC20) | `tron` | TronGrid | account |
 | Solana (SOL + SPL) | `sol` | public JSON-RPC | account |
 | TON (TON + jettons, e.g. USDT) | `ton` | toncenter v3 | account |
@@ -438,7 +440,7 @@ with an `nfts` column in the CSV. Failed (aborted) NFT transfers are not counted
 
 ### Bitcoin clustering (common-input-ownership)
 
-Bitcoin's UTXO model enables the strongest clustering heuristic in blockchain
+Bitcoin's UTXO model (Litecoin's and Dogecoin's too) enables the strongest clustering heuristic in blockchain
 forensics: if several addresses sign the inputs of one transaction, one party
 almost certainly controls all of them. `cluster` surfaces those co-signers,
 turning a single address into a set of wallets belonging to the same owner. A

{crypttrace-0.29.0 → crypttrace-0.31.0}/pyproject.toml

@@ -6,7 +6,7 @@ readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "bobslayerX" }]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 keywords = ["osint", "blockchain", "forensics", "cryptocurrency", "bitcoin", "ethereum", "tron", "solana", "ton", "investigation"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -16,11 +16,11 @@ classifiers = [
     "Intended Audience :: Legal Industry",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Security",
     "Topic :: Utilities",
 ]

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/__init__.py

@@ -1,2 +1,2 @@
 """crypttrace — OSINT crypto investigation CLI."""
-__version__ = "0.29.0"
+__version__ = "0.31.0"

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/addresses.py

@@ -82,6 +82,18 @@ def check_base58check(addr: str, expect_prefix: Optional[bytes] = None) -> Tuple
     return True, "base58check checksum valid"
 
 
+def _versioned(addr: str, versions: dict, name: str) -> Tuple[bool, str]:
+    """base58check plus the chain's version byte — a Bitcoin '3…' address passes the
+    checksum too, so the version is what tells the chains apart."""
+    ok, why = check_base58check(addr)
+    if not ok:
+        return ok, why
+    v = _b58_decode(addr)[0]
+    if v not in versions:
+        return False, f"version byte {v:#04x} is not a {name} address"
+    return True, "base58check checksum valid"
+
+
 # ---------------------------------------------------------------- per chain
 
 def validate(address: str, chain: str) -> Tuple[bool, str]:
@@ -108,6 +120,18 @@ def validate(address: str, chain: str) -> Tuple[bool, str]:
             return check_base58check(a)
         return False, "not a recognised Bitcoin address format"
 
+    if chain == "ltc":
+        if a.lower().startswith("ltc1"):
+            return check_bech32(a, "ltc")
+        if a.startswith(("L", "M", "3")):
+            return _versioned(a, {0x30: "L", 0x32: "M", 0x05: "3"}, "Litecoin")
+        return False, "not a recognised Litecoin address format (L…, M…, 3… or ltc1…)"
+
+    if chain == "doge":
+        if a.startswith(("D", "A", "9")):
+            return _versioned(a, {0x1E: "D", 0x16: "A/9"}, "Dogecoin")
+        return False, "not a recognised Dogecoin address format (D…, A… or 9…)"
+
     if chain == "tron":
         if not a.startswith("T") or len(a) != 34:
             return False, "Tron addresses start with T and are 34 characters"

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/analysis.py

@@ -22,7 +22,7 @@ from crypttrace.labels import labels
 # Amounts below these are treated as dust: spam sent to well-known addresses to
 # pollute their history (and sometimes to deanonymise the owner). Left in, dust
 # drowns out the transfers an investigation is actually about.
-DUST = {"btc": 0.0005, "eth": 0.002, "bsc": 0.005, "polygon": 5.0,
+DUST = {"btc": 0.0005, "ltc": 0.001, "doge": 5.0, "eth": 0.002, "bsc": 0.005, "polygon": 5.0,
         "arbitrum": 0.002, "optimism": 0.002, "base": 0.002,
         "tron": 5.0, "sol": 0.01, "ton": 0.01}
 

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/assets.py

@@ -69,8 +69,8 @@ def resolve_asset(asset: Optional[str], chain: str = "eth") -> Optional[dict]:
     elif a.startswith("0x") and len(a) == 42:
         return {"contract": a, "symbol": asset.upper()[:8], "stable": False}
 
-    if chain == "btc":
-        raise ValueError("Bitcoin has no tokens — omit --asset (or use --asset btc).")
+    if chain in ("btc", "ltc", "doge"):
+        raise ValueError(f"{chain.upper()} has no tokens — omit --asset (or use --asset {chain}).")
 
     opts = ", ".join(known) or "none registered"
     raise ValueError(f"Unknown asset '{asset}' on {chain}. Known symbols: {opts}. "

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/chains.py

@@ -19,17 +19,19 @@ from crypttrace.labels import labels as _labels
 from crypttrace.fetchers import etherscan, bitcoin, http as _http, tron, solana, ton
 
 EVM_CHAINS = set(config.CHAINS)
-NON_EVM = {"btc", "tron", "sol", "ton"}
+NON_EVM = {"btc", "ltc", "doge", "tron", "sol", "ton"}
 ALL_CHAINS = sorted(EVM_CHAINS | NON_EVM)
 
 SYMBOL = {"eth": "ETH", "bsc": "BNB", "polygon": "MATIC", "arbitrum": "ETH",
-          "optimism": "ETH", "base": "ETH", "btc": "BTC", "tron": "TRX", "sol": "SOL", "ton": "TON"}
+          "optimism": "ETH", "base": "ETH", "btc": "BTC", "ltc": "LTC", "doge": "DOGE", "tron": "TRX", "sol": "SOL",
+          "ton": "TON"}
 
 EXPLORER = {
     "eth": "https://etherscan.io/address/{}", "bsc": "https://bscscan.com/address/{}",
     "polygon": "https://polygonscan.com/address/{}", "arbitrum": "https://arbiscan.io/address/{}",
     "optimism": "https://optimistic.etherscan.io/address/{}", "base": "https://basescan.org/address/{}",
-    "btc": "https://mempool.space/address/{}", "tron": "https://tronscan.org/#/address/{}",
+    "btc": "https://mempool.space/address/{}", "ltc": "https://litecoinspace.org/address/{}",
+    "doge": "https://blockchair.com/dogecoin/address/{}", "tron": "https://tronscan.org/#/address/{}",
     "sol": "https://solscan.io/account/{}", "ton": "https://tonviewer.com/{}",
 }
 
@@ -37,7 +39,8 @@ TX_EXPLORER = {
     "eth": "https://etherscan.io/tx/{}", "bsc": "https://bscscan.com/tx/{}",
     "polygon": "https://polygonscan.com/tx/{}", "arbitrum": "https://arbiscan.io/tx/{}",
     "optimism": "https://optimistic.etherscan.io/tx/{}", "base": "https://basescan.org/tx/{}",
-    "btc": "https://mempool.space/tx/{}", "tron": "https://tronscan.org/#/transaction/{}",
+    "btc": "https://mempool.space/tx/{}", "ltc": "https://litecoinspace.org/tx/{}",
+    "doge": "https://blockchair.com/dogecoin/transaction/{}", "tron": "https://tronscan.org/#/transaction/{}",
     "sol": "https://solscan.io/tx/{}", "ton": "https://tonviewer.com/transaction/{}",
 }
 
@@ -53,6 +56,11 @@ def is_evm(chain: str) -> bool:
     return chain in EVM_CHAINS
 
 
+def is_utxo(chain: str) -> bool:
+    """Bitcoin, Litecoin, Dogecoin: outputs and inputs, no tokens."""
+    return chain in bitcoin.UTXO_CHAINS
+
+
 def case_sensitive(chain: str) -> bool:
     """Bitcoin/Tron/Solana use base58 — address case is significant."""
     return chain in NON_EVM
@@ -86,8 +94,8 @@ def balance(address: str, chain: str = "eth") -> float:
     try:
         if is_evm(chain):
             return etherscan.get_balance(address, chain)
-        if chain == "btc":
-            return bitcoin.balance(address)
+        if is_utxo(chain):
+            return bitcoin.balance(address, chain)
         if chain == "tron":
             return tron.balance(address)
         if chain == "sol":
@@ -221,10 +229,10 @@ def transfers(address: str, chain: str = "eth", limit: int = 1000,
         if is_evm(chain):
             rows = _evm_token(address, chain, contract, limit) if asset \
                 else _evm_native(address, chain, limit)
-        elif chain == "btc":
+        elif is_utxo(chain):
             if asset:
-                raise ChainError("Bitcoin has no tokens.")
-            rows = bitcoin.transfers(address, limit)
+                raise ChainError(f"{bitcoin.NETWORKS[chain]['name']} has no tokens.")
+            rows = bitcoin.transfers(address, limit, chain=chain)
         elif chain == "tron":
             # keep TRX and TRC20 strictly separate
             rows = _tron_token(address, contract, limit) if asset \
@@ -337,7 +345,7 @@ def inflows(address: str, chain: str, top: int, limit: int = 1000, asset=None):
 def token_holdings(address: str, chain: str = "eth", limit: int = 1000) -> List[Dict]:
     """Approximate token holdings from transfer history (net in − out per token)."""
     check(chain)
-    if chain == "btc":
+    if is_utxo(chain):
         return []
     me = norm_addr(address, chain)
     try:

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/cli.py

@@ -762,7 +762,7 @@ def verify(
     style = _verdict_style(v["status"])
     console.print(f"\n[{style}]{v['status'].upper()}[/{style}]  {verify_mod.headline(v)}\n")
 
-    if v["checks"]:
+    if v.get("checks"):        # absent when the chain could not be read at all
         t = render.Table(title="Cross-check against the chain", header_style="bold")
         t.add_column("Figure"); t.add_column("Computed", justify="right")
         t.add_column("Chain", justify="right"); t.add_column("", justify="center")
@@ -803,12 +803,12 @@ def cluster(
                       "funder set it up. Wallets set up by the same person's wallet are likely one party; a "
                       "funding from an exchange, mixer, bridge or any contract links nothing. A lead, not proof.[/dim]")
         return
-    if chain != "btc":
-        console.print("[red]Error:[/red] cluster works on Bitcoin and EVM chains")
+    if not chains_mod.is_utxo(chain):
+        console.print("[red]Error:[/red] cluster works on Bitcoin, Litecoin, Dogecoin and EVM chains")
         raise typer.Exit(1)
     from crypttrace.fetchers import bitcoin
     try:
-        peers = bitcoin.cluster(address)
+        peers = bitcoin.cluster(address, chain)
     except bitcoin.BitcoinError as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
@@ -884,6 +884,8 @@ def chains():
         console.print(f"  {name:<10} chainid {cid}{paid}")
     console.print("\n[bold]Non-EVM[/bold] (no API key needed):")
     console.print("  btc        Bitcoin — mempool.space (UTXO)")
+    console.print("  ltc        Litecoin — litecoinspace.org (UTXO)")
+    console.print("  doge       Dogecoin — BlockCypher (UTXO; free tier ~100 requests an hour)")
     console.print("  tron       Tron — TronGrid (TRX + USDT-TRC20)")
     console.print("  sol        Solana — public JSON-RPC")
     console.print("  ton        TON — toncenter (TON + jettons such as USDT)")

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/drain.py

@@ -29,7 +29,7 @@ _ALL_TOKENS = {"contract": None, "symbol": "*"}
 
 def _history(address: str, chain: str, limit: int) -> List[dict]:
     rows = list(chains.transfers(address, chain, limit))
-    if chain != "btc":
+    if not chains.is_utxo(chain):
         try:
             rows += [r for r in chains.transfers(address, chain, limit, asset=_ALL_TOKENS)
                      if not spam.verdict(chain, r.get("contract", ""), r.get("symbol", ""),

crypttrace-0.31.0/src/crypttrace/fetchers/bitcoin.py

@@ -0,0 +1,287 @@
+"""UTXO chains — Bitcoin, Litecoin, Dogecoin — with no API key required.
+
+Bitcoin reads mempool.space and Litecoin its twin litecoinspace.org (both
+Esplora). Dogecoin has no public Esplora, so it reads BlockCypher, whose
+answers are turned into the same shape; its free tier allows about 100
+requests an hour, which is enough for a check and a few hops of tracing.
+
+These chains use the UTXO model, not accounts: a transaction consumes previous
+outputs and creates new ones, so there is no single "from" or "to". To fit the
+same tracing engine used for EVM chains, transactions are normalized into
+directional transfer rows:
+
+  * if our address signed an input, each output that isn't ours is an outflow
+    (outputs back to ourselves are change and are skipped);
+  * otherwise, outputs paying us are inflows, attributed to the first input.
+
+UTXO chains also enable the strongest clustering heuristic in blockchain
+forensics: common-input-ownership. If several addresses sign inputs of the
+same transaction, one party almost certainly controls all of them.
+"""
+import datetime as dt
+from typing import List, Dict, Optional
+
+import requests
+
+NETWORKS = {
+    "btc": {"name": "Bitcoin", "symbol": "BTC", "api": "esplora", "base": "https://mempool.space/api",
+            "host": "mempool.space"},
+    "ltc": {"name": "Litecoin", "symbol": "LTC", "api": "esplora", "base": "https://litecoinspace.org/api",
+            "host": "litecoinspace.org"},
+    "doge": {"name": "Dogecoin", "symbol": "DOGE", "api": "blockcypher",
+             "base": "https://api.blockcypher.com/v1/doge/main", "host": "BlockCypher"},
+}
+UTXO_CHAINS = set(NETWORKS)
+BASE = NETWORKS["btc"]["base"]
+SATS = 100_000_000          # satoshis, litoshis and koinus alike
+BLOCKCYPHER_MAX_TXS = 200   # history read per Dogecoin address: the free tier is ~100 calls an hour
+
+
+class BitcoinError(RuntimeError):
+    pass
+
+
+def _net(chain: str) -> dict:
+    if chain not in NETWORKS:
+        raise BitcoinError(f"not a UTXO chain: {chain}")
+    return NETWORKS[chain]
+
+
+def _get(path: str, timeout: int = 30, chain: str = "btc", params: Optional[dict] = None):
+    """Cached, throttled GET against the chain's explorer API."""
+    from crypttrace.fetchers import http
+    n = _net(chain)
+    try:
+        data = http.request_json(f"{n['base']}{path}", params or {}, timeout=timeout)
+    except http.RateLimited as e:
+        raise BitcoinError(str(e) + (" (BlockCypher's free tier allows about 100 requests an hour)"
+                                     if n["api"] == "blockcypher" else ""))
+    except requests.RequestException as e:
+        raise BitcoinError(f"{n['host']} request failed: {e}")
+    except ValueError as e:
+        raise BitcoinError(f"bad response from {n['host']}: {e}")
+    if isinstance(data, dict) and "__status__" in data:
+        if data["__status__"] == 400:
+            raise BitcoinError(f"{n['name']} address rejected by {n['host']} — check it is "
+                               "exact (these addresses are case-sensitive).")
+        raise BitcoinError(f"Address not found on the {n['name']} chain.")
+    return data
+
+
+def stats(address: str, chain: str = "btc") -> Dict:
+    """Authoritative totals straight from the chain index.
+
+    These are the numbers our own parsing must agree with — the reference for
+    checking that a trace didn't miscount or silently miss history.
+    """
+    if _net(chain)["api"] == "blockcypher":
+        d = _get(f"/addrs/{address}/balance", chain=chain)
+        recv, sent = (d.get("total_received") or 0) / SATS, (d.get("total_sent") or 0) / SATS
+        return {"received": recv, "sent": sent, "balance": recv - sent,
+                "tx_count": d.get("final_n_tx") or d.get("n_tx") or 0, "funded_outputs": None}
+    d = _get(f"/address/{address}", chain=chain)
+    cs = d.get("chain_stats", {}) or {}
+    ms = d.get("mempool_stats", {}) or {}
+    recv = (cs.get("funded_txo_sum", 0) + ms.get("funded_txo_sum", 0)) / SATS
+    sent = (cs.get("spent_txo_sum", 0) + ms.get("spent_txo_sum", 0)) / SATS
+    return {
+        "received": recv,
+        "sent": sent,
+        "balance": recv - sent,
+        "tx_count": (cs.get("tx_count", 0) + ms.get("tx_count", 0)),
+        "funded_outputs": (cs.get("funded_txo_count", 0) + ms.get("funded_txo_count", 0)),
+    }
+
+
+def balance(address: str, chain: str = "btc") -> float:
+    return stats(address, chain)["balance"]
+
+
+def _bc_time(tx: dict) -> int:
+    s = tx.get("confirmed") or tx.get("received") or ""
+    try:
+        return int(dt.datetime.fromisoformat(s.replace("Z", "+00:00")).timestamp())
+    except ValueError:
+        return 0
+
+
+def _from_blockcypher(tx: dict) -> dict:
+    """A BlockCypher transaction in Esplora's shape, so one parser serves every chain."""
+    first = lambda xs: (xs or [None])[0]
+    return {
+        "txid": tx.get("hash", ""),
+        "status": {"block_time": _bc_time(tx)},
+        "vin": [{"prevout": {"scriptpubkey_address": first(i.get("addresses")),
+                             "value": i.get("output_value") or 0}} for i in tx.get("inputs") or []],
+        "vout": [{"scriptpubkey_address": first(o.get("addresses")), "value": o.get("value") or 0}
+                 for o in tx.get("outputs") or []],
+    }
+
+
+def raw_txs(address: str, max_txs: int = 500, chain: str = "btc") -> List[dict]:
+    """Transactions touching this address, paging back through history.
+
+    The explorers return ~50 per call. A single page is not enough for
+    investigations: famous addresses get spammed with dust, which pushes the
+    transactions that actually matter out of the recent window. So we follow
+    the cursor back until we have enough history.
+    """
+    out: List[dict] = []
+    if _net(chain)["api"] == "blockcypher":
+        seen, before = set(), None
+        while len(out) < max_txs:
+            params = {"limit": 50, "txlimit": 500}      # txlimit: inputs/outputs per tx (default 20)
+            if before is not None:
+                params["before"] = before
+            d = _get(f"/addrs/{address}/full", chain=chain, params=params)
+            batch = [t for t in (d.get("txs") or []) if t.get("hash") not in seen]
+            if not batch:
+                break
+            for t in batch:
+                seen.add(t.get("hash"))
+                out.append(_from_blockcypher(t))
+            heights = [t.get("block_height") for t in batch if (t.get("block_height") or -1) > 0]
+            if not d.get("hasMore") or not heights:
+                break
+            before = min(heights)
+        return out[:max_txs]
+    last: Optional[str] = None
+    while len(out) < max_txs:
+        path = f"/address/{address}/txs" if last is None \
+            else f"/address/{address}/txs/chain/{last}"
+        batch = _get(path, chain=chain)
+        if not isinstance(batch, list) or not batch:
+            break
+        out.extend(batch)
+        if len(batch) < 25:      # last page
+            break
+        nxt = batch[-1].get("txid")
+        if not nxt or nxt == last:
+            break
+        last = nxt
+    return out[:max_txs]
+
+
+def _in_addrs(tx: dict) -> List[str]:
+    out = []
+    for v in tx.get("vin", []) or []:
+        a = (v.get("prevout") or {}).get("scriptpubkey_address")
+        if a:
+            out.append(a)
+    return out
+
+
+def _in_pairs(tx: dict):
+    """(address, value) for every input — a UTXO tx can be funded by many parties."""
+    for v in tx.get("vin", []) or []:
+        p = v.get("prevout") or {}
+        a = p.get("scriptpubkey_address")
+        if a:
+            yield a, (p.get("value", 0) or 0) / SATS
+
+
+def _out_pairs(tx: dict):
+    for o in tx.get("vout", []) or []:
+        a = o.get("scriptpubkey_address")
+        if a:
+            yield a, o.get("value", 0) / SATS
+
+
+def _depth(limit: int, chain: str) -> int:
+    """How many transactions of history to read for `limit` transfer rows."""
+    depth = max(limit, 200)
+    if _net(chain)["api"] == "blockcypher":
+        depth = min(depth, BLOCKCYPHER_MAX_TXS)        # 4 calls of the ~100 an hour
+    return depth
+
+
+def change(address: str, limit: int = 1000, chain: str = "btc") -> Dict[str, float]:
+    """What the address paid back to itself as change, over the same history
+    `transfers` reads. Transfers leave change out — it is not money moving — but
+    the chain's totals count it twice, so a check against them adds it back:
+    in full to "received" (the change output is the address's), and in the
+    address's share of the inputs to "sent" (when others funded the transaction
+    too, only that share of what came back was the address's own spending)."""
+    received = sent = 0.0
+    for tx in raw_txs(address, max_txs=_depth(limit, chain), chain=chain):
+        ins = list(_in_pairs(tx))
+        mine_in = sum(v for a, v in ins if a == address)
+        if mine_in <= 0:
+            continue
+        back = sum(v for a, v in _out_pairs(tx) if a == address)
+        received += back
+        sent += back * mine_in / sum(v for _, v in ins)
+    return {"received": received, "sent": sent}
+
+
+def transfers(address: str, limit: int = 1000, chain: str = "btc") -> List[Dict]:
+    """Normalized {from,to,value,timestamp,hash,symbol} rows.
+
+    A UTXO transaction has no single sender: it can be funded by many inputs
+    from different owners and pay many outputs. Attributing a whole transfer to
+    the first input address — the naive shortcut — badly misreports
+    consolidations, e.g. crediting one wallet with funds a hundred others
+    supplied. So value is split in proportion to what each side actually
+    contributed or received.
+    """
+    me = address
+    sym = _net(chain)["symbol"]
+    rows: List[Dict] = []
+    for tx in raw_txs(address, max_txs=_depth(limit, chain), chain=chain):
+        ts = int((tx.get("status") or {}).get("block_time") or 0)
+        h = tx.get("txid", "")
+        ins = list(_in_pairs(tx))
+        outs = list(_out_pairs(tx))
+        total_in = sum(v for _, v in ins)
+        if total_in <= 0:
+            continue
+
+        if me in (a for a, _ in ins):
+            # outgoing: our share of the inputs funds our share of each output
+            mine_in = sum(v for a, v in ins if a == me)
+            share = mine_in / total_in
+            # The chain counts a spent output at full value; the recipient gets
+            # less, because the miner fee comes out in between. Carry our share
+            # of that fee so totals can be reconciled exactly rather than
+            # hidden inside a tolerance.
+            fee_share = (total_in - sum(v for _, v in outs)) * share
+            # one row per recipient: several equal outputs to one address in one
+            # transaction would otherwise be identical rows, and the store keeps one
+            paid: Dict[str, float] = {}
+            for a, v in outs:
+                if a == me or v <= 0:
+                    continue                      # change back to self
+                paid[a] = paid.get(a, 0.0) + v
+            for a, v in paid.items():
+                rows.append({"from": me, "to": a, "value": v * share,
+                             "timestamp": ts, "hash": h, "symbol": sym,
+                             "fee_share": fee_share})
+        else:
+            # incoming: credit every funder in proportion to what it put in
+            mine_out = sum(v for a, v in outs if a == me)
+            if mine_out <= 0:
+                continue
+            merged: Dict[str, float] = {}
+            for a, v in ins:
+                merged[a] = merged.get(a, 0.0) + v
+            for a, v in merged.items():
+                rows.append({"from": a, "to": me, "value": mine_out * (v / total_in),
+                             "timestamp": ts, "hash": h, "symbol": sym})
+        if len(rows) >= limit:
+            break
+    return rows
+
+
+def cluster(address: str, chain: str = "btc") -> List[tuple]:
+    """Common-input-ownership: addresses that co-signed inputs with `address`.
+
+    Returns [(address, times_seen_together)] — likely the same owner's wallets.
+    """
+    peers: Dict[str, int] = {}
+    for tx in raw_txs(address, chain=chain):
+        ins = _in_addrs(tx)
+        if address in ins and len(set(ins)) > 1:
+            for a in set(ins):
+                if a != address:
+                    peers[a] = peers.get(a, 0) + 1
+    return sorted(peers.items(), key=lambda kv: kv[1], reverse=True)

{crypttrace-0.29.0 → crypttrace-0.31.0}/src/crypttrace/fetchers/http.py

@@ -24,6 +24,8 @@ from crypttrace import config
 MIN_INTERVAL = {
     "api.trongrid.io": 0.4,
     "mempool.space": 0.25,
+    "litecoinspace.org": 0.25,
+    "api.blockcypher.com": 0.4,       # free tier: 3 a second, ~100 an hour
     "api.mainnet-beta.solana.com": 0.3,
 }
 DEFAULT_INTERVAL = 0.25