@rev-net/core-v6 0.0.30 → 0.0.31

package/USER_JOURNEYS.md

@@ -93,6 +93,17 @@
 2. Use only those surfaces rather than treating the project like a normal owner-governed Juicebox project.
 3. Audit cross-package behavior whenever the Revnet enabled buybacks, 721 hooks, router terminals, or suckers.
 
+## Journey 7: Receive Cross-Chain Payments With Correct Hook Routing
+
+**Starting state:** a sucker pays the Revnet on behalf of a remote user via `payRemote`, and the hooks attached via `REVOwner.beforePayRecordedWith` need to see the real user.
+
+**Success:** the 721 hook and buyback hook see the real remote user as the beneficiary so NFTs mint to and buyback routing benefits the correct person.
+
+**Flow**
+1. The sucker calls `terminal.pay()` with relay-beneficiary metadata.
+2. `REVOwner.beforePayRecordedWith()` resolves the relay beneficiary from the metadata when the payer is a registered sucker.
+3. The swapped beneficiary is forwarded to both the 721 hook and the buyback hook.
+
 ## Hand-Offs
 
 - Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the underlying project, terminal, and ruleset mechanics that Revnets package and constrain.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rev-net/core-v6",
-    "version": "0.0.30",
+    "version": "0.0.31",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -19,14 +19,14 @@
         "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'revnet-core-v6'"
     },
     "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.32",
-        "@bananapus/buyback-hook-v6": "^0.0.26",
-        "@bananapus/core-v6": "^0.0.32",
+        "@bananapus/721-hook-v6": "^0.0.33",
+        "@bananapus/buyback-hook-v6": "^0.0.27",
+        "@bananapus/core-v6": "^0.0.34",
         "@bananapus/ownable-v6": "^0.0.17",
-        "@bananapus/permission-ids-v6": "^0.0.16",
+        "@bananapus/permission-ids-v6": "^0.0.17",
         "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.22",
-        "@croptop/core-v6": "^0.0.30",
+        "@bananapus/suckers-v6": "^0.0.25",
+        "@croptop/core-v6": "github:mejango/croptop-core-v6",
         "@openzeppelin/contracts": "^5.6.1",
         "@uniswap/v4-core": "^1.0.2",
         "@uniswap/v4-periphery": "^1.0.3"
@@ -35,4 +35,4 @@
         "@bananapus/address-registry-v6": "^0.0.17",
         "@sphinx-labs/plugins": "^0.33.2"
     }
-}
+}

package/script/Deploy.s.sol

@@ -389,7 +389,9 @@ contract DeployScript is Script, Sphinx {
             (address _candidateRevloansAddr, bool _candidateRevloansDeployed) = _isDeployed({
                 salt: REVLOANS_SALT,
                 creationCode: type(REVLoans).creationCode,
-                arguments: abi.encode(core.controller, _candidateId, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER)
+                arguments: abi.encode(
+                    core.controller, suckers.registry, _candidateId, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER
+                )
             });
 
             if (_candidateRevloansDeployed) {
@@ -469,6 +471,7 @@ contract DeployScript is Script, Sphinx {
             ? REVLoans(payable(_existingRevloansAddr))
             : new REVLoans{salt: REVLOANS_SALT}({
                 controller: core.controller,
+                suckerRegistry: suckers.registry,
                 revId: FEE_PROJECT_ID,
                 owner: LOANS_OWNER,
                 permit2: PERMIT2,

package/src/REVDeployer.sol

@@ -375,7 +375,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         uint256[] memory customSplitOperatorPermissionIndexes = _extraOperatorPermissions[revnetId];
 
         // Make the array that merges the default and custom operator permissions.
-        allOperatorPermissions = new uint256[](9 + customSplitOperatorPermissionIndexes.length);
+        allOperatorPermissions = new uint256[](10 + customSplitOperatorPermissionIndexes.length);
         allOperatorPermissions[0] = JBPermissionIds.SET_SPLIT_GROUPS;
         allOperatorPermissions[1] = JBPermissionIds.SET_BUYBACK_POOL;
         allOperatorPermissions[2] = JBPermissionIds.SET_BUYBACK_TWAP;
@@ -385,10 +385,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         allOperatorPermissions[6] = JBPermissionIds.SET_BUYBACK_HOOK;
         allOperatorPermissions[7] = JBPermissionIds.SET_ROUTER_TERMINAL;
         allOperatorPermissions[8] = JBPermissionIds.SET_TOKEN_METADATA;
+        allOperatorPermissions[9] = JBPermissionIds.SIGN_FOR_ERC20;
 
         // Copy the custom permissions into the array.
         for (uint256 i; i < customSplitOperatorPermissionIndexes.length;) {
-            allOperatorPermissions[9 + i] = customSplitOperatorPermissionIndexes[i];
+            allOperatorPermissions[10 + i] = customSplitOperatorPermissionIndexes[i];
             unchecked {
                 ++i;
             }
@@ -833,6 +834,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // Store the cash out delay of the revnet if its stages are already in progress.
         // This prevents cash out liquidity/arbitrage issues for existing revnets which
         // are deploying to a new chain.
+        // slither-disable-next-line reentrancy-events
         _setCashOutDelayIfNeeded({revnetId: revnetId, firstStageConfig: configuration.stageConfigurations[0]});
 
         // Deploy the revnet's ERC-20 token.

package/src/REVLoans.sol

@@ -1,15 +1,14 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+import {JBPermissioned} from "@bananapus/core-v6/src/abstract/JBPermissioned.sol";
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPayoutTerminal} from "@bananapus/core-v6/src/interfaces/IJBPayoutTerminal.sol";
 import {IJBPermissioned} from "@bananapus/core-v6/src/interfaces/IJBPermissioned.sol";
-import {JBPermissioned} from "@bananapus/core-v6/src/abstract/JBPermissioned.sol";
 import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {IJBTokenUriResolver} from "@bananapus/core-v6/src/interfaces/IJBTokenUriResolver.sol";
-import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {JBCashOuts} from "@bananapus/core-v6/src/libraries/JBCashOuts.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBFees} from "@bananapus/core-v6/src/libraries/JBFees.sol";
@@ -18,6 +17,8 @@ import {JBSurplus} from "@bananapus/core-v6/src/libraries/JBSurplus.sol";
 import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
 import {JBSingleAllowance} from "@bananapus/core-v6/src/structs/JBSingleAllowance.sol";
+import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
+import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -124,6 +125,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @notice The ID of the REV revnet that will receive the fees.
     uint256 public immutable override REV_ID;
 
+    /// @notice The sucker registry used to discover peer chain suckers for cross-chain awareness.
+    IJBSuckerRegistry public immutable override SUCKER_REGISTRY;
+
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
@@ -180,12 +184,14 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     //*********************************************************************//
 
     /// @param controller The controller that manages revnets using this loans contract.
+    /// @param suckerRegistry The registry used to discover peer chain suckers for cross-chain supply/surplus awareness.
     /// @param revId The ID of the REV revnet that will receive the fees.
     /// @param owner The owner of the contract that can set the URI resolver.
     /// @param permit2 A permit2 utility.
     /// @param trustedForwarder A trusted forwarder of transactions to this contract.
     constructor(
         IJBController controller,
+        IJBSuckerRegistry suckerRegistry,
         uint256 revId,
         address owner,
         IPermit2 permit2,
@@ -201,6 +207,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         PRICES = controller.PRICES();
         REV_ID = revId;
         PERMIT2 = permit2;
+        SUCKER_REGISTRY = suckerRegistry;
     }
 
     //*********************************************************************//
@@ -355,17 +362,29 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Get a refeerence to the collateral being used to secure loans.
         uint256 totalCollateral = totalCollateralOf[revnetId];
 
+        // The local supply includes both circulating tokens and tokens locked as loan collateral.
+        uint256 localSupply = totalSupply + totalCollateral;
+
+        // The local surplus includes both the treasury surplus and the outstanding borrowed amounts.
+        uint256 localSurplus = totalSurplus + totalBorrowed;
+
         // Proportional — uses the CURRENT stage's cashOutTaxRate.
         // NOTE: When a revnet transitions between stages with different cashOutTaxRate values, the borrowable amount
         // for the same collateral changes. A lower cashOutTaxRate in a later stage means more borrowable value per
         // collateral. This is by design: loan value tracks the current bonding curve parameters, just as cash-out
         // value does. Borrowers benefit from decreasing tax rates and are constrained by increasing ones.
-        return JBCashOuts.cashOutFrom({
-            surplus: totalSurplus + totalBorrowed,
+        // Add cross-chain remote values for proportional reclaim.
+        uint256 omnichainSurplus =
+            localSurplus + SUCKER_REGISTRY.remoteSurplusOf({projectId: revnetId, decimals: 18, currency: currency});
+        uint256 omnichainSupply = localSupply + SUCKER_REGISTRY.remoteTotalSupplyOf(revnetId);
+        uint256 reclaimable = JBCashOuts.cashOutFrom({
+            surplus: omnichainSurplus,
             cashOutCount: collateralCount,
-            totalSupply: totalSupply + totalCollateral,
+            totalSupply: omnichainSupply,
             cashOutTaxRate: currentStage.cashOutTaxRate()
         });
+        // Cap at local surplus — can't borrow more than what this chain's terminals actually hold.
+        return reclaimable > localSurplus ? localSurplus : reclaimable;
     }
 
     /// @notice The amount of the loan that should be borrowed for the given collateral amount.
@@ -1078,33 +1097,16 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             ? 0
             : JBFees.feeAmountFrom({amountBeforeFee: addedBorrowAmount, feePercent: REV_PREPAID_FEE_PERCENT});
 
+        // Try to pay the REV fee. If it fails, revFeeAmount is zeroed so the borrower receives it instead.
         if (revFeeAmount > 0) {
-            // Increase the allowance for the fee terminal.
-            uint256 payValue =
-                _beforeTransferTo({to: address(feeTerminal), token: loan.source.token, amount: revFeeAmount});
-
-            // Pay the fee. Send the REV to the beneficiary. If fee payment fails, give the amount back to the borrower.
-            // NOTE: When terminal.pay() reverts (e.g. due to a misconfigured terminal or paused payments),
-            // the REV fee is refunded to the borrower, resulting in an effectively interest-free loan for the
-            // REV fee portion. This is acceptable — it requires a broken/misconfigured fee terminal and the
-            // borrower still pays the source fee and protocol fee.
-            // slither-disable-next-line arbitrary-send-eth,unused-return
-            try feeTerminal.pay{value: payValue}({
-                projectId: REV_ID,
-                token: loan.source.token,
-                amount: revFeeAmount,
-                beneficiary: beneficiary,
-                minReturnedTokens: 0,
-                memo: "",
-                metadata: bytes(abi.encodePacked(revnetId))
-            }) {}
-            catch (bytes memory) {
-                // If the fee can't be processed, decrease the ERC-20 allowance and zero out the fee
-                // so the borrower receives it instead.
-                if (loan.source.token != JBConstants.NATIVE_TOKEN) {
-                    IERC20(loan.source.token)
-                        .safeDecreaseAllowance({spender: address(feeTerminal), requestedDecrease: revFeeAmount});
-                }
+            if (!_tryPayFee({
+                    terminal: feeTerminal,
+                    projectId: REV_ID,
+                    token: loan.source.token,
+                    amount: revFeeAmount,
+                    beneficiary: beneficiary,
+                    metadataProjectId: revnetId
+                })) {
                 revFeeAmount = 0;
             }
         }
@@ -1195,35 +1197,16 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             });
         }
 
-        // If there is a source fee, pay it. Wrapped in try-catch so a reverting source terminal
-        // cannot block all loan operations (matching the REV fee pattern above).
+        // Try to pay the source fee. If it fails, transfer the amount to the beneficiary instead.
         if (sourceFeeAmount > 0) {
-            // Increase the allowance for the source terminal.
-            uint256 payValue =
-                _beforeTransferTo({to: address(sourceTerminal), token: sourceToken, amount: sourceFeeAmount});
-
-            // Pay the fee. If it fails, reclaim the allowance and give the amount back to the borrower.
-            // NOTE: When terminal.pay() reverts (e.g. due to a misconfigured terminal or paused payments),
-            // the source fee is refunded to the borrower, resulting in an effectively interest-free loan for the
-            // source fee portion. This is acceptable — it requires a broken/misconfigured source terminal and
-            // the borrower still pays the REV fee and protocol fee.
-            // slither-disable-next-line unused-return,arbitrary-send-eth
-            try sourceTerminal.pay{value: payValue}({
-                projectId: revnetId,
-                token: sourceToken,
-                amount: sourceFeeAmount,
-                beneficiary: beneficiary,
-                minReturnedTokens: 0,
-                memo: "",
-                metadata: bytes(abi.encodePacked(REV_ID))
-            }) {}
-            catch (bytes memory) {
-                // If the fee can't be processed, decrease the ERC-20 allowance and return the amount
-                // to the beneficiary instead.
-                if (sourceToken != JBConstants.NATIVE_TOKEN) {
-                    IERC20(sourceToken)
-                        .safeDecreaseAllowance({spender: address(sourceTerminal), requestedDecrease: sourceFeeAmount});
-                }
+            if (!_tryPayFee({
+                    terminal: IJBTerminal(address(sourceTerminal)),
+                    projectId: revnetId,
+                    token: sourceToken,
+                    amount: sourceFeeAmount,
+                    beneficiary: beneficiary,
+                    metadataProjectId: REV_ID
+                })) {
                 _transferFrom({from: address(this), to: beneficiary, token: sourceToken, amount: sourceFeeAmount});
             }
         }
@@ -1517,6 +1500,45 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         PERMIT2.transferFrom({from: from, to: to, amount: uint160(amount), token: token});
     }
 
+    /// @notice Attempts to pay a fee to a terminal. On failure, cleans up the ERC-20 allowance and returns false.
+    /// @param terminal The terminal to pay the fee to.
+    /// @param projectId The project receiving the fee.
+    /// @param token The token being used to pay the fee.
+    /// @param amount The fee amount.
+    /// @param beneficiary The address to credit for the fee payment.
+    /// @param metadataProjectId The project ID encoded in the payment metadata.
+    /// @return success Whether the fee was successfully paid.
+    function _tryPayFee(
+        IJBTerminal terminal,
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        address beneficiary,
+        uint256 metadataProjectId
+    )
+        internal
+        returns (bool success)
+    {
+        uint256 payValue = _beforeTransferTo({to: address(terminal), token: token, amount: amount});
+
+        // slither-disable-next-line arbitrary-send-eth,unused-return
+        try terminal.pay{value: payValue}({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: bytes(abi.encodePacked(metadataProjectId))
+        }) {
+            success = true;
+        } catch (bytes memory) {
+            if (token != JBConstants.NATIVE_TOKEN) {
+                IERC20(token).safeDecreaseAllowance({spender: address(terminal), requestedDecrease: amount});
+            }
+        }
+    }
+
     fallback() external payable {}
     receive() external payable {}
 }

package/src/REVOwner.sol

@@ -137,7 +137,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
     /// out.
     /// @return cashOutCount The number of revnet tokens that are cashed out.
-    /// @return totalSupply The total revnet token supply.
+    /// @return totalSupply The total token supply across all chains (for both proportional reclaim and tax).
+    /// @return effectiveSurplusValue The global surplus across all chains for proportional reclaim.
     /// @return hookSpecifications The amount of funds and the data to send to cash out hooks (this contract).
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
         external
@@ -147,6 +148,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             uint256 cashOutTaxRate,
             uint256 cashOutCount,
             uint256 totalSupply,
+            uint256 effectiveSurplusValue,
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
@@ -154,7 +156,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         // This relies on the sucker registry to only contain trusted sucker contracts deployed via
         // the registry's own deploySuckersFor flow — external addresses cannot register as suckers.
         if (_isSuckerOf({revnetId: context.projectId, addr: context.holder})) {
-            return (0, context.cashOutCount, context.totalSupply, hookSpecifications);
+            return (0, context.cashOutCount, context.totalSupply, context.surplus.value, hookSpecifications);
         }
 
         // Keep a reference to the cash out delay of the revnet.
@@ -168,11 +170,23 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         // Get the terminal that will receive the cash out fee.
         IJBTerminal feeTerminal = DIRECTORY.primaryTerminalOf({projectId: FEE_REVNET_ID, token: context.surplus.token});
 
+        // Compute the cross-chain total supply (local + remote peer chain supplies) for cross-chain-aware bonding
+        // curve.
+        totalSupply = context.totalSupply + SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
+        effectiveSurplusValue = context.surplus.value
+            + SUCKER_REGISTRY.remoteSurplusOf({
+                projectId: context.projectId,
+                decimals: context.surplus.decimals,
+                currency: uint256(uint160(context.surplus.token))
+            });
+
         // If there's no cash out tax (100% cash out tax rate), if there's no fee terminal, or if the beneficiary is
-        // feeless (e.g. the router terminal routing value between projects), proxy directly to the buyback hook.
+        // feeless (e.g. the router terminal routing value between projects), proxy to the buyback hook with our
+        // totalSupply and effectiveSurplusValue.
         if (context.cashOutTaxRate == 0 || address(feeTerminal) == address(0) || context.beneficiaryIsFeeless) {
             // slither-disable-next-line unused-return
-            return BUYBACK_HOOK.beforeCashOutRecordedWith(context);
+            (cashOutTaxRate, cashOutCount,,, hookSpecifications) = BUYBACK_HOOK.beforeCashOutRecordedWith(context);
+            return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
         }
 
         // Split the cashed-out tokens into a fee portion and a non-fee portion.
@@ -185,20 +199,33 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         uint256 nonFeeCashOutCount = context.cashOutCount - feeCashOutCount;
 
         // Calculate how much surplus the non-fee tokens can reclaim via the bonding curve.
+        // Use effective (cross-chain) surplus; cap at local surplus.
         uint256 postFeeReclaimedAmount = JBCashOuts.cashOutFrom({
-            surplus: context.surplus.value,
+            surplus: effectiveSurplusValue,
             cashOutCount: nonFeeCashOutCount,
-            totalSupply: context.totalSupply,
+            totalSupply: totalSupply,
             cashOutTaxRate: context.cashOutTaxRate
         });
+        // Cap at local surplus — the bonding curve uses cross-chain effective surplus which can exceed what this
+        // chain's terminal actually holds.
+        if (postFeeReclaimedAmount > context.surplus.value) postFeeReclaimedAmount = context.surplus.value;
 
         // Calculate how much the fee tokens reclaim from the remaining surplus after the non-fee reclaim.
+        // Use remaining effective surplus; cap at remaining local surplus.
         uint256 feeAmount = JBCashOuts.cashOutFrom({
-            surplus: context.surplus.value - postFeeReclaimedAmount,
+            surplus: effectiveSurplusValue > postFeeReclaimedAmount
+                ? effectiveSurplusValue - postFeeReclaimedAmount
+                : 0,
             cashOutCount: feeCashOutCount,
-            totalSupply: context.totalSupply - nonFeeCashOutCount,
+            totalSupply: totalSupply - nonFeeCashOutCount,
             cashOutTaxRate: context.cashOutTaxRate
         });
+        // Cap the fee reclaim at remaining local surplus. The bonding curve uses the cross-chain effective surplus,
+        // which can exceed what's actually held locally. Without this cap, the terminal would try to send more than
+        // it has.
+        if (feeAmount > context.surplus.value - postFeeReclaimedAmount) {
+            feeAmount = context.surplus.value - postFeeReclaimedAmount;
+        }
 
         // Build a context for the buyback hook using only the non-fee token count.
         JBBeforeCashOutRecordedContext memory buybackHookContext = context;
@@ -206,11 +233,13 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
 
         // Let the buyback hook adjust the cash out parameters and optionally return a hook specification.
         JBCashOutHookSpecification[] memory buybackHookSpecifications;
-        (cashOutTaxRate, cashOutCount, totalSupply, buybackHookSpecifications) =
+        (cashOutTaxRate, cashOutCount,,, buybackHookSpecifications) =
             BUYBACK_HOOK.beforeCashOutRecordedWith(buybackHookContext);
 
         // If the fee rounds down to zero, return the buyback hook's response directly — no fee to process.
-        if (feeAmount == 0) return (cashOutTaxRate, cashOutCount, totalSupply, buybackHookSpecifications);
+        if (feeAmount == 0) {
+            return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, buybackHookSpecifications);
+        }
 
         // Build a hook spec that routes the fee amount to this contract's `afterCashOutRecordedWith` for processing.
         JBCashOutHookSpecification memory feeSpec = JBCashOutHookSpecification({
@@ -232,7 +261,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             hookSpecifications[0] = feeSpec;
         }
 
-        return (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications);
+        return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
     }
 
     /// @notice Before a revnet processes an incoming payment, determine the weight and pay hooks to use.

package/src/interfaces/IREVLoans.sol

@@ -7,6 +7,7 @@ import {IJBPayoutTerminal} from "@bananapus/core-v6/src/interfaces/IJBPayoutTerm
 import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBTokenUriResolver} from "@bananapus/core-v6/src/interfaces/IJBTokenUriResolver.sol";
 import {JBSingleAllowance} from "@bananapus/core-v6/src/structs/JBSingleAllowance.sol";
+import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
 import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
 import {REVLoan} from "../structs/REVLoan.sol";
 import {REVLoanSource} from "../structs/REVLoanSource.sol";
@@ -167,6 +168,10 @@ interface IREVLoans {
     /// @return The REV revnet ID.
     function REV_ID() external view returns (uint256);
 
+    /// @notice The sucker registry used to discover peer chain suckers for cross-chain supply/surplus awareness.
+    /// @return The sucker registry.
+    function SUCKER_REGISTRY() external view returns (IJBSuckerRegistry);
+
     /// @notice The fee percent charged by the REV revnet on each loan, in terms of `JBConstants.MAX_FEE`.
     /// @return The REV prepaid fee percent.
     function REV_PREPAID_FEE_PERCENT() external view returns (uint256);

package/test/REV.integrations.t.sol

@@ -40,6 +40,8 @@ import {JBArbitrumSucker, JBLayer, IArbGatewayRouter, IInbox} from "@bananapus/s
 
 import {JB721TiersHook} from "@bananapus/721-hook-v6/src/JB721TiersHook.sol";
 import {JB721TiersHookStore} from "@bananapus/721-hook-v6/src/JB721TiersHookStore.sol";
+import {JB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JBAddressRegistry} from "@bananapus/address-registry-v6/src/JBAddressRegistry.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
 
@@ -211,7 +213,14 @@ contract REVnet_Integrations is TestBaseWorkflow {
         HOOK_STORE = new JB721TiersHookStore();
 
         EXAMPLE_HOOK = new JB721TiersHook(
-            jbDirectory(), jbPermissions(), jbPrices(), jbRulesets(), HOOK_STORE, jbSplits(), multisig()
+            jbDirectory(),
+            jbPermissions(),
+            jbPrices(),
+            jbRulesets(),
+            HOOK_STORE,
+            jbSplits(),
+            IJB721CheckpointsDeployer(address(new JB721CheckpointsDeployer())),
+            multisig()
         );
 
         ADDRESS_REGISTRY = new JBAddressRegistry();

package/test/REVAutoIssuanceFuzz.t.sol

@@ -32,6 +32,8 @@ import {JBSuckerRegistry} from "@bananapus/suckers-v6/src/JBSuckerRegistry.sol";
 import {JB721TiersHookDeployer} from "@bananapus/721-hook-v6/src/JB721TiersHookDeployer.sol";
 import {JB721TiersHook} from "@bananapus/721-hook-v6/src/JB721TiersHook.sol";
 import {JB721TiersHookStore} from "@bananapus/721-hook-v6/src/JB721TiersHookStore.sol";
+import {JB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JBAddressRegistry} from "@bananapus/address-registry-v6/src/JBAddressRegistry.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
 import {REVEmpty721Config} from "./helpers/REVEmpty721Config.sol";
@@ -77,7 +79,14 @@ contract REVAutoIssuanceFuzz_Local is TestBaseWorkflow {
         SUCKER_REGISTRY = new JBSuckerRegistry(jbDirectory(), jbPermissions(), multisig(), address(0));
         HOOK_STORE = new JB721TiersHookStore();
         EXAMPLE_HOOK = new JB721TiersHook(
-            jbDirectory(), jbPermissions(), jbPrices(), jbRulesets(), HOOK_STORE, jbSplits(), multisig()
+            jbDirectory(),
+            jbPermissions(),
+            jbPrices(),
+            jbRulesets(),
+            HOOK_STORE,
+            jbSplits(),
+            IJB721CheckpointsDeployer(address(new JB721CheckpointsDeployer())),
+            multisig()
         );
         ADDRESS_REGISTRY = new JBAddressRegistry();
         HOOK_DEPLOYER = new JB721TiersHookDeployer(EXAMPLE_HOOK, HOOK_STORE, ADDRESS_REGISTRY, multisig());

package/test/REVDeployerRegressions.t.sol

@@ -35,10 +35,13 @@ import {JBSuckerRegistry} from "@bananapus/suckers-v6/src/JBSuckerRegistry.sol";
 import {JB721TiersHookDeployer} from "@bananapus/721-hook-v6/src/JB721TiersHookDeployer.sol";
 import {JB721TiersHook} from "@bananapus/721-hook-v6/src/JB721TiersHook.sol";
 import {JB721TiersHookStore} from "@bananapus/721-hook-v6/src/JB721TiersHookStore.sol";
+import {JB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JBAddressRegistry} from "@bananapus/address-registry-v6/src/JBAddressRegistry.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
 import {REVOwner} from "../src/REVOwner.sol";
 import {IREVDeployer} from "../src/interfaces/IREVDeployer.sol";
+import {MockSuckerRegistry} from "./mock/MockSuckerRegistry.sol";
 
 /// @notice Regression tests for REVDeployer.
 contract REVDeployerRegressions is TestBaseWorkflow {
@@ -83,7 +86,14 @@ contract REVDeployerRegressions is TestBaseWorkflow {
         SUCKER_REGISTRY = new JBSuckerRegistry(jbDirectory(), jbPermissions(), multisig(), address(0));
         HOOK_STORE = new JB721TiersHookStore();
         EXAMPLE_HOOK = new JB721TiersHook(
-            jbDirectory(), jbPermissions(), jbPrices(), jbRulesets(), HOOK_STORE, jbSplits(), multisig()
+            jbDirectory(),
+            jbPermissions(),
+            jbPrices(),
+            jbRulesets(),
+            HOOK_STORE,
+            jbSplits(),
+            IJB721CheckpointsDeployer(address(new JB721CheckpointsDeployer())),
+            multisig()
         );
         ADDRESS_REGISTRY = new JBAddressRegistry();
         HOOK_DEPLOYER = new JB721TiersHookDeployer(EXAMPLE_HOOK, HOOK_STORE, ADDRESS_REGISTRY, multisig());
@@ -92,6 +102,7 @@ contract REVDeployerRegressions is TestBaseWorkflow {
 
         LOANS_CONTRACT = new REVLoans({
             controller: jbController(),
+            suckerRegistry: IJBSuckerRegistry(address(new MockSuckerRegistry())),
             revId: FEE_PROJECT_ID,
             owner: address(this),
             permit2: permit2(),

package/test/REVInvincibility.t.sol

@@ -41,6 +41,8 @@ import {JBSuckerRegistry} from "@bananapus/suckers-v6/src/JBSuckerRegistry.sol";
 import {JB721TiersHookDeployer} from "@bananapus/721-hook-v6/src/JB721TiersHookDeployer.sol";
 import {JB721TiersHook} from "@bananapus/721-hook-v6/src/JB721TiersHook.sol";
 import {JB721TiersHookStore} from "@bananapus/721-hook-v6/src/JB721TiersHookStore.sol";
+import {JB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "@bananapus/721-hook-v6/src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JBAddressRegistry} from "@bananapus/address-registry-v6/src/JBAddressRegistry.sol";
 import {IJBAddressRegistry} from "@bananapus/address-registry-v6/src/interfaces/IJBAddressRegistry.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
@@ -50,6 +52,7 @@ import {BrokenFeeTerminal} from "./helpers/MaliciousContracts.sol";
 import {REVEmpty721Config} from "./helpers/REVEmpty721Config.sol";
 import {REVOwner} from "../src/REVOwner.sol";
 import {IREVDeployer} from "../src/interfaces/IREVDeployer.sol";
+import {MockSuckerRegistry} from "./mock/MockSuckerRegistry.sol";
 
 // =========================================================================
 // Shared config struct
@@ -234,7 +237,14 @@ contract REVInvincibility_PropertyTests is TestBaseWorkflow {
         SUCKER_REGISTRY = new JBSuckerRegistry(jbDirectory(), jbPermissions(), multisig(), address(0));
         HOOK_STORE = new JB721TiersHookStore();
         EXAMPLE_HOOK = new JB721TiersHook(
-            jbDirectory(), jbPermissions(), jbPrices(), jbRulesets(), HOOK_STORE, jbSplits(), multisig()
+            jbDirectory(),
+            jbPermissions(),
+            jbPrices(),
+            jbRulesets(),
+            HOOK_STORE,
+            jbSplits(),
+            IJB721CheckpointsDeployer(address(new JB721CheckpointsDeployer())),
+            multisig()
         );
         ADDRESS_REGISTRY = new JBAddressRegistry();
         HOOK_DEPLOYER = new JB721TiersHookDeployer(EXAMPLE_HOOK, HOOK_STORE, ADDRESS_REGISTRY, multisig());
@@ -244,6 +254,7 @@ contract REVInvincibility_PropertyTests is TestBaseWorkflow {
 
         LOANS_CONTRACT = new REVLoans({
             controller: jbController(),
+            suckerRegistry: IJBSuckerRegistry(address(new MockSuckerRegistry())),
             revId: FEE_PROJECT_ID,
             owner: address(this),
             permit2: permit2(),
@@ -1019,7 +1030,14 @@ contract REVInvincibility_Invariants is StdInvariant, TestBaseWorkflow {
         SUCKER_REGISTRY = new JBSuckerRegistry(jbDirectory(), jbPermissions(), multisig(), address(0));
         HOOK_STORE = new JB721TiersHookStore();
         EXAMPLE_HOOK = new JB721TiersHook(
-            jbDirectory(), jbPermissions(), jbPrices(), jbRulesets(), HOOK_STORE, jbSplits(), multisig()
+            jbDirectory(),
+            jbPermissions(),
+            jbPrices(),
+            jbRulesets(),
+            HOOK_STORE,
+            jbSplits(),
+            IJB721CheckpointsDeployer(address(new JB721CheckpointsDeployer())),
+            multisig()
         );
         ADDRESS_REGISTRY = new JBAddressRegistry();
         HOOK_DEPLOYER = new JB721TiersHookDeployer(EXAMPLE_HOOK, HOOK_STORE, ADDRESS_REGISTRY, multisig());
@@ -1028,6 +1046,7 @@ contract REVInvincibility_Invariants is StdInvariant, TestBaseWorkflow {
 
         LOANS_CONTRACT = new REVLoans({
             controller: jbController(),
+            suckerRegistry: IJBSuckerRegistry(address(new MockSuckerRegistry())),
             revId: FEE_PROJECT_ID,
             owner: address(this),
             permit2: permit2(),