B7: confirmations with merkle proof, adoption of the confirmed version, RBF bumper and reconciler (TX-30..33, DAT-85)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
davideandClaude Sonnet 5.5 committed 2026-11-16 16:29:08 +01:00
1 parent feff993584
commit fa57d2e5ab
20 files changed
+1165 -20

No files matched your search

+1 -1
View File
@@ -83,7 +83,7 @@ class LotteryConfigAdmin(admin.ModelAdmin):
commands, which ask for a reason (WEB-43). A change is audited with what changed."""
fields = ("fee_address", "bet_amount_sats", "round_duration_seconds", "round_cooldown_seconds",
"draw_confirmations", "deposit_confirmations", "max_round_pool_sats", "fee_rate_sat_vb")
"draw_confirmations", "deposit_confirmations", "max_round_pool_sats", "fee_rate_sat_vb", "rbf_timeout_seconds")
def has_add_permission(self, request):
return False
+10 -8
View File
@@ -77,6 +77,8 @@ def _sign_one(tx: ChainTransaction, account, fee_rate: int) -> bool:
if fresh.status != ChainTransaction.Status.BUILDING or fresh.current_txid is not None:
return False # someone else got there first
register_version(fresh, built.txid, built.raw_hex)
fresh.fee_rate_sat_vb = fee_rate # DAT-85: what the next bump starts from
fresh.save(update_fields=["fee_rate_sat_vb"])
bet.bet_txid, bet.bet_vout, bet.bet_amount_sats = built.txid, RECIPIENT_VOUT, built.recipient_sats
bet.save(update_fields=["bet_txid", "bet_vout", "bet_amount_sats"])
audit.record("bet_signed", actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
@@ -85,23 +87,23 @@ def _sign_one(tx: ChainTransaction, account, fee_rate: int) -> bool:
return True
def _fail(tx: ChainTransaction, reason: str, *, release: bool) -> None:
def _fail(tx: ChainTransaction, reason: str, *, release: bool, action: str = "bet_refused") -> int:
"""Refused with proof (or unbuildable): the bet is rejected, the coins return, the movement stops counting."""
with transaction.atomic():
fresh = ChainTransaction.objects.select_for_update().get(pk=tx.pk)
if fresh.status not in (ChainTransaction.Status.BUILDING, ChainTransaction.Status.PENDING):
return
return 0
fresh.status, fresh.failed_at, fresh.failure_reason = ChainTransaction.Status.FAILED, timezone.now(), reason[:500]
fresh.save(update_fields=["status", "failed_at", "failure_reason"])
if release:
reservation.release(fresh)
freed = reservation.release(fresh) if release else 0
bet = _bet_of(fresh)
if bet is not None:
bet.status = Participation.Status.REJECTED
bet.save(update_fields=["status"])
Movement.objects.filter(participation=bet, kind=Movement.Kind.BET).update(status=Movement.Status.FAILED)
audit.record("bet_refused", actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
outcome="error", payload={"reason": reason[:500]})
audit.record(action, actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
outcome="error", payload={"reason": reason[:500], "coins_freed": freed})
return freed
def _settle(tx_id: int, txid: str, verdict, now: datetime) -> bool:
@@ -111,8 +113,8 @@ def _settle(tx_id: int, txid: str, verdict, now: datetime) -> bool:
if fresh.status != ChainTransaction.Status.BUILDING or fresh.current_txid != txid:
return False
if verdict.outcome is Outcome.ACCEPTED:
fresh.status, fresh.broadcast_at = ChainTransaction.Status.PENDING, now
fresh.save(update_fields=["status", "broadcast_at"])
fresh.status, fresh.broadcast_at, fresh.last_broadcast_at = ChainTransaction.Status.PENDING, now, now
fresh.save(update_fields=["status", "broadcast_at", "last_broadcast_at"])
audit.record("bet_broadcast", actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
payload={"txid": txid, "note": verdict.reason})
return True
+88
View File
@@ -0,0 +1,88 @@
"""Confirmations of the platform's own transactions (roadmap B7, TX-30, TX-31, TX-26).
Three phases like the deposit scan: read the pending transactions and every txid each has had; ask the servers with no
database open (a version in a block, with a merkle proof the others back); write the outcome, only for rows still
`pending`. The version that confirms is adopted even when it is not `current_txid`: an RBF replacement may not have won.
"""
import asyncio
import logging
from datetime import datetime
from django.db import transaction
from django.utils import timezone
from . import audit
from .models import ChainTransaction, DepositAddress, Movement, Participation, Utxo
logger = logging.getLogger(__name__)
WORKER = "worker"
def spending_address(tx: ChainTransaction) -> str | None:
"""The address whose history shows the transaction: the player's for a bet or a withdrawal, the round's pool for a
payout (B8)."""
if tx.kind == ChainTransaction.Kind.PAYOUT:
return tx.round.pool_address if tx.round_id else None
owner = DepositAddress.objects.filter(user_id=tx.user_id).first()
return owner.address if owner else None
def plan() -> list[tuple[int, str, frozenset[str]]]:
wanted = []
for tx in ChainTransaction.objects.filter(status=ChainTransaction.Status.PENDING).select_related("round").order_by("id"):
address = spending_address(tx)
txids = frozenset(tx.versions.values_list("txid", flat=True))
if address and txids:
wanted.append((tx.pk, address, txids))
return wanted
def apply_confirmations(confirmed: dict[int, tuple[str, int]], now: datetime | None = None) -> int:
now = now or timezone.now()
done = 0
for tx_id, (txid, height) in confirmed.items():
with transaction.atomic():
fresh = ChainTransaction.objects.select_for_update().get(pk=tx_id)
if fresh.status != ChainTransaction.Status.PENDING:
continue # TX-26: confirmed, abandoned or settled by someone else while the network was asked
version = fresh.versions.filter(txid=txid).first()
if version is None:
logger.error("transaction %s: confirmed txid %s is none of its versions", tx_id, txid)
continue
adopted = fresh.current_txid != txid
if adopted: # TX-31
fresh.current_txid = txid
if version.raw_hex:
fresh.raw_hex = version.raw_hex
fresh.status, fresh.confirmed_at = ChainTransaction.Status.CONFIRMED, now
fresh.save(update_fields=["status", "confirmed_at", "current_txid", "raw_hex"])
Utxo.objects.filter(reserved_by=fresh).update(spent_txid=txid)
if fresh.kind == ChainTransaction.Kind.BET:
_bet_confirmed(fresh, txid, now)
audit.record("tx_confirmed", actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
payload={"txid": txid, "height": height, "adopted": adopted, "kind": fresh.kind})
done += 1
return done
def _bet_confirmed(tx: ChainTransaction, txid: str, now: datetime) -> None:
"""The bet takes part in the draw (BET, TX-07): found through its fixed links, never through the txid (TX-08)."""
movement = Movement.objects.filter(chain_transaction=tx, kind=Movement.Kind.BET).select_related("participation").first()
if movement is None or movement.participation is None:
return
bet = movement.participation
if bet.status == Participation.Status.PENDING:
bet.status, bet.confirmed_at, bet.bet_txid = Participation.Status.CONFIRMED, now, txid
bet.save(update_fields=["status", "confirmed_at", "bet_txid"])
if movement.status == Movement.Status.PENDING:
movement.status, movement.confirmed_at = Movement.Status.CONFIRMED, now
movement.save(update_fields=["status", "confirmed_at"])
def poll_confirmations(chain, now: datetime | None = None) -> int:
wanted = plan()
if not wanted:
return 0
confirmed = asyncio.run(chain.observe_confirmations(wanted))
return apply_confirmations(confirmed, now) if confirmed else 0
+71 -2
View File
@@ -176,15 +176,20 @@ class ElectrumChain:
if not self.majority(await self._ask_others(lists_it)):
return False
return await self._proof_holds(active, entry.txid, entry.height)
async def _proof_holds(self, active: ElectrumClient, txid: str, height: int) -> bool:
"""ELC-26, TX-22: a header of the active server at `height` with valid work for the profile, and a merkle
proof from the others (by majority) that puts `txid` in that block."""
try:
header = await asyncio.wait_for(active.get_block_header(entry.height), ANSWER_TIMEOUT)
header = await asyncio.wait_for(active.get_block_header(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 proof_matches_header(txid, height, await client.get_merkle(txid, height), str(header))
return self.majority(await self._ask_others(proves_it))
@@ -197,6 +202,70 @@ class ElectrumChain:
return self.majority(await self._ask_others(lacks_it))
# -- confirmations and presence (TX-30, TX-33) ----------------------------------------------------------------
@staticmethod
async def _history(client: ElectrumClient, address: str) -> list[tuple[str, int]] | None:
try:
raw = await asyncio.wait_for(client.get_history(address_to_scripthash(address)), ANSWER_TIMEOUT)
except Exception as error:
logger.warning("history of %s failed: %s", address, error)
return None
try:
return [(str(item["tx_hash"]), int(item["height"])) for item in raw]
except (KeyError, TypeError, ValueError):
return None
async def observe_confirmations(self, wanted: list[tuple[int, str, frozenset[str]]]) -> dict[int, tuple[str, int]]:
"""`wanted` is `(row id, spending address, every txid of the row)`. Returns, per row, the version that is in a
block *and* proven (TX-30): `{row id: (txid, height)}`. An address that cannot be read blocks nobody else."""
active = await self._connect_active()
if active is None:
return {}
try:
histories: dict[str, list[tuple[str, int]] | None] = {}
confirmed: dict[int, tuple[str, int]] = {}
for row_id, address, txids in wanted:
if address not in histories:
histories[address] = await self._history(active, address)
history = histories[address]
if history is None:
continue
for txid, height in history:
if txid in txids and height > 0 and await self._proof_holds(active, txid, height):
confirmed[row_id] = (txid, height)
break
return confirmed
except Exception:
logger.exception("confirmation poll failed")
return {}
finally:
await active.close()
async def versions_known(self, address: str, txids: frozenset[str]) -> tuple[set[str], bool]:
"""TX-33: which of `txids` any server of the network has seen (mempool or block), and whether the network
answered enough for the *absence* of the rest to mean something (the active server and the quorum)."""
active = await self._connect_active()
if active is None:
return set(), False
try:
mine = await self._history(active, address)
async def theirs(client: ElectrumClient):
history = await self._history(client, address)
return None if history is None else {txid for txid, _ in history if txid in txids}
others = await self._ask_others(theirs)
known = ({txid for txid, _ in mine if txid in txids} if mine is not None else set())
for answer in others:
if answer:
known |= answer
# an absence is a statement only if the active server answered and the others agree among themselves
complete = mine is not None and self.majority([a is not None for a in others])
return known, complete
finally:
await active.close()
# -- broadcast (BET-32) -----------------------------------------------------------------------------------
async def transaction_known(self, active: ElectrumClient, txid: str) -> bool | None:
@@ -42,13 +42,18 @@ def process_chain_bets() -> None:
"""BET-31/32: sign what the web admitted, send what was signed. On a real ledger only."""
from django.conf import settings
from apps.lottery import bets
from apps.lottery import bets, confirmation, rbf, reconcile
from apps.lottery.electrum_chain import ElectrumChain
chain = ElectrumChain(settings.ELECTRUM_ENDPOINTS, settings.PLM_PROFILE, settings.ELECTRUM_ALLOW_NO_QUORUM)
done = bets.process_bets(chain)
if any(done.values()):
logger.info("bets: %s", done)
confirmed = confirmation.poll_confirmations(chain) # B7: TX-30
bumped = rbf.bump_due(chain) # TX-32
reconciled = reconcile.reconcile_once(chain) # TX-33
if confirmed or bumped or any(reconciled.values()):
logger.info("transactions: confirmed=%s bumped=%s reconciled=%s", confirmed, bumped, reconciled)
def tick() -> None:
@@ -0,0 +1,37 @@
# Generated by Django 5.2.19 on 2026-11-16 15:20
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('lottery', '0007_fee_rate'),
]
operations = [
migrations.AddField(
model_name='chaintransaction',
name='attempt_count',
field=models.PositiveSmallIntegerField(default=1),
),
migrations.AddField(
model_name='chaintransaction',
name='fee_rate_sat_vb',
field=models.PositiveIntegerField(blank=True, null=True),
),
migrations.AddField(
model_name='chaintransaction',
name='last_broadcast_at',
field=models.DateTimeField(blank=True, null=True),
),
migrations.AddField(
model_name='lotteryconfig',
name='rbf_timeout_seconds',
field=models.PositiveIntegerField(default=900),
),
migrations.AddConstraint(
model_name='lotteryconfig',
constraint=models.CheckConstraint(condition=models.Q(('rbf_timeout_seconds__gte', 60), ('rbf_timeout_seconds__lte', 86400)), name='lottery_config_rbf_timeout_range'),
),
]
+9
View File
@@ -37,6 +37,8 @@ class LotteryConfig(models.Model):
max_round_pool_sats = models.BigIntegerField(default=0) # 0 = no cap
# Network fee of the transactions built from now on, sat/vB (BET-04); a transaction in flight keeps its own.
fee_rate_sat_vb = models.PositiveIntegerField(default=1)
# TX-32: how long a pending transaction waits before it is replaced with a higher fee.
rbf_timeout_seconds = models.PositiveIntegerField(default=900)
# ADR-57: three distinct commands.
pause_after_round = models.BooleanField(default=False)
@@ -72,6 +74,9 @@ class LotteryConfig(models.Model):
models.CheckConstraint(
condition=Q(fee_rate_sat_vb__gte=1, fee_rate_sat_vb__lte=5000), name="lottery_config_fee_rate_range"
),
models.CheckConstraint(
condition=Q(rbf_timeout_seconds__gte=60, rbf_timeout_seconds__lte=86400), name="lottery_config_rbf_timeout_range"
),
]
@classmethod
@@ -245,6 +250,10 @@ class ChainTransaction(models.Model):
confirmed_at = models.DateTimeField(null=True, blank=True)
failed_at = models.DateTimeField(null=True, blank=True)
failure_reason = models.TextField(blank=True, default="")
# DAT-85: the current version's rate, the last send (RBF moves it; broadcast_at stays the first) and the tries.
fee_rate_sat_vb = models.PositiveIntegerField(null=True, blank=True)
last_broadcast_at = models.DateTimeField(null=True, blank=True)
attempt_count = models.PositiveSmallIntegerField(default=1)
class Meta:
indexes = [models.Index(fields=["status"])]
+160
View File
@@ -0,0 +1,160 @@
"""Replace-by-fee for the platform's transactions (roadmap B7, TX-32, TX-10..TX-13, TX-24).
Same coins, same outputs to the counterpart; the increase comes out of one output only, the player's change. The
replacement is signed and **recorded as a version before it is sent**; after the send (accepted or uncertain) the row
moves to it with an update that matches only if the row is still `pending` and still on the txid that was replaced.
"""
import asyncio
import logging
from datetime import datetime, timedelta
from django.db import transaction
from django.utils import timezone
from embit import script
from embit.finalizer import finalize_psbt
from embit.psbt import PSBT
from embit.transaction import Transaction, TransactionInput, TransactionOutput
from plm_engine import hd
from plm_engine.psbt_builder import DUST_LIMIT_SATS, MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
from . import audit, keys
from .chain import register_version
from .electrum_chain import Outcome
from .models import AuditEntry, ChainTransaction, DepositAddress, LotteryConfig, Participation
logger = logging.getLogger(__name__)
WORKER = "worker"
FEE_RATE_INCREMENT = 1 # sat/vB more than the recorded rate, per bump (TX-10)
INCREMENTAL_RELAY_FEE_RATE = 1 # BIP125 rule 4, sat/vB
REASON_MAX_RATE = "max_fee_rate"
REASON_NO_CHANGE = "no_change_output"
REASON_REFUSED = "replacement_refused"
class RbfError(Exception):
def __init__(self, message: str, reason: str):
super().__init__(message)
self.reason = reason
def due(now: datetime | None = None) -> list[ChainTransaction]:
"""TX-32: pending bets whose last send is older than the timeout."""
now = now or timezone.now()
limit = now - timedelta(seconds=LotteryConfig.get().rbf_timeout_seconds)
rows = ChainTransaction.objects.filter(kind=ChainTransaction.Kind.BET, status=ChainTransaction.Status.PENDING)
return [t for t in rows.order_by("id") if (t.last_broadcast_at or t.broadcast_at or t.created_at) <= limit]
def _build_replacement(tx: ChainTransaction, account) -> tuple[str, str, int, int]:
"""Phase 2, no network and no open transaction: the signed replacement. Returns `(txid, raw hex, new rate, vsize)`."""
if (tx.fee_rate_sat_vb or 1) >= MAX_FEE_RATE_SAT_VB:
raise RbfError(f"already at the maximum fee rate ({MAX_FEE_RATE_SAT_VB} sat/vB)", REASON_MAX_RATE)
owner = DepositAddress.objects.get(user=tx.user)
key = hd.user_key(account, owner.derivation_index)
own_script = script.p2wpkh(key.to_public())
old = Transaction.parse(bytes.fromhex(tx.raw_hex))
amounts = {(u.txid, u.vout): u.amount_sats for u in tx.reserved_utxos.all()}
input_amounts = [amounts[(v.txid.hex(), v.vout)] for v in old.vin]
old_fee = sum(input_amounts) - sum(o.value for o in old.vout)
vsize = estimate_vsize(len(old.vin), len(old.vout))
rate = tx.fee_rate_sat_vb or 1
target_rate = min(rate + FEE_RATE_INCREMENT, MAX_FEE_RATE_SAT_VB)
min_delta = vsize * INCREMENTAL_RELAY_FEE_RATE # BIP125: never below this, whatever the target says
delta = max(vsize * target_rate - old_fee, min_delta)
change = next((i for i, o in enumerate(old.vout) if o.script_pubkey.data == own_script.data), None)
if change is None:
raise RbfError("there is no change output to take the increase from", REASON_NO_CHANGE)
available = old.vout[change].value
if available < min_delta:
raise RbfError(f"its change ({available} sat) cannot cover the minimum increase ({min_delta} sat)", REASON_NO_CHANGE)
outputs = list(old.vout)
if available - delta >= DUST_LIMIT_SATS:
outputs[change] = TransactionOutput(available - delta, outputs[change].script_pubkey)
else: # TX-11: nothing relayable would be left, so the output goes to the fee and this is the last replacement
del outputs[change]
delta = available
new = Transaction(vin=[TransactionInput(v.txid, v.vout, sequence=RBF_SEQUENCE) for v in old.vin], vout=outputs)
psbt = PSBT(new)
for i, amount in enumerate(input_amounts):
psbt.inputs[i].witness_utxo = TransactionOutput(amount, own_script)
if psbt.sign_with(key) != len(old.vin):
raise RuntimeError("the replacement was not signed on every input")
final = finalize_psbt(psbt)
if final is None:
raise RuntimeError("failed to finalize the replacement")
new_rate = (old_fee + delta) // estimate_vsize(len(old.vin), len(outputs))
return final.txid().hex(), final.serialize().hex(), new_rate, vsize
def _record_failure(tx: ChainTransaction, reason: str, message: str) -> None:
"""TX-24: once per (txid, reason); the log carries every repeat."""
seen = AuditEntry.objects.filter(action="rbf_bump_failed", subject_id=str(tx.pk)).values_list("payload", flat=True)
if any(p.get("txid") == tx.current_txid and p.get("reason") == reason for p in seen):
logger.info("bump of transaction %s failed again (%s): %s", tx.pk, reason, message)
return
audit.record("rbf_bump_failed", actor_label=WORKER, subject_type="chain_transaction", subject_id=tx.pk,
outcome=AuditEntry.Outcome.ERROR, reason=message,
payload={"txid": tx.current_txid, "reason": reason})
def bump(tx_id: int, chain, now: datetime | None = None) -> str | None:
"""Accelerate one transaction. Returns the new txid, or None if there was nothing to do (not pending any more, a
conflict, or an impossible/refused bump, which is recorded)."""
now = now or timezone.now()
tx = ChainTransaction.objects.select_related("user").filter(pk=tx_id).first()
if tx is None or tx.status != ChainTransaction.Status.PENDING:
return None
try:
account = keys.signing_account_key()
new_txid, raw_hex, new_rate, _ = _build_replacement(tx, account)
except RbfError as error:
_record_failure(tx, error.reason, str(error))
return None
except keys.SigningKeyUnavailable as error:
logger.error("cannot bump transaction %s: %s", tx_id, error)
return None
old_txid = tx.current_txid
with transaction.atomic(): # the candidate is recorded before it is sent (TX-12)
fresh = ChainTransaction.objects.select_for_update().get(pk=tx_id)
if fresh.status != ChainTransaction.Status.PENDING or fresh.current_txid != old_txid:
return None
from .models import TransactionVersion
if not TransactionVersion.objects.filter(txid=new_txid).exists():
TransactionVersion.objects.create(transaction=fresh, txid=new_txid, raw_hex=raw_hex)
verdict = asyncio.run(chain.broadcast(raw_hex, new_txid))
if verdict.outcome is Outcome.REFUSED: # the candidate stays recorded; nobody will confirm it (TX-24)
_record_failure(tx, REASON_REFUSED, f"the network refused the replacement: {verdict.reason}")
return None
with transaction.atomic(): # TX-12: move the row, only if it is still exactly what was replaced
moved = ChainTransaction.objects.filter(
pk=tx_id, status=ChainTransaction.Status.PENDING, current_txid=old_txid
).update(current_txid=new_txid, raw_hex=raw_hex, fee_rate_sat_vb=new_rate, last_broadcast_at=now,
attempt_count=tx.attempt_count + 1)
if not moved: # TX-13: it changed under us; the candidate stays and confirmation looks for it anyway
logger.warning("transaction %s changed while its replacement was being sent: conflict", tx_id)
return None
Participation.objects.filter(movements__chain_transaction_id=tx_id, bet_txid=old_txid).update(bet_txid=new_txid)
audit.record("rbf_bumped", actor_label=WORKER, subject_type="chain_transaction", subject_id=tx_id,
payload={"from": old_txid, "to": new_txid, "fee_rate_sat_vb": new_rate,
"network": verdict.outcome.value})
return new_txid
def bump_due(chain, now: datetime | None = None) -> int:
"""TX-32: accelerate every transaction that waited too long. An error on one row stops no other."""
count = 0
for tx in due(now):
try:
if bump(tx.pk, chain, now):
count += 1
except Exception:
logger.exception("bumping transaction %s failed", tx.pk)
return count
+125
View File
@@ -0,0 +1,125 @@
"""Reconciling what the database believes with what the network knows (roadmap B7, TX-33, TX-15..TX-17, TX-23, TX-26).
A row is only ever given up on proof (ADR-51): a refusal of the newest version for missing or already spent inputs
while no server knows any version of it. A timeout, silence or a refusal for the fee is never a proof. The second
proof of TX-17 (an input spent in a block by another transaction) arrives with the reorg work of B10.
"""
import asyncio
import logging
from datetime import datetime, timedelta
from django.db import transaction
from django.utils import timezone
from . import audit
from .bets import WORKER, _fail
from .confirmation import apply_confirmations, spending_address
from .electrum_chain import Outcome
from .models import ChainTransaction, LotteryConfig
logger = logging.getLogger(__name__)
GRACE_BUILDING = timedelta(seconds=120)
GRACE_PENDING = timedelta(hours=6)
FAILED_WATCH = timedelta(days=14)
# Wordings by which a node says the inputs are not there to spend. Anything else is not a proof (TX-17).
_MISSING_INPUTS = ("missing-inputs", "missing inputs", "missingorspent", "already spent")
def is_missing_inputs(reason: str) -> bool:
lowered = reason.lower()
return any(marker in lowered for marker in _MISSING_INPUTS)
def _is_due(tx: ChainTransaction, now: datetime) -> bool:
if tx.status == ChainTransaction.Status.BUILDING:
return tx.current_txid is not None and now - tx.created_at >= GRACE_BUILDING
return now - (tx.broadcast_at or tx.created_at) >= GRACE_PENDING
def _promote(tx_id: int, now: datetime, txid: str) -> bool:
"""TX-16: the network has it. A `building` row becomes `pending` (so confirmation and RBF can take over)."""
with transaction.atomic():
fresh = ChainTransaction.objects.select_for_update().get(pk=tx_id)
if fresh.status != ChainTransaction.Status.BUILDING or fresh.current_txid != txid: # TX-26
return False
fresh.status, fresh.broadcast_at, fresh.last_broadcast_at = ChainTransaction.Status.PENDING, now, now
fresh.save(update_fields=["status", "broadcast_at", "last_broadcast_at"])
audit.record("pending_tx_recovered", actor_label=WORKER, subject_type="chain_transaction", subject_id=fresh.pk,
payload={"txid": txid})
return True
def reconcile_once(chain, now: datetime | None = None) -> dict[str, int]:
now = now or timezone.now()
done = {"recovered": 0, "abandoned": 0, "resurrected": 0}
rows = ChainTransaction.objects.filter(
status__in=[ChainTransaction.Status.BUILDING, ChainTransaction.Status.PENDING]
).select_related("round").order_by("id")
for tx in rows:
if not _is_due(tx, now):
continue
try:
_reconcile_row(tx, chain, now, done)
except Exception:
logger.exception("reconciling transaction %s failed", tx.pk)
_watch_failed(chain, now, done)
return done
def _reconcile_row(tx: ChainTransaction, chain, now: datetime, done: dict[str, int]) -> None:
address = spending_address(tx)
txids = frozenset(tx.versions.values_list("txid", flat=True))
if not address or not txids:
return
known, complete = asyncio.run(chain.versions_known(address, txids))
if known: # TX-15: at least one server has at least one version: it is alive
if _promote(tx.pk, now, tx.current_txid):
done["recovered"] += 1
return
if not complete or not tx.raw_hex: # an unreadable network proves nothing
return
verdict = asyncio.run(chain.broadcast(tx.raw_hex, tx.current_txid))
if verdict.outcome is Outcome.ACCEPTED:
if _promote(tx.pk, now, tx.current_txid):
done["recovered"] += 1
elif verdict.outcome is Outcome.REFUSED:
if is_missing_inputs(verdict.reason): # TX-17, proof 2
_fail(tx, f"abandoned: {verdict.reason}", release=True, action="tx_abandoned")
done["abandoned"] += 1
elif _promote(tx.pk, now, tx.current_txid): # refused for the fee: not a proof; let RBF accelerate it
done["recovered"] += 1
def _watch_failed(chain, now: datetime, done: dict[str, int]) -> None:
"""TX-23: a transaction given up for dead can still confirm. If one does, say it once and stop new bets."""
rows = ChainTransaction.objects.filter(
status=ChainTransaction.Status.FAILED, failed_at__gte=now - FAILED_WATCH
).select_related("round")
wanted = []
for tx in rows:
if audit_exists("tx_resurrected", tx.pk):
continue
address, txids = spending_address(tx), frozenset(tx.versions.values_list("txid", flat=True))
if address and txids:
wanted.append((tx.pk, address, txids))
if not wanted:
return
for tx_id, (txid, height) in asyncio.run(chain.observe_confirmations(wanted)).items():
with transaction.atomic():
if audit_exists("tx_resurrected", tx_id):
continue
audit.record("tx_resurrected", actor_label=WORKER, subject_type="chain_transaction", subject_id=tx_id,
outcome="error", payload={"txid": txid, "height": height})
LotteryConfig.objects.filter(pk=1).update(new_bets_suspended=True) # the operator puts things in order
done["resurrected"] += 1
def audit_exists(action: str, subject_id: int) -> bool:
from .models import AuditEntry
return AuditEntry.objects.filter(action=action, subject_id=str(subject_id)).exists()
__all__ = ["apply_confirmations", "is_missing_inputs", "reconcile_once"]