crypttrace 0.23.0__tar.gz → 0.24.0__tar.gz

{crypttrace-0.23.0/src/crypttrace.egg-info → crypttrace-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.23.0
+Version: 0.24.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -79,7 +79,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). One v2 key covers all EVM chains. |
+| **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. |
 
 ```bash
@@ -120,7 +120,7 @@ the number either way.
 
 | Chain | `--chain` | Data source | Model |
 |---|---|---|---|
-| Ethereum, BSC, Polygon, Arbitrum, Optimism, Base | `eth` `bsc` `polygon` `arbitrum` `optimism` `base` | Etherscan v2 | account |
+| 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 |
 | Tron (TRX + USDT-TRC20) | `tron` | TronGrid | account |
 | Solana (SOL + SPL) | `sol` | public JSON-RPC | account |

{crypttrace-0.23.0 → crypttrace-0.24.0}/README.md

@@ -45,7 +45,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). One v2 key covers all EVM chains. |
+| **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. |
 
 ```bash
@@ -86,7 +86,7 @@ the number either way.
 
 | Chain | `--chain` | Data source | Model |
 |---|---|---|---|
-| Ethereum, BSC, Polygon, Arbitrum, Optimism, Base | `eth` `bsc` `polygon` `arbitrum` `optimism` `base` | Etherscan v2 | account |
+| 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 |
 | Tron (TRX + USDT-TRC20) | `tron` | TronGrid | account |
 | Solana (SOL + SPL) | `sol` | public JSON-RPC | account |

{crypttrace-0.23.0 → crypttrace-0.24.0}/src/crypttrace/__init__.py

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

{crypttrace-0.23.0 → crypttrace-0.24.0}/src/crypttrace/bridges.py

@@ -15,7 +15,7 @@ are reported as likely continuations with the delay and amount so the analyst
 can judge. (v1 matches native-coin value; token-bridging and recipient-address
 decoding from bridge calldata are natural extensions.)
 """
-from typing import List, Dict
+from typing import Dict, List, Optional
 
 from crypttrace.fetchers import etherscan
 from crypttrace.labels import labels
@@ -46,9 +46,13 @@ def bridge_outflows(address: str, chain: str = "eth") -> List[Dict]:
 
 
 def find_arrivals(address: str, source_chain: str, amount: float, after_ts: int,
-                  tol: float = 0.05, window_h: int = 48) -> List[Dict]:
+                  tol: float = 0.05, window_h: int = 48,
+                  unread: Optional[Dict[str, str]] = None) -> List[Dict]:
     """Search every other supported chain for an inbound transfer to `address`
-    of ~`amount` (within `tol`) within `window_h` hours after `after_ts`."""
+    of ~`amount` (within `tol`) within `window_h` hours after `after_ts`.
+
+    A chain that could not be read is no evidence of "no arrival": it goes into
+    `unread` (chain -> why) instead of silently counting as searched."""
     me = address.lower()
     hits = []
     for ch in config.CHAINS:
@@ -56,7 +60,9 @@ def find_arrivals(address: str, source_chain: str, amount: float, after_ts: int,
             continue
         try:
             txs = etherscan.get_txs(address, ch, limit=200, sort="asc")
-        except etherscan.EtherscanError:
+        except etherscan.EtherscanError as e:
+            if unread is not None:
+                unread[ch] = str(e)
             continue
         for tx in txs:
             if tx.get("to", "").lower() != me:
@@ -80,11 +86,12 @@ def find_arrivals(address: str, source_chain: str, amount: float, after_ts: int,
 
 
 def trace_cross(address: str, chain: str = "eth", tol: float = 0.05,
-                window_h: int = 48) -> List[Dict]:
-    """For each bridge-out from `address`, list likely continuations on other chains."""
+                window_h: int = 48, unread: Optional[Dict[str, str]] = None) -> List[Dict]:
+    """For each bridge-out from `address`, list likely continuations on other chains.
+    Chains that could not be searched are collected in `unread`."""
     results = []
     for out in bridge_outflows(address, chain):
         arrivals = find_arrivals(address, chain, out["amount"], out["timestamp"],
-                                 tol=tol, window_h=window_h)
+                                 tol=tol, window_h=window_h, unread=unread)
         results.append({"bridge_out": out, "arrivals": arrivals})
     return results

{crypttrace-0.23.0 → crypttrace-0.24.0}/src/crypttrace/cli.py

@@ -303,8 +303,9 @@ def crosschain(
     tol: float = typer.Option(0.05, "--tol", help="Amount tolerance (0.05 = 5%, for bridge fees)"),
 ):
     """Follow funds across bridges: find likely arrivals of the same address on other chains."""
+    unread = {}
     try:
-        results = bridges_mod.trace_cross(address, chain, tol=tol, window_h=window)
+        results = bridges_mod.trace_cross(address, chain, tol=tol, window_h=window, unread=unread)
     except etherscan.EtherscanError as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
@@ -313,6 +314,10 @@ def crosschain(
                       "address on this chain.[/dim]")
         return
     console.print(render.crosschain_tree(address, chain, results))
+    if unread:
+        console.print(f"\n[yellow]Not searched:[/yellow] {', '.join(sorted(unread))} — "
+                      "could not be read, so no arrival there is not evidence of none. "
+                      f"({next(iter(unread.values()))})")
     console.print("\n[dim]Cross-chain links are heuristic (same-address arrival by amount+time), "
                   "not proof. Verify each candidate before relying on it.[/dim]")
 
@@ -875,7 +880,8 @@ def chains():
     """List supported chains."""
     console.print("[bold]EVM[/bold] (Etherscan v2, needs ETHERSCAN_API_KEY):")
     for name, cid in config.CHAINS.items():
-        console.print(f"  {name:<10} chainid {cid}")
+        paid = "  (paid Etherscan plan only)" if name in config.PAID_PLAN_CHAINS else ""
+        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("  tron       Tron — TronGrid (TRX + USDT-TRC20)")

{crypttrace-0.23.0 → crypttrace-0.24.0}/src/crypttrace/config.py

@@ -38,5 +38,7 @@ CHAINS = {
     "optimism": 10,
     "base": 8453,
 }
+# not served on Etherscan's free plan; the API says so and crypttrace reports it
+PAID_PLAN_CHAINS = {"bsc", "optimism", "base"}
 
 WEI = 10 ** 18

{crypttrace-0.23.0 → crypttrace-0.24.0}/src/crypttrace/fetchers/etherscan.py

@@ -2,6 +2,11 @@
 
 The blockchain is public: every transaction is queryable. This module wraps the
 Etherscan API and caches responses so repeated traces don't re-hit the API.
+
+Etherscan's free plan does not cover every chain: BNB Chain, Base and Optimism
+need a paid plan. Etherscan says so in an error, which used to pass for an
+empty history — a wallet there looked untouched. Now any error Etherscan
+returns is raised (and never cached); only "No transactions found" is empty.
 """
 import json
 import sqlite3
@@ -50,6 +55,15 @@ class EtherscanError(RuntimeError):
     pass
 
 
+def _empty(data: dict) -> bool:
+    """A valid answer with nothing in it ("No transactions found") — not an error."""
+    return str(data.get("message", "")).startswith("No ") or isinstance(data.get("result"), list)
+
+
+def _failed(data: dict) -> bool:
+    return str(data.get("status")) == "0" and not _empty(data)
+
+
 MIN_INTERVAL = 0.22        # the free plan allows 5 calls a second
 _last_call = 0.0
 
@@ -70,7 +84,7 @@ def _call(chain: str, params: Dict[str, str], cache_age: int = 3600, _tries: int
     key = f"{chain}:" + "&".join(f"{k}={v}" for k, v in sorted(q.items()) if k != "apikey")
     from crypttrace.fetchers import http
     cached = None if http.FRESH else _cache_get(key, cache_age)
-    if cached is not None:
+    if cached is not None and not _failed(cached):      # older versions cached errors too
         return cached
 
     global _last_call
@@ -78,16 +92,23 @@ def _call(chain: str, params: Dict[str, str], cache_age: int = 3600, _tries: int
     if wait > 0:
         time.sleep(wait)
     _last_call = time.time()
-    resp = requests.get(config.ETHERSCAN_BASE, params=q, timeout=30)
-    resp.raise_for_status()
-    data = resp.json()
-    # status "0" with "No transactions found" is a valid empty result, not an error
-    if data.get("status") == "0" and "No transactions" not in str(data.get("message", "")):
-        # rate-limit or bad key etc.
-        if "rate limit" in str(data.get("result", "")).lower() and _tries < 4:
+    try:
+        resp = requests.get(config.ETHERSCAN_BASE, params=q, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+    except (requests.RequestException, ValueError) as e:
+        raise EtherscanError(f"Etherscan request failed: {e}")
+    if _failed(data):
+        said = str(data.get("result") or data.get("message") or "")
+        if "rate limit" in said.lower() and _tries < 4:
             time.sleep(1 + _tries)
             return _call(chain, params, cache_age, _tries + 1)
-        # otherwise return as-is; caller handles empty
+        if "not supported for this chain" in said:
+            raise EtherscanError(
+                f"Etherscan's free plan does not cover {chain}: its history needs a paid "
+                "Etherscan API plan (https://etherscan.io/apis). Without one, crypttrace "
+                f"cannot read {chain} — it is not that the wallet is empty.")
+        raise EtherscanError(f"Etherscan answered: {said}")
     _cache_put(key, data)
     return data
 

{crypttrace-0.23.0 → crypttrace-0.24.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.23.0
+Version: 0.24.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -79,7 +79,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). One v2 key covers all EVM chains. |
+| **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. |
 
 ```bash
@@ -120,7 +120,7 @@ the number either way.
 
 | Chain | `--chain` | Data source | Model |
 |---|---|---|---|
-| Ethereum, BSC, Polygon, Arbitrum, Optimism, Base | `eth` `bsc` `polygon` `arbitrum` `optimism` `base` | Etherscan v2 | account |
+| 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 |
 | Tron (TRX + USDT-TRC20) | `tron` | TronGrid | account |
 | Solana (SOL + SPL) | `sol` | public JSON-RPC | account |