contracts: bound chklocks' sweep (epoch-stall risk) + materialize the per-bucket locked total

contracts/sysio.epoch/src/sysio.epoch.cpp

@@ -4,8 +4,9 @@
 #include <sysio.opp.common/opp_keys.hpp>
 #include <sysio.authex/sysio.authex.hpp>
 #include <sysio.token/sysio.token.hpp>
-// For uwrit::MAX_UWREQ_PRUNE_PER_EPOCH — the per-epoch budget advance hands
-// to the inline `pruneuwreqs` sweep (the constant is owned by sysio.uwrit).
+// For uwrit::MAX_LOCK_RELEASE_PER_EPOCH and uwrit::MAX_UWREQ_PRUNE_PER_EPOCH —
+// the per-epoch budgets advance hands to the inline `chklocks` and
+// `pruneuwreqs` sweeps (both constants are owned by sysio.uwrit).
 #include <sysio.uwrit/sysio.uwrit.hpp>
 // Canonical sysio.system emissions types + compute_epoch_emission. The
 // [[sysio::contract("sysio.system")]] attribute on emission_config / t5_state
@@ -359,7 +360,7 @@ void epoch::advance() {
       permission_level{get_self(), "owner"_n},
       UWRIT_ACCOUNT,
       "chklocks"_n,
-      std::make_tuple()
+      std::make_tuple(uwrit::MAX_LOCK_RELEASE_PER_EPOCH)
    ).send();
 
    // Bounded UWREQ lifecycle sweep (SEC-129 / WSA-223): erase terminal

contracts/sysio.opreg/src/sysio.opreg.cpp

@@ -345,28 +345,23 @@ void opreg::regoperator(name account,
 
 namespace {
 
-/// Sum the active locks on `sysio.uwrit::locks` for a given (op, chain, token).
-/// Returns 0 if uwrit's locks table is empty or if the operator has no locks
-/// on that chain/token.
+/// The active lock total on `sysio.uwrit` for a given (op, chain, token) —
+/// an O(1) read of uwrit's `locksums` rollup. Returns 0 when the operator
+/// holds no live locks on that chain/token (the rollup erases a bucket's row
+/// once it empties, so an absent row IS zero).
 ///
-/// Per v6 plan §B.2 (split-index design): `sysio.uwrit::locks_t` exposes only
-/// uint64 secondary indexes. The `byuw` index keys on `underwriter.value`;
-/// rows are filtered on `(chain_code, token_code)` in memory. Per-underwriter
-/// lock counts are O(1)-ish in steady state so the scan is cheap.
+/// This used to scan `sysio.uwrit::locks` through its `byuw` index and filter
+/// `(chain_code, token_code)` in memory, on the stated assumption that
+/// per-underwriter lock counts are "O(1)-ish in steady state so the scan is
+/// cheap". That assumption does not hold: uwrit locks are held for the full
+/// wall-clock challenge window and are never released by delivery, so a
+/// bucket's live lock count is (settlement rate × lock duration). uwrit now
+/// maintains the total at the two sites that can change it; see
+/// `uwrit::lock_sum`.
 uint64_t sum_locks_inline(name account, sysio::slug_name chain_code, sysio::slug_name token_code) {
-   uwrit::locks_t locks(opreg::UWRIT_ACCOUNT);
-   auto idx = locks.template get_index<"byuw"_n>();
-
-   uint64_t total = 0;
-   auto it  = idx.lower_bound(account.value);
-   auto end = idx.upper_bound(account.value);
-   for (; it != end; ++it) {
-      if (it->chain_code != chain_code || it->token_code != token_code) continue;
-      // Saturating: amounts are uncapped uint64 (external-chain values); a
-      // wrapped subtotal would understate `reserved` and overstate availability.
-      total = opp::safe::add_sat_u64(total, it->amount);
-   }
-   return total;
+   uwrit::locksums_t sums(opreg::UWRIT_ACCOUNT);
+   uwrit::lock_sum_key pk{account, chain_code, token_code};
+   return sums.contains(pk) ? sums.get(pk).amount : 0;
 }
 
 /// Sum the pending (not-yet-flushed) withdraws on this contract for a given

contracts/sysio.uwrit/README.md

@@ -64,7 +64,8 @@ chain deregistered) refund in full.
 |-------|----------|-------------|
 | `uwconfig` | `uw_config` | Singleton: `fee_bps`, `collateral_lock_duration_ms`, `min_fromwire_amount`, `fromwire_revert_fee_bps`, `uwreq_pending_timeout_epochs`, `uwreq_retention_epochs` |
 | `uwreqs` | `uw_request_t` | One row per swap intent — race state in `commits_by`, `winner`, lifecycle status, mirrored `variance_tolerance_bps`. Retained for `uwreq_retention_epochs` after ANY terminal transition — `COMPLETED` (after `chklocks` sweeps the final collateral lock; the reserve settlement itself already happened at winner selection, which is what made the row CONFIRMED), `REJECTED` (immediate failure via `reject_and_refund`), or `EXPIRED` (pending timeout, same path) — then erased by `pruneuwreqs` |
-| `locks` | `lock_entry` | Flat per-leg lock vector consulted by `sysio.opreg::available()`. The `byexpire` secondary index lets `chklocks` sweep expired locks in one pass |
+| `locks` | `lock_entry` | Flat per-leg lock vector consulted by `sysio.opreg::available()`. The `byexpire` secondary index lets `chklocks` sweep expired locks oldest-first, up to its per-epoch budget |
+| `locksums` | `lock_sum` | Materialized Σ `lock_entry.amount` per `(underwriter, chain_code, token_code)` bucket — the "locked" half of `sysio.opreg::available()`, read O(1) instead of scanning `locks`. Written by exactly three paths, all in this contract: `try_select_winner` ADDS (on a win), `chklocks` DECREMENTS (healthy release at expiry), and `sweeplocks` DECREMENTS (erasing a commitment's held locks on an UPHELD challenge). A bucket's row is erased once its total reaches zero, so an absent row reads as zero. Any new erase path must decrement too — the rollup is authoritative for `available()`, so a bucket left positive after its last row is gone suppresses that collateral permanently |
 | `fwqueue` | `fromwire_q` | Escrowed swap-from-WIRE requests awaiting drain. `byepoch` secondary index |
 | `uwcounters` | `uw_counters` | Monotonic id allocators (uwreq ids, lock ids) |
 
@@ -77,8 +78,11 @@ chain deregistered) refund in full.
 | `rcrdcommit` | `sysio.msgch` | Record an underwriter's per-leg `UNDERWRITE_INTENT_COMMIT` bytes; resolves the race once both legs are present |
 | `swapfromwire` | `user` | Escrow WIRE and enqueue a swap-FROM-WIRE request |
 | `drainfwq` | `sysio.epoch` or self | Drain the from-WIRE queue: settle what prices, revert the rest (charging the revert fee on caller-fault causes) |
-| `chklocks` | `sysio.epoch` or self | Sweep collateral locks whose wall-clock window has expired |
+| `chklocks` | `sysio.epoch` or self | Sweep collateral locks whose wall-clock window has expired, oldest-first, at most `max_rows` per call (`advance` passes `MAX_LOCK_RELEASE_PER_EPOCH`); an oversized expiry burst drains across later epochs rather than aborting `advance` |
 | `pruneuwreqs` | `sysio.epoch` or self | Expire timed-out PENDING uwreqs and erase terminal rows past their retention window |
+| `holdlocks` | `sysio.chalg` | Mark a commitment's winning locks as held by an OPEN underwriter-fault challenge (WIRE-297); held locks are skipped by `chklocks` instead of released |
+| `freelocks` | `sysio.chalg` | Clear the hold after a REJECTED or LAPSED challenge, so the next `chklocks` releases the locks normally |
+| `sweeplocks` | `sysio.chalg` | Erase a commitment's held locks after an UPHELD challenge — the underwriter is already SLASHED, so each `releaselock` takes its deferred-slash branch. Decrements `locksums` like `chklocks` does |
 | `sumlocks` | read-only | Sum an underwriter's active locks for a `(chain, token)` bucket — the lock half of `sysio.opreg::available()` |
 
 ## Dependencies

contracts/sysio.uwrit/include/sysio.uwrit/sysio.uwrit.hpp

@@ -107,6 +107,28 @@ namespace sysio {
       // subsequent epochs.
       static constexpr uint32_t MAX_UWREQ_PRUNE_PER_EPOCH = 32;
 
+      // Locks `sysio.epoch::advance` passes to `chklocks` each epoch. Sized
+      // like MAX_UWREQ_PRUNE_PER_EPOCH / MAX_FWQ_DRAIN_PER_EPOCH, and for the
+      // same reason — but the exposure here is sharper than either, because
+      // lock EXPIRY is inherently bursty. Every lock is stamped
+      // `now + collateral_lock_duration_ms` at creation, so a burst of
+      // settlements inside one epoch produces a burst of expiries inside one
+      // epoch, exactly one lock-duration later. Sustained swap traffic
+      // therefore presents `chklocks` with a whole epoch's settlements at
+      // once, and per expired lock the sweep does an inline
+      // `opreg::releaselock` dispatch plus an erase — all inside advance's
+      // hard, uncatchable transaction CPU deadline.
+      //
+      // Unbounded, a large enough expiry burst aborts `advance`; and because
+      // those same locks are still expired at the next advance, it aborts
+      // identically every epoch thereafter — a PERMANENT chain-wide epoch
+      // stall rather than a transient one. Bounded, an oversized burst is
+      // just release latency that drains across subsequent epochs, which is
+      // harmless: the challenge window has already closed, so a lock freed an
+      // epoch or two late costs only a brief overstatement of the
+      // underwriter's reserved collateral.
+      static constexpr uint32_t MAX_LOCK_RELEASE_PER_EPOCH = 32;
+
       // ── UWREQ row-growth rails (SEC-129 / WSA-223) ─────────────────────────
       // Every uwreqs `modify` re-serializes the whole row inside the
       // never-throw evalcons / advance dispatch surfaces, so per-field byte
@@ -344,8 +366,11 @@ namespace sysio {
       /// (delivery itself is implicit — there is no SWAP_REMIT ack; the
       /// lock window expiring IS the settlement horizon).
       ///
-      /// This sweep is the ONLY lock-release path: locks are a wall-clock
-      /// challenge window (12h default) and are never released by delivery.
+      /// This sweep is the only HEALTHY lock-release path: locks are a
+      /// wall-clock challenge window (12h default) and are never released by
+      /// delivery. It is not the only path that ERASES a lock — `sweeplocks`
+      /// does too, on an UPHELD challenge (see `lock_sum`, whose rollup both
+      /// must maintain).
       ///
       /// EXCEPTION (WIRE-297): a lock whose `challenge_id` is non-zero — an
       /// underwriter-fault challenge is OPEN against its commitment — is NOT
@@ -354,8 +379,34 @@ namespace sysio {
       /// with the underwriter slashed (`sweeplocks`) or clears the hold
       /// (`freelocks`) so the NEXT sweep releases them normally. The epoch
       /// tick is thereby the challenge system's only cadence.
+      ///
+      /// Budget-bounded, mirroring `pruneuwreqs` / `drainfwq`: walks the
+      /// `byexpire` index in ascending `expires_at_ms` and EXAMINES at most
+      /// `max_rows` rows (`max_rows == 0` is a no-op). Inlined from
+      /// `sysio.epoch::advance` with `MAX_LOCK_RELEASE_PER_EPOCH`; also
+      /// invocable by `sysio.uwrit` itself with a caller-chosen budget for a
+      /// manual backlog drain. NEVER throws past the auth gate: it runs inline
+      /// inside `advance`, where an abort stalls epoch progress chain-wide.
+      ///
+      /// The budget counts rows EXAMINED, not locks released — held locks and
+      /// the challenge pokes they generate cost real work too. Bounding only
+      /// releases would let an arbitrary number of held rows be scanned and an
+      /// arbitrary number of distinct challenges fan out an inline
+      /// `chkuwchal` each, which is exactly the unbounded `advance` work this
+      /// bound exists to remove. `open_challenges` is therefore bounded by
+      /// `max_rows` as a consequence of the same counter.
+      ///
+      /// Ascending-expiry order makes the bound a FIFO drain, so an oversized
+      /// burst simply spreads across subsequent epochs. Held locks are the one
+      /// thing that can sit at the head of that queue without leaving it: they
+      /// are skipped, not erased, so while more than `max_rows` challenges are
+      /// open the rows behind them wait. That is bounded and self-clearing
+      /// rather than a stall — each sweep pokes the challenges it can see, and
+      /// a resolved challenge removes its locks (`sweeplocks`) or clears their
+      /// hold (`freelocks`), letting the window advance on the next tick.
+
       [[sysio::action]]
-      void chklocks();
+      void chklocks(uint32_t max_rows);
 
       /// Mark the winning underwriter's locks for `uwreq_id` as held by the OPEN underwriter-
       /// fault challenge `chal_id` (WIRE-297). Auth: `sysio.chalg`, inlined from `openuwchal`.
@@ -489,6 +540,30 @@ namespace sysio {
       /// a slash, the outpost routes seized collateral to that reserve via
       /// `ReserveAmount`, even when multiple reserves exist for the same
       /// `(chain_code, token_code)` pair.
+      /// The `(account, chain_code, token_code)` collateral-bucket digest:
+      /// the three uint64 identities packed little-endian into 24 bytes and
+      /// hashed. 3 × uint64 = 192 bits does not fit `uint128_t`, so the triple
+      /// is hashed to land in a `checksum256`.
+      ///
+      /// SINGLE SOURCE for that encoding, and it must stay that way.
+      /// `lock_entry::by_underwriter_ck()` says which bucket a lock row
+      /// belongs to; `lock_sum_key::primary_key()` addresses that bucket's
+      /// materialized total. If the two derivations ever diverged, the rollup
+      /// would be keyed differently from the rows it summarizes and every
+      /// reader would silently observe zero locked — collateral already
+      /// committed to a live lock would look spendable. Both call this, so
+      /// they cannot diverge.
+      static checksum256 compose_account_chain_token_ck(name account,
+                                                        sysio::slug_name chain_code,
+                                                        sysio::slug_name token_code) {
+         std::array<uint8_t, 24> buf{};
+         uint64_t acc_v = account.value;
+         std::memcpy(buf.data() +  0, &acc_v,             8);
+         std::memcpy(buf.data() +  8, &chain_code.value,  8);
+         std::memcpy(buf.data() + 16, &token_code.value,  8);
+         return sysio::sha256(reinterpret_cast<const char*>(buf.data()), buf.size());
+      }
+
       struct lock_key {
          uint64_t lock_id;
          uint64_t primary_key() const { return lock_id; }
@@ -511,17 +586,11 @@ namespace sysio {
          /// `byexpire` so `chklocks` sweeps expired locks in ascending order.
          uint64_t                expires_at_ms    = 0;
 
-         /// Composite checksum index for opreg's `available()` rollup:
-         /// `sha256(underwriter.value || chain_code.value || token_code.value)`
-         /// packed as 24 little-endian bytes. 3 × uint64 = 192 bits doesn't
-         /// fit `uint128_t`, so we hash the triple to land in `checksum256`.
+         /// Which collateral bucket this lock belongs to — see
+         /// `compose_account_chain_token_ck`, the single source of that
+         /// encoding, shared with `lock_sum_key::primary_key()`.
          checksum256 by_underwriter_ck() const {
-            std::array<uint8_t, 24> buf{};
-            uint64_t uw_v = underwriter.value;
-            std::memcpy(buf.data() +  0, &uw_v,             8);
-            std::memcpy(buf.data() +  8, &chain_code.value, 8);
-            std::memcpy(buf.data() + 16, &token_code.value, 8);
-            return sysio::sha256(reinterpret_cast<const char*>(buf.data()), buf.size());
+            return compose_account_chain_token_ck(underwriter, chain_code, token_code);
          }
          /// Non-zero while an underwriter-fault challenge (the `sysio.chalg::uwchals` row id) is
          /// OPEN against this lock's commitment (WIRE-297). A held lock is NOT released at
@@ -560,6 +629,72 @@ namespace sysio {
             sysio::const_mem_fun<lock_entry, uint64_t, &lock_entry::by_expires_at_ms>>
       >;
 
+      /// Primary key of `locksums`: one (underwriter, chain_code, token_code)
+      /// collateral bucket, addressed by the SAME digest
+      /// `lock_entry::by_underwriter_ck()` uses to say which bucket a lock row
+      /// belongs to — both call `compose_account_chain_token_ck`.
+      struct lock_sum_key {
+         name             underwriter;
+         sysio::slug_name chain_code;
+         sysio::slug_name token_code;
+         checksum256 primary_key() const {
+            return compose_account_chain_token_ck(underwriter, chain_code, token_code);
+         }
+         SYSLIB_SERIALIZE(lock_sum_key, (underwriter)(chain_code)(token_code))
+      };
+
+      /// Materialized Σ `lock_entry.amount` for one (underwriter, chain_code,
+      /// token_code) bucket — the "locked" half of `sysio.opreg::available()`.
+      ///
+      /// A CACHE of the `locks` table with exactly ONE writer: every code path
+      /// that can change a bucket's total lives in this contract. There are
+      /// THREE, and any new one inherits the same obligation — nothing
+      /// structural enforces it:
+      ///
+      ///   * `try_select_winner` — ADDS, one lock per required leg, on a win.
+      ///   * `chklocks`  — DECREMENTS, releasing locks at expiry.
+      ///   * `sweeplocks` — DECREMENTS, erasing the held locks of a commitment
+      ///     whose underwriter-fault challenge was UPHELD (WIRE-297). This one
+      ///     runs OUTSIDE `chklocks`, which is exactly why it was missed once:
+      ///     this block previously said `chklocks` was the sole erase path, and
+      ///     `sweeplocks` erased rows without decrementing.
+      ///
+      /// Getting that wrong is permanent and silent rather than merely stale:
+      /// the rollup is authoritative for `sysio.opreg::available()`, so a bucket
+      /// left positive after its last row is gone suppresses that collateral
+      /// forever — nothing decrements it again, because the rows that would
+      /// have are already erased.
+      ///
+      /// A row is erased when its total reaches zero, so an absent row reads as
+      /// zero and the table holds only live buckets.
+      ///
+      /// It exists because the derivation it replaces does not scale. Both
+      /// `sum_locks_inline` rollups (here and in sysio.opreg) previously
+      /// walked every lock row an underwriter held, each documenting the
+      /// assumption that "per-underwriter lock counts are O(1)-ish so the scan
+      /// is cheap". That is false under sustained swap traffic: locks are held
+      /// for the full wall-clock challenge window
+      /// (`collateral_lock_duration_ms`, 12h default) and are NEVER released
+      /// by delivery, so a bucket's live lock count is
+      /// (settlement rate × lock duration) — unbounded within the window. The
+      /// scan ran per candidate inside `try_select_winner` (up to
+      /// MAX_UWREQ_CANDIDATES of them per uwreq), i.e. inside the same
+      /// consensus-dispatch CPU budget whose overrun stalls the chain.
+      ///
+      /// `sumlocks` reads this rollup, so it stays the cheap external answer
+      /// to "how much of this bucket is locked"; the authoritative recompute
+      /// is the `locks` table itself, which the contract tests scan and
+      /// compare against this total.
+      struct [[sysio::table("locksums")]] lock_sum {
+         name             underwriter;
+         sysio::slug_name chain_code;
+         sysio::slug_name token_code;
+         uint64_t         amount = 0;
+         SYSLIB_SERIALIZE(lock_sum, (underwriter)(chain_code)(token_code)(amount))
+      };
+
+      using locksums_t = sysio::kv::table<"locksums"_n, lock_sum_key, lock_sum>;
+
       /// Per-underwriter race entry inside an UWREQ row. Tracks when each
       /// leg of a dual-COMMIT pair arrived so `try_select_winner` can
       /// resolve the race deterministically. Each leg's COMMIT is an