brawny 0.1.13__py3-none-any.whl

brawny/jobs/base.py

@@ -0,0 +1,287 @@
+"""Base Job class for brawny.
+
+Jobs are the core abstraction for scheduling and executing Ethereum transactions
+based on block events. Jobs implement check() to evaluate conditions and
+build_tx() to create transactions.
+
+Phase-specific contexts (OE7):
+- CheckContext: Read chain state, return Trigger. KV is read+write.
+- BuildContext: Produces TxSpec. Has trigger + signer. KV is read-only.
+- AlertContext: Receives immutable snapshots. KV is read-only.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from brawny.model.contexts import (
+        CheckContext,
+        BuildContext,
+        AlertContext,
+        TriggerContext,
+        SuccessContext,
+        FailureContext,
+    )
+    from brawny.model.types import Trigger, TxIntent, TxIntentSpec, TxAttempt
+
+
+class TxInfo:
+    """Transaction info for alert context."""
+
+    def __init__(
+        self,
+        hash: str,
+        nonce: int,
+        from_address: str,
+        to_address: str,
+        gas_limit: int,
+        max_fee_per_gas: int,
+        max_priority_fee_per_gas: int,
+    ) -> None:
+        self.hash = hash
+        self.nonce = nonce
+        self.from_address = from_address
+        self.to_address = to_address
+        self.gas_limit = gas_limit
+        self.max_fee_per_gas = max_fee_per_gas
+        self.max_priority_fee_per_gas = max_priority_fee_per_gas
+
+
+class TxReceipt:
+    """Transaction receipt for alert context."""
+
+    def __init__(
+        self,
+        transaction_hash: str,
+        block_number: int,
+        block_hash: str,
+        status: int,
+        gas_used: int,
+        logs: list[dict[str, Any]],
+    ) -> None:
+        self.transactionHash = transaction_hash
+        self.blockNumber = block_number
+        self.blockHash = block_hash
+        self.status = status
+        self.gasUsed = gas_used
+        self.logs = logs
+
+
+class BlockInfo:
+    """Block info for alert context."""
+
+    def __init__(
+        self,
+        number: int,
+        hash: str,
+        timestamp: int,
+    ) -> None:
+        self.number = number
+        self.hash = hash
+        self.timestamp = timestamp
+
+
+class Job(ABC):
+    """Base class for all jobs.
+
+    Jobs are the core abstraction for scheduling and executing Ethereum
+    transactions based on block events.
+
+    Attributes:
+        job_id: Stable identifier, must not change across deployments
+        name: Human-readable name for logging and alerts
+        check_interval_blocks: Minimum blocks between check() calls
+        check_timeout_seconds: Timeout for check() execution
+        build_timeout_seconds: Timeout for build_intent() execution
+        max_in_flight_intents: Optional cap on active intents for this job
+    """
+
+    job_id: str
+    name: str
+    check_interval_blocks: int = 1
+    check_timeout_seconds: int = 30
+    build_timeout_seconds: int = 10
+    max_in_flight_intents: int | None = None
+
+    # Simulation config
+    disable_simulation: bool = False
+    rpc: str | None = None  # Override global RPC URL for simulation
+
+    # Gas overrides (None = inherit from config, all values in wei)
+    max_fee: int | None = None
+    priority_fee: int | None = None
+
+    # Alert config
+    # NOTE: Use None as sentinel to avoid mutable default sharing across subclasses
+    telegram_chat_ids: list[str] | None = None  # Override global alert targets (None = use global)
+
+    # Signer config (set by @job(signer="...") decorator)
+    _signer_name: str | None = None
+
+    # Alert routing (set by @job(alert_to="...") decorator)
+    _alert_to: list[str] | None = None
+
+    @property
+    def signer(self) -> str | None:
+        """Signer alias from @job(signer="..."), or None if not set."""
+        return self._signer_name
+
+    @signer.setter
+    def signer(self, value: str | None) -> None:
+        """Allow setting signer dynamically (tests/dev flows)."""
+        self._signer_name = value
+
+    @property
+    def signer_address(self) -> str:
+        """Resolved checksummed address for this job's signer.
+
+        Raises:
+            RuntimeError: If no signer configured.
+            KeystoreError: If signer not found in keystore.
+        """
+        if self._signer_name is None:
+            raise RuntimeError(f"Job '{self.job_id}' has no signer configured.")
+        if self._signer_name.startswith("0x") and len(self._signer_name) == 42:
+            from web3 import Web3
+
+            return Web3.to_checksum_address(self._signer_name)
+        from brawny.api import get_address_from_alias
+        return get_address_from_alias(self._signer_name)
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Ensure each subclass has its own mutable containers.
+
+        This prevents the Python mutable default argument bug where all
+        subclasses would share the same dict/list instance.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Create fresh containers for each subclass if not explicitly defined
+        # Check if the attribute is inherited from Job (shared) vs defined on cls
+        if "telegram_chat_ids" not in cls.__dict__:
+            cls.telegram_chat_ids = []
+        elif cls.telegram_chat_ids is None:
+            cls.telegram_chat_ids = []
+
+    def check(self, *args: Any, **kwargs: Any) -> Trigger | None:
+        """Check if job should trigger.
+
+        Called at most once per check_interval_blocks.
+
+        Supported signatures:
+            def check(self) -> Trigger | None           # Implicit context
+            def check(self, ctx) -> Trigger | None      # Explicit context
+
+        When using implicit context, access via:
+            - block.number, block.timestamp (from brawny.api)
+            - kv.get(), kv.set() (from brawny.api)
+            - Contract() (from brawny.api)
+            - ctx() for full context access
+
+        Note:
+            Explicit style requires the parameter to be named 'ctx' so the
+            runner can detect it safely. Using a different name will be
+            treated as implicit style.
+
+        Returns:
+            Trigger if action needed, None otherwise
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement check()")
+
+    def build_tx(self, *args: Any, **kwargs: Any) -> TxIntentSpec:
+        """Build transaction spec from trigger.
+
+        Only called if trigger.tx_required is True. Trigger is available
+        via ctx.trigger (explicit) or via the ctx() helper (implicit).
+
+        Supported signatures:
+            def build_tx(self) -> TxIntentSpec           # Implicit context
+            def build_tx(self, ctx) -> TxIntentSpec      # Explicit context
+
+        Use ctx.contracts.at(name, addr) for 'latest' reads.
+        Safety-critical predicates should be computed in check() and
+        encoded in ctx.trigger.reason or intent.metadata.
+
+        Note:
+            Explicit style requires the parameter to be named 'ctx' so the
+            runner can detect it safely.
+
+        Returns:
+            Transaction intent specification
+
+        Raises:
+            NotImplementedError: For monitor-only jobs
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} must implement build_tx()")
+
+    def validate_simulation(self, output: str) -> bool:
+        """Validate simulation output before broadcast.
+
+        Called only if simulation succeeds (no revert). Override to add
+        custom checks like verifying return values or slippage.
+
+        Args:
+            output: Hex-encoded return data from simulation (0x...)
+
+        Returns:
+            True to proceed with broadcast.
+            False to fail (executor raises SimulationReverted).
+
+        Example:
+            def validate_simulation(self, output):
+                decoded = self._decode_output(output)
+                return decoded >= self.min_output
+        """
+        return True
+
+    # =========================================================================
+    # Lifecycle Hooks (New Simplified API)
+    # =========================================================================
+
+    def on_trigger(self, ctx: "TriggerContext") -> None:
+        """Called when check() returns a Trigger, BEFORE build_tx().
+
+        Use for:
+        - Monitor-only jobs (tx_required=False) - your only hook
+        - Pre-transaction alerts/logging
+        - KV updates before intent creation
+
+        Note: No intent exists yet. After this hook, trigger is gone -
+              only intent.metadata persists.
+
+        To send alerts, use:
+            from brawny import alert
+            alert(f"Triggered: {ctx.trigger.reason}")
+        """
+        pass
+
+    def on_success(self, ctx: "SuccessContext") -> None:
+        """Called when transaction confirms.
+
+        ctx.intent.metadata["reason"] = original trigger.reason
+        ctx.intent.metadata[...] = your custom data from build_tx()
+
+        To send alerts, use:
+            from brawny import alert
+            alert(f"Confirmed: {ctx.intent.metadata['reason']}")
+        """
+        pass
+
+    def on_failure(self, ctx: "FailureContext") -> None:
+        """Called on failures. ctx.intent may be None for pre-intent failures.
+
+        Pre-intent failures include:
+        - check() exception
+        - build_tx() exception
+        - intent creation failure
+
+        To send alerts, use:
+            from brawny import alert
+            if ctx.intent:
+                alert(f"Failed: {ctx.intent.metadata['reason']}")
+            else:
+                alert(f"Pre-intent failure: {ctx.error}")
+        """
+        pass

brawny/jobs/discovery.py

@@ -0,0 +1,233 @@
+"""Job discovery for brawny.
+
+Provides module and path-based job discovery mechanisms.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import pkgutil
+import sys
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class JobLoadError:
+    """Represents a failure to load a job module."""
+
+    path: str
+    message: str  # str(e) for quick scanning
+    traceback: str  # full traceback for debugging
+
+
+class JobDiscoveryFailed(Exception):
+    """Raised when one or more job modules fail to load."""
+
+    def __init__(self, errors: list[JobLoadError]) -> None:
+        self.errors = errors
+        super().__init__(f"Failed to load {len(errors)} job module(s)")
+
+
+def _import_module_tree(module_path: str) -> list[JobLoadError]:
+    """Import a module and all submodules if it's a package.
+
+    Returns:
+        List of JobLoadError for any modules that failed to load.
+    """
+    load_errors: list[JobLoadError] = []
+
+    try:
+        module = importlib.import_module(module_path)
+    except Exception as e:
+        load_errors.append(
+            JobLoadError(
+                path=module_path,
+                message=str(e),
+                traceback=traceback.format_exc(),
+            )
+        )
+        logger.error(
+            "job.module_load_failed",
+            module=module_path,
+            error=str(e),
+            error_type=type(e).__name__,
+        )
+        return load_errors
+
+    # If it's a package, walk submodules recursively.
+    if hasattr(module, "__path__"):
+        for _, name, _ in pkgutil.walk_packages(module.__path__, module.__name__ + "."):
+            if name.split(".")[-1].startswith("_"):
+                continue
+            try:
+                importlib.import_module(name)
+            except Exception as e:
+                load_errors.append(
+                    JobLoadError(
+                        path=name,
+                        message=str(e),
+                        traceback=traceback.format_exc(),
+                    )
+                )
+                logger.error(
+                    "job.module_load_failed",
+                    module=name,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
+
+    return load_errors
+
+
+def discover_jobs(module_paths: list[str]) -> tuple[list[str], list[JobLoadError]]:
+    """Discover and import job modules.
+
+    Imports the specified modules to trigger @job decorators.
+
+    Args:
+        module_paths: List of Python module paths to import
+
+    Returns:
+        Tuple of (discovered job IDs, list of JobLoadError for failed modules)
+    """
+    # Lazy import to avoid circular dependency
+    from brawny.jobs.registry import get_registry
+
+    registry = get_registry()
+    discovered: list[str] = []
+    load_errors: list[JobLoadError] = []
+
+    for module_path in module_paths:
+        # Record jobs before import
+        before = set(registry.list_job_ids())
+
+        # Import module and any submodules (package tree)
+        errors = _import_module_tree(module_path)
+        load_errors.extend(errors)
+
+        # Find newly registered jobs
+        after = set(registry.list_job_ids())
+        new_jobs = after - before
+
+        for job_id in new_jobs:
+            discovered.append(job_id)
+
+    return discovered, load_errors
+
+
+def discover_jobs_from_path(jobs_dir: str | Path) -> tuple[list[str], list[JobLoadError]]:
+    """Discover jobs by scanning a directory for Python files.
+
+    Recursively finds all .py files and imports them to trigger @job.
+    Does NOT require __init__.py files in subdirectories.
+
+    Args:
+        jobs_dir: Path to jobs directory
+
+    Returns:
+        Tuple of (discovered job IDs, list of JobLoadError for failed modules)
+    """
+    # Lazy import to avoid circular dependency
+    from brawny.jobs.registry import get_registry
+
+    registry = get_registry()
+    jobs_path = Path(jobs_dir).resolve()
+    load_errors: list[JobLoadError] = []
+
+    if not jobs_path.is_dir():
+        logger.error("job.discovery.not_a_directory", path=str(jobs_path))
+        return [], []
+
+    discovered: list[str] = []
+    before = set(registry.list_job_ids())
+
+    # Find all .py files recursively
+    for py_file in jobs_path.rglob("*.py"):
+        # Skip private files and __init__.py
+        if py_file.name.startswith("_"):
+            continue
+
+        # Skip examples directory (reference code, not to be registered)
+        if "examples" in py_file.parts:
+            continue
+
+        try:
+            # Create a unique module name based on path
+            rel_path = py_file.relative_to(jobs_path)
+            module_name = f"_jobs_.{rel_path.with_suffix('').as_posix().replace('/', '.')}"
+
+            # Import the file directly
+            spec = importlib.util.spec_from_file_location(module_name, py_file)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = module
+                spec.loader.exec_module(module)
+
+        except Exception as e:
+            load_errors.append(
+                JobLoadError(
+                    path=str(py_file),
+                    message=str(e),
+                    traceback=traceback.format_exc(),
+                )
+            )
+            logger.error(
+                "job.module_load_failed",
+                file=str(py_file),
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+
+    # Find newly registered jobs
+    after = set(registry.list_job_ids())
+    new_jobs = after - before
+
+    for job_id in sorted(new_jobs):
+        discovered.append(job_id)
+
+    return discovered, load_errors
+
+
+def auto_discover_jobs() -> tuple[list[str], list[JobLoadError]]:
+    """Auto-discover jobs from conventional locations.
+
+    Checks in order:
+    1. ./jobs/ directory
+    2. ./src/*/jobs/ directories
+
+    This enables zero-config job discovery for projects that follow conventions.
+
+    Returns:
+        Tuple of (discovered job IDs, list of JobLoadError for failed modules)
+    """
+    discovered: list[str] = []
+    load_errors: list[JobLoadError] = []
+    cwd = Path.cwd()
+
+    # Check ./jobs/
+    jobs_dir = cwd / "jobs"
+    if jobs_dir.is_dir():
+        jobs, errors = discover_jobs_from_path(jobs_dir)
+        discovered.extend(jobs)
+        load_errors.extend(errors)
+
+    # Check ./src/*/jobs/ (setuptools convention)
+    if not discovered:
+        src_dir = cwd / "src"
+        if src_dir.is_dir():
+            for pkg_dir in src_dir.iterdir():
+                if pkg_dir.is_dir() and not pkg_dir.name.startswith("_"):
+                    pkg_jobs = pkg_dir / "jobs"
+                    if pkg_jobs.is_dir():
+                        jobs, errors = discover_jobs_from_path(pkg_jobs)
+                        discovered.extend(jobs)
+                        load_errors.extend(errors)
+
+    return discovered, load_errors

brawny/jobs/job_validation.py

@@ -0,0 +1,111 @@
+"""Job validation for brawny.
+
+Provides structural validation for job instances.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from brawny.jobs.base import Job
+    from brawny.keystore import Keystore
+
+
+def _is_valid_address(address: str) -> bool:
+    """Check if a string looks like a valid Ethereum address.
+
+    Args:
+        address: String to validate
+
+    Returns:
+        True if valid address format
+    """
+    if not isinstance(address, str):
+        return False
+    if not address.startswith("0x"):
+        return False
+    if len(address) != 42:
+        return False
+    try:
+        int(address, 16)
+        return True
+    except ValueError:
+        return False
+
+
+def validate_job(job: "Job", keystore: "Keystore | None" = None) -> list[str]:
+    """Validate job structure and configuration.
+
+    Checks:
+    - Required attributes (job_id, name)
+    - Required methods (check)
+    - check_interval_blocks is positive
+    - Signer exists in keystore (if configured and keystore provided)
+
+    Does NOT:
+    - Call check() or build_intent()
+    - Make RPC calls
+    - Validate runtime behavior
+
+    Args:
+        job: Job instance to validate
+        keystore: Optional keystore for signer validation
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors: list[str] = []
+
+    # Required attributes
+    job_id = getattr(job, "job_id", None)
+    if not job_id:
+        errors.append("missing job_id attribute")
+
+    name = getattr(job, "name", None)
+    if not name:
+        errors.append("missing name attribute")
+
+    # Required methods
+    if not callable(getattr(job, "check", None)):
+        errors.append("missing check() method")
+
+    # check_interval_blocks should be positive
+    interval = getattr(job, "check_interval_blocks", 1)
+    if not isinstance(interval, int) or interval < 1:
+        errors.append(f"check_interval_blocks must be positive integer, got {interval}")
+
+    # Signer validation (if keystore available)
+    signer = getattr(job, "_signer_name", None)
+    if signer and keystore:
+        if not keystore.has_key(signer):
+            available = keystore.list_keys()
+            if available:
+                errors.append(f"signer '{signer}' not found in keystore (available: {', '.join(available)})")
+            else:
+                errors.append(f"signer '{signer}' not found (keystore is empty)")
+
+    return errors
+
+
+def validate_all_jobs(
+    jobs: dict[str, "Job"],
+    keystore: "Keystore | None" = None,
+) -> dict[str, list[str]]:
+    """Validate all jobs and return errors by job_id.
+
+    Args:
+        jobs: Dict of job_id -> Job instance
+        keystore: Optional keystore for signer validation
+
+    Returns:
+        Dict of job_id -> list of errors (only jobs with errors included)
+    """
+    all_errors: dict[str, list[str]] = {}
+
+    for job_id, job in jobs.items():
+        errors = validate_job(job, keystore)
+        if errors:
+            all_errors[job_id] = errors
+
+    return all_errors