crypttrace 0.19.0__tar.gz → 0.20.0__tar.gz

{crypttrace-0.19.0/src/crypttrace.egg-info → crypttrace-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.19.0
+Version: 0.20.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -468,6 +468,24 @@ 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
 strong lead, not proof.
 
+### EVM clustering (gas funding)
+
+```bash
+crypttrace cluster 0xADDRESS            # Ethereum; --chain bsc / polygon / … for others
+```
+
+A new EVM wallet can't send anything until someone gives it coin for gas, so its
+first funder is whoever set it up. `cluster` lists the wallets that share this
+one's first funder (*siblings*) and the wallets this one funded first
+(*children*). Siblings funded the same day with similar amounts — what a script
+spinning up wallets looks like — make a strong link. A first funding from an
+exchange, mixer, bridge or any contract (an internal transaction) links
+nothing: those fund countless unrelated wallets, and the tool says so instead
+of listing strangers.
+
+On the Ronin bridge exploiter this finds the 18 laundering wallets it set up
+with 1,000–3,300 ETH each in April 2022; from any one of them, its 17 siblings.
+
 ### Cross-chain tracing (bridges)
 
 When funds cross a bridge the trail ends at the bridge contract and reappears on
@@ -690,7 +708,6 @@ cases/             # worked investigations with their data
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
-- Entity clustering on EVM via the gas-funding heuristic
 
 ## Contributing
 

{crypttrace-0.19.0 → crypttrace-0.20.0}/README.md

@@ -434,6 +434,24 @@ 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
 strong lead, not proof.
 
+### EVM clustering (gas funding)
+
+```bash
+crypttrace cluster 0xADDRESS            # Ethereum; --chain bsc / polygon / … for others
+```
+
+A new EVM wallet can't send anything until someone gives it coin for gas, so its
+first funder is whoever set it up. `cluster` lists the wallets that share this
+one's first funder (*siblings*) and the wallets this one funded first
+(*children*). Siblings funded the same day with similar amounts — what a script
+spinning up wallets looks like — make a strong link. A first funding from an
+exchange, mixer, bridge or any contract (an internal transaction) links
+nothing: those fund countless unrelated wallets, and the tool says so instead
+of listing strangers.
+
+On the Ronin bridge exploiter this finds the 18 laundering wallets it set up
+with 1,000–3,300 ETH each in April 2022; from any one of them, its 17 siblings.
+
 ### Cross-chain tracing (bridges)
 
 When funds cross a bridge the trail ends at the bridge contract and reappears on
@@ -656,7 +674,6 @@ cases/             # worked investigations with their data
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
-- Entity clustering on EVM via the gas-funding heuristic
 
 ## Contributing
 

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/__init__.py

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

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/cli.py

@@ -775,9 +775,32 @@ def verify(
 
 @app.command()
 def cluster(
-    address: str = typer.Argument(..., help="Bitcoin address (bc1…/1…/3…)"),
+    address: str = typer.Argument(..., help="Bitcoin (bc1…/1…/3…) or EVM (0x…) address"),
+    chain: Optional[str] = typer.Option(None, "--chain", "-c",
+                                        help="btc, or an EVM chain (eth, bsc, …); guessed from the address"),
+    checks: int = typer.Option(60, "--checks", help="EVM: how many of the funder's wallets to check"),
 ):
-    """Bitcoin only: find addresses likely owned by the same person (common-input-ownership)."""
+    """Addresses likely owned by the same party.
+
+    Bitcoin: common-input ownership. EVM: gas funding — wallets whose first funding came
+    from the same wallet, and wallets this one funded first."""
+    chain = chain or ("btc" if not address.lower().startswith("0x") else "eth")
+    if chain in config.CHAINS:
+        from crypttrace import gascluster
+        try:
+            with console.status("Finding who set up this wallet and what else they set up…"):
+                res = gascluster.cluster(address, chain, max_checks=checks)
+        except (chains_mod.ChainError, etherscan.EtherscanError) as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise typer.Exit(1)
+        console.print(render.gas_cluster_report(res, chains_mod.symbol(chain)))
+        console.print("\n[dim]Heuristic: a new wallet needs gas before it can send anything, so its first "
+                      "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")
+        raise typer.Exit(1)
     from crypttrace.fetchers import bitcoin
     try:
         peers = bitcoin.cluster(address)

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/fetchers/etherscan.py

@@ -50,7 +50,11 @@ class EtherscanError(RuntimeError):
     pass
 
 
-def _call(chain: str, params: Dict[str, str], cache_age: int = 3600) -> dict:
+MIN_INTERVAL = 0.22        # the free plan allows 5 calls a second
+_last_call = 0.0
+
+
+def _call(chain: str, params: Dict[str, str], cache_age: int = 3600, _tries: int = 0) -> dict:
     if chain not in config.CHAINS:
         raise EtherscanError(f"unsupported chain '{chain}'. Options: {list(config.CHAINS)}")
     if not config.ETHERSCAN_API_KEY:
@@ -69,15 +73,20 @@ def _call(chain: str, params: Dict[str, str], cache_age: int = 3600) -> dict:
     if cached is not None:
         return cached
 
+    global _last_call
+    wait = MIN_INTERVAL - (time.time() - _last_call)
+    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():
-            time.sleep(1)
-            return _call(chain, params, cache_age)
+        if "rate limit" in str(data.get("result", "")).lower() and _tries < 4:
+            time.sleep(1 + _tries)
+            return _call(chain, params, cache_age, _tries + 1)
         # otherwise return as-is; caller handles empty
     _cache_put(key, data)
     return data

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/funder.py

@@ -37,6 +37,7 @@ def first_funder(address: str, chain: str = "eth") -> Optional[dict]:
             "value": r.get("value", 0.0),
             "timestamp": str(r.get("timestamp", 0)),
             "hash": r.get("hash", ""),
+            "internal": bool(r.get("internal")),       # EVM: sent by a contract, not a wallet
         }
     return None
 

crypttrace-0.20.0/src/crypttrace/gascluster.py

@@ -0,0 +1,87 @@
+"""EVM clustering by gas funding — wallets started by the same funder.
+
+A new EVM wallet cannot send anything until someone gives it coin for gas, so
+the first payment into a wallet says who set it up. An attacker who spins up
+many fresh wallets usually tops them all up from one place. Wallets whose
+*first* funding came from the same address — and wallets this one started —
+are therefore likely one entity.
+
+The rule only holds when the funder is a person's wallet. An exchange,
+mixer, bridge or DEX "funds" countless unrelated wallets, and so does any
+contract (a first funding that arrived as an internal transaction came from
+one) — a wallet funded like that is not linked to anything by it, and the
+result says so.
+Same-day funding with similar amounts makes a sibling link stronger: that is
+what a script setting up wallets looks like.
+"""
+from typing import Dict, List, Optional
+
+from crypttrace import chains, funder
+from crypttrace.labels import labels
+
+# a funder of this kind funds the public, not a set of its own wallets
+SERVICE_TYPES = {"exchange", "mixer", "bridge", "dex", "service"}
+DAY = 86400
+
+
+def _first(addr: str, chain: str) -> Optional[dict]:
+    try:
+        return funder.first_funder(addr, chain)
+    except chains.ChainError:
+        return None
+
+
+def _recipients(addr: str, chain: str, limit: int) -> List[dict]:
+    """Distinct addresses `addr` paid in the native coin, first payment each."""
+    seen: Dict[str, dict] = {}
+    for r in sorted(chains.transfers(addr, chain, 1000, oldest_first=True), key=lambda r: r["timestamp"]):
+        to = r.get("to")
+        if r.get("from") != addr or not to or to == addr or (r.get("value") or 0) <= 0 or r.get("kind"):
+            continue
+        seen.setdefault(to, {"address": to, "value": r["value"], "timestamp": r["timestamp"], "hash": r.get("hash", "")})
+    return list(seen.values())[:limit]
+
+
+def cluster(address: str, chain: str, max_checks: int = 60) -> Dict:
+    """Siblings (same first funder) and children (wallets this one funded first)."""
+    me = chains.norm_addr(address, chain)
+    res: Dict = {"address": me, "chain": chain, "funder": None, "siblings": [], "children": [],
+                 "note": "", "checked": 0}
+    mine = _first(me, chain)
+    if mine:
+        f = mine["funder"]
+        labels.enrich([f], chain)
+        res["funder"] = {"address": f, "label": labels.label_of(f), "type": labels.type_of(f),
+                         "value": mine["value"], "timestamp": int(mine["timestamp"]), "hash": mine["hash"]}
+        if mine.get("internal"):
+            res["note"] = ("first funded by a contract (a withdrawal from a bridge, protocol or mixer), "
+                           "not by a wallet — that links nothing")
+        elif res["funder"]["type"] in SERVICE_TYPES:
+            res["note"] = (f"first funded by {res['funder']['label'] or 'a ' + res['funder']['type']} — "
+                           "a service funds countless unrelated wallets, so this links nothing")
+        else:
+            cands = [c for c in _recipients(f, chain, 1000) if c["address"] != me]
+            # the wallets funded closest in time to this one are the likeliest siblings
+            t0 = res["funder"]["timestamp"]
+            cands.sort(key=lambda c: abs(c["timestamp"] - t0))
+            for c in cands[:max_checks]:
+                res["checked"] += 1
+                first = _first(c["address"], chain)
+                if first and first["funder"] == f and not first.get("internal"):
+                    near = abs(c["timestamp"] - t0) <= DAY
+                    similar = mine["value"] > 0 and 1 / 3 <= c["value"] / mine["value"] <= 3
+                    res["siblings"].append({**c, "same_day": near, "similar_amount": similar,
+                                            "label": labels.label_of(c["address"])})
+    else:
+        res["note"] = "no funding into this wallet was found in the history read"
+
+    for c in _recipients(me, chain, max_checks):
+        first = _first(c["address"], chain)
+        if first and first["funder"] == me and not first.get("internal"):
+            res["children"].append({**c, "label": labels.label_of(c["address"])})
+
+    same_day = [s for s in res["siblings"] if s["same_day"] and s["similar_amount"]]
+    similar = [s for s in res["siblings"] if s["similar_amount"]]
+    res["strength"] = ("strong" if len(same_day) >= 2 or len(similar) >= 5 else
+                       "moderate" if res["siblings"] or res["children"] else "none")
+    return res

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/render.py

@@ -181,6 +181,42 @@ def cluster_table(address: str, peers: list) -> Table:
     return t
 
 
+def gas_cluster_report(res: dict, symbol: str = "ETH"):
+    """EVM clustering by gas funding: the funder, siblings and children, with the caveat."""
+    from rich.console import Group
+    parts = []
+    f = res.get("funder")
+    if f:
+        who = escape(f["address"]) + (f"  [{escape(f['label'])}]" if f.get("label") else "")
+        parts.append(Text.from_markup(f"First funded by {who} — {f['value']:,.4f} {symbol} on {_ts(str(f['timestamp']))}"))
+    if res.get("note"):
+        parts.append(Text(res["note"], style="yellow"))
+    for title, rows, extra in (("Siblings — wallets this funder also set up (same first funder)", res["siblings"], True),
+                               ("Children — wallets this one set up (it was their first funder)", res["children"], False)):
+        if not rows:
+            continue
+        t = Table(title=title, header_style="bold")
+        t.add_column("Address")
+        t.add_column(f"First funding ({symbol})", justify="right")
+        t.add_column("When (UTC)")
+        if extra:
+            t.add_column("Same day")
+            t.add_column("Similar amount")
+        for r in rows:
+            cells = [addr_label(r["address"]), f"{r['value']:,.4f}", _ts(str(r["timestamp"]))]
+            if extra:
+                cells += ["yes" if r["same_day"] else "", "yes" if r["similar_amount"] else ""]
+            t.add_row(*cells)
+        parts.append(t)
+    verdict = {"strong": "[bold green]Strong link[/bold green]: one funder set up several wallets the same day, "
+                         "or many with similar amounts — what a script spinning up wallets looks like.",
+               "moderate": "[bold yellow]Possible link[/bold yellow]: shared first funder, but not the tell-tale "
+                           "pattern — check the wallets' activity before acting on it.",
+               "none": "[dim]No linked wallets found.[/dim]"}[res.get("strength", "none")]
+    parts.append(Text.from_markup(verdict))
+    return Group(*parts)
+
+
 def crosschain_tree(address: str, chain: str, results: list) -> Tree:
     """Render bridge-outs and their likely cross-chain continuations."""
     root = Tree(Text.assemble(addr_label(address), Text(f"  (source chain: {chain})")))

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace/store.py

@@ -94,6 +94,18 @@ def _conn() -> sqlite3.Connection:
         c.execute(f"DELETE FROM fetched WHERE chain IN ({marks}) AND asset=''", evm)
         c.execute("PRAGMA user_version=4")
         c.commit()
+    if c.execute("PRAGMA user_version").fetchone()[0] < 5:
+        # 0.20: remember which EVM transfers were internal (sent by a contract) — gas-funding
+        # clustering must not link wallets a contract paid; read EVM native history again
+        cols = [r[1] for r in c.execute("PRAGMA table_info(transfers)")]
+        if "internal" not in cols:
+            c.execute("ALTER TABLE transfers ADD COLUMN internal INTEGER")
+        evm = tuple(config.CHAINS)
+        marks = ",".join("?" * len(evm))
+        c.execute(f"DELETE FROM transfers WHERE chain IN ({marks}) AND (contract IS NULL OR contract='')", evm)
+        c.execute(f"DELETE FROM fetched WHERE chain IN ({marks}) AND asset=''", evm)
+        c.execute("PRAGMA user_version=5")
+        c.commit()
     return c
 
 
@@ -117,13 +129,13 @@ def save(chain: str, address: str, rows: List[dict], asset_key: str = "",
     try:
         c.executemany(
             "INSERT OR REPLACE INTO transfers"
-            "(id,chain,tx_hash,from_addr,to_addr,value,symbol,contract,ts,fee_share,memo,kind)"
-            " VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+            "(id,chain,tx_hash,from_addr,to_addr,value,symbol,contract,ts,fee_share,memo,kind,internal)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
             [(_row_id(chain, r), chain, r.get("hash", ""), r.get("from", ""),
               r.get("to", ""), float(r.get("value", 0) or 0), r.get("symbol", ""),
               r.get("contract", ""), int(r.get("timestamp", 0) or 0),
               float(r.get("fee_share", 0) or 0), r.get("memo") or None,
-              r.get("kind") or None) for r in rows])
+              r.get("kind") or None, 1 if r.get("internal") else None) for r in rows])
         c.execute("INSERT OR REPLACE INTO fetched(chain,address,asset,fetched_at,rows,complete)"
                   " VALUES (?,?,?,?,?,?)",
                   (chain, address, asset_key, int(time.time()), len(rows), int(complete)))
@@ -153,7 +165,8 @@ def is_fresh(chain: str, address: str, asset_key: str = "",
 def load(chain: str, address: str, contract: str = "", native_symbol: str = "") -> List[dict]:
     """Every stored transfer touching this address, newest first."""
     c = _conn()
-    cols = "SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share,memo,kind FROM transfers"
+    cols = ("SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share,memo,kind,internal"
+            " FROM transfers")
     try:
         if contract == "*":
             # every token, whatever its contract (address-poisoning checks need fakes too)
@@ -179,7 +192,7 @@ def load(chain: str, address: str, contract: str = "", native_symbol: str = "")
     finally:
         c.close()
     out = []
-    for f, t, v, sym, con, ts, h, fee, memo, kind in rows:
+    for f, t, v, sym, con, ts, h, fee, memo, kind, internal in rows:
         r = {"from": f, "to": t, "value": v, "symbol": sym,
              "timestamp": ts, "hash": h}
         if con:
@@ -190,6 +203,8 @@ def load(chain: str, address: str, contract: str = "", native_symbol: str = "")
             r["memo"] = memo
         if kind:
             r["kind"] = kind
+        if internal:
+            r["internal"] = True
         out.append(r)
     return out
 

{crypttrace-0.19.0 → crypttrace-0.20.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.19.0
+Version: 0.20.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -468,6 +468,24 @@ 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
 strong lead, not proof.
 
+### EVM clustering (gas funding)
+
+```bash
+crypttrace cluster 0xADDRESS            # Ethereum; --chain bsc / polygon / … for others
+```
+
+A new EVM wallet can't send anything until someone gives it coin for gas, so its
+first funder is whoever set it up. `cluster` lists the wallets that share this
+one's first funder (*siblings*) and the wallets this one funded first
+(*children*). Siblings funded the same day with similar amounts — what a script
+spinning up wallets looks like — make a strong link. A first funding from an
+exchange, mixer, bridge or any contract (an internal transaction) links
+nothing: those fund countless unrelated wallets, and the tool says so instead
+of listing strangers.
+
+On the Ronin bridge exploiter this finds the 18 laundering wallets it set up
+with 1,000–3,300 ETH each in April 2022; from any one of them, its 17 siblings.
+
 ### Cross-chain tracing (bridges)
 
 When funds cross a bridge the trail ends at the bridge contract and reappears on
@@ -690,7 +708,6 @@ cases/             # worked investigations with their data
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
-- Entity clustering on EVM via the gas-funding heuristic
 
 ## Contributing
 

{crypttrace-0.19.0 → crypttrace-0.20.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ src/crypttrace/drain.py
 src/crypttrace/evidence.py
 src/crypttrace/freeze.py
 src/crypttrace/funder.py
+src/crypttrace/gascluster.py
 src/crypttrace/investigate.py
 src/crypttrace/offramp.py
 src/crypttrace/poisoning.py