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

+2 -9
View File
@@ -14,7 +14,7 @@ from app.config import settings
from app.db.models import AuditLog, BugReport, PendingTransaction, Round, User
from app.db.session import get_session
from app.rounds.config import get_round_config
from app.rounds.pause import AUTOMATIC_REASONS, OPERATOR_REASON
from app.rounds.pause import pause_by_operator
from app.rounds.service import get_active_round, payout_config_problem
from app.wallet.address import is_valid_plm_address
from app.wallet.hd import derive_user_wif
@@ -196,14 +196,7 @@ async def pause_lottery(
B-78 (DAT-69, API-32): the reason is "operator", except that an automatic reason
already in force stays — it is the one that needs a look. The audit row always
says `operator` for this call."""
config = await get_round_config(session)
if not (config.paused and config.paused_reason in AUTOMATIC_REASONS):
config.paused_reason = OPERATOR_REASON
config.paused = True
payload = {"reason": OPERATOR_REASON}
if body is not None and body.note:
payload["note"] = body.note
await write_audit_log(session, "lottery_paused", payload)
config = await pause_by_operator(session, body.note if body is not None else None)
await session.commit()
return _config_response(config)
+8
View File
@@ -70,6 +70,14 @@ class TokenResponse(BaseModel):
async def register(
body: RegisterRequest, request: Request, session: AsyncSession = Depends(get_session)
) -> TokenResponse:
# B-90 (REG-15): after a restore a new user could be handed the derivation index — the
# address, with the funds — of someone who registered after the backup.
if not getattr(request.app.state.electrum_listener, "registration_open", True):
raise http_error(
status.HTTP_503_SERVICE_UNAVAILABLE,
"registration_unavailable",
"registration is temporarily unavailable",
)
limiters = _rate_limiters(request)
ip_key = f"ip:{_client_ip(request)}"
# B-58: checked before the Argon2 hash below, so an IP that's out of quota
+3
View File
@@ -41,6 +41,9 @@ class Settings(BaseSettings):
# trust the quorum exists to remove.
allow_no_quorum: bool = False
# B-90 (OPS-27): start with the lottery paused, as after restoring a backup.
start_paused: bool = False
xprv_encryption_key: str = ""
master_key_path: str = "./master.xprv.enc"
jwt_secret: str = ""
+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
+6
View File
@@ -28,6 +28,7 @@ from app.deposits.reconcile import DepositReconciler
from app.electrum.client import ElectrumClient, ElectrumEndpoint, parse_endpoints
from app.electrum.listener import ElectrumListener
from app.rounds.scheduler import RoundScheduler
from app.rounds.pause import pause_by_operator
from app.tx.broadcast import RbfBumper
from app.tx.confirmation import ConfirmationPoller
from app.tx.locks import UserLocks
@@ -55,6 +56,11 @@ async def lifespan(app: FastAPI):
)
validate_quorum_servers(endpoints) # B-84: refuses to serve without a usable quorum
verify_master_key() # B-89: refuses to serve with a key that did not produce the stored addresses
if settings.start_paused: # B-90 (OPS-27): before the scheduler exists, so no round can open first
async with AsyncSessionLocal() as session:
await pause_by_operator(session, "START_PAUSED")
await session.commit()
logger.warning("START_PAUSED=true: the lottery starts paused (resume it from /admin)")
logger.info("Electrum endpoints (in rotation order): %s", ", ".join(str(e) for e in endpoints))
listener = ElectrumListener(
+15
View File
@@ -28,3 +28,18 @@ async def pause_automatically(session: AsyncSession, reason: str) -> None:
config.paused = True
config.paused_reason = reason
await write_audit_log(session, "lottery_paused", {"reason": reason})
async def pause_by_operator(session: AsyncSession, note: str | None = None):
"""The operator's pause (`POST /admin/pause`, B-90's `START_PAUSED`): never overwrites
an automatic reason already in force — that is the one that needs a look — and the
audit row always says `operator`. Returns the config row; the caller commits."""
config = await get_round_config(session)
if not (config.paused and config.paused_reason in AUTOMATIC_REASONS):
config.paused_reason = OPERATOR_REASON
config.paused = True
payload = {"reason": OPERATOR_REASON}
if note:
payload["note"] = note
await write_audit_log(session, "lottery_paused", payload)
return config
+7
View File
@@ -161,6 +161,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Enter an amount greater than zero.',
'error.broadcast_failed': 'The network refused the transaction. Please try again shortly.',
'error.service_busy': 'The service is busy right now and nothing was sent. Please try again in a moment.',
'error.registration_unavailable': 'Registration is temporarily unavailable. Please try again later.',
'error.amount_below_dust_limit': 'The amount is too small to be sent.',
'error.too_many_inputs': 'Your balance is split across too many small deposits to be spent in a single transaction (max {max_inputs}). Please contact support to consolidate it.',
'error.withdrawal_to_own_address': 'That is your own deposit address — withdraw to an external wallet.',
@@ -329,6 +330,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Inserisci un importo maggiore di zero.',
'error.broadcast_failed': 'La rete ha rifiutato la transazione. Riprova tra poco.',
'error.service_busy': 'Il servizio è occupato in questo momento e non è stato inviato nulla. Riprova tra poco.',
'error.registration_unavailable': 'La registrazione è temporaneamente non disponibile. Riprova più tardi.',
'error.amount_below_dust_limit': "L'importo è troppo basso per essere inviato.",
'error.too_many_inputs': 'Il tuo saldo è suddiviso in troppi piccoli depositi per essere speso in una sola transazione (max {max_inputs}). Contatta l\'assistenza per consolidarlo.',
'error.withdrawal_to_own_address': 'Questo è il tuo indirizzo di deposito — preleva verso un wallet esterno.',
@@ -497,6 +499,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Introduce un importe mayor que cero.',
'error.broadcast_failed': 'La red rechazó la transacción. Inténtalo de nuevo en un momento.',
'error.service_busy': 'El servicio está ocupado en este momento y no se ha enviado nada. Inténtalo de nuevo en un momento.',
'error.registration_unavailable': 'El registro no está disponible temporalmente. Inténtalo de nuevo más tarde.',
'error.amount_below_dust_limit': 'El importe es demasiado pequeño para enviarse.',
'error.too_many_inputs': 'Tu saldo está repartido en demasiados depósitos pequeños para gastarse en una sola transacción (máx. {max_inputs}). Contacta con soporte para consolidarlo.',
'error.withdrawal_to_own_address': 'Esa es tu propia dirección de depósito — retira a una cartera externa.',
@@ -665,6 +668,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Saisissez un montant supérieur à zéro.',
'error.broadcast_failed': 'Le réseau a refusé la transaction. Veuillez réessayer dans un instant.',
'error.service_busy': 'Le service est occupé pour le moment et rien n\'a été envoyé. Veuillez réessayer dans un instant.',
'error.registration_unavailable': 'L\'inscription est temporairement indisponible. Veuillez réessayer plus tard.',
'error.amount_below_dust_limit': "Le montant est trop faible pour être envoyé.",
'error.too_many_inputs': 'Votre solde est réparti sur trop de petits dépôts pour être dépensé en une seule transaction (max {max_inputs}). Contactez le support pour le consolider.',
'error.withdrawal_to_own_address': "C'est votre propre adresse de dépôt — retirez vers un portefeuille externe.",
@@ -833,6 +837,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Gib einen Betrag größer als null ein.',
'error.broadcast_failed': 'Das Netzwerk hat die Transaktion abgelehnt. Bitte versuche es in Kürze erneut.',
'error.service_busy': 'Der Dienst ist gerade ausgelastet und es wurde nichts gesendet. Bitte versuche es gleich noch einmal.',
'error.registration_unavailable': 'Die Registrierung ist vorübergehend nicht verfügbar. Bitte versuche es später noch einmal.',
'error.amount_below_dust_limit': 'Der Betrag ist zu klein, um gesendet zu werden.',
'error.too_many_inputs': 'Ihr Guthaben ist auf zu viele kleine Einzahlungen verteilt, um in einer einzigen Transaktion ausgegeben zu werden (max. {max_inputs}). Bitte wenden Sie sich an den Support, um es zusammenzufassen.',
'error.withdrawal_to_own_address': 'Das ist deine eigene Einzahlungsadresse — zahle auf eine externe Wallet aus.',
@@ -1001,6 +1006,7 @@ const TRANSLATIONS = {
'error.invalid_amount': 'Введите сумму больше нуля.',
'error.broadcast_failed': 'Сеть отклонила транзакцию. Попробуйте ещё раз через минуту.',
'error.service_busy': 'Сервис сейчас занят, ничего не было отправлено. Попробуйте ещё раз через минуту.',
'error.registration_unavailable': 'Регистрация временно недоступна. Попробуйте позже.',
'error.amount_below_dust_limit': 'Сумма слишком мала для отправки.',
'error.too_many_inputs': 'Ваш баланс разбит на слишком много мелких депозитов, чтобы потратить его одной транзакцией (максимум {max_inputs}). Обратитесь в поддержку для консолидации.',
'error.withdrawal_to_own_address': 'Это ваш собственный адрес для депозита — выводите на внешний кошелёк.',
@@ -1169,6 +1175,7 @@ const TRANSLATIONS = {
'error.invalid_amount': '请输入大于零的金额。',
'error.broadcast_failed': '网络拒绝了该交易,请稍后重试。',
'error.service_busy': '服务当前繁忙,没有发送任何内容,请稍后重试。',
'error.registration_unavailable': '注册暂时不可用,请稍后再试。',
'error.amount_below_dust_limit': '金额过小,无法发送。',
'error.too_many_inputs': '您的余额分散在过多的小额存款中,无法在一笔交易中花费(最多 {max_inputs} 笔)。请联系客服进行归集。',
'error.withdrawal_to_own_address': '这是你自己的充值地址 — 请提现到外部钱包。',