crypttrace 0.3.0__tar.gz → 0.5.0__tar.gz

{crypttrace-0.3.0/src/crypttrace.egg-info → crypttrace-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.3.0
+Version: 0.5.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -163,6 +163,10 @@ It is also honest with you: most stolen crypto is not recovered, and what
 matters is speed and whether the funds touch a regulated exchange. The tool
 gives you evidence and timing — it cannot move funds or name a person by itself.
 
+**Sent money to an address that looked right?** That is usually address
+poisoning — see below. Check your own wallet with
+`crypttrace poisoning YOUR_ADDRESS`.
+
 ## Commands
 
 ```bash
@@ -191,6 +195,9 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Address poisoning: look-alike addresses planted in a wallet's history
+crypttrace poisoning TADDRESS --chain tron
+
 # Is this an exchange deposit address (i.e. the cash-out point)?
 crypttrace offramp 0xADDRESS
 
@@ -216,6 +223,9 @@ crypttrace report 0xADDRESS --depth 3
 # Refresh label lists (OFAC sanctions, …)
 crypttrace update-labels
 
+# …and add OKX's ~300k signed deposit addresses (downloads ~80 MB once)
+crypttrace update-labels --okx
+
 # Launch the web UI / list chains
 crypttrace serve
 crypttrace chains
@@ -265,6 +275,33 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Address poisoning
+
+Wallets show addresses shortened — `TDDD34…rCr9Ps`. A poisoner generates an
+address with the same first and last characters and plants it in the victim's
+history with a zero-value transfer, a speck of dust or a counterfeit token. The
+next time the victim copies "the address I paid last time", they copy the
+attacker's. It is common on Tron and Ethereum, and it needs no hacking at all.
+
+`crypttrace poisoning` looks at it from both ends:
+
+- **Your wallet:** pairs of addresses in your history that share their visible
+  characters, which one arrived later with bait, and — the part that matters —
+  whether you then sent real money to it.
+- **The address your money went to:** who paid it real money right after it
+  lured them, and which address it was imitating, read from the payer's own
+  history. `investigate` and the assessment run this automatically.
+
+Tested on a documented Tron case from August 2026: from the victim's wallet it
+finds the 2,527,862 USDT sent to `TDDDHi…rCr9Ps`, a look-alike of
+`TDDD34…rCr9Ps`, an address the wallet had paid 8.4M USDT in all. From the
+attacker's side it finds the same payment and two more victims of $2.4M and
+$2.0M, each lured by a look-alike created three to twelve minutes earlier.
+
+Cheap look-alikes match only one or two characters at each end, which happens
+by chance; those are reported only when they arrived as bait after the real
+address was in use.
+
 ### Off-ramp detection
 
 Laundered funds reaching an exchange land on a per-user *deposit address* —
@@ -380,6 +417,16 @@ flag deposit addresses on those chains. Funds sent to an exchange not on that
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**Deposit addresses, labelled outright.** OKX signs every address that holds
+customer funds — over 300,000, nearly all of them per-customer deposit addresses
+— and publishes the list with its proof of reserves. `crypttrace update-labels
+--okx` downloads the latest one into `~/.crypttrace/` (about 18 MB once
+imported). With it, funds landing on an OKX deposit address are identified the
+moment they arrive, before OKX sweeps them onward — which is when a freeze
+request still has something to freeze. Without it, `offramp` only recognises a
+deposit address after it has forwarded the money. Rows without OKX's signature
+are ignored, and every address is checked before it is stored.
+
 ### Reports
 
 `report` runs the full analysis and writes to `~/crypttrace-reports/` (override
@@ -483,10 +530,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- OKX's full signed address set (~310k, mostly deposit addresses) as an
-  optional `update-labels` download, so deposits are labelled outright
-- Address-poisoning detection: flag look-alike addresses (same first and last
-  characters) in a victim's history before they copy the wrong one
 - Stablecoin freeze check: whether USDT/USDC at an address is already frozen
   by the issuer, and who to ask for a freeze
 - `report --html`: one self-contained file with the interactive graph, to

{crypttrace-0.3.0 → crypttrace-0.5.0}/README.md

@@ -129,6 +129,10 @@ It is also honest with you: most stolen crypto is not recovered, and what
 matters is speed and whether the funds touch a regulated exchange. The tool
 gives you evidence and timing — it cannot move funds or name a person by itself.
 
+**Sent money to an address that looked right?** That is usually address
+poisoning — see below. Check your own wallet with
+`crypttrace poisoning YOUR_ADDRESS`.
+
 ## Commands
 
 ```bash
@@ -157,6 +161,9 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Address poisoning: look-alike addresses planted in a wallet's history
+crypttrace poisoning TADDRESS --chain tron
+
 # Is this an exchange deposit address (i.e. the cash-out point)?
 crypttrace offramp 0xADDRESS
 
@@ -182,6 +189,9 @@ crypttrace report 0xADDRESS --depth 3
 # Refresh label lists (OFAC sanctions, …)
 crypttrace update-labels
 
+# …and add OKX's ~300k signed deposit addresses (downloads ~80 MB once)
+crypttrace update-labels --okx
+
 # Launch the web UI / list chains
 crypttrace serve
 crypttrace chains
@@ -231,6 +241,33 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Address poisoning
+
+Wallets show addresses shortened — `TDDD34…rCr9Ps`. A poisoner generates an
+address with the same first and last characters and plants it in the victim's
+history with a zero-value transfer, a speck of dust or a counterfeit token. The
+next time the victim copies "the address I paid last time", they copy the
+attacker's. It is common on Tron and Ethereum, and it needs no hacking at all.
+
+`crypttrace poisoning` looks at it from both ends:
+
+- **Your wallet:** pairs of addresses in your history that share their visible
+  characters, which one arrived later with bait, and — the part that matters —
+  whether you then sent real money to it.
+- **The address your money went to:** who paid it real money right after it
+  lured them, and which address it was imitating, read from the payer's own
+  history. `investigate` and the assessment run this automatically.
+
+Tested on a documented Tron case from August 2026: from the victim's wallet it
+finds the 2,527,862 USDT sent to `TDDDHi…rCr9Ps`, a look-alike of
+`TDDD34…rCr9Ps`, an address the wallet had paid 8.4M USDT in all. From the
+attacker's side it finds the same payment and two more victims of $2.4M and
+$2.0M, each lured by a look-alike created three to twelve minutes earlier.
+
+Cheap look-alikes match only one or two characters at each end, which happens
+by chance; those are reported only when they arrived as bait after the real
+address was in use.
+
 ### Off-ramp detection
 
 Laundered funds reaching an exchange land on a per-user *deposit address* —
@@ -346,6 +383,16 @@ flag deposit addresses on those chains. Funds sent to an exchange not on that
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**Deposit addresses, labelled outright.** OKX signs every address that holds
+customer funds — over 300,000, nearly all of them per-customer deposit addresses
+— and publishes the list with its proof of reserves. `crypttrace update-labels
+--okx` downloads the latest one into `~/.crypttrace/` (about 18 MB once
+imported). With it, funds landing on an OKX deposit address are identified the
+moment they arrive, before OKX sweeps them onward — which is when a freeze
+request still has something to freeze. Without it, `offramp` only recognises a
+deposit address after it has forwarded the money. Rows without OKX's signature
+are ignored, and every address is checked before it is stored.
+
 ### Reports
 
 `report` runs the full analysis and writes to `~/crypttrace-reports/` (override
@@ -449,10 +496,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- OKX's full signed address set (~310k, mostly deposit addresses) as an
-  optional `update-labels` download, so deposits are labelled outright
-- Address-poisoning detection: flag look-alike addresses (same first and last
-  characters) in a victim's history before they copy the wrong one
 - Stablecoin freeze check: whether USDT/USDC at an address is already frozen
   by the issuer, and who to ask for a freeze
 - `report --html`: one self-contained file with the interactive graph, to

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/__init__.py

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

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/assess.py

@@ -14,7 +14,7 @@ from collections import Counter
 from dataclasses import dataclass, field, asdict
 from typing import Dict, List, Optional
 
-from crypttrace import analysis, chains
+from crypttrace import analysis, chains, poisoning
 from crypttrace.labels import labels
 
 
@@ -197,6 +197,43 @@ def assess(address: str, chain: str = "eth", asset: Optional[dict] = None,
             confidence="medium", weight=15,
             evidence={"amount": exposure["bridge"], "bridge": named["bridge"]}))
 
+    # --- address poisoning ----------------------------------------------
+    try:
+        lured = poisoning.baited_payments(address, chain)
+        pairs = poisoning.lookalikes(address, chain)
+        spam = poisoning.campaign(address, chain)
+    except chains.ChainError:
+        lured, pairs, spam = [], [], None
+    if lured:
+        top = lured[0]
+        confirmed = [x for x in lured if x["imitates"]]
+        signals.append(Signal(
+            name="address poisoning",
+            observed=(f"{len(lured)} payer(s) sent real money right after this address lured "
+                      f"them ({top['lure']}); largest {top['paid']:.2f} {top['symbol']}"
+                      + (f", imitating {confirmed[0]['imitates']}" if confirmed else "")),
+            implication="payments made to a look-alike of an address the payer really meant — "
+                        "the victim copied this address from their own history",
+            confidence="high" if confirmed else "medium", weight=55,
+            evidence={"payments": lured[:5]}))
+    if spam:
+        signals.append(Signal(
+            name="poisoning campaign",
+            observed=(f"sent {spam['bait_transfers']} zero, dust or counterfeit transfers to "
+                      f"{spam['targets']} different wallets"),
+            implication="plants itself in strangers' histories — the address-poisoning pattern",
+            confidence="high", weight=40, evidence=spam))
+    sent_to_fake = [p for p in pairs if p["sent_to_lookalike"] > 0]
+    if sent_to_fake:
+        p = sent_to_fake[0]
+        signals.append(Signal(
+            name="paid a look-alike",
+            observed=(f"sent {p['sent_to_lookalike']:.2f} to {p['lookalike']}, which imitates "
+                      f"{p['genuine']} (same first {p['matching']['prefix']} and last "
+                      f"{p['matching']['suffix']} characters)"),
+            implication="this wallet was likely the victim of address poisoning",
+            confidence=p["confidence"], weight=0, evidence={"pairs": sent_to_fake[:5]}))
+
     # --- holding behaviour ---------------------------------------------
     if received > 0 and sent == 0 and len(inbound) >= 3:
         signals.append(Signal(
@@ -267,6 +304,16 @@ def _statement(signals: List[Signal], risk: int, confidence: str, hit) -> str:
     if "cross-chain movement" in names:
         parts.append("Some value left this chain through a bridge and would need to be "
                      "picked up on the destination network.")
+    if "address poisoning" in names:
+        parts.append("Money reached this address through address poisoning: it was made to "
+                     "look like an address the payer really meant, and planted in their "
+                     "history first.")
+    if "poisoning campaign" in names:
+        parts.append("It sends worthless transfers to many strangers, the way poisoners "
+                     "plant look-alike addresses.")
+    if "paid a look-alike" in names:
+        parts.append("This wallet sent money to a look-alike of an address it had used "
+                     "before — the signature of an address-poisoning theft.")
     if "funds held" in names:
         parts.append("The proceeds have not been spent, so intervention is still possible.")
     parts.append(f"Overall risk {risk}/100, confidence {confidence}.")

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/chains.py

@@ -151,11 +151,19 @@ def transfers(address: str, chain: str = "eth", limit: int = 1000,
     contract = asset.get("contract") if asset else None
 
     from crypttrace import store
-    asset_key = (contract or "").lower()
+    # What the stored rows are filed under: "" native, a contract, "*" every
+    # token, or "spl" on Solana, whose token rows carry no mint to tell apart.
+    if not asset:
+        asset_key = ""
+    elif chain == "sol":
+        asset_key = "spl"
+    else:
+        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 "")
+            rows = store.load(address=address, chain=chain, contract=asset_key,
+                              native_symbol=symbol(chain))
             if rows or OFFLINE:
                 rows.sort(key=lambda r: r.get("timestamp", 0), reverse=not oldest_first)
                 return rows

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/cli.py

@@ -5,10 +5,12 @@ known entities (exchanges, mixers, sanctioned wallets), and traces where the
 funds went.
 """
 import sys
+import zipfile
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
 
+import requests
 import typer
 from rich.console import Console
 
@@ -260,6 +262,64 @@ def crosschain(
                   "not proof. Verify each candidate before relying on it.[/dim]")
 
 
+@app.command()
+def poisoning(
+    address: str = typer.Argument(..., help="Your wallet, or the address the money went to"),
+    chain: str = CHAIN_OPT,
+    limit: int = typer.Option(1000, "--limit", help="How much history to read"),
+):
+    """Address poisoning: look-alike addresses planted in a wallet's history."""
+    from crypttrace import poisoning as poison_mod
+    from datetime import timezone
+    when = lambda ts: datetime.fromtimestamp(ts, timezone.utc).strftime("%Y-%m-%d %H:%M UTC") \
+        if ts else "?"
+    try:
+        pairs = poison_mod.lookalikes(address, chain, limit)
+        lured = poison_mod.baited_payments(address, chain, limit)
+        spam = poison_mod.campaign(address, chain, limit)
+    except (chains_mod.ChainError, etherscan.EtherscanError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    paid = [p for p in pairs if p["sent_to_lookalike"] > 0]
+    for p in paid:
+        console.print(f"[bold red]✗ Money went to a look-alike:[/bold red] "
+                      f"{p['sent_to_lookalike']:.4f} {'/'.join(p['symbols'])} sent to it")
+        console.print(f"    real address   {p['genuine']}")
+        console.print(f"    look-alike     {p['lookalike']}")
+        console.print(f"    same first {p['matching']['prefix']} and last "
+                      f"{p['matching']['suffix']} characters; first seen {when(p['lookalike_first_seen'])}")
+    if paid:
+        console.print("  This is address poisoning. Run [bold]crypttrace investigate "
+                      f"{paid[0]['lookalike']} --chain {chain}[/bold] to follow the money.\n")
+
+    planted = [p for p in pairs if p["sent_to_lookalike"] <= 0]
+    if planted:
+        console.print(f"[yellow]![/yellow] {len(planted)} look-alike address(es) planted in this "
+                      "history — never copy an address from here:")
+        for p in planted[:10]:
+            console.print(f"    {poison_mod.short(p['lookalike'], chain)} imitates "
+                          f"{poison_mod.short(p['genuine'], chain)}  [dim]({p['resemblance']} "
+                          f"match, {p['bait_transfers']} bait transfer(s), "
+                          f"{when(p['lookalike_first_seen'])})[/dim]")
+        console.print()
+
+    for x in lured:
+        tag = f"imitating [bold]{x['imitates']}[/bold]" if x["imitates"] \
+            else "[dim](the imitated address was not found in the payer's recent history)[/dim]"
+        console.print(f"[bold red]✗ Lured payment:[/bold red] {x['payer']} paid "
+                      f"{x['paid']:.2f} {x['symbol']} on {when(x['paid_ts'])}, after this "
+                      f"address lured it ({x['lure']}) — {tag}")
+    if spam:
+        console.print(f"[bold red]✗ Poisoning campaign:[/bold red] this address sent "
+                      f"{spam['bait_transfers']} zero/dust/counterfeit transfers to "
+                      f"{spam['targets']} different wallets.")
+
+    if not (pairs or lured or spam):
+        console.print("[green]No look-alike addresses or poisoning pattern found[/green] "
+                      f"[dim]in the last {limit} transfers.[/dim]")
+
+
 @app.command()
 def offramp(
     address: str = typer.Argument(..., help="Address to check"),
@@ -352,6 +412,17 @@ def labels_audit():
         for u in a["unsourced"][:8]:
             console.print(f"     [dim]{u['name']} ({u['type']})[/dim]")
 
+    from crypttrace.labels import bulk
+    downloaded = bulk.sets()
+    if downloaded:
+        console.print("\n  [bold]downloaded exchange address sets[/bold] (self-published, "
+                      "checked on import)")
+        for s in downloaded.values():
+            console.print(f"     {s['name']:<34} {s['count']:>8}   snapshot {s['snapshot']}")
+    else:
+        console.print("\n  [dim]No exchange address sets downloaded. "
+                      "`crypttrace update-labels --okx` adds OKX's ~300k deposit addresses.[/dim]")
+
 
 @labels_app.command("why")
 def labels_why(
@@ -393,15 +464,33 @@ def labels_check(
 
 
 @app.command(name="update-labels")
-def update_labels():
+def update_labels(
+    okx: bool = typer.Option(False, "--okx",
+                             help="Also download OKX's signed address list (~80 MB): "
+                                  "labels its ~300k deposit addresses directly"),
+    okx_file: Optional[Path] = typer.Option(None, "--okx-file",
+                                            help="Import an OKX proof-of-reserves zip you "
+                                                 "already downloaded, instead of fetching it"),
+):
     """Download the latest label lists (OFAC sanctions, etc.) into the local DB."""
+    from crypttrace.labels import bulk
     console.print("Updating label database…")
     for name, cnt, err in labels.update():
         if err:
             console.print(f"  [red]✗[/red] {name}: {err}")
         else:
             console.print(f"  [green]✓[/green] {name}: [bold]{cnt}[/bold] addresses")
-    console.print(f"[green]Done.[/green] {labels.count()} labelled addresses now loaded.")
+    if okx or okx_file:
+        try:
+            n, snap = bulk.import_okx(str(okx_file) if okx_file else None,
+                                      progress=lambda m: console.print(f"  [dim]OKX: {m}[/dim]"))
+            console.print(f"  [green]✓[/green] OKX signed addresses (snapshot {snap}): "
+                          f"[bold]{n}[/bold] addresses")
+        except (requests.RequestException, ValueError, OSError, zipfile.BadZipFile) as e:
+            console.print(f"  [red]✗[/red] OKX signed addresses: {e}")
+    console.print(f"[green]Done.[/green] {labels.count()} curated and imported labels loaded"
+                  + (f", plus {sum(s['count'] for s in bulk.sets().values())} exchange addresses"
+                     if bulk.sets() else "") + ".")
     console.print(f"[dim]Cache: {config.DATA_DIR / 'imported_labels.json'}[/dim]")
 
 

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/fetchers/solana.py

@@ -82,7 +82,8 @@ def _parse_tx(sig: str) -> List[Dict]:
                 val = 0.0
             rows.append({"from": info.get("source", "") or info.get("authority", ""),
                          "to": info.get("destination", ""), "value": val,
-                         "timestamp": ts, "hash": sig, "symbol": "SPL"})
+                         "timestamp": ts, "hash": sig, "symbol": "SPL",
+                         "contract": "spl"})   # keeps token rows apart from SOL in the store
     return rows
 
 

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/fetchers/tron.py

@@ -109,6 +109,10 @@ def token_transfers(address: str, limit: int = 200) -> List[Dict]:
     d = _get(f"/v1/accounts/{address}/transactions/trc20", {"limit": min(limit, 200)})
     rows = []
     for t in d.get("data", []) or []:
+        # the endpoint also lists Approval events, whose "value" is an allowance
+        # (often 2**256-1), not money that moved
+        if t.get("type", "Transfer") != "Transfer":
+            continue
         info = t.get("token_info") or {}
         dec = int(info.get("decimals") or 6)
         try:

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/investigate.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Dict, List, Optional
 
 from crypttrace import chains, prices, report as report_mod, trace as trace_mod
-from crypttrace import funder as funder_mod, offramp as offramp_mod
+from crypttrace import funder as funder_mod, offramp as offramp_mod, poisoning
 from crypttrace.labels import labels
 
 
@@ -78,6 +78,11 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
     except Exception:
         result["offramp"] = None
 
+    try:
+        result["poisoning"] = poisoning.baited_payments(address, chain)
+    except chains.ChainError:
+        result["poisoning"] = []
+
     result["guidance"] = build_guidance(result)
     return result
 
@@ -127,6 +132,22 @@ def build_guidance(r: dict) -> dict:
             "urgent": False,
         })
 
+    lured = r.get("poisoning") or []
+    if lured:
+        x = lured[0]
+        like = (f", made to look like {x['imitates']}, an address the sender had really "
+                f"used before" if x["imitates"] else "")
+        steps.insert(0, {
+            "title": "How it happened: address poisoning",
+            "body": (f"{x['payer']} sent {x['paid']:.2f} {x['symbol']} to this address{like}. "
+                     "Before that, this address had planted itself in that wallet's "
+                     "history, so it was copied from there by mistake. Tell the exchange "
+                     "and the police it is an address-poisoning case. Never copy an "
+                     "address from your transaction history; check your own wallet for "
+                     "other look-alikes with: crypttrace poisoning YOUR_ADDRESS"),
+            "urgent": False,
+        })
+
     # always-applicable steps
     steps.append({
         "title": "Report it to the police",

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/labels/audit.py

@@ -90,6 +90,9 @@ def evidence(address: str) -> Dict:
     # Tron/Solana keys keep their case (it carries the checksum), but callers
     # often pass addresses already lower-cased by the label layer.
     meta = raw.get(address) or {k.lower(): v for k, v in raw.items()}.get(address.lower())
+    if not meta:
+        from crypttrace.labels import bulk     # large downloaded sets (OKX, …)
+        meta = bulk.lookup(address)
     if not meta:
         return {"address": address, "known": False}
     return {

crypttrace-0.5.0/src/crypttrace/labels/bulk.py

@@ -0,0 +1,187 @@
+"""Large address sets published by exchanges themselves, kept in SQLite.
+
+OKX signs every address that holds customer funds for its proof of reserves —
+over 300,000 of them, most of them per-customer *deposit* addresses. A deposit
+address is the cash-out point: funds that land there are with an exchange that
+knows the depositor. Labelling them outright catches a deposit the moment funds
+arrive, before the exchange sweeps them onward — the window in which a freeze
+request can still work. The behavioural off-ramp heuristic only sees the sweep.
+
+That is far too many to ship in known.json or to load on every run, so the set
+is downloaded on request (`crypttrace update-labels --okx`) into a SQLite file
+and looked up one address at a time. Curated labels in known.json always win.
+"""
+import csv
+import io
+import re
+import sqlite3
+import time
+import zipfile
+from pathlib import Path
+from typing import Callable, Dict, Optional, Tuple
+
+import requests
+
+from crypttrace import addresses, config
+
+DB_PATH: Path = config.DATA_DIR / "bulk_labels.sqlite"
+
+OKX_PAGE = "https://www.okx.com/proof-of-reserves/download"
+_OKX_FILE = re.compile(r"https://static\.okx\.com/cdn/okx/por/chain/por_csv_(\d{10})_V(\d+)\.zip")
+
+# OKX network name -> crypttrace chain (only the chains crypttrace can trace)
+OKX_NETWORKS = {"BTC": "btc", "TRON": "tron", "SOL": "sol", "ETH": "eth", "BSC": "bsc",
+                "POLYGON": "polygon", "ARBITRUM": "arbitrum", "OPTIMISM": "optimism",
+                "BASE": "base"}
+
+_conn: Optional[sqlite3.Connection] = None
+
+
+def _db() -> Optional[sqlite3.Connection]:
+    """Open the store lazily; None when no set has been downloaded."""
+    global _conn
+    if _conn is None:
+        if not DB_PATH.exists():
+            return None
+        _conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+    return _conn
+
+
+def _create(c: sqlite3.Connection) -> None:
+    c.execute("CREATE TABLE IF NOT EXISTS labels (key TEXT PRIMARY KEY, chain TEXT, "
+              "set_name TEXT) WITHOUT ROWID")
+    c.execute("CREATE TABLE IF NOT EXISTS sets (set_name TEXT PRIMARY KEY, name TEXT, "
+              "type TEXT, role TEXT, source TEXT, source_kind TEXT, snapshot TEXT, "
+              "url TEXT, count INTEGER, imported_at INTEGER)")
+
+
+def lookup(address: str) -> Optional[dict]:
+    c = _db()
+    if c is None:
+        return None
+    row = c.execute("SELECT s.name, s.type, s.role, s.source, s.source_kind, s.snapshot, l.chain "
+                    "FROM labels l JOIN sets s USING (set_name) WHERE l.key = ?",
+                    (address.strip().lower(),)).fetchone()
+    if not row:
+        return None
+    name, typ, role, source, kind, snapshot, chain = row
+    return {"name": name, "type": typ, "role": role, "source": source,
+            "source_kind": kind, "added": snapshot, "chain": chain}
+
+
+def sets() -> Dict[str, dict]:
+    """What has been downloaded, for `labels audit`."""
+    c = _db()
+    if c is None:
+        return {}
+    cols = ["set_name", "name", "snapshot", "url", "count", "imported_at"]
+    return {r[0]: dict(zip(cols, r)) for r in
+            c.execute(f"SELECT {', '.join(cols)} FROM sets").fetchall()}
+
+
+def latest_okx_url(timeout: int = 30) -> str:
+    """The newest address file linked from OKX's proof-of-reserves download page."""
+    html = requests.get(OKX_PAGE, timeout=timeout, headers={"User-Agent": "Mozilla/5.0"}).text
+    found = {(m.group(1), int(m.group(2))): m.group(0) for m in _OKX_FILE.finditer(html)}
+    if not found:
+        raise ValueError("no address file found on OKX's proof-of-reserves page")
+    return found[max(found)]
+
+
+def _okx_csv_name(zip_path: Path) -> str:
+    with zipfile.ZipFile(zip_path) as z:
+        return next(n for n in z.namelist() if n.lower().endswith(".csv"))
+
+
+def _okx_rows(zip_path: Path):
+    """Yield (network, address) from OKX's file: a totals table, a blank line,
+    then one row per address with its network and ownership signature."""
+    with zipfile.ZipFile(zip_path) as z:
+        with z.open(_okx_csv_name(zip_path)) as raw:
+            f = io.TextIOWrapper(raw, encoding="utf-8-sig", newline="")
+            for line in f:
+                if line.lower().startswith("coin,type,network"):
+                    header = next(csv.reader([line]))
+                    break
+            else:
+                raise ValueError("unexpected OKX file layout: no address table")
+            idx = {h.strip().lower(): i for i, h in enumerate(header)}
+            n_i, a_i, s_i = idx["network"], idx["address"], idx["signature1"]
+            for row in csv.reader(f):
+                if len(row) > max(n_i, a_i, s_i) and row[s_i].strip():   # signed only
+                    yield row[n_i].strip().upper(), row[a_i].strip()
+
+
+def import_okx(source: Optional[str] = None,
+               progress: Optional[Callable[[str], None]] = None) -> Tuple[int, str]:
+    """Download (or read a local copy of) OKX's signed address file and store it.
+
+    Returns (addresses stored, snapshot). The previous OKX set is replaced in
+    one transaction, so a failed import leaves the old one in place.
+    """
+    say = progress or (lambda m: None)
+    url = source or latest_okx_url()
+    config.DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    if Path(url).exists():
+        zip_path, downloaded = Path(url), False
+        # the source text can end up in a report; a local path would leak the user's name
+        url = f"local copy {zip_path.name}"
+    else:
+        zip_path, downloaded = config.DATA_DIR / "okx_por.zip.part", True
+        say(f"downloading {url}")
+        with requests.get(url, stream=True, timeout=60,
+                          headers={"User-Agent": "Mozilla/5.0"}) as r:
+            r.raise_for_status()
+            with open(zip_path, "wb") as fh:
+                for chunk in r.iter_content(1 << 20):
+                    fh.write(chunk)
+
+    try:
+        # the snapshot time is in the file name: okx_por_2026090800_V1.csv
+        stamp = re.search(r"(\d{10})", _okx_csv_name(zip_path) + " " + url)
+        snapshot = (f"{stamp[1][:4]}-{stamp[1][4:6]}-{stamp[1][6:8]}" if stamp
+                    else "unknown date")
+        say("reading addresses")
+        rows, validators, bad = {}, 0, 0
+        for network, addr in _okx_rows(zip_path):
+            chain = OKX_NETWORKS.get(network)
+            if not chain:
+                continue
+            key = addr.lower()
+            if key in rows:
+                continue
+            if chain == "eth" and len(addr) == 98:
+                validators += 1       # a staking validator's public key, not an address
+                continue
+            if not addresses.validate(addr, chain)[0]:
+                bad += 1
+                continue
+            rows[key] = (key, chain, "okx")
+
+        c = sqlite3.connect(DB_PATH)
+        try:
+            _create(c)
+            with c:
+                c.execute("DELETE FROM labels WHERE set_name = 'okx'")
+                c.executemany("INSERT OR REPLACE INTO labels VALUES (?, ?, ?)", rows.values())
+                c.execute("INSERT OR REPLACE INTO sets VALUES (?,?,?,?,?,?,?,?,?,?)", (
+                    "okx", "OKX deposit address", "exchange", "deposit",
+                    f"one of the ~{len(rows) // 1000}k addresses OKX signed ('I am an OKX "
+                    f"address') in its proof-of-reserves snapshot {snapshot} ({url}); most are "
+                    "customer deposit addresses. Signature not verified by crypttrace.",
+                    "self-published", snapshot, url, len(rows), int(time.time())))
+        finally:
+            c.close()
+    finally:
+        if downloaded:
+            zip_path.unlink(missing_ok=True)
+
+    global _conn
+    if _conn is not None:
+        _conn.close()
+    _conn = None
+    say(f"stored {len(rows)} addresses"
+        + (f", skipped {validators} ETH staking validator keys" if validators else "")
+        + (f", skipped {bad} malformed" if bad else ""))
+    return len(rows), snapshot

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/labels/labels.py

@@ -17,6 +17,7 @@ from typing import Optional, Dict, List
 import requests
 
 from crypttrace import addresses, config
+from crypttrace.labels import bulk
 
 _HERE = Path(__file__).parent
 _IMPORTED = config.DATA_DIR / "imported_labels.json"
@@ -179,7 +180,13 @@ def lookup(address: str) -> Optional[dict]:
     hit = _KNOWN.get(address.lower())
     if hit:
         return hit
-    return _match_partial(address)
+    return _match_partial(address) or bulk.lookup(address)
+
+
+def is_deposit(address: str) -> bool:
+    """A per-customer deposit address rather than one of the service's own wallets."""
+    hit = lookup(address)
+    return bool(hit and hit.get("role") == "deposit")
 
 
 def company(label: str) -> str:

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/offramp.py

@@ -32,7 +32,9 @@ def _one(address: str, chain: str, threshold: float, asset: Optional[dict]) -> O
             continue
         val = r.get("value", 0) or 0
         out_total += val
-        if labels.type_of(to) == "exchange":
+        # sending *into* another customer's deposit address is a cash-out by
+        # this wallet, not evidence that this wallet is itself a deposit address
+        if labels.type_of(to) == "exchange" and not labels.is_deposit(to):
             to_exchange[to] = to_exchange.get(to, 0.0) + val
 
     if out_total <= 0 or not to_exchange:

crypttrace-0.5.0/src/crypttrace/poisoning.py

@@ -0,0 +1,262 @@
+"""Address poisoning — look-alike addresses planted in a wallet's history.
+
+Wallets show addresses shortened, "0x1234…abcd". An attacker who sees a victim
+pay 0x1234…abcd generates an address with the same first and last characters,
+then sends the victim a zero-value transfer (or a fake token) from it, so the
+look-alike sits at the top of the victim's history. The next time the victim
+copies "the address I paid last time", they copy the attacker's.
+
+Three views of the same attack:
+
+  * lookalikes(victim)  — pairs of counterparties in one wallet's history that
+    share their visible characters, which one arrived later with a zero or dust
+    transfer, and whether real money was then sent to it;
+  * baited_payments(address) — the poisoner's side, which is usually the
+    address a victim brings to an investigation: someone paid it real money
+    after exchanging a zero or dust transfer with it. On EVM chains the bait is
+    often transferFrom(victim, look-alike, 0), which records a zero transfer
+    *from the victim*, so the look-alike itself never has to send anything;
+  * campaign(address)   — an address sending zero/dust transfers to many
+    unrelated wallets (the dust-sending style, common on Tron).
+"""
+from collections import defaultdict
+from typing import Dict, List, Optional, Tuple
+
+from crypttrace import analysis, assets, chains
+
+# How closely two addresses must match at the ends (after "0x", "T", "bc1q"…).
+# Strong: rare by chance, flagged on resemblance alone. Weak: the cheap
+# look-alikes seen on Tron (first and last two characters), flagged only when
+# the look-alike arrived with bait after the genuine address was in use.
+STRONG = (3, 3, 7)          # min prefix, min suffix, min total
+WEAK = (1, 2, 3)
+# A campaign: this many distinct recipients of zero/dust transfers.
+CAMPAIGN_MIN_TARGETS = 10
+
+_ALL_TOKENS = {"contract": None, "symbol": "*"}
+
+
+def _body(address: str, chain: str) -> str:
+    """The part of an address that varies — what a shortened display shows."""
+    a = address if chains.case_sensitive(chain) else address.lower()
+    for p in ("0x", "bc1q", "bc1p", "bc1", "tb1q", "T"):
+        if a.startswith(p) and (p != "T" or chain == "tron"):
+            return a[len(p):]
+    return a
+
+
+def match_lengths(a: str, b: str, chain: str) -> Tuple[int, int]:
+    """How many leading and trailing characters two addresses share."""
+    x, y = _body(a, chain), _body(b, chain)
+    pre = 0
+    while pre < min(len(x), len(y)) and x[pre] == y[pre]:
+        pre += 1
+    suf = 0
+    while suf < min(len(x), len(y)) - pre and x[-1 - suf] == y[-1 - suf]:
+        suf += 1
+    return pre, suf
+
+
+def resemblance(a: str, b: str, chain: str) -> Optional[str]:
+    """'strong', 'weak' or None."""
+    if chains.norm_addr(a, chain) == chains.norm_addr(b, chain):
+        return None
+    pre, suf = match_lengths(a, b, chain)
+    for name, (p, s, t) in (("strong", STRONG), ("weak", WEAK)):
+        if pre >= p and suf >= s and pre + suf >= t:
+            return name
+    return None
+
+
+def _history(address: str, chain: str, limit: int) -> List[dict]:
+    """Native and every-token transfers, fakes included — they are the bait."""
+    rows = list(chains.transfers(address, chain, limit))
+    if chain != "btc":
+        try:
+            rows += chains.transfers(address, chain, limit, asset=_ALL_TOKENS)
+        except chains.ChainError:
+            pass
+    return rows
+
+
+def _is_bait(row: dict, chain: str) -> bool:
+    """A transfer whose only purpose is to appear in a history: zero value, dust,
+    or a counterfeit token wearing a real token's symbol."""
+    v = row.get("value", 0) or 0
+    if v <= 0:
+        return True
+    contract = (row.get("contract") or "").lower()
+    if not contract:
+        return v < analysis.dust_threshold(chain)
+    real = assets.tokens_for(chain).get((row.get("symbol") or "").lower())
+    if real:
+        if contract != real["contract"].lower():
+            return True                        # 'USDT' from the wrong contract
+        return real.get("stable", False) and v < 1.0
+    return False                               # unknown token, real amount: not bait
+
+
+def lookalikes(address: str, chain: str, limit: int = 1000) -> List[dict]:
+    """Look-alike counterparty pairs in `address`'s history, newest risk first.
+
+    For each pair the earlier-used address is taken as the genuine one; the
+    later one is the suspected look-alike. `sent_to_lookalike` > 0 means real
+    value went to it after it appeared — the usual way this theft completes.
+    """
+    me = chains.norm_addr(address, chain)
+    seen: Dict[str, dict] = {}
+    for r in _history(address, chain, limit):
+        frm, to = r.get("from") or "", r.get("to") or ""
+        if frm == me and to and to != me:
+            other, outgoing = to, True
+        elif to == me and frm and frm != me:
+            other, outgoing = frm, False
+        else:
+            continue
+        ts = int(r.get("timestamp") or 0)
+        c = seen.setdefault(other, {"address": other, "first_ts": ts, "rows": 0, "bait": 0,
+                                    "bait_first_ts": None, "sent_value": 0.0,
+                                    "sent_first_ts": None, "symbols": set()})
+        c["first_ts"] = min(c["first_ts"], ts) if c["first_ts"] else ts
+        c["rows"] += 1
+        c["symbols"].add(r.get("symbol") or "?")
+        if _is_bait(r, chain):
+            c["bait"] += 1
+            c["bait_first_ts"] = ts if c["bait_first_ts"] is None else min(c["bait_first_ts"], ts)
+        elif outgoing:
+            c["sent_value"] += r.get("value", 0) or 0
+            c["sent_first_ts"] = ts if c["sent_first_ts"] is None else min(c["sent_first_ts"], ts)
+
+    # only compare addresses that could match: bucket by visible ends
+    buckets = defaultdict(list)
+    for a in seen:
+        b = _body(a, chain)
+        if len(b) >= WEAK[0] + WEAK[1]:
+            buckets[(b[:WEAK[0]], b[-WEAK[1]:])].append(a)
+
+    findings = []
+    for group in buckets.values():
+        if len(group) < 2:
+            continue
+        # genuine = the one this wallet paid real value to first (else the earliest seen)
+        def rank(a):
+            c = seen[a]
+            return (c["sent_first_ts"] is None, c["sent_first_ts"] or c["first_ts"], c["first_ts"])
+        genuine = min(group, key=rank)
+        for fake in group:
+            level = resemblance(genuine, fake, chain) if fake != genuine else None
+            if not level:
+                continue
+            g, f = seen[genuine], seen[fake]
+            baited = f["bait"] > 0 and (f["bait_first_ts"] or 0) >= (g["first_ts"] or 0)
+            if level == "weak" and not baited:
+                continue            # a two-character coincidence is not evidence by itself
+            pre, suf = match_lengths(genuine, fake, chain)
+            findings.append({
+                "genuine": genuine, "lookalike": fake, "resemblance": level,
+                "confidence": "high" if level == "strong" or f["sent_value"] > 0 else "medium",
+                "matching": {"prefix": pre, "suffix": suf},
+                "lookalike_first_seen": f["first_ts"],
+                "lookalike_after_genuine_s": (f["first_ts"] - g["first_ts"])
+                if f["first_ts"] and g["first_ts"] else None,
+                "bait_transfers": f["bait"],
+                "sent_to_lookalike": f["sent_value"],
+                "sent_to_genuine": g["sent_value"],
+                "symbols": sorted(f["symbols"]),
+            })
+    findings.sort(key=lambda x: (x["sent_to_lookalike"] <= 0, -x["bait_transfers"]))
+    return findings
+
+
+def _substantial(row: dict, chain: str) -> bool:
+    """Money a victim would actually lose: native well above dust, or a real
+    stablecoin of at least $10. Excludes the few-dollar top-ups an operator
+    uses to activate a fresh look-alike."""
+    v = row.get("value", 0) or 0
+    contract = (row.get("contract") or "").lower()
+    if not contract:
+        return v >= 100 * analysis.dust_threshold(chain)
+    real = assets.tokens_for(chain).get((row.get("symbol") or "").lower())
+    return bool(real and real.get("stable") and contract == real["contract"].lower() and v >= 10)
+
+
+def baited_payments(address: str, chain: str, limit: int = 1000,
+                    confirm: int = 3) -> List[dict]:
+    """Payers who sent `address` real money right after it lured them.
+
+    The lure is either bait (a zero, dust or counterfeit transfer between the
+    two) or this address first sending the payer a small real amount — what
+    makes it appear in the payer's history. For up to `confirm` payers their
+    own history is read for the address this one imitates, which turns a
+    pattern into a specific claim.
+    """
+    me = chains.norm_addr(address, chain)
+    rows = _history(address, chain, limit)
+    first_active = min((int(r.get("timestamp") or 0) for r in rows if r.get("timestamp")), default=0)
+    lure: Dict[str, dict] = {}           # counterparty -> earliest lure
+    paid: Dict[Tuple[str, str], dict] = {}
+    for r in rows:
+        frm, to = r.get("from") or "", r.get("to") or ""
+        other = to if frm == me else frm if to == me else ""
+        if not other or other == me:
+            continue
+        ts, v = int(r.get("timestamp") or 0), r.get("value", 0) or 0
+        if _is_bait(r, chain):
+            kind = "bait"
+        elif frm == me:
+            kind = "small transfer from this address"
+        elif _substantial(r, chain):
+            p = paid.setdefault((other, r.get("symbol") or "?"), {"value": 0.0, "first_ts": ts})
+            p["value"] += v
+            p["first_ts"] = min(p["first_ts"], ts)
+            continue
+        else:
+            continue
+        l = lure.get(other)
+        if l is None or ts < l["ts"]:
+            lure[other] = {"ts": ts, "kind": kind, "value": v, "symbol": r.get("symbol")}
+    out = []
+    for (payer, symbol), p in paid.items():
+        l = lure.get(payer)
+        if not l or l["ts"] > p["first_ts"]:
+            continue
+        if l["kind"] != "bait" and l["symbol"] == symbol and l["value"] > 0.01 * p["value"]:
+            continue                      # a real exchange of similar size, not a lure
+        out.append({"payer": payer, "paid": p["value"], "symbol": symbol,
+                    "lure": l["kind"], "lure_ts": l["ts"], "paid_ts": p["first_ts"],
+                    "address_age_s": p["first_ts"] - first_active if first_active else None,
+                    "imitates": None})
+    out.sort(key=lambda x: -x["paid"])
+    for x in out[:confirm]:
+        try:
+            for pair in lookalikes(x["payer"], chain, limit):
+                if chains.norm_addr(pair["lookalike"], chain) == me:
+                    x["imitates"] = pair["genuine"]
+                    break
+        except chains.ChainError:
+            pass
+    return out
+
+
+def campaign(address: str, chain: str, limit: int = 1000) -> Optional[dict]:
+    """Does `address` send zero/dust transfers to many unrelated wallets?"""
+    me = chains.norm_addr(address, chain)
+    targets, bait, real_out = set(), 0, 0
+    for r in _history(address, chain, limit):
+        if r.get("from") != me or not r.get("to") or r.get("to") == me:
+            continue
+        if _is_bait(r, chain):
+            bait += 1
+            targets.add(r["to"])
+        else:
+            real_out += 1
+    if len(targets) < CAMPAIGN_MIN_TARGETS or bait < 2 * real_out:
+        return None
+    return {"targets": len(targets), "bait_transfers": bait, "real_transfers_out": real_out,
+            "sample": sorted(targets)[:5]}
+
+
+def short(address: str, chain: str, pre: int = 6, suf: int = 6) -> str:
+    """How a wallet would show it — the part a poisoner imitates."""
+    head = len(address) - len(_body(address, chain))
+    return address[:head + pre] + "…" + address[-suf:]

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace/store.py

@@ -114,18 +114,24 @@ 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 FROM transfers"
     try:
-        if contract:
-            q = ("SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share"
-                 " FROM transfers WHERE chain=? AND (from_addr=? OR to_addr=?)"
+        if contract == "*":
+            # every token, whatever its contract (address-poisoning checks need fakes too)
+            q = (f"{cols} WHERE chain=? AND (from_addr=? OR to_addr=?)"
+                 " AND contract IS NOT NULL AND contract!='' ORDER BY ts DESC")
+            args = (chain, address, address)
+        elif contract:
+            q = (f"{cols} WHERE chain=? AND (from_addr=? OR to_addr=?)"
                  " AND lower(contract)=lower(?) ORDER BY ts DESC")
             args = (chain, address, address, contract)
         else:
-            # native asset: rows carry no contract
-            q = ("SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share"
-                 " FROM transfers WHERE chain=? AND (from_addr=? OR to_addr=?)"
-                 " AND (contract IS NULL OR contract='') ORDER BY ts DESC")
-            args = (chain, address, address)
+            # native asset: rows carry no contract. Older stores filed Solana
+            # SPL rows without one too, so the symbol is checked as well.
+            q = (f"{cols} WHERE chain=? AND (from_addr=? OR to_addr=?)"
+                 " AND (contract IS NULL OR contract='')"
+                 + (" AND symbol=?" if native_symbol else "") + " ORDER BY ts DESC")
+            args = (chain, address, address) + ((native_symbol,) if native_symbol else ())
         rows = c.execute(q, args).fetchall()
     finally:
         c.close()

{crypttrace-0.3.0 → crypttrace-0.5.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.3.0
+Version: 0.5.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -163,6 +163,10 @@ It is also honest with you: most stolen crypto is not recovered, and what
 matters is speed and whether the funds touch a regulated exchange. The tool
 gives you evidence and timing — it cannot move funds or name a person by itself.
 
+**Sent money to an address that looked right?** That is usually address
+poisoning — see below. Check your own wallet with
+`crypttrace poisoning YOUR_ADDRESS`.
+
 ## Commands
 
 ```bash
@@ -191,6 +195,9 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Address poisoning: look-alike addresses planted in a wallet's history
+crypttrace poisoning TADDRESS --chain tron
+
 # Is this an exchange deposit address (i.e. the cash-out point)?
 crypttrace offramp 0xADDRESS
 
@@ -216,6 +223,9 @@ crypttrace report 0xADDRESS --depth 3
 # Refresh label lists (OFAC sanctions, …)
 crypttrace update-labels
 
+# …and add OKX's ~300k signed deposit addresses (downloads ~80 MB once)
+crypttrace update-labels --okx
+
 # Launch the web UI / list chains
 crypttrace serve
 crypttrace chains
@@ -265,6 +275,33 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Address poisoning
+
+Wallets show addresses shortened — `TDDD34…rCr9Ps`. A poisoner generates an
+address with the same first and last characters and plants it in the victim's
+history with a zero-value transfer, a speck of dust or a counterfeit token. The
+next time the victim copies "the address I paid last time", they copy the
+attacker's. It is common on Tron and Ethereum, and it needs no hacking at all.
+
+`crypttrace poisoning` looks at it from both ends:
+
+- **Your wallet:** pairs of addresses in your history that share their visible
+  characters, which one arrived later with bait, and — the part that matters —
+  whether you then sent real money to it.
+- **The address your money went to:** who paid it real money right after it
+  lured them, and which address it was imitating, read from the payer's own
+  history. `investigate` and the assessment run this automatically.
+
+Tested on a documented Tron case from August 2026: from the victim's wallet it
+finds the 2,527,862 USDT sent to `TDDDHi…rCr9Ps`, a look-alike of
+`TDDD34…rCr9Ps`, an address the wallet had paid 8.4M USDT in all. From the
+attacker's side it finds the same payment and two more victims of $2.4M and
+$2.0M, each lured by a look-alike created three to twelve minutes earlier.
+
+Cheap look-alikes match only one or two characters at each end, which happens
+by chance; those are reported only when they arrived as bait after the real
+address was in use.
+
 ### Off-ramp detection
 
 Laundered funds reaching an exchange land on a per-user *deposit address* —
@@ -380,6 +417,16 @@ flag deposit addresses on those chains. Funds sent to an exchange not on that
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**Deposit addresses, labelled outright.** OKX signs every address that holds
+customer funds — over 300,000, nearly all of them per-customer deposit addresses
+— and publishes the list with its proof of reserves. `crypttrace update-labels
+--okx` downloads the latest one into `~/.crypttrace/` (about 18 MB once
+imported). With it, funds landing on an OKX deposit address are identified the
+moment they arrive, before OKX sweeps them onward — which is when a freeze
+request still has something to freeze. Without it, `offramp` only recognises a
+deposit address after it has forwarded the money. Rows without OKX's signature
+are ignored, and every address is checked before it is stored.
+
 ### Reports
 
 `report` runs the full analysis and writes to `~/crypttrace-reports/` (override
@@ -483,10 +530,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- OKX's full signed address set (~310k, mostly deposit addresses) as an
-  optional `update-labels` download, so deposits are labelled outright
-- Address-poisoning detection: flag look-alike addresses (same first and last
-  characters) in a victim's history before they copy the wrong one
 - Stablecoin freeze check: whether USDT/USDC at an address is already frozen
   by the issuer, and who to ask for a freeze
 - `report --html`: one self-contained file with the interactive graph, to

{crypttrace-0.3.0 → crypttrace-0.5.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/crypttrace/config.py
 src/crypttrace/funder.py
 src/crypttrace/investigate.py
 src/crypttrace/offramp.py
+src/crypttrace/poisoning.py
 src/crypttrace/prices.py
 src/crypttrace/render.py
 src/crypttrace/report.py
@@ -35,6 +36,7 @@ src/crypttrace/fetchers/solana.py
 src/crypttrace/fetchers/tron.py
 src/crypttrace/labels/__init__.py
 src/crypttrace/labels/audit.py
+src/crypttrace/labels/bulk.py
 src/crypttrace/labels/known.json
 src/crypttrace/labels/labels.py
 src/crypttrace/labels/partial.json