@rev-net/core-v6 0.0.51 → 0.0.53

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.53",
   "license": "MIT",
   "repository": {
     "type": "git",

package/script/Deploy.s.sol

@@ -478,7 +478,7 @@ contract DeployScript is Script, Sphinx {
                 feeRevnetId: FEE_PROJECT_ID,
                 suckerRegistry: suckers.registry,
                 loans: revloans,
-                deployerBinder: msg.sender
+                deployer: msg.sender
             });
 
         // Deploy REVDeployer with the REVLoans, buyback hook, and REVOwner addresses.

package/src/REVOwner.sol

@@ -96,7 +96,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     //*********************************************************************//
 
     /// @notice The account allowed to bind the canonical deployer exactly once.
-    address private immutable _DEPLOYER_BINDER;
+    address private immutable _DEPLOYER;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -107,7 +107,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @param feeRevnetId The Juicebox project ID of the fee revnet.
     /// @param suckerRegistry The sucker registry.
     /// @param loans The loan contract.
-    /// @param deployerBinder The account allowed to bind the canonical deployer via `setDeployer`. Passed explicitly
+    /// @param deployer The account allowed to bind the canonical deployer via `setDeployer`. Passed explicitly
     /// because CREATE2 deployments set `msg.sender` to the factory, not the intended operator.
     constructor(
         IJBBuybackHookRegistry buybackHook,
@@ -115,14 +115,14 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         uint256 feeRevnetId,
         IJBSuckerRegistry suckerRegistry,
         IREVLoans loans,
-        address deployerBinder
+        address deployer
     ) {
         BUYBACK_HOOK = buybackHook;
         DIRECTORY = directory;
         FEE_REVNET_ID = feeRevnetId;
         SUCKER_REGISTRY = suckerRegistry;
         LOANS = loans;
-        _DEPLOYER_BINDER = deployerBinder;
+        _DEPLOYER = deployer;
     }
 
     //*********************************************************************//
@@ -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)
@@ -471,9 +508,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @param deployer The canonical REVDeployer instance that will manage revnet runtime state.
     function setDeployer(IREVDeployer deployer) external {
         // Only the account that deployed this REVOwner may complete the one-time deployer binding.
-        if (msg.sender != _DEPLOYER_BINDER) {
-            revert REVOwner_Unauthorized({caller: msg.sender, expectedCaller: _DEPLOYER_BINDER});
-        }
+        if (msg.sender != _DEPLOYER) revert REVOwner_Unauthorized({caller: msg.sender, expectedCaller: _DEPLOYER});
         // Prevent the deployer binding from being overwritten after initialization.
         if (address(DEPLOYER) != address(0)) revert REVOwner_AlreadyInitialized({deployer: address(DEPLOYER)});
         // Store the canonical REVDeployer that is authorized to manage runtime hook state.