@venusprotocol/liquidity-hub 2.1.0-dev.4 → 2.1.0-dev.6

package/contracts/lens/HubCapacityMath.sol

@@ -0,0 +1,610 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.25;
+
+/**
+ * @title HubCapacityMath
+ * @author Venus
+ * @notice Aggregate deposit capacity for a {Hub}, solved against the post-deposit TVL.
+ * @dev Pure arithmetic over values already in memory. It never reads a Hub — {HubLens} gathers the
+ *      inputs and hands them over — so a test can drive it with cap books a live Hub would refuse to
+ *      accept (`absoluteCap == type(uint256).max`, `percentageCapBps > 10_000`) and still reach the
+ *      saturation and overflow guards.
+ *
+ *      A YieldGroup's cap is `min(absoluteCap, pctBps × TVL / 10_000)`, so a deposit lifts the very
+ *      caps it is measured against. This library finds the largest TVL every cap still admits, and
+ *      returns the distance from today's TVL to it.
+ *
+ *      Write `X` for the post-deposit TVL and, for each YieldGroup `i` in {GroupInput}, `bal_i` for
+ *      what it holds today, `absBound_i` for the most it could ever hold, and `pct_i` for its
+ *      percentage cap. What it holds once TVL is `X` is
+ *
+ *          hold_i(X) = max(bal_i, min(absBound_i, pct_i × X / 10_000))
+ *
+ *      Writing `C` for the assets that cannot move — Hub idle, paused YieldGroups, YieldGroups off
+ *      the deposit queue, any whose views revert — the answer is the largest `X` satisfying
+ *      `X ≤ C + Σ hold_i(X)`, less `hubTotalAssets`. Derivation and worked example are in the
+ *      README, under Cap enforcement.
+ *
+ *      Each `hold_i` is flat, then sloped, then flat, with a breakpoint at each turn:
+ *
+ *          hold_i
+ *            ^
+ *            |                        +-----------  absBound_i   absolute bound binds
+ *            |                       /
+ *            |                      /               percentage cap binds, slope pct_i
+ *            |        +------------+                bal_i        balance floor binds
+ *            +--------+------------+-------------->  TVL (X)
+ *                  breakLow_i   breakHigh_i
+ *
+ *      Summed over the queue, the corners are every YieldGroup's breakpoints together. Between two
+ *      adjacent corners no YieldGroup changes which bound it sits on, so the sum is
+ *      `base + slope × X / 10_000` there and crosses in closed form. {_solveCeiling} sorts the
+ *      corners, solves each segment, and keeps the largest crossing that lands inside its own one.
+ *
+ *      Never over-reports: the flooring the cascade does per YieldGroup is pre-paid off each segment
+ *      before it is solved, so `Hub.deposit(HubLens.maxDeposit(hub))` fits.
+ */
+library HubCapacityMath {
+    /// @notice BPS denominator (`10_000` = 100%); mirrors `Hub.BPS_DENOMINATOR`.
+    uint16 internal constant BPS_DENOMINATOR = 10_000;
+
+    /// @notice Downward refinement passes before falling back to the pre-deposit room.
+    /// @dev Backstop for segment boundaries only — the pre-payment in {_solveCeiling} means the
+    ///      first check normally passes and none of these run.
+    uint256 private constant MAX_REFINEMENTS = 3;
+
+    /**
+     * @notice One deposit-queue YieldGroup, as read off the chain.
+     * @dev Caller supplies only YieldGroups the cascade would actually route to: registered,
+     *      unpaused, and answering both views. Everything it leaves out is immovable TVL.
+     * @param balance YieldGroup's current `totalAssets()`.
+     * @param venueRoom YieldGroup's current `maxDeposit()` — what its venues will still take.
+     * @param absoluteCap Hub-configured hard cap for this YieldGroup.
+     * @param percentageCapBps Hub-configured percentage cap in BPS; `10_000` disables the
+     *        percentage dimension (see `IHub.YieldGroupConfig`).
+     */
+    struct GroupInput {
+        uint256 balance;
+        uint256 venueRoom;
+        uint256 absoluteCap;
+        uint16 percentageCapBps;
+    }
+
+    /**
+     * @notice One YieldGroup after classification, reduced to the numbers the solve needs.
+     * @param balance YieldGroup's current `totalAssets()`.
+     * @param absBound `min(absoluteCap, balance + venueRoom)`, saturating on the add.
+     * @param breakLow Lowest TVL at which the percentage cap reaches `balance`.
+     * @param breakHigh Lowest TVL at which the percentage cap reaches `absBound`.
+     * @param pctBps Percentage cap in BPS, or 0 when it can never bind — the 100% sentinel disabled
+     *        it, or the YieldGroup is pinned at `balance` whatever the TVL.
+     */
+    struct CapPoint {
+        uint256 balance;
+        uint256 absBound;
+        uint256 breakLow;
+        uint256 breakHigh;
+        uint16 pctBps;
+    }
+
+    /**
+     * @notice One resource of a YieldGroup that has a minimum deposit, in inner deposit-queue order.
+     * @dev Such a resource skips a leg below `minDeposit` unless it exactly fills `room` (the tail),
+     *      so a leg the Hub cap or the queue shrinks after `maxDeposit()` was read can be refused.
+     * @param room What the resource will still take.
+     * @param minDeposit Smallest leg it accepts short of `room`. `0` = no floor.
+     */
+    struct ResourceFloor {
+        uint256 room;
+        uint256 minDeposit;
+    }
+
+    // ============================== Internal ==================================
+
+    /**
+     * @notice Aggregate asset units the deposit cascade would accept right now.
+     * @param groups Routable YieldGroups, in deposit-queue order.
+     * @param hubTotalAssets Hub's `totalAssets()` — the pre-deposit TVL.
+     * @return assets Asset units that could be deposited right now.
+     */
+    function capacity(GroupInput[] memory groups, uint256 hubTotalAssets) internal pure returns (uint256 assets) {
+        (CapPoint[] memory points, uint256 immovable) = _toPoints(groups, hubTotalAssets);
+        return _capacityOn(points, immovable, hubTotalAssets);
+    }
+
+    /**
+     * @notice The same figure {capacity} reports, split by the YieldGroup that would receive it.
+     * @dev Walks `groups` in deposit-queue order handing each one as much as it can hold, exactly as
+     *      the Hub's cascade does, so `Σ perGroup == total`. Answers "where would my deposit land",
+     *      which is not the same question as "how much could this YieldGroup take on its own" — a
+     *      YieldGroup late in the queue reads 0 here whenever the ones before it absorb everything.
+     * @param groups Routable YieldGroups, in deposit-queue order.
+     * @param hubTotalAssets Hub's `totalAssets()` — the pre-deposit TVL.
+     * @return total Asset units that could be deposited right now.
+     * @return perGroup Per-YieldGroup share of `total`, aligned index-for-index with `groups`.
+     */
+    function capacityPerGroup(GroupInput[] memory groups, uint256 hubTotalAssets)
+        internal
+        pure
+        returns (uint256 total, uint256[] memory perGroup)
+    {
+        (CapPoint[] memory points, uint256 immovable) = _toPoints(groups, hubTotalAssets);
+        total = _capacityOn(points, immovable, hubTotalAssets);
+        if (total == 0) return (total, new uint256[](groups.length));
+
+        perGroup = _splitOn(points, hubTotalAssets, total);
+    }
+
+    /**
+     * @notice {capacityPerGroup}, less an accrual margin of `balance / marginDivisor` per YieldGroup.
+     * @dev One entry point for the whole figure a view can safely promise, so the {CapPoint} set is
+     *      built once instead of once per step. A deposit settles resource interest before it prices
+     *      caps (`Hub._accrueFees`); a view cannot, so a Core position is marked off a stale
+     *      `exchangeRateStored()` and its real room is smaller. The margin is trimmed off the answer
+     *      rather than added to the mark: a higher mark would also lift the TVL the percentage caps
+     *      are priced at.
+     *
+     *      Sized on the balance, not on the room, because the interest a deposit settles scales with
+     *      what the YieldGroup holds.
+     * @param groups Routable YieldGroups, in deposit-queue order.
+     * @param hubTotalAssets Hub's `totalAssets()`, the pre-deposit TVL.
+     * @param marginDivisor Margin denominator, e.g. `10_000` for 0.01% of each balance. Must be
+     *        non-zero.
+     * @return total Asset units a view can promise, margin already trimmed.
+     * @return perGroup Per-YieldGroup share of `total`, aligned index-for-index with `groups`.
+     */
+    function trimmedCapacity(GroupInput[] memory groups, uint256 hubTotalAssets, uint256 marginDivisor)
+        internal
+        pure
+        returns (uint256 total, uint256[] memory perGroup)
+    {
+        (CapPoint[] memory points, uint256 immovable) = _toPoints(groups, hubTotalAssets);
+        total = _trimmedOn(points, immovable, hubTotalAssets, marginDivisor);
+        perGroup = _splitOn(points, hubTotalAssets, total);
+    }
+
+    /**
+     * @notice {trimmedCapacity}'s total, trimmed once more, for a figure quoted in shares.
+     * @dev `mint` prices the shares at a share price the deposit's own interest settlement raises,
+     *      so the same share count converts to more assets than it does in this view. One more
+     *      margin covers that, on the same {CapPoint} set as the first.
+     * @param groups Routable YieldGroups, in deposit-queue order.
+     * @param hubTotalAssets Hub's `totalAssets()`, the pre-deposit TVL.
+     * @param marginDivisor Margin denominator, e.g. `10_000` for 0.01%. Must be non-zero.
+     * @return total Asset units a share-denominated view can promise.
+     */
+    function doubleTrimmedCapacity(GroupInput[] memory groups, uint256 hubTotalAssets, uint256 marginDivisor)
+        internal
+        pure
+        returns (uint256 total)
+    {
+        (CapPoint[] memory points, uint256 immovable) = _toPoints(groups, hubTotalAssets);
+        total = _trimmedOn(points, immovable, hubTotalAssets, marginDivisor);
+        return _feasibleOn(points, hubTotalAssets, total - total / marginDivisor);
+    }
+
+    /// @notice Room the cascade would still leave at `tvl`, floored per YieldGroup exactly as it
+    ///         floors. Lets a caller check that a figure smaller than {capacity} is placeable: every
+    ///         cap shrinks with the TVL, so a smaller deposit does not automatically fit.
+    /// @param groups Routable YieldGroups, in deposit-queue order.
+    /// @param hubTotalAssets Hub's `totalAssets()` — the pre-deposit TVL.
+    /// @param tvl TVL to measure the caps at.
+    /// @return room Asset units the cascade would accept at `tvl`.
+    function roomAt(GroupInput[] memory groups, uint256 hubTotalAssets, uint256 tvl)
+        internal
+        pure
+        returns (uint256 room)
+    {
+        (CapPoint[] memory points,) = _toPoints(groups, hubTotalAssets);
+        return _roomAt(points, tvl);
+    }
+
+    /**
+     * @notice Room values worth offering the solve for one YieldGroup with floored resources,
+     *         largest first: `venueRoom`, then each queue-prefix sum of room below it, then 0.
+     * @dev A leg equal to a prefix sum fills every resource in that prefix exactly, so each one
+     *      takes its whole room and no floor applies. Between prefix sums a leg can land under the
+     *      next resource's floor, so these are the only edges the caller needs to try.
+     * @param floors The YieldGroup's resources, in inner deposit-queue order.
+     * @param venueRoom The YieldGroup's `maxDeposit()`.
+     * @return values Candidate rooms, non-increasing, ending in 0.
+     */
+    function roomCandidates(ResourceFloor[] memory floors, uint256 venueRoom)
+        internal
+        pure
+        returns (uint256[] memory values)
+    {
+        uint256 len = floors.length;
+        values = new uint256[](len + 1);
+        uint256 prefix;
+        for (uint256 k; k < len; ++k) {
+            prefix = _satAdd(prefix, floors[k].room);
+            values[len - 1 - k] = prefix < venueRoom ? prefix : venueRoom;
+        }
+    }
+
+    /**
+     * @notice Dry run of `Hub._routeDeposit(amount)`: each YieldGroup in queue order gets
+     *         `min(remaining, cap room, venueRoom)`, a floored one places it through its resources
+     *         the way `YieldGroupBase.deposit` does, and whatever it skips moves on.
+     * @dev Caps are rounded up and priced at `hubTotalAssets + amount`, as `Hub._effectiveCap` does.
+     * @param groups Routable YieldGroups, in deposit-queue order, with their real `venueRoom`.
+     * @param floors Per YieldGroup, its resources if any has a floor, else empty.
+     * @param hubTotalAssets Hub's `totalAssets()`, the pre-deposit TVL.
+     * @param amount Deposit to route.
+     * @return left What no YieldGroup placed. Non-zero means the Hub reverts `HubCapacityExceeded`.
+     * @return placed Per-YieldGroup amount placed, aligned with `groups`.
+     * @return short Per YieldGroup, whether its resources skipped part of the leg it was sent.
+     */
+    function route(GroupInput[] memory groups, ResourceFloor[][] memory floors, uint256 hubTotalAssets, uint256 amount)
+        internal
+        pure
+        returns (uint256 left, uint256[] memory placed, bool[] memory short)
+    {
+        uint256 n = groups.length;
+        placed = new uint256[](n);
+        short = new bool[](n);
+        uint256 tvl = _satAdd(hubTotalAssets, amount);
+        left = amount;
+
+        for (uint256 i; i < n && left > 0; ++i) {
+            GroupInput memory g = groups[i];
+            uint256 cap = _hubCap(g.absoluteCap, g.percentageCapBps, tvl);
+            uint256 room = cap > g.balance ? cap - g.balance : 0;
+            if (g.venueRoom < room) room = g.venueRoom;
+            uint256 sent = left < room ? left : room;
+
+            uint256 took = floors[i].length == 0 ? sent : _placeThrough(floors[i], sent);
+            placed[i] = took;
+            short[i] = took < sent;
+            left -= took;
+        }
+    }
+
+    // ============================== Private — classification ==================
+
+    /// @dev Reduce each {GroupInput} to its {CapPoint}, plus the TVL that cannot move: Hub idle,
+    ///      paused YieldGroups, ones outside the deposit queue, and any whose views reverted.
+    function _toPoints(GroupInput[] memory groups, uint256 hubTotalAssets)
+        private
+        pure
+        returns (CapPoint[] memory points, uint256 immovable)
+    {
+        uint256 len = groups.length;
+        points = new CapPoint[](len);
+        uint256 tracked;
+
+        for (uint256 i; i < len; ++i) {
+            GroupInput memory g = groups[i];
+
+            uint256 absBound = _satAdd(g.balance, g.venueRoom);
+            if (g.absoluteCap < absBound) absBound = g.absoluteCap;
+
+            uint16 pctBps = g.percentageCapBps;
+            uint256 breakLow;
+            uint256 breakHigh;
+            if (pctBps == 0 || g.balance >= absBound) {
+                // Pinned at `balance` for every TVL. Checked BEFORE the 100% sentinel: a YieldGroup
+                // holding more than its cap still holds it — a deposit cannot claw it back — so it
+                // must count as `balance`, not `absBound`, or the solve understates reachable TVL.
+                pctBps = 0;
+                breakLow = type(uint256).max;
+                breakHigh = type(uint256).max;
+            } else if (pctBps == BPS_DENOMINATOR) {
+                // Percentage dimension disabled by the 100% sentinel: only `absBound` ever binds,
+                // at every TVL. Both breakpoints sit at 0 so the YieldGroup is always absolute-bound.
+                pctBps = 0;
+            } else {
+                breakLow = _tvlReaching(g.balance, pctBps);
+                breakHigh = _tvlReaching(absBound, pctBps);
+            }
+
+            points[i] = CapPoint({
+                balance: g.balance, absBound: absBound, breakLow: breakLow, breakHigh: breakHigh, pctBps: pctBps
+            });
+            tracked = _satAdd(tracked, g.balance);
+        }
+
+        immovable = hubTotalAssets > tracked ? hubTotalAssets - tracked : 0;
+    }
+
+    // ============================== Private over a built point set ============
+
+    /// @dev {capacity} once the {CapPoint} set is in hand.
+    function _capacityOn(CapPoint[] memory points, uint256 immovable, uint256 hubTotalAssets)
+        private
+        pure
+        returns (uint256 assets)
+    {
+        if (points.length == 0) return 0;
+
+        uint256 ceiling = _solveCeiling(points, immovable, hubTotalAssets);
+        assets = ceiling > hubTotalAssets ? ceiling - hubTotalAssets : 0;
+
+        // The cascade will price its caps at `hubTotalAssets + assets`. Confirm that TVL really
+        // does leave `assets` of room, and walk the figure down if the closed form rounded high.
+        for (uint256 i; i < MAX_REFINEMENTS; ++i) {
+            uint256 room = _roomAt(points, hubTotalAssets + assets);
+            if (room >= assets) return assets;
+            assets = room;
+        }
+
+        // Unreached in practice. The room at the pre-deposit TVL is always feasible, because every
+        // cap is non-decreasing in TVL and depositing only raises it.
+        return _roomAt(points, hubTotalAssets);
+    }
+
+    /// @dev {capacity} less the accrual margin, once the {CapPoint} set is in hand. Trimmed per
+    ///      YieldGroup, off the room that YieldGroup would actually receive, and each one floors at
+    ///      0 on its own: a YieldGroup whose room is smaller than its own margin reads as full.
+    function _trimmedOn(CapPoint[] memory points, uint256 immovable, uint256 hubTotalAssets, uint256 marginDivisor)
+        private
+        pure
+        returns (uint256 total)
+    {
+        uint256 untrimmed = _capacityOn(points, immovable, hubTotalAssets);
+        if (untrimmed == 0) return 0;
+
+        uint256[] memory split = _splitOn(points, hubTotalAssets, untrimmed);
+        for (uint256 i; i < split.length; ++i) {
+            uint256 margin = points[i].balance / marginDivisor;
+            total += split[i] > margin ? split[i] - margin : 0;
+        }
+
+        return _feasibleOn(points, hubTotalAssets, total);
+    }
+
+    /// @dev Split `amount` across the YieldGroups the way the cascade would place it, with every
+    ///      cap priced at `hubTotalAssets + amount`, once the {CapPoint} set is in hand.
+    function _splitOn(CapPoint[] memory points, uint256 hubTotalAssets, uint256 amount)
+        private
+        pure
+        returns (uint256[] memory perGroup)
+    {
+        perGroup = new uint256[](points.length);
+        uint256 postTvl = hubTotalAssets + amount;
+        uint256 remaining = amount;
+
+        for (uint256 i; i < points.length && remaining > 0; ++i) {
+            uint256 held = _holdAt(points[i], postTvl);
+            uint256 balance = points[i].balance;
+            uint256 room = held > balance ? held - balance : 0;
+            if (room > remaining) room = remaining;
+            perGroup[i] = room;
+            remaining -= room;
+        }
+    }
+
+    /// @dev Walk `total` down to something the cascade would actually place. Trimming breaks the
+    ///      fixed point {_solveCeiling} found: every cap scales with the TVL, so a smaller deposit
+    ///      buys smaller caps, and where the percentage caps sum to ~100% each one's flooring sheds
+    ///      a wei the smaller figure no longer pre-pays.
+    function _feasibleOn(CapPoint[] memory points, uint256 hubTotalAssets, uint256 total)
+        private
+        pure
+        returns (uint256)
+    {
+        for (uint256 i; i < MAX_REFINEMENTS; ++i) {
+            uint256 room = _roomAt(points, hubTotalAssets + total);
+            if (room >= total) return total;
+
+            // Snap the post-deposit TVL down to a multiple of `BPS_DENOMINATOR`, where every
+            // percentage cap divides exactly and nothing is shed. Only reached when the plain room
+            // is short, so a book without that rounding keeps its exact figure.
+            uint256 postTvl = ((hubTotalAssets + room) / BPS_DENOMINATOR) * BPS_DENOMINATOR;
+            total = postTvl > hubTotalAssets ? postTvl - hubTotalAssets : room;
+        }
+        return total;
+    }
+
+    // ============================== Private — the solve =======================
+
+    /// @dev Largest post-deposit TVL every cap admits. Walks the segments between breakpoints and
+    ///      keeps the highest crossing that lands inside its own segment. Seeded at `floorTvl`, the
+    ///      pre-deposit TVL, which always satisfies the inequality: every YieldGroup already holds
+    ///      what the sum credits it with there.
+    function _solveCeiling(CapPoint[] memory points, uint256 immovable, uint256 floorTvl)
+        private
+        pure
+        returns (uint256 ceiling)
+    {
+        (uint256[] memory bounds, uint256 m) = _sortedBounds(points, floorTvl);
+
+        ceiling = floorTvl;
+        for (uint256 s; s < m; ++s) {
+            uint256 low = bounds[s];
+            uint256 high = s + 1 < m ? bounds[s + 1] : type(uint256).max;
+            (uint256 base, uint256 slopeBps, uint256 pctBoundCount) = _segmentAt(points, immovable, low);
+            if (slopeBps >= BPS_DENOMINATOR) {
+                // Slope >= 100%: every TVL in the segment fits, so take its top edge, snapped to a
+                // multiple of BPS_DENOMINATOR where the per-group floors lose nothing.
+                if (high != type(uint256).max) {
+                    uint256 edge = (high / BPS_DENOMINATOR) * BPS_DENOMINATOR;
+                    if (edge >= low && edge > ceiling) ceiling = edge;
+                }
+                continue;
+            }
+
+            // Crossing below `low` is not in this segment. Above `high`, the whole segment fits,
+            // so its top edge is the candidate.
+            uint256 exact = _crossing(base, slopeBps);
+            if (exact < low) continue;
+            if (exact > high) {
+                if (high > low) ceiling = _raiseIfFits(points, floorTvl, ceiling, high - 1);
+                continue;
+            }
+
+            // Per-group flooring can leave `exact` a wei short. Test it before pre-paying, so a
+            // crossing on `low` is not pushed into the segment below.
+            if (exact > ceiling && exact - floorTvl <= _roomAt(points, exact)) {
+                ceiling = exact;
+                continue;
+            }
+
+            // Pre-pay the flooring loss: one wei per percentage-bound YieldGroup.
+            if (base <= pctBoundCount) continue;
+            uint256 crossing = _crossing(base - pctBoundCount, slopeBps);
+            ceiling = _raiseIfFits(points, floorTvl, ceiling, crossing);
+        }
+    }
+
+    /// @dev `floorTvl` plus every finite breakpoint above it, sorted ascending; `m` is the count used.
+    function _sortedBounds(CapPoint[] memory points, uint256 floorTvl)
+        private
+        pure
+        returns (uint256[] memory bounds, uint256 m)
+    {
+        uint256 n = points.length;
+        bounds = new uint256[](2 * n + 1);
+
+        bounds[m] = floorTvl;
+        ++m;
+        for (uint256 i; i < n; ++i) {
+            uint256 low = points[i].breakLow;
+            uint256 high = points[i].breakHigh;
+            if (low > floorTvl && low != type(uint256).max) {
+                bounds[m] = low;
+                ++m;
+            }
+            if (high > floorTvl && high != type(uint256).max) {
+                bounds[m] = high;
+                ++m;
+            }
+        }
+
+        // Insertion sort: `m ≤ 2n + 1` and a Hub carries a handful of YieldGroups.
+        for (uint256 i = 1; i < m; ++i) {
+            uint256 v = bounds[i];
+            uint256 j = i;
+            while (j > 0 && bounds[j - 1] > v) {
+                bounds[j] = bounds[j - 1];
+                --j;
+            }
+            bounds[j] = v;
+        }
+    }
+
+    /// @dev `candidate`, walked down like {capacity}, if the cascade admits it; else `ceiling`.
+    ///      An unchecked candidate a wei too high would replace a ceiling that fits.
+    function _raiseIfFits(CapPoint[] memory points, uint256 floorTvl, uint256 ceiling, uint256 candidate)
+        private
+        pure
+        returns (uint256)
+    {
+        for (uint256 i; i < MAX_REFINEMENTS && candidate > ceiling; ++i) {
+            uint256 fits = _satAdd(floorTvl, _roomAt(points, candidate));
+            if (fits >= candidate) return candidate;
+            candidate = fits;
+        }
+        return ceiling;
+    }
+
+    /// @dev Constant, slope and percentage-bound count on the segment starting at `tvl`, where
+    ///      each YieldGroup's classification is constant. `pctBoundCount` counts the separate floors
+    ///      the cascade will take, one wei each, which is what the caller pre-pays off `base`.
+    function _segmentAt(CapPoint[] memory points, uint256 immovable, uint256 tvl)
+        private
+        pure
+        returns (uint256 base, uint256 slopeBps, uint256 pctBoundCount)
+    {
+        base = immovable;
+        uint256 n = points.length;
+        for (uint256 i; i < n; ++i) {
+            CapPoint memory p = points[i];
+            if (tvl >= p.breakHigh) {
+                base = _satAdd(base, p.absBound);
+            } else if (tvl < p.breakLow) {
+                base = _satAdd(base, p.balance);
+            } else {
+                slopeBps += p.pctBps;
+                ++pctBoundCount;
+            }
+        }
+    }
+
+    /// @dev Solve `X = base + slopeBps × X / 10_000`, rounded down so the result stays admissible
+    ///      on its segment. Returns 0 when `base` cannot be scaled without overflow, which reads as
+    ///      "no crossing here" rather than reverting the whole view. Caller guarantees slope < 100%.
+    function _crossing(uint256 base, uint256 slopeBps) private pure returns (uint256 crossing) {
+        if (base > type(uint256).max / BPS_DENOMINATOR) return 0;
+        crossing = (base * BPS_DENOMINATOR) / (BPS_DENOMINATOR - slopeBps);
+    }
+
+    // ============================== Private — exact room ======================
+
+    /// @dev Room at `tvl`, flooring each percentage cap. The Hub rounds it up, so this is never
+    ///      above the room the cascade gives.
+    function _roomAt(CapPoint[] memory points, uint256 tvl) private pure returns (uint256 room) {
+        uint256 n = points.length;
+        for (uint256 i; i < n; ++i) {
+            uint256 held = _holdAt(points[i], tvl);
+            uint256 balance = points[i].balance;
+            if (held > balance) room = _satAdd(room, held - balance);
+        }
+    }
+
+    /// @dev What one YieldGroup holds once TVL is `tvl`, i.e. `hold_i` of the header:
+    ///      `max(balance, min(absBound, pctBps × tvl / 10_000))`. The breakpoints already say which
+    ///      of the three cases applies, so nothing is compared here.
+    function _holdAt(CapPoint memory p, uint256 tvl) private pure returns (uint256 held) {
+        if (tvl >= p.breakHigh) return p.absBound;
+        if (tvl < p.breakLow) return p.balance;
+        held = _mulBpsDown(tvl, p.pctBps);
+    }
+
+    // ============================== Private — floored routing =================
+
+    /// @dev What a YieldGroup places of `amount` across `floors`, mirroring
+    ///      `YieldGroupBase._tryDepositOneResource`: a leg under the floor that is not the whole room
+    ///      is skipped and carried to the next resource.
+    function _placeThrough(ResourceFloor[] memory floors, uint256 amount) private pure returns (uint256) {
+        uint256 remaining = amount;
+        for (uint256 k; k < floors.length && remaining > 0; ++k) {
+            uint256 room = floors[k].room;
+            uint256 leg = remaining < room ? remaining : room;
+            if (leg == 0 || (leg < room && leg < floors[k].minDeposit)) continue;
+            remaining -= leg;
+        }
+        return amount - remaining;
+    }
+
+    /// @dev `Hub._effectiveCap`: the percentage cap rounded up, the 100% sentinel disabling it.
+    ///      Saturates instead of overflowing on a TVL no Hub can hold.
+    function _hubCap(uint256 absoluteCap, uint16 pctBps, uint256 tvl) private pure returns (uint256) {
+        if (pctBps == BPS_DENOMINATOR) return absoluteCap;
+        if (pctBps != 0 && tvl > (type(uint256).max - BPS_DENOMINATOR) / pctBps) return absoluteCap;
+        uint256 pctCap = (tvl * pctBps + BPS_DENOMINATOR - 1) / BPS_DENOMINATOR;
+        return pctCap < absoluteCap ? pctCap : absoluteCap;
+    }
+
+    // ============================== Private — arithmetic ======================
+
+    /// @dev `⌈target × 10_000 / pctBps⌉`, rounded up so the breakpoint is exact against the floored
+    ///      cap the cascade computes. `type(uint256).max` when out of range.
+    function _tvlReaching(uint256 target, uint16 pctBps) private pure returns (uint256 tvl) {
+        if (pctBps == 0) return type(uint256).max;
+        if (target > type(uint256).max / BPS_DENOMINATOR) return type(uint256).max;
+        uint256 numerator = target * BPS_DENOMINATOR;
+        tvl = numerator / pctBps;
+        if (numerator % pctBps != 0) ++tvl;
+    }
+
+    /// @dev `x × bps / 10_000`, rounded down, without overflowing on a large `x`. Saturates at
+    ///      `type(uint256).max`, which only a `bps` above 10_000 can reach.
+    function _mulBpsDown(uint256 x, uint256 bps) private pure returns (uint256 scaled) {
+        if (bps == 0) return 0;
+        if (x <= type(uint256).max / bps) return (x * bps) / BPS_DENOMINATOR;
+        uint256 whole = x / BPS_DENOMINATOR;
+        if (whole > type(uint256).max / bps) return type(uint256).max;
+        scaled = _satAdd(whole * bps, ((x % BPS_DENOMINATOR) * bps) / BPS_DENOMINATOR);
+    }
+
+    /// @dev Saturating add: a YieldGroup may advertise an unbounded `maxDeposit()`, and that must
+    ///      not be able to brick the capacity view.
+    function _satAdd(uint256 a, uint256 b) private pure returns (uint256 sum) {
+        unchecked {
+            sum = a + b;
+            if (sum < a) sum = type(uint256).max;
+        }
+    }
+}