brawny 0.1.13__py3-none-any.whl

brawny/alerts/encoded_call.py

@@ -0,0 +1,201 @@
+"""Encoded call types for contract interactions.
+
+Provides EncodedCall, ReturnValue, and FunctionABI classes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from brawny.alerts.contracts import ContractHandle
+    from brawny.jobs.base import TxReceipt
+
+
+@dataclass
+class FunctionABI:
+    """Parsed function ABI entry."""
+
+    name: str
+    inputs: list[dict[str, Any]]
+    outputs: list[dict[str, Any]]
+    state_mutability: str
+    signature: str
+    selector: bytes
+
+    @property
+    def is_view(self) -> bool:
+        """Check if function is view or pure (read-only)."""
+        return self.state_mutability in ("view", "pure")
+
+    @property
+    def is_state_changing(self) -> bool:
+        """Check if function modifies state."""
+        return self.state_mutability in ("nonpayable", "payable")
+
+    @property
+    def is_payable(self) -> bool:
+        """Check if function accepts ETH value."""
+        return self.state_mutability == "payable"
+
+
+class ReturnValue(tuple):
+    """Tuple with named field access for contract return values.
+
+    Brownie-compatible: prints as tuple, supports named access.
+
+    Supports multiple access patterns:
+        result[0]              # Index access
+        result["fieldName"]    # Dict-style access
+        result.fieldName       # Attribute access
+        result.keys()          # Get field names
+        result.items()         # Get (name, value) pairs
+        dict(result.items())   # Convert to dict
+    """
+
+    _names: tuple[str, ...]
+    _dict: dict[str, Any]
+
+    def __new__(
+        cls, values: tuple | list, abi: list[dict[str, Any]] | None = None
+    ) -> "ReturnValue":
+        values = list(values)
+
+        # Recursively wrap nested tuples based on ABI components
+        if abi is not None:
+            for i in range(len(values)):
+                if isinstance(values[i], (tuple, list)) and not isinstance(
+                    values[i], ReturnValue
+                ):
+                    if "components" in abi[i]:
+                        components = abi[i]["components"]
+                        if abi[i]["type"] == "tuple":
+                            # Single struct
+                            values[i] = ReturnValue(values[i], components)
+                        else:
+                            # Array of structs - wrap each element, keep as list
+                            values[i] = [ReturnValue(v, components) for v in values[i]]
+
+        instance = super().__new__(cls, values)
+
+        # Build names from ABI or use fallback (arg0, arg1 - no brackets for attr access)
+        if abi is not None:
+            names = tuple(out.get("name") or f"arg{i}" for i, out in enumerate(abi))
+        else:
+            names = tuple(f"arg{i}" for i in range(len(values)))
+
+        object.__setattr__(instance, "_names", names)
+        object.__setattr__(instance, "_dict", dict(zip(names, values)))
+        return instance
+
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            try:
+                return self._dict[key]
+            except KeyError:
+                raise KeyError(f"No field '{key}'. Available: {list(self._names)}")
+        return super().__getitem__(key)
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return self._dict[name]
+        except KeyError:
+            raise AttributeError(f"No field '{name}'. Available: {list(self._names)}")
+
+    def keys(self) -> tuple[str, ...]:
+        """Return output names."""
+        return self._names
+
+    def items(self):
+        """Return (name, value) pairs."""
+        return self._dict.items()
+
+    def dict(self) -> dict[str, object]:
+        """Convert to dict, recursively unwrapping nested ReturnValues."""
+
+        def _norm(x: object) -> object:
+            if isinstance(x, ReturnValue):
+                return x.dict()
+            if isinstance(x, list):
+                return [_norm(v) for v in x]
+            return x
+
+        return {k: _norm(v) for k, v in self._dict.items()}
+
+    # Use tuple's __repr__ for Brownie parity: prints as (val1, val2)
+    __repr__ = tuple.__repr__
+
+
+class EncodedCall(str):
+    """Encoded calldata with .call() and .transact() methods.
+
+    This is a str subclass so it can be used directly as calldata,
+    while also providing Brownie-style modifiers for execution.
+
+    Usage:
+        # Get calldata (str)
+        calldata = vault.harvest()
+
+        # Force eth_call simulation
+        result = vault.harvest().call()
+
+        # Broadcast transaction (only in @broadcast context)
+        receipt = vault.harvest().transact({"from": "yearn-worker"})
+    """
+
+    _contract: "ContractHandle"
+    _abi: FunctionABI
+
+    def __new__(
+        cls,
+        calldata: str,
+        contract: "ContractHandle",
+        abi: FunctionABI,
+    ) -> "EncodedCall":
+        instance = super().__new__(cls, calldata)
+        instance._contract = contract
+        instance._abi = abi
+        return instance
+
+    def call(self) -> Any:
+        """Execute eth_call and return decoded result.
+
+        Performs a static call (simulation) without broadcasting.
+        Works regardless of function state mutability.
+
+        Returns:
+            Decoded return value from the function
+        """
+        return self._contract._call_with_calldata(str(self), self._abi)
+
+    def transact(self, tx_params: dict[str, Any] | None = None) -> "TxReceipt":
+        """Broadcast the transaction and wait for receipt.
+
+        Only works inside a @broadcast decorated function.
+        Raises BroadcastNotAllowedError if not in broadcast context.
+
+        Args:
+            tx_params: Transaction parameters (Brownie-style)
+                - from: Signer name or address (required)
+                - value: ETH value to send (optional, for payable functions)
+                - gas: Gas limit (optional, auto-estimated if not provided)
+                - gasPrice: Gas price (optional)
+                - maxFeePerGas: EIP-1559 max fee (optional)
+                - maxPriorityFeePerGas: EIP-1559 priority fee (optional)
+                - nonce: Transaction nonce (optional, auto-fetched if not provided)
+
+        Returns:
+            Transaction receipt after confirmation
+
+        Raises:
+            BroadcastNotAllowedError: If not in @broadcast context
+            SignerNotFoundError: If 'from' address not in keystore
+            TransactionRevertedError: If transaction reverts
+            TransactionTimeoutError: If receipt wait times out
+        """
+        if tx_params is None:
+            tx_params = {}
+        return self._contract._transact_with_calldata(str(self), tx_params, self._abi)

brawny/alerts/errors.py

@@ -0,0 +1,267 @@
+"""alerts-specific error classes for the Alerts extension.
+
+These errors provide clear, actionable feedback when developers
+misuse the contract interaction APIs in alert hooks.
+"""
+
+from __future__ import annotations
+
+
+class DXError(Exception):
+    """Base class for all alerts-related errors."""
+
+    pass
+
+
+class ABINotFoundError(DXError):
+    """Raised when ABI cannot be resolved for a contract address.
+
+    Includes details about which sources were checked.
+    """
+
+    def __init__(self, address: str, checked_sources: list[str]) -> None:
+        self.address = address
+        self.checked_sources = checked_sources
+        sources_str = ", ".join(checked_sources) if checked_sources else "none"
+        super().__init__(
+            f"ABI not found for {address}. Checked: {sources_str}. "
+            f"Consider setting ABI manually with 'brawny abi set {address} --file abi.json'"
+        )
+
+
+class ProxyResolutionError(DXError):
+    """Raised when proxy resolution fails.
+
+    This can happen when:
+    - EIP-1967 slots don't contain valid addresses
+    - Beacon implementation call fails
+    - Max recursion depth exceeded
+    """
+
+    def __init__(self, address: str, reason: str) -> None:
+        self.address = address
+        self.reason = reason
+        super().__init__(f"Failed to resolve proxy {address}: {reason}")
+
+
+class StateChangingCallError(DXError):
+    """Raised when attempting to call a state-changing function.
+
+    State-changing functions (nonpayable/payable) cannot be called
+    via eth_call in alert hooks. Use .encode_input() or .transact() in @broadcast.
+    """
+
+    def __init__(
+        self,
+        function_name: str,
+        signature: str,
+        address: str | None = None,
+        job_id: str | None = None,
+        hook: str | None = None,
+    ) -> None:
+        self.function_name = function_name
+        self.signature = signature
+        self.address = address
+        self.job_id = job_id
+        self.hook = hook
+        context = _format_context(job_id, hook, address, signature)
+        super().__init__(
+            f"{function_name}() is a state-changing function{context}. "
+            f"Use .encode_input() for calldata or .transact(...) inside @broadcast."
+        )
+
+
+class ReceiptRequiredError(DXError):
+    """Raised when accessing events without a receipt context.
+
+    Events are only available in alert_confirmed hook where
+    ctx.receipt is populated.
+    """
+
+    def __init__(self, operation: str = "Events") -> None:
+        self.operation = operation
+        super().__init__(
+            f"{operation} are only available in alert_confirmed context where receipt is present. "
+            f"For other hooks, use ctx.block for current block information."
+        )
+
+
+class EventNotFoundError(DXError):
+    """Raised when expected event is not found in receipt logs.
+
+    Provides helpful information about what events are available.
+    """
+
+    def __init__(
+        self,
+        event_name: str,
+        address: str,
+        available_events: list[str],
+    ) -> None:
+        self.event_name = event_name
+        self.address = address
+        self.available_events = available_events
+        available_str = ", ".join(available_events) if available_events else "none"
+        super().__init__(
+            f"No '{event_name}' events found in receipt for {address}. "
+            f"Available decoded events: [{available_str}]"
+        )
+
+
+class AmbiguousOverloadError(DXError):
+    """Raised when function call matches multiple ABI overloads.
+
+    Provides guidance on using explicit signatures.
+    """
+
+    def __init__(
+        self,
+        function_name: str,
+        arg_count: int,
+        candidates: list[str],
+    ) -> None:
+        self.function_name = function_name
+        self.arg_count = arg_count
+        self.candidates = candidates
+        candidates_str = ", ".join(candidates)
+        super().__init__(
+            f"Multiple matches for '{function_name}' with {arg_count} argument(s). "
+            f"Candidates: {candidates_str}. "
+            f"Use explicit signature: contract.fn(\"{candidates[0]}\").call(...) "
+            f"or contract.fn(\"{candidates[0]}\").transact(...)."
+        )
+
+
+class OverloadMatchError(DXError):
+    """Raised when no overload matches the provided arguments."""
+
+    def __init__(
+        self,
+        function_name: str,
+        arg_count: int,
+        candidates: list[str],
+    ) -> None:
+        self.function_name = function_name
+        self.arg_count = arg_count
+        self.candidates = candidates
+        candidates_str = ", ".join(candidates)
+        super().__init__(
+            f"No overload of '{function_name}' matches {arg_count} argument(s). "
+            f"Available: {candidates_str}. "
+            f"Use explicit signature: contract.fn(\"{candidates[0]}\").call(...)."
+        )
+
+
+class FunctionNotFoundError(DXError):
+    """Raised when function is not found in contract ABI."""
+
+    def __init__(
+        self,
+        function_name: str,
+        address: str,
+        available_functions: list[str] | None = None,
+    ) -> None:
+        self.function_name = function_name
+        self.address = address
+        self.available_functions = available_functions
+        if available_functions:
+            available_str = ", ".join(available_functions[:10])
+            if len(available_functions) > 10:
+                available_str += f" ... ({len(available_functions) - 10} more)"
+            msg = (
+                f"Function '{function_name}' not found in ABI for {address}. "
+                f"Available functions: [{available_str}]"
+            )
+        else:
+            msg = f"Function '{function_name}' not found in ABI for {address}."
+        super().__init__(msg)
+
+
+class InvalidAddressError(DXError):
+    """Raised when an invalid Ethereum address is provided."""
+
+    def __init__(self, address: str) -> None:
+        self.address = address
+        super().__init__(
+            f"Invalid Ethereum address: {address}. "
+            f"Address must be a 40-character hex string with 0x prefix."
+        )
+
+
+class EventDecodeError(DXError):
+    """Raised when event log cannot be decoded.
+
+    This typically happens when the log signature doesn't match
+    any known event in the ABI.
+    """
+
+    def __init__(self, log_index: int, topic0: str | None = None) -> None:
+        self.log_index = log_index
+        self.topic0 = topic0
+        if topic0:
+            super().__init__(
+                f"Failed to decode event at log index {log_index} "
+                f"with topic0 {topic0}. Event may not be in ABI."
+            )
+        else:
+            super().__init__(
+                f"Failed to decode event at log index {log_index}. "
+                f"Log has no topic0 (anonymous event)."
+            )
+
+
+class ContractCallError(DXError):
+    """Raised when a contract call fails.
+
+    Wraps underlying RPC errors with context about the call.
+    """
+
+    def __init__(
+        self,
+        function_name: str,
+        address: str,
+        reason: str,
+        block_identifier: int | str | None = None,
+        signature: str | None = None,
+        job_id: str | None = None,
+        hook: str | None = None,
+    ) -> None:
+        self.function_name = function_name
+        self.address = address
+        self.reason = reason
+        self.block_identifier = block_identifier
+        self.signature = signature
+        self.job_id = job_id
+        self.hook = hook
+        block_str = f" at block {block_identifier}" if block_identifier else ""
+        context = _format_context(job_id, hook, address, signature)
+        super().__init__(
+            f"Call to {function_name}() on {address}{block_str}{context} failed: {reason}"
+        )
+
+
+def _format_context(
+    job_id: str | None,
+    hook: str | None,
+    address: str | None,
+    signature: str | None,
+) -> str:
+    parts = []
+    if job_id:
+        parts.append(f"job={job_id}")
+    if hook:
+        parts.append(f"hook={hook}")
+    if signature:
+        parts.append(f"sig={signature}")
+    if not parts:
+        return ""
+    return f" ({', '.join(parts)})"
+
+
+class ABICacheError(DXError):
+    """Raised when ABI cache operations fail."""
+
+    def __init__(self, operation: str, reason: str) -> None:
+        self.operation = operation
+        self.reason = reason
+        super().__init__(f"ABI cache {operation} failed: {reason}")