@rev-net/core-v6 0.0.51 → 0.0.52

package/CHANGELOG.md

@@ -21,6 +21,18 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 - The v6 test tree is substantially broader than the v5 tree, with dedicated regression, fork, attack, and invariant coverage for loans, cash-outs, split weights, and lifecycle edges.
 - The repo moved from the v5 `0.8.23` baseline to `0.8.28`.
 
+## In-v6 changes
+
+### `0.0.52` — Cap reported surplus on `REVOwner.beforeCashOutRecordedWith` to fit local liquidity
+
+PR #149 scaled the fee + reclaim proportionally when the gross global outflow exceeded local terminal liquidity, preserving a nonzero fee. But the data hook still returned the **unscaled** `effectiveSurplusValue` to `JBTerminalStore._cashOutWithDataHook`, which recomputes the beneficiary reclaim as `cashOutFrom(effSurplus, cashOutCount, totalSupply, taxRate)` and caps it at local surplus before adding the fee spec — so `balanceDiff = localSurplus + feeAmount > localSurplus` reverted with `InadequateTerminalStoreBalance`. Omnichain holders could not cash out locally when global surplus dominated.
+
+`cashOutFrom` is linear in `surplus`. After the existing PR #149 scaling, `REVOwner` now lowers the reported `effectiveSurplusValue` proportionally so the store's recomputed reclaim is at most `localSurplus - feeAmount`, leaving exact room for the (preserved) fee spec. The buyback hook still receives the full pre-cap global surplus for its routing decision — only the store-facing return is capped.
+
+The fee is **never** trimmed or zeroed: that was the regression PR #149 fixed.
+
+Integrator impact: omnichain cash-outs that previously reverted with `InadequateTerminalStoreBalance` when local liquidity was the binding cap now settle. The beneficiary receives `localSurplus - feeAmount` and the fee revnet receives `feeAmount`. The user still burns the full `context.cashOutCount` tokens — semantics are the same as the pre-existing local-cap protocol behavior, just now reachable end-to-end.
+
 ## Operator delegation
 
 - Added new `JBPermissionIds` for operator delegation in `@bananapus/permission-ids-v6`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rev-net/core-v6",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/REVOwner.sol

@@ -239,6 +239,12 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
             cashOutTaxRate: context.cashOutTaxRate
         });
 
+        // Snapshot the unscaled reclaim before the local-liquidity proportional scaling below mutates it. This is
+        // what `JBTerminalStore._cashOutWithDataHook` will recompute when it calls
+        // `JBCashOuts.cashOutFrom(effectiveSurplusValue, cashOutCount, totalSupply, cashOutTaxRate)` — same inputs,
+        // same output. Used to cap the surplus we report to the store so the recompute leaves room for the fee.
+        uint256 unscaledReclaim = postFeeReclaimedAmount;
+
         // If the gross outflow exceeds local terminal liquidity, scale reclaim AND fee proportionally so the fee
         // is preserved instead of being capped to zero when the reclaim alone consumes all local surplus.
         uint256 grossOutflow = postFeeReclaimedAmount + feeAmount;
@@ -272,6 +278,37 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
             return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, buybackHookSpecifications);
         }
 
+        // The store will recompute the beneficiary reclaim as `cashOutFrom(effectiveSurplusValue, cashOutCount,
+        // totalSupply, cashOutTaxRate)` and add the fee spec on top. When local liquidity is the binding cap, that
+        // sum can exceed local surplus and revert. `cashOutFrom` is linear in `surplus`, so scale the surplus we
+        // report so the store-side reclaim is at most `localSurplus - feeAmount`, preserving room for the fee.
+        // The fee is NOT scaled here — it was already scaled by the PR #149 block above. Only the store-facing
+        // surplus is touched; the buyback hook already received the full pre-cap value for its routing decision.
+        //
+        // Worked example (local=10, global=100, 500 of 1000 tokens at 50% tax):
+        //   above this block (PR #149):
+        //     unscaledReclaim = cashOutFrom(100, 487.5, 1000, 5000)            ≈ 36 ETH        (global)
+        //     feeAmount       = cashOutFrom(64, 12.5, 512.5, 5000)             ≈ 0.78 ETH      (global)
+        //     grossOutflow ≈ 36.78 > 10  →  scale both proportionally to local liquidity:
+        //       postFeeReclaimedAmount *= 10/36.78 ≈ 9.79 ETH
+        //       feeAmount              *= 10/36.78 ≈ 0.214 ETH                 (preserved, nonzero)
+        //   this block:
+        //     reclaimCap = 10 − 0.214 = 9.786 ETH
+        //     unscaledReclaim (36) > reclaimCap (9.786)  →  cap the surplus we report:
+        //       effectiveSurplusValue = 100 × 9.786 / 36 ≈ 27.18 ETH
+        //   store recompute (linear in surplus):
+        //     storeReclaim = 36 × (27.18 / 100) ≈ 9.786 ETH
+        //     balanceDiff  = 9.786 + 0.214 = 10 ETH = localSurplus              ✓ no revert
+        //
+        // Underflow safety on `localSurplus − feeAmount`: after PR #149 the relation
+        // `feeAmount ≤ localSurplus` holds in both branches — in the scaling branch because
+        // `feeAmount ≤ grossOutflow` and the multiplier is `localSurplus / grossOutflow ≤ 1`;
+        // in the else branch because `feeAmount ≤ grossOutflow ≤ localSurplus` already.
+        uint256 reclaimCap = context.surplus.value - feeAmount;
+        if (unscaledReclaim > reclaimCap) {
+            effectiveSurplusValue = mulDiv({x: effectiveSurplusValue, y: reclaimCap, denominator: unscaledReclaim});
+        }
+
         // Build a hook spec that routes the fee amount to this contract's `afterCashOutRecordedWith` for processing.
         JBCashOutHookSpecification memory feeSpec = JBCashOutHookSpecification({
             hook: IJBCashOutHook(address(this)), noop: false, amount: feeAmount, metadata: abi.encode(feeTerminal)