brawny 0.1.13__py3-none-any.whl

brawny/db/sqlite_new.py

@@ -0,0 +1,191 @@
+"""SQLite database implementation.
+
+Slim execution layer with 4 primitives. All business operations live in db/ops/.
+Uses single connection with WAL mode.
+
+SQLite supports :name placeholders natively with dict params.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from brawny.db.base_new import Database, Dialect, IsolationLevel
+from brawny.model.errors import DatabaseError
+
+
+def _adapt_datetime(dt: datetime) -> str:
+    """Adapt datetime to ISO format string for SQLite."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat()
+
+
+def _convert_datetime(val: bytes) -> datetime:
+    """Convert ISO format string from SQLite to datetime."""
+    s = val.decode("utf-8")
+    try:
+        return datetime.fromisoformat(s)
+    except ValueError:
+        # Handle format without timezone
+        return datetime.strptime(s, "%Y-%m-%d %H:%M:%S").replace(tzinfo=timezone.utc)
+
+
+# Register adapters globally
+sqlite3.register_adapter(datetime, _adapt_datetime)
+sqlite3.register_converter("TIMESTAMP", _convert_datetime)
+
+
+def _dict_factory(cursor: sqlite3.Cursor, row: tuple) -> dict[str, Any]:
+    """Row factory that returns dict rows."""
+    cols = [d[0] for d in cursor.description]
+    return dict(zip(cols, row))
+
+
+class SQLiteDatabase(Database):
+    """SQLite implementation with single connection.
+
+    Uses WAL mode for better concurrency. Thread safety via lock.
+    Queries use :name placeholders natively.
+    """
+
+    def __init__(self, database_path: str) -> None:
+        """Initialize SQLite database.
+
+        Args:
+            database_path: Path to SQLite database file (or :memory:)
+        """
+        # Remove sqlite:/// prefix if present
+        if database_path.startswith("sqlite:///"):
+            database_path = database_path[10:]
+
+        self._database_path = database_path
+        self._conn: sqlite3.Connection | None = None
+        self._lock = threading.RLock()
+        self._in_transaction = False
+
+    @property
+    def dialect(self) -> Dialect:
+        """Return dialect name for query selection."""
+        return "sqlite"
+
+    def connect(self) -> None:
+        """Establish database connection."""
+        if self._conn is not None:
+            return
+
+        # Create directory if needed
+        if self._database_path != ":memory:":
+            path = Path(self._database_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+
+        self._conn = sqlite3.connect(
+            self._database_path,
+            detect_types=sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES,
+            check_same_thread=False,
+            timeout=30.0,
+            isolation_level=None,  # Autocommit mode - we manage transactions manually
+        )
+        self._conn.row_factory = _dict_factory
+        # Enable foreign keys and WAL mode
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.execute("PRAGMA journal_mode = WAL")
+
+    def close(self) -> None:
+        """Close database connection."""
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def is_connected(self) -> bool:
+        """Check if database is connected."""
+        return self._conn is not None
+
+    def _ensure_connected(self) -> sqlite3.Connection:
+        """Ensure connection exists and return it."""
+        if self._conn is None:
+            raise DatabaseError("Database not connected. Call connect() first.")
+        return self._conn
+
+    @contextmanager
+    def transaction(
+        self, isolation_level: IsolationLevel | None = None
+    ) -> Iterator[None]:
+        """Context manager for database transactions.
+
+        Uses BEGIN IMMEDIATE for write transactions to avoid
+        SQLITE_BUSY errors on concurrent writes.
+
+        Args:
+            isolation_level: Ignored on SQLite (BEGIN IMMEDIATE provides isolation)
+        """
+        conn = self._ensure_connected()
+
+        with self._lock:
+            if self._in_transaction:
+                raise DatabaseError("Nested transactions are not supported")
+
+            try:
+                conn.execute("BEGIN IMMEDIATE")
+                self._in_transaction = True
+                yield
+                conn.commit()
+            except Exception:
+                conn.rollback()
+                raise
+            finally:
+                self._in_transaction = False
+
+    def execute(self, query: str, params: dict[str, Any] | None = None) -> None:
+        """Execute a query without returning results."""
+        conn = self._ensure_connected()
+        with self._lock:
+            try:
+                conn.execute(query, params or {})
+                if not self._in_transaction:
+                    conn.commit()
+            except sqlite3.Error as e:
+                raise DatabaseError(f"SQLite query failed: {e}") from e
+
+    def fetch_one(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any] | None:
+        """Execute a query and return single result or None."""
+        conn = self._ensure_connected()
+        with self._lock:
+            try:
+                cursor = conn.execute(query, params or {})
+                return cursor.fetchone()
+            except sqlite3.Error as e:
+                raise DatabaseError(f"SQLite query failed: {e}") from e
+
+    def fetch_all(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """Execute a query and return all results."""
+        conn = self._ensure_connected()
+        with self._lock:
+            try:
+                cursor = conn.execute(query, params or {})
+                return cursor.fetchall()
+            except sqlite3.Error as e:
+                raise DatabaseError(f"SQLite query failed: {e}") from e
+
+    def execute_rowcount(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> int:
+        """Execute a query and return affected row count."""
+        conn = self._ensure_connected()
+        with self._lock:
+            try:
+                cursor = conn.execute(query, params or {})
+                if not self._in_transaction:
+                    conn.commit()
+                return cursor.rowcount
+            except sqlite3.Error as e:
+                raise DatabaseError(f"SQLite query failed: {e}") from e

brawny/history.py

@@ -0,0 +1,126 @@
+"""Transaction history tracking.
+
+Usage:
+    from brawny import history
+
+    history[-1]                    # Last transaction
+    history.filter(sender="0x...")  # Filter by attribute
+    len(history)                   # Count
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Iterator
+
+if TYPE_CHECKING:
+    from brawny.jobs.base import TxReceipt
+
+
+_history: "TxHistory | None" = None
+
+
+class TxHistory:
+    """Container for transaction receipts in current session.
+
+    Brownie-compatible interface for tracking transactions.
+    Note: Scripts are single-threaded, so no locking is needed.
+    """
+
+    def __init__(self) -> None:
+        self._receipts: list["TxReceipt"] = []
+
+    def _add(self, receipt: "TxReceipt") -> None:
+        """Add receipt to history (internal use)."""
+        self._receipts.append(receipt)
+
+    def __getitem__(self, index: int) -> "TxReceipt":
+        return self._receipts[index]
+
+    def __len__(self) -> int:
+        return len(self._receipts)
+
+    def __iter__(self) -> Iterator["TxReceipt"]:
+        return iter(self._receipts)
+
+    def filter(
+        self,
+        key: Callable[["TxReceipt"], bool] | None = None,
+        **kwargs: Any,
+    ) -> list["TxReceipt"]:
+        """Filter transactions by attribute or function.
+
+        Args:
+            key: Optional filter function
+            **kwargs: Attribute filters (e.g., sender="0x...")
+
+        Returns:
+            List of matching receipts
+        """
+        results = list(self._receipts)
+
+        if key:
+            results = [r for r in results if key(r)]
+
+        for attr, value in kwargs.items():
+            results = [r for r in results if getattr(r, attr, None) == value]
+
+        return results
+
+    def clear(self) -> None:
+        """Clear transaction history."""
+        self._receipts.clear()
+
+    def copy(self) -> list["TxReceipt"]:
+        """Get copy of receipts as list."""
+        return list(self._receipts)
+
+    def __repr__(self) -> str:
+        return f"<TxHistory [{len(self)} txs]>"
+
+
+def _init_history() -> None:
+    """Initialize global history singleton."""
+    global _history
+    _history = TxHistory()
+
+
+def _get_history() -> TxHistory:
+    """Get history singleton."""
+    if _history is None:
+        _init_history()
+    return _history
+
+
+def _add_to_history(receipt: "TxReceipt") -> None:
+    """Add receipt to global history."""
+    _get_history()._add(receipt)
+
+
+# Proxy for import-time access
+class _HistoryProxy:
+    """Proxy that delegates to history singleton."""
+
+    def __getitem__(self, index: int) -> "TxReceipt":
+        return _get_history()[index]
+
+    def __len__(self) -> int:
+        return len(_get_history())
+
+    def __iter__(self) -> Iterator["TxReceipt"]:
+        return iter(_get_history())
+
+    def filter(self, key: Callable | None = None, **kwargs: Any) -> list["TxReceipt"]:
+        return _get_history().filter(key, **kwargs)
+
+    def clear(self) -> None:
+        _get_history().clear()
+
+    def copy(self) -> list["TxReceipt"]:
+        return _get_history().copy()
+
+    def __repr__(self) -> str:
+        return repr(_get_history())
+
+
+# Global proxy instance
+history = _HistoryProxy()

brawny/interfaces.py

@@ -0,0 +1,136 @@
+"""Project interface support (Brownie-style JSON ABI interfaces)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from brawny.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _load_json_abi(path: Path) -> list[dict[str, Any]]:
+    """Load ABI list from a JSON file.
+
+    Accepts either a raw ABI list or an artifact with an "abi" field.
+    """
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict) and isinstance(data.get("abi"), list):
+        return data["abi"]
+    raise ValueError("Interface JSON must be ABI list or object with 'abi' list")
+
+
+@dataclass(frozen=True)
+class InterfaceConstructor:
+    """Constructor used to create Contract handles from a JSON ABI."""
+
+    name: str
+    abi: list[dict[str, Any]]
+    selectors: dict[bytes, str] = field(init=False)
+
+    def __post_init__(self) -> None:
+        from eth_utils import function_signature_to_4byte_selector
+        from brawny.alerts.abi_resolver import get_function_signature
+
+        selectors: dict[bytes, str] = {}
+        for item in self.abi:
+            if item.get("type") != "function":
+                continue
+            signature = get_function_signature(item["name"], item.get("inputs", []))
+            selectors[function_signature_to_4byte_selector(signature)] = item["name"]
+        object.__setattr__(self, "selectors", selectors)
+
+    def __call__(self, address: str):
+        from brawny.api import Contract
+
+        return Contract(address, abi=self.abi)
+
+    def __repr__(self) -> str:
+        return f"<InterfaceConstructor '{self.name}'>"
+
+    def decode_input(self, calldata: str | bytes) -> tuple[str, list[Any]]:
+        """Decode calldata for this interface.
+
+        Returns:
+            (function_signature, decoded_args)
+        """
+        from eth_abi import decode as abi_decode
+        from eth_utils import function_signature_to_4byte_selector
+        from hexbytes import HexBytes
+        from brawny.alerts.abi_resolver import get_function_signature
+
+        data = HexBytes(calldata)
+        fn_selector = data[:4]
+
+        abi = next(
+            (
+                item
+                for item in self.abi
+                if item.get("type") == "function"
+                and function_signature_to_4byte_selector(
+                    get_function_signature(item["name"], item.get("inputs", []))
+                )
+                == fn_selector
+            ),
+            None,
+        )
+        if abi is None:
+            raise ValueError("Four byte selector does not match the ABI for this contract")
+
+        function_sig = get_function_signature(abi["name"], abi.get("inputs", []))
+        types_list = [inp["type"] for inp in abi.get("inputs", [])]
+        decoded = list(abi_decode(types_list, data[4:])) if types_list else []
+        return function_sig, decoded
+
+
+class InterfaceContainer:
+    """Container providing access to interfaces within ./interfaces."""
+
+    def __init__(self, interfaces_dir: Path | None = None) -> None:
+        self._interfaces_dir = interfaces_dir or (Path.cwd() / "interfaces")
+        self._loaded = False
+
+    def _load(self) -> None:
+        if self._loaded:
+            return
+        self._loaded = True
+        if not self._interfaces_dir.is_dir():
+            return
+
+        for path in sorted(self._interfaces_dir.rglob("*.json")):
+            name = path.stem
+            try:
+                abi = _load_json_abi(path)
+            except Exception as exc:
+                logger.warning(
+                    "interface.load_failed",
+                    name=name,
+                    path=str(path),
+                    error=str(exc),
+                )
+                continue
+            self._add(name, abi)
+
+    def _add(self, name: str, abi: list[dict[str, Any]]) -> None:
+        constructor = InterfaceConstructor(name, abi)
+        setattr(self, name, constructor)
+
+    def __getattr__(self, name: str):
+        self._load()
+        try:
+            return self.__dict__[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def __dir__(self) -> list[str]:
+        self._load()
+        return sorted(set(self.__dict__.keys()))
+
+
+# Singleton instance (Brownie-style)
+interface = InterfaceContainer()

brawny/invariants.py

@@ -0,0 +1,155 @@
+"""System invariants exposed as metrics.
+
+These queries should return 0 in a healthy system. Non-zero values
+indicate potential issues that need investigation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING, Any
+
+from brawny.alerts.health import health_alert
+from brawny.logging import get_logger
+from brawny.metrics import (
+    INVARIANT_NONCE_GAP_AGE,
+    INVARIANT_ORPHANED_CLAIMS,
+    INVARIANT_ORPHANED_NONCES,
+    INVARIANT_PENDING_NO_ATTEMPTS,
+    INVARIANT_STUCK_CLAIMED,
+    get_metrics,
+)
+
+if TYPE_CHECKING:
+    from brawny.db.base import Database
+
+logger = get_logger(__name__)
+
+# Threshold for "stuck" claimed intents (minutes)
+STUCK_CLAIM_THRESHOLD_MINUTES = 10
+
+
+def _get_stuck_claim_details(
+    db: "Database",
+    chain_id: int,
+    older_than_minutes: int = STUCK_CLAIM_THRESHOLD_MINUTES,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """Fetch sample of stuck claimed intents for debugging context."""
+    if db.dialect == "sqlite":
+        query = """
+            SELECT intent_id, job_id,
+                   (julianday('now') - julianday(claimed_at)) * 86400 as age_seconds
+            FROM tx_intents
+            WHERE chain_id = :chain_id
+              AND status = 'claimed'
+              AND datetime(claimed_at) < datetime('now', :offset || ' minutes')
+            ORDER BY claimed_at ASC
+            LIMIT :limit
+        """
+        params = {"chain_id": chain_id, "offset": -older_than_minutes, "limit": limit}
+    else:
+        query = """
+            SELECT intent_id, job_id,
+                   EXTRACT(EPOCH FROM (NOW() - claimed_at)) as age_seconds
+            FROM tx_intents
+            WHERE chain_id = :chain_id
+              AND status = 'claimed'
+              AND claimed_at < NOW() - make_interval(mins => :older_than_minutes)
+            ORDER BY claimed_at ASC
+            LIMIT :limit
+        """
+        params = {"chain_id": chain_id, "older_than_minutes": older_than_minutes, "limit": limit}
+
+    return db.execute_returning(query, params)
+
+
+@dataclass
+class InvariantMetrics:
+    """Current values of all invariant checks."""
+
+    stuck_claimed_intents: int
+    nonce_gap_oldest_age_seconds: float
+    pending_without_attempts: int
+    orphaned_claims: int
+    orphaned_nonces: int
+
+
+def collect_invariants(
+    db: Database,
+    chain_id: int,
+    health_send_fn: Any = None,
+    health_chat_id: str | None = None,
+    health_cooldown: int = 1800,
+) -> InvariantMetrics:
+    """Collect all invariant metrics for a chain.
+
+    Call periodically (e.g., every 30 seconds) to update Prometheus gauges.
+    Uses DB methods added in Phase 1 (count_pending_without_attempts) and
+    Phase 2 (count_stuck_claimed, etc.).
+    """
+    m = InvariantMetrics(
+        stuck_claimed_intents=db.count_stuck_claimed(chain_id),
+        nonce_gap_oldest_age_seconds=db.get_oldest_nonce_gap_age_seconds(chain_id),
+        pending_without_attempts=db.count_pending_without_attempts(chain_id),
+        orphaned_claims=db.count_orphaned_claims(chain_id),
+        orphaned_nonces=db.count_orphaned_nonces(chain_id),
+    )
+
+    # Export to Prometheus using metric constants
+    metrics = get_metrics()
+    metrics.gauge(INVARIANT_STUCK_CLAIMED).set(
+        m.stuck_claimed_intents, chain_id=chain_id
+    )
+    metrics.gauge(INVARIANT_NONCE_GAP_AGE).set(
+        m.nonce_gap_oldest_age_seconds, chain_id=chain_id
+    )
+    metrics.gauge(INVARIANT_PENDING_NO_ATTEMPTS).set(
+        m.pending_without_attempts, chain_id=chain_id
+    )
+    metrics.gauge(INVARIANT_ORPHANED_CLAIMS).set(
+        m.orphaned_claims, chain_id=chain_id
+    )
+    metrics.gauge(INVARIANT_ORPHANED_NONCES).set(
+        m.orphaned_nonces, chain_id=chain_id
+    )
+
+    # Log if any non-zero
+    if any([
+        m.stuck_claimed_intents,
+        m.pending_without_attempts,
+        m.orphaned_claims,
+        m.orphaned_nonces,
+    ]):
+        extra: dict[str, Any] = {}
+        if m.stuck_claimed_intents:
+            details = _get_stuck_claim_details(db, chain_id)
+            extra = {
+                "stuck_intents_sample": [d["intent_id"] for d in details],
+                "stuck_jobs_sample": list(set(d["job_id"] for d in details)),
+                "oldest_claim_age_seconds": details[0]["age_seconds"] if details else 0,
+            }
+
+            # Send health alert for stuck claimed intents
+            health_alert(
+                component="brawny.invariants",
+                chain_id=chain_id,
+                error=f"stuck_claimed_intents={m.stuck_claimed_intents}, oldest_age={extra.get('oldest_claim_age_seconds', 0):.0f}s",
+                fingerprint_key="invariant.stuck_claimed",
+                job_id=extra.get("stuck_jobs_sample", [None])[0],
+                intent_id=extra.get("stuck_intents_sample", [None])[0],
+                action="Run: brawny intents clear-stuck",
+                db_dialect=db.dialect,
+                send_fn=health_send_fn,
+                health_chat_id=health_chat_id,
+                cooldown_seconds=health_cooldown,
+            )
+
+        logger.warning(
+            "invariants.violations_detected",
+            **asdict(m),
+            chain_id=chain_id,
+            **extra,
+        )
+
+    return m

brawny/jobs/__init__.py

@@ -0,0 +1,26 @@
+"""Job framework with base class, registry, and discovery."""
+
+from brawny.jobs.base import Job, TxInfo, TxReceipt, BlockInfo
+from brawny.jobs.registry import job, registry, get_registry, JobRegistry
+from brawny.jobs.discovery import discover_jobs, discover_jobs_from_path, auto_discover_jobs
+from brawny.jobs.job_validation import validate_job, validate_all_jobs
+
+__all__ = [
+    # Base classes
+    "Job",
+    "TxInfo",
+    "TxReceipt",
+    "BlockInfo",
+    # Registry
+    "job",
+    "registry",
+    "get_registry",
+    "JobRegistry",
+    # Discovery
+    "discover_jobs",
+    "discover_jobs_from_path",
+    "auto_discover_jobs",
+    # Validation
+    "validate_job",
+    "validate_all_jobs",
+]