crypttrace 0.2.0__py3-none-any.whl

crypttrace/assets.py

@@ -0,0 +1,68 @@
+"""Asset registry — which token to follow, per chain.
+
+Most thefts and scams move stablecoins, not native coins, so tracing has to be
+able to follow a specific token. Contract addresses differ per chain, so the
+registry is keyed by chain. All addresses below are the official ones and were
+verified against block explorers — a wrong contract would silently trace the
+wrong asset (fake "USDT" tokens are routinely airdropped to poison wallets).
+"""
+from typing import Optional, Dict
+
+# chain -> symbol -> {contract, symbol, stable}
+TOKENS: Dict[str, Dict[str, dict]] = {
+    "eth": {
+        "usdt": {"contract": "0xdac17f958d2ee523a2206206994597c13d831ec7", "symbol": "USDT", "stable": True},
+        "usdc": {"contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "symbol": "USDC", "stable": True},
+        "dai":  {"contract": "0x6b175474e89094c44da98b954eedeac495271d0f", "symbol": "DAI", "stable": True},
+        "busd": {"contract": "0x4fabb145d64652a948d72533023f6e7a623c7c53", "symbol": "BUSD", "stable": True},
+        "weth": {"contract": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "symbol": "WETH", "stable": False},
+        "wbtc": {"contract": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", "symbol": "WBTC", "stable": False},
+    },
+    # Tron: where most everyday scams (romance / "pig butchering") move money.
+    "tron": {
+        "usdt": {"contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "symbol": "USDT", "stable": True},
+        "usdc": {"contract": "TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8", "symbol": "USDC", "stable": True},
+    },
+    "sol": {
+        "usdc": {"contract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "stable": True},
+        "usdt": {"contract": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "symbol": "USDT", "stable": True},
+    },
+}
+
+# chains where token tracing is supported at all
+TOKEN_CHAINS = set(TOKENS) | {"bsc", "polygon", "arbitrum", "optimism", "base"}
+
+
+def tokens_for(chain: str) -> Dict[str, dict]:
+    """Known token symbols for a chain (EVM sidechains reuse the eth registry
+    only for symbol names — pass an explicit contract for those)."""
+    return TOKENS.get(chain, {})
+
+
+def resolve_asset(asset: Optional[str], chain: str = "eth") -> Optional[dict]:
+    """Turn an --asset value into an asset descriptor, or None for the native coin.
+
+    Accepts 'eth'/'native'/None, a known symbol on that chain, or a raw contract
+    address (0x… on EVM, base58 on Tron/Solana).
+    """
+    if asset is None or asset.lower() in ("eth", "native", "btc", "trx", "sol", "bnb", "matic"):
+        return None
+
+    a = asset.lower()
+    known = TOKENS.get(chain, {})
+    if a in known:
+        return dict(known[a])
+
+    # raw contract address
+    if chain in ("tron", "sol"):
+        if len(asset) >= 32 and not asset.startswith("0x"):
+            return {"contract": asset, "symbol": asset[:6].upper(), "stable": False}
+    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).")
+
+    opts = ", ".join(known) or "none registered"
+    raise ValueError(f"Unknown asset '{asset}' on {chain}. Known symbols: {opts}. "
+                     f"You can also pass a contract address.")

crypttrace/bridges.py

@@ -0,0 +1,90 @@
+"""Cross-chain tracing across bridges.
+
+When funds cross a bridge, the on-chain trail on the source chain ends at the
+bridge contract, and the money reappears on another chain — there is no free,
+deterministic link between the two. This module uses a behavioural heuristic
+that catches a large share of real cases:
+
+  Launderers very often bridge to the *same address they control* on the
+  destination chain. So after spotting a transfer into a bridge, we search every
+  other supported chain for an inbound transfer to the same address, of a
+  similar amount (bridges take a fee), shortly afterwards.
+
+A match is a strong *lead*, not proof: amounts and timing can coincide. Results
+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 crypttrace.fetchers import etherscan
+from crypttrace.labels import labels
+from crypttrace import config
+
+
+def bridge_outflows(address: str, chain: str = "eth") -> List[Dict]:
+    """Native transfers from `address` into a labelled bridge contract."""
+    me = address.lower()
+    outs = []
+    for tx in etherscan.get_txs(address, chain, limit=1000):
+        if tx.get("from", "").lower() != me:
+            continue
+        to = tx.get("to", "").lower()
+        if labels.type_of(to) != "bridge":
+            continue
+        val = int(tx.get("value", 0)) / config.WEI
+        if val <= 0:
+            continue
+        outs.append({
+            "bridge": labels.label_of(to) or to,
+            "bridge_address": to,
+            "amount": val,
+            "timestamp": int(tx.get("timeStamp", "0")),
+            "hash": tx.get("hash", ""),
+        })
+    return outs
+
+
+def find_arrivals(address: str, source_chain: str, amount: float, after_ts: int,
+                  tol: float = 0.05, window_h: int = 48) -> List[Dict]:
+    """Search every other supported chain for an inbound transfer to `address`
+    of ~`amount` (within `tol`) within `window_h` hours after `after_ts`."""
+    me = address.lower()
+    hits = []
+    for ch in config.CHAINS:
+        if ch == source_chain:
+            continue
+        try:
+            txs = etherscan.get_txs(address, ch, limit=200, sort="asc")
+        except etherscan.EtherscanError:
+            continue
+        for tx in txs:
+            if tx.get("to", "").lower() != me:
+                continue
+            ts = int(tx.get("timeStamp", "0"))
+            if ts < after_ts or ts > after_ts + window_h * 3600:
+                continue
+            val = int(tx.get("value", 0)) / config.WEI
+            if val <= 0 or amount <= 0:
+                continue
+            if abs(val - amount) / amount <= tol:
+                hits.append({
+                    "chain": ch,
+                    "from": tx.get("from", "").lower(),
+                    "amount": val,
+                    "timestamp": ts,
+                    "delay_min": round((ts - after_ts) / 60, 1),
+                    "hash": tx.get("hash", ""),
+                })
+    return hits
+
+
+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."""
+    results = []
+    for out in bridge_outflows(address, chain):
+        arrivals = find_arrivals(address, chain, out["amount"], out["timestamp"],
+                                 tol=tol, window_h=window_h)
+        results.append({"bridge_out": out, "arrivals": arrivals})
+    return results

crypttrace/chains.py

@@ -0,0 +1,254 @@
+"""Unified multi-chain adapter.
+
+Every supported network — EVM (Etherscan v2), Bitcoin (UTXO, mempool.space),
+Tron (TronGrid) and Solana (JSON-RPC) — is normalized to the same transfer row:
+
+    {"from", "to", "value", "timestamp", "hash", "symbol", "contract"?}
+
+so the tracing engine, profiles and the web graph work identically everywhere.
+
+Native coins and tokens are kept strictly separate: summing 5 TRX with 250 USDT
+would be meaningless, so a caller always asks for one asset at a time.
+"""
+from typing import List, Dict, Optional
+
+from crypttrace import config
+from crypttrace.fetchers import etherscan, bitcoin, tron, solana
+
+EVM_CHAINS = set(config.CHAINS)
+NON_EVM = {"btc", "tron", "sol"}
+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"}
+
+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/{}",
+    "sol": "https://solscan.io/account/{}",
+}
+
+_UPSTREAM_ERRORS = (etherscan.EtherscanError, bitcoin.BitcoinError,
+                    tron.TronError, solana.SolanaError)
+
+
+class ChainError(RuntimeError):
+    pass
+
+
+def is_evm(chain: str) -> bool:
+    return chain in EVM_CHAINS
+
+
+def case_sensitive(chain: str) -> bool:
+    """Bitcoin/Tron/Solana use base58 — address case is significant."""
+    return chain in NON_EVM
+
+
+def norm_addr(address: str, chain: str) -> str:
+    return address if case_sensitive(chain) else address.lower()
+
+
+def symbol(chain: str) -> str:
+    return SYMBOL.get(chain, "?")
+
+
+def explorer_url(address: str, chain: str) -> str:
+    return EXPLORER.get(chain, EXPLORER["eth"]).format(address)
+
+
+def check(chain: str) -> None:
+    if chain not in ALL_CHAINS:
+        raise ChainError(f"unsupported chain '{chain}'. Options: {ALL_CHAINS}")
+
+
+def balance(address: str, chain: str = "eth") -> float:
+    check(chain)
+    try:
+        if is_evm(chain):
+            return etherscan.get_balance(address, chain)
+        if chain == "btc":
+            return bitcoin.balance(address)
+        if chain == "tron":
+            return tron.balance(address)
+        if chain == "sol":
+            return solana.balance(address)
+    except _UPSTREAM_ERRORS as e:
+        raise ChainError(str(e))
+    return 0.0
+
+
+# ---------- normalized row builders ----------
+
+def _evm_native(address: str, chain: str, limit: int) -> List[Dict]:
+    rows = []
+    for tx in etherscan.get_txs(address, chain, limit=limit):
+        try:
+            val = int(tx.get("value", 0)) / config.WEI
+        except (TypeError, ValueError):
+            val = 0.0
+        rows.append({"from": tx.get("from", "").lower(), "to": tx.get("to", "").lower(),
+                     "value": val, "timestamp": int(tx.get("timeStamp", "0") or 0),
+                     "hash": tx.get("hash", ""), "symbol": symbol(chain)})
+    return rows
+
+
+def _evm_token(address: str, chain: str, contract: Optional[str], limit: int) -> List[Dict]:
+    rows = []
+    want = (contract or "").lower()
+    for t in etherscan.get_token_txs(address, chain, limit=limit):
+        c = (t.get("contractAddress") or "").lower()
+        if want and c != want:
+            continue
+        try:
+            dec = int(t.get("tokenDecimal") or 18)
+            val = int(t.get("value", 0)) / (10 ** dec)
+        except (TypeError, ValueError):
+            continue
+        rows.append({"from": t.get("from", "").lower(), "to": t.get("to", "").lower(),
+                     "value": val, "timestamp": int(t.get("timeStamp", "0") or 0),
+                     "hash": t.get("hash", ""), "symbol": t.get("tokenSymbol", "?"),
+                     "contract": c})
+    return rows
+
+
+def _tron_token(address: str, contract: Optional[str], limit: int) -> List[Dict]:
+    rows = tron.token_transfers(address, limit)
+    if contract:
+        want = contract.lower()
+        rows = [r for r in rows if (r.get("contract") or "").lower() == want]
+    return rows
+
+
+def _sol_rows(address: str, limit: int, token: bool, contract: Optional[str]) -> List[Dict]:
+    rows = solana.transfers(address, limit)
+    if token:
+        rows = [r for r in rows if r.get("symbol") != "SOL"]
+        if contract:
+            rows = [r for r in rows if r.get("mint") in (None, contract)
+                    or (r.get("contract") or "") == contract]
+    else:
+        rows = [r for r in rows if r.get("symbol") == "SOL"]
+    return rows
+
+
+USE_STORE = True      # keep a local copy of what we fetch
+FORCE_FRESH = False   # ignore what's stored, but still store the new pull
+OFFLINE = False       # answer only from what is already stored
+
+
+def transfers(address: str, chain: str = "eth", limit: int = 1000,
+              oldest_first: bool = False, asset: Optional[dict] = None,
+              fresh: bool = False) -> List[Dict]:
+    """Normalized transfers for one asset (native by default), newest first.
+
+    Served from the local store when it holds recent data for this address, so
+    repeat analysis costs nothing and works offline.
+    """
+    check(chain)
+    contract = asset.get("contract") if asset else None
+
+    from crypttrace import store
+    asset_key = (contract or "").lower()
+    skip_read = fresh or FORCE_FRESH
+    if USE_STORE and not skip_read:
+        if OFFLINE or store.is_fresh(chain, address, asset_key):
+            rows = store.load(address=address, chain=chain, contract=contract or "")
+            if rows or OFFLINE:
+                rows.sort(key=lambda r: r.get("timestamp", 0), reverse=not oldest_first)
+                return rows
+
+    if OFFLINE:
+        # nothing stored for this address and we're not allowed to fetch
+        return []
+
+    try:
+        if is_evm(chain):
+            rows = _evm_token(address, chain, contract, limit) if asset \
+                else _evm_native(address, chain, limit)
+        elif chain == "btc":
+            if asset:
+                raise ChainError("Bitcoin has no tokens.")
+            rows = bitcoin.transfers(address, limit)
+        elif chain == "tron":
+            # keep TRX and TRC20 strictly separate
+            rows = _tron_token(address, contract, limit) if asset \
+                else tron.transfers(address, limit)
+        elif chain == "sol":
+            rows = _sol_rows(address, limit, bool(asset), contract)
+        else:
+            rows = []
+    except _UPSTREAM_ERRORS as e:
+        raise ChainError(str(e))
+
+    if USE_STORE:
+        try:
+            store.save(chain, address, rows, asset_key, complete=len(rows) < limit)
+        except Exception:
+            pass          # a store problem must never break an investigation
+
+    rows.sort(key=lambda r: r.get("timestamp", 0), reverse=not oldest_first)
+    return rows
+
+
+def flows(address: str, chain: str, top: int, direction: str = "out",
+          limit: int = 1000, asset: Optional[dict] = None):
+    """Aggregated value per counterparty: [(other, total, tx_count)].
+
+    direction='out' — where this address SENT funds (follow the money forward).
+    direction='in'  — where its funds CAME FROM (trace the source backward).
+    """
+    me = norm_addr(address, chain)
+    near, far = ("from", "to") if direction == "out" else ("to", "from")
+    agg: Dict[str, list] = {}
+    for r in transfers(address, chain, limit, asset=asset):
+        if r.get(near) != me:
+            continue
+        other = r.get(far)
+        if not other or r.get("value", 0) <= 0:
+            continue
+        rec = agg.setdefault(other, [0.0, 0])
+        rec[0] += r["value"]
+        rec[1] += 1
+    ranked = sorted(agg.items(), key=lambda kv: kv[1][0], reverse=True)
+    return [(a, v, c) for a, (v, c) in ranked][:top]
+
+
+def outflows(address: str, chain: str, top: int, limit: int = 1000, asset=None):
+    return flows(address, chain, top, "out", limit, asset)
+
+
+def inflows(address: str, chain: str, top: int, limit: int = 1000, asset=None):
+    return flows(address, chain, top, "in", limit, asset)
+
+
+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":
+        return []
+    me = norm_addr(address, chain)
+    try:
+        if is_evm(chain):
+            rows = _evm_token(address, chain, None, limit)
+        elif chain == "tron":
+            rows = _tron_token(address, None, limit)
+        else:
+            rows = _sol_rows(address, limit, True, None)
+    except _UPSTREAM_ERRORS as e:
+        raise ChainError(str(e))
+
+    agg: Dict[str, dict] = {}
+    for r in rows:
+        key = r.get("contract") or r.get("symbol", "?")
+        rec = agg.setdefault(key, {"symbol": r.get("symbol", "?"), "contract": key,
+                                   "net": 0.0, "txs": 0})
+        if r.get("to") == me:
+            rec["net"] += r.get("value", 0.0)
+        if r.get("from") == me:
+            rec["net"] -= r.get("value", 0.0)
+        rec["txs"] += 1
+    return sorted([h for h in agg.values() if h["net"] > 1e-9],
+                  key=lambda h: h["net"], reverse=True)