crypttrace 0.20.0__tar.gz → 0.22.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.20.0
+Version: 0.22.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -101,7 +101,7 @@ own credentials (all optional):
 
 ```bash
 export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
-export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
+export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own Solana RPC — 1,000 txs of history instead of 50
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
 export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
@@ -109,6 +109,13 @@ export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags f
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
 
+**Solana history depth.** Solana has no "transfers of an address" call: every
+transaction is a separate request, and the public endpoint sustains about one
+a second. So on it crypttrace reads the latest **50** transactions of each
+address (about a minute); with your own endpoint (a free Helius or QuickNode
+key) it reads up to **1,000**, in parallel. `CRYPTTRACE_SOLANA_MAX_TXS` sets
+the number either way.
+
 ## Supported chains
 
 | Chain | `--chain` | Data source | Model |
@@ -415,8 +422,11 @@ coin.
 then whoever funded that funder. A fresh laundering wallet must be bootstrapped
 from somewhere, and the chain frequently terminates at an exchange withdrawal —
 an identification point. A core primitive for tying "unrelated" wallets to one
-controller. (Uses external transactions; wallets first funded by an internal
-contract call need internal-tx data — a planned extension.)
+controller. On EVM chains, Tron and TON the history is read from its start, so
+the first funding of a years-old, busy wallet is found too; Bitcoin and Solana
+explorers list newest first, so there it is the earliest of the latest 200
+transfers. On EVM chains a first funding sent by a contract (a mixer or bridge
+withdrawal, an internal transaction) counts and is flagged.
 
 ### Victim lists and timing analysis
 

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

@@ -67,7 +67,7 @@ own credentials (all optional):
 
 ```bash
 export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
-export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
+export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own Solana RPC — 1,000 txs of history instead of 50
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
 export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
@@ -75,6 +75,13 @@ export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags f
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
 
+**Solana history depth.** Solana has no "transfers of an address" call: every
+transaction is a separate request, and the public endpoint sustains about one
+a second. So on it crypttrace reads the latest **50** transactions of each
+address (about a minute); with your own endpoint (a free Helius or QuickNode
+key) it reads up to **1,000**, in parallel. `CRYPTTRACE_SOLANA_MAX_TXS` sets
+the number either way.
+
 ## Supported chains
 
 | Chain | `--chain` | Data source | Model |
@@ -381,8 +388,11 @@ coin.
 then whoever funded that funder. A fresh laundering wallet must be bootstrapped
 from somewhere, and the chain frequently terminates at an exchange withdrawal —
 an identification point. A core primitive for tying "unrelated" wallets to one
-controller. (Uses external transactions; wallets first funded by an internal
-contract call need internal-tx data — a planned extension.)
+controller. On EVM chains, Tron and TON the history is read from its start, so
+the first funding of a years-old, busy wallet is found too; Bitcoin and Solana
+explorers list newest first, so there it is the earliest of the latest 200
+transfers. On EVM chains a first funding sent by a contract (a mixer or bridge
+withdrawal, an internal transaction) counts and is flagged.
 
 ### Victim lists and timing analysis
 

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

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

{crypttrace-0.20.0 → crypttrace-0.22.0}/src/crypttrace/chains.py

@@ -101,12 +101,14 @@ def balance(address: str, chain: str = "eth") -> float:
 
 # ---------- normalized row builders ----------
 
-def _evm_native(address: str, chain: str, limit: int) -> List[Dict]:
+def _evm_native(address: str, chain: str, limit: int, oldest: bool = False) -> List[Dict]:
     """The native coin moved: normal transactions plus internal ones (sent by contracts —
-    withdrawals from mixers and exchanges, ETH back from swaps). Failed calls moved nothing."""
+    withdrawals from mixers and exchanges, ETH back from swaps). Failed calls moved nothing.
+    `oldest` reads the start of the history instead of its latest part."""
     rows = []
-    calls = [(tx, False) for tx in etherscan.get_txs(address, chain, limit=limit)]
-    calls += [(tx, True) for tx in etherscan.get_internal_txs(address, chain, limit=limit)]
+    sort = "asc" if oldest else "desc"
+    calls = [(tx, False) for tx in etherscan.get_txs(address, chain, limit=limit, sort=sort)]
+    calls += [(tx, True) for tx in etherscan.get_internal_txs(address, chain, limit=limit, sort=sort)]
     for tx, internal in calls:
         if str(tx.get("isError", "0")) == "1":
             continue
@@ -175,6 +177,12 @@ def transfers(address: str, chain: str = "eth", limit: int = 1000,
 
     Served from the local store when it holds recent data for this address, so
     repeat analysis costs nothing and works offline.
+
+    `oldest_first` returns the *first* `limit` transfers of the address, oldest
+    first — what "who funded this wallet" needs. On EVM chains, Tron and TON the
+    explorers can list a history from its start, so a busy wallet's first
+    funding is found however long ago it was; on Bitcoin and Solana (newest
+    first only) it is the oldest of the latest `limit`.
     """
     check(chain)
     if chain == "ton":
@@ -189,6 +197,11 @@ def transfers(address: str, chain: str = "eth", limit: int = 1000,
     else:
         asset_key = (contract or "*").lower()
     skip_read = fresh or FORCE_FRESH
+    if oldest_first and not asset and not OFFLINE and (is_evm(chain) or chain in ("tron", "ton")):
+        # the store keeps the latest part of a history; only a complete one holds its start
+        if not (USE_STORE and not skip_read and store.is_fresh(chain, address, asset_key)
+                and store.is_complete(chain, address, asset_key)):
+            return _oldest(address, chain, limit, 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=asset_key,
@@ -239,6 +252,28 @@ def transfers(address: str, chain: str = "eth", limit: int = 1000,
     return rows
 
 
+def _oldest(address: str, chain: str, limit: int, fresh: bool) -> List[Dict]:
+    """The first `limit` native transfers of an address, oldest first.
+
+    Not written to the store: it keeps the latest part of each history, and a
+    start-of-history slice filed there would pass for it."""
+    was_fresh = _http.FRESH
+    _http.FRESH = was_fresh or fresh
+    try:
+        if is_evm(chain):
+            rows = _evm_native(address, chain, limit, oldest=True)
+        elif chain == "tron":
+            rows = tron.transfers(address, limit, oldest=True)
+        else:
+            rows = ton.transfers(address, limit, oldest=True)
+    except _UPSTREAM_ERRORS as e:
+        raise ChainError(str(e))
+    finally:
+        _http.FRESH = was_fresh
+    rows.sort(key=lambda r: r.get("timestamp", 0))
+    return rows
+
+
 def flows(address: str, chain: str, top: int, direction: str = "out",
           limit: int = 1000, asset: Optional[dict] = None):
     """Aggregated value per counterparty: [(other, total, tx_count)].

{crypttrace-0.20.0 → crypttrace-0.22.0}/src/crypttrace/fetchers/solana.py

@@ -1,9 +1,15 @@
 """Solana fetcher via public JSON-RPC — no API key required.
 
 Solana has no "list transfers for an address" endpoint: you fetch the address's
-recent signatures, then each transaction, and read the parsed instructions. That
-means one RPC call per transaction, so this fetcher is slower and intentionally
-capped. Set CRYPTTRACE_SOLANA_RPC to use your own (faster) endpoint.
+signatures (page after page), then the transactions, and read the parsed
+instructions; failed transactions are skipped — they moved nothing.
+
+The public endpoint sustains about one getTransaction call a second — faster,
+and most calls come back 429 with a 10-second wait; JSON-RPC batches fare worse.
+So on it transactions are fetched one at a time, paced to that rate, and history
+is capped at MAX_TXS = 50 transactions per address. With your own endpoint in
+CRYPTTRACE_SOLANA_RPC (e.g. a free Helius or QuickNode key) calls run in parallel
+and the cap is 1,000. CRYPTTRACE_SOLANA_MAX_TXS overrides either.
 """
 import os
 from typing import List, Dict
@@ -12,9 +18,15 @@ import requests
 
 from crypttrace import assets
 
-RPC = os.environ.get("CRYPTTRACE_SOLANA_RPC", "https://api.mainnet-beta.solana.com")
+PUBLIC_RPC = "https://api.mainnet-beta.solana.com"
+RPC = os.environ.get("CRYPTTRACE_SOLANA_RPC", PUBLIC_RPC)
 LAMPORTS = 1_000_000_000
-MAX_TXS = 25  # keep the number of RPC round-trips sane
+MAX_TXS = int(os.environ.get("CRYPTTRACE_SOLANA_MAX_TXS") or (50 if RPC == PUBLIC_RPC else 1000))
+WORKERS = 1 if RPC == PUBLIC_RPC else 8   # calls in flight; the HTTP layer spaces their starts
+if RPC == PUBLIC_RPC:
+    from crypttrace.fetchers import http as _http
+    _http.MIN_INTERVAL["api.mainnet-beta.solana.com"] = 1.1
+SIG_PAGE = 1000       # the most getSignaturesForAddress returns at once
 
 # mint -> symbol for the tokens crypttrace knows; others show as "SPL"
 _KNOWN_MINTS = {t["contract"]: t["symbol"] for t in assets.tokens_for("sol").values()}
@@ -53,15 +65,44 @@ def balance(address: str) -> float:
 
 
 def _signatures(address: str, limit: int) -> List[str]:
-    res = _rpc("getSignaturesForAddress", [address, {"limit": min(limit, MAX_TXS)}]) or []
-    return [s.get("signature") for s in res if s.get("signature")]
+    """Signatures of successful transactions, newest first, page after page."""
+    want = min(limit, MAX_TXS)
+    out: List[str] = []
+    before = None
+    while len(out) < want:
+        opts = {"limit": min(SIG_PAGE, want - len(out) + 50)}
+        if before:
+            opts["before"] = before
+        page = _rpc("getSignaturesForAddress", [address, opts]) or []
+        if not page:
+            break
+        out += [s["signature"] for s in page if s.get("signature") and s.get("err") is None]
+        before = page[-1].get("signature")
+        if len(page) < opts["limit"]:
+            break
+    return out[:want]
+
+
+def _transactions(sigs: List[str]) -> List[tuple]:
+    """(signature, transaction) for each signature — one cached call each, a few at a time."""
+    from concurrent.futures import ThreadPoolExecutor
+
+    def one(sig):
+        try:
+            return sig, _rpc("getTransaction", [sig, {"encoding": "jsonParsed",
+                                                      "maxSupportedTransactionVersion": 1}])
+        except SolanaError:
+            return sig, None
+    with ThreadPoolExecutor(max_workers=WORKERS) as pool:
+        return list(pool.map(one, sigs))
 
 
-def _parse_tx(sig: str) -> List[Dict]:
-    tx = _rpc("getTransaction", [sig, {"encoding": "jsonParsed",
-                                       "maxSupportedTransactionVersion": 0}])
-    if not tx:
-        return []
+def _parse_tx(sig: str, tx=None) -> List[Dict]:
+    if tx is None:
+        tx = _rpc("getTransaction", [sig, {"encoding": "jsonParsed",
+                                           "maxSupportedTransactionVersion": 1}])
+    if not tx or (tx.get("meta") or {}).get("err") is not None:
+        return []                               # a failed transaction moved nothing
     ts = int(tx.get("blockTime") or 0)
     rows = []
     meta = tx.get("meta") or {}
@@ -121,11 +162,9 @@ def _parse_tx(sig: str) -> List[Dict]:
 
 
 def transfers(address: str, limit: int = MAX_TXS) -> List[Dict]:
-    """Normalized transfer rows. Note: capped at MAX_TXS transactions."""
+    """Normalized transfer rows from the latest `limit` (at most MAX_TXS) successful transactions."""
     rows: List[Dict] = []
-    for sig in _signatures(address, limit):
-        try:
-            rows.extend(_parse_tx(sig))
-        except SolanaError:
-            continue
+    for sig, tx in _transactions(_signatures(address, limit)):
+        if tx:                                  # unreadable ones are skipped, not refetched
+            rows.extend(_parse_tx(sig, tx))
     return rows

{crypttrace-0.20.0 → crypttrace-0.22.0}/src/crypttrace/fetchers/ton.py

@@ -53,12 +53,14 @@ def _get(path: str, params: Optional[dict] = None, timeout: int = 30) -> dict:
     return data if isinstance(data, dict) else {}
 
 
-def _pages(path: str, key: str, params: dict, limit: int, page: int) -> List[dict]:
+def _pages(path: str, key: str, params: dict, limit: int, page: int,
+           oldest: bool = False) -> List[dict]:
     items: List[dict] = []
     offset = 0
+    sort = "asc" if oldest else "desc"
     while len(items) < limit:
         n = min(page, limit - len(items))
-        batch = _get(path, dict(params, limit=n, offset=offset, sort="desc")).get(key) or []
+        batch = _get(path, dict(params, limit=n, offset=offset, sort=sort)).get(key) or []
         items += batch
         if len(batch) < n:
             break
@@ -103,11 +105,12 @@ def balance(address: str) -> float:
     return int(d.get("balance") or 0) / NANO
 
 
-def transfers(address: str, limit: int = 1000) -> List[Dict]:
-    """TON moved in and out of `address`: its incoming message and outgoing ones."""
+def transfers(address: str, limit: int = 1000, oldest: bool = False) -> List[Dict]:
+    """TON moved in and out of `address`: its incoming message and outgoing ones;
+    from the latest transactions, or with `oldest` from the first."""
     me = _addr(address)
     rows = []
-    for tx in _pages("/transactions", "transactions", {"account": address}, limit, TX_PAGE):
+    for tx in _pages("/transactions", "transactions", {"account": address}, limit, TX_PAGE, oldest):
         ts, h = int(tx.get("now") or 0), _hex(tx.get("hash", ""))
         msgs = [tx.get("in_msg") or {}] + list(tx.get("out_msgs") or [])
         for m in msgs:

{crypttrace-0.20.0 → crypttrace-0.22.0}/src/crypttrace/fetchers/tron.py

@@ -85,13 +85,16 @@ def balance(address: str) -> float:
 PAGE = 200    # TronGrid's page size
 
 
-def _pages(path: str, limit: int) -> List[Dict]:
-    """Up to `limit` items, following TronGrid's fingerprint cursor page by page.
+def _pages(path: str, limit: int, oldest: bool = False) -> List[Dict]:
+    """Up to `limit` items, following TronGrid's fingerprint cursor page by page;
+    the latest ones, or with `oldest` the first ones.
 
     One page (200 items) used to be all we read, so a busy wallet's history
     ended a few days back and older transfers were simply invisible."""
     items: List[Dict] = []
     params = {"limit": min(limit, PAGE)}
+    if oldest:
+        params["order_by"] = "block_timestamp,asc"
     while len(items) < limit:
         d = _get(path, dict(params))
         page = d.get("data", []) or []
@@ -103,10 +106,10 @@ def _pages(path: str, limit: int) -> List[Dict]:
     return items[:limit]
 
 
-def _native(address: str, limit: int) -> List[Dict]:
+def _native(address: str, limit: int, oldest: bool = False) -> List[Dict]:
     # the endpoint lists every transaction type; TRX transfers are a subset of it
     rows = []
-    for tx in _pages(f"/v1/accounts/{address}/transactions", limit):
+    for tx in _pages(f"/v1/accounts/{address}/transactions", limit, oldest):
         try:
             c = (tx.get("raw_data", {}).get("contract") or [])[0]
             if c.get("type") != "TransferContract":
@@ -147,6 +150,7 @@ def token_transfers(address: str, limit: int = 200) -> List[Dict]:
     return rows
 
 
-def transfers(address: str, limit: int = 200) -> List[Dict]:
-    """Native TRX transfers (use token_transfers for USDT-TRC20)."""
-    return _native(address, limit)
+def transfers(address: str, limit: int = 200, oldest: bool = False) -> List[Dict]:
+    """Native TRX transfers (use token_transfers for USDT-TRC20); the latest
+    `limit`, or with `oldest` the first."""
+    return _native(address, limit, oldest)

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

@@ -7,9 +7,11 @@ funding hub or — the prize — a centralised-exchange withdrawal, which is a K
 identification point. Investigators like ZachXBT lean on this constantly to tie
 "unrelated" laundering wallets back to a single controller.
 
-Limitation: this uses normal (external) transactions. Wallets first funded by an
-internal contract call (some exchanges, disperse tools) need internal-tx data,
-a natural next extension.
+The history is read from its start on EVM chains, Tron and TON, so a busy
+wallet's first funding is found however long ago it came. Bitcoin and Solana
+explorers list newest first, so there it is the earliest of the latest 200
+transfers. On EVM chains a first funding sent by a contract (an internal
+transaction — a mixer or bridge withdrawal) counts, and is flagged.
 """
 from typing import Optional, List, Dict
 

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

@@ -106,6 +106,12 @@ def _conn() -> sqlite3.Connection:
         c.execute(f"DELETE FROM fetched WHERE chain IN ({marks}) AND asset=''", evm)
         c.execute("PRAGMA user_version=5")
         c.commit()
+    if c.execute("PRAGMA user_version").fetchone()[0] < 6:
+        # 0.21: Solana history skipped every version-1 transaction — read it again
+        c.execute("DELETE FROM transfers WHERE chain='sol'")
+        c.execute("DELETE FROM fetched WHERE chain='sol'")
+        c.execute("PRAGMA user_version=6")
+        c.commit()
     return c
 
 
@@ -162,6 +168,17 @@ def is_fresh(chain: str, address: str, asset_key: str = "",
     return a is not None and a <= max_age
 
 
+def is_complete(chain: str, address: str, asset_key: str = "") -> bool:
+    """Whether the last fetch of this address read its whole history."""
+    c = _conn()
+    try:
+        row = c.execute("SELECT complete FROM fetched WHERE chain=? AND address=? AND asset=?",
+                        (chain, address, asset_key)).fetchone()
+    finally:
+        c.close()
+    return bool(row and row[0])
+
+
 def load(chain: str, address: str, contract: str = "", native_symbol: str = "") -> List[dict]:
     """Every stored transfer touching this address, newest first."""
     c = _conn()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.20.0
+Version: 0.22.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -101,7 +101,7 @@ own credentials (all optional):
 
 ```bash
 export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
-export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
+export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own Solana RPC — 1,000 txs of history instead of 50
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
 export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
@@ -109,6 +109,13 @@ export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags f
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
 
+**Solana history depth.** Solana has no "transfers of an address" call: every
+transaction is a separate request, and the public endpoint sustains about one
+a second. So on it crypttrace reads the latest **50** transactions of each
+address (about a minute); with your own endpoint (a free Helius or QuickNode
+key) it reads up to **1,000**, in parallel. `CRYPTTRACE_SOLANA_MAX_TXS` sets
+the number either way.
+
 ## Supported chains
 
 | Chain | `--chain` | Data source | Model |
@@ -415,8 +422,11 @@ coin.
 then whoever funded that funder. A fresh laundering wallet must be bootstrapped
 from somewhere, and the chain frequently terminates at an exchange withdrawal —
 an identification point. A core primitive for tying "unrelated" wallets to one
-controller. (Uses external transactions; wallets first funded by an internal
-contract call need internal-tx data — a planned extension.)
+controller. On EVM chains, Tron and TON the history is read from its start, so
+the first funding of a years-old, busy wallet is found too; Bitcoin and Solana
+explorers list newest first, so there it is the earliest of the latest 200
+transfers. On EVM chains a first funding sent by a contract (a mixer or bridge
+withdrawal, an internal transaction) counts and is flagged.
 
 ### Victim lists and timing analysis