@rev-net/core-v6 0.0.37 → 0.0.40

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,18 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {IREVDeployer} from "./interfaces/IREVDeployer.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 {
+import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
+import {IREVLoans} from "./interfaces/IREVLoans.sol";
+import {REVLoanSource} from "./structs/REVLoanSource.sol";
+
+/// @notice The runtime hook for all revnets — set as every revnet's `dataHook` in ruleset metadata. At pay time, it
+/// coordinates the 721 hook (NFT tier minting) with the buyback hook (secondary market swap routing) and scales weight
+/// for split deductions. At cash-out time, it aggregates cross-chain total supply and surplus (including outstanding
+/// loan debt and collateral), grants suckers 0% tax, splits a 2.5% fee from non-sucker cash outs, and routes fee
+/// proceeds to the fee revnet via `afterCashOutRecordedWith`.
+/// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit. Also implements
+/// `IJBPeerChainAdjustedAccounts` to expose loan state to peer-chain supply/surplus snapshots.
+contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAccounts {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
 
@@ -61,10 +70,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 +111,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;
     }
@@ -127,13 +134,14 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Determine how a cash out from a revnet should be processed.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a cash out.
-    /// @dev If a sucker is cashing out, no taxes or fees are imposed.
-    /// @dev REVOwner is intentionally not registered as a feeless address. The protocol fee (2.5%) applies on top
-    /// of the rev fee — this is by design. The fee hook spec amount sent to `afterCashOutRecordedWith` will have the
-    /// protocol fee deducted by the terminal before reaching this contract, so the rev fee is computed on the
-    /// post-protocol-fee amount.
+    /// @notice Called before a cash out is recorded. Suckers get 0% tax (bridged tokens redeem at face value). For
+    /// regular holders, aggregates cross-chain total supply and surplus (including outstanding loan debt/collateral),
+    /// splits a 2.5% fee from the cashed-out token count, computes bonding curve reclaims for both the holder's portion
+    /// and the fee portion, then delegates to the buyback hook for potential swap routing.
+    /// @dev Part of `IJBRulesetDataHook`. REVOwner is intentionally not registered as a feeless address — the
+    /// protocol
+    /// fee (2.5%) applies on top of the rev fee. The fee hook spec amount sent to `afterCashOutRecordedWith` will have
+    /// the protocol fee deducted by the terminal before reaching this contract.
     /// @param context Standard Juicebox cash out context. See `JBBeforeCashOutRecordedContext`.
     /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
     /// out.
@@ -153,11 +161,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,8 +193,8 @@ 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,
@@ -274,8 +294,11 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
     }
 
-    /// @notice Before a revnet processes an incoming payment, determine the weight and pay hooks to use.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a payment.
+    /// @notice Called before a payment is recorded. Coordinates the 721 hook (NFT tier minting with split deductions)
+    /// with the buyback hook (which may route funds through a Uniswap pool for a better token price). Merges their hook
+    /// specifications and scales the minting weight so payers only receive tokens proportional to funds entering the
+    /// project (not the split portion).
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook spec comes first in the returned array.
     /// @param context Standard Juicebox payment context. See `JBBeforePayRecordedContext`.
     /// @return weight The weight which revnet tokens are minted relative to. This can be used to customize how many
     /// tokens get minted by a payment.
@@ -332,8 +355,11 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         if (usesBuybackHook) hookSpecifications[usesTiered721Hook ? 1 : 0] = buybackHookSpecs[0];
     }
 
-    /// @notice A flag indicating whether an address has permission to mint a revnet's tokens on-demand.
-    /// @dev Required by the `IJBRulesetDataHook` interface.
+    /// @notice Returns whether an address may mint a revnet's tokens on-demand. Grants permission to: the loans
+    /// contract (re-mints collateral on repayment), hidden tokens contract (re-mints on reveal), buyback hook and its
+    /// delegates
+    /// (mints tokens from pool swaps), and suckers (mints bridged tokens on the destination chain).
+    /// @dev Part of `IJBRulesetDataHook`.
     /// @param revnetId The ID of the revnet to check permissions for.
     /// @param ruleset The ruleset to check the mint permission for.
     /// @param addr The address to check the mint permission of.
@@ -350,11 +376,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 ----------------------- //
     //*********************************************************************//
@@ -460,7 +510,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 +526,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/src/structs/REVAutoIssuance.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member chainId The ID of the chain on which the mint should be honored.
-/// @custom:member count The number of tokens that should be minted.
+/// @notice A per-stage token mint that happens without any payment — think of it as a scheduled premint. Each auto
+/// issuance specifies a chain, beneficiary, and token count. Can be claimed once per stage via `autoIssueFor`.
+/// @custom:member chainId The chain ID where this auto-issuance should be honored (only mints on the matching chain).
+/// @custom:member count The number of tokens to mint for the beneficiary.
 /// @custom:member beneficiary The address that will receive the minted tokens.
 struct REVAutoIssuance {
     uint32 chainId;

package/src/structs/REVConfig.sol

@@ -4,11 +4,14 @@ pragma solidity ^0.8.0;
 import {REVDescription} from "./REVDescription.sol";
 import {REVStageConfig} from "./REVStageConfig.sol";
 
-/// @custom:member description The description of the revnet.
-/// @custom:member baseCurrency The currency that the issuance is based on.
-/// @custom:member splitOperator The address that will receive the token premint and initial production split,
-/// and who is allowed to change who the operator is. Only the operator can replace itself after deployment.
-/// @custom:member stageConfigurations The periods of changing constraints.
+/// @notice Top-level configuration for deploying a revnet. Defines the revnet's identity, base currency for issuance
+/// pricing, the split operator (who receives production splits and can reassign that role), and the ordered list of
+/// stages that govern the revnet's lifecycle.
+/// @custom:member description The revnet's name, ticker, metadata URI, and deployment salt.
+/// @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 stageConfigurations The ordered stages that define how the revnet's tokenomics evolve over time.
 struct REVConfig {
     REVDescription description;
     uint32 baseCurrency;

package/src/structs/REVDescription.sol

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member name The name of the ERC-20 token being create for the revnet.
-/// @custom:member ticker The ticker of the ERC-20 token being created for the revnet.
-/// @custom:member uri The metadata URI containing revnet's info.
-/// @custom:member salt Revnets deployed across chains by the same address with the same salt will have the same
-/// address.
+/// @notice Identity and metadata for a revnet deployment.
+/// @custom:member name The name of the ERC-20 token created for the revnet.
+/// @custom:member ticker The ticker symbol of the ERC-20 token created for the revnet.
+/// @custom:member uri The metadata URI containing the revnet's off-chain info (logo, description, links).
+/// @custom:member salt A deployment salt — revnets deployed across chains by the same address with the same salt get
+/// deterministic matching addresses.
 struct REVDescription {
     string name;
     string ticker;

package/src/structs/REVLoan.sol

@@ -3,12 +3,15 @@ pragma solidity ^0.8.0;
 
 import {REVLoanSource} from "./REVLoanSource.sol";
 
-/// @custom:member borrowedAmount The amount that is being borrowed.
-/// @custom:member collateralTokenCount The number of collateral tokens currently accounted for.
+/// @notice An active loan against a revnet. The borrower locked collateral tokens (which were burned) and received
+/// funds from the revnet's terminal. The loan can be repaid within the prepaid duration at no extra cost; after that,
+/// repayment cost increases linearly until liquidation at 10 years.
+/// @custom:member amount The amount borrowed (includes fees taken at creation).
+/// @custom:member collateral The number of revnet tokens burned as collateral.
 /// @custom:member createdAt The timestamp when the loan was created.
-/// @custom:member prepaidFeePercent The percentage of the loan's fees that were prepaid.
-/// @custom:member prepaidDuration The duration that the loan was prepaid for.
-/// @custom:member source The source of the loan.
+/// @custom:member prepaidFeePercent The percentage of fees prepaid at creation (determines prepaid duration).
+/// @custom:member prepaidDuration The duration (seconds) during which repayment costs nothing beyond the original
+/// amount. @custom:member source The terminal and token from which funds were drawn.
 struct REVLoan {
     uint112 amount;
     uint112 collateral;

package/src/structs/REVStageConfig.sol

@@ -5,22 +5,20 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
 import {REVAutoIssuance} from "./REVAutoIssuance.sol";
 
-/// @custom:member startsAtOrAfter The timestamp to start a stage at the given rate at or after.
-/// @custom:member autoIssuances The configurations of mints during this stage.
-/// @custom:member splitPercent The percentage of newly issued tokens that should be split with the operator, out
-/// of 10_000 (JBConstants.MAX_RESERVED_PERCENT).
-/// @custom:member splits The splits for the revnet.
-/// @custom:member initialIssuance The number of revnet tokens that one unit of the revnet's base currency will buy, as
-/// a fixed point number
-/// with 18 decimals.
-/// @custom:member issuanceCutFrequency The number of seconds between applied issuance decreases. This
-/// should be at least 24 hours.
-/// @custom:member issuanceCutPercent The percent that issuance should decrease over time. This percentage is out
-/// of 1_000_000_000 (JBConstants.MAX_CUT_PERCENT). 0% corresponds to no issuance increase.
-/// @custom:member cashOutTaxRate The factor determining how much each token can cash out from the revnet once
-/// cashed out. This rate is out of 10_000 (JBConstants.MAX_CASH_OUT_TAX_RATE). 0% corresponds to no tax when cashing
-/// out.
-/// @custom:member extraMetadata Extra info to attach set into this stage that may affect hooks.
+/// @notice A stage in a revnet's lifecycle. Each stage defines the token issuance rate, how quickly it decays, what
+/// percentage goes to splits, and the cash-out tax rate. Stages are processed in order — each one activates at or
+/// after
+/// its `startsAtOrAfter` timestamp.
+/// @custom:member startsAtOrAfter The earliest timestamp this stage can begin. Must be strictly increasing across
+/// stages. @custom:member autoIssuances Tokens to mint without payment during this stage (per-chain, per-beneficiary).
+/// @custom:member splitPercent The percentage of newly issued tokens routed to splits, out of 10,000.
+/// @custom:member splits The split recipients for this stage's production allocation.
+/// @custom:member initialIssuance Tokens per unit of base currency at stage start (18-decimal fixed point).
+/// @custom:member issuanceCutFrequency Seconds between each issuance reduction. Should be >= 24 hours.
+/// @custom:member issuanceCutPercent How much issuance decreases each period, out of 1,000,000,000. 0 = no decay.
+/// @custom:member cashOutTaxRate The tax on cash outs, out of 10,000. 0 = no tax (full reclaim). Higher = more tax
+/// retained by the treasury.
+/// @custom:member extraMetadata Additional metadata bits passed to hooks for stage-specific behavior.
 struct REVStageConfig {
     uint48 startsAtOrAfter;
     REVAutoIssuance[] autoIssuances;

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.