Safe restore from a backup: START_PAUSED and the derivation-gap check (B-90, REG-15, OPS-27)

START_PAUSED=true pauses the lottery as the operator before the scheduler exists.
On the first Electrum session the 20 derivation indexes past the highest
assigned one are looked up on every server; if any has history, registration
stays closed (503 registration_unavailable) and restore_gap_detected is
written, so a restored database cannot hand a lost user's address to a new one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-10-18 00:43:45 +02:00
1 parent 55d852fe08
commit 40ac490826
21 files changed
+281 -70

No files matched your search

+68 -1
View File
@@ -5,7 +5,7 @@ from collections import Counter
from collections.abc import Callable
from embit.transaction import Transaction
from sqlalchemy import select
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import async_sessionmaker
from app.audit.log import write_audit_log
@@ -34,6 +34,7 @@ from app.rounds.draw import (
)
from app.rounds.events import broadcaster
from app.rounds.pause import pause_automatically
from app.wallet.hd import derive_user_address
logger = logging.getLogger(__name__)
@@ -70,6 +71,10 @@ _monotonic = time.monotonic
# ordinary on any chain, two or more is worth a look before a new round opens.
_REORG_PAUSE_DEPTH = 2
# B-90 (REG-15): how many derivation indexes past the highest assigned one are looked up for history
# before registration opens.
_RESTORE_GAP_WINDOW = 20
# `blockchain.block.headers` serves at most this many headers per request (ELC-12).
_MAX_HEADERS_PER_REQUEST = 2016
@@ -95,6 +100,11 @@ class ElectrumListener:
servers down) still backs off instead of spinning.
"""
# B-90 (REG-15): False until the check of the derivation indexes past the highest assigned
# one has completed and found no address with history. A class attribute so a test that
# is not about a restore can open registration once for every listener.
registration_open = False
def __init__(
self,
client_factory: Callable[[ElectrumEndpoint], ElectrumClient],
@@ -108,6 +118,7 @@ class ElectrumListener:
# B-84 (ELC-19): ALLOW_NO_QUORUM, development only — see _corroborate_majority.
self._allow_no_quorum = allow_no_quorum
self._endpoint_index = 0
self._restore_checked = False
self._scripthash_to_user: dict[str, int] = {}
# Retains address_for_new_user's fire-and-forget subscribe task so it
# can't be garbage-collected mid-flight, and so its exception (if any) is
@@ -267,10 +278,16 @@ class ElectrumListener:
# the session actually does end.
subscribe_task = asyncio.create_task(self._subscribe_all_users())
subscribe_task.add_done_callback(self._log_subscribe_all_users_failure)
restore_task = None
if not self._restore_checked:
restore_task = asyncio.create_task(self._check_restore_gap())
restore_task.add_done_callback(self._log_restore_check_failure)
try:
done, still_running = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
finally:
subscribe_task.cancel()
if restore_task is not None:
restore_task.cancel()
for task in tasks:
task.cancel()
for task in done:
@@ -282,6 +299,56 @@ class ElectrumListener:
await client.close()
return True
def _log_restore_check_failure(self, task: asyncio.Task) -> None:
if not task.cancelled() and task.exception() is not None:
logger.warning("restore-gap check not completed, registration stays closed: %r", task.exception())
async def _check_restore_gap(self) -> None:
"""B-90 (REG-15): a database restored from a backup does not know the users who
registered after it, and would hand their derivation indexes — their addresses,
with whatever they received — to new users. So the `_RESTORE_GAP_WINDOW` indexes
past the highest assigned one are looked up with `get_history` on the active
server and on every other one; a single server reporting a transaction makes the
address used. Registration opens only when none is; otherwise `restore_gap_detected`
is written and it stays closed until a later start finds none (the operator
occupies those indexes, OPS-28). If the active server cannot answer the check is
simply tried again on the next session."""
async with self._session_factory() as session:
highest = (await session.execute(select(func.max(User.derivation_index)))).scalar_one_or_none()
first = 0 if highest is None else highest + 1
addresses = [(index, derive_user_address(index)) for index in range(first, first + _RESTORE_GAP_WINDOW)]
async def ask(client: ElectrumClient) -> list[bool]:
histories = await asyncio.gather(
*(client.request("blockchain.scripthash.get_history", [address_to_scripthash(a)]) for _, a in addresses)
)
return [bool(history) for history in histories]
active = await self._ask_active_server(ask)
if active is None:
raise RuntimeError("the active server did not answer the history lookups")
others = await self._ask_other_servers(ask)
answers = [active] + [answer for answer in others if answer is not None]
used = [
{"derivation_index": index, "address": address}
for position, (index, address) in enumerate(addresses)
if any(answer[position] for answer in answers)
]
self._restore_checked = True
if not used:
self.registration_open = True
return
logger.error(
"restore gap: %s derivation index(es) past the highest assigned one already have history "
"on chain — registration stays closed (OPS-28)",
len(used),
)
async with self._session_factory() as session:
await write_audit_log(
session, "restore_gap_detected", {"highest_assigned_index": highest, "used": used}
)
await session.commit()
def _log_subscribe_all_users_failure(self, task: asyncio.Task) -> None:
if task.cancelled():
return