"""The network phase of a deposit scan (roadmap B5, DEP-20, ELC-14, ELC-17, ELC-26, ELC-31). Nothing here touches the database. `observe` takes the `Policy` read in phase 1 and returns what the servers say, already corroborated: the active server is the first one that answers *and* has the genesis of the network profile; every other configured server is asked, over a fresh connection with its own time limit, whether it agrees. Silence is never an answer (ELC-14): a server that does not respond does not count. """ import asyncio import hashlib import logging from collections.abc import Awaitable, Callable from embit.transaction import Transaction from plm_engine.electrum.client import ElectrumClient, ElectrumEndpoint from plm_engine.electrum.merkle import proof_matches_header from plm_engine.electrum.scripthash import address_to_scripthash from plm_engine.headers import header_meets_its_own_target from plm_engine.network import Profile from plm_engine.psbt_builder import DUST_LIMIT_SATS from .deposits import Observation, Policy, ScanResult, Seen, confirmations, threshold_for logger = logging.getLogger(__name__) CONNECT_TIMEOUT = 10.0 ANSWER_TIMEOUT = 10.0 def _seen(raw: dict) -> Seen | None: try: return Seen(txid=str(raw["tx_hash"]), vout=int(raw["tx_pos"]), value=int(raw["value"]), height=int(raw["height"])) except (KeyError, TypeError, ValueError): return None class ElectrumChain: def __init__( self, endpoints: list[ElectrumEndpoint], profile: Profile, allow_no_quorum: bool = False, client_factory: Callable[[ElectrumEndpoint], ElectrumClient] | None = None, ): self.endpoints = endpoints self.profile = profile self.allow_no_quorum = allow_no_quorum self._factory = client_factory or ( lambda e: ElectrumClient(e.host, e.port, e.use_ssl, e.pin, genesis_hash=profile.genesis_hash) ) self.active_endpoint: ElectrumEndpoint | None = None # -- connections ------------------------------------------------------------------------------ async def _open(self, endpoint: ElectrumEndpoint) -> ElectrumClient | None: client = self._factory(endpoint) try: await asyncio.wait_for(client.connect(), CONNECT_TIMEOUT) except Exception as error: # unreachable, wrong chain, bad pin: all are "this server is not usable now" logger.warning("electrum %s unusable: %s", endpoint, error) return None return client async def _connect_active(self) -> ElectrumClient | None: for endpoint in self.endpoints: # rotation: the first usable one in configuration order client = await self._open(endpoint) if client is not None: self.active_endpoint = endpoint return client return None async def _ask_others(self, ask: Callable[[ElectrumClient], Awaitable]) -> list: """`ask` on every server but the active one, concurrently, each over a fresh connection. `None` = no answer.""" async def one(endpoint: ElectrumEndpoint): client = await self._open(endpoint) if client is None: return None try: return await asyncio.wait_for(ask(client), ANSWER_TIMEOUT) except Exception as error: logger.warning("electrum %s did not answer: %s", endpoint, error) return None finally: await client.close() others = [e for e in self.endpoints if e != self.active_endpoint] return list(await asyncio.gather(*(one(e) for e in others))) def majority(self, answers: list) -> bool: """ELC-14. Answers are True (agrees), False (disagrees) or None (silent). At least two answered and a strict majority of those agrees; with the development exception, no other server at all passes and any strict majority of even one answer does.""" answered = [a for a in answers if a is not None] if self.allow_no_quorum: if not self.endpoints or len(self.endpoints) == 1: return True return bool(answered) and sum(bool(a) for a in answered) * 2 > len(answered) return len(answered) >= 2 and sum(bool(a) for a in answered) * 2 > len(answered) # -- what is asked ------------------------------------------------------------------------------ async def _tip(self, active: ElectrumClient) -> tuple[int, str] | None: """The active server's tip, accepted only with work valid for the profile and agreed by the others.""" reply = await active.subscribe_headers() try: height, header = int(reply["height"]), str(reply["hex"]) except (KeyError, TypeError, ValueError): return None if not header_meets_its_own_target(header, self.profile.pow_limit): logger.warning("the tip header of %s has no valid work", self.active_endpoint) return None async def same_header(client: ElectrumClient) -> bool: return await client.get_block_header(height) == header if not self.majority(await self._ask_others(same_header)): return None return height, header async def _unspent(self, client: ElectrumClient, address: str) -> list[Seen] | None: try: raw = await asyncio.wait_for(client.listunspent(address_to_scripthash(address)), ANSWER_TIMEOUT) except Exception as error: logger.warning("listunspent for %s failed: %s", address, error) return None if not isinstance(raw, list): return None seen = [_seen(item) for item in raw if isinstance(item, dict)] return None if any(item is None for item in seen) else seen async def is_coinbase(self, client: ElectrumClient, txid: str) -> bool | None: """From the raw transaction, accepted only if its hash is the txid (DEP-21); None = could not tell.""" try: raw = await asyncio.wait_for(client.get_transaction(txid), ANSWER_TIMEOUT) tx = Transaction.parse(bytes.fromhex(str(raw))) if tx.txid().hex() != txid: return None except Exception as error: logger.warning("cannot read transaction %s: %s", txid, error) return None return len(tx.vin) == 1 and tx.vin[0].txid == bytes(32) async def _credit_verified(self, active: ElectrumClient, address: str, entry: Seen, tip: int, need: int) -> bool: """ELC-17 (the others list the coin, same value, deep enough) and ELC-26 (a merkle proof from the others matches a header of the active server that has valid work).""" scripthash = address_to_scripthash(address) deepest = tip - need + 1 async def lists_it(client: ElectrumClient) -> bool: for raw in await client.listunspent(scripthash): other = _seen(raw) if isinstance(raw, dict) else None if other and (other.txid, other.vout) == (entry.txid, entry.vout): return other.value == entry.value and 0 < other.height <= deepest return False if not self.majority(await self._ask_others(lists_it)): return False try: header = await asyncio.wait_for(active.get_block_header(entry.height), ANSWER_TIMEOUT) except Exception: return False if not header_meets_its_own_target(str(header), self.profile.pow_limit): return False async def proves_it(client: ElectrumClient) -> bool: return proof_matches_header(entry.txid, entry.height, await client.get_merkle(entry.txid, entry.height), str(header)) return self.majority(await self._ask_others(proves_it)) async def _absent_confirmed(self, address: str, outpoint: tuple[str, int]) -> bool: scripthash = address_to_scripthash(address) async def lacks_it(client: ElectrumClient) -> bool: listed = {(r.get("tx_hash"), r.get("tx_pos")) for r in await client.listunspent(scripthash) if isinstance(r, dict)} return outpoint not in listed return self.majority(await self._ask_others(lacks_it)) # -- the scan ---------------------------------------------------------------------------------------- async def observe(self, policy: Policy) -> ScanResult: active = await self._connect_active() if active is None: return ScanResult(None, {}) try: tip = await self._tip(active) if tip is None: return ScanResult(None, {}) result = ScanResult(tip[0], {}) for address in policy.addresses: result.addresses[address] = await self._observe_address(active, address, tip[0], policy) return result except Exception: # a scan that fails writes nothing; the next one starts again logger.exception("deposit scan failed") return ScanResult(None, {}) finally: await active.close() async def _observe_address(self, active: ElectrumClient, address: str, tip: int, policy: Policy) -> Observation: entries = await self._unspent(active, address) observation = Observation(entries) if entries is None: return observation listed = {(e.txid, e.vout) for e in entries} for entry in entries: outpoint = (entry.txid, entry.vout) if entry.value < DUST_LIMIT_SATS or entry.height <= 0 or outpoint in policy.credited: continue have = confirmations(tip, entry.height) if have >= policy.deposit_confirmations and entry.txid not in policy.own_txids: coinbase = await self.is_coinbase(active, entry.txid) if coinbase is None: continue # unreadable: it cannot be credited as an ordinary deposit by mistake if coinbase: observation.coinbase.add(entry.txid) need = threshold_for(entry.txid, policy, observation.coinbase) if have >= need and await self._credit_verified(active, address, entry, tip, need): observation.verified.add(outpoint) for outpoint in policy.waiting.get(address, frozenset()) - listed: if await self._absent_confirmed(address, outpoint): observation.absent_confirmed.add(outpoint) return observation