@rev-net/core-v6 0.0.43 → 0.0.45

package/README.md

@@ -72,7 +72,7 @@ Most mistakes come from assuming a deploy-time parameter can be changed later or
 2. `test/REVLoans.invariants.t.sol`
 3. `test/TestLongTailEconomics.t.sol`
 4. `test/fork/TestLoanBorrowFork.t.sol`
-5. `test/audit/PhantomSurplusTerminal.t.sol`
+5. `test/regression/PhantomSurplusTerminal.t.sol`
 
 ## Install
 
@@ -108,7 +108,7 @@ src/
   interfaces/
   structs/
 test/
-  lifecycle, deployment, loan, fork, invariant, audit, and regression coverage
+  lifecycle, deployment, loan, fork, invariant, review, and regression coverage
 script/
   Deploy.s.sol
   helpers/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rev-net/core-v6",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "dependencies": {
     "@bananapus/721-hook-v6": "0.0.43",
     "@bananapus/buyback-hook-v6": "0.0.37",
-    "@bananapus/core-v6": "0.0.42",
+    "@bananapus/core-v6": "0.0.44",
     "@bananapus/ownable-v6": "0.0.24",
     "@bananapus/permission-ids-v6": "0.0.22",
     "@bananapus/router-terminal-v6": "0.0.36",

package/references/operations.md

@@ -266,6 +266,7 @@ REVConfig memory config = REVConfig({
     }),
     baseCurrency: 1,                       // ETH
     splitOperator: msg.sender,
+    scopeCashOutsToLocalBalances: false,
     stageConfigurations: stages
 });
 

package/script/Deploy.s.sol

@@ -271,6 +271,7 @@ contract DeployScript is Script, Sphinx {
             description: REVDescription({name: NAME, ticker: SYMBOL, uri: PROJECT_URI, salt: ERC20_SALT}),
             baseCurrency: ETH_CURRENCY,
             splitOperator: OPERATOR,
+            scopeCashOutsToLocalBalances: false,
             stageConfigurations: stageConfigurations
         });
 
@@ -497,7 +498,8 @@ contract DeployScript is Script, Sphinx {
                 feeRevnetId: FEE_PROJECT_ID,
                 suckerRegistry: suckers.registry,
                 loans: revloans,
-                hiddenTokens: revHiddenTokens
+                hiddenTokens: revHiddenTokens,
+                deployerBinder: msg.sender
             });
 
         // Deploy REVDeployer with the REVLoans, buyback hook, and REVOwner addresses.

package/src/REVDeployer.sol

@@ -57,15 +57,15 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error REVDeployer_AutoIssuanceBeneficiaryZeroAddress();
+    error REVDeployer_AutoIssuanceBeneficiaryZeroAddress(uint256 stageIndex, uint256 autoIssuanceIndex);
     error REVDeployer_CashOutsCantBeTurnedOffCompletely(uint256 cashOutTaxRate, uint256 maxCashOutTaxRate);
-    error REVDeployer_MustHaveSplits();
-    error REVDeployer_NothingToAutoIssue();
-    error REVDeployer_NothingToBurn();
-    error REVDeployer_RulesetDoesNotAllowDeployingSuckers();
+    error REVDeployer_MustHaveSplits(uint256 stageIndex, uint256 splitPercent);
+    error REVDeployer_NothingToAutoIssue(uint256 revnetId, uint256 stageId, address beneficiary);
+    error REVDeployer_NothingToBurn(uint256 revnetId, address holder);
+    error REVDeployer_RulesetDoesNotAllowDeployingSuckers(uint256 revnetId);
     error REVDeployer_StageNotStarted(uint256 stageId);
-    error REVDeployer_StagesRequired();
-    error REVDeployer_StageTimesMustIncrease();
+    error REVDeployer_StagesRequired(uint256 stageCount);
+    error REVDeployer_StageTimesMustIncrease(uint256 stageIndex, uint256 previousStageStart, uint256 effectiveStart);
     error REVDeployer_Unauthorized(uint256 revnetId, address caller);
 
     //*********************************************************************//
@@ -164,7 +164,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @notice A list of `JBPermissonIds` indices to grant to the split operator of a specific revnet.
     /// @dev These should be set in the revnet's deployment process.
     /// @custom:param revnetId The ID of the revnet to look up.
-    // slither-disable-next-line uninitialized-state
     mapping(uint256 revnetId => uint256[]) internal _extraOperatorPermissions;
 
     //*********************************************************************//
@@ -203,7 +202,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         PUBLISHER = publisher;
         BUYBACK_HOOK = buybackHook;
         LOANS = loans;
-        // slither-disable-next-line missing-zero-check
         OWNER = owner;
 
         // Give the loan contract permission to use the surplus allowance of all revnets.
@@ -262,7 +260,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @param operator The address to check.
     function _checkIfIsSplitOperatorOf(uint256 revnetId, address operator) internal view {
         if (!isSplitOperatorOf({revnetId: revnetId, addr: operator})) {
-            revert REVDeployer_Unauthorized(revnetId, operator);
+            revert REVDeployer_Unauthorized({revnetId: revnetId, caller: operator});
         }
     }
 
@@ -318,11 +316,13 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
     /// @notice Make a ruleset configuration for a revnet's stage.
     /// @param baseCurrency The base currency of the revnet.
+    /// @param scopeCashOutsToLocalBalances If true, cash-out calculations use only the local terminal's surplus.
     /// @param stageConfiguration The stage configuration to build a ruleset from.
     /// @param fundAccessLimitGroups The fund access limit groups to include in the ruleset.
     /// @return rulesetConfiguration The ruleset configuration.
     function _makeRulesetConfiguration(
         uint32 baseCurrency,
+        bool scopeCashOutsToLocalBalances,
         REVStageConfig calldata stageConfiguration,
         JBFundAccessLimitGroup[] memory fundAccessLimitGroups
     )
@@ -335,7 +335,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         metadata.reservedPercent = stageConfiguration.splitPercent;
         metadata.cashOutTaxRate = stageConfiguration.cashOutTaxRate;
         metadata.baseCurrency = baseCurrency;
-        metadata.useTotalSurplusForCashOuts = true; // Use surplus from all terminals for cash outs.
+        metadata.scopeCashOutsToLocalBalances = scopeCashOutsToLocalBalances;
         metadata.allowOwnerMinting = true; // Allow this contract to auto-mint tokens as the revnet's owner.
         metadata.useDataHookForPay = true; // Call this contract's `beforePayRecordedWith(…)` callback on payments.
         metadata.useDataHookForCashOut = true; // Call this contract's `beforeCashOutRecordedWith(…)` callback on cash
@@ -399,29 +399,36 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// Silently catches failures (e.g., if the pool is already initialized).
     /// @param revnetId The ID of the revnet to initialize a pool for.
     /// @param terminalToken The terminal token to create a buyback pool for.
+    /// @param terminalTokenDecimals The number of decimals the terminal token uses.
     /// @param initialIssuance The initial issuance rate (project tokens per terminal token, 18 decimals).
-    function _tryInitializeBuybackPoolFor(uint256 revnetId, address terminalToken, uint112 initialIssuance) internal {
+    function _tryInitializeBuybackPoolFor(
+        uint256 revnetId,
+        address terminalToken,
+        uint8 terminalTokenDecimals,
+        uint112 initialIssuance
+    )
+        internal
+    {
         uint160 sqrtPriceX96;
+        uint256 terminalTokenUnit = 10 ** terminalTokenDecimals;
 
         if (initialIssuance == 0) {
             sqrtPriceX96 = uint160(1 << 96);
         } else {
             address normalizedTerminalToken = terminalToken == JBConstants.NATIVE_TOKEN ? address(0) : terminalToken;
-            // slither-disable-next-line calls-loop
             address projectToken = address(CONTROLLER.TOKENS().tokenOf(revnetId));
 
             if (projectToken == address(0) || projectToken == normalizedTerminalToken) {
                 sqrtPriceX96 = uint160(1 << 96);
             } else if (normalizedTerminalToken < projectToken) {
-                // token0 = terminal, token1 = project → price = issuance / 1e18
-                sqrtPriceX96 = uint160(sqrt(mulDiv(uint256(initialIssuance), 1 << 192, 1e18)));
+                // token0 = terminal, token1 = project → price = issuance / terminalTokenUnit
+                sqrtPriceX96 = uint160(sqrt(mulDiv(uint256(initialIssuance), 1 << 192, terminalTokenUnit)));
             } else {
-                // token0 = project, token1 = terminal → price = 1e18 / issuance
-                sqrtPriceX96 = uint160(sqrt(mulDiv(1e18, 1 << 192, uint256(initialIssuance))));
+                // token0 = project, token1 = terminal → price = terminalTokenUnit / issuance
+                sqrtPriceX96 = uint160(sqrt(mulDiv(terminalTokenUnit, 1 << 192, uint256(initialIssuance))));
             }
         }
 
-        // slither-disable-next-line calls-loop
         try BUYBACK_HOOK.initializePoolFor({
             projectId: revnetId,
             fee: DEFAULT_BUYBACK_POOL_FEE,
@@ -449,19 +456,21 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // IDs `block.timestamp`, `block.timestamp + 1`, ... exactly correspond to the JB-assigned ruleset IDs.
         // The returned `ruleset.start` contains the derived start time (from `deriveStartFrom` using the stage's
         // `mustStartAtOrAfter`), NOT the queue timestamp — so the timing guard correctly blocks early claims.
-        // slither-disable-next-line unused-return
         (JBRuleset memory ruleset,) = CONTROLLER.getRulesetOf({projectId: revnetId, rulesetId: stageId});
 
         // Make sure the stage has started.
+        // forge-lint: disable-next-line(block-timestamp)
         if (ruleset.start > block.timestamp) {
-            revert REVDeployer_StageNotStarted(stageId);
+            revert REVDeployer_StageNotStarted({stageId: stageId});
         }
 
         // Get a reference to the number of tokens to auto-issue.
         uint256 count = amountToAutoIssue[revnetId][stageId][beneficiary];
 
         // If there's nothing to auto-mint, return.
-        if (count == 0) revert REVDeployer_NothingToAutoIssue();
+        if (count == 0) {
+            revert REVDeployer_NothingToAutoIssue({revnetId: revnetId, stageId: stageId, beneficiary: beneficiary});
+        }
 
         // Reset the auto-mint amount.
         amountToAutoIssue[revnetId][stageId][beneficiary] = 0;
@@ -471,7 +480,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         });
 
         // Mint the tokens.
-        // slither-disable-next-line unused-return
         CONTROLLER.mintTokensOf({
             projectId: revnetId, tokenCount: count, beneficiary: beneficiary, memo: "", useReservedPercent: false
         });
@@ -482,10 +490,9 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @param revnetId The ID of the revnet to burn tokens for.
     function burnHeldTokensOf(uint256 revnetId) external override {
         uint256 balance = CONTROLLER.TOKENS().totalBalanceOf({holder: address(this), projectId: revnetId});
-        if (balance == 0) revert REVDeployer_NothingToBurn();
+        if (balance == 0) revert REVDeployer_NothingToBurn({revnetId: revnetId, holder: address(this)});
         CONTROLLER.burnTokensOf({holder: address(this), projectId: revnetId, tokenCount: balance, memo: ""});
-        // slither-disable-next-line reentrancy-events
-        emit BurnHeldTokens(revnetId, balance, _msgSender());
+        emit BurnHeldTokens({revnetId: revnetId, count: balance, caller: _msgSender()});
     }
 
     /// @notice Launch a revnet, or initialize an existing Juicebox project as a revnet.
@@ -506,7 +513,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @return revnetId The ID of the newly created revnet.
     /// @return hook The address of the tiered ERC-721 hook deployed for the revnet.
     // The deployment flow makes external setup calls, but any observed state is revnet-scoped and reverts atomically.
-    // slither-disable-next-line reentrancy-benign
     function deployFor(
         uint256 revnetId,
         REVConfig calldata configuration,
@@ -541,7 +547,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
     /// @inheritdoc IREVDeployer
     // The deployment flow makes external setup calls, but any observed state is revnet-scoped and reverts atomically.
-    // slither-disable-next-line reentrancy-benign
     function deployFor(
         uint256 revnetId,
         REVConfig calldata configuration,
@@ -610,14 +615,13 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         _checkIfIsSplitOperatorOf({revnetId: revnetId, operator: _msgSender()});
 
         // Check if the current ruleset allows deploying new suckers.
-        // slither-disable-next-line unused-return
         (, JBRulesetMetadata memory metadata) = CONTROLLER.currentRulesetOf(revnetId);
 
         // Check the third bit, it indicates if the ruleset allows new suckers to be deployed.
         bool allowsDeployingSuckers = ((metadata.metadata >> 2) & 1) == 1;
 
         if (!allowsDeployingSuckers) {
-            revert REVDeployer_RulesetDoesNotAllowDeployingSuckers();
+            revert REVDeployer_RulesetDoesNotAllowDeployingSuckers({revnetId: revnetId});
         }
 
         // Deploy the suckers.
@@ -655,7 +659,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
     /// @notice Deploy a revnet which sells tiered ERC-721s and (optionally) allows croptop posts to its ERC-721 tiers.
     // The helper performs external hook/post setup after core revnet setup; any failure reverts the whole deployment.
-    // slither-disable-next-line reentrancy-benign
     function _deploy721RevnetFor(
         uint256 revnetId,
         bool shouldDeployNewRevnet,
@@ -814,12 +817,10 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         if (!shouldDeployNewRevnet) {
             // Initialize the existing Juicebox project as a revnet by transferring the `JBProjects` NFT to this
             // deployer. This is irreversible.
-            // slither-disable-next-line reentrancy-benign
             IERC721(PROJECTS).safeTransferFrom({from: owner, to: address(this), tokenId: revnetId});
         }
 
         // Launch the revnet rulesets for the reserved or pre-existing blank project.
-        // slither-disable-next-line unused-return
         CONTROLLER.launchRulesetsFor({
             projectId: revnetId,
             projectUri: configuration.description.uri,
@@ -831,11 +832,9 @@ 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.
-        // slither-disable-next-line unused-return
         CONTROLLER.deployERC20For({
             projectId: revnetId,
             name: configuration.description.name,
@@ -847,10 +846,10 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         for (uint256 i; i < terminalConfigurations.length;) {
             JBTerminalConfig calldata terminalConfiguration = terminalConfigurations[i];
             for (uint256 j; j < terminalConfiguration.accountingContextsToAccept.length;) {
-                // slither-disable-next-line calls-loop
                 _tryInitializeBuybackPoolFor({
                     revnetId: revnetId,
                     terminalToken: terminalConfiguration.accountingContextsToAccept[j].token,
+                    terminalTokenDecimals: terminalConfiguration.accountingContextsToAccept[j].decimals,
                     initialIssuance: configuration.stageConfigurations[0].initialIssuance
                 });
                 unchecked {
@@ -901,7 +900,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
         // Include the caller so two revnets with identical configuration and user salt cannot collide. Same-address
         // cross-chain deployment still works when the same operator calls this helper on each chain.
-        // slither-disable-next-line unused-return
         suckers = SUCKER_REGISTRY.deploySuckersFor({
             projectId: revnetId,
             salt: keccak256(abi.encode(encodedConfigurationHash, suckerDeploymentConfiguration.salt, _msgSender())),
@@ -934,7 +932,9 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         returns (JBRulesetConfig[] memory rulesetConfigurations, bytes32 encodedConfigurationHash)
     {
         // If there are no stages, revert.
-        if (configuration.stageConfigurations.length == 0) revert REVDeployer_StagesRequired();
+        if (configuration.stageConfigurations.length == 0) {
+            revert REVDeployer_StagesRequired({stageCount: configuration.stageConfigurations.length});
+        }
 
         // Initialize the array of rulesets.
         rulesetConfigurations = new JBRulesetConfig[](configuration.stageConfigurations.length);
@@ -942,6 +942,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // Add the base configuration to the byte-encoded configuration.
         bytes memory encodedConfiguration = abi.encode(
             configuration.baseCurrency,
+            configuration.scopeCashOutsToLocalBalances,
             configuration.description.name,
             configuration.description.ticker,
             configuration.description.salt
@@ -975,7 +976,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             // Make sure the revnet has at least one split if it has a split percent.
             // Otherwise, the split would go to this contract since its the revnet's owner.
             if (stageConfiguration.splitPercent > 0 && stageConfiguration.splits.length == 0) {
-                revert REVDeployer_MustHaveSplits();
+                revert REVDeployer_MustHaveSplits({stageIndex: i, splitPercent: stageConfiguration.splitPercent});
             }
 
             // Compute the effective start time for this stage.
@@ -985,7 +986,9 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
             // If the stage's start time is not after the previous stage's start time, revert.
             if (i > 0 && effectiveStart <= previousStageStart) {
-                revert REVDeployer_StageTimesMustIncrease();
+                revert REVDeployer_StageTimesMustIncrease({
+                    stageIndex: i, previousStageStart: previousStageStart, effectiveStart: effectiveStart
+                });
             }
 
             // Store for the next iteration's ordering check.
@@ -993,14 +996,16 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
             // Make sure the revnet doesn't prevent cashouts all together.
             if (stageConfiguration.cashOutTaxRate >= JBConstants.MAX_CASH_OUT_TAX_RATE) {
-                revert REVDeployer_CashOutsCantBeTurnedOffCompletely(
-                    stageConfiguration.cashOutTaxRate, JBConstants.MAX_CASH_OUT_TAX_RATE
-                );
+                revert REVDeployer_CashOutsCantBeTurnedOffCompletely({
+                    cashOutTaxRate: stageConfiguration.cashOutTaxRate,
+                    maxCashOutTaxRate: JBConstants.MAX_CASH_OUT_TAX_RATE
+                });
             }
 
             // Set up the ruleset.
             rulesetConfigurations[i] = _makeRulesetConfiguration({
                 baseCurrency: configuration.baseCurrency,
+                scopeCashOutsToLocalBalances: configuration.scopeCashOutsToLocalBalances,
                 stageConfiguration: stageConfiguration,
                 fundAccessLimitGroups: fundAccessLimitGroups
             });
@@ -1027,7 +1032,9 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
                 REVAutoIssuance calldata autoIssuance = stageConfiguration.autoIssuances[j];
 
                 // Make sure the beneficiary is not the zero address.
-                if (autoIssuance.beneficiary == address(0)) revert REVDeployer_AutoIssuanceBeneficiaryZeroAddress();
+                if (autoIssuance.beneficiary == address(0)) {
+                    revert REVDeployer_AutoIssuanceBeneficiaryZeroAddress({stageIndex: i, autoIssuanceIndex: j});
+                }
 
                 // If there's nothing to auto-mint, continue.
                 if (autoIssuance.count == 0) continue;
@@ -1039,7 +1046,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
                 // If the issuance config is for another chain, skip it.
                 if (autoIssuance.chainId != block.chainid) continue;
 
-                // slither-disable-next-line reentrancy-events
                 emit StoreAutoIssuanceAmount({
                     revnetId: revnetId,
                     stageId: block.timestamp + i,
@@ -1054,7 +1060,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
                 // (JBRulesets.sol L172), producing the same sequential IDs when all stages are queued in one tx.
                 // `autoIssueFor` later calls `getRulesetOf(revnetId, stageId)` — the returned `ruleset.start`
                 // is the derived start time (not the queue time), so the timing guard works correctly.
-                // slither-disable-next-line reentrancy-benign
                 amountToAutoIssue[revnetId][block.timestamp + i][autoIssuance.beneficiary] += autoIssuance.count;
             }
             unchecked {
@@ -1073,13 +1078,13 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     function _setCashOutDelayIfNeeded(uint256 revnetId, REVStageConfig calldata firstStageConfig) internal {
         // If this is the first revnet being deployed (with a `startsAtOrAfter` of 0),
         // or if the first stage hasn't started yet, we don't need to set a cash out delay.
+        // forge-lint: disable-next-line(block-timestamp)
         if (firstStageConfig.startsAtOrAfter == 0 || firstStageConfig.startsAtOrAfter >= block.timestamp) return;
 
         // Calculate the timestamp at which the cash out delay ends.
         uint256 cashOutDelay = block.timestamp + CASH_OUT_DELAY;
 
         // Store the cash out delay in the owner contract.
-        // slither-disable-next-line reentrancy-events
         REVOwner(OWNER).setCashOutDelayOf({revnetId: revnetId, cashOutDelay: cashOutDelay});
 
         emit SetCashOutDelay({revnetId: revnetId, cashOutDelay: cashOutDelay, caller: _msgSender()});

package/src/REVHiddenTokens.sol

@@ -85,7 +85,7 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
             _hasPermissionFrom(caller, PROJECTS.ownerOf(revnetId), revnetId, JBPermissionIds.HIDE_TOKENS);
 
         if (!isAllowlistedHolder && !isPermissionedOperator) {
-            revert REVHiddenTokens_Unauthorized(revnetId, caller);
+            revert REVHiddenTokens_Unauthorized({revnetId: revnetId, caller: caller});
         }
 
         // Increment the holder's hidden balance.
@@ -95,7 +95,6 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
         totalHiddenOf[revnetId] += tokenCount;
 
         // Burn the tokens from the holder. The holder must have granted BURN_TOKENS permission.
-        // slither-disable-next-line reentrancy-events
         CONTROLLER.burnTokensOf({holder: holder, projectId: revnetId, tokenCount: tokenCount, memo: ""});
 
         emit HideTokens({revnetId: revnetId, tokenCount: tokenCount, holder: holder, caller: _msgSender()});
@@ -125,7 +124,6 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
         totalHiddenOf[revnetId] -= tokenCount;
 
         // Mint the tokens to the beneficiary without applying the reserved percent.
-        // slither-disable-next-line unused-return,reentrancy-events
         CONTROLLER.mintTokensOf({
             projectId: revnetId, tokenCount: tokenCount, beneficiary: holder, memo: "", useReservedPercent: false
         });

package/src/REVLoans.sol

@@ -61,19 +61,21 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     error REVLoans_InvalidPrepaidFeePercent(uint256 prepaidFeePercent, uint256 min, uint256 max);
     error REVLoans_InvalidTerminal(address terminal, uint256 revnetId);
     error REVLoans_LoanExpired(uint256 timeSinceLoanCreated, uint256 loanLiquidationDuration);
-    error REVLoans_LoanIdOverflow();
+    error REVLoans_LoanIdOverflow(uint256 revnetId, uint256 loanNumber, uint256 maxLoanNumber);
     error REVLoans_NewBorrowAmountGreaterThanLoanAmount(uint256 newBorrowAmount, uint256 loanAmount);
-    error REVLoans_NoMsgValueAllowed();
-    error REVLoans_NotEnoughCollateral();
-    error REVLoans_NothingToRepay();
+    error REVLoans_NoMsgValueAllowed(uint256 msgValue, address token);
+    error REVLoans_NotEnoughCollateral(uint256 collateralCountToRemove, uint256 loanCollateral);
+    error REVLoans_NothingToRepay(uint256 repayBorrowAmount, uint256 collateralCountToReturn);
     error REVLoans_OverMaxRepayBorrowAmount(uint256 maxRepayBorrowAmount, uint256 repayBorrowAmount);
     error REVLoans_OverflowAlert(uint256 value, uint256 limit);
     error REVLoans_PermitAllowanceNotEnough(uint256 allowanceAmount, uint256 requiredAmount);
     error REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows(uint256 newBorrowAmount, uint256 loanAmount);
-    error REVLoans_SourceMismatch();
+    error REVLoans_SourceMismatch(
+        address expectedToken, address actualToken, address expectedTerminal, address actualTerminal
+    );
     error REVLoans_UnderMinBorrowAmount(uint256 minBorrowAmount, uint256 borrowAmount);
-    error REVLoans_ZeroBorrowAmount();
-    error REVLoans_ZeroCollateralLoanIsInvalid();
+    error REVLoans_ZeroBorrowAmount(uint256 revnetId, uint256 collateralCount);
+    error REVLoans_ZeroCollateralLoanIsInvalid(uint256 collateralCount);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -229,6 +231,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         JBRuleset memory currentRuleset = _currentRulesetOf(revnetId);
 
         // If the cash out delay hasn't passed yet, no amount is borrowable.
+        // forge-lint: disable-next-line(block-timestamp)
         if (_cashOutDelayOf({revnetId: revnetId, currentRuleset: currentRuleset}) > block.timestamp) return 0;
 
         return _borrowableAmountFrom({
@@ -369,14 +372,19 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // 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.
-        // Add cross-chain remote values for proportional reclaim.
-        uint256 omnichainSurplus = localSurplus
-            + SUCKER_REGISTRY.remoteSurplusOf({projectId: revnetId, decimals: decimals, currency: currency});
-        uint256 omnichainSupply = localSupply + SUCKER_REGISTRY.remoteTotalSupplyOf(revnetId);
+        // Start with local values. If the ruleset aggregates cross-chain state, add remote supply and surplus.
+        uint256 effectiveSurplus = localSurplus;
+        uint256 effectiveSupply = localSupply;
+        if (!currentStage.scopeCashOutsToLocalBalances()) {
+            effectiveSurplus += SUCKER_REGISTRY.remoteSurplusOf({
+                projectId: revnetId, decimals: decimals, currency: currency
+            });
+            effectiveSupply += SUCKER_REGISTRY.remoteTotalSupplyOf(revnetId);
+        }
         uint256 reclaimable = JBCashOuts.cashOutFrom({
-            surplus: omnichainSurplus,
+            surplus: effectiveSurplus,
             cashOutCount: collateralCount,
-            totalSupply: omnichainSupply,
+            totalSupply: effectiveSupply,
             cashOutTaxRate: currentStage.cashOutTaxRate()
         });
         // Cap at local surplus — can't borrow more than what this chain's terminals actually hold.
@@ -443,7 +451,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @param revnetId The ID of the revnet.
     /// @return currentRuleset The current ruleset.
     function _currentRulesetOf(uint256 revnetId) internal view returns (JBRuleset memory currentRuleset) {
-        // slither-disable-next-line unused-return
         (currentRuleset,) = CONTROLLER.currentRulesetOf(revnetId);
     }
 
@@ -462,7 +469,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Uses `>` (not `>=`) so the exact boundary second is still repayable — the liquidation path
         // uses `<=`, and matching `>=` here would create a 1-second window where neither path is available.
         if (timeSinceLoanCreated > LOAN_LIQUIDATION_DURATION) {
-            revert REVLoans_LoanExpired(timeSinceLoanCreated, LOAN_LIQUIDATION_DURATION);
+            revert REVLoans_LoanExpired({
+                timeSinceLoanCreated: timeSinceLoanCreated, loanLiquidationDuration: LOAN_LIQUIDATION_DURATION
+            });
         }
 
         // Get a reference to the amount prepaid for the full loan.
@@ -548,7 +557,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             if (tokensLoaned == 0) continue;
 
             // Get a reference to the accounting context for the source.
-            // slither-disable-next-line calls-loop
             JBAccountingContext memory accountingContext =
                 source.terminal.accountingContextForTokenOf({projectId: revnetId, token: source.token});
 
@@ -567,7 +575,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
                 borrowedAmount += normalizedTokens;
             } else {
                 // Otherwise, convert via the price feed.
-                // slither-disable-next-line calls-loop
                 uint256 pricePerUnit = PRICES.pricePerUnitOf({
                     projectId: revnetId,
                     pricingCurrency: accountingContext.currency,
@@ -649,7 +656,12 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @param count The number of loans to iterate over.
     function liquidateExpiredLoansFrom(uint256 revnetId, uint256 startingLoanId, uint256 count) external override {
         // Prevent cross-revnet accounting corruption: loan numbers must stay within the revnet's ID namespace.
-        if (startingLoanId + count > _ONE_TRILLION) revert REVLoans_LoanIdOverflow();
+        uint256 endLoanNumber = startingLoanId + count;
+        if (endLoanNumber > _ONE_TRILLION) {
+            revert REVLoans_LoanIdOverflow({
+                revnetId: revnetId, loanNumber: endLoanNumber, maxLoanNumber: _ONE_TRILLION
+            });
+        }
 
         // Cache the sender to avoid repeated ERC2771 context reads inside the loop.
         address sender = _msgSender();
@@ -660,7 +672,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             uint256 loanId = _generateLoanId({revnetId: revnetId, loanNumber: startingLoanId + i});
 
             // Check createdAt via storage ref first to avoid loading the full struct for empty slots.
-            // slither-disable-next-line incorrect-equality
             if (_loanOf[loanId].createdAt == 0) continue;
 
             // Get a reference to the loan being iterated on.
@@ -670,6 +681,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             address owner = _ownerOf(loanId);
 
             // If the loan is already burned, or if it hasn't passed its liquidation duration, continue.
+            // forge-lint: disable-next-line(block-timestamp)
             if (owner == address(0) || (block.timestamp <= loan.createdAt + LOAN_LIQUIDATION_DURATION)) continue;
 
             // Burn the loan.
@@ -735,15 +747,24 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         _requirePermissionFrom({account: loanOwner, projectId: revnetId, permissionId: JBPermissionIds.REALLOCATE_LOAN});
 
         // Make sure the loan hasn't expired.
+        // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp - _loanOf[loanId].createdAt > LOAN_LIQUIDATION_DURATION) {
-            revert REVLoans_LoanExpired(block.timestamp - _loanOf[loanId].createdAt, LOAN_LIQUIDATION_DURATION);
+            revert REVLoans_LoanExpired({
+                timeSinceLoanCreated: block.timestamp - _loanOf[loanId].createdAt,
+                loanLiquidationDuration: LOAN_LIQUIDATION_DURATION
+            });
         }
 
         // Make sure the new loan's source matches the existing loan's source to prevent cross-source value extraction.
         {
             REVLoanSource storage existingSource = _loanOf[loanId].source;
             if (source.token != existingSource.token || source.terminal != existingSource.terminal) {
-                revert REVLoans_SourceMismatch();
+                revert REVLoans_SourceMismatch({
+                    expectedToken: existingSource.token,
+                    actualToken: source.token,
+                    expectedTerminal: address(existingSource.terminal),
+                    actualTerminal: address(source.terminal)
+                });
             }
         }
 
@@ -806,7 +827,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         REVLoan storage loan = _loanOf[loanId];
 
         if (collateralCountToReturn > loan.collateral) {
-            revert REVLoans_CollateralExceedsLoan(collateralCountToReturn, loan.collateral);
+            revert REVLoans_CollateralExceedsLoan({
+                collateralToReturn: collateralCountToReturn, loanCollateral: loan.collateral
+            });
         }
 
         // Get a reference to the revnet ID of the loan being repaid.
@@ -833,7 +856,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
             // Make sure the new borrow amount is less than the loan's amount.
             if (newBorrowAmount > loan.amount) {
-                revert REVLoans_NewBorrowAmountGreaterThanLoanAmount(newBorrowAmount, loan.amount);
+                revert REVLoans_NewBorrowAmountGreaterThanLoanAmount({
+                    newBorrowAmount: newBorrowAmount, loanAmount: loan.amount
+                });
             }
 
             // Get the amount of the loan being repaid.
@@ -843,7 +868,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Revert if this repayment would do nothing — no borrow amount repaid and no collateral returned.
         // Without this check, a zero-amount repayment would burn the old loan NFT and mint a new one,
         // incrementing totalLoansBorrowedFor without limit.
-        if (repayBorrowAmount == 0 && collateralCountToReturn == 0) revert REVLoans_NothingToRepay();
+        if (repayBorrowAmount == 0 && collateralCountToReturn == 0) {
+            revert REVLoans_NothingToRepay({
+                repayBorrowAmount: repayBorrowAmount, collateralCountToReturn: collateralCountToReturn
+            });
+        }
 
         // Keep a reference to the fee that'll be taken.
         uint256 sourceFeeAmount = _determineSourceFeeAmount({loan: loan, amount: repayBorrowAmount});
@@ -857,7 +886,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
         // Make sure the minimum borrow amount is met.
         if (repayBorrowAmount > maxRepayBorrowAmount) {
-            revert REVLoans_OverMaxRepayBorrowAmount(maxRepayBorrowAmount, repayBorrowAmount);
+            revert REVLoans_OverMaxRepayBorrowAmount({
+                maxRepayBorrowAmount: maxRepayBorrowAmount, repayBorrowAmount: repayBorrowAmount
+            });
         }
 
         // Cache the source token before _repayLoan deletes the loan storage.
@@ -915,13 +946,13 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         if (token == JBConstants.NATIVE_TOKEN) return msg.value;
 
         // If the token is not native, revert if there is a non-zero `msg.value`.
-        if (msg.value != 0) revert REVLoans_NoMsgValueAllowed();
+        if (msg.value != 0) revert REVLoans_NoMsgValueAllowed({msgValue: msg.value, token: token});
 
         // Check if the metadata contains permit data.
         if (allowance.amount != 0) {
             // Make sure the permit allowance is enough for this payment. If not we revert early.
             if (allowance.amount < amount) {
-                revert REVLoans_PermitAllowanceNotEnough(allowance.amount, amount);
+                revert REVLoans_PermitAllowanceNotEnough({allowanceAmount: allowance.amount, requiredAmount: amount});
             }
 
             // Keep a reference to the permit rules.
@@ -995,7 +1026,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
                 loan.source.terminal.accountingContextForTokenOf({projectId: revnetId, token: loan.source.token});
 
             // Pull the amount to be loaned out of the revnet. This will incure the protocol fee.
-            // slither-disable-next-line unused-return
             netAmountPaidOut = loan.source.terminal
                 .useAllowanceOf({
                     projectId: revnetId,
@@ -1083,7 +1113,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Any reentrant call will see the updated loan values, reverting on overflow.
         if (newBorrowAmount > type(uint112).max) revert REVLoans_OverflowAlert(newBorrowAmount, type(uint112).max);
         if (newCollateralCount > type(uint112).max) {
-            revert REVLoans_OverflowAlert(newCollateralCount, type(uint112).max);
+            revert REVLoans_OverflowAlert({value: newCollateralCount, limit: type(uint112).max});
         }
         // forge-lint: disable-next-line(unsafe-typecast)
         loan.amount = uint112(newBorrowAmount);
@@ -1177,20 +1207,20 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         returns (uint256 loanId, REVLoan memory)
     {
         // A loan needs to have collateral.
-        if (collateralCount == 0) revert REVLoans_ZeroCollateralLoanIsInvalid();
+        if (collateralCount == 0) revert REVLoans_ZeroCollateralLoanIsInvalid({collateralCount: collateralCount});
 
         // Make sure the source terminal is registered in the directory for this revnet.
         if (!DIRECTORY.isTerminalOf({projectId: revnetId, terminal: IJBTerminal(address(source.terminal))})) {
-            revert REVLoans_InvalidTerminal(address(source.terminal), revnetId);
+            revert REVLoans_InvalidTerminal({terminal: address(source.terminal), revnetId: revnetId});
         }
 
         // Make sure the prepaid fee percent is between `MIN_PREPAID_FEE_PERCENT` and `MAX_PREPAID_FEE_PERCENT`. Meaning
         // an 16 year loan can be paid upfront with a
         // payment of 50% of the borrowed assets, the cheapest possible rate.
         if (prepaidFeePercent < MIN_PREPAID_FEE_PERCENT || prepaidFeePercent > MAX_PREPAID_FEE_PERCENT) {
-            revert REVLoans_InvalidPrepaidFeePercent(
-                prepaidFeePercent, MIN_PREPAID_FEE_PERCENT, MAX_PREPAID_FEE_PERCENT
-            );
+            revert REVLoans_InvalidPrepaidFeePercent({
+                prepaidFeePercent: prepaidFeePercent, min: MIN_PREPAID_FEE_PERCENT, max: MAX_PREPAID_FEE_PERCENT
+            });
         }
 
         // Cache the current ruleset once — used by both _cashOutDelayOf and _borrowAmountFrom.
@@ -1199,16 +1229,14 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Enforce the cash out delay.
         {
             uint256 cashOutDelay = _cashOutDelayOf({revnetId: revnetId, currentRuleset: currentRuleset});
+            // forge-lint: disable-next-line(block-timestamp)
             if (cashOutDelay > block.timestamp) {
-                revert REVLoans_CashOutDelayNotFinished(cashOutDelay, block.timestamp);
+                revert REVLoans_CashOutDelayNotFinished({cashOutDelay: cashOutDelay, blockTimestamp: block.timestamp});
             }
         }
 
-        // Prevent the loan number from exceeding the ID namespace for this revnet.
-        if (totalLoansBorrowedFor[revnetId] >= _ONE_TRILLION) revert REVLoans_LoanIdOverflow();
-
         // Get a reference to the loan ID.
-        loanId = _generateLoanId({revnetId: revnetId, loanNumber: ++totalLoansBorrowedFor[revnetId]});
+        loanId = _nextLoanIdFor(revnetId);
 
         // Get a reference to the loan being created.
         REVLoan storage loan = _loanOf[loanId];
@@ -1227,7 +1255,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         });
 
         // Revert if the bonding curve returns zero to prevent creating zero-amount loans.
-        if (borrowAmount == 0) revert REVLoans_ZeroBorrowAmount();
+        if (borrowAmount == 0) {
+            revert REVLoans_ZeroBorrowAmount({revnetId: revnetId, collateralCount: collateralCount});
+        }
 
         // Make sure the minimum borrow amount is met.
         if (borrowAmount < minBorrowAmount) revert REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount);
@@ -1264,6 +1294,18 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         return (loanId, loan);
     }
 
+    /// @notice Allocate the next loan ID for a revnet.
+    /// @param revnetId The ID of the revnet.
+    /// @return loanId The allocated loan ID.
+    function _nextLoanIdFor(uint256 revnetId) internal returns (uint256 loanId) {
+        uint256 loanNumber = totalLoansBorrowedFor[revnetId] + 1;
+        if (loanNumber > _ONE_TRILLION) {
+            revert REVLoans_LoanIdOverflow({revnetId: revnetId, loanNumber: loanNumber, maxLoanNumber: _ONE_TRILLION});
+        }
+        totalLoansBorrowedFor[revnetId] = loanNumber;
+        return _generateLoanId({revnetId: revnetId, loanNumber: loanNumber});
+    }
+
     /// @notice Reallocate collateral from a loan by making a new loan based on the original, with reduced collateral.
     /// @param loanId The ID of the loan to reallocate collateral from.
     /// @param revnetId The ID of the revnet the loan is from.
@@ -1286,7 +1328,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         REVLoan storage loan = _loanOf[loanId];
 
         // Make sure there is enough collateral to transfer.
-        if (collateralCountToRemove > loan.collateral) revert REVLoans_NotEnoughCollateral();
+        if (collateralCountToRemove > loan.collateral) {
+            revert REVLoans_NotEnoughCollateral({
+                collateralCountToRemove: collateralCountToRemove, loanCollateral: loan.collateral
+            });
+        }
 
         // Keep a reference to the new collateral amount.
         uint256 newCollateralCount = loan.collateral - collateralCountToRemove;
@@ -1301,14 +1347,13 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
         // Make sure the borrow amount is not less than the original loan's amount.
         if (borrowAmount < loan.amount) {
-            revert REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows(borrowAmount, loan.amount);
+            revert REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows({
+                newBorrowAmount: borrowAmount, loanAmount: loan.amount
+            });
         }
 
-        // Prevent the loan number from exceeding the ID namespace for this revnet.
-        if (totalLoansBorrowedFor[revnetId] >= _ONE_TRILLION) revert REVLoans_LoanIdOverflow();
-
         // Get a reference to the replacement loan ID.
-        reallocatedLoanId = _generateLoanId({revnetId: revnetId, loanNumber: ++totalLoansBorrowedFor[revnetId]});
+        reallocatedLoanId = _nextLoanIdFor(revnetId);
 
         // Get a reference to the loan being created.
         reallocatedLoan = _loanOf[reallocatedLoanId];
@@ -1364,7 +1409,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         });
 
         // Add the loaned amount back to the revnet.
-        // slither-disable-next-line arbitrary-send-eth
         loan.source.terminal.addToBalanceOf{value: payValue}({
             projectId: revnetId,
             token: loan.source.token,
@@ -1385,7 +1429,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @param collateralCountToReturn The amount of collateral to return that the loan no longer requires.
     /// @param beneficiary The address to receive the returned collateral and any tokens resulting from paying fees.
     /// @param loanOwner The owner of the loan NFT (receives replacement loan if partial repay).
-    // slither-disable-next-line reentrancy-eth,reentrancy-events
     function _repayLoan(
         uint256 loanId,
         REVLoan storage loan,
@@ -1403,7 +1446,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         _burn(loanId);
 
         // If the loan will carry no more amount or collateral, store its changes directly.
-        // slither-disable-next-line incorrect-equality
         if (collateralCountToReturn == loan.collateral) {
             // Snapshot the loan to memory BEFORE _adjust zeroes the storage pointer.
             REVLoan memory loanSnapshot = loan;
@@ -1440,12 +1482,8 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
             return (loanId, paidOffSnapshot);
         } else {
-            // Make a new loan with the remaining amount and collateral.
-            // Prevent the loan number from exceeding the ID namespace for this revnet.
-            if (totalLoansBorrowedFor[revnetId] >= _ONE_TRILLION) revert REVLoans_LoanIdOverflow();
-
             // Get a reference to the replacement loan ID.
-            uint256 paidOffLoanId = _generateLoanId({revnetId: revnetId, loanNumber: ++totalLoansBorrowedFor[revnetId]});
+            uint256 paidOffLoanId = _nextLoanIdFor(revnetId);
 
             // Get a reference to the loan being paid off.
             REVLoan storage paidOffLoan = _loanOf[paidOffLoanId];
@@ -1502,7 +1540,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         totalCollateralOf[revnetId] -= collateralCount;
 
         // Mint the collateral tokens back to the loan payer.
-        // slither-disable-next-line unused-return,calls-loop
         CONTROLLER.mintTokensOf({
             projectId: revnetId,
             tokenCount: collateralCount,
@@ -1561,7 +1598,6 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     {
         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,
@@ -1580,6 +1616,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         }
     }
 
+    /// @notice Accepts calldata sent with native tokens so repayment helpers can refund or settle value.
     fallback() external payable {}
+
+    /// @notice Accepts native tokens sent directly to the loan contract.
     receive() external payable {}
 }

package/src/REVOwner.sol

@@ -43,9 +43,9 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    error REVOwner_AlreadyInitialized();
+    error REVOwner_AlreadyInitialized(address deployer);
     error REVOwner_CashOutDelayNotFinished(uint256 cashOutDelay, uint256 blockTimestamp);
-    error REVOwner_Unauthorized();
+    error REVOwner_Unauthorized(address caller, address expectedCaller);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -89,7 +89,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
 
     /// @notice Each revnet's tiered ERC-721 hook.
     /// @custom:param revnetId The ID of the revnet to look up.
-    // slither-disable-next-line uninitialized-state
     mapping(uint256 revnetId => IJB721TiersHook tiered721Hook) public tiered721HookOf;
 
     /// @notice The deployer that manages revnet state.
@@ -113,13 +112,16 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @param suckerRegistry The sucker registry.
     /// @param loans The loan contract.
     /// @param hiddenTokens The hidden tokens contract.
+    /// @param deployerBinder 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,
         IJBDirectory directory,
         uint256 feeRevnetId,
         IJBSuckerRegistry suckerRegistry,
         IREVLoans loans,
-        IREVHiddenTokens hiddenTokens
+        IREVHiddenTokens hiddenTokens,
+        address deployerBinder
     ) {
         BUYBACK_HOOK = buybackHook;
         DIRECTORY = directory;
@@ -127,7 +129,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         SUCKER_REGISTRY = suckerRegistry;
         LOANS = loans;
         HIDDEN_TOKENS = hiddenTokens;
-        _DEPLOYER_BINDER = msg.sender;
+        _DEPLOYER_BINDER = deployerBinder;
     }
 
     //*********************************************************************//
@@ -183,22 +185,27 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         uint256 cashOutDelay = cashOutDelayOf[context.projectId];
 
         // Enforce the cash out delay.
+        // forge-lint: disable-next-line(block-timestamp)
         if (cashOutDelay > block.timestamp) {
-            revert REVOwner_CashOutDelayNotFinished(cashOutDelay, block.timestamp);
+            revert REVOwner_CashOutDelayNotFinished({cashOutDelay: cashOutDelay, blockTimestamp: block.timestamp});
         }
 
         // 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 + totalCollateral + SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
-        effectiveSurplusValue = context.surplus.value + totalBorrowed
-            + SUCKER_REGISTRY.remoteSurplusOf({
+        // Start with local supply and surplus (including collateral and borrowed amounts).
+        totalSupply = context.totalSupply + totalCollateral;
+        effectiveSurplusValue = context.surplus.value + totalBorrowed;
+
+        // If the ruleset aggregates cross-chain state, add remote supply and surplus.
+        if (!context.scopeCashOutsToLocalBalances) {
+            totalSupply += SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
+            effectiveSurplusValue += SUCKER_REGISTRY.remoteSurplusOf({
                 projectId: context.projectId,
                 decimals: context.surplus.decimals,
                 currency: uint256(context.surplus.currency)
             });
+        }
 
         // 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 to the buyback hook with our
@@ -209,7 +216,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
             JBBeforeCashOutRecordedContext memory routedContext = context;
             routedContext.totalSupply = totalSupply;
             routedContext.surplus.value = effectiveSurplusValue;
-            // slither-disable-next-line unused-return
             (cashOutTaxRate, cashOutCount,,, hookSpecifications) = BUYBACK_HOOK.beforeCashOutRecordedWith(routedContext);
             return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
         }
@@ -261,7 +267,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
 
         // Let the buyback hook adjust the cash out parameters and optionally return a hook specification.
         JBCashOutHookSpecification[] memory buybackHookSpecifications;
-        // slither-disable-next-line unused-return
         (cashOutTaxRate, cashOutCount,,, buybackHookSpecifications) =
             BUYBACK_HOOK.beforeCashOutRecordedWith(buybackHookContext);
 
@@ -316,7 +321,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         bool usesTiered721Hook = address(tiered721Hook) != address(0);
         if (usesTiered721Hook) {
             JBPayHookSpecification[] memory specs;
-            // slither-disable-next-line unused-return
             (, specs) = IJBRulesetDataHook(address(tiered721Hook)).beforePayRecordedWith(context);
             // The 721 hook returns a single spec (itself) whose amount is the total split amount.
             if (specs.length > 0) {
@@ -429,7 +433,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         });
 
         // Pay the fee.
-        // slither-disable-next-line arbitrary-send-eth,unused-return
         try feeTerminal.pay{value: payValue}({
             projectId: FEE_REVNET_ID,
             token: context.forwardedAmount.token,
@@ -454,7 +457,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
                 to: msg.sender, token: context.forwardedAmount.token, amount: context.forwardedAmount.value
             });
 
-            // slither-disable-next-line arbitrary-send-eth
             IJBTerminal(msg.sender).addToBalanceOf{value: payValue}({
                 projectId: context.projectId,
                 token: context.forwardedAmount.token,
@@ -474,9 +476,11 @@ 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();
+        if (msg.sender != _DEPLOYER_BINDER) {
+            revert REVOwner_Unauthorized({caller: msg.sender, expectedCaller: _DEPLOYER_BINDER});
+        }
         // Prevent the deployer binding from being overwritten after initialization.
-        if (address(DEPLOYER) != address(0)) revert REVOwner_AlreadyInitialized();
+        if (address(DEPLOYER) != address(0)) revert REVOwner_AlreadyInitialized({deployer: address(DEPLOYER)});
         // Store the canonical REVDeployer that is authorized to manage runtime hook state.
         DEPLOYER = deployer;
     }
@@ -486,7 +490,9 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @param revnetId The ID of the revnet.
     /// @param cashOutDelay The timestamp after which cash outs are allowed.
     function setCashOutDelayOf(uint256 revnetId, uint256 cashOutDelay) external {
-        if (msg.sender != address(DEPLOYER)) revert REVOwner_Unauthorized();
+        if (msg.sender != address(DEPLOYER)) {
+            revert REVOwner_Unauthorized({caller: msg.sender, expectedCaller: address(DEPLOYER)});
+        }
         cashOutDelayOf[revnetId] = cashOutDelay;
     }
 
@@ -495,7 +501,9 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @param revnetId The ID of the revnet.
     /// @param hook The tiered ERC-721 hook.
     function setTiered721HookOf(uint256 revnetId, IJB721TiersHook hook) external {
-        if (msg.sender != address(DEPLOYER)) revert REVOwner_Unauthorized();
+        if (msg.sender != address(DEPLOYER)) {
+            revert REVOwner_Unauthorized({caller: msg.sender, expectedCaller: address(DEPLOYER)});
+        }
         tiered721HookOf[revnetId] = hook;
     }
 
@@ -552,13 +560,11 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         for (uint256 i; i < sources.length; i++) {
             REVLoanSource memory source = sources[i];
             // Each configured source must be queried live so cash-out math includes current outstanding debt.
-            // slither-disable-next-line calls-loop
             uint256 tokensLoaned =
                 loans.totalBorrowedFrom({revnetId: revnetId, terminal: source.terminal, token: source.token});
             if (tokensLoaned == 0) continue;
 
             // Read the source token's accounting context so debt can be normalized before cross-currency conversion.
-            // slither-disable-next-line calls-loop
             JBAccountingContext memory accountingContext =
                 source.terminal.accountingContextForTokenOf({projectId: revnetId, token: source.token});
 
@@ -576,7 +582,6 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
                 borrowedAmount += normalizedTokens;
             } else {
                 // Convert source-token debt into the requested currency using the loans contract's shared prices.
-                // slither-disable-next-line calls-loop
                 uint256 pricePerUnit = loans.PRICES()
                     .pricePerUnitOf({
                     projectId: revnetId,

package/src/structs/REVConfig.sol

@@ -11,10 +11,13 @@ import {REVStageConfig} from "./REVStageConfig.sol";
 /// @custom:member baseCurrency The currency that issuance pricing is denominated in (e.g. ETH or USD).
 /// @custom:member splitOperator The address that receives production splits and can reassign the operator role.
 /// Only the current operator can replace itself after deployment.
+/// @custom:member scopeCashOutsToLocalBalances If true, cash-out calculations use only the local terminal's surplus.
+/// When false, the bonding curve considers surplus from every terminal across all chains.
 /// @custom:member stageConfigurations The ordered stages that define how the revnet's tokenomics evolve over time.
 struct REVConfig {
     REVDescription description;
     uint32 baseCurrency;
     address splitOperator;
+    bool scopeCashOutsToLocalBalances;
     REVStageConfig[] stageConfigurations;
 }