Meet BIP125's relay minimum on every RBF bump, and cap the fee rate (B-32)

bump_fee computed fee_delta as new_fee - old_fee, falling back to a
flat 1-satoshi bump whenever that came out zero or negative - which
happened whenever old_fee (the actual fee paid, from real prevout
amounts) already exceeded the naive target, e.g. because dust change
had been folded into the original fee (psbt_builder.py's
DUST_LIMIT_SATS handling). A 1-satoshi total increase is nowhere near
BIP125 rule 4's minimum (the replacement must pay at least the
incremental relay fee rate times its own vsize more than what it
replaces), so the node rejected it every time - and since bump_fee
raised before touching `pending`, the next tick retried with identical
parameters every 30 seconds, forever. Separately, the fee rate climbed
by 1 sat/vB every bump with no ceiling.

fee_delta is now max(target_fee - old_fee, vsize * the incremental
relay rate) - always at least the relay-mandated minimum regardless of
what the naive arithmetic produces. pending.fee_rate_sat_vb is set to
the actual resulting rate rather than the naive target, so a later
bump's arithmetic starts from what's really being paid instead of
drifting from it. Once a transaction reaches MAX_FEE_RATE_SAT_VB (a
new constant, 10,000 sat/vB, shared with RoundConfig.fee_rate_sat_vb's
existing admin-facing bound so the two can't drift apart - the same
reason MIN_PASSWORD_LENGTH is shared elsewhere) bump_fee refuses to
bump further; the reconciler abandons it if it never confirms (B-27)
instead of this retrying forever.

Suite grows from 185 to 187 tests. BUGS.md moves B-32 to Previously
fixed.

app/api/routes/admin.py

@@ -14,6 +14,7 @@ from app.db.session import get_session
 from app.rounds.config import get_round_config
 from app.wallet.address import is_valid_plm_address
 from app.wallet.hd import derive_user_wif
+from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB
 
 router = APIRouter(prefix="/admin", tags=["admin"])
 
@@ -68,7 +69,7 @@ class RoundConfigUpdate(BaseModel):
     bet_amount_sats: int | None = Field(default=None, gt=0, le=100_000 * 100_000_000)
     round_duration_seconds: int | None = Field(default=None, ge=30, le=7 * 24 * 3600)
     round_cooldown_seconds: int | None = Field(default=None, ge=0, le=24 * 3600)
-    fee_rate_sat_vb: int | None = Field(default=None, ge=1, le=10_000)
+    fee_rate_sat_vb: int | None = Field(default=None, ge=1, le=MAX_FEE_RATE_SAT_VB)
     rbf_timeout_seconds: int | None = Field(default=None, ge=60, le=7 * 24 * 3600)
     draw_animation_seconds: int | None = Field(default=None, ge=0, le=600)
 

app/tx/broadcast.py

@@ -14,12 +14,18 @@ from app.electrum.client import ElectrumClient
 from app.rounds.config import get_round_config
 from app.wallet.hd import derive_pool_key, derive_user_key
 from app.wallet.plm_network import PLM_MAINNET
-from app.wallet.psbt_builder import RBF_SEQUENCE, estimate_vsize
+from app.wallet.psbt_builder import MAX_FEE_RATE_SAT_VB, RBF_SEQUENCE, estimate_vsize
 
 logger = logging.getLogger(__name__)
 
 _POLL_INTERVAL_SECONDS = 30
-_FEE_RATE_INCREMENT = 1  # minimum relay-policy-friendly bump per BIP125
+_FEE_RATE_INCREMENT = 1  # how much pending.fee_rate_sat_vb's *target* rises by per bump
+
+# BIP125 rule 4: a replacement transaction must pay at least this much more, in
+# total, per vbyte of its own size, than the transaction it replaces — Bitcoin
+# Core's default incremental relay fee. bump_fee's delta must never fall below
+# this regardless of what the target-rate arithmetic comes out to (B-32).
+_INCREMENTAL_RELAY_FEE_RATE_SAT_VB = 1
 
 
 class RbfError(Exception):
@@ -79,20 +85,38 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
     tx's own sender address, large enough to absorb the increase. If there's no
     such output (e.g. an exact-amount bet with no change), this raises RbfError —
     bumping such a tx would require selecting additional inputs, which isn't
-    implemented for the MVP; it needs manual operator intervention.
+    implemented for the MVP; it needs manual operator intervention. Also raises
+    RbfError, rather than bumping, once `pending` is already at MAX_FEE_RATE_SAT_VB
+    (B-32) — the reconciler abandons it if it never confirms (B-27), instead of
+    this retrying an ever-higher fee forever.
     """
+    if pending.fee_rate_sat_vb >= MAX_FEE_RATE_SAT_VB:
+        raise RbfError(
+            f"pending_transaction {pending.id}: already at the maximum fee rate "
+            f"({MAX_FEE_RATE_SAT_VB} sat/vB) — refusing to bump further"
+        )
+
     old_tx = Transaction.parse(bytes.fromhex(pending.raw_tx_hex))
     signing_key, own_script, own_address = await _signing_context(session, pending)
 
     input_amounts = [await _prevout_amount(client, vin) for vin in old_tx.vin]
     total_in = sum(input_amounts)
     old_fee = total_in - sum(o.value for o in old_tx.vout)
+    vsize = estimate_vsize(len(old_tx.vin), len(old_tx.vout))
 
-    new_fee_rate = pending.fee_rate_sat_vb + _FEE_RATE_INCREMENT
-    new_fee = estimate_vsize(len(old_tx.vin), len(old_tx.vout)) * new_fee_rate
-    fee_delta = new_fee - old_fee
-    if fee_delta <= 0:
-        fee_delta = _FEE_RATE_INCREMENT  # already above the new target vsize*rate; bump by a token amount
+    target_fee_rate = min(pending.fee_rate_sat_vb + _FEE_RATE_INCREMENT, MAX_FEE_RATE_SAT_VB)
+    target_fee = vsize * target_fee_rate
+    # BIP125 rule 4's minimum, in absolute sats for this tx's size — the floor
+    # `fee_delta` must never go below, no matter what `target_fee - old_fee` comes
+    # out to. That naive difference used to go to zero or negative whenever
+    # old_fee already exceeded target_fee (e.g. a dust change amount folded into
+    # the original fee — wallet/psbt_builder.py's DUST_LIMIT_SATS handling), and
+    # the previous fallback — a flat 1-satoshi total bump — was nowhere near this
+    # relay-mandated minimum, so the node rejected it every time. Because bump_fee
+    # raised before touching `pending`, the next tick retried with identical
+    # parameters every 30 seconds, forever (B-32).
+    min_valid_delta = vsize * _INCREMENTAL_RELAY_FEE_RATE_SAT_VB
+    fee_delta = max(target_fee - old_fee, min_valid_delta)
 
     change_index = _find_change_output(old_tx, own_address)
     if change_index is None or old_tx.vout[change_index].value <= fee_delta:
@@ -124,7 +148,11 @@ async def bump_fee(session: AsyncSession, client: ElectrumClient, pending: Pendi
     pending.replaced_by_txid = old_txid  # points backwards: what current_txid replaced
     pending.current_txid = new_txid
     pending.raw_tx_hex = raw_hex
-    pending.fee_rate_sat_vb = new_fee_rate
+    # The *actual* resulting rate, not target_fee_rate: when the BIP125-minimum
+    # floor above raised fee_delta past the naive target, the tx now pays more
+    # than target_fee_rate implied. Recording the true rate keeps the next bump's
+    # arithmetic honest instead of drifting from what's really being paid.
+    pending.fee_rate_sat_vb = (old_fee + fee_delta) // vsize
     pending.attempt_count += 1
     # last_broadcast_at, not broadcast_at (B-27): broadcast_at must stay the *first*
     # broadcast, since reconcile.py's abandon-after-N-hours grace period is measured

app/wallet/psbt_builder.py

@@ -25,6 +25,14 @@ RBF_SEQUENCE = 0xFFFFFFFD
 # withdrawal fail at broadcast with an opaque error (B-06).
 DUST_LIMIT_SATS = 294
 
+# Sanity ceiling on any transaction's fee rate — shared by RoundConfig.fee_rate_sat_vb's
+# admin-facing bound (app/api/routes/admin.py, so the two can't drift apart, the same
+# reason MIN_PASSWORD_LENGTH is shared in auth/security.py) and tx/broadcast.py's RBF
+# bump escalation, which refuses to bump a pending_transaction past this rate (B-32) —
+# without a ceiling, a stuck transaction's fee climbed by 1 sat/vB every bump forever,
+# eating further and further into the sender's change with no limit.
+MAX_FEE_RATE_SAT_VB = 10_000
+
 
 class InsufficientFundsError(Exception):
     """`code` is the machine-readable identifier the API layer forwards to the