brawny 0.1.13__py3-none-any.whl

brawny/db/migrations/001_init.sql

@@ -0,0 +1,186 @@
+-- brawny initial schema migration
+-- Version: 001
+-- Description: Create all core tables for the brawny framework
+
+-- ============================================================================
+-- Migration tracking table
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version VARCHAR(20) PRIMARY KEY,
+    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- 1. Block State - tracks last processed block per chain
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS block_state (
+    chain_id INTEGER PRIMARY KEY,
+    last_processed_block_number BIGINT NOT NULL,
+    last_processed_block_hash VARCHAR(66) NOT NULL,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- 2. Block Hash History - for reorg detection
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS block_hash_history (
+    id SERIAL PRIMARY KEY,
+    chain_id INTEGER NOT NULL,
+    block_number BIGINT NOT NULL,
+    block_hash VARCHAR(66) NOT NULL,
+    inserted_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (chain_id, block_number)
+);
+
+CREATE INDEX IF NOT EXISTS idx_block_hash_history_chain_block
+    ON block_hash_history(chain_id, block_number DESC);
+
+-- ============================================================================
+-- 3. Jobs - job registry and configuration
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS jobs (
+    job_id VARCHAR(200) PRIMARY KEY,
+    job_name VARCHAR(200) NOT NULL,
+    enabled BOOLEAN NOT NULL DEFAULT true,
+    check_interval_blocks INTEGER NOT NULL DEFAULT 1,
+    last_checked_block_number BIGINT,
+    last_triggered_block_number BIGINT,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_jobs_enabled ON jobs(enabled) WHERE enabled = true;
+
+-- ============================================================================
+-- 4. Job KV Store - persistent key-value storage per job
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS job_kv (
+    job_id VARCHAR(200) NOT NULL REFERENCES jobs(job_id) ON DELETE CASCADE,
+    key VARCHAR(200) NOT NULL,
+    value_json TEXT NOT NULL,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (job_id, key)
+);
+
+-- ============================================================================
+-- 5. Signers - tracks nonce state per signer per chain
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS signers (
+    chain_id INTEGER NOT NULL,
+    signer_address VARCHAR(42) NOT NULL,
+    next_nonce BIGINT NOT NULL DEFAULT 0,
+    last_synced_chain_nonce BIGINT,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (chain_id, signer_address)
+);
+
+-- ============================================================================
+-- 6. Nonce Reservations - tracks nonce allocation and status
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS nonce_reservations (
+    id SERIAL PRIMARY KEY,
+    chain_id INTEGER NOT NULL,
+    signer_address VARCHAR(42) NOT NULL,
+    nonce BIGINT NOT NULL,
+    status VARCHAR(20) NOT NULL CHECK (status IN ('reserved', 'in_flight', 'released', 'orphaned')),
+    intent_id UUID,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (chain_id, signer_address, nonce)
+);
+
+CREATE INDEX IF NOT EXISTS idx_nonce_reservations_signer_status
+    ON nonce_reservations(chain_id, signer_address, status);
+
+-- ============================================================================
+-- 7. Transaction Intents - durable transaction intent records
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS tx_intents (
+    intent_id UUID PRIMARY KEY,
+    job_id VARCHAR(200) NOT NULL,
+    chain_id INTEGER NOT NULL,
+    signer_address VARCHAR(42) NOT NULL,
+    idempotency_key VARCHAR(200) NOT NULL,
+    to_address VARCHAR(42) NOT NULL,
+    data TEXT,
+    value_wei VARCHAR(78) NOT NULL DEFAULT '0',
+    gas_limit BIGINT,
+    max_fee_per_gas VARCHAR(78),
+    max_priority_fee_per_gas VARCHAR(78),
+    min_confirmations INTEGER NOT NULL DEFAULT 1,
+    deadline_ts TIMESTAMP,
+    status VARCHAR(20) NOT NULL DEFAULT 'created' CHECK (
+        status IN ('created', 'claimed', 'sending', 'pending', 'confirmed', 'failed', 'abandoned')
+    ),
+    claim_token VARCHAR(100),
+    claimed_at TIMESTAMP,
+    claimed_by VARCHAR(200),
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_tx_intents_status ON tx_intents(status);
+CREATE INDEX IF NOT EXISTS idx_tx_intents_job_status ON tx_intents(job_id, status);
+CREATE INDEX IF NOT EXISTS idx_tx_intents_signer_status ON tx_intents(chain_id, signer_address, status);
+CREATE INDEX IF NOT EXISTS idx_tx_intents_created ON tx_intents(created_at);
+
+-- Idempotency is scoped to (chain_id, signer_address)
+CREATE UNIQUE INDEX IF NOT EXISTS uq_tx_intents_idempotency_scoped
+    ON tx_intents(chain_id, signer_address, idempotency_key);
+
+-- ============================================================================
+-- 8. Transaction Attempts - individual broadcast attempts
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS tx_attempts (
+    attempt_id UUID PRIMARY KEY,
+    intent_id UUID NOT NULL REFERENCES tx_intents(intent_id),
+    nonce BIGINT NOT NULL,
+    tx_hash VARCHAR(66),
+    gas_params_json TEXT NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'signed' CHECK (
+        status IN ('signed', 'broadcast', 'pending', 'confirmed', 'failed', 'replaced')
+    ),
+    error_code VARCHAR(100),
+    error_detail TEXT,
+    replaces_attempt_id UUID REFERENCES tx_attempts(attempt_id),
+    broadcast_block BIGINT,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_tx_attempts_intent ON tx_attempts(intent_id);
+CREATE INDEX IF NOT EXISTS idx_tx_attempts_tx_hash ON tx_attempts(tx_hash) WHERE tx_hash IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_tx_attempts_status ON tx_attempts(status);
+
+-- ============================================================================
+-- 9. ABI Cache - cached contract ABIs
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS abi_cache (
+    chain_id INTEGER NOT NULL,
+    address VARCHAR(42) NOT NULL,
+    abi_json TEXT NOT NULL,
+    source VARCHAR(30) NOT NULL CHECK (source IN ('etherscan', 'sourcify', 'manual', 'proxy_implementation')),
+    resolved_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (chain_id, address)
+);
+
+CREATE INDEX IF NOT EXISTS idx_abi_cache_resolved ON abi_cache(resolved_at);
+
+-- ============================================================================
+-- 10. Proxy Cache - cached proxy-to-implementation mappings
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS proxy_cache (
+    chain_id INTEGER NOT NULL,
+    proxy_address VARCHAR(42) NOT NULL,
+    implementation_address VARCHAR(42) NOT NULL,
+    resolved_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (chain_id, proxy_address)
+);
+
+-- ============================================================================
+-- Record this migration
+-- ============================================================================
+INSERT INTO schema_migrations (version) VALUES ('001');

brawny/db/migrations/002_add_included_block.sql

@@ -0,0 +1,7 @@
+-- Add included_block to tx_attempts for receipt inclusion tracking
+-- Version: 002
+
+ALTER TABLE tx_attempts
+    ADD COLUMN included_block BIGINT;
+
+INSERT INTO schema_migrations (version) VALUES ('002');

brawny/db/migrations/003_add_broadcast_at.sql

@@ -0,0 +1,10 @@
+-- Add broadcast_at to tx_attempts for accurate confirmation timing
+
+ALTER TABLE tx_attempts
+    ADD COLUMN broadcast_at TIMESTAMP;
+
+UPDATE tx_attempts
+SET broadcast_at = updated_at
+WHERE broadcast_at IS NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('003');

brawny/db/migrations/004_broadcast_binding.sql

@@ -0,0 +1,20 @@
+-- Migration: Broadcast binding for RPC groups privacy invariant
+--
+-- This adds columns to track which RPC group and endpoints were used for
+-- the first broadcast of an intent. Retries MUST use the same endpoint list
+-- to preserve the privacy invariant (no cross-group fallback).
+
+-- Broadcast binding on intents (set on first successful broadcast)
+ALTER TABLE tx_intents ADD COLUMN broadcast_group VARCHAR(100);
+ALTER TABLE tx_intents ADD COLUMN broadcast_endpoints_json TEXT;
+
+-- Index for querying by broadcast group
+CREATE INDEX IF NOT EXISTS idx_tx_intents_broadcast_group
+    ON tx_intents(broadcast_group);
+
+-- Audit trail on attempts (which endpoint was actually used)
+ALTER TABLE tx_attempts ADD COLUMN broadcast_group VARCHAR(100);
+ALTER TABLE tx_attempts ADD COLUMN endpoint_url VARCHAR(500);
+
+-- Record migration
+INSERT INTO schema_migrations (version) VALUES ('004');

brawny/db/migrations/005_add_retry_after.sql

@@ -0,0 +1,9 @@
+-- Add retry_after to tx_intents for execution backoff
+-- Version: 005
+
+ALTER TABLE tx_intents ADD COLUMN retry_after TIMESTAMP;
+
+CREATE INDEX IF NOT EXISTS idx_tx_intents_retry_after
+    ON tx_intents(retry_after);
+
+INSERT INTO schema_migrations (version) VALUES ('005');

brawny/db/migrations/006_add_retry_count_column.sql

@@ -0,0 +1,11 @@
+-- Add retry_count to tx_intents for tracking execution attempts
+-- Version: 006
+-- Description: Move retry tracking from job_kv to native column for atomicity
+
+ALTER TABLE tx_intents ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0;
+
+-- Index for querying intents by retry count (e.g., finding frequently retried intents)
+CREATE INDEX IF NOT EXISTS idx_tx_intents_retry_count
+    ON tx_intents(retry_count) WHERE retry_count > 0;
+
+INSERT INTO schema_migrations (version) VALUES ('006');

brawny/db/migrations/007_add_gap_tracking.sql

@@ -0,0 +1,18 @@
+-- Migration 007: Add gap tracking columns to signers table
+--
+-- Adds:
+--   - gap_started_at: Timestamp when nonce gap blocking started (for alerts)
+--   - alias: Optional human-readable alias for signers
+--
+-- Part of nonce policy simplification - see NONCE.md
+
+-- Add gap tracking column (nullable timestamp)
+ALTER TABLE signers ADD COLUMN gap_started_at TIMESTAMP;
+
+-- Add optional alias column
+ALTER TABLE signers ADD COLUMN alias VARCHAR(50);
+
+-- Index for alias lookup (partial index, only non-null aliases)
+CREATE INDEX IF NOT EXISTS idx_signers_alias ON signers (chain_id, alias) WHERE alias IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('007');

brawny/db/migrations/008_add_transactions.sql

@@ -0,0 +1,72 @@
+-- brawny transactions table migration
+-- Version: 008
+-- Description: Add single Transaction model replacing TxIntent + TxAttempt
+--
+-- This is Phase 1 of the ATTEMPT_MODEL.md simplification:
+-- - Single transactions table (no joins)
+-- - 4-state TxStatus (created, broadcast, confirmed, failed)
+-- - JSON blobs for rarely-queried fields
+-- - Append-only tx_hash_history for debugging
+
+-- ============================================================================
+-- Transactions - single model for job transaction lifecycle
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS transactions (
+    -- Identity (queryable, indexed)
+    tx_id UUID PRIMARY KEY,
+    job_id VARCHAR(200) NOT NULL,
+    chain_id INTEGER NOT NULL,
+    idempotency_key VARCHAR(200) NOT NULL,
+
+    -- Payload (immutable after creation)
+    signer_address VARCHAR(42) NOT NULL,
+    to_address VARCHAR(42) NOT NULL,
+    data TEXT,
+    value_wei VARCHAR(78) NOT NULL DEFAULT '0',
+    min_confirmations INTEGER NOT NULL DEFAULT 1,
+    deadline_ts TIMESTAMP,
+
+    -- Status (queryable)
+    status VARCHAR(20) NOT NULL DEFAULT 'created'
+        CHECK (status IN ('created', 'broadcast', 'confirmed', 'failed')),
+    failure_type VARCHAR(50),
+
+    -- Broadcast state (queryable)
+    current_tx_hash VARCHAR(66),
+    current_nonce BIGINT,
+    replacement_count INTEGER NOT NULL DEFAULT 0,
+
+    -- Worker coordination (queryable)
+    claim_token VARCHAR(100),
+    claimed_at TIMESTAMP,
+
+    -- Confirmation (queryable)
+    included_block BIGINT,
+    confirmed_at TIMESTAMP,
+
+    -- Audit (queryable)
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    -- JSON BLOBS (rarely queried - no indexes)
+    gas_params_json TEXT,           -- {"gas_limit": N, "max_fee": N, "priority_fee": N}
+    broadcast_info_json TEXT,       -- {"group": str, "endpoints": [...]}
+    error_info_json TEXT,           -- ErrorInfo as JSON
+    tx_hash_history TEXT            -- Append-only JSON array of TxHashRecord
+);
+
+-- Indexes (only on queryable columns)
+CREATE INDEX IF NOT EXISTS idx_transactions_status ON transactions(status);
+CREATE INDEX IF NOT EXISTS idx_transactions_job_status ON transactions(job_id, status);
+CREATE INDEX IF NOT EXISTS idx_transactions_signer ON transactions(chain_id, signer_address);
+CREATE INDEX IF NOT EXISTS idx_transactions_tx_hash ON transactions(current_tx_hash) WHERE current_tx_hash IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_transactions_created ON transactions(created_at);
+
+-- Idempotency is scoped to (chain_id, signer_address)
+CREATE UNIQUE INDEX IF NOT EXISTS uq_transactions_idempotency_scoped
+    ON transactions(chain_id, signer_address, idempotency_key);
+
+-- ============================================================================
+-- Record this migration
+-- ============================================================================
+INSERT INTO schema_migrations (version) VALUES ('008');

brawny/db/migrations/009_add_intent_metadata.sql

@@ -0,0 +1,5 @@
+-- Add metadata_json column to tx_intents table
+-- Stores per-intent context for alerts (JSON-serializable dict)
+-- trigger.reason is auto-merged into this field
+
+ALTER TABLE tx_intents ADD COLUMN metadata_json TEXT;

brawny/db/migrations/010_add_nonce_gap_index.sql

@@ -0,0 +1,9 @@
+-- Add composite index for efficient nonce gap age queries
+-- Makes the MIN(created_at) scan an index walk instead of heap scan
+-- Version: 010
+-- Note: CONCURRENTLY removed for SQLite compatibility (PostgreSQL-only syntax)
+
+CREATE INDEX IF NOT EXISTS idx_nonce_res_chain_signer_status_nonce_created
+ON nonce_reservations (chain_id, signer_address, status, nonce, created_at);
+
+INSERT INTO schema_migrations (version) VALUES ('010');

brawny/db/migrations/011_add_job_logs.sql

@@ -0,0 +1,24 @@
+-- Job logs for operator-visible snapshots during check()
+-- Version: 011
+-- Note: SERIAL becomes INTEGER on SQLite (handled by sqlite.py adapter)
+
+CREATE TABLE IF NOT EXISTS job_logs (
+    id SERIAL PRIMARY KEY,
+    chain_id INTEGER NOT NULL,
+    job_id VARCHAR(200) NOT NULL,
+    block_number BIGINT,
+    ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    level VARCHAR(20) NOT NULL DEFAULT 'info',
+    fields_json TEXT NOT NULL
+);
+
+-- Primary query: recent logs for a job
+CREATE INDEX IF NOT EXISTS idx_job_logs_job_ts
+    ON job_logs(chain_id, job_id, ts DESC);
+
+-- Cleanup query: purge old logs (per-chain)
+CREATE INDEX IF NOT EXISTS idx_job_logs_chain_ts
+    ON job_logs(chain_id, ts);
+
+-- Record migration
+INSERT INTO schema_migrations (version) VALUES ('011');

brawny/db/migrations/012_add_claimed_by.sql

@@ -0,0 +1,5 @@
+-- Postgres only (SQLite handled in migrator)
+ALTER TABLE tx_intents ADD COLUMN IF NOT EXISTS claimed_by VARCHAR(200);
+
+INSERT INTO schema_migrations (version) VALUES ('012')
+ON CONFLICT (version) DO NOTHING;

brawny/db/ops/__init__.py

@@ -0,0 +1,29 @@
+"""Database operations modules.
+
+Flat function-based operations for each domain:
+- blocks: Block state and hash history
+- jobs: Job configuration and KV store
+- intents: Transaction intents
+- attempts: Transaction attempts
+- nonces: Signer state and nonce reservations
+- cache: ABI and proxy cache
+
+Usage:
+    from brawny.db import ops
+
+    # Use functions from specific modules
+    state = ops.blocks.get_block_state(db, chain_id)
+    job = ops.jobs.get_job(db, job_id)
+    intent = ops.intents.create_intent(db, ...)
+"""
+
+from __future__ import annotations
+
+from brawny.db.ops import blocks
+from brawny.db.ops import jobs
+from brawny.db.ops import intents
+from brawny.db.ops import attempts
+from brawny.db.ops import nonces
+from brawny.db.ops import cache
+
+__all__ = ["blocks", "jobs", "intents", "attempts", "nonces", "cache"]

brawny/db/ops/attempts.py

@@ -0,0 +1,108 @@
+"""Transaction attempt operations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from brawny.db.base_new import Database
+from brawny.db import queries as Q
+from brawny.db import mappers as M
+from brawny.model.types import TxAttempt, GasParams
+
+
+def create_attempt(
+    db: Database,
+    attempt_id: UUID,
+    intent_id: UUID,
+    nonce: int,
+    tx_hash: str | None,
+    gas_params: GasParams,
+    status: str,
+    broadcast_block: int | None = None,
+    broadcast_at: datetime | None = None,
+    broadcast_group: str | None = None,
+    endpoint_url: str | None = None,
+) -> TxAttempt | None:
+    """Create a new transaction attempt."""
+    row = db.fetch_one(Q.CREATE_ATTEMPT, {
+        "attempt_id": str(attempt_id),
+        "intent_id": str(intent_id),
+        "nonce": nonce,
+        "tx_hash": tx_hash,
+        "gas_params_json": gas_params.to_json(),
+        "status": status,
+        "broadcast_block": broadcast_block,
+        "broadcast_at": broadcast_at,
+        "broadcast_group": broadcast_group,
+        "endpoint_url": endpoint_url,
+    })
+    return M.row_to_attempt(row) if row else None
+
+
+def get_attempt(db: Database, attempt_id: UUID) -> TxAttempt | None:
+    """Get attempt by ID."""
+    row = db.fetch_one(Q.GET_ATTEMPT, {"attempt_id": str(attempt_id)})
+    return M.row_to_attempt(row) if row else None
+
+
+def get_attempt_by_tx_hash(db: Database, tx_hash: str) -> TxAttempt | None:
+    """Get attempt by transaction hash."""
+    row = db.fetch_one(Q.GET_ATTEMPT_BY_TX_HASH, {"tx_hash": tx_hash})
+    return M.row_to_attempt(row) if row else None
+
+
+def get_attempts_for_intent(db: Database, intent_id: UUID) -> list[TxAttempt]:
+    """Get all attempts for an intent, ordered by created_at DESC."""
+    rows = db.fetch_all(Q.GET_ATTEMPTS_FOR_INTENT, {"intent_id": str(intent_id)})
+    return [M.row_to_attempt(row) for row in rows]
+
+
+def get_latest_attempt_for_intent(db: Database, intent_id: UUID) -> TxAttempt | None:
+    """Get the most recent attempt for an intent."""
+    row = db.fetch_one(Q.GET_LATEST_ATTEMPT_FOR_INTENT, {"intent_id": str(intent_id)})
+    return M.row_to_attempt(row) if row else None
+
+
+def update_attempt_status(db: Database, attempt_id: UUID, status: str) -> bool:
+    """Update attempt status."""
+    count = db.execute_rowcount(Q.UPDATE_ATTEMPT_STATUS, {
+        "attempt_id": str(attempt_id),
+        "status": status,
+    })
+    return count > 0
+
+
+def update_attempt_included(
+    db: Database, attempt_id: UUID, status: str, included_block: int
+) -> bool:
+    """Update attempt with inclusion info."""
+    count = db.execute_rowcount(Q.UPDATE_ATTEMPT_INCLUDED, {
+        "attempt_id": str(attempt_id),
+        "status": status,
+        "included_block": included_block,
+    })
+    return count > 0
+
+
+def update_attempt_error(
+    db: Database,
+    attempt_id: UUID,
+    status: str,
+    error_code: str | None,
+    error_detail: str | None,
+) -> bool:
+    """Update attempt with error info."""
+    count = db.execute_rowcount(Q.UPDATE_ATTEMPT_ERROR, {
+        "attempt_id": str(attempt_id),
+        "status": status,
+        "error_code": error_code,
+        "error_detail": error_detail,
+    })
+    return count > 0
+
+
+def get_pending_attempts(db: Database, chain_id: int) -> list[TxAttempt]:
+    """Get pending attempts for a chain."""
+    rows = db.fetch_all(Q.GET_PENDING_ATTEMPTS, {"chain_id": chain_id})
+    return [M.row_to_attempt(row) for row in rows]

brawny/db/ops/blocks.py

@@ -0,0 +1,83 @@
+"""Block state and hash history operations."""
+
+from __future__ import annotations
+
+from brawny.db.base_new import Database, BlockState
+from brawny.db import queries as Q
+from brawny.db import mappers as M
+
+
+def get_block_state(db: Database, chain_id: int) -> BlockState | None:
+    """Get the current block processing state."""
+    row = db.fetch_one(Q.GET_BLOCK_STATE, {"chain_id": chain_id})
+    return M.row_to_block_state(row) if row else None
+
+
+def upsert_block_state(
+    db: Database, chain_id: int, block_number: int, block_hash: str
+) -> None:
+    """Update or insert block processing state."""
+    db.execute(Q.UPSERT_BLOCK_STATE, {
+        "chain_id": chain_id,
+        "block_number": block_number,
+        "block_hash": block_hash,
+    })
+
+
+def get_block_hash_at_height(
+    db: Database, chain_id: int, block_number: int
+) -> str | None:
+    """Get stored block hash at a specific height."""
+    row = db.fetch_one(Q.GET_BLOCK_HASH_AT_HEIGHT, {
+        "chain_id": chain_id,
+        "block_number": block_number,
+    })
+    return row["block_hash"] if row else None
+
+
+def insert_block_hash(
+    db: Database, chain_id: int, block_number: int, block_hash: str
+) -> None:
+    """Insert a block hash into history."""
+    db.execute(Q.INSERT_BLOCK_HASH, {
+        "chain_id": chain_id,
+        "block_number": block_number,
+        "block_hash": block_hash,
+    })
+
+
+def delete_block_hashes_above(db: Database, chain_id: int, block_number: int) -> int:
+    """Delete block hashes above a certain height (for reorg rewind)."""
+    return db.execute_rowcount(Q.DELETE_BLOCK_HASHES_ABOVE, {
+        "chain_id": chain_id,
+        "block_number": block_number,
+    })
+
+
+def delete_block_hash_at_height(db: Database, chain_id: int, block_number: int) -> bool:
+    """Delete a specific block hash (for stale hash cleanup)."""
+    count = db.execute_rowcount(Q.DELETE_BLOCK_HASH_AT_HEIGHT, {
+        "chain_id": chain_id,
+        "block_number": block_number,
+    })
+    return count > 0
+
+
+def cleanup_old_block_hashes(db: Database, chain_id: int, keep_count: int) -> int:
+    """Delete old block hashes beyond the history window."""
+    # Get max block number
+    row = db.fetch_one(Q.GET_MAX_BLOCK_IN_HISTORY, {"chain_id": chain_id})
+    if not row or row["max_block"] is None:
+        return 0
+
+    cutoff = row["max_block"] - keep_count
+    return db.execute_rowcount(Q.DELETE_BLOCK_HASHES_BELOW, {
+        "chain_id": chain_id,
+        "cutoff": cutoff,
+    })
+
+
+def get_oldest_block_in_history(db: Database, chain_id: int) -> int | None:
+    """Get the oldest block number in hash history."""
+    row = db.fetch_one(Q.GET_OLDEST_BLOCK_IN_HISTORY, {"chain_id": chain_id})
+    return row["min_block"] if row else None