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

brawny/db/__init__.py

@@ -1,4 +1,4 @@
-"""Database layer with support for PostgreSQL (production) and SQLite (development)."""
+"""Database layer with SQLite-only support."""
 
 from brawny.db.base import (
     ABICacheEntry,
@@ -9,11 +9,8 @@ from brawny.db.base import (
     ProxyCacheEntry,
 )
 from brawny.db.migrate import Migrator, discover_migrations, get_pending_migrations
-try:
-    from brawny.db.postgres import PostgresDatabase
-except ModuleNotFoundError:
-    PostgresDatabase = None  # type: ignore
 from brawny.db.sqlite import SQLiteDatabase
+from brawny.db.serialized import SerializedDatabase
 
 __all__ = [
     # Base classes
@@ -26,7 +23,7 @@ __all__ = [
     "ProxyCacheEntry",
     # Implementations
     "SQLiteDatabase",
-    "PostgresDatabase",
+    "SerializedDatabase",
     # Migration
     "Migrator",
     "discover_migrations",
@@ -40,13 +37,11 @@ def create_database(database_url: str, **kwargs: object) -> Database:
     """Factory function to create a database instance based on URL.
 
     Args:
-        database_url: Database connection URL
-            - sqlite:///path/to/db.sqlite
-            - postgresql://user:pass@host:port/dbname
+        database_url: Database connection URL (sqlite:///path/to/db.sqlite)
         **kwargs: Additional arguments passed to the database constructor
 
     Returns:
-        Database instance (SQLiteDatabase or PostgresDatabase)
+        Database instance (SQLiteDatabase)
 
     Raises:
         ValueError: If database URL scheme is not supported
@@ -54,25 +49,18 @@ def create_database(database_url: str, **kwargs: object) -> Database:
     circuit_breaker_failures = int(kwargs.pop("circuit_breaker_failures", 5))
     circuit_breaker_seconds = int(kwargs.pop("circuit_breaker_seconds", 30))
     if database_url.startswith("sqlite:///"):
-        return SQLiteDatabase(
-            database_url,
-            circuit_breaker_failures=circuit_breaker_failures,
-            circuit_breaker_seconds=circuit_breaker_seconds,
-        )
-    elif database_url.startswith(("postgresql://", "postgres://")):
-        if PostgresDatabase is None:
-            raise ValueError(
-                "Postgres support requires psycopg and psycopg-pool. "
-                "Install with: pip install psycopg[binary] psycopg-pool"
+        kwargs.pop("db_op_timeout_seconds", None)
+        kwargs.pop("db_busy_retries", None)
+        kwargs.pop("db_busy_backoff_seconds", None)
+        return SerializedDatabase(
+            SQLiteDatabase(
+                database_url,
+                circuit_breaker_failures=circuit_breaker_failures,
+                circuit_breaker_seconds=circuit_breaker_seconds,
             )
-        return PostgresDatabase(  # type: ignore
-            database_url,
-            circuit_breaker_failures=circuit_breaker_failures,
-            circuit_breaker_seconds=circuit_breaker_seconds,
-            **kwargs,
         )
     else:
         raise ValueError(
             f"Unsupported database URL: {database_url}. "
-            "Must start with 'sqlite:///', 'postgresql://', or 'postgres://'"
+            "Must start with 'sqlite:///'"
         )

brawny/db/base.py

@@ -1,7 +1,4 @@
-"""Database abstraction layer for brawny.
-
-Provides a unified interface for both PostgreSQL and SQLite backends.
-"""
+"""Database abstraction layer for brawny (SQLite-only)."""
 
 from __future__ import annotations
 
@@ -19,11 +16,12 @@ if TYPE_CHECKING:
         GasParams,
         JobConfig,
         NonceReservation,
+        RuntimeControl,
         SignerState,
-        Transaction,
         TxAttempt,
         TxIntent,
     )
+    from brawny.types import ClaimedIntent
 
 
 IsolationLevel = Literal["SERIALIZABLE", "REPEATABLE READ", "READ COMMITTED", "READ UNCOMMITTED"]
@@ -260,6 +258,28 @@ class Database(ABC):
         """Enable or disable a job. Returns True if job exists."""
         ...
 
+    @abstractmethod
+    def set_job_drain(
+        self,
+        job_id: str,
+        drain_until: datetime,
+        reason: str | None = None,
+        actor: str | None = None,
+        source: str | None = None,
+    ) -> bool:
+        """Drain a job until a timestamp. Returns True if job exists."""
+        ...
+
+    @abstractmethod
+    def clear_job_drain(
+        self,
+        job_id: str,
+        actor: str | None = None,
+        source: str | None = None,
+    ) -> bool:
+        """Clear job drain. Returns True if job exists."""
+        ...
+
     @abstractmethod
     def delete_job(self, job_id: str) -> bool:
         """Delete a job from the database. Returns True if job existed."""
@@ -331,6 +351,59 @@ class Database(ABC):
         """Clear gap tracking (gap resolved or force reset)."""
         ...
 
+    @abstractmethod
+    def set_signer_quarantined(
+        self,
+        chain_id: int,
+        address: str,
+        reason: str,
+        actor: str | None = None,
+        source: str | None = None,
+    ) -> bool:
+        """Quarantine signer (block nonce reservations/broadcast)."""
+        ...
+
+    @abstractmethod
+    def clear_signer_quarantined(
+        self,
+        chain_id: int,
+        address: str,
+        actor: str | None = None,
+        source: str | None = None,
+    ) -> bool:
+        """Clear signer quarantine."""
+        ...
+
+    @abstractmethod
+    def set_replacements_paused(
+        self,
+        chain_id: int,
+        address: str,
+        paused: bool,
+        reason: str | None = None,
+        actor: str | None = None,
+        source: str | None = None,
+    ) -> bool:
+        """Pause or resume replacements for a signer."""
+        ...
+
+    @abstractmethod
+    def record_nonce_reset_audit(
+        self,
+        chain_id: int,
+        signer_address: str,
+        old_next_nonce: int | None,
+        new_next_nonce: int,
+        released_reservations: int,
+        source: str,
+        reason: str | None,
+    ) -> None:
+        """Record a nonce force reset in the audit table.
+
+        Provides durable record for incident investigation.
+        """
+        ...
+
     @abstractmethod
     def get_signer_by_alias(self, chain_id: int, alias: str) -> SignerState | None:
         """Get signer by alias. Returns None if not found."""
@@ -394,11 +467,54 @@ class Database(ABC):
 
     @abstractmethod
     def release_nonce_reservation(
-        self, chain_id: int, address: str, nonce: int
+        self,
+        chain_id: int,
+        address: str,
+        nonce: int,
+        actor: str | None = None,
+        reason: str | None = None,
+        source: str | None = None,
     ) -> bool:
         """Release (mark as released) a nonce reservation."""
         ...
 
+    @abstractmethod
+    def record_mutation_audit(
+        self,
+        entity_type: str,
+        entity_id: str,
+        action: str,
+        actor: str | None = None,
+        reason: str | None = None,
+        source: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Record durable mutation audit entry."""
+        ...
+
+    @abstractmethod
+    def set_runtime_control(
+        self,
+        control: str,
+        active: bool,
+        expires_at: datetime | None,
+        reason: str | None,
+        actor: str | None,
+        mode: str,
+    ) -> "RuntimeControl":
+        """Create or update runtime control with TTL."""
+        ...
+
+    @abstractmethod
+    def get_runtime_control(self, control: str) -> "RuntimeControl | None":
+        """Fetch runtime control by name."""
+        ...
+
+    @abstractmethod
+    def list_runtime_controls(self) -> list["RuntimeControl"]:
+        """List all runtime controls."""
+        ...
+
     @abstractmethod
     def cleanup_orphaned_nonces(
         self, chain_id: int, older_than_hours: int = 24
@@ -434,6 +550,7 @@ class Database(ABC):
         max_priority_fee_per_gas: str | None,
         min_confirmations: int,
         deadline_ts: datetime | None,
+        signer_alias: str | None = None,
         broadcast_group: str | None = None,
         broadcast_endpoints: list[str] | None = None,
     ) -> TxIntent | None:
@@ -491,6 +608,46 @@ class Database(ABC):
         """Count intents with retry_after in the future."""
         ...
 
+    @abstractmethod
+    def bind_broadcast_endpoints(
+        self,
+        intent_id: UUID,
+        group_name: str | None,
+        endpoints: list[str],
+    ) -> tuple[str | None, list[str]]:
+        """Bind broadcast endpoints to an intent (idempotent)."""
+        ...
+
+    @abstractmethod
+    def create_attempt_once(
+        self,
+        attempt_id: UUID,
+        intent_id: UUID,
+        nonce: int,
+        gas_params_json: str,
+        status: str = "pending_send",
+        tx_hash: str | None = None,
+        replaces_attempt_id: UUID | None = None,
+        broadcast_group: str | None = None,
+        endpoint_url: str | None = None,
+        binding: tuple[str | None, list[str]] | None = None,
+        actor: str | None = None,
+        reason: str | None = None,
+        source: str | None = None,
+    ) -> TxAttempt:
+        """Create attempt once per intent+nonce; return existing if present."""
+        ...
+
+    @abstractmethod
+    def require_bound_and_attempt(
+        self,
+        intent_id: UUID,
+        nonce: int,
+        endpoints: list[str],
+    ) -> None:
+        """Assert broadcast binding and attempt existence before side effects."""
+        ...
+
     @abstractmethod
     def get_oldest_pending_intent_age(self, chain_id: int) -> float | None:
         """Get age in seconds of the oldest pending intent.
@@ -522,12 +679,23 @@ class Database(ABC):
         """List sending intents older than a threshold."""
         ...
 
+    @abstractmethod
+    def list_claimed_intents_older_than(
+        self,
+        max_age_seconds: int,
+        limit: int = 100,
+        chain_id: int | None = None,
+    ) -> list[TxIntent]:
+        """List claimed intents older than a threshold (with attempts)."""
+        ...
+
     @abstractmethod
     def claim_next_intent(
         self,
         claim_token: str,
         claimed_by: str | None = None,
-    ) -> TxIntent | None:
+        lease_seconds: int | None = None,
+    ) -> ClaimedIntent | None:
         """Claim the next available intent for processing."""
         ...
 
@@ -588,6 +756,18 @@ class Database(ABC):
         """Release claim only if claim_token matches. Returns True if released."""
         ...
 
+    @abstractmethod
+    def release_claim_if_token_and_no_attempts(
+        self, intent_id: UUID, claim_token: str
+    ) -> bool:
+        """Atomically release claim only if token matches AND no attempts exist.
+
+        Safe primitive for pre-attempt failure handling:
+        - Returns True iff release succeeded (ownership + no work started)
+        - Returns False if token mismatch, attempts exist, or not claimed
+        """
+        ...
+
     @abstractmethod
     def clear_intent_claim(self, intent_id: UUID) -> bool:
         """Clear claim token and claimed_at without changing status."""
@@ -604,8 +784,58 @@ class Database(ABC):
         ...
 
     @abstractmethod
-    def release_stale_intent_claims(self, max_age_seconds: int) -> int:
-        """Release stale intent claims with no attempts. Returns count released."""
+    def requeue_expired_claims_no_attempts(
+        self,
+        limit: int,
+        grace_seconds: int,
+        chain_id: int | None = None,
+    ) -> int:
+        """Requeue expired claimed intents with no attempts. Returns count requeued."""
+        ...
+
+    @abstractmethod
+    def count_expired_claims_with_attempts(
+        self,
+        limit: int,
+        grace_seconds: int,
+        chain_id: int | None = None,
+    ) -> int:
+        """Count expired claimed intents that have attempts."""
+        ...
+
+    @abstractmethod
+    def requeue_missing_lease_claims_no_attempts(
+        self,
+        limit: int,
+        cutoff_seconds: int,
+        chain_id: int | None = None,
+    ) -> int:
+        """Requeue claimed intents with NULL lease_expires_at and no attempts."""
+        ...
+
+    @abstractmethod
+    def count_missing_lease_claims_with_attempts(
+        self,
+        limit: int,
+        cutoff_seconds: int,
+        chain_id: int | None = None,
+    ) -> int:
+        """Count claimed intents with NULL lease_expires_at that have attempts."""
+        ...
+
+    @abstractmethod
+    def should_create_intent(
+        self,
+        cooldown_key: str,
+        now: int,
+        cooldown_seconds: int,
+    ) -> tuple[bool, int | None]:
+        """Check cooldown key and update if allowed. Returns (allowed, last_intent_at)."""
+        ...
+
+    @abstractmethod
+    def prune_job_cooldowns(self, older_than_days: int) -> int:
+        """Delete stale cooldown keys older than N days. Returns count deleted."""
         ...
 
     @abstractmethod
@@ -631,12 +861,15 @@ class Database(ABC):
         intent_id: UUID,
         nonce: int,
         gas_params_json: str,
-        status: str = "signed",
+        status: str = "pending_send",
         tx_hash: str | None = None,
         replaces_attempt_id: UUID | None = None,
         broadcast_group: str | None = None,
         endpoint_url: str | None = None,
         binding: tuple[str, list[str]] | None = None,
+        actor: str | None = None,
+        reason: str | None = None,
+        source: str | None = None,
     ) -> TxAttempt:
         """Create a new transaction attempt.
 
@@ -645,7 +878,7 @@ class Database(ABC):
             intent_id: Parent intent ID
             nonce: Transaction nonce
             gas_params_json: Gas parameters as JSON
-            status: Initial status (default: "signed")
+            status: Initial status (default: "pending_send")
             tx_hash: Transaction hash if known
             replaces_attempt_id: ID of attempt being replaced
             broadcast_group: RPC group used for broadcast
@@ -684,152 +917,16 @@ class Database(ABC):
         broadcast_block: int | None = None,
         broadcast_at: datetime | None = None,
         included_block: int | None = None,
+        endpoint_url: str | None = None,
         error_code: str | None = None,
         error_detail: str | None = None,
+        actor: str | None = None,
+        reason: str | None = None,
+        source: str | None = None,
     ) -> bool:
         """Update attempt status and related fields."""
         ...
 
-    # =========================================================================
-    # Transaction Operations (NEW - replaces Intent/Attempt in Phase 2+)
-    #
-    # IMPORTANT: Transaction is the only durable execution model.
-    # Do not add attempt-related methods here.
-    # =========================================================================
-
-    @abstractmethod
-    def create_tx(
-        self,
-        tx_id: UUID,
-        job_id: str,
-        chain_id: int,
-        idempotency_key: str,
-        signer_address: str,
-        to_address: str,
-        data: str | None,
-        value_wei: str,
-        min_confirmations: int,
-        deadline_ts: datetime | None,
-        gas_params: GasParams | None = None,
-    ) -> Transaction | None:
-        """Create a new transaction.
-
-        Returns None if idempotency_key already exists (idempotency).
-        Initial status is always 'created'.
-        """
-        ...
-
-    @abstractmethod
-    def get_tx(self, tx_id: UUID) -> Transaction | None:
-        """Get a transaction by ID."""
-        ...
-
-    @abstractmethod
-    def get_tx_by_idempotency_key(
-        self,
-        chain_id: int,
-        signer_address: str,
-        idempotency_key: str,
-    ) -> Transaction | None:
-        """Get a transaction by idempotency key (scoped to chain and signer)."""
-        ...
-
-    @abstractmethod
-    def get_tx_by_hash(self, tx_hash: str) -> Transaction | None:
-        """Get a transaction by current tx hash.
-
-        NOTE: Does NOT search tx_hash_history. Only matches current_tx_hash.
-        """
-        ...
-
-    @abstractmethod
-    def list_pending_txs(
-        self,
-        chain_id: int | None = None,
-        job_id: str | None = None,
-    ) -> list[Transaction]:
-        """List transactions in CREATED or BROADCAST status."""
-        ...
-
-    @abstractmethod
-    def claim_tx(self, claim_token: str) -> Transaction | None:
-        """Claim the next CREATED transaction for processing.
-
-        This is a lease, not ownership. The claim gates execution only.
-        Status remains CREATED while claimed - no "claimed" status.
-        """
-        ...
-
-    @abstractmethod
-    def set_tx_broadcast(
-        self,
-        tx_id: UUID,
-        tx_hash: str,
-        nonce: int,
-        gas_params: GasParams,
-        broadcast_block: int,
-        broadcast_info: BroadcastInfo | None = None,
-    ) -> bool:
-        """Record initial broadcast.
-
-        Sets status=BROADCAST, creates first tx_hash_history record.
-        Returns True if successful, False if tx not found or wrong status.
-        """
-        ...
-
-    @abstractmethod
-    def set_tx_replaced(
-        self,
-        tx_id: UUID,
-        new_tx_hash: str,
-        gas_params: GasParams,
-        broadcast_block: int,
-        reason: str = "fee_bump",
-    ) -> bool:
-        """Record replacement broadcast.
-
-        Appends to tx_hash_history, updates current_tx_hash, increments
-        replacement_count. Status remains BROADCAST.
-
-        Returns True if successful, False if tx not found or wrong status.
-        """
-        ...
-
-    @abstractmethod
-    def set_tx_confirmed(
-        self,
-        tx_id: UUID,
-        included_block: int,
-    ) -> bool:
-        """Mark transaction confirmed.
-
-        Sets status=CONFIRMED, included_block, confirmed_at.
-        Returns True if successful, False if tx not found or wrong status.
-        """
-        ...
-
-    @abstractmethod
-    def set_tx_failed(
-        self,
-        tx_id: UUID,
-        failure_type: FailureType,
-        error_info: ErrorInfo | None = None,
-    ) -> bool:
-        """Mark transaction failed.
-
-        Sets status=FAILED, failure_type, error_info_json.
-        Returns True if successful, False if tx not found or already terminal.
-        """
-        ...
-
-    @abstractmethod
-    def release_stale_tx_claims(self, max_age_seconds: int) -> int:
-        """Release claims older than threshold.
-
-        Returns count of claims released.
-        """
-        ...
-
     # =========================================================================
     # ABI Cache Operations
     # =========================================================================

brawny/db/global_cache.py

@@ -16,6 +16,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from brawny.utils import db_address
+
 if TYPE_CHECKING:
     pass
 
@@ -84,7 +86,8 @@ class GlobalABICache:
 
     def _init_schema(self) -> None:
         """Create tables if they don't exist."""
-        assert self._conn is not None
+        if self._conn is None:
+            raise RuntimeError("Global cache connection not initialized")
 
         self._conn.executescript("""
             CREATE TABLE IF NOT EXISTS abi_cache (
@@ -119,6 +122,7 @@ class GlobalABICache:
         Returns:
             ABICacheEntry if found, None otherwise
         """
+        address = db_address(address)
         with self._lock:
             conn = self._ensure_connected()
             cursor = conn.execute(
@@ -156,6 +160,7 @@ class GlobalABICache:
             abi_json: JSON-encoded ABI
             source: Source of ABI ('etherscan', 'sourcify', 'manual', 'proxy_implementation')
         """
+        address = db_address(address)
         with self._lock:
             conn = self._ensure_connected()
             conn.execute(
@@ -181,6 +186,7 @@ class GlobalABICache:
         Returns:
             True if entry was deleted, False if not found
         """
+        address = db_address(address)
         with self._lock:
             conn = self._ensure_connected()
             cursor = conn.execute(
@@ -223,6 +229,7 @@ class GlobalABICache:
         Returns:
             ProxyCacheEntry if found, None otherwise
         """
+        proxy_address = db_address(proxy_address)
         with self._lock:
             conn = self._ensure_connected()
             cursor = conn.execute(
@@ -257,6 +264,8 @@ class GlobalABICache:
             proxy_address: Proxy contract address
             implementation_address: Implementation contract address
         """
+        proxy_address = db_address(proxy_address)
+        implementation_address = db_address(implementation_address)
         with self._lock:
             conn = self._ensure_connected()
             conn.execute(
@@ -281,6 +290,7 @@ class GlobalABICache:
         Returns:
             True if entry was deleted, False if not found
         """
+        proxy_address = db_address(proxy_address)
         with self._lock:
             conn = self._ensure_connected()
             cursor = conn.execute(