brawny 0.1.13__py3-none-any.whl

brawny/__init__.py

@@ -0,0 +1,106 @@
+"""
+brawny: Block-driven Ethereum job/transaction execution framework.
+
+This package provides a robust, production-ready framework for scheduling
+and executing Ethereum transactions based on block events.
+"""
+
+from brawny.jobs.base import Job
+from brawny.jobs.registry import registry, job
+from brawny.model.types import (
+    BlockInfo,
+    Trigger,
+    TxAttempt,
+    TxIntent,
+    TxIntentSpec,
+    to_wei,
+)
+from brawny.model.contexts import (
+    BlockContext,
+    CheckContext,
+    BuildContext,
+    AlertContext,
+)
+from brawny.model.events import DecodedEvent, find_event, events_by_name
+from brawny.telegram import telegram, get_telegram, TelegramBot
+from brawny.testing import job_context
+from brawny.interfaces import interface
+
+# Implicit context helpers (Flask-like pattern)
+from brawny.api import (
+    block,
+    ctx,       # Get current phase context (CheckContext or BuildContext)
+    trigger,
+    intent,
+    shorten,
+    explorer_link,
+    gas_ok,
+    gas_quote,
+    kv,        # Persistent KV store
+    alert,     # Send alerts from job hooks
+    rpc,       # RPC proxy (internal package renamed to _rpc to avoid collision)
+    get_address_from_alias,
+    Contract,  # Brownie-style
+    Wei,       # Brownie-style
+    web3,      # Brownie-style
+)
+
+# Brownie-style singletons for scripts
+from brawny.accounts import accounts, Account
+from brawny.history import history
+from brawny.chain import chain
+from brawny.networks import network
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Job",
+    "job",
+    "registry",
+    "BlockInfo",
+    "Trigger",
+    "TxAttempt",
+    "TxIntent",
+    "TxIntentSpec",
+    "to_wei",
+    # Phase-specific contexts (OE7)
+    "BlockContext",
+    "CheckContext",
+    "BuildContext",
+    "AlertContext",
+    # Events
+    "DecodedEvent",
+    "find_event",
+    "events_by_name",
+    # Implicit context helpers
+    "block",
+    "ctx",
+    "trigger",
+    "intent",
+    "shorten",
+    "explorer_link",
+    "gas_ok",
+    "gas_quote",
+    "kv",
+    "alert",
+    "rpc",
+    "get_address_from_alias",
+    # Brownie-style helpers
+    "Contract",
+    "Wei",
+    "web3",
+    # Brownie-style singletons
+    "accounts",
+    "Account",
+    "history",
+    "chain",
+    "network",
+    # Telegram
+    "telegram",
+    "get_telegram",
+    "TelegramBot",
+    # Testing
+    "job_context",
+    "interface",
+]

brawny/_context.py

@@ -0,0 +1,232 @@
+"""Implicit context for job hooks and console.
+
+Provides thread-safe context storage using Python's contextvars module.
+The framework sets these before calling check() / build_tx(), allowing
+helper functions like Contract(), trigger(), intent() to work without explicit
+ctx parameter.
+
+Usage (in job methods):
+    from brawny import Contract, trigger, intent, block
+
+    def check(self, ctx):
+        vault = Contract("vault")  # Works because context is set
+        return trigger(reason="...", tx_required=True)
+
+Usage (in alert hooks):
+    from brawny import Contract, shorten, explorer_link
+
+    def alert_confirmed(self, ctx):
+        vault = Contract("vault")
+        return f"Done!\\n{explorer_link(ctx.receipt.transactionHash.hex())}"
+
+Usage (in console):
+    >>> claimer = interface.IClaimer("0x...")  # Works via console context
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextvars import Token
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Union
+
+if TYPE_CHECKING:
+    from brawny.model.contexts import CheckContext, BuildContext, AlertContext
+    from brawny.jobs.base import Job
+    from brawny._rpc import RPCManager
+    from brawny.alerts.contracts import ContractSystem
+
+# Type alias for any phase context
+PhaseContext = Union["CheckContext", "BuildContext"]
+
+
+@dataclass(frozen=True)
+class ActiveContext:
+    """Minimal context for Contract()/interface/web3 access.
+
+    Used by console (and potentially scripts/tests) to provide the
+    necessary dependencies without requiring full job/alert context.
+    """
+
+    rpc: RPCManager
+    contract_system: ContractSystem
+    chain_id: int
+    network_name: str | None = None
+    rpc_group: str | None = None
+
+
+# Context variables - set by framework before calling job hooks
+_job_ctx: contextvars.ContextVar[PhaseContext | None] = contextvars.ContextVar(
+    "job_ctx", default=None
+)
+_current_job: contextvars.ContextVar[Job | None] = contextvars.ContextVar(
+    "current_job", default=None
+)
+# Alert context - uses Any to support both old AlertContext and new hook contexts
+_alert_ctx: contextvars.ContextVar[Any | None] = contextvars.ContextVar(
+    "alert_ctx", default=None
+)
+_console_ctx: contextvars.ContextVar[ActiveContext | None] = contextvars.ContextVar(
+    "console_ctx", default=None
+)
+
+# Block pinning for check() scope - ensures consistent snapshot reads
+_check_block: contextvars.ContextVar[int | None] = contextvars.ContextVar(
+    "check_block", default=None
+)
+
+
+def get_job_context() -> PhaseContext:
+    """Get the current phase context (CheckContext or BuildContext).
+
+    Returns:
+        The active context
+
+    Raises:
+        LookupError: If called outside a job hook (check/build_tx)
+    """
+    ctx = _job_ctx.get()
+    if ctx is None:
+        raise LookupError(
+            "No active context. Must be called from within check() or build_tx()."
+        )
+    return ctx
+
+
+def get_current_job() -> Job:
+    """Get the current Job instance.
+
+    Returns:
+        The active Job
+
+    Raises:
+        LookupError: If called outside a job hook
+    """
+    job = _current_job.get()
+    if job is None:
+        raise LookupError("No active job.")
+    return job
+
+
+def get_alert_context() -> Any | None:
+    """Get the current alert context if available.
+
+    Returns:
+        The active context (TriggerContext, SuccessContext, FailureContext,
+        or AlertContext for legacy hooks), or None if not in a hook
+    """
+    return _alert_ctx.get()
+
+
+def set_alert_context(ctx: Any) -> Token:
+    """Set the current alert context, return token for reset.
+
+    Called by the framework before invoking hooks. Use token-based reset
+    to ensure safe nesting if hooks call helpers.
+
+    Args:
+        ctx: Context to set (TriggerContext, SuccessContext, FailureContext)
+
+    Returns:
+        Token that can be used to reset the context
+    """
+    return _alert_ctx.set(ctx)
+
+
+def reset_alert_context(token: Token) -> None:
+    """Reset alert context to previous value using token.
+
+    Args:
+        token: Token from set_alert_context()
+    """
+    _alert_ctx.reset(token)
+
+
+def get_console_context() -> ActiveContext | None:
+    """Get the current console ActiveContext if available.
+
+    Returns:
+        The active console context, or None if not in console
+    """
+    return _console_ctx.get()
+
+
+def set_console_context(ctx: ActiveContext | None) -> contextvars.Token:
+    """Set the console ActiveContext.
+
+    Called by console at startup to enable Contract()/interface/web3 access.
+
+    Args:
+        ctx: ActiveContext to set, or None to clear
+
+    Returns:
+        Token that can be used to reset the context (useful for tests)
+    """
+    return _console_ctx.set(ctx)
+
+
+# =============================================================================
+# Block Pinning for check() Scope
+# =============================================================================
+
+
+def set_check_block(block_number: int) -> contextvars.Token:
+    """Set the block number for check() scope.
+
+    Called by the runner before invoking check() to pin all Contract reads
+    to a consistent block snapshot.
+
+    Args:
+        block_number: Block number to pin reads to
+
+    Returns:
+        Token for reset (must call reset_check_block when check completes)
+    """
+    return _check_block.set(block_number)
+
+
+def reset_check_block(token: contextvars.Token) -> None:
+    """Reset check block after check() completes.
+
+    Args:
+        token: Token from set_check_block()
+    """
+    _check_block.reset(token)
+
+
+def get_check_block() -> int | None:
+    """Get current check block, or None if not in check scope.
+
+    Returns:
+        Block number if in check() scope, None otherwise
+    """
+    return _check_block.get()
+
+
+def resolve_block_identifier(
+    explicit: int | str | None,
+    handle_block: int | None = None,
+) -> int | str:
+    """Resolve block identifier with 4-level precedence.
+
+    Precedence (highest to lowest):
+    1. Explicit param (caller override) - always wins
+    2. Handle's baked block (from ctx.contracts.at_block())
+    3. Check scope pin (_check_block contextvar)
+    4. Default "latest"
+
+    Args:
+        explicit: Explicitly passed block_identifier (None if not passed)
+        handle_block: Block baked into ContractHandle (None if not set)
+
+    Returns:
+        Block identifier to use for eth_call (int or "latest")
+    """
+    if explicit is not None:
+        return explicit
+    if handle_block is not None:
+        return handle_block
+    check_block = get_check_block()
+    if check_block is not None:
+        return check_block
+    return "latest"

brawny/_rpc/__init__.py

@@ -0,0 +1,38 @@
+"""RPC management with multi-endpoint failover and health tracking.
+
+OE6 Simplification:
+- Uses EndpointSelector for health-aware endpoint ordering
+- Explicit failover gate (only on RPCRetryableError)
+- Removed circuit breaker and rate limiter (simpler error handling)
+"""
+
+from brawny._rpc.errors import (
+    RPCError,
+    RPCFatalError,
+    RPCRecoverableError,
+    RPCRetryableError,
+    classify_error,
+    normalize_error_code,
+)
+from brawny._rpc.manager import RPCManager
+from brawny._rpc.selector import EndpointSelector, EndpointHealth
+from brawny._rpc.context import (
+    get_job_context,
+    reset_job_context,
+    set_job_context,
+)
+
+__all__ = [
+    "RPCManager",
+    "EndpointSelector",
+    "EndpointHealth",
+    "RPCError",
+    "RPCFatalError",
+    "RPCRecoverableError",
+    "RPCRetryableError",
+    "classify_error",
+    "normalize_error_code",
+    "get_job_context",
+    "reset_job_context",
+    "set_job_context",
+]

brawny/_rpc/broadcast.py

@@ -0,0 +1,172 @@
+"""Broadcast helpers with isolation guarantees.
+
+This is the ONLY place that wraps RPCPoolExhaustedError → RPCGroupUnavailableError.
+RPCManager does the endpoint iteration; this module adds group context.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from brawny.metrics import (
+    BROADCAST_ATTEMPTS,
+    BROADCAST_LATENCY_SECONDS,
+    get_metrics,
+)
+from brawny._rpc.errors import (
+    RPCFatalError,
+    RPCPoolExhaustedError,
+    RPCGroupUnavailableError,
+    RPCRecoverableError,
+)
+
+if TYPE_CHECKING:
+    from brawny.config import Config
+    from brawny._rpc.manager import RPCManager
+
+
+def create_broadcast_manager(endpoints: list[str], config: "Config") -> "RPCManager":
+    """Create an RPCManager for broadcasting to specific endpoints.
+
+    This creates a dedicated RPCManager instance for broadcasting.
+    Each call uses the provided endpoints (from binding snapshot for retries,
+    or from current config for first broadcast).
+
+    Args:
+        endpoints: List of endpoint URLs to use (must be canonical)
+        config: Config for RPC settings
+
+    Returns:
+        RPCManager configured for the provided endpoints
+    """
+    from brawny._rpc.manager import RPCManager
+
+    return RPCManager(
+        endpoints=endpoints,
+        timeout_seconds=config.rpc_timeout_seconds,
+        max_retries=config.rpc_max_retries,
+        retry_backoff_base=config.rpc_retry_backoff_base,
+        circuit_breaker_seconds=config.rpc_circuit_breaker_seconds,
+        rate_limit_per_second=config.rpc_rate_limit_per_second,
+        rate_limit_burst=config.rpc_rate_limit_burst,
+        chain_id=config.chain_id,
+        log_init=False,  # Don't log ephemeral broadcast managers
+    )
+
+
+def broadcast_transaction(
+    raw_tx: bytes,
+    endpoints: list[str],
+    group_name: str | None,
+    config: "Config",
+    job_id: str | None = None,
+) -> tuple[str, str]:
+    """Broadcast transaction with isolation guarantee.
+
+    This function creates a dedicated RPCManager for the broadcast,
+    ensuring the transaction is only sent to the specified endpoints.
+
+    Args:
+        raw_tx: Signed transaction bytes
+        endpoints: Endpoint list (MUST be binding snapshot for retries)
+        group_name: Group name for logging/errors (None for ungrouped)
+        config: Config for RPC settings
+        job_id: Job ID for metrics (optional)
+
+    Returns:
+        Tuple of (tx_hash, endpoint_url)
+
+    Raises:
+        RPCGroupUnavailableError: All endpoints in group failed
+        RPCFatalError: TX rejected (nonce, funds, revert)
+        RPCRecoverableError: TX may succeed with different params
+    """
+    manager = create_broadcast_manager(endpoints, config)
+    metrics = get_metrics()
+    chain_id = config.chain_id
+    start_time = time.perf_counter()
+    group_label = group_name or "ungrouped"
+
+    try:
+        tx_hash, endpoint_url = manager.send_raw_transaction(raw_tx)
+
+        # Record success metrics
+        latency = time.perf_counter() - start_time
+        metrics.counter(BROADCAST_ATTEMPTS).inc(
+            chain_id=chain_id,
+            job_id=job_id or "unknown",
+            broadcast_group=group_label,
+            result="success",
+        )
+        metrics.histogram(BROADCAST_LATENCY_SECONDS).observe(
+            latency,
+            chain_id=chain_id,
+            job_id=job_id or "unknown",
+            broadcast_group=group_label,
+        )
+
+        return tx_hash, endpoint_url
+
+    except RPCPoolExhaustedError as e:
+        # Record unavailable metrics
+        metrics.counter(BROADCAST_ATTEMPTS).inc(
+            chain_id=chain_id,
+            job_id=job_id or "unknown",
+            broadcast_group=group_label,
+            result="unavailable",
+        )
+        # Wrap with group context for user-facing error
+        raise RPCGroupUnavailableError(
+            f"All endpoints in group '{group_label}' failed",
+            group_name=group_name,
+            endpoints=e.endpoints,
+            last_error=e.last_error,
+        ) from e
+
+    except RPCFatalError:
+        # Record fatal error metrics
+        metrics.counter(BROADCAST_ATTEMPTS).inc(
+            chain_id=chain_id,
+            job_id=job_id or "unknown",
+            broadcast_group=group_label,
+            result="fatal",
+        )
+        raise
+
+    except RPCRecoverableError:
+        # Record recoverable error metrics
+        metrics.counter(BROADCAST_ATTEMPTS).inc(
+            chain_id=chain_id,
+            job_id=job_id or "unknown",
+            broadcast_group=group_label,
+            result="recoverable",
+        )
+        raise
+
+
+def get_broadcast_endpoints(config: "Config", group_name: str) -> list[str]:
+    """Get endpoints for a broadcast group (already canonical + deduped).
+
+    This returns the endpoint list from the current config. For first broadcasts,
+    this list should be persisted as the binding. For retries, use the
+    persisted binding instead of calling this function.
+
+    Args:
+        config: Application configuration
+        group_name: Name of the broadcast group
+
+    Returns:
+        List of canonical endpoint URLs
+
+    Raises:
+        ValueError: If group not found or has no endpoints
+    """
+    if group_name not in config.rpc_groups:
+        raise ValueError(f"Broadcast group '{group_name}' not found")
+
+    group = config.rpc_groups[group_name]
+    if not group.endpoints:
+        raise ValueError(f"Broadcast group '{group_name}' has no endpoints")
+
+    return group.endpoints

brawny/_rpc/clients.py

@@ -0,0 +1,98 @@
+"""RPC client management — shared by TxExecutor and JobRunner.
+
+This module provides caching for read RPC clients by group.
+Broadcast clients are created per-call from endpoint snapshots (see broadcast.py).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from brawny.config import Config
+    from brawny._rpc.manager import RPCManager
+
+
+class RPCClients:
+    """Manages RPC clients for read operations.
+
+    Caches read clients by group. Broadcast clients are created per-call
+    from endpoint snapshots (see broadcast.py).
+
+    Example:
+        clients = RPCClients(config)
+
+        # Get cached read client for a group
+        public_rpc = clients.get_read_client("public")
+        private_rpc = clients.get_read_client("private")
+
+        # Same group = same cached client
+        assert clients.get_read_client("public") is public_rpc
+    """
+
+    def __init__(self, config: "Config") -> None:
+        """Initialize RPC clients manager.
+
+        Args:
+            config: Application configuration
+        """
+        self._config = config
+        self._read_clients: dict[str, "RPCManager"] = {}
+
+    def get_read_client(self, group_name: str) -> "RPCManager":
+        """Get (cached) read client for a group.
+
+        If the group's client hasn't been created yet, creates it.
+        Subsequent calls return the same cached instance.
+
+        Args:
+            group_name: Name of the RPC group (e.g., "public", "private")
+
+        Returns:
+            RPCManager configured for the group's endpoints
+
+        Raises:
+            ValueError: If group not found in config.rpc_groups
+        """
+        if group_name not in self._read_clients:
+            from brawny._rpc.manager import RPCManager
+
+            if group_name not in self._config.rpc_groups:
+                raise ValueError(f"RPC group '{group_name}' not found")
+
+            group = self._config.rpc_groups[group_name]
+            self._read_clients[group_name] = RPCManager(
+                endpoints=group.endpoints,
+                timeout_seconds=self._config.rpc_timeout_seconds,
+                max_retries=self._config.rpc_max_retries,
+                retry_backoff_base=self._config.rpc_retry_backoff_base,
+                circuit_breaker_seconds=self._config.rpc_circuit_breaker_seconds,
+                rate_limit_per_second=self._config.rpc_rate_limit_per_second,
+                rate_limit_burst=self._config.rpc_rate_limit_burst,
+                chain_id=self._config.chain_id,
+                log_init=False,  # Daemon already logged main RPC init
+            )
+
+        return self._read_clients[group_name]
+
+    def get_default_client(self) -> "RPCManager":
+        """Get the default read client.
+
+        Uses config.rpc_default_group if set, otherwise requires a single rpc_group.
+
+        Returns:
+            RPCManager for the default group
+
+        Raises:
+            ValueError: If default group cannot be resolved
+        """
+        from brawny.config.routing import resolve_default_group
+
+        return self.get_read_client(resolve_default_group(self._config))
+
+    def clear_cache(self) -> None:
+        """Clear all cached clients.
+
+        Useful for testing or when config changes require new clients.
+        """
+        self._read_clients.clear()

brawny/_rpc/context.py

@@ -0,0 +1,49 @@
+"""RPC job context for attribution metrics.
+
+Provides a contextvar to track which job is making RPC calls,
+allowing per-job RPC pressure metrics without high-cardinality labels
+on the main RPC metrics.
+
+Usage:
+    from brawny._rpc.context import set_job_context, reset_job_context
+
+    token = set_job_context(job.job_id)
+    try:
+        # ... RPC calls here get attributed to job_id ...
+    finally:
+        reset_job_context(token)
+"""
+
+from contextvars import ContextVar, Token
+
+_rpc_job_ctx: ContextVar[str | None] = ContextVar("rpc_job_ctx", default=None)
+
+
+def set_job_context(job_id: str | None) -> Token:
+    """Set the current job context for RPC attribution.
+
+    Args:
+        job_id: Job ID to attribute RPC calls to, or None to clear
+
+    Returns:
+        Token for resetting context via reset_job_context()
+    """
+    return _rpc_job_ctx.set(job_id)
+
+
+def reset_job_context(token: Token) -> None:
+    """Reset job context to previous value.
+
+    Args:
+        token: Token returned by set_job_context()
+    """
+    _rpc_job_ctx.reset(token)
+
+
+def get_job_context() -> str | None:
+    """Get the current job context.
+
+    Returns:
+        Job ID if set, None otherwise
+    """
+    return _rpc_job_ctx.get()