crypttrace 0.21.0__tar.gz → 0.22.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.21.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
@@ -422,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.21.0 → crypttrace-0.22.0}/README.md

@@ -388,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.21.0 → crypttrace-0.22.0}/src/crypttrace/__init__.py

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

{crypttrace-0.21.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.21.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.21.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.21.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.21.0 → crypttrace-0.22.0}/src/crypttrace/store.py

@@ -168,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.21.0 → crypttrace-0.22.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.21.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
@@ -422,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