B5: real deposits on the ORM, Electrum scan with quorum and merkle proof, configurable threshold (DEP-20..23, ELC-31)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
f1d09075a1
commit
2acd4ccd1c
21 files changed
+1223
-49
No files matched your search
@@ -0,0 +1,224 @@
|
||||
"""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
|
||||
|
||||
Reference in new issue
Block a user