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

brawny/model/types.py

@@ -16,8 +16,7 @@ JSONValue = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSO
 # Hook names for type-safe dispatch
 HookName = Literal["on_trigger", "on_success", "on_failure"]
 
-from brawny.model.enums import AttemptStatus, IntentStatus, NonceStatus, TxStatus
-from brawny.model.errors import FailureType
+from brawny.model.enums import AttemptStatus, IntentStatus, NonceStatus
 
 
 def to_wei(value: int | float | str) -> int:
@@ -96,10 +95,19 @@ class BlockInfo:
     block_number: int
     block_hash: str
     timestamp: int
+    base_fee: int = 0
 
     def __post_init__(self) -> None:
         if not self.block_hash.startswith("0x"):
             object.__setattr__(self, "block_hash", f"0x{self.block_hash}")
+        base_fee = self.base_fee
+        if base_fee is None:
+            base_fee = 0
+        elif isinstance(base_fee, str):
+            base_fee = int(base_fee, 16) if base_fee.startswith("0x") else int(base_fee)
+        else:
+            base_fee = int(base_fee)
+        object.__setattr__(self, "base_fee", base_fee)
 
 
 @dataclass
@@ -154,12 +162,16 @@ class TxIntent:
     claimed_at: datetime | None
     created_at: datetime
     updated_at: datetime
+    claimed_by: str | None = None
+    lease_expires_at: datetime | None = None
+    signer_alias: str | None = None
     retry_count: int = 0
 
     # Broadcast binding (set on first successful broadcast)
     # These fields preserve the privacy invariant: retries use the SAME endpoints
     broadcast_group: str | None = None
     broadcast_endpoints_json: str | None = None
+    broadcast_binding_id: UUID | None = None
 
     # Per-intent context for alerts (parsed dict, not JSON string)
     metadata: dict[str, JSONValue] = field(default_factory=dict)
@@ -240,6 +252,7 @@ class TxAttempt:
     # Audit trail (which group and endpoint were used for this attempt)
     broadcast_group: str | None = None
     endpoint_url: str | None = None
+    endpoint_binding_id: UUID | None = None
 
 
 @dataclass
@@ -272,135 +285,6 @@ class BroadcastInfo:
         )
 
 
-@dataclass
-class TxHashRecord:
-    """Record of a single broadcast attempt, stored in tx_hash_history JSON.
-
-    This is append-only archival data for debugging and postmortems.
-    NEVER query this in normal flows.
-    """
-
-    tx_hash: str
-    nonce: int
-    broadcast_at: str  # ISO timestamp
-    broadcast_block: int | None
-    gas_limit: int
-    max_fee_per_gas: int
-    max_priority_fee_per_gas: int
-    reason: str  # "initial", "replacement", "fee_bump"
-    outcome: str | None = None  # "confirmed", "replaced", "failed", None (pending)
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return {
-            "tx_hash": self.tx_hash,
-            "nonce": self.nonce,
-            "broadcast_at": self.broadcast_at,
-            "broadcast_block": self.broadcast_block,
-            "gas_limit": self.gas_limit,
-            "max_fee_per_gas": self.max_fee_per_gas,
-            "max_priority_fee_per_gas": self.max_priority_fee_per_gas,
-            "reason": self.reason,
-            "outcome": self.outcome,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "TxHashRecord":
-        """Create from dict."""
-        return cls(
-            tx_hash=data["tx_hash"],
-            nonce=data["nonce"],
-            broadcast_at=data["broadcast_at"],
-            broadcast_block=data.get("broadcast_block"),
-            gas_limit=data["gas_limit"],
-            max_fee_per_gas=data["max_fee_per_gas"],
-            max_priority_fee_per_gas=data["max_priority_fee_per_gas"],
-            reason=data["reason"],
-            outcome=data.get("outcome"),
-        )
-
-
-@dataclass
-class Transaction:
-    """Single model representing a job transaction through its full lifecycle.
-
-    IMPORTANT: Transaction is the only durable execution model.
-    Do not add attempt tables.
-
-    This replaces the old TxIntent + TxAttempt dual model with a single
-    row per transaction. Replacement history is preserved in tx_hash_history
-    JSON field (append-only, for debugging only).
-    """
-
-    # Identity (queryable)
-    tx_id: UUID  # Primary key
-    job_id: str
-    chain_id: int
-    idempotency_key: str  # UNIQUE - prevents duplicates
-
-    # Transaction payload (immutable after creation)
-    signer_address: str
-    to_address: str
-    data: str | None
-    value_wei: str
-    min_confirmations: int
-    deadline_ts: datetime | None
-
-    # Current state (queryable)
-    status: TxStatus  # CREATED → BROADCAST → CONFIRMED/FAILED
-    failure_type: FailureType | None
-
-    # Broadcast state (queryable)
-    current_tx_hash: str | None  # Active tx hash being monitored
-    current_nonce: int | None  # Nonce for current broadcast
-    replacement_count: int  # 0 = first attempt, 1+ = replacements
-
-    # Worker coordination (queryable)
-    claim_token: str | None
-    claimed_at: datetime | None
-
-    # Confirmation (queryable)
-    included_block: int | None
-    confirmed_at: datetime | None
-
-    # Audit (queryable)
-    created_at: datetime
-    updated_at: datetime
-
-    # --- JSON BLOBS (rarely queried) ---
-
-    # Gas params for current/next attempt
-    gas_params_json: str | None = None  # {"gas_limit": N, "max_fee": N, "priority_fee": N}
-
-    # Broadcast binding (privacy invariant)
-    broadcast_info_json: str | None = None  # {"group": str, "endpoints": [...]}
-
-    # Error details (debugging only)
-    error_info_json: str | None = None  # ErrorInfo as JSON
-
-    # Broadcast history (append-only, debugging only)
-    tx_hash_history: str | None = None  # JSON array of TxHashRecord
-
-    @property
-    def gas_params(self) -> GasParams | None:
-        """Get gas params from JSON."""
-        if self.gas_params_json is None:
-            return None
-        return GasParams.from_json(self.gas_params_json)
-
-    @property
-    def broadcast_info(self) -> BroadcastInfo | None:
-        """Get broadcast info from JSON."""
-        return BroadcastInfo.from_json(self.broadcast_info_json)
-
-    def get_hash_history(self) -> list[TxHashRecord]:
-        """Get tx hash history from JSON. For debugging only."""
-        if self.tx_hash_history is None:
-            return []
-        records = json.loads(self.tx_hash_history)
-        return [TxHashRecord.from_dict(r) for r in records]
-
-
 @dataclass
 class NonceReservation:
     """Nonce reservation record."""
@@ -427,6 +311,36 @@ class SignerState:
     updated_at: datetime
     gap_started_at: datetime | None = None  # When nonce gap blocking started (for alerts)
     alias: str | None = None  # Optional human-readable alias
+    quarantined_at: datetime | None = None
+    quarantine_reason: str | None = None
+    replacements_paused: bool = False
+
+
+@dataclass
+class RuntimeControl:
+    """Runtime containment control with TTL."""
+
+    control: str
+    active: bool
+    expires_at: datetime | None
+    reason: str | None
+    actor: str | None
+    mode: str
+    updated_at: datetime
+
+
+@dataclass
+class MutationAudit:
+    """Durable mutation audit record."""
+
+    entity_type: str
+    entity_id: str
+    action: str
+    actor: str | None
+    reason: str | None
+    source: str | None
+    metadata_json: str | None
+    created_at: datetime
 
 
 @dataclass
@@ -439,6 +353,8 @@ class JobConfig:
     check_interval_blocks: int
     last_checked_block_number: int | None
     last_triggered_block_number: int | None
+    drain_until: datetime | None
+    drain_reason: str | None
     created_at: datetime
     updated_at: datetime
 

brawny/network_guard.py

@@ -0,0 +1,133 @@
+"""Runtime network guard for job execution contexts."""
+
+from __future__ import annotations
+
+import inspect
+import socket
+import threading
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Iterator
+
+from brawny.logging import get_logger
+from brawny.metrics import get_metrics, NETWORK_GUARD_ALLOW, NETWORK_GUARD_VIOLATION
+
+
+_guard_depth = 0
+_guard_context_counts: dict[str, int] = {}
+_guard_lock = threading.RLock()
+_allow_network: ContextVar[bool] = ContextVar("brawny_allow_network", default=False)
+_allow_reason: ContextVar[str | None] = ContextVar("brawny_allow_reason", default=None)
+_patched = False
+
+_ALLOWED_REASONS = frozenset({"rpc", "alerts", "approved_http_client"})
+
+logger = get_logger(__name__)
+
+
+def install_network_guard() -> None:
+    """Install socket-level guard (idempotent)."""
+    global _patched
+    if _patched:
+        return
+
+    original_connect = socket.socket.connect
+    original_create_connection = socket.create_connection
+
+    def guarded_connect(sock: socket.socket, address: object) -> object:
+        if _guard_is_active() and not _allow_network.get():
+            _record_violation()
+            raise RuntimeError(
+                "Direct network call blocked. Use ctx.rpc or ctx.http (approved clients)."
+            )
+        return original_connect(sock, address)
+
+    def guarded_create_connection(*args: object, **kwargs: object) -> socket.socket:
+        if _guard_is_active() and not _allow_network.get():
+            _record_violation()
+            raise RuntimeError(
+                "Direct network call blocked. Use ctx.rpc or ctx.http (approved clients)."
+            )
+        return original_create_connection(*args, **kwargs)
+
+    socket.socket.connect = guarded_connect  # type: ignore[assignment]
+    socket.create_connection = guarded_create_connection  # type: ignore[assignment]
+    _patched = True
+
+
+def _guard_is_active() -> bool:
+    with _guard_lock:
+        return _guard_depth > 0
+
+
+def _current_context() -> str:
+    with _guard_lock:
+        if "job" in _guard_context_counts:
+            return "job"
+        if _guard_context_counts:
+            return next(iter(_guard_context_counts.keys()))
+    return "unknown"
+
+
+def _caller_module() -> str:
+    for frame_info in inspect.stack()[2:]:
+        module = inspect.getmodule(frame_info.frame)
+        if module is None:
+            continue
+        name = module.__name__
+        if name.startswith(("socket", "httpx", "requests", "urllib", "ssl", "asyncio")):
+            continue
+        if name.startswith("brawny"):
+            continue
+        return name
+    return "unknown"
+
+
+def _record_violation() -> None:
+    metrics = get_metrics()
+    metrics.counter(NETWORK_GUARD_VIOLATION).inc(
+        context=_current_context(),
+        caller_module=_caller_module(),
+    )
+    logger.warning(
+        "network_guard.violation",
+        context=_current_context(),
+        caller_module=_caller_module(),
+    )
+
+
+@contextmanager
+def job_network_guard(context: str = "job") -> Iterator[None]:
+    """Enable network guard within a job execution context."""
+    install_network_guard()
+    with _guard_lock:
+        global _guard_depth
+        _guard_depth += 1
+        _guard_context_counts[context] = _guard_context_counts.get(context, 0) + 1
+    try:
+        yield
+    finally:
+        with _guard_lock:
+            current = _guard_context_counts.get(context, 0)
+            if current <= 1:
+                _guard_context_counts.pop(context, None)
+            else:
+                _guard_context_counts[context] = current - 1
+            _guard_depth -= 1
+
+
+@contextmanager
+def allow_network_calls(reason: str) -> Iterator[None]:
+    """Temporarily allow network calls within a guarded context."""
+    if reason not in _ALLOWED_REASONS:
+        raise ValueError(f"Invalid allow_network reason: {reason}")
+    metrics = get_metrics()
+    metrics.counter(NETWORK_GUARD_ALLOW).inc(reason=reason)
+    logger.debug("network_guard.allow", reason=reason)
+    token = _allow_network.set(True)
+    reason_token = _allow_reason.set(reason)
+    try:
+        yield
+    finally:
+        _allow_reason.reset(reason_token)
+        _allow_network.reset(token)

brawny/networks/__init__.py

@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING
 from brawny.networks.manager import _get_manager
 
 if TYPE_CHECKING:
-    from brawny._rpc import RPCManager
+    from brawny._rpc.clients import ReadClient
 
 
 class _NetworkProxy:
@@ -57,12 +57,12 @@ class _NetworkProxy:
         return _get_manager().list_networks()
 
     @property
-    def rpc(self) -> RPCManager | None:
-        """Get underlying RPCManager."""
+    def rpc(self) -> ReadClient | None:
+        """Get underlying read client."""
         return _get_manager().rpc
 
-    def rpc_required(self) -> RPCManager:
-        """Get RPCManager, raising error if not connected.
+    def rpc_required(self) -> ReadClient:
+        """Get read client, raising error if not connected.
 
         Use this instead of checking `if network.rpc is None` everywhere.
 

brawny/networks/config.py

@@ -94,12 +94,9 @@ class NetworkConfig:
     multicall2: str | None = None  # Passed to Contract layer for batch calls
     timeout: int = 30
 
-    # RPC settings (passed to RPCManager for production-grade handling)
+    # RPC settings (passed to ReadClient for production-grade handling)
     max_retries: int = 3
     retry_backoff_base: float = 1.0
-    circuit_breaker_seconds: int = 300
-    rate_limit_per_second: float | None = None
-    rate_limit_burst: int | None = None
 
     # Development network fields (None for live networks)
     cmd: str | None = None
@@ -201,9 +198,6 @@ def _parse_networks(data: dict) -> dict[str, NetworkConfig]:
                 timeout=net.get("timeout", 30),
                 max_retries=net.get("max_retries", 3),
                 retry_backoff_base=net.get("retry_backoff_base", 1.0),
-                circuit_breaker_seconds=net.get("circuit_breaker_seconds", 300),
-                rate_limit_per_second=net.get("rate_limit_per_second"),
-                rate_limit_burst=net.get("rate_limit_burst"),
             )
 
     # Parse development networks (fork resolution happens at connect time)

brawny/networks/manager.py

@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING
 from brawny.networks.config import NetworkConfig, load_networks
 
 if TYPE_CHECKING:
-    from brawny._rpc import RPCManager
+    from brawny._rpc.clients import ReadClient
 
 
 def _get_pidfile_dir() -> Path:
@@ -49,7 +49,7 @@ class NetworkManager:
     def __init__(self) -> None:
         self._networks: dict[str, NetworkConfig] | None = None
         self._active: NetworkConfig | None = None
-        self._rpc: RPCManager | None = None
+        self._rpc: ReadClient | None = None
         self._rpc_process: subprocess.Popen | None = None
         self._rpc_process_network_id: str | None = None  # Track which network we started
         self._chain_id: int | None = None  # Cached after first lookup
@@ -161,7 +161,7 @@ class NetworkManager:
         # Resolve fork reference at connect time
         self._resolve_fork(config, networks)
 
-        # Get endpoints (list) - RPCManager handles failover automatically
+        # Get endpoints (list) - read client handles failover automatically
         endpoints = config.get_endpoints()
 
         # Launch RPC for development networks
@@ -179,17 +179,20 @@ class NetworkManager:
             # Dev networks only use local endpoint
             endpoints = [local_url]
 
-        # Create RPCManager with full configuration (preserves brawny's advantages)
-        from brawny._rpc import RPCManager
+        # Create read client with full configuration (preserves brawny's advantages)
+        from brawny._rpc.clients import ReadClient
+        from brawny._rpc.retry_policy import policy_from_values
 
-        self._rpc = RPCManager(
+        self._rpc = ReadClient(
             endpoints=endpoints,
             timeout_seconds=float(config.timeout),
             max_retries=config.max_retries,
             retry_backoff_base=config.retry_backoff_base,
-            circuit_breaker_seconds=config.circuit_breaker_seconds,
-            rate_limit_per_second=config.rate_limit_per_second,
-            rate_limit_burst=config.rate_limit_burst,
+            retry_policy=policy_from_values(
+                "FAST_READ",
+                max_attempts=config.max_retries,
+                base_backoff_seconds=config.retry_backoff_base,
+            ),
             chain_id=config.chainid,
         )
         self._active = config
@@ -403,8 +406,8 @@ class NetworkManager:
         }
 
     @property
-    def rpc(self) -> RPCManager | None:
-        """Get underlying RPCManager."""
+    def rpc(self) -> ReadClient | None:
+        """Get underlying read client."""
         return self._rpc
 
 

brawny/runtime_controls.py

@@ -0,0 +1,74 @@
+"""Runtime controls with TTL caching."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from brawny.model.types import RuntimeControl
+from brawny.metrics import RUNTIME_CONTROL_ACTIVE, RUNTIME_CONTROL_TTL_SECONDS, get_metrics
+
+if TYPE_CHECKING:
+    from brawny.db.base import Database
+
+
+@dataclass
+class _CachedControl:
+    control: RuntimeControl | None
+    expires_at: float
+
+
+class RuntimeControls:
+    """Cached runtime controls accessor."""
+
+    def __init__(self, db: "Database", ttl_seconds: float = 2.0) -> None:
+        self._db = db
+        self._ttl_seconds = ttl_seconds
+        self._lock = threading.RLock()
+        self._cache: dict[str, _CachedControl] = {}
+
+    def get(self, control: str) -> RuntimeControl | None:
+        now = time.monotonic()
+        with self._lock:
+            cached = self._cache.get(control)
+            if cached and cached.expires_at > now:
+                return cached.control
+
+        value = self._db.get_runtime_control(control)
+        self._emit_metrics(control, value)
+        with self._lock:
+            self._cache[control] = _CachedControl(
+                control=value,
+                expires_at=now + self._ttl_seconds,
+            )
+        return value
+
+    def is_active(self, control: str) -> bool:
+        rc = self.get(control)
+        if rc is None or not rc.active:
+            return False
+        if rc.expires_at is None:
+            return True
+        now = datetime.utcnow()
+        if rc.expires_at.tzinfo is not None:
+            now = datetime.now(rc.expires_at.tzinfo)
+        return rc.expires_at > now
+
+    def refresh(self, control: str) -> None:
+        with self._lock:
+            if control in self._cache:
+                del self._cache[control]
+
+    def _emit_metrics(self, control: str, rc: RuntimeControl | None) -> None:
+        metrics = get_metrics()
+        if rc is None:
+            metrics.gauge(RUNTIME_CONTROL_ACTIVE).set(0, control=control)
+            return
+        metrics.gauge(RUNTIME_CONTROL_ACTIVE).set(1 if rc.active else 0, control=control)
+        if rc.expires_at:
+            now = datetime.utcnow()
+            ttl = (rc.expires_at - now).total_seconds()
+            metrics.gauge(RUNTIME_CONTROL_TTL_SECONDS).set(max(ttl, 0), control=control)

brawny/scheduler/poller.py

@@ -36,7 +36,7 @@ if TYPE_CHECKING:
     from brawny.config import Config
     from brawny.db.base import Database
     from brawny.model.types import BlockInfo
-    from brawny._rpc.manager import RPCManager
+    from brawny._rpc.clients import ReadClient
     from brawny.scheduler.reorg import ReorgDetector
 
 logger = get_logger(__name__)
@@ -69,7 +69,7 @@ class BlockPoller:
     def __init__(
         self,
         db: Database,
-        rpc: RPCManager,
+        rpc: ReadClient,
         config: Config,
         block_handler: Callable[[BlockInfo], None],
         reorg_detector: "ReorgDetector | None" = None,
@@ -250,6 +250,12 @@ class BlockPoller:
             try:
                 if self._reorg_detector:
                     reorg_result = self._reorg_detector.check(block_number)
+                    if reorg_result is None:
+                        return PollResult(
+                            blocks_processed=0,
+                            head_block=head_block,
+                            last_processed=last_processed,
+                        )
                     if reorg_result.reorg_detected:
                         if reorg_result.pause:
                             logger.error(
@@ -306,15 +312,11 @@ class BlockPoller:
                     block_info = self._fetch_block_info(block_number)
                     if block_info is not None:
                         break
-                    # Exponential backoff: 0.5s, 1s, 2s
-                    backoff = 0.5 * (2**retry)
                     logger.debug(
                         "poller.block_fetch_retry",
                         block_number=block_number,
                         retry=retry + 1,
-                        backoff_seconds=backoff,
                     )
-                    time.sleep(backoff)
 
                 if block_info is None:
                     logger.warning(
@@ -446,6 +448,7 @@ class BlockPoller:
             BlockInfo or None if not found
         """
         from brawny.model.types import BlockInfo
+        from brawny._rpc.errors import RPCError
 
         try:
             block = self._rpc.get_block(block_number)
@@ -457,8 +460,9 @@ class BlockPoller:
                 block_number=block["number"],
                 block_hash=f"0x{block['hash'].hex()}" if isinstance(block["hash"], bytes) else block["hash"],
                 timestamp=block["timestamp"],
+                base_fee=block.get("baseFeePerGas", 0),
             )
-        except Exception:
+        except (RPCError, KeyError, TypeError, ValueError):
             return None
 
     def poll_once(self) -> PollResult: