@rev-net/core-v6 0.0.36 → 0.0.39

package/src/REVLoans.sol

@@ -359,10 +359,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Get the total amount of tokens in circulation.
         uint256 totalSupply = CONTROLLER.totalTokenSupplyWithReservedTokensOf(revnetId);
 
-        // Get a refeerence to the collateral being used to secure loans.
+        // Get a reference 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.
+        // Hidden tokens are intentionally excluded from borrowing math. Operators can hide tokens as a security
+        // handle without changing the fair loan market for visible token holders.
         uint256 localSupply = totalSupply + totalCollateral;
 
         // The local surplus includes both the treasury surplus and the outstanding borrowed amounts.
@@ -469,10 +470,13 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             revert REVLoans_LoanExpired(timeSinceLoanCreated, LOAN_LIQUIDATION_DURATION);
         }
 
-        // Get a reference to the amount prepaid for the full loan.
-        uint256 prepaid = JBFees.feeAmountFrom({amountBeforeFee: loan.amount, feePercent: loan.prepaidFeePercent});
+        // Get a reference to the amount prepaid for the full loan. This is an app-level loan fee, so keep it
+        // floor-rounded instead of applying the protocol fee helper's dust minimum.
+        uint256 prepaid = JBFees.feeAmountFromFloor({amountBeforeFee: loan.amount, feePercent: loan.prepaidFeePercent});
 
-        uint256 fullSourceFeeAmount = JBFees.feeAmountFrom({
+        // This source fee ramps with elapsed time. Use the floor-rounded fee helper so a one-second elapsed window
+        // with zero fee percent stays free instead of inheriting the protocol fee helper's anti-dust minimum.
+        uint256 fullSourceFeeAmount = JBFees.feeAmountFromFloor({
             amountBeforeFee: loan.amount - prepaid,
             feePercent: mulDiv({
                 x: timeSinceLoanCreated - loan.prepaidDuration,
@@ -627,93 +631,15 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Note: the operator controls `beneficiary`, so they can direct borrowed funds to any address.
         _requirePermissionFrom({account: holder, projectId: revnetId, permissionId: JBPermissionIds.OPEN_LOAN});
 
-        // A loan needs to have collateral.
-        if (collateralCount == 0) revert REVLoans_ZeroCollateralLoanIsInvalid();
-
-        // 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);
-        }
-
-        // 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
-            );
-        }
-
-        // Cache the current ruleset once — used by both _cashOutDelayOf and _borrowAmountFrom.
-        JBRuleset memory currentRuleset = _currentRulesetOf(revnetId);
-
-        // Enforce the cash out delay.
-        {
-            uint256 cashOutDelay = _cashOutDelayOf({revnetId: revnetId, currentRuleset: currentRuleset});
-            if (cashOutDelay > block.timestamp) {
-                revert REVLoans_CashOutDelayNotFinished(cashOutDelay, 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]});
-
-        // Get a reference to the loan being created.
-        REVLoan storage loan = _loanOf[loanId];
-
-        // Set the loan's values.
-        loan.source = source;
-        loan.createdAt = uint48(block.timestamp);
-        // forge-lint: disable-next-line(unsafe-typecast)
-        loan.prepaidFeePercent = uint16(prepaidFeePercent);
-        loan.prepaidDuration =
-            uint32(mulDiv({x: prepaidFeePercent, y: LOAN_LIQUIDATION_DURATION, denominator: MAX_PREPAID_FEE_PERCENT}));
-
-        // Get the amount of the loan, using the cached ruleset.
-        uint256 borrowAmount = _borrowAmountFrom({
-            loan: loan, revnetId: revnetId, collateralCount: collateralCount, currentRuleset: currentRuleset
-        });
-
-        // Revert if the bonding curve returns zero to prevent creating zero-amount loans.
-        if (borrowAmount == 0) revert REVLoans_ZeroBorrowAmount();
-
-        // Make sure the minimum borrow amount is met.
-        if (borrowAmount < minBorrowAmount) revert REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount);
-
-        // Get the amount of additional fee to take for the revnet issuing the loan.
-        // Fee rounding may leave a few wei of dust — economically insignificant relative to gas costs.
-        uint256 sourceFeeAmount = JBFees.feeAmountFrom({amountBeforeFee: borrowAmount, feePercent: prepaidFeePercent});
-
-        // Borrow the amount.
-        _adjust({
-            loan: loan,
-            revnetId: revnetId,
-            newBorrowAmount: borrowAmount,
-            newCollateralCount: collateralCount,
-            sourceFeeAmount: sourceFeeAmount,
-            beneficiary: beneficiary,
-            holder: holder
-        });
-
-        // Mint the loan NFT to the holder.
-        _mint({to: holder, tokenId: loanId});
-
-        emit Borrow({
-            loanId: loanId,
+        return _borrowFrom({
             revnetId: revnetId,
-            loan: loan,
             source: source,
-            borrowAmount: borrowAmount,
+            minBorrowAmount: minBorrowAmount,
             collateralCount: collateralCount,
-            sourceFeeAmount: sourceFeeAmount,
             beneficiary: beneficiary,
-            caller: _msgSender()
+            prepaidFeePercent: prepaidFeePercent,
+            holder: holder
         });
-
-        return (loanId, loan);
     }
 
     /// @notice Liquidates loans that have exceeded the 10-year liquidation duration.
@@ -838,7 +764,9 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
         // Make a new loan with the leftover collateral from reallocating.
         // The loan owner is the holder for the new loan (their tokens are used as collateral).
-        (newLoanId, newLoan) = borrowFrom({
+        // Uses _borrowFrom to skip the OPEN_LOAN permission check — the caller already proved REALLOCATE_LOAN
+        // permission above, and requiring OPEN_LOAN here would block operators with only REALLOCATE_LOAN.
+        (newLoanId, newLoan) = _borrowFrom({
             revnetId: revnetId,
             source: source,
             minBorrowAmount: minBorrowAmount,
@@ -1093,10 +1021,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Keep a reference to the fee terminal.
         IJBTerminal feeTerminal = DIRECTORY.primaryTerminalOf({projectId: REV_ID, token: loan.source.token});
 
-        // Get the amount of additional fee to take for REV.
+        // Get the amount of additional fee to take for REV. This is an app-level loan fee, not the terminal's
+        // protocol fee, so keep it floor-rounded instead of applying the protocol fee helper's dust minimum.
         uint256 revFeeAmount = address(feeTerminal) == address(0)
             ? 0
-            : JBFees.feeAmountFrom({amountBeforeFee: addedBorrowAmount, feePercent: REV_PREPAID_FEE_PERCENT});
+            : JBFees.feeAmountFromFloor({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) {
@@ -1234,6 +1163,121 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         IERC20(token).forceApprove({spender: to, value: 0});
     }
 
+    /// @notice Internal implementation of loan creation, without the OPEN_LOAN permission check.
+    /// @dev Called by `borrowFrom` (after its own permission check) and by `reallocateCollateralFromLoan`
+    /// (which only requires REALLOCATE_LOAN permission).
+    /// @param revnetId The ID of the revnet being borrowed from.
+    /// @param source The source of the loan being borrowed.
+    /// @param minBorrowAmount The minimum amount being borrowed.
+    /// @param collateralCount The amount of tokens to use as collateral for the loan.
+    /// @param beneficiary The address that'll receive the borrowed funds and the tokens resulting from fee payments.
+    /// @param prepaidFeePercent The fee percent that will be charged upfront.
+    /// @param holder The address whose tokens are used as collateral and who receives the loan NFT.
+    /// @return loanId The ID of the loan created from borrowing.
+    /// @return loan The loan created from borrowing.
+    function _borrowFrom(
+        uint256 revnetId,
+        REVLoanSource calldata source,
+        uint256 minBorrowAmount,
+        uint256 collateralCount,
+        address payable beneficiary,
+        uint256 prepaidFeePercent,
+        address holder
+    )
+        internal
+        returns (uint256 loanId, REVLoan memory)
+    {
+        // A loan needs to have collateral.
+        if (collateralCount == 0) revert REVLoans_ZeroCollateralLoanIsInvalid();
+
+        // 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);
+        }
+
+        // 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
+            );
+        }
+
+        // Cache the current ruleset once — used by both _cashOutDelayOf and _borrowAmountFrom.
+        JBRuleset memory currentRuleset = _currentRulesetOf(revnetId);
+
+        // Enforce the cash out delay.
+        {
+            uint256 cashOutDelay = _cashOutDelayOf({revnetId: revnetId, currentRuleset: currentRuleset});
+            if (cashOutDelay > block.timestamp) {
+                revert REVLoans_CashOutDelayNotFinished(cashOutDelay, 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]});
+
+        // Get a reference to the loan being created.
+        REVLoan storage loan = _loanOf[loanId];
+
+        // Set the loan's values.
+        loan.source = source;
+        loan.createdAt = uint48(block.timestamp);
+        // forge-lint: disable-next-line(unsafe-typecast)
+        loan.prepaidFeePercent = uint16(prepaidFeePercent);
+        loan.prepaidDuration =
+            uint32(mulDiv({x: prepaidFeePercent, y: LOAN_LIQUIDATION_DURATION, denominator: MAX_PREPAID_FEE_PERCENT}));
+
+        // Get the amount of the loan, using the cached ruleset.
+        uint256 borrowAmount = _borrowAmountFrom({
+            loan: loan, revnetId: revnetId, collateralCount: collateralCount, currentRuleset: currentRuleset
+        });
+
+        // Revert if the bonding curve returns zero to prevent creating zero-amount loans.
+        if (borrowAmount == 0) revert REVLoans_ZeroBorrowAmount();
+
+        // Make sure the minimum borrow amount is met.
+        if (borrowAmount < minBorrowAmount) revert REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount);
+
+        // Get the amount of additional fee to take for the revnet issuing the loan. This is an app-level loan fee,
+        // not the terminal's protocol fee, so keep it floor-rounded instead of applying the protocol fee helper's dust
+        // minimum.
+        uint256 sourceFeeAmount =
+            JBFees.feeAmountFromFloor({amountBeforeFee: borrowAmount, feePercent: prepaidFeePercent});
+
+        // Borrow the amount.
+        _adjust({
+            loan: loan,
+            revnetId: revnetId,
+            newBorrowAmount: borrowAmount,
+            newCollateralCount: collateralCount,
+            sourceFeeAmount: sourceFeeAmount,
+            beneficiary: beneficiary,
+            holder: holder
+        });
+
+        // Mint the loan NFT to the holder.
+        _mint({to: holder, tokenId: loanId});
+
+        emit Borrow({
+            loanId: loanId,
+            revnetId: revnetId,
+            loan: loan,
+            source: source,
+            borrowAmount: borrowAmount,
+            collateralCount: collateralCount,
+            sourceFeeAmount: sourceFeeAmount,
+            beneficiary: beneficiary,
+            caller: _msgSender()
+        });
+
+        return (loanId, loan);
+    }
+
     /// @notice Reallocates 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.

package/src/REVOwner.sol

@@ -9,12 +9,14 @@ import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDa
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {JBCashOuts} from "@bananapus/core-v6/src/libraries/JBCashOuts.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
 import {JBAfterCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterCashOutRecordedContext.sol";
 import {JBBeforeCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforeCashOutRecordedContext.sol";
 import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
 import {JBCashOutHookSpecification} from "@bananapus/core-v6/src/structs/JBCashOutHookSpecification.sol";
 import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {IJBPeerChainAdjustedAccounts} from "@bananapus/suckers-v6/src/interfaces/IJBPeerChainAdjustedAccounts.sol";
 import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -22,11 +24,14 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {IREVDeployer} from "./interfaces/IREVDeployer.sol";
+import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
+import {IREVLoans} from "./interfaces/IREVLoans.sol";
+import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
 /// @notice Handles the runtime data hook and cash out hook behavior for revnets.
 /// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit.
 /// This contract is set as the `dataHook` in each revnet's ruleset metadata.
-contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
+contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAccounts {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
 
@@ -61,10 +66,10 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     uint256 public immutable FEE_REVNET_ID;
 
     /// @notice The hidden tokens contract used by all revnets.
-    address public immutable HIDDEN_TOKENS;
+    IREVHiddenTokens public immutable HIDDEN_TOKENS;
 
     /// @notice The loan contract used by all revnets.
-    address public immutable LOANS;
+    IREVLoans public immutable LOANS;
 
     /// @notice Deploys and tracks suckers for revnets.
     IJBSuckerRegistry public immutable SUCKER_REGISTRY;
@@ -102,23 +107,21 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     /// @param directory The directory of terminals and controllers.
     /// @param feeRevnetId The Juicebox project ID of the fee revnet.
     /// @param suckerRegistry The sucker registry.
-    /// @param loans The loan contract address.
-    /// @param hiddenTokens The hidden tokens contract address.
+    /// @param loans The loan contract.
+    /// @param hiddenTokens The hidden tokens contract.
     constructor(
         IJBBuybackHookRegistry buybackHook,
         IJBDirectory directory,
         uint256 feeRevnetId,
         IJBSuckerRegistry suckerRegistry,
-        address loans,
-        address hiddenTokens
+        IREVLoans loans,
+        IREVHiddenTokens hiddenTokens
     ) {
         BUYBACK_HOOK = buybackHook;
         DIRECTORY = directory;
         FEE_REVNET_ID = feeRevnetId;
         SUCKER_REGISTRY = suckerRegistry;
-        // slither-disable-next-line missing-zero-check
         LOANS = loans;
-        // slither-disable-next-line missing-zero-check
         HIDDEN_TOKENS = hiddenTokens;
         _DEPLOYER_BINDER = msg.sender;
     }
@@ -153,11 +156,23 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
+        // Treat outstanding local loans as temporarily off-terminal revnet assets. Borrowed funds are owed back to
+        // the revnet, while burned loan collateral can be re-minted on repayment, so both affect fair cash-out math.
+        (uint256 totalBorrowed, uint256 totalCollateral) = _localLoanStateOf({
+            revnetId: context.projectId, decimals: context.surplus.decimals, currency: context.surplus.currency
+        });
+
         // If the cash out is from a sucker, return the full cash out amount without taxes or fees.
         // 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, context.surplus.value, hookSpecifications);
+            return (
+                0,
+                context.cashOutCount,
+                context.totalSupply + totalCollateral,
+                context.surplus.value + totalBorrowed,
+                hookSpecifications
+            );
         }
 
         // Keep a reference to the cash out delay of the revnet.
@@ -173,12 +188,12 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
 
         // 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
+        totalSupply = context.totalSupply + totalCollateral + SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
+        effectiveSurplusValue = context.surplus.value + totalBorrowed
             + SUCKER_REGISTRY.remoteSurplusOf({
                 projectId: context.projectId,
                 decimals: context.surplus.decimals,
-                currency: uint256(uint160(context.surplus.token))
+                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
@@ -350,11 +365,35 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     {
         // The loans contract, hidden tokens contract, buyback hook (and its delegates), and suckers are allowed to mint
         // the revnet's tokens.
-        return addr == LOANS || addr == HIDDEN_TOKENS || addr == address(BUYBACK_HOOK)
+        return addr == address(LOANS) || addr == address(HIDDEN_TOKENS) || addr == address(BUYBACK_HOOK)
             || BUYBACK_HOOK.hasMintPermissionFor({projectId: revnetId, ruleset: ruleset, addr: addr})
             || _isSuckerOf({revnetId: revnetId, addr: addr});
     }
 
+    /// @notice Additional revnet accounts that peer-chain snapshots should include.
+    /// @dev Hidden tokens are intentionally excluded. Revnet operators can hide tokens as a security handle without
+    /// changing loan or cash-out math for other holders. Outstanding loan debt is counted as both surplus and balance:
+    /// it is value owed back to this chain's revnet and should travel to peer snapshots with the collateral supply.
+    /// @param revnetId The ID of the revnet being snapshotted.
+    /// @param decimals The decimals the returned surplus should use.
+    /// @param currency The currency the returned surplus should be in terms of.
+    /// @return supply The loan-collateral supply to include in the peer snapshot.
+    /// @return surplus The outstanding loan debt to include in `sourceSurplus`.
+    /// @return balance The outstanding loan debt to include in `sourceBalance`.
+    function peerChainAdjustedAccountsOf(
+        uint256 revnetId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        override
+        returns (uint256 supply, uint256 surplus, uint256 balance)
+    {
+        (surplus, supply) = _localLoanStateOf({revnetId: revnetId, decimals: decimals, currency: currency});
+        balance = surplus;
+    }
+
     //*********************************************************************//
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
@@ -397,8 +436,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             if (context.forwardedAmount.token != JBConstants.NATIVE_TOKEN) {
                 IERC20(context.forwardedAmount.token)
                     .safeDecreaseAllowance({
-                        spender: address(feeTerminal), requestedDecrease: context.forwardedAmount.value
-                    });
+                    spender: address(feeTerminal), requestedDecrease: context.forwardedAmount.value
+                });
             }
 
             // If the fee can't be processed, return the funds to the project.
@@ -460,7 +499,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     /// @return A flag indicating if the provided interface ID is supported.
     function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
         return interfaceId == type(IERC165).interfaceId || interfaceId == type(IJBRulesetDataHook).interfaceId
-            || interfaceId == type(IJBCashOutHook).interfaceId;
+            || interfaceId == type(IJBCashOutHook).interfaceId
+            || interfaceId == type(IJBPeerChainAdjustedAccounts).interfaceId;
     }
 
     //*********************************************************************//
@@ -475,6 +515,73 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         return SUCKER_REGISTRY.isSuckerOf({projectId: revnetId, addr: addr});
     }
 
+    /// @notice Total outstanding local loan debt and collateral for a revnet.
+    /// @dev This is included in cash-out and peer-snapshot math because borrowed funds are still owed to the revnet
+    /// and collateral can re-enter supply when the loan is repaid.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param decimals The decimals the resulting fixed point debt value should use.
+    /// @param currency The currency the resulting debt value should be in terms of.
+    /// @return borrowedAmount The local outstanding loan debt converted into `currency`.
+    /// @return collateralCount The local burned loan collateral count.
+    function _localLoanStateOf(
+        uint256 revnetId,
+        uint256 decimals,
+        uint256 currency
+    )
+        internal
+        view
+        returns (uint256 borrowedAmount, uint256 collateralCount)
+    {
+        IREVLoans loans = LOANS;
+        if (address(loans) == address(0) || address(loans).code.length == 0) return (0, 0);
+
+        collateralCount = loans.totalCollateralOf(revnetId);
+
+        REVLoanSource[] memory sources = loans.loanSourcesOf(revnetId);
+        // Loan sources are project configuration, and this read-only aggregation needs the latest terminal/pricing
+        // state for each configured source.
+        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});
+
+            // Normalize each source from its native token decimals into the caller's requested decimals.
+            uint256 normalizedTokens;
+            if (accountingContext.decimals > decimals) {
+                normalizedTokens = tokensLoaned / (10 ** (accountingContext.decimals - decimals));
+            } else if (accountingContext.decimals < decimals) {
+                normalizedTokens = tokensLoaned * (10 ** (decimals - accountingContext.decimals));
+            } else {
+                normalizedTokens = tokensLoaned;
+            }
+
+            if (accountingContext.currency == currency) {
+                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,
+                    pricingCurrency: accountingContext.currency,
+                    unitCurrency: currency,
+                    decimals: decimals
+                });
+                if (pricePerUnit == 0) continue;
+
+                borrowedAmount += mulDiv({x: normalizedTokens, y: 10 ** decimals, denominator: pricePerUnit});
+            }
+        }
+    }
+
     //*********************************************************************//
     // --------------------- internal transactions ----------------------- //
     //*********************************************************************//

package/src/interfaces/IREVDeployer.sol

@@ -16,6 +16,7 @@ import {REVConfig} from "../structs/REVConfig.sol";
 import {REVCroptopAllowedPost} from "../structs/REVCroptopAllowedPost.sol";
 import {REVDeploy721TiersHookConfig} from "../structs/REVDeploy721TiersHookConfig.sol";
 import {REVSuckerDeploymentConfig} from "../structs/REVSuckerDeploymentConfig.sol";
+import {IREVLoans} from "./IREVLoans.sol";
 
 /// @notice Deploys and manages revnets -- Juicebox projects with pre-configured tokenomics.
 interface IREVDeployer {
@@ -143,7 +144,7 @@ interface IREVDeployer {
 
     /// @notice The loan contract used by all revnets.
     /// @return The loans contract address.
-    function LOANS() external view returns (address);
+    function LOANS() external view returns (IREVLoans);
 
     /// @notice The runtime data hook contract that handles pay and cash out callbacks for revnets.
     /// @return The owner contract address.

package/src/interfaces/IREVHiddenTokens.sol

@@ -3,7 +3,10 @@ pragma solidity ^0.8.0;
 
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 
-/// @notice Manages hiding (burning) and revealing (re-minting) revnet tokens to exclude them from totalSupply.
+/// @notice Manages hiding (burning) and revealing (re-minting) revnet tokens to exclude them from live totalSupply.
+/// @dev Hidden balances are an operator-controlled security handle. They remain revealable, but cash-out and loan
+/// accounting intentionally excludes `totalHiddenOf` so hidden inventory cannot dilute other holders' access to
+/// revnet capital.
 interface IREVHiddenTokens {
     /// @notice Emitted when a holder is allowed or disallowed to hide their own tokens.
     /// @param revnetId The ID of the revnet.

package/src/interfaces/IREVOwner.sol

@@ -2,9 +2,14 @@
 pragma solidity ^0.8.0;
 
 import {IREVDeployer} from "./IREVDeployer.sol";
+import {IREVHiddenTokens} from "./IREVHiddenTokens.sol";
 
 /// @notice Interface for the REVOwner contract that handles runtime data hook and cash out hook behavior for revnets.
 interface IREVOwner {
+    /// @notice The hidden tokens contract used by the revnet owner hook.
+    /// @return The hidden tokens contract.
+    function HIDDEN_TOKENS() external view returns (IREVHiddenTokens);
+
     /// @notice The timestamp of when cashouts will become available to a specific revnet's participants.
     /// @param revnetId The ID of the revnet.
     /// @return The cash out delay timestamp.

package/ADMINISTRATION.md

@@ -1,73 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Revnet deployment shape, bounded runtime operators, loan-owner cosmetics, and optional integration control surfaces |
-| Control posture | Intentionally narrow and mostly deployment-defined |
-| Highest-risk actions | Bad stage design, wrong split-operator assignment, and misunderstanding which runtime surfaces stay live after launch |
-| Recovery posture | Usually replacement, not patching; the design intentionally avoids easy admin escape hatches |
-
-## Purpose
-
-`revnet-core-v6` is designed to collapse ordinary post-launch governance into deployment-time decisions plus a small set of bounded runtime roles. The main administration task is understanding which power still exists and which power was intentionally removed.
-
-## Control Model
-
-- `REVDeployer` holds the project NFT and therefore remains part of the ownership model.
-- Revnet economics are mainly fixed at deployment through staged rulesets.
-- `REVOwner` provides live runtime policy, but not broad human governance.
-- Split operators can hold narrow powers depending on stage and deployment config.
-- `REVLoans` has a cosmetic global owner surface, but loan economics are still bounded by revnet logic.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| `REVDeployer` | Deployed singleton | Global launcher and project-NFT holder | Part of the ownership model |
-| Split operator | Deployment config | Per revnet | Holds only the allowed operator envelope |
-| Auto-issuance beneficiary | Deployment config | Per stage | Can receive preconfigured stage issuance |
-| Borrower or delegated loan operator | Token holder plus permission | Per holder or loan | Can open or manage loans within loan rules |
-| `REVLoans` owner | Constructor owner | Global cosmetic/admin surface | Does not turn Revnets back into ordinary governed projects |
-
-## Privileged Surfaces
-
-- `deployFor(...)` defines the revnet's long-lived shape
-- split-operator paths can manage only the permissions left open by deployment
-- `autoIssueFor(...)` consumes preconfigured stage issuance
-- loan operators can redirect borrowed value if a holder delegates loan permissions
-- hidden-token flows require the holder's permission grant and mint permission wiring through `REVOwner`
-
-## Immutable And One-Way
-
-- Stage configuration is effectively permanent after deployment.
-- The deployer-held project NFT is not a normal owner-recovery tool.
-- Loan collateral is burned at borrow time and only reminted through repayment or documented flows.
-- Hidden-token balances change visible supply until reveal.
-
-## Operational Notes
-
-- Treat revnet launch as the real governance decision.
-- Validate stage timing, split-operator scope, and optional integrations before deployment.
-- Review cash-out delay, hidden-token semantics, and loan permissions together.
-- Do not assume there is a broad admin override for bad economics after launch.
-
-## Machine Notes
-
-- Do not describe Revnets as fully adminless if the deployer-held NFT still matters for the trust model.
-- Also do not describe them as ordinary owner-controlled projects. The point is that the available control surface is intentionally narrow.
-- If a question is about runtime cash-outs, buybacks, or mint permissions, inspect `REVOwner` before inferring behavior from deployment prose.
-
-## Recovery
-
-- If launch-time economics are wrong, recovery usually means replacement, not in-place repair.
-- If optional integrations are misconfigured, fix only where the code still exposes a valid path.
-- If the design intentionally omitted a recovery path, do not invent one in documentation or ops guidance.
-
-## Admin Boundaries
-
-- No ordinary owner can casually rewrite staged economics after launch.
-- Split operators are not general-purpose governors.
-- Loan mechanics, hidden-token mechanics, and cash-out policy remain bounded by the deployed revnet logic.
-- This repo should not be documented as if it had a normal mutable project-owner model.