fastweb3-objects 0.1.0__py3-none-any.whl

fw3_objects/explorers/lookup.py

@@ -0,0 +1,267 @@
+"""Internal asynchronous ABI lookup worker used by Contract."""
+
+from __future__ import annotations
+
+import itertools
+import os
+import queue
+import threading
+import time
+from dataclasses import dataclass, field
+
+from fw3_objects.errors import ABINotFound, ExplorerError, ExplorerRateLimited
+
+from . import blockscout, etherscan
+
+LOW_PRIORITY = 10
+HIGH_PRIORITY = 0
+NEGATIVE_ABI_TTL = 30
+
+
+@dataclass
+class ABILookupJob:
+    chain_id: int
+    address: str
+    ignore_negative_cache: bool = False
+    resolve_proxy: bool = True
+    priority: int = LOW_PRIORITY
+    _event: threading.Event = field(default_factory=threading.Event, init=False)
+    _lock: threading.RLock = field(default_factory=threading.RLock, init=False)
+    _result: tuple[list[dict], str | None] | None = field(default=None, init=False)
+    _error: BaseException | None = field(default=None, init=False)
+    _callbacks: list = field(default_factory=list, init=False)
+
+    def add_done_callback(self, callback) -> None:
+        with self._lock:
+            if not self._event.is_set():
+                self._callbacks.append(callback)
+                return
+            result = self._result
+
+        if result is not None:
+            callback(result)
+
+    def bump_priority(self, priority: int) -> None:
+        with self._lock:
+            if self._event.is_set() or priority >= self.priority:
+                return
+            self.priority = priority
+        _enqueue(self)
+
+    def wait(self) -> tuple[list[dict], str | None]:
+        self._event.wait()
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+    def set_result(self, result: tuple[list[dict], str | None]) -> None:
+        with self._lock:
+            self._result = result
+            callbacks = tuple(self._callbacks)
+            self._callbacks.clear()
+            self._event.set()
+
+        for callback in callbacks:
+            try:
+                callback(result)
+            except Exception:
+                pass
+
+    def set_error(self, error: BaseException) -> None:
+        with self._lock:
+            self._error = error
+            self._callbacks.clear()
+            self._event.set()
+
+    @property
+    def done(self) -> bool:
+        return self._event.is_set()
+
+
+_sequence = itertools.count()
+_queue: queue.PriorityQueue[tuple[int, int, ABILookupJob]] = queue.PriorityQueue()
+_pending: dict[tuple[int, str, bool], ABILookupJob] = {}
+_negative_cache: dict[tuple[int, str, bool], float] = {}
+_rate_limited_until: dict[str, float] = {}
+_state_lock = threading.RLock()
+_worker_started = False
+
+
+def fetch_abi(
+    chain_id: int,
+    address: str,
+    *,
+    priority: int = LOW_PRIORITY,
+    ignore_negative_cache: bool = False,
+    resolve_proxy: bool = True,
+    on_success=None,
+) -> ABILookupJob:
+    chain_id = int(chain_id)
+    address = address.lower()
+    key = (chain_id, address, resolve_proxy)
+
+    with _state_lock:
+        existing = _pending.get(key)
+        if existing is not None and not existing.done and not ignore_negative_cache:
+            if on_success is not None:
+                existing.add_done_callback(on_success)
+            existing.bump_priority(priority)
+            return existing
+
+        if not ignore_negative_cache:
+            expires_at = _negative_cache.get(key)
+            if expires_at is not None and expires_at > time.monotonic():
+                job = ABILookupJob(
+                    chain_id,
+                    address,
+                    ignore_negative_cache=ignore_negative_cache,
+                    resolve_proxy=resolve_proxy,
+                    priority=priority,
+                )
+                job.set_error(ABINotFound(f"ABI not found for {address} on chain {chain_id}"))
+                return job
+            if expires_at is not None:
+                _negative_cache.pop(key, None)
+
+        job = ABILookupJob(
+            chain_id,
+            address,
+            ignore_negative_cache=ignore_negative_cache,
+            resolve_proxy=resolve_proxy,
+            priority=priority,
+        )
+        if on_success is not None:
+            job.add_done_callback(on_success)
+        _pending[key] = job
+        _ensure_worker_started()
+
+    _enqueue(job)
+    return job
+
+
+def _ensure_worker_started() -> None:
+    global _worker_started
+
+    if _worker_started:
+        return
+
+    thread = threading.Thread(target=_worker, name="fw3-objects-abi-lookup", daemon=True)
+    thread.start()
+    _worker_started = True
+
+
+def _enqueue(job: ABILookupJob) -> None:
+    _queue.put((job.priority, next(_sequence), job))
+
+
+def _worker() -> None:
+    while True:
+        priority, _, job = _queue.get()
+        try:
+            if job.done or priority != job.priority:
+                continue
+            _run_job(job)
+        finally:
+            _queue.task_done()
+
+
+def _run_job(job: ABILookupJob) -> None:
+    key = (job.chain_id, job.address, job.resolve_proxy)
+
+    try:
+        result = _fetch_abi(job.chain_id, job.address, resolve_proxy=job.resolve_proxy)
+    except BaseException as exc:
+        job.set_error(exc)
+        with _state_lock:
+            should_cache = _pending.get(key) is job
+            if should_cache and not job.ignore_negative_cache and isinstance(exc, ABINotFound):
+                _negative_cache[key] = time.monotonic() + NEGATIVE_ABI_TTL
+    else:
+        job.set_result(result)
+    finally:
+        with _state_lock:
+            if _pending.get(key) is job:
+                _pending.pop(key, None)
+
+
+def _fetch_abi(
+    chain_id: int, address: str, *, resolve_proxy: bool = True
+) -> tuple[list[dict], str | None]:
+    providers = _providers()
+    if not providers:
+        raise ABINotFound(
+            "No block explorer API keys configured, set ETHERSCAN_API_KEY or BLOCKSCOUT_API_KEY"
+        )
+
+    errors = []
+
+    while providers:
+        ready, blocked = _partition_ready(providers)
+
+        for name, func, api_key, cooldown in ready:
+            try:
+                return func(chain_id, address, api_key, resolve_proxy=resolve_proxy)
+            except ExplorerRateLimited as exc:
+                retry_after = exc.retry_after if exc.retry_after is not None else cooldown
+                with _state_lock:
+                    _rate_limited_until[name] = time.monotonic() + retry_after
+                errors.append(exc)
+            except (ABINotFound, ExplorerError) as exc:
+                errors.append(exc)
+
+        providers = blocked
+        if not providers:
+            break
+
+        sleep_for = (
+            min(_rate_limited_until.get(name, 0) for name, *_ in providers) - time.monotonic()
+        )
+        if sleep_for > 0:
+            time.sleep(sleep_for)
+
+    if errors:
+        if all(isinstance(error, ExplorerRateLimited) for error in errors):
+            raise errors[-1]
+
+        non_not_found_errors = [error for error in errors if not isinstance(error, ABINotFound)]
+        if non_not_found_errors:
+            raise non_not_found_errors[-1]
+
+    raise ABINotFound(f"ABI not found for {address} on chain {chain_id}")
+
+
+def _providers():
+    providers = []
+
+    # quietly support ETHERSCAN_TOKEN for brownie users
+    etherscan_key = os.getenv("ETHERSCAN_API_KEY") or os.getenv("ETHERSCAN_TOKEN")
+    if etherscan_key:
+        providers.append(
+            ("etherscan", etherscan.get_abi, etherscan_key, etherscan.RATE_LIMIT_COOLDOWN)
+        )
+
+    blockscout_key = os.getenv("BLOCKSCOUT_API_KEY")
+    if blockscout_key:
+        providers.append(
+            ("blockscout", blockscout.get_abi, blockscout_key, blockscout.RATE_LIMIT_COOLDOWN)
+        )
+
+    return providers
+
+
+def _partition_ready(providers):
+    now = time.monotonic()
+    ready = []
+    blocked = []
+
+    with _state_lock:
+        for provider in providers:
+            name = provider[0]
+            expires_at = _rate_limited_until.get(name)
+            if expires_at is None or expires_at <= now:
+                _rate_limited_until.pop(name, None)
+                ready.append(provider)
+            else:
+                blocked.append(provider)
+
+    return ready, blocked

fw3_objects/monitor.py

@@ -0,0 +1,125 @@
+"""Internal transaction monitoring process used by Chain and Transaction."""
+
+from __future__ import annotations
+
+import time
+from threading import Event, RLock, Thread
+from weakref import WeakSet
+
+from .transaction import TxStatus
+
+MAX_BATCH_SIZE = 100
+POLL_INTERVAL = 1.0
+
+
+class TransactionMonitor:
+    """Internal transaction polling process for a Chain.
+
+    Users do not instantiate this class directly. A Chain creates one lazily when a
+    Transaction is watched, and Transaction objects use it to receive mempool,
+    receipt, replacement, and drop updates.
+    """
+
+    def __init__(self, chain):
+        self.chain = chain
+        self._watched = WeakSet()
+        self._lock = RLock()
+        self._wake = Event()
+        self._thread = None
+        self.last_error = None
+
+    def watch(self, tx):
+        with self._lock:
+            self._watched.add(tx)
+            if self._thread is None:
+                self._thread = Thread(target=self._run, daemon=True)
+                self._thread.start()
+        self._wake.set()
+
+    def _run(self):
+        while True:
+            started_at = time.monotonic()
+            self._poll_once()
+            elapsed = time.monotonic() - started_at
+            self._wake.wait(max(0, POLL_INTERVAL - elapsed))
+            self._wake.clear()
+
+    def _poll_once(self):
+        with self._lock:
+            watched = tuple(self._watched)
+
+        if not watched:
+            return
+
+        transactions_per_batch = max(1, MAX_BATCH_SIZE // 3)
+        for batch in _chunks(watched, transactions_per_batch):
+            try:
+                self._poll_batch(batch)
+            except Exception as exc:
+                self.last_error = exc
+
+    def _poll_batch(self, watched):
+        w3 = self.chain.w3
+        known = [tx for tx in watched if tx._transaction.get("from")]
+        senders = {tx._transaction["from"] for tx in known}
+
+        with w3.batch_requests():
+            tx_data = {tx: w3.eth.get_transaction_by_hash(tx.hash) for tx in watched}
+            receipts = {tx: w3.eth.get_transaction_receipt(tx.hash) for tx in watched}
+            latest_nonces = {
+                sender: w3.eth.get_transaction_count(sender, "latest") for sender in senders
+            }
+
+        for tx in watched:
+            txdict = tx_data[tx]
+            receipt = receipts[tx]
+
+            if bool(receipt):
+                # receipt is available, transaction has confirmed.
+                if bool(txdict):
+                    tx._transaction = dict(txdict)
+                tx._receipt = dict(receipt)
+                tx._status = TxStatus(receipt["status"])
+                tx._finalized.set()
+                if tx._status == TxStatus.REVERTED:
+                    tx._resolve_revert_reason()
+
+            elif bool(txdict):
+                # receipt not available, but transaction is. the transaction
+                # is currently sitting in a the public mempool.
+                tx._transaction = dict(txdict)
+                tx._status = TxStatus.PENDING
+
+            else:
+                # receipt and transaction are both unavailable from node
+                sender = tx._transaction.get("from")
+                if sender and latest_nonces.get(sender, 0) > tx._transaction["nonce"]:
+                    # we know the sender and nonce, because the transaction was either
+                    # previously seen publicly or seeded locally. the sender's nonce has
+                    # advanced beyond the nonce of this transaction, but the transaction
+                    # did not confirm. finalize as replaced by another transaction.
+                    tx._status = TxStatus.REPLACED
+                    tx._finalized.set()
+                elif tx._status != TxStatus.UNSEEN:
+                    # transaction was previously seen, but we cannot say for sure
+                    # that it was replaced - only that it is no longer available from
+                    # the node. mark it as dropped.
+                    tx._status = TxStatus.DROPPED
+                elif not tx._allow_unseen:
+                    # transaction was never seen and caller did not ask us to keep
+                    # watching unseen hashes. finalize as not found.
+                    tx._finalized.set()
+
+            tx._initialized.set()
+
+        remove = {i for i in watched if i._finalized.is_set()}
+
+        if remove:
+            with self._lock:
+                self._watched.difference_update(remove)
+
+
+def _chunks(values, size):
+    values = tuple(values)
+    for idx in range(0, len(values), size):
+        yield values[idx : idx + size]