fastweb3-objects 0.1.0__py3-none-any.whl

fw3_objects/cache/rpc.py

@@ -0,0 +1,205 @@
+"""Internal RPC response cache middleware used by Chain Web3 instances."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from typing import Any
+
+from .db import CacheDB, get_cache_db
+
+RPC_CACHE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS rpc_cache (
+    chain_id INTEGER NOT NULL,
+    method TEXT NOT NULL,
+    params_json TEXT NOT NULL,
+    result_json TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    PRIMARY KEY (chain_id, method, params_json)
+);
+"""
+
+_READ = object()
+CacheRule = Callable[[Any, Any], Any | None]
+
+ERC20_METADATA_SELECTORS = {
+    "0x06fdde03",  # name()
+    "0x95d89b41",  # symbol()
+    "0x313ce567",  # decimals()
+}
+
+
+def _json_dumps(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def _eth_get_code_cache_params(call, result: Any = _READ) -> Any | None:
+    params = getattr(call, "params", None)
+    if not isinstance(params, (list, tuple)) or len(params) < 2:
+        return None
+
+    address, block = params[:2]
+    if block != "latest":
+        return None
+
+    if result is not _READ and result == "0x":
+        return None
+
+    return [address.lower(), "latest"]
+
+
+def _eth_call_cache_params(call, result: Any = _READ) -> Any | None:
+    params = getattr(call, "params", None)
+    if not isinstance(params, (list, tuple)) or len(params) < 2:
+        return None
+
+    tx, block = params[:2]
+    if block != "latest":
+        return None
+
+    if not isinstance(tx, dict):
+        return None
+
+    to = tx.get("to")
+    data = tx.get("data") or tx.get("input")
+
+    if not isinstance(to, str) or not isinstance(data, str):
+        return None
+
+    data = data.lower()
+    if data not in ERC20_METADATA_SELECTORS:
+        return None
+
+    if isinstance(result, Exception):
+        return None
+
+    return [to.lower(), data, "latest"]
+
+
+CACHE_RULES: dict[str, CacheRule] = {
+    "eth_getCode": _eth_get_code_cache_params,
+    "eth_call": _eth_call_cache_params,
+}
+
+
+def cache_params(call, result: Any = _READ) -> Any | None:
+    """Return normalized cache params for a call, if it is cacheable."""
+    rule = CACHE_RULES.get(call.method)
+    if rule is None:
+        return None
+    return rule(call, result)
+
+
+class RpcCache:
+    """Read and write raw RPC cache entries."""
+
+    def __init__(self, db: CacheDB | None = None) -> None:
+        """Initialize the RPC cache.
+
+        Args:
+            db: Cache database. If omitted, the process-global cache is used.
+        """
+        if db is None:
+            db = get_cache_db()
+        self.db = db
+
+    def get(self, chain_id: int, method: str, params: Any) -> Any | None:
+        """Return a cached RPC result, if present."""
+        params_json = _json_dumps(params)
+        row = self.db.execute(
+            """
+            SELECT result_json FROM rpc_cache
+            WHERE chain_id = ? AND method = ? AND params_json = ?
+            """,
+            (int(chain_id), method, params_json),
+        ).fetchone()
+
+        if row is None:
+            return None
+        return json.loads(row["result_json"])
+
+    def set(self, chain_id: int, method: str, params: Any, result: Any) -> None:
+        """Store an RPC result."""
+        now = int(time.time())
+        params_json = _json_dumps(params)
+        result_json = _json_dumps(result)
+        self.db.execute(
+            """
+            INSERT INTO rpc_cache (
+                chain_id, method, params_json, result_json, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(chain_id, method, params_json) DO UPDATE SET
+                result_json = excluded.result_json,
+                updated_at = excluded.updated_at
+            """,
+            (
+                int(chain_id),
+                method,
+                params_json,
+                result_json,
+                now,
+                now,
+            ),
+        )
+        self.db.commit()
+
+
+class RpcCacheMiddleware:
+    """fastweb3 middleware that caches selected RPC responses."""
+
+    def __init__(self, chain_id: int, db: CacheDB | None = None) -> None:
+        """Initialize the middleware.
+
+        Args:
+            chain_id: Chain ID to use in cache keys.
+            db: Cache database. If omitted, the process-global cache is used.
+        """
+        self.chain_id = int(chain_id)
+        self.cache = RpcCache(db)
+
+    def before_request(self, ctx, calls):
+        """Remove cached calls from the outbound request list."""
+        cached_results = {}
+        miss_indexes = []
+        miss_calls = []
+
+        for idx, call in enumerate(calls):
+            params = cache_params(call)
+
+            if params is not None:
+                result = self.cache.get(self.chain_id, call.method, params)
+                if result is not None:
+                    cached_results[idx] = result
+                    continue
+
+            miss_indexes.append(idx)
+            miss_calls.append(call)
+
+        ctx.state["rpc_cache_cached_results"] = cached_results
+        ctx.state["rpc_cache_miss_indexes"] = miss_indexes
+        ctx.state["rpc_cache_miss_calls"] = miss_calls
+        ctx.state["rpc_cache_original_count"] = len(calls)
+
+        return miss_calls
+
+    def after_request(self, ctx, calls, results):
+        """Store fresh results and merge them with cached hits."""
+        cached_results = ctx.state.get("rpc_cache_cached_results", {})
+        miss_indexes = ctx.state.get("rpc_cache_miss_indexes", [])
+        miss_calls = ctx.state.get("rpc_cache_miss_calls", [])
+        original_count = ctx.state.get("rpc_cache_original_count", len(results))
+
+        merged = [None] * original_count
+
+        for idx, result in cached_results.items():
+            merged[idx] = result
+
+        for idx, call, result in zip(miss_indexes, miss_calls, results, strict=True):
+            params = cache_params(call, result)
+            if params is not None:
+                self.cache.set(self.chain_id, call.method, params, result)
+            merged[idx] = result
+
+        return merged

fw3_objects/chain.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import AbstractContextManager
+from typing import Any
+
+from fw3 import Web3
+from fw3.deferred import deferred_response
+from fw3.validation import block_ref, hash32
+
+from .cache.rpc import RpcCacheMiddleware
+from .errors import ChainMismatch
+
+
+class _DefaultChainContext(AbstractContextManager["Chain"]):
+    """Context manager for temporarily setting the thread-local default chain."""
+
+    def __init__(self, chain: "Chain", *, strict: bool = False) -> None:
+        self._chain = chain
+        self._strict = strict
+        self._previous: tuple[Chain | None, bool] = (None, False)
+
+    def __enter__(self) -> "Chain":
+        self._previous = Chain._get_default_chain()
+        previous_chain, previous_strict = self._previous
+
+        if previous_strict:
+            raise ChainMismatch(
+                previous_chain, self._chain, "cannot nest default Chain contexts inside strict mode"
+            )
+
+        if self._strict and previous_chain is not None and previous_chain is not self._chain:
+            raise ChainMismatch(
+                previous_chain, self._chain, "default Chain context manager in strict mode"
+            )
+
+        Chain._set_default_chain(self._chain, self._strict)
+        return self._chain
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        Chain._set_default_chain(*self._previous)
+        return None
+
+
+class Chain:
+    """Canonical chain context for block, transaction, and contract access."""
+
+    _instances: dict[int, "Chain"] = {}
+    _instances_lock = threading.RLock()
+
+    _thread_local = threading.local()
+
+    def __new__(cls, chain_id: int) -> "Chain":
+        """Return the canonical instance for a chain ID.
+
+        Args:
+            chain_id: Chain ID to instantiate.
+
+        Returns:
+            Canonical Chain instance for the given chain ID.
+        """
+        chain_id = int(chain_id)
+
+        with cls._instances_lock:
+            if chain_id not in cls._instances:
+                cls._instances[chain_id] = super().__new__(cls)
+
+            return cls._instances[chain_id]
+
+    def __init__(self, chain_id: int) -> None:
+        """Initialize chain state.
+
+        Web3 configuration is stored immediately, but the Web3 client itself is created
+        lazily on first access.
+
+        Args:
+            chain_id: Chain ID to initialize.
+        """
+        if getattr(self, "_initialized", False):
+            return
+
+        self._initialized = True
+        self._chain_id = int(chain_id)
+        self._w3_params: dict[str, Any] = {}
+        self._w3: Web3 | None = None
+        self.__transaction_monitor = None
+
+    def __repr__(self) -> str:
+        """Return a developer-friendly representation."""
+        return f"Chain({self.id})"
+
+    def __int__(self) -> int:
+        """Return the numeric chain ID."""
+        return self.id
+
+    def __len__(self) -> int:
+        """Return the number of addressable block indices.
+
+        Returns:
+            Deferred value resolving to latest block height plus one.
+        """
+        height = self.height()
+        return deferred_response(None, ref_func=lambda h: h.set_value(height + 1))
+
+    def __getitem__(self, block_number: int):
+        """Return a block by number.
+
+        Negative indices are resolved relative to the latest block.
+
+        Args:
+            block_number: Absolute or negative-relative block number.
+
+        Returns:
+            Requested block object.
+
+        Raises:
+            TypeError: If ``block_number`` is not an integer.
+            IndexError: If a negative index resolves before genesis.
+
+        Notes:
+            Negative indices (``-2`` and below) require an additional RPC call to
+            resolve the latest block height. As a result, accessing the returned
+            value will perform I/O on first use.
+        """
+
+        if isinstance(block_number, slice):
+            raise TypeError("Slicing is not supported")
+
+        if not isinstance(block_number, int):
+            raise TypeError("block_number must be int")
+
+        if block_number > -2:
+            if block_number == -1:
+                block_number = "latest"
+            return self.get_block(block_number)
+
+        height = self.height()
+
+        def ref_func(handle):
+            blk = height + 1 + block_number
+            if blk < 0:
+                raise IndexError("block index out of range")
+            handle.set_value(self.get_block(blk))
+
+        return deferred_response(None, ref_func=ref_func)
+
+    @property
+    def id(self) -> int:
+        """Return the chain ID."""
+        return self._chain_id
+
+    @property
+    def w3(self) -> Web3:
+        """Return the configured Web3 instance for this chain.
+
+        The instance is created lazily on first access.
+
+        When a default chain context is active in strict mode, access is only
+        permitted on that chain. Attempting to access ``w3`` on any other chain
+        will raise.
+
+        Raises:
+            ChainMismatch: If a strict default chain context is active and this chain is
+                not the default chain.
+        """
+        default_chain, strict = self._get_default_chain()
+        if strict and default_chain is not None and default_chain is not self:
+            raise ChainMismatch(default_chain, self, "strict default chain")
+        if self._w3 is None:
+            self._create_w3(**self._w3_params)
+        return self._w3
+
+    @property
+    def _transaction_monitor(self):
+        if self.__transaction_monitor is None:
+            from .monitor import TransactionMonitor
+
+            self.__transaction_monitor = TransactionMonitor(self)
+        return self.__transaction_monitor
+
+    def height(self) -> int:
+        """Return the latest block number."""
+        return self.w3.eth.block_number()
+
+    def block_gas_limit(self) -> int:
+        """Return the gas limit of the latest block."""
+        block = self.get_block("latest")
+
+        return deferred_response(None, ref_func=lambda h: h.set_value(block["gasLimit"]))
+
+    def base_fee(self) -> int:
+        """Return the base fee per gas of the latest block."""
+        fee_history = self.w3.eth.fee_history(1, "latest", [])
+        return deferred_response(
+            None, ref_func=lambda h: h.set_value(fee_history["baseFeePerGas"][0])
+        )
+
+    def priority_fee(self) -> int:
+        """Return the suggested max priority fee per gas."""
+        return self.w3.eth.max_priority_fee_per_gas()
+
+    def get_transaction(self, hash: str | bytes):
+        """Return a transaction by hash.
+
+        Args:
+            hash: Transaction hash as a hex string or bytes.
+
+        Returns:
+            Transaction object.
+        """
+        from .transaction import Transaction
+
+        return Transaction(hash, chain=self)
+
+    def get_block(self, block_identifier: int | str | bytes):
+        """Return a block by number, tag, or hash.
+
+        Args:
+            block_identifier: Block number, block tag, or block hash.
+
+        Returns:
+            RPC block object.
+        """
+        if isinstance(block_identifier, bytes):
+            return self.w3.eth.get_block_by_hash(
+                hash32(block_identifier, name="block", strict=True)
+            )
+
+        normalized = block_ref(block_identifier, strict=True)
+
+        if (
+            isinstance(block_identifier, str)
+            and normalized.startswith("0x")
+            and len(normalized) == 66
+        ):
+            return self.w3.eth.get_block_by_hash(normalized)
+
+        return self.w3.eth.get_block_by_number(normalized)
+
+    def new_blocks(
+        self,
+        height_buffer: int = 0,
+        poll_interval: float = 5.0,
+    ) -> Iterator:
+        """Yield new blocks as they become available.
+
+        Args:
+            height_buffer: Number of blocks behind the tip to follow.
+            poll_interval: Target polling interval in seconds.
+
+        Yields:
+            New buffered blocks in ascending height order.
+
+        Raises:
+            ValueError: If ``height_buffer`` is negative or ``poll_interval`` is not
+                positive.
+        """
+        if height_buffer < 0:
+            raise ValueError("height_buffer must be >= 0")
+
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be > 0")
+
+        last_height = max(0, self.height() - height_buffer)
+
+        while True:
+            started_at = time.monotonic()
+            current_height = max(0, self.height() - height_buffer)
+
+            while current_height > last_height:
+                last_height += 1
+                yield self.get_block(last_height)
+
+            elapsed = time.monotonic() - started_at
+            time.sleep(max(0, poll_interval - elapsed))
+
+    def as_default(self, *, strict: bool = False) -> AbstractContextManager["Chain"]:
+        """Return a context manager that sets this thread's default chain.
+
+        Args:
+            strict: Whether to reject access through any other chain while the context
+                is active.
+
+        Returns:
+            Context manager that restores the previous default chain on exit.
+        """
+        return _DefaultChainContext(self, strict=strict)
+
+    def _create_w3(self, **w3_params: Any) -> None:
+        """Create and assign a new ``Web3`` instance for this chain."""
+        self._w3_params = dict(w3_params)
+        self._w3 = Web3(chain_id=self.id, **self._w3_params)
+        self._w3.provider.add_middleware(RpcCacheMiddleware(self.id))
+
+    @classmethod
+    def _get_default_chain(cls) -> tuple["Chain | None", bool]:
+        return (
+            getattr(cls._thread_local, "default_chain", None),
+            getattr(cls._thread_local, "default_chain_strict", False),
+        )
+
+    @classmethod
+    def _set_default_chain(cls, chain: "Chain | None", strict: bool) -> None:
+        cls._thread_local.default_chain = chain
+        cls._thread_local.default_chain_strict = strict
+
+
+def configure_chain(chain: Chain | int, **w3_params: Any) -> None:
+    """Configure the canonical Chain instance for a chain ID.
+
+    Args:
+        chain: Chain instance or chain ID to configure.
+        **w3_params: Keyword arguments forwarded to ``Web3``.
+    """
+    Chain(chain)._create_w3(**w3_params)