brawny 0.1.13__py3-none-any.whl

brawny/model/contexts.py

@@ -0,0 +1,319 @@
+"""Phase-specific contexts for the job lifecycle.
+
+Each phase gets only what it needs:
+- 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.
+
+Contract access is explicit and block-aware:
+- at_block(name, addr, block): Pinned reads for check()
+- at(name, addr): Latest reads for build/alerts
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+from brawny.model.events import DecodedEvent
+from brawny.model.errors import FailureType
+
+if TYPE_CHECKING:
+    from brawny.jobs.kv import KVReader, KVStore
+    from brawny.model.types import Trigger, TxIntent, TxAttempt
+    from brawny.jobs.base import TxInfo, TxReceipt
+    from brawny.alerts.send import AlertConfig
+    from brawny.config.models import TelegramConfig
+    from brawny.telegram import TelegramBot
+    import structlog
+
+
+# =============================================================================
+# Contract Factory Protocol
+# =============================================================================
+
+
+class ContractHandle(Protocol):
+    """Protocol for contract handles. Actual implementation in alerts/contracts.py."""
+
+    @property
+    def address(self) -> str:
+        """Contract address (checksummed)."""
+        ...
+
+    def _call_with_calldata(self, calldata: str, abi: Any) -> Any:
+        """Execute eth_call with pre-encoded calldata."""
+        ...
+
+
+class ContractFactory(Protocol):
+    """Factory for creating contract handles.
+
+    Block-aware contract access:
+    - at(): Get handle reading at 'latest'. Use in build/alerts.
+    - at_block(): Get handle pinned to specific block. Use in check().
+    - with_abi(): Get handle with explicit ABI.
+
+    Factory stays dumb:
+    - Does not silently switch endpoints/groups
+    - Does not mutate global caches
+    - Is deterministic under a given rpc + abi_resolver
+    - Factory binds handles; resolver owns policy
+    """
+
+    def at(self, name: str, address: str) -> ContractHandle:
+        """Get contract handle, reads at 'latest'. Use in build/alerts."""
+        ...
+
+    def at_block(self, name: str, address: str, block: int) -> ContractHandle:
+        """Get contract handle pinned to specific block. Use in check()."""
+        ...
+
+    def with_abi(self, address: str, abi: list[Any]) -> ContractHandle:
+        """Get contract handle with explicit ABI."""
+        ...
+
+
+# =============================================================================
+# Block Context (Immutable Snapshot)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class BlockContext:
+    """Immutable chain state snapshot at check() time.
+
+    Contains only chain state metadata. Jobs can still make RPC calls,
+    but check() reads should be block-pinned using ctx.block.number.
+    """
+
+    number: int
+    timestamp: int
+    hash: str
+    base_fee: int
+    chain_id: int
+
+
+# =============================================================================
+# Check Context
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class CheckContext:
+    """Context available during check(). Read chain state, return Trigger.
+
+    Semantic rules:
+    - check() may read chain state + mutate kv
+    - Returns Trigger | None
+    - Use ctx.contracts.at_block(name, addr, ctx.block.number) for block-pinned reads
+    """
+
+    block: BlockContext
+    kv: KVStore  # Read+write allowed
+    job_id: str
+    rpc: Any  # RPCManager or similar
+    logger: "structlog.stdlib.BoundLogger"
+    contracts: ContractFactory
+    _db: Any = None  # Internal: for log()
+
+    def log(self, level: str = "info", **fields: Any) -> None:
+        """Record structured snapshot. Best-effort, never interrupts."""
+        if self._db is None:
+            return
+        try:
+            from brawny.db.ops import logs as log_ops
+            log_ops.insert_log(
+                self._db, self.block.chain_id, self.job_id,
+                self.block.number, level, fields
+            )
+        except Exception as e:
+            self.logger.warning("log_failed", error=str(e))
+
+
+# =============================================================================
+# Build Context
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    """Context available during build_tx(). Produces transaction spec.
+
+    Semantic rules:
+    - build_tx() produces a TxSpec
+    - Has trigger + signer_address
+    - KV is read-only
+    - ctx.contracts.at(name, addr) defaults to 'latest', fine for build
+    - Safety-critical predicates should be computed in check() and encoded in Trigger.data
+    """
+
+    block: BlockContext
+    trigger: "Trigger"
+    job_id: str
+    signer_address: str  # Signer belongs here, not on RPC
+    rpc: Any  # RPCManager or similar
+    logger: "structlog.stdlib.BoundLogger"
+    contracts: ContractFactory
+    kv: KVReader  # Read-only
+
+
+# =============================================================================
+# Alert Context
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class AlertContext:
+    """Context available during alert hooks. Immutable snapshots only.
+
+    Semantic rules:
+    - Alert hooks receive immutable snapshots
+    - KV is read-only
+    - events is raw list[DecodedEvent], not an accessor framework
+    - chain_id comes from block.chain_id (no duplication)
+    """
+
+    block: BlockContext
+    trigger: "Trigger"
+    tx: "TxInfo | None"
+    receipt: "TxReceipt | None"
+    events: list[DecodedEvent] | None  # Raw list, not a framework
+    failure_type: FailureType | None
+    error_info: Any | None  # ErrorInfo for failure context
+    logger: "structlog.stdlib.BoundLogger"
+    contracts: ContractFactory
+    kv: KVReader  # Read-only
+
+    @property
+    def has_receipt(self) -> bool:
+        """Check if receipt is available."""
+        return self.receipt is not None
+
+    @property
+    def has_error(self) -> bool:
+        """Check if this is a failure context."""
+        return self.failure_type is not None
+
+    @property
+    def error_message(self) -> str:
+        """Convenience: error message or 'unknown'."""
+        if self.error_info is not None and hasattr(self.error_info, "message"):
+            return self.error_info.message
+        return "unknown"
+
+    @property
+    def chain_id(self) -> int:
+        """Chain ID from block context."""
+        return self.block.chain_id
+
+
+# =============================================================================
+# Hook Contexts (New Simplified API)
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class TriggerContext:
+    """Passed to on_trigger. Trigger still exists here.
+
+    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.
+    """
+
+    trigger: "Trigger"
+    block: BlockContext
+    kv: "KVStore"  # Read+write (pre-intent)
+    logger: "structlog.stdlib.BoundLogger"
+    # Alert routing
+    job_id: str
+    job_name: str
+    chain_id: int
+    alert_config: "AlertConfig"
+    telegram_config: "TelegramConfig"  # Always exists (Config.telegram has default factory)
+    # Optional telegram fields
+    telegram_bot: "TelegramBot | None" = None
+    job_alert_to: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class SuccessContext:
+    """Passed to on_success. No trigger - use intent.metadata.
+
+    ctx.intent.metadata["reason"] = original trigger.reason
+    ctx.intent.metadata[...] = your custom data from build_tx()
+    """
+
+    intent: "TxIntent"
+    receipt: "TxReceipt"
+    events: list[DecodedEvent] | None
+    block: BlockContext
+    kv: "KVReader"  # Read-only
+    logger: "structlog.stdlib.BoundLogger"
+    # Alert routing
+    job_id: str
+    job_name: str
+    chain_id: int
+    alert_config: "AlertConfig"
+    telegram_config: "TelegramConfig"  # Always exists (Config.telegram has default factory)
+    # Optional telegram fields
+    telegram_bot: "TelegramBot | None" = None
+    job_alert_to: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class FailureContext:
+    """Passed to on_failure. Intent may be None for pre-intent failures.
+
+    Pre-intent failures include:
+    - check() exception
+    - build_tx() exception
+    - intent creation failure
+    """
+
+    intent: "TxIntent | None"  # None for pre-intent failures
+    attempt: "TxAttempt | None"  # intent None for pre-intent; attempt may be None even post-intent
+    error: Exception
+    failure_type: FailureType
+    failure_stage: FailureStage | None
+    block: BlockContext
+    kv: "KVReader"  # Read-only (no side effects during failure handling)
+    logger: "structlog.stdlib.BoundLogger"
+    # Alert routing
+    job_id: str
+    job_name: str
+    chain_id: int
+    alert_config: "AlertConfig"
+    telegram_config: "TelegramConfig"  # Always exists (Config.telegram has default factory)
+    # Optional telegram fields
+    telegram_bot: "TelegramBot | None" = None
+    job_alert_to: list[str] | None = None
+
+
+# =============================================================================
+# Context Size Caps (Prevent Re-Growth)
+# =============================================================================
+
+# These are validated in tests to prevent gradual re-growth into god object:
+# - BlockContext: <= 5 fields
+# - CheckContext: <= 7 fields
+# - BuildContext: <= 9 fields
+# - AlertContext: <= 10 fields
+
+
+__all__ = [
+    "BlockContext",
+    "CheckContext",
+    "BuildContext",
+    "AlertContext",
+    "TriggerContext",
+    "SuccessContext",
+    "FailureContext",
+    "ContractFactory",
+    "ContractHandle",
+]

brawny/model/enums.py

@@ -0,0 +1,70 @@
+"""Enumerations for brawny statuses and states."""
+
+from enum import Enum
+
+
+class IntentStatus(str, Enum):
+    """Transaction intent status."""
+
+    CREATED = "created"
+    CLAIMED = "claimed"
+    SENDING = "sending"
+    PENDING = "pending"
+    CONFIRMED = "confirmed"
+    FAILED = "failed"
+    ABANDONED = "abandoned"
+
+
+class AttemptStatus(str, Enum):
+    """Transaction attempt status."""
+
+    SIGNED = "signed"
+    BROADCAST = "broadcast"
+    PENDING = "pending"
+    CONFIRMED = "confirmed"
+    FAILED = "failed"
+    REPLACED = "replaced"
+
+
+class NonceStatus(str, Enum):
+    """Nonce reservation status."""
+
+    RESERVED = "reserved"
+    IN_FLIGHT = "in_flight"
+    RELEASED = "released"
+    ORPHANED = "orphaned"
+
+
+class TxStatus(str, Enum):
+    """Transaction lifecycle status. 4 states only.
+
+    IMPORTANT: Do not add new statuses. This enum is intentionally minimal.
+    """
+
+    CREATED = "created"      # Exists, not yet broadcast
+    BROADCAST = "broadcast"  # Has current_tx_hash, awaiting confirmation
+    CONFIRMED = "confirmed"  # Terminal: receipt status=1
+    FAILED = "failed"        # Terminal: permanent failure
+
+
+class ABISource(str, Enum):
+    """Source of ABI data."""
+
+    ETHERSCAN = "etherscan"
+    SOURCIFY = "sourcify"
+    MANUAL = "manual"
+    PROXY_IMPLEMENTATION = "proxy_implementation"
+
+
+class KeystoreType(str, Enum):
+    """Keystore type for private key management."""
+
+    ENV = "env"
+    FILE = "file"
+
+
+class LogFormat(str, Enum):
+    """Log output format."""
+
+    JSON = "json"
+    TEXT = "text"

brawny/model/errors.py

@@ -0,0 +1,194 @@
+"""Error types for brawny."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class HookType(Enum):
+    """Alert hook types."""
+
+    TRIGGERED = "triggered"
+    CONFIRMED = "confirmed"
+    FAILED = "failed"
+
+
+class TriggerReason:
+    """Constants for synthetic trigger reasons (not from job.check())."""
+
+    MISSING = "missing_trigger"
+    UNKNOWN_VERSION = "unknown_version"
+    INVALID_FORMAT = "invalid_format"
+    # CHECK_EXCEPTION and BUILD_TX_EXCEPTION use FailureType.*.value
+
+
+@dataclass
+class ErrorInfo:
+    """Structured error for alert context. JSON-safe."""
+
+    error_type: str  # e.g., "SimulationReverted", "BroadcastFailed"
+    message: str  # Truncated, sanitized
+    code: str | None = None  # RPC error code if applicable
+
+    @classmethod
+    def from_exception(cls, e: Exception, max_len: int = 200) -> "ErrorInfo":
+        """Create ErrorInfo from an exception."""
+        code = getattr(e, "code", None)
+        return cls(
+            error_type=type(e).__name__,
+            message=str(e)[:max_len],
+            code=str(code) if code is not None else None,
+        )
+
+
+class FailureStage(Enum):
+    """When in the lifecycle did the failure occur."""
+
+    PRE_BROADCAST = "pre_broadcast"  # Never made it to chain
+    BROADCAST = "broadcast"  # Failed during broadcast
+    POST_BROADCAST = "post_broadcast"  # Failed after broadcast (on-chain)
+
+
+class FailureType(Enum):
+    """What specifically failed."""
+
+    # Permanent (no retry will help)
+    SIMULATION_REVERTED = "simulation_reverted"  # TX would revert
+    TX_REVERTED = "tx_reverted"  # On-chain revert
+    DEADLINE_EXPIRED = "deadline_expired"  # Intent too old
+
+    # Transient (might resolve on retry)
+    SIMULATION_NETWORK_ERROR = "simulation_network_error"  # RPC issue during sim
+    BROADCAST_FAILED = "broadcast_failed"  # RPC rejected tx
+
+    # Pre-broadcast failures (kept for backward compat)
+    SIGNER_FAILED = "signer_failed"  # Keystore/signer issue
+    NONCE_FAILED = "nonce_failed"  # Couldn't reserve nonce
+    SIGN_FAILED = "sign_failed"  # Signing error
+    NONCE_CONSUMED = "nonce_consumed"  # Nonce used elsewhere
+
+    # Superseded (replaced by new attempt)
+    SUPERSEDED = "superseded"
+
+    # Reorg (terminal - we don't retry reorged intents)
+    REORGED = "reorged"
+
+    # Pre-intent exceptions (no intent created yet)
+    CHECK_EXCEPTION = "check_exception"  # job.check() crashed
+    BUILD_TX_EXCEPTION = "build_tx_exception"  # job.build_tx() crashed
+
+    # Fallback
+    UNKNOWN = "unknown"
+
+
+class BrawnyError(Exception):
+    """Base exception for all brawny errors."""
+
+    pass
+
+
+class ConfigError(BrawnyError):
+    """Configuration error."""
+
+    pass
+
+
+class DatabaseError(BrawnyError):
+    """Database operation error."""
+
+    pass
+
+
+class NonceError(BrawnyError):
+    """Nonce management error."""
+
+    pass
+
+
+class NonceReservationError(NonceError):
+    """Failed to reserve a nonce."""
+
+    pass
+
+
+class IntentError(BrawnyError):
+    """Transaction intent error."""
+
+    pass
+
+
+class RetriableExecutionError(BrawnyError):
+    """Temporary execution error that should be retried with backoff.
+
+    Used when execution cannot proceed temporarily (e.g., no gas quote available)
+    but may succeed after a backoff period.
+    """
+
+    pass
+
+
+class JobError(BrawnyError):
+    """Job execution error."""
+
+    pass
+
+
+class ReorgError(BrawnyError):
+    """Blockchain reorganization error."""
+
+    pass
+
+
+class KeystoreError(BrawnyError):
+    """Keystore or signing error."""
+
+    pass
+
+
+class ABIResolutionError(BrawnyError):
+    """ABI resolution failed."""
+
+    pass
+
+
+class ReceiptRequiredError(BrawnyError):
+    """Attempted to access receipt-only features without a receipt."""
+
+    pass
+
+
+class EventNotFoundError(BrawnyError):
+    """Event not found in receipt logs."""
+
+    pass
+
+
+class StateChangingCallError(BrawnyError):
+    """Attempted to call a state-changing function in a read-only context."""
+
+    pass
+
+
+class CircuitBreakerOpenError(BrawnyError):
+    """All RPC endpoints are unhealthy."""
+
+    pass
+
+
+class DatabaseCircuitBreakerOpenError(BrawnyError):
+    """Database circuit breaker is open."""
+
+    pass
+
+
+class SimulationReverted(BrawnyError):
+    """Transaction would revert on-chain. Permanent failure - do not retry or broadcast."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class SimulationNetworkError(BrawnyError):
+    """Network/RPC error during simulation. Transient - may retry."""
+
+    pass

brawny/model/events.py

@@ -0,0 +1,93 @@
+"""Event decoding types and helpers.
+
+DecodedEvent is a frozen dataclass representing a single decoded log event.
+Helper functions are pure functions, not methods.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class DecodedEvent:
+    """Single decoded log event. Immutable.
+
+    Use Mapping[str, Any] for args to ensure immutability.
+    The args are wrapped with MappingProxyType at construction.
+    """
+
+    address: str
+    event_name: str
+    args: Mapping[str, Any]  # Immutable - use MappingProxyType when constructing
+    log_index: int
+    tx_hash: str
+    block_number: int
+
+    @classmethod
+    def create(
+        cls,
+        address: str,
+        event_name: str,
+        args: dict[str, Any],
+        log_index: int,
+        tx_hash: str,
+        block_number: int,
+    ) -> DecodedEvent:
+        """Create a DecodedEvent with immutable args.
+
+        Wraps the args dict in MappingProxyType to ensure immutability.
+        """
+        return cls(
+            address=address,
+            event_name=event_name,
+            args=MappingProxyType(args),
+            log_index=log_index,
+            tx_hash=tx_hash,
+            block_number=block_number,
+        )
+
+
+def find_event(events: list[DecodedEvent], event_name: str) -> DecodedEvent | None:
+    """Find the first event matching the given name.
+
+    Args:
+        events: List of decoded events
+        event_name: Name of event to find
+
+    Returns:
+        First matching event, or None if not found
+    """
+    for event in events:
+        if event.event_name == event_name:
+            return event
+    return None
+
+
+def events_by_name(events: list[DecodedEvent], event_name: str) -> list[DecodedEvent]:
+    """Get all events matching the given name.
+
+    Args:
+        events: List of decoded events
+        event_name: Name of events to find
+
+    Returns:
+        List of matching events (may be empty)
+    """
+    return [e for e in events if e.event_name == event_name]
+
+
+def events_by_address(events: list[DecodedEvent], address: str) -> list[DecodedEvent]:
+    """Get all events emitted by the given address.
+
+    Args:
+        events: List of decoded events
+        address: Contract address (case-insensitive comparison)
+
+    Returns:
+        List of matching events (may be empty)
+    """
+    addr_lower = address.lower()
+    return [e for e in events if e.address.lower() == addr_lower]

brawny/model/startup.py

@@ -0,0 +1,20 @@
+"""Startup diagnostic message types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class StartupMessage:
+    """Startup diagnostic message for human-readable display.
+
+    Used to collect warnings and errors during startup for display
+    before the "--- Starting brawny ---" banner.
+    """
+
+    level: Literal["warning", "error"]
+    code: str
+    message: str
+    fix: str | None = None  # Actionable fix suggestion