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

brawny/_rpc/retry.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import time
+import threading
+from typing import Any, Callable
+
+from cachetools import TTLCache
+
+from brawny._rpc.errors import (
+    RPCDeadlineExceeded,
+    RPCError,
+    RPCFatalError,
+    RPCPoolExhaustedError,
+    RpcErrorKind,
+)
+from brawny._rpc.retry_policy import RetryPolicy
+from brawny._rpc.pool import EndpointPool
+from brawny._rpc.caller import Caller
+from brawny._rpc.context import get_intent_budget_context, get_job_context
+from brawny.metrics import (
+    RPC_CALL_TIMEOUTS,
+    RPC_ERRORS,
+    RPC_FAILOVERS,
+    RPC_REQUESTS,
+    RPC_REQUESTS_BY_JOB,
+    RPC_REQUEST_SECONDS,
+    get_metrics,
+)
+from brawny.timeout import Deadline
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+# High cardinality keys (intent budget keys): maxsize=10K, ttl=15min
+_unknown_budget_counts: TTLCache[str, int] = TTLCache(maxsize=10_000, ttl=900)
+_unknown_budget_lock = threading.Lock()
+_MAX_UNKNOWN_RETRIES_PER_INTENT = 2
+
+
+def _unknown_budget_exhausted(budget_key: str | None) -> bool:
+    if not budget_key:
+        return False
+    with _unknown_budget_lock:
+        current = _unknown_budget_counts.get(budget_key, 0)
+        if current >= _MAX_UNKNOWN_RETRIES_PER_INTENT:
+            return True
+        _unknown_budget_counts[budget_key] = current + 1
+        return False
+
+
+def call_with_retries(
+    pool: EndpointPool,
+    caller: Caller,
+    policy: RetryPolicy,
+    method: str,
+    args: tuple[Any, ...],
+    *,
+    timeout: float,
+    deadline: Deadline | None,
+    block_identifier: int | str,
+    chain_id: int | None,
+    request_id: str,
+    bound: bool,
+    attempt_event: str = "rpc.attempt",
+    allowed_hosts: frozenset[str] | None = None,
+    return_endpoint: bool = False,
+) -> Any:
+    endpoints = pool.order_endpoints()
+    attempts_to_try = min(policy.max_attempts, len(endpoints))
+    if attempts_to_try <= 0:
+        raise RPCPoolExhaustedError("No endpoints available for call", endpoints=[], last_error=None)
+
+    metrics = get_metrics()
+    last_error: Exception | None = None
+
+    for attempt, endpoint in enumerate(endpoints[:attempts_to_try], start=1):
+        if deadline is not None and deadline.expired():
+            metrics.counter(RPC_CALL_TIMEOUTS).inc(
+                chain_id=chain_id,
+                method=method,
+                rpc_category=_rpc_category(method),
+                rpc_host=_rpc_host(endpoint, allowed_hosts),
+            )
+            raise RPCDeadlineExceeded(
+                "RPC deadline exhausted before call",
+                code="deadline_exceeded",
+                method=method,
+                endpoint=endpoint,
+            )
+
+        effective_timeout = timeout
+        if deadline is not None:
+            remaining = deadline.remaining()
+            if remaining <= 0:
+                metrics.counter(RPC_CALL_TIMEOUTS).inc(
+                    chain_id=chain_id,
+                    method=method,
+                    rpc_category=_rpc_category(method),
+                    rpc_host=_rpc_host(endpoint, allowed_hosts),
+                )
+                raise RPCDeadlineExceeded(
+                    "RPC deadline exhausted before call",
+                    code="deadline_exceeded",
+                    method=method,
+                    endpoint=endpoint,
+                )
+            effective_timeout = min(timeout, remaining)
+
+        metrics.counter(RPC_REQUESTS).inc(
+            chain_id=chain_id,
+            method=method,
+            rpc_category=_rpc_category(method),
+            rpc_host=_rpc_host(endpoint, allowed_hosts),
+        )
+        job_id = get_job_context()
+        if job_id:
+            metrics.counter(RPC_REQUESTS_BY_JOB).inc(
+                chain_id=chain_id,
+                job_id=job_id,
+                rpc_category=_rpc_category(method),
+            )
+
+        start_time = time.time()
+        try:
+            result = caller.call(
+                endpoint,
+                method,
+                args,
+                timeout=effective_timeout,
+                deadline=deadline,
+                block_identifier=block_identifier,
+            )
+            latency = time.time() - start_time
+            metrics.histogram(RPC_REQUEST_SECONDS).observe(
+                latency,
+                chain_id=chain_id,
+                method=method,
+                rpc_category=_rpc_category(method),
+                rpc_host=_rpc_host(endpoint, allowed_hosts),
+            )
+            log_fields = {
+                "chain_id": chain_id,
+                "endpoint": _safe_endpoint_label(endpoint),
+                "request_id": request_id,
+                "method": method,
+                "attempt": attempt,
+                "policy_name": policy.name,
+                "bound": bound,
+                "error_class": None,
+            }
+            if job_id:
+                log_fields["job_id"] = job_id
+            logger.info(attempt_event, **log_fields)
+            if return_endpoint:
+                return result, endpoint
+            return result
+        except RPCError as exc:
+            latency = time.time() - start_time
+            metrics.histogram(RPC_REQUEST_SECONDS).observe(
+                latency,
+                chain_id=chain_id,
+                method=method,
+                rpc_category=_rpc_category(method),
+                rpc_host=_rpc_host(endpoint, allowed_hosts),
+            )
+
+            error_class = type(exc)
+            should_retry = isinstance(exc, policy.retryable_error_classes)
+            failover_ok = getattr(exc, "failover_ok", True)
+            error_kind = getattr(exc, "classification_kind", None)
+            if error_kind == RpcErrorKind.UNKNOWN and _unknown_budget_exhausted(
+                get_intent_budget_context()
+            ):
+                logger.error(
+                    "rpc.unknown_budget_exhausted",
+                    budget_key=get_intent_budget_context(),
+                    method=method,
+                    endpoint=_safe_endpoint_label(endpoint),
+                )
+                raise RPCFatalError(
+                    "unknown_budget_exhausted",
+                    code="unknown_budget_exhausted",
+                    method=method,
+                    endpoint=endpoint,
+                ) from exc
+
+            log_fields = {
+                "chain_id": chain_id,
+                "endpoint": _safe_endpoint_label(endpoint),
+                "request_id": request_id,
+                "method": method,
+                "attempt": attempt,
+                "policy_name": policy.name,
+                "bound": bound,
+                "error_class": error_class.__name__,
+            }
+            if job_id:
+                log_fields["job_id"] = job_id
+            logger.info(attempt_event, **log_fields)
+
+            if not should_retry or not failover_ok:
+                raise
+
+            metrics.counter(RPC_ERRORS).inc(
+                chain_id=chain_id,
+                method=method,
+                rpc_category=_rpc_category(method),
+                rpc_host=_rpc_host(endpoint, allowed_hosts),
+            )
+            last_error = exc
+            if attempt < attempts_to_try:
+                metrics.counter(RPC_FAILOVERS).inc(chain_id=chain_id, method=method)
+                backoff = policy.backoff_seconds(attempt)
+                if backoff > 0:
+                    time.sleep(backoff)
+                continue
+        except Exception as exc:  # noqa: BLE001 - unexpected bug
+            log_fields = {
+                "chain_id": chain_id,
+                "endpoint": _safe_endpoint_label(endpoint),
+                "request_id": request_id,
+                "method": method,
+                "attempt": attempt,
+                "policy_name": policy.name,
+                "bound": bound,
+                "error_class": type(exc).__name__,
+                "exc_info": True,
+            }
+            if job_id:
+                log_fields["job_id"] = job_id
+            logger.error(attempt_event, **log_fields)
+            raise
+
+    raise RPCPoolExhaustedError(
+        f"All {attempts_to_try} attempts failed",
+        endpoints=endpoints[:attempts_to_try],
+        last_error=last_error,
+    )
+
+
+def _rpc_category(method: str) -> str:
+    return "broadcast" if method in {"eth_sendRawTransaction", "eth_sendTransaction"} else "read"
+
+
+def _rpc_host(url: str, allowed_hosts: frozenset[str] | None = None) -> str:
+    try:
+        split = url.split("://", 1)[1]
+    except IndexError:
+        return "unknown"
+    host = split.split("/", 1)[0]
+    host = host.split("@", 1)[-1]
+    host = host.split(":", 1)[0]
+    if allowed_hosts is not None and host not in allowed_hosts:
+        return "other"
+    return host or "unknown"
+
+
+def _safe_endpoint_label(url: str) -> str:
+    parts = url.split("://", 1)
+    if len(parts) == 2:
+        scheme, rest = parts
+    else:
+        scheme, rest = "http", parts[0]
+    host = rest.split("/", 1)[0]
+    host = host.split("@", 1)[-1]
+    return f"{scheme}://{host}"

brawny/_rpc/retry_policy.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import Iterable, Type
+
+from brawny._rpc.errors import RPCTransient, RPCRateLimited
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Simple retry policy for RPC calls.
+
+    attempt is 1-based (first attempt is 1).
+    """
+
+    name: str
+    max_attempts: int
+    base_backoff_seconds: float
+    max_backoff_seconds: float
+    jitter: bool
+    retryable_error_classes: tuple[type[BaseException], ...] = (RPCTransient, RPCRateLimited)
+
+    def should_retry(self, error_class: type[BaseException]) -> bool:
+        return issubclass(error_class, self.retryable_error_classes)
+
+    def backoff_seconds(self, attempt: int, *, rng: random.Random | None = None) -> float:
+        if attempt <= 0:
+            return 0.0
+        backoff = self.base_backoff_seconds * (2 ** (attempt - 1))
+        backoff = min(backoff, self.max_backoff_seconds)
+        if not self.jitter:
+            return backoff
+        rng = rng or random
+        jitter = rng.uniform(0.0, min(backoff * 0.1, max(self.max_backoff_seconds - backoff, 0.0)))
+        return min(backoff + jitter, self.max_backoff_seconds)
+
+
+def _default_max_backoff(max_attempts: int, base_backoff_seconds: float) -> float:
+    if max_attempts <= 0:
+        return base_backoff_seconds
+    return base_backoff_seconds * (2 ** (max_attempts - 1))
+
+
+def policy_from_values(
+    name: str,
+    *,
+    max_attempts: int,
+    base_backoff_seconds: float,
+    max_backoff_seconds: float | None = None,
+    jitter: bool = False,
+    retryable_error_classes: Iterable[type[BaseException]] | None = None,
+) -> RetryPolicy:
+    if max_backoff_seconds is None:
+        max_backoff_seconds = _default_max_backoff(max_attempts, base_backoff_seconds)
+    if retryable_error_classes is None:
+        retryable_error_classes = (RPCTransient, RPCRateLimited)
+    return RetryPolicy(
+        name=name,
+        max_attempts=max_attempts,
+        base_backoff_seconds=base_backoff_seconds,
+        max_backoff_seconds=max_backoff_seconds,
+        jitter=jitter,
+        retryable_error_classes=tuple(retryable_error_classes),
+    )
+
+
+def fast_read_policy(config) -> RetryPolicy:
+    return policy_from_values(
+        "FAST_READ",
+        max_attempts=config.rpc_max_retries,
+        base_backoff_seconds=config.rpc_retry_backoff_base,
+    )
+
+
+def broadcast_policy(config) -> RetryPolicy:
+    return policy_from_values(
+        "BROADCAST",
+        max_attempts=config.rpc_max_retries,
+        base_backoff_seconds=config.rpc_retry_backoff_base,
+    )

brawny/accounts.py

@@ -9,9 +9,11 @@ Usage:
     # Load by name (prompts for password if needed)
     acct = accounts.load("my_wallet")
 
-    # Add new account (generates mnemonic if no key provided)
-    acct = accounts.add()  # Generates new key
-    acct = accounts.add("0x...")  # From private key
+    # Add new account (returns GeneratedAccount, includes mnemonic if generated)
+    gen = accounts.add()  # Generates new key
+    acct = gen.account
+    gen = accounts.add("0x...")  # From private key
+    acct = gen.account
 
     # Save to keystore
     acct.save("my_wallet")
@@ -33,6 +35,7 @@ import json
 import os
 import sys
 from pathlib import Path
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Iterator
 
 from eth_account import Account as EthAccount
@@ -42,6 +45,15 @@ if TYPE_CHECKING:
     from brawny.jobs.base import TxReceipt
 
 _accounts: "Accounts | None" = None
+_hdwallet_enabled = False
+
+
+def _ensure_hdwallet_enabled() -> None:
+    global _hdwallet_enabled
+    if _hdwallet_enabled:
+        return
+    EthAccount.enable_unaudited_hdwallet_features()
+    _hdwallet_enabled = True
 
 
 def _get_accounts_dir() -> Path:
@@ -241,6 +253,12 @@ class Account:
         return hash(self._address.lower())
 
 
+@dataclass(frozen=True)
+class GeneratedAccount:
+    account: Account
+    mnemonic: str | None = None
+
+
 class Accounts:
     """Container for available signing accounts.
 
@@ -335,7 +353,7 @@ class Accounts:
 
         return self._register(account)
 
-    def add(self, private_key: str | bytes | None = None) -> Account:
+    def add(self, private_key: str | bytes | None = None) -> GeneratedAccount:
         """Add account from private key or generate new one.
 
         Args:
@@ -343,17 +361,18 @@ class Accounts:
                         If None, generates new account with mnemonic.
 
         Returns:
-            Account instance (prints mnemonic if generated)
+            GeneratedAccount with mnemonic if generated
         """
         if private_key is None:
             # Generate new account with mnemonic
+            _ensure_hdwallet_enabled()
             mnemonic = generate_mnemonic(num_words=12, lang="english")
-            print(f"mnemonic: '{mnemonic}'")
             eth_acct = EthAccount.from_mnemonic(mnemonic)
             account = Account(
                 address=eth_acct.address,
                 private_key=eth_acct.key,
             )
+            return GeneratedAccount(account=self._register(account), mnemonic=mnemonic)
         else:
             # From provided key
             if isinstance(private_key, str):
@@ -364,8 +383,7 @@ class Accounts:
                 address=eth_acct.address,
                 private_key=eth_acct.key,
             )
-
-        return self._register(account)
+        return GeneratedAccount(account=self._register(account), mnemonic=None)
 
     def from_mnemonic(
         self,
@@ -386,6 +404,7 @@ class Accounts:
             Single Account if count=1, else list of Accounts
         """
         results = []
+        _ensure_hdwallet_enabled()
         for i in range(offset, offset + count):
             # Standard Ethereum derivation path
             path = f"m/44'/60'/0'/0/{i}"
@@ -497,7 +516,7 @@ class _AccountsProxy:
     def load(self, filename: str, password: str | None = None) -> Account:
         return _get_accounts().load(filename, password)
 
-    def add(self, private_key: str | bytes | None = None) -> Account:
+    def add(self, private_key: str | bytes | None = None) -> GeneratedAccount:
         return _get_accounts().add(private_key)
 
     def from_mnemonic(

brawny/alerts/__init__.py

@@ -1,15 +1,16 @@
 """Alerts extension with contract handles, ABI resolution, and event decoding.
 
 This extension provides an ergonomic interface for job authors to:
-- Interact with contracts in alert hooks
+- Send alerts from lifecycle hooks via ctx.alert()
+- Interact with contracts in hooks
 - Decode events from transaction receipts (brownie-compatible)
 - Make contract reads
 - Format messages with explorer links
 
 Key components:
-- AlertContext: Context passed to alert hooks with event access
+- SuccessContext: Context passed to on_success with receipt + events
+- FailureContext: Context passed to on_failure with error info
 - ContractHandle: Interface for contract function calls
-- EventDict: Brownie-compatible event container
 - ABIResolver: Automatic ABI resolution with caching
 
 Formatting helpers (Markdown is the default):
@@ -17,27 +18,23 @@ Formatting helpers (Markdown is the default):
 - explorer_link(hash): "[🔗 View on Explorer](url)"
 - escape_markdown_v2(text): Escapes special characters
 
-Usage in alert hooks:
+Usage in lifecycle hooks:
 
-    from brawny import Contract
     from brawny.alerts import shorten, explorer_link
+    from brawny.model.contexts import SuccessContext
 
-    def alert_confirmed(self, ctx: AlertContext) -> str:
-        # Get contract handle (brownie-style)
-        token = Contract("token")
-
+    def on_success(self, ctx: SuccessContext) -> None:
         # Decode events from receipt (brownie-compatible)
-        deposit = ctx.events["Deposit"][0]
-        amount = deposit["assets"]
-
-        # Make contract reads
-        symbol = token.symbol()
-        decimals = token.decimals()
+        if ctx.events:
+            deposit = ctx.events[0]  # First decoded event
+            amount = deposit["assets"]
 
-        # Format with explorer links
-        tx_link = explorer_link(ctx.receipt.transactionHash.hex())
+            # Format with explorer links
+            tx_link = explorer_link(ctx.receipt.transaction_hash)
 
-        return f"Deposited {amount / 10**decimals} {symbol}\\n{tx_link}"
+            ctx.alert(f"Deposited {amount}\\n{tx_link}")
+        else:
+            ctx.alert(f"Confirmed: {shorten(ctx.receipt.transaction_hash)}")
 """
 
 from brawny.alerts.context import AlertContext, JobMetadata