iwa 0.0.60__py3-none-any.whl → 0.0.61__py3-none-any.whl

iwa/core/chain/interface.py

@@ -54,9 +54,41 @@ class ChainInterface:
 
         self._initial_block = 0
         self._rotation_lock = threading.Lock()
-        self._session = requests.Session()
+        self._session = self._create_session()
+
+        # Enrich with public RPCs from ChainList (skip for Tenderly vNets)
+        if not self.is_tenderly:
+            self._enrich_rpcs_from_chainlist()
+
         self._init_web3()
 
+    def _create_session(self) -> requests.Session:
+        """Create a requests Session with bounded connection pooling.
+
+        Configures the session with limited pool sizes to prevent file
+        descriptor exhaustion during RPC rotations. Connections are reused
+        within the pool but won't accumulate unboundedly.
+        """
+        session = requests.Session()
+        # Limit pool size: we only talk to one RPC at a time, but may rotate
+        # through multiple during the session lifetime. Keep modest limits.
+        adapter = requests.adapters.HTTPAdapter(
+            pool_connections=5,  # Max different hosts to keep connections to
+            pool_maxsize=10,  # Max connections per host
+        )
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+        return session
+
+    def close(self) -> None:
+        """Close the session and release all connections.
+
+        Call this when the ChainInterface is no longer needed to ensure
+        proper cleanup of network resources.
+        """
+        if hasattr(self, "_session") and self._session:
+            self._session.close()
+
     @property
     def current_rpc(self) -> str:
         """Get the current active RPC URL."""
@@ -251,6 +283,35 @@ class ChainInterface:
         ]
         return any(signal in err_text for signal in quota_signals)
 
+    # -- ChainList enrichment ----------------------------------------------
+
+    MAX_RPCS = 10  # Cap total RPCs per chain
+
+    def _enrich_rpcs_from_chainlist(self) -> None:
+        """Add validated public RPCs from ChainList to the rotation pool."""
+        if len(self.chain.rpcs) >= self.MAX_RPCS:
+            return
+
+        try:
+            from iwa.core.chainlist import ChainlistRPC
+
+            chainlist = ChainlistRPC()
+            extra = chainlist.get_validated_rpcs(
+                self.chain.chain_id,
+                existing_rpcs=self.chain.rpcs,
+                max_results=self.MAX_RPCS - len(self.chain.rpcs),
+            )
+            if extra:
+                self.chain.rpcs.extend(extra)
+                logger.info(
+                    f"Enriched {self.chain.name} with {len(extra)} "
+                    f"ChainList RPCs (total: {len(self.chain.rpcs)})"
+                )
+        except Exception as e:
+            logger.debug(
+                f"ChainList enrichment failed for {self.chain.name}: {e}"
+            )
+
     # -- Per-RPC health tracking ------------------------------------------
 
     def _mark_rpc_backoff(self, index: int, seconds: float) -> None:

iwa/core/chain/manager.py

@@ -36,3 +36,11 @@ class ChainInterfaces:
         for name, interface in self.items():
             results[name] = interface.check_rpc_health()
         return results
+
+    def close_all(self) -> None:
+        """Close all chain interface sessions.
+
+        Call this at application shutdown to release network resources.
+        """
+        for _, interface in self.items():
+            interface.close()

iwa/core/chainlist.py

@@ -2,12 +2,158 @@
 
 import json
 import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 import requests
 
 from iwa.core.constants import CACHE_DIR
+from iwa.core.utils import configure_logger
+
+logger = configure_logger()
+
+# -- RPC probing constants --------------------------------------------------
+
+MAX_CHAINLIST_CANDIDATES = 15  # Probe at most this many candidates
+PROBE_TIMEOUT = 5.0  # Seconds per probe request
+MAX_BLOCK_LAG = 10  # Blocks behind majority → considered stale
+
+
+def _normalize_url(url: str) -> str:
+    """Normalize an RPC URL for deduplication (lowercase, strip trailing slash)."""
+    return url.rstrip("/").lower()
+
+
+def _is_template_url(url: str) -> bool:
+    """Return True if the URL contains template variables requiring an API key."""
+    return "${" in url or "{" in url
+
+
+def probe_rpc(
+    url: str,
+    timeout: float = PROBE_TIMEOUT,
+    session: Optional[requests.Session] = None,
+) -> Optional[Tuple[str, float, int]]:
+    """Probe an RPC endpoint with eth_blockNumber.
+
+    Returns ``(url, latency_ms, block_number)`` on success, or ``None``
+    if the endpoint is unreachable, slow, or returns invalid data.
+
+    Args:
+        url: The RPC endpoint URL to probe.
+        timeout: Request timeout in seconds.
+        session: Optional requests.Session for connection reuse. If None,
+                 creates a temporary session that is properly closed.
+
+    """
+    # Use provided session or create temporary one with proper cleanup
+    own_session = session is None
+    if own_session:
+        session = requests.Session()
+
+    try:
+        start = time.monotonic()
+        resp = session.post(
+            url,
+            json={"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1},
+            timeout=timeout,
+        )
+        latency_ms = (time.monotonic() - start) * 1000
+        data = resp.json()
+        block_hex = data.get("result")
+        if not block_hex or not isinstance(block_hex, str) or block_hex == "0x0":
+            return None
+        return (url, latency_ms, int(block_hex, 16))
+    except Exception:
+        return None
+    finally:
+        if own_session:
+            session.close()
+
+
+def _filter_candidates(
+    nodes: "List[RPCNode]",
+    existing_normalized: set,
+) -> List[str]:
+    """Filter ChainList nodes to usable HTTPS candidates."""
+    candidates: List[str] = []
+    for node in nodes:
+        url = node.url
+        if not url.startswith("https://"):
+            continue
+        if _is_template_url(url):
+            continue
+        if _normalize_url(url) in existing_normalized:
+            continue
+        candidates.append(url)
+        if len(candidates) >= MAX_CHAINLIST_CANDIDATES:
+            break
+    return candidates
+
+
+def _probe_candidates(
+    candidates: List[str],
+) -> List[Tuple[str, float, int]]:
+    """Probe a list of RPC URLs in parallel, returning successful results.
+
+    Uses a shared session for all probes to enable connection pooling and
+    ensure proper cleanup of all connections when probing completes.
+    """
+    results: List[Tuple[str, float, int]] = []
+    # Use a shared session with connection pooling for all probes
+    # This prevents FD leaks from individual probe connections
+    with requests.Session() as session:
+        # Configure connection pool size to match our max workers
+        adapter = requests.adapters.HTTPAdapter(
+            pool_connections=10,
+            pool_maxsize=10,
+            max_retries=0,  # No retries - we handle failure gracefully
+        )
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+
+        with ThreadPoolExecutor(max_workers=min(len(candidates), 10)) as pool:
+            futures = {
+                pool.submit(probe_rpc, url, PROBE_TIMEOUT, session): url
+                for url in candidates
+            }
+            for future in as_completed(futures, timeout=15):
+                try:
+                    result = future.result()
+                    if result is not None:
+                        results.append(result)
+                except Exception:
+                    pass
+    # Session is closed here via context manager, releasing all connections
+    return results
+
+
+def _rank_and_select(
+    results: List[Tuple[str, float, int]],
+    candidates: List[str],
+    chain_id: int,
+    max_results: int,
+) -> List[str]:
+    """Rank probed RPCs by latency, filtering stale ones."""
+    blocks = sorted(r[2] for r in results)
+    median_block = blocks[len(blocks) // 2]
+
+    valid = [
+        (url, latency)
+        for url, latency, block in results
+        if median_block - block <= MAX_BLOCK_LAG
+    ]
+    valid.sort(key=lambda x: x[1])
+
+    selected = [url for url, _ in valid[:max_results]]
+    if selected:
+        logger.info(
+            f"ChainList: validated {len(selected)}/{len(candidates)} "
+            f"candidates for chain {chain_id} "
+            f"(median block: {median_block})"
+        )
+    return selected
 
 
 @dataclass
@@ -50,11 +196,12 @@ class ChainlistRPC:
             except Exception as e:
                 print(f"Error reading Chainlist cache: {e}")
 
-        # 2. Fetch from remote
+        # 2. Fetch from remote (use session context for proper cleanup)
         try:
-            response = requests.get(self.URL, timeout=10)
-            response.raise_for_status()
-            self._data = response.json()
+            with requests.Session() as session:
+                response = session.get(self.URL, timeout=10)
+                response.raise_for_status()
+                self._data = response.json()
 
             # 3. Update local cache
             if self._data:
@@ -119,3 +266,34 @@ class ChainlistRPC:
             for node in rpcs
             if node.url.startswith("wss://") or node.url.startswith("ws://")
         ]
+
+    def get_validated_rpcs(
+        self,
+        chain_id: int,
+        existing_rpcs: List[str],
+        max_results: int = 5,
+    ) -> List[str]:
+        """Return ChainList RPCs filtered, probed, and sorted by quality.
+
+        1. Fetch HTTPS RPCs from ChainList for *chain_id*.
+        2. Filter out template URLs, duplicates of *existing_rpcs*, and
+           websocket endpoints.
+        3. Probe the top candidates in parallel with ``eth_blockNumber``.
+        4. Discard RPCs that are stale (block number lagging behind majority).
+        5. Return up to *max_results* URLs sorted by latency (fastest first).
+        """
+        nodes = self.get_rpcs(chain_id)
+        if not nodes:
+            return []
+
+        existing_normalized = {_normalize_url(u) for u in existing_rpcs}
+        candidates = _filter_candidates(nodes, existing_normalized)
+        if not candidates:
+            return []
+
+        results = _probe_candidates(candidates)
+        if not results:
+            return []
+
+        selected = _rank_and_select(results, candidates, chain_id, max_results)
+        return selected

{iwa-0.0.60.dist-info → iwa-0.0.61.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iwa
-Version: 0.0.60
+Version: 0.0.61
 Summary: A secure, modular, and plugin-based framework for crypto agents and ops
 Requires-Python: <4.0,>=3.12
 Description-Content-Type: text/markdown

{iwa-0.0.60.dist-info → iwa-0.0.61.dist-info}/RECORD

@@ -1,7 +1,7 @@
 iwa/__init__.py,sha256=vu12UytYNREtMRvIWp6AfV1GgUe53XWwCMhYyqKAPgo,19
 iwa/__main__.py,sha256=eJU5Uxeu9Y7shWg5dt5Mcq0pMC4wFVNWjeYGKSf4Apw,88
 iwa/core/__init__.py,sha256=GJv4LJOXeZ3hgGvbt5I6omkoFkP2A9qhHjpDlOep9ik,24
-iwa/core/chainlist.py,sha256=bcbv1P9R-RiCghullse0qVmqkTs1l4_ZOkOHZ0MzjtI,4097
+iwa/core/chainlist.py,sha256=OraylOuaGXR65p7HNkEssjQzQe5as1WxZoRlxQFYVho,10187
 iwa/core/cli.py,sha256=Qo0SXvgKFOd3Ru-LnX5zEXIaR7r3uwYoqwPhVShEqiQ,8315
 iwa/core/constants.py,sha256=_CYUVQpR--dRPuxotsmbzQE-22y61tlnjUD7IhlvVVA,997
 iwa/core/db.py,sha256=WI-mP0tQAmwFPeEi9w7RCa_Mcf_zBfd_7JcbHJwU1aU,10377
@@ -23,8 +23,8 @@ iwa/core/utils.py,sha256=FTYpIdQ1wnugD4lYU4TQ7d7_TlDs4CTUIhEpHGEJph4,4281
 iwa/core/wallet.py,sha256=xSGFOK5Wzh-ctLGhBMK1BySlXN0Ircpztyk1an21QiQ,13129
 iwa/core/chain/__init__.py,sha256=XJMmn0ed-_aVkY2iEMKpuTxPgIKBd41dexSVmEZTa-o,1604
 iwa/core/chain/errors.py,sha256=9SEbhxZ-qASPkzt-DoI51qq0GRJVqRgqgL720gO7a64,1275
-iwa/core/chain/interface.py,sha256=ww779Wek8qeIxu5t0v3hcmwXq7dMaxp0TjpW4Eikg8Y,25924
-iwa/core/chain/manager.py,sha256=cFEzh6pK5OyVhjhpeMAqhc9RnRDQR1DjIGiGKp-FXBI,1159
+iwa/core/chain/interface.py,sha256=4VA2qRUZ40J38l7edaeGTlOnwcXLxZxFPo1Flitzl3M,28270
+iwa/core/chain/manager.py,sha256=XHwn7ciapFCZVk0rPSJopUqM5Wu3Kpp6XrenkgTE1HA,1397
 iwa/core/chain/models.py,sha256=WUhAighMKcFdbAUkPU_3dkGbWyAUpRJqXMHLcWFC1xg,5261
 iwa/core/chain/rate_limiter.py,sha256=Ps1MrR4HHtylxgUAawe6DoC9tuqKagjQdKulqcJD2gs,9093
 iwa/core/contracts/__init__.py,sha256=P5GFY_pnuI02teqVY2U0t98bn1_SSPAbcAzRMpCdTi4,34
@@ -166,7 +166,7 @@ iwa/web/tests/test_web_endpoints.py,sha256=vA25YghHNB23sbmhD4ciesn_f_okSq0tjlkrS
 iwa/web/tests/test_web_olas.py,sha256=0CVSsrncOeJ3x0ECV7mVLQV_CXZRrOqGiVjgLIi6hZ8,16308
 iwa/web/tests/test_web_swap.py,sha256=7A4gBJFL01kIXPtW1E1J17SCsVc_0DmUn-R8kKrnnVA,2974
 iwa/web/tests/test_web_swap_coverage.py,sha256=zGNrzlhZ_vWDCvWmLcoUwFgqxnrp_ACbo49AtWBS_Kw,5584
-iwa-0.0.60.dist-info/licenses/LICENSE,sha256=eIubm_IlBHPYRQlLNZKbBNKhJUUP3JH0A2miZUhAVfI,1078
+iwa-0.0.61.dist-info/licenses/LICENSE,sha256=eIubm_IlBHPYRQlLNZKbBNKhJUUP3JH0A2miZUhAVfI,1078
 tests/legacy_cow.py,sha256=oOkZvIxL70ReEoD9oHQbOD5GpjIr6AGNHcOCgfPlerU,8389
 tests/legacy_safe.py,sha256=AssM2g13E74dNGODu_H0Q0y412lgqsrYnEzI97nm_Ts,2972
 tests/legacy_transaction_retry_logic.py,sha256=D9RqZ7DBu61Xr2djBAodU2p9UE939LL-DnQXswX5iQk,1497
@@ -178,6 +178,7 @@ tests/test_balance_service.py,sha256=wcuCOVszxPy8nPkldAVcEiygcOK3BuQt797fqAJvbp4
 tests/test_chain.py,sha256=VZoidSojWyt1y4mQdZdoZsjuuDZjLC6neTC-2SF_Q7I,13957
 tests/test_chain_interface.py,sha256=bgqGM8wJGZjc-BOX6i0K4sh06KCJl-6UAvrwl8x24lA,8324
 tests/test_chain_interface_coverage.py,sha256=fvrVvw8-DMwdsSFKQHUhpbfutrVRxnnTc-tjB7Bb-jo,3327
+tests/test_chainlist_enrichment.py,sha256=P7WctRhZ0sBTlsHsJXj5hv97CzgaEH556Nir2J8vWpg,12928
 tests/test_cli.py,sha256=Pl4RC2xp1omiJUnL3Dza6pCmIoO29LJ0vGw33_ZpT5c,3980
 tests/test_contract.py,sha256=tApHAxsfKGawYJWA9PhTNrOZUE0VVAq79ruIe3KxeWY,14412
 tests/test_db.py,sha256=dmbrupj0qlUeiiycZ2mzMFjf7HrDa6tcqMPY8zpiKIk,5710
@@ -202,7 +203,7 @@ tests/test_rpc_rate_limit.py,sha256=3P_Nd9voFmz-4r_Et-vw8W-Esbq5elSYmRBSOtJGx1Y,
 tests/test_rpc_rotation.py,sha256=a1cFKsf0fo-73_MSDnTuU6Zpv7bJHjrCVu3ANe8PXDU,12541
 tests/test_rpc_view.py,sha256=sgZ53KEHl8VGb7WKYa0VI7Cdxbf8JH1SdroHYbWHjfQ,2031
 tests/test_safe_coverage.py,sha256=KBxKz64XkK8CgN0N0LTNVKakf8Wg8EpghcBlLmDFmLs,6119
-tests/test_safe_executor.py,sha256=V3ovBRY1lOuW5rm8rpm5Ns7jb-rgmHKHpz9pMTqz6c4,14448
+tests/test_safe_executor.py,sha256=HYdyWdoKs3xK-1wJ9QGcLx58Dk2GV4-IpDqE9hUhA8I,22149
 tests/test_safe_integration.py,sha256=WWAKDio3N-CFyr5RRvphbOPdu3TI9WSM8IesfbFbvWQ,5363
 tests/test_safe_service.py,sha256=5ULlj0fPZRwg-4fCBJplhm4Msr_Beof7W-Zf_JljZc8,5782
 tests/test_service_manager_integration.py,sha256=I_BLUzEKrVTyg_8jqsUK0oFD3aQVPCRJ7z0gY8P-j04,2354
@@ -211,7 +212,7 @@ tests/test_service_transaction.py,sha256=IeqYhmRD-pIXffBJrBQwfPx-qnfNEJs0iPM3eCb
 tests/test_staking_router.py,sha256=cnOtwWeQPu09kecVhlCf1WA4ONqs13OcQJhJCx2EOPY,3067
 tests/test_staking_simple.py,sha256=NHyZ1pcVQEJGFiGseC5m6Y9Y6FJGnRIFJUwhd1hAV9g,1138
 tests/test_tables.py,sha256=1KQHgxuizoOrRxpubDdnzk9iaU5Lwyp3bcWP_hZD5uU,2686
-tests/test_transaction_service.py,sha256=TXhIleUNOnp3DXi-RrKJ1Y_6dA6de5TQLOc9qndMHm4,5765
+tests/test_transaction_service.py,sha256=q2IQ6cJ6sZtzc_pVCM_dv0vW7LW2sONNrK5Pvrm63rU,12816
 tests/test_transfer_multisend.py,sha256=PErjNqNwN66TMh4oVa307re64Ucccg1LkXqB0KlkmsI,6677
 tests/test_transfer_native.py,sha256=cDbb4poV_veIw6eHpokrHe9yUndOjA6rQhrHd_IY3HQ,7445
 tests/test_transfer_security.py,sha256=gdpC6ybdXQbQgILbAQ0GqjWdwn9AJRNR3B_7TYg0NxI,3617
@@ -222,8 +223,8 @@ tests/test_utils.py,sha256=vkP49rYNI8BRzLpWR3WnKdDr8upeZjZcs7Rx0pjbQMo,1292
 tests/test_workers.py,sha256=MInwdkFY5LdmFB3o1odIaSD7AQZb3263hNafO1De5PE,2793
 tools/create_and_stake_service.py,sha256=1xwy_bJQI1j9yIQ968Oc9Db_F6mk1659LuuZntTASDE,3742
 tools/verify_drain.py,sha256=PkMjblyOOAuQge88FwfEzRtCYeEtJxXhPBmtQYCoQ-8,6743
-iwa-0.0.60.dist-info/METADATA,sha256=BpkWW6DmPQhaX7fFo7LtVfNYg3thQWSMiMmR_yGApCc,7337
-iwa-0.0.60.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-iwa-0.0.60.dist-info/entry_points.txt,sha256=nwB6kscrfA7M00pYmL2j-sBH6eF6h2ga9IK1BZxdiyQ,241
-iwa-0.0.60.dist-info/top_level.txt,sha256=kedS9cRUbm4JE2wYeabIXilhHjN8KCw0IGbqqqsw0Bs,16
-iwa-0.0.60.dist-info/RECORD,,
+iwa-0.0.61.dist-info/METADATA,sha256=FLMOGU9L47jQQ45Cd7i64bfZNXCtNidn1ryV4-uBjCA,7337
+iwa-0.0.61.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iwa-0.0.61.dist-info/entry_points.txt,sha256=nwB6kscrfA7M00pYmL2j-sBH6eF6h2ga9IK1BZxdiyQ,241
+iwa-0.0.61.dist-info/top_level.txt,sha256=kedS9cRUbm4JE2wYeabIXilhHjN8KCw0IGbqqqsw0Bs,16
+iwa-0.0.61.dist-info/RECORD,,

tests/test_chainlist_enrichment.py

@@ -0,0 +1,354 @@
+"""Tests for ChainList RPC enrichment and quality probing."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from iwa.core.chainlist import (
+    ChainlistRPC,
+    RPCNode,
+    _is_template_url,
+    _normalize_url,
+    probe_rpc,
+)
+
+
+@pytest.fixture(autouse=True)
+def mock_chainlist_enrichment():
+    """Override conftest — allow real enrichment calls in this test file."""
+    yield
+
+
+class TestNormalizeUrl:
+    """Test URL normalization for deduplication."""
+
+    def test_strips_trailing_slash(self):
+        assert _normalize_url("https://rpc.example.com/") == "https://rpc.example.com"
+
+    def test_lowercases(self):
+        assert _normalize_url("https://RPC.Example.COM") == "https://rpc.example.com"
+
+    def test_no_change_needed(self):
+        assert _normalize_url("https://rpc.example.com") == "https://rpc.example.com"
+
+
+class TestIsTemplateUrl:
+    """Test template URL detection."""
+
+    def test_dollar_brace(self):
+        assert _is_template_url("https://rpc.example.com/${API_KEY}") is True
+
+    def test_plain_brace(self):
+        assert _is_template_url("https://rpc.example.com/{api_key}") is True
+
+    def test_no_template(self):
+        assert _is_template_url("https://rpc.example.com") is False
+
+
+class TestProbeRpc:
+    """Test single RPC probing."""
+
+    @pytest.fixture
+    def mock_session(self):
+        """Create a mock session for probe_rpc tests."""
+        with patch("iwa.core.chainlist.requests.Session") as mock_session_cls:
+            mock_session = MagicMock()
+            mock_session_cls.return_value = mock_session
+            # Make it work as context manager too
+            mock_session.__enter__ = MagicMock(return_value=mock_session)
+            mock_session.__exit__ = MagicMock(return_value=False)
+            yield mock_session
+
+    def test_success(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x1A4B5C", "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+
+        assert result is not None
+        url, latency, block = result
+        assert url == "https://rpc.example.com"
+        assert latency > 0
+        assert block == 0x1A4B5C
+        # Verify session was closed
+        mock_session.close.assert_called_once()
+
+    def test_timeout_returns_none(self, mock_session):
+        mock_session.post.side_effect = requests.exceptions.Timeout("timed out")
+
+        result = probe_rpc("https://slow.example.com")
+        assert result is None
+        # Session still closed on error
+        mock_session.close.assert_called_once()
+
+    def test_connection_error_returns_none(self, mock_session):
+        mock_session.post.side_effect = requests.exceptions.ConnectionError("refused")
+
+        result = probe_rpc("https://dead.example.com")
+        assert result is None
+        mock_session.close.assert_called_once()
+
+    def test_zero_block_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x0", "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_null_result_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": None, "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_error_response_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {
+            "jsonrpc": "2.0",
+            "error": {"code": -32600, "message": "Invalid Request"},
+            "id": 1,
+        }
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_uses_provided_session(self):
+        """When a session is provided, use it instead of creating one."""
+        provided_session = MagicMock()
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x100", "id": 1}
+        provided_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com", session=provided_session)
+
+        assert result is not None
+        provided_session.post.assert_called_once()
+        # Should NOT close provided session (caller's responsibility)
+        provided_session.close.assert_not_called()
+
+
+class TestGetValidatedRpcs:
+    """Test ChainlistRPC.get_validated_rpcs()."""
+
+    def _make_node(self, url, tracking="none"):
+        return RPCNode(url=url, is_working=True, tracking=tracking)
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_template_urls(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://rpc.example.com/${API_KEY}"),
+            self._make_node("https://good.example.com"),
+        ]
+        mock_probe.return_value = ("https://good.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == ["https://good.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_non_https(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("http://insecure.example.com"),
+            self._make_node("wss://ws.example.com"),
+            self._make_node("https://good.example.com"),
+        ]
+        mock_probe.return_value = ("https://good.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == ["https://good.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_deduplicates_existing(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://already.configured.com"),
+            self._make_node("https://new.example.com"),
+        ]
+        mock_probe.return_value = ("https://new.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(
+            100, existing_rpcs=["https://already.configured.com/"]
+        )
+
+        assert result == ["https://new.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_stale_rpcs(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://fresh.example.com"),
+            self._make_node("https://stale.example.com"),
+            self._make_node("https://also-fresh.example.com"),
+        ]
+        # fresh=1000, stale=900 (100 blocks behind), also-fresh=999
+        mock_probe.side_effect = [
+            ("https://fresh.example.com", 50.0, 1000),
+            ("https://stale.example.com", 30.0, 900),
+            ("https://also-fresh.example.com", 60.0, 999),
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        # Stale RPC (900) is 100 blocks behind median (999) > MAX_BLOCK_LAG
+        assert "https://stale.example.com" not in result
+        assert "https://fresh.example.com" in result
+        assert "https://also-fresh.example.com" in result
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_sorts_by_latency(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://slow.example.com"),
+            self._make_node("https://fast.example.com"),
+            self._make_node("https://medium.example.com"),
+        ]
+        mock_probe.side_effect = [
+            ("https://slow.example.com", 200.0, 1000),
+            ("https://fast.example.com", 10.0, 1000),
+            ("https://medium.example.com", 80.0, 1000),
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == [
+            "https://fast.example.com",
+            "https://medium.example.com",
+            "https://slow.example.com",
+        ]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_respects_max_results(self, mock_probe, mock_get_rpcs):
+        nodes = [self._make_node(f"https://rpc{i}.example.com") for i in range(10)]
+        mock_get_rpcs.return_value = nodes
+        mock_probe.side_effect = [
+            (f"https://rpc{i}.example.com", float(i * 10), 1000) for i in range(10)
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[], max_results=3)
+
+        assert len(result) == 3
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    def test_returns_empty_on_no_rpcs(self, mock_get_rpcs):
+        mock_get_rpcs.return_value = []
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == []
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_returns_empty_when_all_probes_fail(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://dead1.example.com"),
+            self._make_node("https://dead2.example.com"),
+        ]
+        mock_probe.return_value = None
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == []
+
+
+class TestEnrichFromChainlist:
+    """Test ChainInterface._enrich_rpcs_from_chainlist().
+
+    The conftest fixture is overridden in this file so the real
+    enrichment method runs during __init__.
+    """
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_skipped_for_tenderly(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://virtual.tenderly.co/test"]
+        chain.rpc = "https://virtual.tenderly.co/test"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            ci = ChainInterface(chain)
+
+        # is_tenderly=True → enrichment skipped → ChainlistRPC never called
+        assert "tenderly" in ci.current_rpc.lower()
+        mock_cl_cls.assert_not_called()
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_enriches_non_tenderly(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://rpc1.example.com"]
+        chain.rpc = "https://rpc1.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            mock_cl = mock_cl_cls.return_value
+            mock_cl.get_validated_rpcs.return_value = [
+                "https://extra1.example.com",
+                "https://extra2.example.com",
+            ]
+            ChainInterface(chain)
+
+        assert len(chain.rpcs) == 3
+        assert "https://extra1.example.com" in chain.rpcs
+        assert "https://extra2.example.com" in chain.rpcs
+        # Original RPC stays first
+        assert chain.rpcs[0] == "https://rpc1.example.com"
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_survives_fetch_failure(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://rpc1.example.com"]
+        chain.rpc = "https://rpc1.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            mock_cl_cls.side_effect = Exception("network error")
+            ChainInterface(chain)
+
+        # Should still work with original RPCs
+        assert chain.rpcs == ["https://rpc1.example.com"]
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_respects_max_rpcs(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = [f"https://rpc{i}.example.com" for i in range(10)]
+        chain.rpc = "https://rpc0.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            ChainInterface(chain)
+
+        # Already at MAX_RPCS=10, ChainlistRPC should not be called
+        mock_cl_cls.assert_not_called()

tests/test_safe_executor.py

@@ -359,3 +359,211 @@ def test_retry_preserves_gas(executor, mock_chain_interface, mock_safe_tx, mock_
             executor.execute_with_retry("0xSafe", mock_safe_tx, ["key1"])
 
         assert mock_safe_tx.safe_tx_gas == original_gas
+
+
+# =============================================================================
+# Test: Gas estimation (_estimate_safe_tx_gas)
+# =============================================================================
+
+
+def test_estimate_safe_tx_gas_with_buffer(executor, mock_safe):
+    """Test gas estimation applies buffer correctly."""
+    mock_safe.estimate_tx_gas.return_value = 100_000
+    mock_safe_tx = MagicMock()
+    mock_safe_tx.to = "0xDest"
+    mock_safe_tx.value = 0
+    mock_safe_tx.data = b""
+    mock_safe_tx.operation = 0
+
+    result = executor._estimate_safe_tx_gas(mock_safe, mock_safe_tx)
+
+    # Default buffer is 1.5, so 100000 * 1.5 = 150000
+    assert result == 150_000
+
+
+def test_estimate_safe_tx_gas_caps_at_10x(executor, mock_safe):
+    """Test gas estimation respects x10 cap when base_estimate is provided."""
+    mock_safe.estimate_tx_gas.return_value = 500_000  # High estimate
+    mock_safe_tx = MagicMock()
+    mock_safe_tx.to = "0xDest"
+    mock_safe_tx.value = 0
+    mock_safe_tx.data = b""
+    mock_safe_tx.operation = 0
+
+    # 500000 * 1.5 = 750000, but base_estimate * 10 = 50000
+    result = executor._estimate_safe_tx_gas(mock_safe, mock_safe_tx, base_estimate=5_000)
+
+    # Should be capped at 5000 * 10 = 50000
+    assert result == 50_000
+
+
+def test_estimate_safe_tx_gas_fallback_on_failure(executor, mock_safe):
+    """Test gas estimation uses fallback when estimation fails."""
+    mock_safe.estimate_tx_gas.side_effect = Exception("Estimation failed")
+    mock_safe_tx = MagicMock()
+    mock_safe_tx.to = "0xDest"
+    mock_safe_tx.value = 0
+    mock_safe_tx.data = b""
+    mock_safe_tx.operation = 0
+
+    result = executor._estimate_safe_tx_gas(mock_safe, mock_safe_tx)
+
+    assert result == executor.DEFAULT_FALLBACK_GAS
+
+
+# =============================================================================
+# Test: Error decoding (_decode_revert_reason)
+# =============================================================================
+
+
+def test_decode_revert_reason_with_hex_data(executor):
+    """Test decoding when error contains hex data."""
+    # Create an error with hex data that might be decodable
+    error = ValueError("execution reverted: 0x08c379a0...")
+
+    with patch("iwa.core.services.safe_executor.ErrorDecoder") as mock_decoder:
+        mock_decoder.return_value.decode.return_value = [("Error", "Insufficient balance", "ERC20")]
+        result = executor._decode_revert_reason(error)
+
+    # Note: Due to hex matching, this should find the data and attempt decode
+    assert result == "Insufficient balance (from ERC20)"
+
+
+def test_decode_revert_reason_no_hex_data(executor):
+    """Test decoding when error has no hex data."""
+    error = ValueError("Some generic error without hex")
+
+    result = executor._decode_revert_reason(error)
+
+    assert result is None
+
+
+def test_decode_revert_reason_decode_fails(executor):
+    """Test decoding when decoder returns None."""
+    error = ValueError("error: 0xdeadbeef")
+
+    with patch("iwa.core.services.safe_executor.ErrorDecoder") as mock_decoder:
+        mock_decoder.return_value.decode.return_value = None
+        result = executor._decode_revert_reason(error)
+
+    assert result is None
+
+
+# =============================================================================
+# Test: Error classification
+# =============================================================================
+
+
+def test_classify_error_gas_error(executor):
+    """Test classification of gas-related errors."""
+    error = ValueError("intrinsic gas too low")
+    result = executor._classify_error(error)
+
+    assert result["is_gas_error"] is True
+    assert result["is_nonce_error"] is False
+
+
+def test_classify_error_revert(executor):
+    """Test classification of revert errors."""
+    error = ValueError("execution reverted: some reason")
+    result = executor._classify_error(error)
+
+    assert result["is_revert"] is True
+
+
+def test_classify_error_out_of_gas(executor):
+    """Test classification of out of gas errors."""
+    error = ValueError("out of gas")
+    result = executor._classify_error(error)
+
+    assert result["is_gas_error"] is True
+
+
+# =============================================================================
+# Test: Transaction failures
+# =============================================================================
+
+
+def test_transaction_reverts_onchain(executor, mock_chain_interface, mock_safe_tx, mock_safe):
+    """Test handling when transaction is mined but reverts (status 0)."""
+    with patch.object(executor, "_recreate_safe_client", return_value=mock_safe):
+        mock_safe_tx.execute.return_value = b"tx_hash"
+        # Receipt with status 0 (reverted)
+        mock_chain_interface.web3.eth.wait_for_transaction_receipt.return_value = MagicMock(
+            status=0
+        )
+
+        with patch("time.sleep"):
+            success, error, receipt = executor.execute_with_retry(
+                "0xSafe", mock_safe_tx, ["key1"]
+            )
+
+        assert success is False
+        assert "reverted" in error.lower()
+
+
+def test_check_receipt_status_dict_format(executor):
+    """Test receipt status check with dict-style receipt."""
+    # Dict-style receipt (not MagicMock)
+    receipt_dict = {"status": 1, "gasUsed": 21000}
+    assert executor._check_receipt_status(receipt_dict) is True
+
+    receipt_dict_failed = {"status": 0}
+    assert executor._check_receipt_status(receipt_dict_failed) is False
+
+
+def test_simulation_revert_not_nonce(executor, mock_chain_interface, mock_safe_tx, mock_safe):
+    """Test handling when simulation reverts with non-nonce error."""
+    with patch.object(executor, "_recreate_safe_client", return_value=mock_safe):
+        # Simulation fails with generic revert
+        mock_safe_tx.call.side_effect = ValueError("execution reverted: insufficient funds")
+
+        with patch("time.sleep"):
+            success, error, receipt = executor.execute_with_retry(
+                "0xSafe", mock_safe_tx, ["key1"]
+            )
+
+        assert success is False
+        assert "insufficient funds" in error.lower() or "reverted" in error.lower()
+
+
+def test_gas_error_strategy_triggers_retry(
+    executor, mock_chain_interface, mock_safe_tx, mock_safe
+):
+    """Test that gas errors trigger retry with gas increase strategy."""
+    with patch.object(executor, "_recreate_safe_client", return_value=mock_safe):
+        mock_safe_tx.execute.side_effect = [
+            ValueError("intrinsic gas too low"),
+            b"tx_hash",
+        ]
+        mock_chain_interface.web3.eth.wait_for_transaction_receipt.return_value = MagicMock(
+            status=1
+        )
+
+        with patch("time.sleep"):
+            success, tx_hash, receipt = executor.execute_with_retry(
+                "0xSafe", mock_safe_tx, ["key1"]
+            )
+
+        # Should have retried and succeeded
+        assert success is True
+        assert mock_safe_tx.execute.call_count == 2
+
+
+def test_rpc_rotation_stops_when_should_not_retry(
+    executor, mock_chain_interface, mock_safe_tx, mock_safe
+):
+    """Test that execution stops when RPC handler says not to retry."""
+    with patch.object(executor, "_recreate_safe_client", return_value=mock_safe):
+        mock_safe_tx.execute.side_effect = ValueError("Rate limit exceeded")
+        mock_chain_interface._is_rate_limit_error.return_value = True
+        mock_chain_interface._handle_rpc_error.return_value = {"should_retry": False}
+
+        with patch("time.sleep"):
+            success, error, receipt = executor.execute_with_retry(
+                "0xSafe", mock_safe_tx, ["key1"]
+            )
+
+        assert success is False
+        # Only 1 attempt because should_retry=False
+        assert mock_safe_tx.execute.call_count == 1

tests/test_transaction_service.py

@@ -1,12 +1,17 @@
-"""Tests for TransactionService."""
+"""Tests for TransactionService and TransferLogger."""
 
 from unittest.mock import MagicMock, patch
 
 import pytest
+from web3 import Web3
 from web3 import exceptions as web3_exceptions
 
 from iwa.core.keys import EncryptedAccount, KeyStorage
-from iwa.core.services.transaction import TransactionService
+from iwa.core.services.transaction import (
+    TRANSFER_EVENT_TOPIC,
+    TransactionService,
+    TransferLogger,
+)
 
 
 @pytest.fixture
@@ -177,3 +182,174 @@ def test_sign_and_send_rpc_rotation(
     assert success is True
     # Verify retry happened - send_raw_transaction called twice
     assert chain_interface.web3.eth.send_raw_transaction.call_count == 2
+
+
+# =============================================================================
+# TransferLogger tests
+# =============================================================================
+
+# Real-world address for tests
+_ADDR = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+_ADDR_LOWER = _ADDR.lower()
+# 32-byte topic with address in last 20 bytes
+_TOPIC_BYTES = b"\x00" * 12 + bytes.fromhex(_ADDR_LOWER[2:])
+_TOPIC_HEX_STR = "0x" + "0" * 24 + _ADDR_LOWER[2:]
+
+
+@pytest.fixture
+def transfer_logger():
+    """Create a TransferLogger with minimal mocks."""
+    account_service = MagicMock()
+    account_service.get_tag_by_address.return_value = None
+    chain_interface = MagicMock()
+    chain_interface.chain.native_currency = "xDAI"
+    chain_interface.chain.get_token_name.return_value = None
+    chain_interface.get_token_decimals.return_value = 18
+    return TransferLogger(account_service, chain_interface)
+
+
+class TestTopicToAddress:
+    """Test TransferLogger._topic_to_address with all input types."""
+
+    def test_bytes_topic(self, transfer_logger):
+        """32 bytes → last 20 bytes extracted as address."""
+        result = transfer_logger._topic_to_address(_TOPIC_BYTES)
+        assert result == Web3.to_checksum_address(_ADDR_LOWER)
+
+    def test_hex_string_topic(self, transfer_logger):
+        """Hex string with 0x prefix → last 40 chars as address."""
+        result = transfer_logger._topic_to_address(_TOPIC_HEX_STR)
+        assert result == Web3.to_checksum_address(_ADDR_LOWER)
+
+    def test_hex_string_no_prefix(self, transfer_logger):
+        """Hex string without 0x prefix."""
+        topic = "0" * 24 + _ADDR_LOWER[2:]
+        result = transfer_logger._topic_to_address(topic)
+        assert result == Web3.to_checksum_address(_ADDR_LOWER)
+
+    def test_hexbytes_like_topic(self, transfer_logger):
+        """Object with .hex() method (like HexBytes)."""
+
+        class FakeHexBytes:
+            def hex(self):
+                return "0" * 24 + _ADDR_LOWER[2:]
+
+        result = transfer_logger._topic_to_address(FakeHexBytes())
+        assert result == Web3.to_checksum_address(_ADDR_LOWER)
+
+    def test_unsupported_type_returns_empty(self, transfer_logger):
+        """Non-bytes, non-str, no .hex() → empty string."""
+        result = transfer_logger._topic_to_address(12345)
+        assert result == ""
+
+
+class TestProcessLog:
+    """Test TransferLogger._process_log with realistic log structures."""
+
+    def _make_transfer_log(self, from_addr, to_addr, amount_wei, token_addr="0xToken"):
+        """Build a dict-style Transfer event log."""
+        from_topic = "0x" + "0" * 24 + from_addr[2:].lower()
+        to_topic = "0x" + "0" * 24 + to_addr[2:].lower()
+        data = amount_wei.to_bytes(32, "big")
+        return {
+            "topics": [TRANSFER_EVENT_TOPIC, from_topic, to_topic],
+            "data": data,
+            "address": token_addr,
+        }
+
+    def test_parses_erc20_transfer(self, transfer_logger):
+        """Valid Transfer log is parsed and logged."""
+        log = self._make_transfer_log(
+            "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+            "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+            10**18,  # 1 token with 18 decimals
+        )
+        # Should not raise
+        transfer_logger._process_log(log)
+
+    def test_ignores_non_transfer_event(self, transfer_logger):
+        """Log with non-Transfer topic is silently skipped."""
+        log = {
+            "topics": ["0xdeadbeef" + "0" * 56],
+            "data": b"",
+            "address": "0xToken",
+        }
+        # Should not raise or log anything
+        transfer_logger._process_log(log)
+
+    def test_ignores_log_with_no_topics(self, transfer_logger):
+        """Log with empty topics is skipped."""
+        transfer_logger._process_log({"topics": [], "data": b""})
+
+    def test_ignores_log_with_insufficient_topics(self, transfer_logger):
+        """Transfer event with < 3 topics (missing from/to) is skipped."""
+        log = {
+            "topics": [TRANSFER_EVENT_TOPIC, "0x" + "0" * 64],
+            "data": b"",
+            "address": "0xToken",
+        }
+        transfer_logger._process_log(log)
+
+    def test_handles_bytes_topics(self, transfer_logger):
+        """Log with bytes topics (not hex strings)."""
+        from_bytes = b"\x00" * 12 + b"\xAA" * 20
+        to_bytes = b"\x00" * 12 + b"\xBB" * 20
+        event_topic = bytes.fromhex(TRANSFER_EVENT_TOPIC[2:])
+        log = {
+            "topics": [event_topic, from_bytes, to_bytes],
+            "data": (100).to_bytes(32, "big"),
+            "address": "0xTokenAddr",
+        }
+        transfer_logger._process_log(log)
+
+    def test_handles_string_data(self, transfer_logger):
+        """Log with hex-encoded data string instead of bytes."""
+        log = self._make_transfer_log(
+            "0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+            "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+            0,
+        )
+        log["data"] = "0x" + "0" * 64  # String instead of bytes
+        transfer_logger._process_log(log)
+
+
+class TestResolveLabels:
+    """Test address/token label resolution fallbacks."""
+
+    def test_address_label_known_wallet(self, transfer_logger):
+        """Known wallet tag is preferred."""
+        transfer_logger.account_service.get_tag_by_address.return_value = "my_safe"
+        result = transfer_logger._resolve_address_label("0xABC")
+        assert result == "my_safe"
+
+    def test_address_label_known_token(self, transfer_logger):
+        """Falls back to token contract name."""
+        transfer_logger.account_service.get_tag_by_address.return_value = None
+        transfer_logger.chain_interface.chain.get_token_name.return_value = "OLAS"
+        result = transfer_logger._resolve_address_label("0xOLAS")
+        assert result == "OLAS_contract"
+
+    def test_address_label_abbreviated(self, transfer_logger):
+        """Falls back to abbreviated address."""
+        result = transfer_logger._resolve_address_label("0xABCDEF1234567890ABCDEF")
+        assert result.startswith("0xABCD")
+        assert result.endswith("CDEF")
+        assert "..." in result
+
+    def test_address_label_empty(self, transfer_logger):
+        """Empty address returns 'unknown'."""
+        assert transfer_logger._resolve_address_label("") == "unknown"
+
+    def test_token_label_known(self, transfer_logger):
+        """Known token returns its name."""
+        transfer_logger.chain_interface.chain.get_token_name.return_value = "OLAS"
+        assert transfer_logger._resolve_token_label("0xOLAS") == "OLAS"
+
+    def test_token_label_unknown(self, transfer_logger):
+        """Unknown token returns abbreviated address."""
+        result = transfer_logger._resolve_token_label("0xABCDEF1234567890ABCDEF")
+        assert "..." in result
+
+    def test_token_label_empty(self, transfer_logger):
+        """Empty address returns 'UNKNOWN'."""
+        assert transfer_logger._resolve_token_label("") == "UNKNOWN"