crypttrace 0.4.0__tar.gz → 0.6.0__tar.gz

{crypttrace-0.4.0/src/crypttrace.egg-info → crypttrace-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.4.0
+Version: 0.6.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -163,6 +163,15 @@ 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.
 
+**Stolen USDT or USDC?** Check at once whether it is still sitting at the
+thief's address — Tether and Circle can freeze it there, and only there:
+`crypttrace freeze THEIR_ADDRESS --chain tron`. `investigate` does this too
+and puts it first.
+
+**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 +200,12 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Is the USDT/USDC at this address frozen by Tether/Circle — and who can freeze it?
+crypttrace freeze TADDRESS --chain tron
+
+# 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
 
@@ -268,6 +283,56 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Stablecoin freezes
+
+Tether and Circle can freeze USDT and USDC at any address. For a victim of a
+stablecoin theft that is the one lever that actually stops the money — while it
+is still there. `crypttrace freeze` reads the issuers' own contracts (USDT's
+`isBlackListed`, USDC's `isBlacklisted`, balances; token-account state on
+Solana) on Ethereum, Tron and Solana, and answers three things: how much is
+there, whether it is already frozen, and if not, who can freeze it:
+
+- **Tether** freezes USDT at the request of law enforcement, often before a
+  court case — so the route is the police, quickly
+  ([policy](https://tether.to/en/legal/?tab=law-enforcement-requests)).
+- **Circle** freezes USDC only on a legal order such as a court order
+  ([terms](https://www.circle.com/legal/usdc-terms)), which takes longer.
+
+No API key is needed: Ethereum is read through a public node (set
+`CRYPTTRACE_ETH_RPC` to use your own). `investigate` runs the check on the
+address the money went to and makes it the first step; the web UI shows it in
+the side panel; a freeze also counts in the assessment. A check that fails is
+reported as unknown, never as "not frozen". Other chains carry bridged or
+third-party versions of these tokens that the issuers cannot freeze in the same
+way, so they are not checked.
+
+### 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* —
@@ -496,10 +561,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
-- 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
   send to an exchange or attach to a police report
 - `report --pdf` for exchange and law-enforcement filings

{crypttrace-0.4.0 → crypttrace-0.6.0}/README.md

@@ -129,6 +129,15 @@ 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.
 
+**Stolen USDT or USDC?** Check at once whether it is still sitting at the
+thief's address — Tether and Circle can freeze it there, and only there:
+`crypttrace freeze THEIR_ADDRESS --chain tron`. `investigate` does this too
+and puts it first.
+
+**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 +166,12 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Is the USDT/USDC at this address frozen by Tether/Circle — and who can freeze it?
+crypttrace freeze TADDRESS --chain tron
+
+# 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
 
@@ -234,6 +249,56 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Stablecoin freezes
+
+Tether and Circle can freeze USDT and USDC at any address. For a victim of a
+stablecoin theft that is the one lever that actually stops the money — while it
+is still there. `crypttrace freeze` reads the issuers' own contracts (USDT's
+`isBlackListed`, USDC's `isBlacklisted`, balances; token-account state on
+Solana) on Ethereum, Tron and Solana, and answers three things: how much is
+there, whether it is already frozen, and if not, who can freeze it:
+
+- **Tether** freezes USDT at the request of law enforcement, often before a
+  court case — so the route is the police, quickly
+  ([policy](https://tether.to/en/legal/?tab=law-enforcement-requests)).
+- **Circle** freezes USDC only on a legal order such as a court order
+  ([terms](https://www.circle.com/legal/usdc-terms)), which takes longer.
+
+No API key is needed: Ethereum is read through a public node (set
+`CRYPTTRACE_ETH_RPC` to use your own). `investigate` runs the check on the
+address the money went to and makes it the first step; the web UI shows it in
+the side panel; a freeze also counts in the assessment. A check that fails is
+reported as unknown, never as "not frozen". Other chains carry bridged or
+third-party versions of these tokens that the issuers cannot freeze in the same
+way, so they are not checked.
+
+### 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* —
@@ -462,10 +527,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
-- 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
   send to an exchange or attach to a police report
 - `report --pdf` for exchange and law-enforcement filings

{crypttrace-0.4.0 → crypttrace-0.6.0}/src/crypttrace/__init__.py

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

{crypttrace-0.4.0 → crypttrace-0.6.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, freeze, poisoning
 from crypttrace.labels import labels
 
 
@@ -197,6 +197,54 @@ 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]}))
+
+    # --- stablecoin issuer freeze ---------------------------------------
+    frozen = [e for e in freeze.check(address, chain) if e.get("frozen")]
+    if frozen:
+        e = frozen[0]
+        signals.append(Signal(
+            name="frozen by issuer",
+            observed=f"{e['frozen_amount']:,.2f} {e['token']} at this address is frozen by {e['issuer']}",
+            implication="the issuer blocked it — usually at the request of law enforcement "
+                        "or under sanctions",
+            confidence="high", weight=40, evidence={"freezes": frozen}))
+
     # --- holding behaviour ---------------------------------------------
     if received > 0 and sent == 0 and len(inbound) >= 3:
         signals.append(Signal(
@@ -267,6 +315,19 @@ 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 "frozen by issuer" in names:
+        parts.append("Stablecoins here are frozen by their issuer, which usually follows a "
+                     "law-enforcement request or a sanctions listing.")
     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.4.0 → crypttrace-0.6.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.4.0 → crypttrace-0.6.0}/src/crypttrace/cli.py

@@ -262,6 +262,96 @@ def crosschain(
                   "not proof. Verify each candidate before relying on it.[/dim]")
 
 
+@app.command()
+def freeze(
+    address: str = typer.Argument(..., help="Address holding the USDT/USDC"),
+    chain: str = CHAIN_OPT,
+):
+    """Is USDT/USDC at this address frozen by its issuer — and who can freeze it?"""
+    from crypttrace import freeze as freeze_mod
+    entries = freeze_mod.check(address, chain)
+    if not entries:
+        console.print("[dim]USDT/USDC freezes are checked on Ethereum, Tron and Solana, where "
+                      "Tether and Circle issue them directly and can freeze them.[/dim]")
+        return
+    for e in entries:
+        head = f"[bold]{e['token']}[/bold] ({e['issuer']})"
+        if e.get("error"):
+            console.print(f"{head}: [yellow]could not be read[/yellow] — {e['error']}")
+        elif e["frozen"]:
+            console.print(f"{head}: [bold green]FROZEN[/bold green] — {e['frozen_amount']:,.2f} "
+                          f"{e['token']} cannot move" + (f"; {e['movable']:,.2f} still can"
+                                                          if e["movable"] else ""))
+        elif e["balance"]:
+            console.print(f"{head}: [bold red]{e['balance']:,.2f} {e['token']} NOT frozen[/bold red]"
+                          " — it can still be moved")
+            console.print(f"    {e['how']}")
+            console.print(f"    [dim]{e['url']}[/dim]")
+        else:
+            console.print(f"{head}: none at this address")
+    if labels.type_of(address) == "exchange":
+        console.print("\n[dim]This is an exchange's own wallet: ask the exchange, "
+                      "not the issuer.[/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"),

{crypttrace-0.4.0 → crypttrace-0.6.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.4.0 → crypttrace-0.6.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.6.0/src/crypttrace/freeze.py

@@ -0,0 +1,150 @@
+"""Stablecoin freezes — has the issuer already frozen the money, and who can?
+
+Tether (USDT) and Circle (USDC) can freeze their tokens at any address. For a
+victim that is the one mechanism that actually stops stolen stablecoins, and it
+works only while the money is still sitting there. So the useful answers are:
+how much USDT/USDC is at this address, is it already frozen, and if not, who
+can freeze it and what they need.
+
+Everything is read from the issuers' own contracts, not from third-party lists:
+
+  * Ethereum — USDT's isBlackListed / USDC's isBlacklisted and balanceOf, via
+    a public JSON-RPC node (no API key; set CRYPTTRACE_ETH_RPC to use your own);
+  * Tron     — the same calls through TronGrid;
+  * Solana   — the state of the owner's token accounts, which the issuer freezes
+    one account at a time ("frozen").
+
+Other chains carry bridged or third-party versions of these tokens that the
+issuers cannot freeze in the same way, so they are not checked.
+"""
+import os
+from typing import Dict, List
+
+import requests
+
+from crypttrace import addresses, assets
+from crypttrace.fetchers import solana
+
+ETH_RPC = os.environ.get("CRYPTTRACE_ETH_RPC", "https://ethereum-rpc.publicnode.com")
+TRON_API = "https://api.trongrid.io"
+
+# selector of the issuer's own "is this address frozen?" function
+_EVM_FROZEN = {"USDT": "0xe47d6060",   # isBlackListed(address)
+               "USDC": "0xfe575a87"}   # isBlacklisted(address)
+_BALANCE_OF = "0x70a08231"             # balanceOf(address)
+_TRON_FROZEN = {"USDT": "isBlackListed(address)", "USDC": "isBlacklisted(address)"}
+
+ISSUERS = {
+    "USDT": {"issuer": "Tether",
+             "how": ("Tether freezes USDT at the request of law enforcement, often before "
+                     "a court case. Give the police this address and ask them to request a "
+                     "freeze from Tether."),
+             "url": "https://tether.to/en/legal/?tab=law-enforcement-requests"},
+    "USDC": {"issuer": "Circle",
+             "how": ("Circle freezes USDC only on a legal order — a court order, a sanctions "
+                     "designation or a request from authorities with jurisdiction over it. "
+                     "Expect to need a court order; ask the police or a lawyer."),
+             "url": "https://www.circle.com/legal/usdc-terms"},
+}
+
+SUPPORTED = ("eth", "tron", "sol")
+
+
+class FreezeError(RuntimeError):
+    pass
+
+
+def _eth_call(contract: str, selector: str, address: str) -> int:
+    data = selector + address.lower().replace("0x", "").rjust(64, "0")
+    try:
+        r = requests.post(ETH_RPC, timeout=30, json={
+            "jsonrpc": "2.0", "id": 1, "method": "eth_call",
+            "params": [{"to": contract, "data": data}, "latest"]}).json()
+    except (requests.RequestException, ValueError) as e:
+        raise FreezeError(f"Ethereum node unreachable: {e}")
+    if "result" not in r:
+        raise FreezeError(f"Ethereum node refused the call: {r.get('error')}")
+    return int(r["result"] or "0x0", 16)
+
+
+def _tron_call(contract: str, signature: str, address: str) -> int:
+    raw = addresses._b58_decode(address)            # 0x41 + 20 bytes + checksum
+    if not raw or len(raw) != 25:
+        raise FreezeError("not a Tron address")
+    headers = {"TRON-PRO-API-KEY": os.environ["TRONGRID_API_KEY"]} \
+        if os.environ.get("TRONGRID_API_KEY") else {}
+    try:
+        r = requests.post(f"{TRON_API}/wallet/triggerconstantcontract", timeout=30,
+                          headers=headers, json={
+                              # a read-only call: the caller does not matter, and
+                              # an unactivated address can be refused as the caller
+                              "owner_address": contract, "contract_address": contract,
+                              "function_selector": signature,
+                              "parameter": raw[1:21].hex().rjust(64, "0"), "visible": True}).json()
+    except (requests.RequestException, ValueError) as e:
+        raise FreezeError(f"TronGrid unreachable: {e}")
+    out = (r.get("constant_result") or [None])[0]
+    if out is None:
+        raise FreezeError(f"TronGrid refused the call: {r.get('result') or r}")
+    return int(out or "0", 16)
+
+
+def _sol_accounts(owner: str, mint: str) -> List[dict]:
+    try:
+        r = solana._rpc("getTokenAccountsByOwner",
+                        [owner, {"mint": mint}, {"encoding": "jsonParsed"}])
+    except solana.SolanaError as e:
+        raise FreezeError(str(e))
+    out = []
+    for v in (r.get("value") if isinstance(r, dict) else r) or []:
+        info = v["account"]["data"]["parsed"]["info"]
+        out.append({"state": info.get("state"),
+                    "amount": float(info["tokenAmount"].get("uiAmountString") or 0)})
+    return out
+
+
+def _one(address: str, chain: str, symbol: str, contract: str) -> Dict:
+    if chain == "eth":
+        frozen = _eth_call(contract, _EVM_FROZEN[symbol], address) == 1
+        balance = _eth_call(contract, _BALANCE_OF, address) / 1e6
+        frozen_amount = balance if frozen else 0.0
+    elif chain == "tron":
+        frozen = _tron_call(contract, _TRON_FROZEN[symbol], address) == 1
+        balance = _tron_call(contract, "balanceOf(address)", address) / 1e6
+        frozen_amount = balance if frozen else 0.0
+    else:                                             # sol: frozen per token account
+        accts = _sol_accounts(address, contract)
+        balance = sum(a["amount"] for a in accts)
+        frozen_amount = sum(a["amount"] for a in accts if a["state"] == "frozen")
+        frozen = any(a["state"] == "frozen" for a in accts)
+    return {"token": symbol, "balance": balance, "frozen": frozen,
+            "frozen_amount": frozen_amount, "movable": balance - frozen_amount}
+
+
+def check(address: str, chain: str) -> List[Dict]:
+    """One entry per issuer stablecoin on this chain; empty where none applies.
+
+    Each entry: token, issuer, balance, frozen, frozen_amount, movable (what can
+    still leave), how (what the issuer needs), url, and error if it could not be
+    read. A failed read is reported, never guessed.
+    """
+    if chain not in SUPPORTED:
+        return []
+    from crypttrace import chains
+    out = []
+    for sym in ("usdt", "usdc"):
+        tok = assets.tokens_for(chain).get(sym)
+        if not tok:
+            continue
+        symbol = tok["symbol"]
+        entry = {"token": symbol, **ISSUERS[symbol]}
+        try:
+            if chains.OFFLINE:
+                raise FreezeError("not checked: working offline")
+            entry.update(_one(address, chain, symbol, tok["contract"]))
+        except (FreezeError, KeyError, TypeError, ValueError) as e:
+            entry.update({"balance": None, "frozen": None, "frozen_amount": None,
+                          "movable": None, "error": str(e)})
+        out.append(entry)
+    return out
+

{crypttrace-0.4.0 → crypttrace-0.6.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 freeze as freeze_mod, funder as funder_mod, offramp as offramp_mod, poisoning
 from crypttrace.labels import labels
 
 
@@ -78,6 +78,14 @@ 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"] = []
+
+    # an exchange's own wallet is the exchange's to freeze, not the issuer's
+    result["freeze"] = [] if result["type"] == "exchange" else freeze_mod.check(address, chain)
+
     result["guidance"] = build_guidance(result)
     return result
 
@@ -127,6 +135,39 @@ 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,
+        })
+
+    for e in r.get("freeze") or []:
+        if e.get("frozen"):
+            steps.insert(0, {
+                "title": f"{e['frozen_amount']:,.2f} {e['token']} here is already frozen by {e['issuer']}",
+                "body": ("It cannot be moved. Frozen funds can be returned to victims, but only "
+                         f"through a legal process: tell the police and {e['issuer']} that you "
+                         "are a victim of this address, and include this report."),
+                "urgent": True,
+            })
+        elif e.get("movable"):
+            steps.insert(0, {
+                "title": f"Ask for a freeze: {e['movable']:,.2f} {e['token']} is still here",
+                "body": (f"{e['how']} It can be moved at any moment, so this is the most "
+                         f"time-critical step. {e['issuer']}'s policy: {e['url']}"),
+                "urgent": True,
+            })
+
     # always-applicable steps
     steps.append({
         "title": "Report it to the police",

crypttrace-0.6.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.4.0 → crypttrace-0.6.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.4.0 → crypttrace-0.6.0}/src/crypttrace/web/index.html

@@ -412,10 +412,11 @@ async function inspect(addr){
   const c=chain();
   $('#side').innerHTML=`<div class="card"><div class="muted"><span class="spin"></span>Loading ${esc(short(addr))}…</div></div>`;
   try{
-    const [p,f,o]=await Promise.all([
+    const [p,f,o,fz]=await Promise.all([
       api(`/api/profile?address=${q(addr)}&chain=${c}`),
       api(`/api/funder?address=${q(addr)}&chain=${c}`).catch(()=>({hops:[]})),
-      api(`/api/offramp?address=${q(addr)}&chain=${c}`).catch(()=>({offramp:null}))
+      api(`/api/offramp?address=${q(addr)}&chain=${c}`).catch(()=>({offramp:null})),
+      api(`/api/freeze?address=${q(addr)}&chain=${c}`).catch(()=>({freeze:[]}))
     ]);
     // A label is a claim about who controls an address — show what backs it.
     let ev={known:false};
@@ -445,6 +446,19 @@ async function inspect(addr){
         <b style="color:var(--green)">${esc(o.offramp.exchange)}</b> — likely a deposit address, i.e. a
         <b>KYC identification point</b>.</div>`,'alert');
     }
+    // Tether/Circle can freeze USDT/USDC in place — the one thing that stops them
+    const fzs=(fz.freeze||[]).filter(e=>e.error||e.frozen||e.balance>0);
+    if(fzs.length&&!fz.exchange){
+      const amt=v=>Number(v).toLocaleString(undefined,{maximumFractionDigits:2});
+      const open=fzs.filter(e=>!e.frozen&&e.balance>0);
+      h+=card('Stablecoin freeze',
+        fzs.map(e=>kv(esc(e.token), e.error ? '<span class="muted">could not be read</span>'
+          : e.frozen ? `<b style="color:var(--green)">${amt(e.frozen_amount)} frozen by ${esc(e.issuer)}</b>`
+          : `<b style="color:#ff6b6b">${amt(e.balance)} not frozen</b>`)).join('')+
+        (open.length?`<div class="vfy-note">${esc(open[0].how)}
+          <a href="${safeUrl(open[0].url)}" target="_blank" rel="noopener">${esc(open[0].issuer)} policy ↗</a></div>`:''),
+        open.length?'alert':'');
+    }
     if(f.hops&&f.hops.length){
       h+=card('First-funder chain',
         f.hops.map(x=>kv('◀ funded by',

{crypttrace-0.4.0 → crypttrace-0.6.0}/src/crypttrace/webapp.py

@@ -255,6 +255,17 @@ def create_app() -> Flask:
             return jsonify({"error": str(e)}), 400
         return jsonify({"hops": hops})
 
+    @app.route("/api/freeze")
+    def api_freeze():
+        addr = request.args.get("address", "")
+        chain = request.args.get("chain", "eth")
+        bad = validate(addr, chain)
+        if bad:
+            return jsonify({"error": bad}), 400
+        from crypttrace import freeze as freeze_mod
+        return jsonify({"freeze": freeze_mod.check(addr, chain),
+                        "exchange": labels.type_of(addr) == "exchange"})
+
     @app.route("/api/offramp")
     def api_offramp():
         addr = request.args.get("address", "")

{crypttrace-0.4.0 → crypttrace-0.6.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.4.0
+Version: 0.6.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -163,6 +163,15 @@ 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.
 
+**Stolen USDT or USDC?** Check at once whether it is still sitting at the
+thief's address — Tether and Circle can freeze it there, and only there:
+`crypttrace freeze THEIR_ADDRESS --chain tron`. `investigate` does this too
+and puts it first.
+
+**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 +200,12 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Is the USDT/USDC at this address frozen by Tether/Circle — and who can freeze it?
+crypttrace freeze TADDRESS --chain tron
+
+# 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
 
@@ -268,6 +283,56 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Stablecoin freezes
+
+Tether and Circle can freeze USDT and USDC at any address. For a victim of a
+stablecoin theft that is the one lever that actually stops the money — while it
+is still there. `crypttrace freeze` reads the issuers' own contracts (USDT's
+`isBlackListed`, USDC's `isBlacklisted`, balances; token-account state on
+Solana) on Ethereum, Tron and Solana, and answers three things: how much is
+there, whether it is already frozen, and if not, who can freeze it:
+
+- **Tether** freezes USDT at the request of law enforcement, often before a
+  court case — so the route is the police, quickly
+  ([policy](https://tether.to/en/legal/?tab=law-enforcement-requests)).
+- **Circle** freezes USDC only on a legal order such as a court order
+  ([terms](https://www.circle.com/legal/usdc-terms)), which takes longer.
+
+No API key is needed: Ethereum is read through a public node (set
+`CRYPTTRACE_ETH_RPC` to use your own). `investigate` runs the check on the
+address the money went to and makes it the first step; the web UI shows it in
+the side panel; a freeze also counts in the assessment. A check that fails is
+reported as unknown, never as "not frozen". Other chains carry bridged or
+third-party versions of these tokens that the issuers cannot freeze in the same
+way, so they are not checked.
+
+### 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* —
@@ -496,10 +561,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
-- 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
   send to an exchange or attach to a police report
 - `report --pdf` for exchange and law-enforcement filings

{crypttrace-0.4.0 → crypttrace-0.6.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -10,9 +10,11 @@ src/crypttrace/bridges.py
 src/crypttrace/chains.py
 src/crypttrace/cli.py
 src/crypttrace/config.py
+src/crypttrace/freeze.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