brawny 0.1.13__py3-none-any.whl → 0.1.22__py3-none-any.whl

brawny/alerts/abi_resolver.py

@@ -11,11 +11,14 @@ from __future__ import annotations
 
 import json
 import os
+import re
+import threading
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
 
-import requests
+import httpx
+from cachetools import TTLCache
 from eth_utils import to_checksum_address
 
 from brawny.alerts.errors import (
@@ -25,14 +28,80 @@ from brawny.alerts.errors import (
 )
 from brawny.db.global_cache import GlobalABICache
 from brawny.logging import get_logger
+from brawny.network_guard import allow_network_calls
 
 if TYPE_CHECKING:
     from brawny.config import Config
-    from brawny._rpc.manager import RPCManager
+    from brawny._rpc.clients import ReadClient
 
 
 logger = get_logger(__name__)
 
+# Short timeout to avoid blocking workers (Plan 08)
+_FETCH_TIMEOUT = 2.0
+
+# Address validation: 40 hex chars, optional 0x prefix
+_ADDR_RE = re.compile(r"^(0x)?[0-9a-fA-F]{40}$")
+
+# In-memory caches with different TTLs (fast-path before database):
+# - Success cache: ABIs are immutable, cache for 24h
+# - Failure cache: Cache misses for 30min (allows recovery if API fixed)
+# Multi-threaded access (from worker threads) - protected by _mem_cache_lock
+_mem_abi_cache: TTLCache[str, list[dict[str, Any]]] = TTLCache(maxsize=5_000, ttl=24 * 3600)
+_mem_abi_not_found: TTLCache[str, bool] = TTLCache(maxsize=1_000, ttl=30 * 60)
+_mem_cache_lock = threading.Lock()
+
+# Module-level HTTP client for connection pooling
+_http_client: httpx.Client | None = httpx.Client(timeout=_FETCH_TIMEOUT)
+
+
+def close_http_client() -> None:
+    """Close HTTP client on shutdown. Idempotent + safe in partial init."""
+    global _http_client
+    client, _http_client = _http_client, None
+    if client is not None:
+        client.close()
+    # Also clear in-memory caches
+    with _mem_cache_lock:
+        _mem_abi_cache.clear()
+        _mem_abi_not_found.clear()
+
+
+def clear_memory_cache() -> None:
+    """Clear in-memory ABI caches. Useful for testing."""
+    with _mem_cache_lock:
+        _mem_abi_cache.clear()
+        _mem_abi_not_found.clear()
+
+
+def _client() -> httpx.Client:
+    """Get HTTP client, fail fast if closed."""
+    if _http_client is None:
+        raise RuntimeError("HTTP client is closed")
+    return _http_client
+
+
+def _is_valid_address(address: str) -> bool:
+    """Check if string looks like a valid Ethereum address."""
+    return bool(_ADDR_RE.match(address))
+
+
+def _normalize_address(address: str) -> str:
+    """Normalize address for cache key: lowercase with 0x prefix.
+
+    Caller should validate with _is_valid_address() first.
+    """
+    addr = address.lower()
+    if not addr.startswith("0x"):
+        addr = "0x" + addr
+    return addr
+
+
+def _mem_cache_key(chain_id: int, address: str) -> str:
+    """Build cache key for in-memory cache: chain_id:normalized_address."""
+    return f"{chain_id}:{_normalize_address(address)}"
+
+
 # EIP-1967 storage slots for proxy detection
 IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc"
 BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50"
@@ -91,11 +160,16 @@ class ABIResolver:
     """Resolves contract ABIs with caching and proxy support.
 
     Resolution order:
-    1. Check database cache (with TTL validation)
-    2. Detect if address is a proxy and resolve implementation
-    3. Try Etherscan API
-    4. Try Sourcify as fallback
-    5. Raise ABINotFoundError if all fail
+    1. Check in-memory TTLCache (fast-path, avoids blocking)
+    2. Check database cache (with TTL validation)
+    3. Detect if address is a proxy and resolve implementation
+    4. Try Etherscan API (short timeout to avoid blocking workers)
+    5. Try Sourcify as fallback
+    6. Raise ABINotFoundError if all fail (or return None for resolve_safe)
+
+    Policy (Plan 08):
+    - Critical path (check/build): Use local ABIs via interfaces or with_abi()
+    - Non-critical path (alerts/hooks): Runtime fetch is best-effort
 
     Proxy detection:
     - Checks EIP-1967 implementation slot
@@ -105,7 +179,7 @@ class ABIResolver:
 
     def __init__(
         self,
-        rpc: RPCManager,
+        rpc: ReadClient,
         config: Config,
         abi_cache: GlobalABICache | None = None,
     ) -> None:
@@ -115,7 +189,7 @@ class ABIResolver:
         self._etherscan_api_url = ETHERSCAN_V2_API_URL
         self._etherscan_api_key = os.environ.get("ETHERSCAN_API_KEY")
         self._sourcify_enabled = True
-        self._request_timeout = 10.0
+        self._request_timeout = _FETCH_TIMEOUT
 
     def resolve(
         self,
@@ -137,24 +211,42 @@ class ABIResolver:
             ABINotFoundError: If ABI cannot be resolved from any source
             InvalidAddressError: If address is invalid
         """
-        # Validate and normalize address
+        # Validate address format (don't poison cache with garbage)
+        if not _is_valid_address(address):
+            raise InvalidAddressError(address)
+
+        # Normalize for caching/lookup
         try:
             address = to_checksum_address(address)
         except Exception:
             raise InvalidAddressError(address)
 
         chain_id = chain_id or self.config.chain_id
+        cache_key = _mem_cache_key(chain_id, address)
         checked_sources: list[str] = []
 
-        # Step 1: Check cache (unless force refresh)
+        # Step 0/1: Check database cache first (authoritative), then memory cache.
         if not force_refresh:
             cached = self.abi_cache.get_cached_abi(chain_id, address)
             if cached and not self._is_cache_expired(cached.resolved_at):
+                # Populate in-memory cache for next time
+                abi = json.loads(cached.abi_json)
+                with _mem_cache_lock:
+                    _mem_abi_cache[cache_key] = abi
                 return ResolvedABI(
                     address=address,
-                    abi=json.loads(cached.abi_json),
+                    abi=abi,
                     source=cached.source,
                 )
+            with _mem_cache_lock:
+                if cache_key in _mem_abi_cache:
+                    return ResolvedABI(
+                        address=address,
+                        abi=_mem_abi_cache[cache_key],
+                        source="memory_cache",
+                    )
+                if cache_key in _mem_abi_not_found:
+                    raise ABINotFoundError(address, ["memory_cache"])
 
         # Step 2: Check if proxy and resolve implementation
         impl_address = self._resolve_proxy_implementation(chain_id, address)
@@ -176,6 +268,9 @@ class ABIResolver:
                         json.dumps(impl_abi),
                         "proxy_implementation",
                     )
+                    # Populate in-memory cache
+                    with _mem_cache_lock:
+                        _mem_abi_cache[cache_key] = impl_abi
                     return ResolvedABI(
                         address=address,
                         abi=impl_abi,
@@ -195,10 +290,47 @@ class ABIResolver:
         if abi:
             source = checked_sources[-1] if checked_sources else "unknown"
             self.abi_cache.set_cached_abi(chain_id, address, json.dumps(abi), source)
+            # Populate in-memory cache
+            with _mem_cache_lock:
+                _mem_abi_cache[cache_key] = abi
             return ResolvedABI(address=address, abi=abi, source=source)
 
+        # Cache failure in memory (shorter TTL allows recovery)
+        with _mem_cache_lock:
+            _mem_abi_not_found[cache_key] = True
+
         raise ABINotFoundError(address, checked_sources)
 
+    def resolve_safe(
+        self,
+        address: str,
+        chain_id: int | None = None,
+    ) -> ResolvedABI | None:
+        """Resolve ABI with fail-open behavior (returns None instead of raising).
+
+        Use this for non-critical paths where missing ABI should be handled
+        gracefully (e.g., event decoding in alerts, lifecycle hooks).
+
+        Args:
+            address: Contract address to resolve ABI for
+            chain_id: Chain ID (defaults to config.chain_id)
+
+        Returns:
+            ResolvedABI if found, None if resolution fails for any reason
+        """
+        try:
+            return self.resolve(address, chain_id=chain_id)
+        except (ABINotFoundError, InvalidAddressError):
+            return None
+        except Exception as e:
+            # Log unexpected errors but don't raise
+            logger.debug(
+                "abi_resolver.resolve_safe_error",
+                address=address[:50] if address else "None",
+                error=type(e).__name__,
+            )
+            return None
+
     def _is_cache_expired(self, resolved_at: datetime) -> bool:
         """Check if cached entry is expired based on TTL."""
         if self.config.abi_cache_ttl_seconds <= 0:
@@ -271,13 +403,15 @@ class ABIResolver:
                         final_impl = nested or impl_address
                         self.abi_cache.set_cached_proxy(chain_id, address, final_impl)
                         return final_impl
-        except Exception as e:
+        except (ValueError, TypeError) as e:
             logger.debug("proxy.beacon_slot_error", address=address, error=str(e))
 
         return None
 
     def _read_storage_slot(self, address: str, slot: str) -> str | None:
         """Read a storage slot from a contract."""
+        from brawny._rpc.errors import RPCError
+
         try:
             result = self.rpc.get_storage_at(address, slot)
             if result is None:
@@ -286,7 +420,7 @@ class ABIResolver:
             if isinstance(result, bytes):
                 return "0x" + result.hex()
             return result
-        except Exception:
+        except (RPCError, ValueError, TypeError):
             return None
 
     def _slot_to_address(self, slot_value: str) -> str | None:
@@ -310,7 +444,7 @@ class ABIResolver:
 
         try:
             return to_checksum_address("0x" + addr_hex)
-        except Exception:
+        except ValueError:
             return None
 
     def _read_beacon_implementation(self, beacon_address: str) -> str | None:
@@ -318,6 +452,8 @@ class ABIResolver:
 
         Beacons typically have an implementation() function.
         """
+        from brawny._rpc.errors import RPCError
+
         # implementation() function selector: 0x5c60da1b
         try:
             tx_params = {"to": beacon_address, "data": "0x5c60da1b"}
@@ -328,7 +464,7 @@ class ABIResolver:
                     result = "0x" + result.hex()
                 if result != "0x":
                     return self._slot_to_address(result)
-        except Exception as e:
+        except (RPCError, ValueError, TypeError) as e:
             logger.debug(
                 "proxy.beacon_call_error",
                 beacon=beacon_address,
@@ -386,11 +522,8 @@ class ABIResolver:
             params["apikey"] = self._etherscan_api_key
 
         try:
-            response = requests.get(
-                api_url,
-                params=params,
-                timeout=self._request_timeout,
-            )
+            with allow_network_calls(reason="alerts"):
+                response = _client().get(api_url, params=params)
             response.raise_for_status()
 
             data = response.json()
@@ -403,13 +536,27 @@ class ABIResolver:
                 )
                 return abi
             else:
-                logger.debug(
-                    "etherscan.abi_not_found",
+                logger.warning(
+                    "etherscan.abi_fetch_failed",
                     address=address,
                     chain_id=chain_id,
-                    message=data.get("message"),
+                    etherscan_status=data.get("status"),
+                    etherscan_message=data.get("message"),
                 )
-        except requests.RequestException as e:
+        except httpx.TimeoutException:
+            logger.warning(
+                "etherscan.timeout",
+                address=address,
+                chain_id=chain_id,
+            )
+        except httpx.HTTPStatusError as e:
+            logger.warning(
+                "etherscan.http_error",
+                address=address,
+                chain_id=chain_id,
+                status=e.response.status_code,
+            )
+        except httpx.RequestError as e:
             logger.warning(
                 "etherscan.request_error",
                 address=address,
@@ -451,17 +598,28 @@ class ABIResolver:
         url = f"https://sourcify.dev/server/repository/contracts/{match_type}/{chain_id}/{address}/metadata.json"
 
         try:
-            response = requests.get(url, timeout=self._request_timeout)
-            if response.status_code == 200:
-                metadata = response.json()
-                if "output" in metadata and "abi" in metadata["output"]:
-                    logger.debug(
-                        "sourcify.abi_fetched",
-                        address=address,
-                        match_type=match_type,
-                    )
-                    return metadata["output"]["abi"]
-        except requests.RequestException as e:
+            with allow_network_calls(reason="alerts"):
+                response = _client().get(url)
+            response.raise_for_status()
+            metadata = response.json()
+            if "output" in metadata and "abi" in metadata["output"]:
+                logger.debug(
+                    "sourcify.abi_fetched",
+                    address=address,
+                    match_type=match_type,
+                )
+                return metadata["output"]["abi"]
+        except httpx.TimeoutException:
+            logger.debug("sourcify.timeout", address=address)
+        except httpx.HTTPStatusError as e:
+            # 404 is expected when contract not found
+            if e.response.status_code != 404:
+                logger.debug(
+                    "sourcify.http_error",
+                    address=address,
+                    status=e.response.status_code,
+                )
+        except httpx.RequestError as e:
             logger.debug("sourcify.request_error", address=address, error=str(e))
         except json.JSONDecodeError as e:
             logger.debug("sourcify.json_error", address=address, error=str(e))
@@ -471,6 +629,8 @@ class ABIResolver:
     def clear_cache(self, address: str, chain_id: int | None = None) -> bool:
         """Clear cached ABI and proxy resolution for an address.
 
+        Clears both in-memory and database caches.
+
         Args:
             address: Contract address
             chain_id: Chain ID (defaults to config.chain_id)
@@ -484,6 +644,13 @@ class ABIResolver:
         except Exception:
             raise InvalidAddressError(address)
 
+        # Clear in-memory cache
+        cache_key = _mem_cache_key(chain_id, address)
+        with _mem_cache_lock:
+            _mem_abi_cache.pop(cache_key, None)
+            _mem_abi_not_found.pop(cache_key, None)
+
+        # Clear database cache
         abi_cleared = self.abi_cache.clear_cached_abi(chain_id, address)
         proxy_cleared = self.abi_cache.clear_cached_proxy(chain_id, address)
 
@@ -497,6 +664,8 @@ class ABIResolver:
     ) -> None:
         """Manually set ABI for a contract.
 
+        Populates both in-memory and database caches.
+
         Args:
             address: Contract address
             abi: ABI to cache
@@ -508,6 +677,13 @@ class ABIResolver:
         except Exception:
             raise InvalidAddressError(address)
 
+        # Populate in-memory cache
+        cache_key = _mem_cache_key(chain_id, address)
+        with _mem_cache_lock:
+            _mem_abi_cache[cache_key] = abi
+            _mem_abi_not_found.pop(cache_key, None)  # Clear any failure marker
+
+        # Populate database cache
         self.abi_cache.set_cached_abi(chain_id, address, json.dumps(abi), "manual")
         logger.info("abi.manual_set", address=address, chain_id=chain_id)
 

brawny/alerts/base.py

@@ -122,7 +122,7 @@ def explorer_link(
     chain_id: int = 1,
     label: str | None = None,
 ) -> str:
-    """Create a MarkdownV2 explorer link with emoji.
+    """Create a Markdown explorer link with emoji.
 
     Automatically detects if input is a tx hash or address.
 
@@ -132,7 +132,7 @@ def explorer_link(
         label: Custom label (default: "🔗 View on Explorer")
 
     Returns:
-        MarkdownV2 formatted link like "[🔗 View on Explorer](url)"
+        Markdown formatted link like "[🔗 View on Explorer](url)"
 
     Example:
         >>> explorer_link("0xabc123...")

brawny/alerts/contracts.py

@@ -21,9 +21,11 @@ For events, use ctx.events (brownie-compatible):
 from __future__ import annotations
 
 import re
+import threading
 import time
 from typing import TYPE_CHECKING, Any
 
+from cachetools import TTLCache
 from eth_abi import decode as abi_decode
 from eth_utils import function_signature_to_4byte_selector, to_checksum_address
 
@@ -40,11 +42,37 @@ from brawny.alerts.function_caller import (
     OverloadedFunction,
 )
 from brawny.db.global_cache import GlobalABICache
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Warn-once cache: don't spam logs for same missing ABI
+# Multi-threaded access - protected by lock
+_warned_addresses: TTLCache[str, bool] = TTLCache(maxsize=1_000, ttl=3600)
+_warned_lock = threading.Lock()
+
+
+def _normalize_for_warn(address: str) -> str:
+    """Normalize address for warn-once cache (matches ABIResolver normalization)."""
+    addr = address.lower()
+    if not addr.startswith("0x"):
+        addr = "0x" + addr
+    return addr
+
+
+def _warn_once(address: str) -> bool:
+    """Return True if we should warn (first time for this address)."""
+    addr = _normalize_for_warn(address)
+    with _warned_lock:
+        if addr in _warned_addresses:
+            return False
+        _warned_addresses[addr] = True
+        return True
 
 if TYPE_CHECKING:
     from brawny.config import Config
     from brawny.jobs.base import TxReceipt
-    from brawny._rpc.manager import RPCManager
+    from brawny._rpc.clients import BroadcastClient
 
 
 class ContractSystem:
@@ -53,14 +81,14 @@ class ContractSystem:
     Uses global ABI cache at ~/.brawny/abi_cache.db for persistent storage.
     """
 
-    def __init__(self, rpc: "RPCManager", config: "Config") -> None:
+    def __init__(self, rpc: "BroadcastClient", config: "Config") -> None:
         self._rpc = rpc
         self._config = config
         self._abi_cache = GlobalABICache()
         self._resolver = None
 
     @property
-    def rpc(self) -> "RPCManager":
+    def rpc(self) -> "BroadcastClient":
         return self._rpc
 
     @property
@@ -136,6 +164,7 @@ class ContractHandle:
         self._job_id = job_id
         self._hook = hook
         self._abi_list = abi
+        self._abi_source: str | None = "manual" if abi is not None else None
         self._functions: dict[str, list[FunctionABI]] | None = None
 
     @property
@@ -150,13 +179,33 @@ class ContractHandle:
         return self._abi_list  # type: ignore
 
     def _ensure_abi(self) -> None:
-        """Ensure ABI is loaded."""
+        """Ensure ABI is loaded, fetching if needed.
+
+        Uses resolve_safe() which returns None instead of raising on failure.
+        If ABI cannot be resolved, logs warning once but doesn't raise.
+        Callers should check self._abi_list before using it.
+        """
         if self._abi_list is not None:
             return
 
         resolver = self._system.resolver()
-        resolved = resolver.resolve(self._address)
-        self._abi_list = resolved.abi
+        resolved = resolver.resolve_safe(self._address)
+
+        if resolved is not None:
+            self._abi_list = resolved.abi
+            self._abi_source = resolved.source
+        else:
+            # Always log at INFO level so resolution failures are visible
+            logger.info(
+                "contract.abi_resolution_failed",
+                address=self._address,
+            )
+            if _warn_once(self._address):
+                logger.warning(
+                    "contract.abi_not_found",
+                    address=self._address,
+                    hint="Use ctx.contracts.with_abi() or add to interfaces/",
+                )
 
     def _ensure_functions_parsed(self) -> None:
         """Ensure function ABIs are parsed."""
@@ -166,7 +215,11 @@ class ContractHandle:
         self._ensure_abi()
         self._functions = {}
 
-        for item in self._abi_list:  # type: ignore
+        # Handle case where ABI resolution failed
+        if self._abi_list is None:
+            return
+
+        for item in self._abi_list:
             if item.get("type") != "function":
                 continue
 
@@ -213,7 +266,13 @@ class ContractHandle:
 
         if name not in self._functions:
             available = list(self._functions.keys()) if self._functions else []
-            raise FunctionNotFoundError(name, self._address, available)
+            raise FunctionNotFoundError(
+                name,
+                self._address,
+                available_functions=available,
+                abi_resolved=self._abi_list is not None,
+                abi_source=self._abi_source,
+            )
 
         overloads = self._functions[name]
 
@@ -259,14 +318,22 @@ class ContractHandle:
                             return ExplicitFunctionCaller(self, func)
 
             raise FunctionNotFoundError(
-                signature, self._address, self._get_all_signatures()
+                signature,
+                self._address,
+                available_functions=self._get_all_signatures(),
+                abi_resolved=self._abi_list is not None,
+                abi_source=self._abi_source,
             )
         else:
             # Just a name - must have exactly one overload
             name = signature
             if name not in self._functions:
                 raise FunctionNotFoundError(
-                    name, self._address, list(self._functions.keys())
+                    name,
+                    self._address,
+                    available_functions=list(self._functions.keys()),
+                    abi_resolved=self._abi_list is not None,
+                    abi_source=self._abi_source,
                 )
 
             overloads = self._functions[name]

brawny/alerts/errors.py

@@ -153,26 +153,53 @@ class OverloadMatchError(DXError):
 
 
 class FunctionNotFoundError(DXError):
-    """Raised when function is not found in contract ABI."""
+    """Raised when function is not found in contract ABI.
+
+    Includes context about ABI resolution status to help diagnose
+    whether the ABI was never fetched vs fetched but missing the function.
+    """
 
     def __init__(
         self,
         function_name: str,
         address: str,
         available_functions: list[str] | None = None,
+        abi_resolved: bool | None = None,
+        abi_source: str | None = None,
     ) -> None:
         self.function_name = function_name
         self.address = address
         self.available_functions = available_functions
-        if available_functions:
+        self.abi_resolved = abi_resolved
+        self.abi_source = abi_source
+
+        # Build message based on ABI resolution status
+        if abi_resolved is False:
+            # ABI fetch failed completely
+            msg = (
+                f"Function '{function_name}' not found for {address}: "
+                f"ABI resolution failed. Check logs for etherscan.abi_fetch_failed "
+                f"or use ctx.contracts.with_abi() to provide ABI manually."
+            )
+        elif available_functions:
+            # ABI resolved but function not in it
             available_str = ", ".join(available_functions[:10])
             if len(available_functions) > 10:
                 available_str += f" ... ({len(available_functions) - 10} more)"
+            source_hint = f" (source: {abi_source})" if abi_source else ""
             msg = (
-                f"Function '{function_name}' not found in ABI for {address}. "
+                f"Function '{function_name}' not found in ABI for {address}{source_hint}. "
                 f"Available functions: [{available_str}]"
             )
+        elif abi_resolved is True:
+            # ABI resolved but empty (no functions)
+            source_hint = f" (source: {abi_source})" if abi_source else ""
+            msg = (
+                f"Function '{function_name}' not found for {address}: "
+                f"ABI was resolved{source_hint} but contains no functions."
+            )
         else:
+            # Legacy fallback (no resolution status provided)
             msg = f"Function '{function_name}' not found in ABI for {address}."
         super().__init__(msg)