brawny 0.1.13__py3-none-any.whl

brawny/alerts/function_caller.py

@@ -0,0 +1,364 @@
+"""Function caller classes for contract interactions.
+
+Provides FunctionCaller, OverloadedFunction, and ExplicitFunctionCaller classes.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from eth_abi import encode as abi_encode, decode as abi_decode
+
+from brawny._context import resolve_block_identifier
+from brawny.alerts.encoded_call import EncodedCall, FunctionABI, ReturnValue
+from brawny.alerts.errors import (
+    AmbiguousOverloadError,
+    ContractCallError,
+    OverloadMatchError,
+)
+
+if TYPE_CHECKING:
+    from brawny.alerts.contracts import ContractHandle
+    from brawny.jobs.base import TxReceipt
+
+
+class FunctionCaller:
+    """Callable wrapper for contract functions with Brownie-style interface.
+
+    Behavior varies by function state mutability:
+    - View/pure functions: __call__ executes eth_call, returns decoded value
+    - State-changing functions:
+        - With {"from": ...} as last arg: broadcasts transaction, returns receipt
+        - Without tx_params: returns EncodedCall (calldata with modifiers)
+
+    Methods:
+    - encode_input(*args): Get calldata without executing
+    - call(*args): Force eth_call simulation
+    - transact(*args, tx_params): Broadcast transaction
+
+    Usage (Brownie-style):
+        token.balanceOf(owner)  # View - returns value
+        token.transfer(to, amount, {"from": accounts[0]})  # Broadcasts, returns receipt
+        token.transfer(to, amount)  # Returns EncodedCall (calldata)
+    """
+
+    def __init__(
+        self,
+        contract: "ContractHandle",
+        function_abi: FunctionABI,
+    ) -> None:
+        self._contract = contract
+        self._abi = function_abi
+
+    def __call__(self, *args: Any, block_identifier: int | str | None = None) -> Any:
+        """Call the function with automatic state mutability handling.
+
+        For view/pure functions: executes eth_call and returns decoded result.
+        For state-changing functions:
+            - With tx_params dict (Brownie-style): broadcasts and returns receipt
+            - Without tx_params: returns EncodedCall for deferred execution
+
+        Args:
+            *args: Function arguments. For state-changing functions, may include
+                   tx_params dict as last argument (Brownie-style).
+            block_identifier: Optional block number/tag override for view calls.
+                             If None, uses handle's block or "latest".
+
+        Usage:
+            # View function - returns value directly
+            decimals = token.decimals()  # 18
+            decimals = token.decimals(block_identifier=21000000)  # at specific block
+
+            # State-changing function - Brownie-style (broadcasts immediately)
+            receipt = token.transfer(to, amount, {"from": accounts[0]})
+
+            # State-changing function - returns EncodedCall (for calldata)
+            calldata = vault.harvest()  # "0x4641257d"
+
+            # EncodedCall can be used as calldata or with modifiers
+            result = vault.harvest().call()  # Simulate
+            receipt = vault.harvest().transact({"from": "worker"})  # Broadcast
+        """
+        if self._abi.is_state_changing:
+            # Check if last arg is tx_params dict (Brownie-style immediate broadcast)
+            if args and isinstance(args[-1], dict) and "from" in args[-1]:
+                tx_params = args[-1]
+                func_args = args[:-1]
+                calldata = self._encode_calldata(*func_args)
+                return self._contract._transact_with_calldata(calldata, tx_params, self._abi)
+
+            # No tx_params - return EncodedCall for calldata or deferred .transact()
+            calldata = self._encode_calldata(*args)
+            return EncodedCall(calldata, self._contract, self._abi)
+
+        # View/pure functions execute immediately
+        return self._execute_call(*args, block_identifier=block_identifier)
+
+    def encode_input(self, *args: Any) -> str:
+        """Encode function calldata without executing.
+
+        Works for any function regardless of state mutability.
+
+        Usage:
+            data = vault.harvest.encode_input()
+            data = token.transfer.encode_input(recipient, amount)
+
+        Returns:
+            Hex-encoded calldata string
+        """
+        return self._encode_calldata(*args)
+
+    def call(self, *args: Any, block_identifier: int | str | None = None) -> Any:
+        """Force eth_call simulation and return decoded result.
+
+        Works for any function regardless of state mutability.
+        Useful for simulating state-changing functions without broadcasting.
+
+        Args:
+            *args: Function arguments
+            block_identifier: Optional block number/tag override.
+                             If None, uses handle's block or "latest".
+
+        Usage:
+            # Simulate state-changing function
+            result = vault.harvest.call()
+
+            # Also works for view functions (same as direct call)
+            decimals = token.decimals.call()
+
+            # Query at specific block
+            decimals = token.decimals.call(block_identifier=21000000)
+
+        Returns:
+            Decoded return value from the function
+        """
+        return self._execute_call(*args, block_identifier=block_identifier)
+
+    def transact(self, *args: Any) -> "TxReceipt":
+        """Broadcast the transaction and wait for receipt.
+
+        Only works inside a @broadcast decorated function.
+        Transaction params dict must be the last argument.
+
+        Usage:
+            # No-arg function
+            receipt = vault.harvest.transact({"from": "yearn-worker"})
+
+            # With function args (tx_params is last)
+            receipt = token.transfer.transact(recipient, amount, {"from": "worker"})
+
+        Args:
+            *args: Function arguments, with tx_params dict as last arg
+
+        Returns:
+            Transaction receipt after confirmation
+
+        Raises:
+            BroadcastNotAllowedError: If not in @broadcast context
+            ValueError: If tx_params dict not provided
+        """
+        # Extract tx_params from last arg
+        if not args or not isinstance(args[-1], dict):
+            raise ValueError(
+                f"{self._abi.name}.transact() requires tx_params dict as last argument. "
+                f"Example: vault.{self._abi.name}.transact({{\"from\": \"signer\"}})"
+            )
+
+        tx_params = args[-1]
+        func_args = args[:-1]
+
+        # Encode calldata and delegate to contract helper
+        calldata = self._encode_calldata(*func_args)
+        return self._contract._transact_with_calldata(calldata, tx_params, self._abi)
+
+    def _execute_call(self, *args: Any, block_identifier: int | str | None = None) -> Any:
+        """Execute eth_call and decode result.
+
+        Args:
+            *args: Function arguments
+            block_identifier: Optional block override. If None, uses handle's block or "latest".
+        """
+        rpc = self._contract._system.rpc
+
+        # Encode call data
+        calldata = self._encode_calldata(*args)
+
+        # Build tx params for eth_call
+        tx_params = {
+            "to": self._contract.address,
+            "data": calldata,
+        }
+
+        # Resolve block using centralized 4-level precedence:
+        # 1. Explicit param  2. Handle's block  3. Check scope pin  4. "latest"
+        block_id = resolve_block_identifier(
+            explicit=block_identifier,
+            handle_block=self._contract._block_identifier,
+        )
+
+        # Execute call with block pinning
+        try:
+            result = rpc.eth_call(tx_params, block_identifier=block_id)
+        except Exception as e:
+            raise ContractCallError(
+                function_name=self._abi.name,
+                address=self._contract.address,
+                reason=str(e),
+                block_identifier=self._contract._block_identifier,
+                signature=self._abi.signature,
+                job_id=self._contract._job_id,
+                hook=self._contract._hook,
+            )
+
+        # Convert result to hex string if bytes
+        if isinstance(result, bytes):
+            result = "0x" + result.hex()
+
+        # Decode result
+        return self._decode_result(result)
+
+    def _encode_calldata(self, *args: Any) -> str:
+        """Encode function call data."""
+        if not self._abi.inputs:
+            return "0x" + self._abi.selector.hex()
+
+        # Convert floats to ints (supports scientific notation like 1e18)
+        converted_args = [int(a) if isinstance(a, float) else a for a in args]
+        types = [inp["type"] for inp in self._abi.inputs]
+        encoded_args = abi_encode(types, converted_args)
+        return "0x" + self._abi.selector.hex() + encoded_args.hex()
+
+    def _decode_result(self, result: str) -> Any:
+        """Decode function return value with Brownie-compatible wrapping."""
+        if not self._abi.outputs:
+            return None
+
+        if result == "0x" or not result:
+            return None
+
+        if isinstance(result, str) and result.startswith("0x0x"):
+            result = "0x" + result[4:]
+
+        # Remove 0x prefix
+        data = bytes.fromhex(result[2:] if result.startswith("0x") else result)
+        if not data:
+            return None
+
+        types = [out["type"] for out in self._abi.outputs]
+        decoded = abi_decode(types, data)
+
+        # Single return value
+        if len(decoded) == 1:
+            # If it's a struct, wrap it so nested fields are accessible
+            if self._abi.outputs[0].get("components"):
+                return ReturnValue(decoded, self._abi.outputs)[0]
+            return decoded[0]
+
+        # Multiple return values: wrap in ReturnValue for named access
+        return ReturnValue(decoded, self._abi.outputs)
+
+
+class OverloadedFunction:
+    """Dispatcher for overloaded contract functions.
+
+    Resolves the correct overload based on argument count and delegates
+    to FunctionCaller. If multiple overloads match, raises AmbiguousOverloadError.
+    """
+
+    def __init__(self, contract: "ContractHandle", overloads: list[FunctionABI]) -> None:
+        self._contract = contract
+        self._overloads = overloads
+
+    def __call__(self, *args: Any) -> Any:
+        # Check if last arg is tx_params dict (Brownie-style)
+        if args and isinstance(args[-1], dict) and "from" in args[-1]:
+            tx_params = args[-1]
+            func_args = args[:-1]
+            caller = self._resolve(func_args)  # Resolve based on func_args count
+            return caller(*func_args, tx_params)  # FunctionCaller handles tx_params
+        else:
+            caller = self._resolve(args)
+            return caller(*args)
+
+    def call(self, *args: Any) -> Any:
+        caller = self._resolve(args)
+        return caller.call(*args)
+
+    def encode_input(self, *args: Any) -> str:
+        caller = self._resolve(args)
+        return caller.encode_input(*args)
+
+    def transact(self, *args: Any) -> "TxReceipt":
+        caller, func_args = self._resolve_for_transact(args)
+        return caller.transact(*func_args)
+
+    def _resolve(self, args: tuple[Any, ...]) -> FunctionCaller:
+        matches = [f for f in self._overloads if len(f.inputs) == len(args)]
+        if not matches:
+            candidates = [f.signature for f in self._overloads]
+            raise OverloadMatchError(
+                self._overloads[0].name,
+                len(args),
+                candidates,
+            )
+        if len(matches) > 1:
+            candidates = [f.signature for f in matches]
+            raise AmbiguousOverloadError(
+                self._overloads[0].name,
+                len(args),
+                candidates,
+            )
+        return FunctionCaller(self._contract, matches[0])
+
+    def _resolve_for_transact(
+        self, args: tuple[Any, ...]
+    ) -> tuple[FunctionCaller, tuple[Any, ...]]:
+        if not args or not isinstance(args[-1], dict):
+            raise ValueError(
+                f"{self._overloads[0].name}.transact() requires tx_params dict as last argument."
+            )
+        func_args = args[:-1]
+        caller = self._resolve(func_args)
+        return caller, args
+
+
+class ExplicitFunctionCaller:
+    """Explicit function caller for overloaded functions.
+
+    Usage:
+        token.fn("balanceOf(address)").call(owner)
+        token.fn("transfer(address,uint256)").transact(to, amount, {"from": "worker"})
+    """
+
+    def __init__(
+        self,
+        contract: "ContractHandle",
+        function_abi: FunctionABI,
+    ) -> None:
+        self._contract = contract
+        self._abi = function_abi
+
+    def call(self, *args: Any) -> Any:
+        """Execute eth_call and return decoded result.
+
+        Works for both view and state-changing functions (simulates the call).
+        """
+        caller = FunctionCaller(self._contract, self._abi)
+        return caller._execute_call(*args)
+
+    def transact(self, *args: Any) -> "TxReceipt":
+        """Broadcast the transaction and wait for receipt.
+
+        Only works inside a @broadcast decorated function.
+        Transaction params dict must be the last argument.
+        """
+        caller = FunctionCaller(self._contract, self._abi)
+        return caller.transact(*args)
+
+    def encode_input(self, *args: Any) -> str:
+        """Encode function call data without executing.
+
+        Returns hex-encoded calldata.
+        """
+        caller = FunctionCaller(self._contract, self._abi)
+        return caller._encode_calldata(*args)

brawny/alerts/health.py

@@ -0,0 +1,185 @@
+"""Daemon health alerts with fingerprint-based deduplication."""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from datetime import datetime, timedelta
+from typing import Any, Callable, Literal
+
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_COOLDOWN_SECONDS = 1800
+MAX_FIELD_LEN = 200
+
+_last_fired: dict[str, datetime] = {}
+_first_seen: dict[str, datetime] = {}
+_suppressed_count: dict[str, int] = {}
+_lock = threading.Lock()
+
+
+def _fingerprint(
+    component: str,
+    exc_type: str,
+    chain_id: int,
+    db_dialect: str | None = None,
+    fingerprint_key: str | None = None,
+) -> str:
+    """Compute stable fingerprint for deduplication.
+
+    Default: component + exc_type + chain_id + db_dialect (message excluded for stability).
+    Override with fingerprint_key for explicit grouping (e.g., invariant names).
+    """
+    if fingerprint_key:
+        key = f"{fingerprint_key}:{chain_id}:{db_dialect or 'unknown'}"
+    else:
+        key = f"{component}:{exc_type}:{chain_id}:{db_dialect or 'unknown'}"
+    return hashlib.sha1(key.encode()).hexdigest()[:12]
+
+
+def health_alert(
+    *,
+    component: str,
+    chain_id: int,
+    error: Exception | str,
+    level: Literal["warning", "error", "critical"] = "error",
+    job_id: str | None = None,
+    intent_id: str | None = None,
+    claim_token: str | None = None,
+    status: str | None = None,
+    action: str | None = None,
+    db_dialect: str | None = None,
+    fingerprint_key: str | None = None,
+    force_send: bool = False,
+    send_fn: Callable[..., None] | None = None,
+    health_chat_id: str | None = None,
+    cooldown_seconds: int = DEFAULT_COOLDOWN_SECONDS,
+) -> None:
+    """Send a daemon health alert with deduplication.
+
+    First occurrence: sends immediately (if level >= error).
+    Within cooldown: suppressed, count incremented.
+    After cooldown: sends summary with suppressed count + duration.
+    Warnings are logged only, never sent to Telegram.
+
+    Args:
+        component: Component identifier (e.g., "brawny.tx.executor")
+        chain_id: Chain ID for context
+        error: Exception or error message
+        level: Severity level (warning, error, critical)
+        job_id: Optional job identifier
+        intent_id: Optional intent identifier
+        claim_token: Optional claim token for debugging stuckness
+        status: Optional intent status for debugging
+        action: Suggested remediation action
+        db_dialect: Database dialect for fingerprinting
+        fingerprint_key: Override default fingerprint for explicit grouping
+        force_send: Bypass deduplication entirely (e.g., startup alerts)
+        send_fn: Function to send alerts (e.g., alerts.send.send_health)
+        health_chat_id: Telegram chat ID for health alerts
+        cooldown_seconds: Deduplication window in seconds
+    """
+    exc_type = type(error).__name__ if isinstance(error, Exception) else "Error"
+    message = str(error)[:MAX_FIELD_LEN]
+    fp = _fingerprint(component, exc_type, chain_id, db_dialect, fingerprint_key)
+
+    now = datetime.utcnow()
+    should_send = False
+    suppressed = 0
+    first_seen = now
+
+    if force_send:
+        should_send = True
+    else:
+        with _lock:
+            last = _last_fired.get(fp)
+            if last is None:
+                # First occurrence
+                should_send = True
+                _last_fired[fp] = now
+                _first_seen[fp] = now
+                _suppressed_count[fp] = 0
+            elif now - last > timedelta(seconds=cooldown_seconds):
+                # Cooldown expired, send summary
+                should_send = True
+                suppressed = _suppressed_count.get(fp, 0)
+                first_seen = _first_seen.get(fp, now)
+                _last_fired[fp] = now
+                _first_seen[fp] = now  # Reset for next incident window
+                _suppressed_count[fp] = 0
+            else:
+                # Within cooldown, suppress
+                _suppressed_count[fp] = _suppressed_count.get(fp, 0) + 1
+
+    # Always log (use appropriate log level)
+    if level == "critical":
+        log_fn = logger.critical
+    elif level == "warning":
+        log_fn = logger.warning
+    else:
+        log_fn = logger.error
+
+    log_fn(
+        "daemon.health_alert",
+        component=component,
+        chain_id=chain_id,
+        error=message,
+        exc_type=exc_type,
+        level=level,
+        job_id=job_id,
+        intent_id=intent_id,
+        claim_token=claim_token,
+        status=status,
+        fingerprint=fp,
+        suppressed=not should_send,
+    )
+
+    # Warnings are logged only, never sent to Telegram
+    if level == "warning":
+        return
+
+    if not should_send:
+        return
+
+    if send_fn is None or health_chat_id is None:
+        return
+
+    # Build message (cap all fields)
+    lines = ["⚠️ Brawny Health Alert" if level == "error" else "🔴 CRITICAL Health Alert"]
+    lines.append(f"chain_id={chain_id}")
+    if job_id:
+        lines.append(f"job={job_id[:MAX_FIELD_LEN]}")
+    if intent_id:
+        lines.append(f"intent={intent_id[:12]}...")
+    if claim_token:
+        lines.append(f"claim_token={claim_token[:12]}...")
+    if status:
+        lines.append(f"status={status}")
+    lines.append(f"{exc_type}: {message}")
+    if suppressed > 0:
+        duration_seconds = (now - first_seen).total_seconds()
+        duration_str = f"{duration_seconds / 60:.0f}m" if duration_seconds >= 60 else f"{duration_seconds:.0f}s"
+        lines.append(f"(suppressed {suppressed}x over {duration_str})")
+    if action:
+        lines.append(f"Action: {action[:MAX_FIELD_LEN]}")
+
+    try:
+        send_fn(chat_id=health_chat_id, text="\n".join(lines))
+    except Exception as e:
+        logger.warning("health_alert.send_failed", error=str(e))
+
+
+def cleanup_stale_fingerprints(cooldown_seconds: int = DEFAULT_COOLDOWN_SECONDS) -> int:
+    """Remove fingerprints older than 2x cooldown. Returns count removed."""
+    cutoff = datetime.utcnow() - timedelta(seconds=cooldown_seconds * 2)
+    removed = 0
+    with _lock:
+        stale = [fp for fp, ts in _last_fired.items() if ts < cutoff]
+        for fp in stale:
+            _last_fired.pop(fp, None)
+            _first_seen.pop(fp, None)
+            _suppressed_count.pop(fp, None)
+            removed += 1
+    return removed

brawny/alerts/routing.py

@@ -0,0 +1,118 @@
+"""Alert routing resolution.
+
+Resolves named targets to chat IDs for Telegram alerts.
+Could be extended for webhooks later.
+
+Policy: Startup fails hard, runtime logs + drops.
+- Startup validation catches typos during normal deployment
+- Runtime unknown names log error and are skipped (not raised)
+- This prevents hot-edited typos from crashing hook execution
+"""
+
+from __future__ import annotations
+
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def is_chat_id(s: str) -> bool:
+    """Check if string looks like a raw Telegram chat ID.
+
+    Handles:
+    - Supergroups/channels: -100...
+    - Basic groups: negative ints -12345
+    - User IDs: positive ints
+    """
+    return s.lstrip("-").isdigit()
+
+
+def resolve_targets(
+    target: str | list[str] | None,
+    chats: dict[str, str],
+    default: list[str],
+    *,
+    job_id: str | None = None,
+) -> list[str]:
+    """Resolve target(s) to deduplicated list of chat IDs.
+
+    Policy: Startup fails hard, runtime logs + drops.
+    - Startup validation catches typos during normal deployment
+    - Runtime unknown names log error and are skipped (not raised)
+    - This prevents hot-edited typos from crashing hook execution
+
+    Args:
+        target: Chat name, raw ID, list of either, or None
+        chats: Name -> chat_id mapping from config
+        default: Default chat names/IDs if target is None
+        job_id: Optional job ID for logging context
+
+    Returns:
+        Deduplicated list of resolved chat IDs (preserves order).
+        Unknown names are logged and skipped, not raised.
+    """
+    if target is None:
+        targets = default
+    elif isinstance(target, str):
+        targets = [target]
+    else:
+        targets = target
+
+    # Resolve names to IDs, dedupe while preserving order
+    seen: set[str] = set()
+    result: list[str] = []
+
+    for t in targets:
+        t = t.strip()
+        if not t:
+            continue
+
+        # Resolve: raw ID passes through, named chat looks up, unknown logs + skips
+        if is_chat_id(t):
+            chat_id = t
+        elif t in chats:
+            chat_id = chats[t]
+        else:
+            # Log and skip unknown names (don't crash hooks at runtime)
+            logger.error(
+                "alert.routing.unknown_target",
+                target=t,
+                job_id=job_id,
+                valid_names=sorted(chats.keys()),
+            )
+            continue
+
+        if chat_id not in seen:
+            seen.add(chat_id)
+            result.append(chat_id)
+
+    return result
+
+
+def validate_targets(
+    target: str | list[str] | None,
+    valid_names: set[str],
+) -> list[str]:
+    """Validate that all non-ID targets are valid chat names.
+
+    Used at startup for hard failure on unknown names.
+
+    Args:
+        target: Chat name, raw ID, list of either, or None
+        valid_names: Set of valid chat names from config
+
+    Returns:
+        List of invalid names (empty if all valid)
+    """
+    if target is None:
+        return []
+
+    targets = [target] if isinstance(target, str) else target
+    invalid: list[str] = []
+
+    for t in targets:
+        t = t.strip()
+        if t and not is_chat_id(t) and t not in valid_names:
+            invalid.append(t)
+
+    return invalid