@rev-net/core-v6 0.0.76 → 0.0.77

package/README.md

@@ -31,6 +31,7 @@ Use this repo when the product is a treasury-backed network with encoded stage t
 | `REVDeployer` | Launches and configures Revnets, stages, operators, and optional auxiliary features. |
 | `REVOwner` | Runtime data-hook and cash-out-hook surface used by active Revnets. |
 | `REVLoans` | Loan surface that lets users borrow against Revnet tokens with burned collateral and NFT loan positions. |
+
 ## Mental Model
 
 Read the package in two halves:
@@ -59,6 +60,7 @@ Most mistakes come from assuming a deploy-time parameter can be changed later or
 - deployment-time configuration and operator envelope live in `REVDeployer`
 - runtime pay and cash-out behavior live in `REVOwner`
 - loan positions and loan-specific state live in `REVLoans`
+
 ## High-Signal Tests
 
 1. `test/REVLifecycle.t.sol`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rev-net/core-v6",
-  "version": "0.0.76",
+  "version": "0.0.77",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md

@@ -69,7 +69,7 @@ Use this file when you need revnet-specific risks, state reads, constants, or ex
 | `REVLoans_InvalidPrepaidFeePercent(prepaidFeePercent, min, max)` | When `prepaidFeePercent` is outside the allowed range (2.5%--50%). |
 | `REVLoans_InvalidTerminal(terminal, revnetId)` | When the specified terminal is not registered for the revnet. |
 | `REVLoans_LoanExpired(timeSinceLoanCreated, loanLiquidationDuration)` | When trying to repay or reallocate an expired loan. |
-| `REVLoans_LoanIdOverflow()` | When the loan ID counter exceeds the per-revnet trillion-ID namespace. |
+| `REVLoans_LoanIdOverflow()` | When the loan ID counter exceeds the per-revnet 1e18-ID namespace. |
 | `REVLoans_NewBorrowAmountGreaterThanLoanAmount(newBorrowAmount, loanAmount)` | When a reallocation would produce a reduced loan with a larger borrow amount than the original. |
 | `REVLoans_NoMsgValueAllowed()` | When `msg.value > 0` on a non-native-token repayment. |
 | `REVLoans_NotEnoughCollateral()` | When the caller does not have enough tokens for the requested collateral. |
@@ -104,7 +104,8 @@ Use this file when you need revnet-specific risks, state reads, constants, or ex
 | `MIN_PREPAID_FEE_PERCENT` | 25 (2.5%) | Minimum upfront fee borrowers must pay |
 | `MAX_PREPAID_FEE_PERCENT` | 500 (50%) | Maximum upfront fee |
 | `REV_PREPAID_FEE_PERCENT` | 10 (1%) | Protocol-level fee to $REV revnet |
-| `_ONE_TRILLION` | 1,000,000,000,000 | Loan ID generator base: `revnetId * 1T + loanNumber` |
+| `_LOAN_ID_NAMESPACE_SIZE` | 1,000,000,000,000,000,000 | Loan ID generator base: `revnetId * namespaceSize + loanNumber` |
+| `_MAX_LOAN_NUMBER` | 999,999,999,999,999,999 | Largest loan number that stays in the current revnet's ID namespace |
 
 ## Storage
 
@@ -144,19 +145,19 @@ Use this file when you need revnet-specific risks, state reads, constants, or ex
 1. **Revnets are permanently ownerless.** `REVOwner` holds the project NFT for every Revnet and exposes no function to release it. Stage parameters cannot be changed after deployment.
 2. **Collateral is burned, not held.** Unlike traditional lending, collateral tokens are destroyed at borrow time and re-minted on repay. If a loan liquidates after 10 years, the collateral is permanently lost.
 3. **100% LTV by design.** Borrowable amount equals the pro-rata cash-out value. No safety margin unless the stage has `cashOutTaxRate > 0`. A tax of 20% creates ~20% effective collateral buffer.
-4. **Loan ID encoding.** `loanId = revnetId * 1_000_000_000_000 + loanNumber`. Each revnet supports ~1 trillion loans. Use `revnetIdOfLoanWith(loanId)` to decode.
+4. **Loan ID encoding.** `loanId = revnetId * 1_000_000_000_000_000_000 + loanNumber`. Each revnet supports loan numbers up to `999_999_999_999_999_999`; `1_000_000_000_000_000_000` is the next revnet's namespace. Use `revnetIdOfLoanWith(loanId)` to decode.
 5. **uint112 truncation risk.** `REVLoan.amount` and `REVLoan.collateral` are `uint112`. Values above ~5.19e33 truncate silently.
 6. **Auto-issuance stage IDs.** Computed as `block.timestamp + i` during deployment. These match the Juicebox ruleset IDs because `JBRulesets` assigns IDs the same way (`latestId >= block.timestamp ? latestId + 1 : block.timestamp`), producing identical sequential IDs when all stages are queued in a single `deployFor()` call.
 7. **Cash-out fee stacking.** Non-zero-tax ordinary cash-outs incur both the Juicebox terminal fee (2.5%) and the revnet cash-out fee (2.5% to fee revnet). These compound. The 2.5% revnet fee is deducted from the TOKEN AMOUNT being cashed out, not from the reclaim value. 2.5% of the tokens are redirected to the fee revnet, which then redeems them at the bonding curve independently. The net reclaim to the caller is based on 97.5% of the tokens, not 97.5% of the computed ETH value. Zero-tax ordinary cash-outs route through the buyback hook without adding the revnet fee hook, matching current code behavior. This is by design.
 8. **30-day cash-out delay.** Applied when deploying an existing revnet to a new chain where the first stage has already started. Prevents cross-chain liquidity arbitrage. Enforced in both `beforeCashOutRecordedWith` (direct cash outs) and `REVLoans.borrowFrom` / `borrowableAmountFrom` (loans). The delay is stored on REVOwner (`cashOutDelayOf(revnetId)`) and populated by REVDeployer during deployment via the bundled `initializeRevnet()` call. REVLoans imports IREVOwner (not IREVDeployer) to read it.
 9. **`cashOutTaxRate` cannot be MAX.** Must be strictly less than `MAX_CASH_OUT_TAX_RATE` (10,000). Revnets cannot fully disable cash outs.
 10. **Split operator is singular.** Only ONE address can be operator at a time. The operator can replace itself via `setOperatorOf` but cannot delegate or multi-sig.
-11. **NATIVE_TOKEN on non-ETH chains.** `JBConstants.NATIVE_TOKEN` on Celo means CELO, on Polygon means MATIC -- not ETH. Use ERC-20 WETH instead. The config matching hash does NOT catch terminal configuration differences.
+11. **NATIVE_TOKEN on non-ETH chains.** `JBConstants.NATIVE_TOKEN` on Celo means CELO, on Polygon means MATIC -- not ETH. Use ERC-20 WETH instead. The config matching hash does not catch terminal or accounting-context differences.
 12. **Loan source array is unbounded.** `_loanSourceTokensOf[revnetId]` grows without limit, bounded in practice by the token accounting contexts accepted by the canonical `MULTI_TERMINAL`.
 13. **Flash-loan surplus exposure.** `borrowableAmountFrom` reads live surplus. A flash loan can temporarily inflate the treasury to borrow more than the sustained value supports.
 14. **Fee revnet must have terminals.** Cash-out fees and loan protocol fees are paid to `FEE_REVNET_ID`. If that project has no terminal for the token, the fee silently fails (try-catch).
 15. **Buyback hook is immutable per deployer.** `BUYBACK_HOOK` is set at construction time on both REVDeployer and REVOwner. All revnets deployed by the same deployer share the same buyback hook.
-16. **Cross-chain config matching.** `hashedEncodedConfigurationOf` covers economic parameters (baseCurrency, stages, auto-issuances) but NOT terminal configurations, accounting contexts, or sucker token mappings. Two deployments with identical hashes can have different terminal setups.
+16. **Cross-chain config matching.** `hashedEncodedConfigurationOf` covers deploy-time revnet identity and economics: base currency, scope flag, name, ticker, salt, stage timing, issuance, cash-out taxes, extra metadata, and auto-issuances. It does not cover terminal configurations, accounting contexts, sucker token mappings, or mutable split recipients. Two deployments with identical hashes can still differ in those external surfaces.
 17. **Loan fee model has three layers.** See Constants table for exact values: REV protocol fee, terminal fee, and prepaid source fee (borrower-chosen, buys interest-free window). After the prepaid window, source fee accrues linearly over the remaining loan duration.
 18. **Permit2 fallback.** `REVLoans` uses permit2 for ERC-20 transfers as a fallback when standard allowance is insufficient. Wrapped in try-catch.
 19. **39.16% cash-out tax crossover.** Below ~39% cash-out tax, cashing out is more capital-efficient than borrowing. Above ~39%, loans become more efficient because they preserve upside while providing liquidity. Based on CryptoEconLab academic research. Design implication: revnets intended for active token trading should consider this threshold when setting `cashOutTaxRate`.
@@ -214,7 +215,7 @@ Quick-reference for common read operations. All functions are `view`/`pure` and
 
 | What | Call | Returns |
 |------|------|---------|
-| Remaining auto-issuance for beneficiary | `REVDeployer.amountToAutoIssue(revnetId, stageId, beneficiary)` | `uint256` (0 if already claimed) |
+| Remaining auto-issuance for beneficiary | `REVOwner.amountToAutoIssue(revnetId, stageId, beneficiary)` | `uint256` (0 if already claimed) |
 
 ### Loans
 
@@ -315,7 +316,7 @@ loans.borrowFrom({
     beneficiary: payable(msg.sender),      // Receive new loan proceeds
     prepaidFeePercent: 25                  // 2.5% prepaid fee on new loan
 });
-// Result: original loan now has 500 fewer collateral tokens (reallocatedLoanId),
+// Result: original loan has 500 fewer collateral tokens (reallocatedLoanId),
 // new loan has 700 tokens of collateral (newLoanId).
 
 // --- Repay a loan ---

package/references/runtime.md

@@ -11,7 +11,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | Contract | Role |
 |----------|------|
 | `REVDeployer` | Deploys revnets. Configures stages, splits, auto-issuance amounts, buyback hooks, suckers, operators, and stores `hashedEncodedConfigurationOf`. Exposes `OWNER()` view returning the REVOwner address. Hands the JBProjects NFT to REVOwner mid-deploy and finishes by bundling every per-revnet runtime write into a single `REVOwner.initializeRevnet(revnetId, init)` call (cash-out delay, tiered 721 hook, auto-issuance allocations, extra operator permissions, the initial operator, and any integration grants). |
-| `REVOwner` | Project NFT owner for every revnet and runtime hook for all revnets. Implements `IJBRulesetDataHook` + `IJBCashOutHook` + `IERC721Receiver`. Set as the `dataHook` in each revnet's ruleset metadata. Holds the JBProjects NFT (project owner of record). Manages operator permissions (grants `DEPLOY_SUCKERS` + `MAP_SUCKER_TOKEN` to REVDeployer in `setDeployer` so the deployer can continue driving sucker setup). Exposes `initializeRevnet` (deployer-only single-call setup), `autoIssueFor`, `burnHeldTokensOf`, `setOperatorOf`, `isOperatorOf`. Handles pay hooks, cash-out hooks, mint permissions, and sucker verification. Stores `cashOutDelayOf`, `tiered721HookOf`, `amountToAutoIssue`, and extra-operator-permission state. |
+| `REVOwner` | Project NFT owner and runtime hook for every revnet. Implements `IJBRulesetDataHook` + `IJBCashOutHook` + `IERC721Receiver`. Set as the `dataHook` in each revnet's ruleset metadata. Holds the JBProjects NFT (project owner of record). Manages operator permissions (grants `DEPLOY_SUCKERS` + `MAP_SUCKER_TOKEN` to REVDeployer in `setDeployer` so the deployer can continue driving sucker setup). Exposes `initializeRevnet` (deployer-only single-call setup), `autoIssueFor`, `burnHeldTokensOf`, `setOperatorOf`, `isOperatorOf`. Handles pay hooks, cash-out hooks, mint permissions, and sucker verification. Stores `cashOutDelayOf`, `tiered721HookOf`, `amountToAutoIssue`, and extra-operator-permission state. |
 | `REVLoans` | Issues token-collateralized loans from revnet treasuries. Each loan is an ERC-721 NFT. Burns collateral on borrow, re-mints on repay. Charges tiered fees (REV protocol fee + source fee + prepaid fee). |
 
 ## Key Functions
@@ -66,7 +66,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REVLoans.determineSourceFeeAmount(loan, amount)` | Calculate the time-proportional source fee for a loan repayment. Zero during prepaid window, linear accrual after. |
 | `REVLoans.loanOf(loanId)` | Returns the full `REVLoan` struct for a loan. |
 | `REVLoans.loanSourceTokensOf(revnetId)` | Returns all token sources used for loans by a revnet. Loans always source funds from the canonical `MULTI_TERMINAL`. |
-| `REVLoans.revnetIdOfLoanWith(loanId)` | Decode the revnet ID from a loan ID (`loanId / 1_000_000_000_000`). |
+| `REVLoans.revnetIdOfLoanWith(loanId)` | Decode the revnet ID from a loan ID (`loanId / 1_000_000_000_000_000_000`). |
 ## Integration Points
 
 | Dependency | Import | Used For |

package/script/Deploy.s.sol

@@ -54,17 +54,17 @@ struct FeeProjectConfig {
 }
 
 contract DeployScript is Script, Sphinx {
-    /// @notice tracks the deployment of the buyback hook.
+    /// @notice Tracks the deployment of the buyback hook.
     BuybackDeployment buybackHook;
-    /// @notice tracks the deployment of the core contracts for the chain we are deploying to.
+    /// @notice Tracks the deployment of the core contracts for the chain we are deploying to.
     CoreDeployment core;
-    /// @notice tracks the deployment of the croptop contracts for the chain we are deploying to.
+    /// @notice Tracks the deployment of the Croptop contracts for the chain we are deploying to.
     CroptopDeployment croptop;
-    /// @notice tracks the deployment of the 721 hook contracts for the chain we are deploying to.
+    /// @notice Tracks the deployment of the 721 hook contracts for the chain we are deploying to.
     Hook721Deployment hook;
-    /// @notice tracks the deployment of the sucker contracts for the chain we are deploying to.
+    /// @notice Tracks the deployment of the sucker contracts for the chain we are deploying to.
     SuckerDeployment suckers;
-    /// @notice tracks the deployment of the router terminal registry package.
+    /// @notice Tracks the deployment of the router terminal registry package.
     RouterTerminalDeployment routerTerminal;
     uint32 private constant _PREMINT_CHAIN_ID = 1;
     string private constant _NAME = "Revnet";
@@ -102,7 +102,7 @@ contract DeployScript is Script, Sphinx {
         // Get the loans owner address.
         loansOwner = safeAddress();
 
-        // Get the deployment addresses for the nana CORE for this chain.
+        // Get the core deployment addresses for this chain.
         // We want to do this outside of the `sphinx` modifier.
         core = CoreDeploymentLib.getDeployment(
             vm.envOr({
@@ -116,13 +116,13 @@ contract DeployScript is Script, Sphinx {
                 defaultValue: string("node_modules/@bananapus/suckers-v6/deployments/")
             })
         );
-        // Get the deployment addresses for the 721 hook contracts for this chain.
+        // Get the Croptop deployment addresses for this chain.
         croptop = CroptopDeploymentLib.getDeployment(
             vm.envOr({
                 name: "CROPTOP_CORE_DEPLOYMENT_PATH", defaultValue: string("node_modules/@croptop/core-v6/deployments/")
             })
         );
-        // Get the deployment addresses for the 721 hook contracts for this chain.
+        // Get the buyback hook deployment addresses for this chain.
         hook = Hook721DeploymentLib.getDeployment(
             vm.envOr({
                 name: "NANA_721_DEPLOYMENT_PATH",
@@ -223,7 +223,7 @@ contract DeployScript is Script, Sphinx {
             autoIssuances: new REVAutoIssuance[](0),
             splitPercent: 3800, // 38%
             splits: splits,
-            initialIssuance: 0, // no more issaunce.
+            initialIssuance: 0, // no more issuance.
             issuanceCutFrequency: 0,
             issuanceCutPercent: 0,
             cashOutTaxRate: 1000, // 0.1
@@ -316,24 +316,11 @@ contract DeployScript is Script, Sphinx {
     }
 
     function deploy() public sphinx {
-        // Check if singletons are already deployed before creating a new fee project.
-        // This prevents creating orphan projects on script restarts.
+        // Check whether the deterministic singletons already exist before creating a new fee project.
+        // This prevents orphan projects on script restarts.
         uint256 feeProjectId;
 
-        // Predict the REVLoans address for an arbitrary fee project ID to check if it exists.
-        // We can't predict without a fee project ID, so we first check the REVDeployer which also stores it.
-        // Try a two-step approach: compute addresses assuming singletons exist, then check.
-
-        // First, check if REVLoans is already deployed by trying with project ID = 0 (placeholder).
-        // We need to iterate: if either singleton exists, extract the fee project ID from it.
-        // Since both encode feeProjectId, we check if any code exists at the predicted address
-        // for sequential project IDs starting from 1.
-
-        // A simpler approach: predict the REVDeployer address for each possible fee project ID
-        // until we find one that's deployed, or give up and create a new one.
-        // In practice, the fee project is always one of the first few projects created.
-
-        // Check the next project ID that would be created — if singletons were deployed with a previous ID,
+        // Check the next project ID that would be created. If singletons were deployed with a previous ID,
         // that ID must be less than the current count.
         uint256 _nextProjectId = core.projects.count() + 1;
 

package/src/REVDeployer.sol

@@ -47,13 +47,12 @@ import {REVOwnerRevnetInit} from "./structs/REVOwnerRevnetInit.sol";
 import {REVStageConfig} from "./structs/REVStageConfig.sol";
 import {REVSuckerDeploymentConfig} from "./structs/REVSuckerDeploymentConfig.sol";
 
-/// @notice Deploys and configures Revnets — autonomous Juicebox projects with pre-programmed tokenomics that cannot
-/// be
-/// changed after launch. Each revnet progresses through stages that define issuance rate, decay schedule, cash-out tax,
-/// split allocations, and auto-issuances. The deployer translates these stage configurations into Juicebox rulesets,
-/// sets up a buyback hook for secondary market routing, deploys a tiered 721 hook, optionally configures Croptop
-/// posting, and can deploy cross-chain suckers. Once deployed, the project NFT is held by this contract — no single
-/// address can modify the revnet's rules.
+/// @notice Deploys and configures Revnets: autonomous Juicebox projects with immutable staged tokenomics.
+/// @dev Each revnet progresses through stages that define issuance rate, decay schedule, cash-out tax, split
+/// allocations, and auto-issuances. The deployer translates these stage configurations into Juicebox rulesets, sets up
+/// a buyback hook for secondary market routing, deploys a tiered 721 hook, optionally configures Croptop posting, and
+/// can deploy cross-chain suckers. Once deployed, the project NFT is held by this contract — no single address can
+/// modify the revnet's rules.
 /// @dev Revnets are unowned Juicebox projects which operate autonomously after deployment. Runtime data hook logic
 /// (pay/cash-out callbacks) is handled by the separate `REVOwner` contract to stay within EIP-170 size limits.
 contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
@@ -106,21 +105,21 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @notice The directory of terminals and controllers for Juicebox projects (and revnets).
     IJBDirectory public immutable override DIRECTORY;
 
-    /// @notice The Juicebox project ID of the revnet that receives cash out fees.
+    /// @notice The Juicebox project ID of the revnet that receives cash-out fees.
     uint256 public immutable override FEE_REVNET_ID;
 
     /// @notice Deploys tiered ERC-721 hooks for revnets.
     IJB721TiersHookDeployer public immutable override HOOK_DEPLOYER;
 
-    /// @notice The loan contract used by all revnets.
+    /// @notice The loan contract used by every revnet.
     /// @dev Revnets can offer loans to their participants, collateralized by their tokens.
-    /// Participants can borrow up to the current cash out value of their tokens.
+    /// Participants can borrow up to the current cash-out value of their tokens.
     IREVLoans public immutable override LOANS;
 
     /// @notice The canonical terminal that holds revnet treasury balances.
     IJBTerminal public immutable override MULTI_TERMINAL;
 
-    /// @notice The runtime data hook contract that handles pay and cash out callbacks for revnets.
+    /// @notice The runtime data hook contract that handles pay and cash-out callbacks for revnets.
     /// @dev Set as `dataHook` in each revnet's ruleset metadata. Implements `IJBRulesetDataHook` and `IJBCashOutHook`.
     address public immutable override OWNER;
 
@@ -162,11 +161,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @param suckerRegistry The registry to use for deploying and tracking each revnet's suckers.
     /// @param feeRevnetId The Juicebox project ID of the revnet that will receive fees.
     /// @param hookDeployer The deployer to use for revnet's tiered ERC-721 hooks.
-    /// @param publisher The croptop publisher revnets can use to publish ERC-721 posts to their tiered ERC-721 hooks.
+    /// @param publisher The Croptop publisher revnets can use to publish ERC-721 posts to their tiered ERC-721 hooks.
     /// @param buybackHook The buyback hook used as a data hook to route payments through buyback pools.
-    /// @param loans The loan contract used by all revnets.
+    /// @param loans The loan contract used by every revnet.
     /// @param trustedForwarder The trusted forwarder for the ERC2771Context.
-    /// @param owner The runtime data hook contract (REVOwner) that handles pay and cash out callbacks.
+    /// @param owner The runtime data hook contract (REVOwner) that handles pay and cash-out callbacks.
     constructor(
         IJBController controller,
         IJBTerminal multiTerminal,
@@ -301,11 +300,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         metadata.cashOutTaxRate = stageConfiguration.cashOutTaxRate;
         metadata.baseCurrency = baseCurrency;
         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
-        // outs.
-        metadata.dataHook = OWNER; // The REVOwner contract is the data hook.
+        // Allow `REVOwner` to auto-mint configured allocations and handle pay/cash-out callbacks.
+        metadata.allowOwnerMinting = true;
+        metadata.useDataHookForPay = true;
+        metadata.useDataHookForCashOut = true;
+        metadata.dataHook = OWNER;
         metadata.metadata = stageConfiguration.extraMetadata;
 
         // Package the reserved token splits.
@@ -449,7 +448,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             sqrtPriceX96: sqrtPriceX96
         }) {}
             catch {
-            // Two failure modes both end up here and both must NOT block the revnet deploy:
+            // Two failure modes both end up here and both must not block the revnet deploy:
             //  1. The V4 pool is already initialized at the expected price (idempotent re-deploy). The buyback
             //     hook's strict price check inside `initializePoolFor` would still call `_setPoolFor`, so the
             //     try-branch already covered this. We reach this catch only when the check rejected the existing
@@ -470,7 +469,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @dev When initializing an existing project (revnetId != 0):
     /// - The project must not yet have a controller or rulesets. `JBController.launchRulesetsFor` enforces this —
     ///   it reverts if rulesets have already been launched, and `JBDirectory.setControllerOf` only allows setting the
-    ///   first controller. This means conversion only works for blank projects (just an ID with no on-chain state).
+    ///   first controller. This means conversion only works for blank projects: an ID with no on-chain state.
     /// - This is useful in deploy scripts where the project ID is needed before configuration (e.g. for cross-chain
     ///   sucker peer mappings): create the project first, then initialize it as a revnet here.
     /// - Initialization is a one-way operation: the project's ownership NFT is permanently transferred to this
@@ -480,7 +479,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @param accountingContextsToAccept The accounting contexts the canonical multi terminal should accept.
     /// @param suckerDeploymentConfiguration The suckers to set up for cross-chain token transfers.
     /// @param tiered721HookConfiguration How to configure the tiered ERC-721 hook for the revnet.
-    /// @param allowedPosts Restrictions on which croptop posts to allow on the revnet's ERC-721 tiers.
+    /// @param allowedPosts Restrictions on which Croptop posts to allow on the revnet's ERC-721 tiers.
     /// @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.
@@ -507,7 +506,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             revert REVDeployer_ProjectCreationFeeNotNeeded({revnetId: revnetId, value: msg.value});
         }
 
-        // Deploy the revnet with the specified tiered ERC-721 hook and croptop posting criteria.
+        // Deploy the revnet with the specified tiered ERC-721 hook and Croptop posting criteria.
         hook = _deploy721RevnetFor({
             revnetId: revnetId,
             shouldDeployNewRevnet: shouldDeployNewRevnet,
@@ -619,7 +618,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     // --------------------- internal transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Deploy a revnet which sells tiered ERC-721s and (optionally) allows croptop posts to its ERC-721 tiers.
+    /// @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.
     function _deploy721RevnetFor(
         uint256 revnetId,
@@ -726,7 +725,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             // deployer passes that check directly only before ownership is scoped to REVOwner below.
             PUBLISHER.configurePostingCriteriaFor({allowedPosts: formattedAllowedPosts});
 
-            // Give the croptop publisher permission to post new ERC-721 tiers on the revnet's behalf.
+            // Give the Croptop publisher permission to post new ERC-721 tiers on the revnet's behalf.
             ownerInit.extraGrants = new REVOwnerExtraGrant[](1);
             ownerInit.extraGrants[0] =
                 REVOwnerExtraGrant({operator: address(PUBLISHER), permissionId: JBPermissionIds.ADJUST_721_TIERS});
@@ -798,7 +797,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             memo: ""
         });
 
-        // Compute the cash out delay if the revnet's stages are already in progress. This prevents cash out
+        // Compute the cash-out delay if the revnet's stages are already in progress. This prevents cash-out
         // liquidity/arbitrage issues for existing revnets which are deploying to a new chain.
         ownerInit.cashOutDelay =
             _computeCashOutDelayIfNeeded({revnetId: revnetId, firstStageConfig: configuration.stageConfigurations[0]});
@@ -951,11 +950,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
 
         // Iterate through each stage to set up its ruleset.
         for (uint256 i; i < configuration.stageConfigurations.length;) {
-            // Set the stage being iterated on.
+            // Read the stage being converted into a ruleset.
             REVStageConfig calldata stageConfiguration = configuration.stageConfigurations[i];
 
             // 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.
+            // Otherwise, the reserved-token residue would stay with this contract as the revnet's owner.
             if (stageConfiguration.splitPercent > 0 && stageConfiguration.splits.length == 0) {
                 revert REVDeployer_MustHaveSplits({stageIndex: i, splitPercent: stageConfiguration.splitPercent});
             }
@@ -975,7 +974,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             // Store for the next iteration's ordering check.
             previousStageStart = effectiveStart;
 
-            // Make sure the revnet doesn't prevent cashouts all together.
+            // Make sure the revnet does not disable cash-outs completely.
             if (stageConfiguration.cashOutTaxRate >= JBConstants.MAX_CASH_OUT_TAX_RATE) {
                 revert REVDeployer_CashOutsCantBeTurnedOffCompletely({
                     cashOutTaxRate: stageConfiguration.cashOutTaxRate,
@@ -1055,12 +1054,12 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         encodedConfigurationHash = keccak256(encodedConfiguration);
     }
 
-    /// @notice Compute the cash out delay for the revnet's first stage if its stages are already in progress.
+    /// @notice Compute the cash-out delay for the revnet's first stage if its stages are already in progress.
     /// @dev Returns 0 when no delay is needed. Emits `SetCashOutDelay` so deployer-side telemetry stays unchanged
     /// even though the actual storage write happens later inside `REVOwner.initializeRevnet`.
-    /// @param revnetId The ID of the revnet to compute the cash out delay for.
+    /// @param revnetId The ID of the revnet to compute the cash-out delay for.
     /// @param firstStageConfig The revnet's first stage.
-    /// @return cashOutDelay The timestamp after which cash outs are allowed, or 0 if no delay applies.
+    /// @return cashOutDelay The timestamp after which cash-outs are allowed, or 0 if no delay applies.
     function _computeCashOutDelayIfNeeded(
         uint256 revnetId,
         REVStageConfig calldata firstStageConfig
@@ -1069,11 +1068,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         returns (uint256 cashOutDelay)
     {
         // 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.
+        // 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 0;
 
-        // Calculate the timestamp at which the cash out delay ends.
+        // Calculate the timestamp at which the cash-out delay ends.
         cashOutDelay = block.timestamp + CASH_OUT_DELAY;
 
         emit SetCashOutDelay({revnetId: revnetId, cashOutDelay: cashOutDelay, caller: _msgSender()});

package/src/REVLoans.sol

@@ -41,8 +41,8 @@ import {REVLoan} from "./structs/REVLoan.sol";
 /// revnet's token structure orderly. Each loan is represented as an ERC-721 NFT that can be transferred.
 /// @dev Fee structure: an upfront fee is taken at borrow time. 2.5% goes to the source revnet
 /// (MIN_PREPAID_FEE_PERCENT), 1% goes to the $REV revnet (REV_PREPAID_FEE_PERCENT), and a variable amount chosen by the
-/// borrower determines the
-/// prepaid duration — the more paid upfront, the longer the borrower can hold without additional cost. After the
+/// borrower determines the prepaid duration — the more paid upfront, the longer the borrower can hold without
+/// additional cost. After the
 /// prepaid duration expires, the repayment cost increases linearly until the loan liquidates at 10 years
 /// (LOAN_LIQUIDATION_DURATION), at which point the collateral is permanently lost.
 /// @dev The loaned amounts include the fees taken, meaning the amount paid back is the amount borrowed plus the fees.
@@ -104,9 +104,12 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     // ------------------------ private constants ------------------------ //
     //*********************************************************************//
 
-    /// @notice Just a kind reminder to our readers.
-    /// @dev Used in loan token ID generation.
-    uint256 private constant _ONE_TRILLION = 1_000_000_000_000;
+    /// @notice The number of loan IDs reserved for each revnet.
+    /// @dev Loan IDs are encoded as `revnetId * _LOAN_ID_NAMESPACE_SIZE + loanNumber`.
+    uint256 private constant _LOAN_ID_NAMESPACE_SIZE = 1_000_000_000_000_000_000;
+
+    /// @dev This is the largest loan number that stays in the current revnet's ID namespace.
+    uint256 private constant _MAX_LOAN_NUMBER = _LOAN_ID_NAMESPACE_SIZE - 1;
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -171,8 +174,8 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     // --------------------- internal stored properties ------------------ //
     //*********************************************************************//
 
-    /// @notice The loans.
-    /// @custom:member The ID of the loan.
+    /// @notice The loan state for each loan ID.
+    /// @custom:param loanId The ID of the loan.
     mapping(uint256 loanId => REVLoan) internal _loanOf;
 
     /// @notice The sources of each revnet's loan.
@@ -308,7 +311,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @param loanId The loan ID to look up.
     /// @return The ID of the revnet.
     function revnetIdOfLoanWith(uint256 loanId) public pure override returns (uint256) {
-        return loanId / _ONE_TRILLION;
+        return loanId / _LOAN_ID_NAMESPACE_SIZE;
     }
 
     /// @notice Returns the URI where the ERC-721 standard JSON of a loan is hosted.
@@ -518,7 +521,7 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @param loanNumber The loan number within the revnet.
     /// @return The token ID of the 721.
     function _generateLoanId(uint256 revnetId, uint256 loanNumber) internal pure returns (uint256) {
-        return (revnetId * _ONE_TRILLION) + loanNumber;
+        return (revnetId * _LOAN_ID_NAMESPACE_SIZE) + loanNumber;
     }
 
     /// @notice The calldata. Preferred to use over `msg.data`.
@@ -689,15 +692,15 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
 
         // Prevent cross-revnet accounting corruption: every iterated loan number must stay within the revnet's ID
         // namespace.
-        if (startingLoanId > _ONE_TRILLION) {
+        if (startingLoanId > _MAX_LOAN_NUMBER) {
             revert REVLoans_LoanIdOverflow({
-                revnetId: revnetId, loanNumber: startingLoanId, maxLoanNumber: _ONE_TRILLION
+                revnetId: revnetId, loanNumber: startingLoanId, maxLoanNumber: _MAX_LOAN_NUMBER
             });
         }
-        uint256 maxCount = _ONE_TRILLION - startingLoanId + 1;
+        uint256 maxCount = _MAX_LOAN_NUMBER - startingLoanId + 1;
         if (count > maxCount) {
             revert REVLoans_LoanIdOverflow({
-                revnetId: revnetId, loanNumber: _ONE_TRILLION + 1, maxLoanNumber: _ONE_TRILLION
+                revnetId: revnetId, loanNumber: _LOAN_ID_NAMESPACE_SIZE, maxLoanNumber: _MAX_LOAN_NUMBER
             });
         }
 
@@ -1388,8 +1391,10 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
     /// @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});
+        if (loanNumber > _MAX_LOAN_NUMBER) {
+            revert REVLoans_LoanIdOverflow({
+                revnetId: revnetId, loanNumber: loanNumber, maxLoanNumber: _MAX_LOAN_NUMBER
+            });
         }
         totalLoansBorrowedFor[revnetId] = loanNumber;
         return _generateLoanId({revnetId: revnetId, loanNumber: loanNumber});

package/src/REVOwner.sol

@@ -38,10 +38,10 @@ import {REVOwnerAutoIssuance} from "./structs/REVOwnerAutoIssuance.sol";
 import {REVOwnerExtraGrant} from "./structs/REVOwnerExtraGrant.sol";
 import {REVOwnerRevnetInit} from "./structs/REVOwnerRevnetInit.sol";
 
-/// @notice The runtime hook for all revnets — set as every revnet's `dataHook` in ruleset metadata. At pay time, it
+/// @notice The runtime hook for every revnet — set as each 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 with a non-zero
+/// loan debt and collateral), grants suckers 0% tax, splits a 2.5% fee from non-sucker cash-outs with a non-zero
 /// cash-out tax, 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.
@@ -73,10 +73,10 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     /// @notice The directory of terminals and controllers for Juicebox projects.
     IJBDirectory public immutable override DIRECTORY;
 
-    /// @notice The Juicebox project ID of the revnet that receives cash out fees.
+    /// @notice The Juicebox project ID of the revnet that receives cash-out fees.
     uint256 public immutable override FEE_REVNET_ID;
 
-    /// @notice The loan contract used by all revnets.
+    /// @notice The loan contract used by every revnet.
     IREVLoans public immutable override LOANS;
 
     /// @notice Deploys and tracks suckers for revnets.
@@ -86,9 +86,9 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The timestamp of when cashouts will become available to a specific revnet's participants.
+    /// @notice The timestamp when cash-outs become available to a specific revnet's participants.
     /// @dev Only applies to existing revnets deploying onto a new network.
-    /// @custom:param revnetId The ID of the revnet to check the cash out delay for.
+    /// @custom:param revnetId The ID of the revnet to check the cash-out delay for.
     mapping(uint256 revnetId => uint256 cashOutDelay) public override cashOutDelayOf;
 
     /// @notice Each revnet's tiered ERC-721 hook.
@@ -107,7 +107,7 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     /// @dev Set once via `setDeployer()` using the precomputed canonical REVDeployer address.
     IREVDeployer public override deployer;
 
-    /// @notice The controller used by all revnets to manage their projects.
+    /// @notice The controller used by every revnet to manage its project.
     /// @dev Cached from the deployer at `setDeployer()` time.
     IJBController public override CONTROLLER;
 
@@ -165,7 +165,7 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Called before a cash out is recorded. Suckers get 0% tax (bridged tokens redeem at face value). For
+    /// @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 when cash-out tax is non-zero, computes bonding curve
     /// reclaims for both the holder's portion and the fee portion, then delegates to the buyback hook for potential
@@ -173,12 +173,12 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     /// @dev Part of `IJBRulesetDataHook`. In the non-zero-tax fee path, 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 reclaimed.
+    /// @param context Standard Juicebox cash-out context. See `JBBeforeCashOutRecordedContext`.
+    /// @return cashOutTaxRate The cash-out tax rate, which influences the amount of terminal tokens reclaimed.
     /// @return cashOutCount The number of revnet tokens to cash out.
     /// @return totalSupply The total token supply across all chains (for both proportional reclaim and tax).
     /// @return effectiveSurplusValue The global surplus across all chains for proportional reclaim.
-    /// @return hookSpecifications The amount of funds and data to send to cash out hooks (this contract).
+    /// @return hookSpecifications The amount of funds and data to send to cash-out hooks (this contract).
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
         external
         view
@@ -201,7 +201,7 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         totalSupply = context.totalSupply + totalCollateral;
         effectiveSurplusValue = context.surplus.value + totalBorrowed;
 
-        // If the cash out is from a sucker, return the full cash out amount without taxes or fees.
+        // If the cash-out is from a sucker, return the full cash-out amount without taxes or fees.
         // Sucker cash-outs are the bridge accounting path: the value moving out of this chain must stay proportional
         // to this chain's local backing. Do not add remote supply/surplus here, even for unscoped revnets.
         // This relies on the sucker registry to only contain trusted sucker contracts deployed via
@@ -210,16 +210,16 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
             return (0, context.cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
         }
 
-        // Keep a reference to the cash out delay of the revnet.
+        // Keep a reference to the cash-out delay of the revnet.
         uint256 cashOutDelay = cashOutDelayOf[context.projectId];
 
-        // Enforce the cash out delay.
+        // Enforce the cash-out delay.
         // forge-lint: disable-next-line(block-timestamp)
         if (cashOutDelay > block.timestamp) {
             revert REVOwner_CashOutDelayNotFinished({cashOutDelay: cashOutDelay, blockTimestamp: block.timestamp});
         }
 
-        // Get the terminal that will receive the cash out fee.
+        // Get the terminal that will receive the cash-out fee.
         IJBTerminal feeTerminal = DIRECTORY.primaryTerminalOf({projectId: FEE_REVNET_ID, token: context.surplus.token});
 
         // If the ruleset aggregates cross-chain state, add remote supply and surplus.
@@ -232,8 +232,8 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
             });
         }
 
-        // If there's no cash out tax, 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 totalSupply and
+        // If there is no cash-out tax, no fee terminal, or a feeless beneficiary (e.g. the router terminal routing
+        // value between projects), proxy to the buyback hook with our totalSupply and
         // effectiveSurplusValue. Zero-tax ordinary cash-outs do not add the revnet fee hook.
         if (context.cashOutTaxRate == 0 || address(feeTerminal) == address(0) || context.beneficiaryIsFeeless) {
             // Build a modified context with cross-chain-adjusted values so the buyback hook sees the global state
@@ -249,8 +249,8 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         // The fee is applied to TOKEN COUNT (2.5% of tokens), not to value. The fee revnet receives the bonding-curve
         // reclaim of its 2.5% token share regardless of whether the remaining 97.5% routes through a buyback pool at
         // a better price. This is by design.
-        // Micro cash outs (< 40 wei at 2.5% fee) round feeCashOutCount to zero, bypassing the fee.
-        // Economically insignificant: the gas cost of the transaction far exceeds the bypassed fee. No fix needed.
+        // Micro cash-outs (< 40 wei at 2.5% fee) round feeCashOutCount to zero. This accepted floor is economically
+        // negligible because gas dominates the avoided fee.
         uint256 feeCashOutCount = JBFees.standardFeeAmountFrom(context.cashOutCount);
         uint256 nonFeeCashOutCount = context.cashOutCount - feeCashOutCount;
 
@@ -311,7 +311,7 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         buybackHookContext.totalSupply = totalSupply;
         buybackHookContext.surplus.value = buybackSurplus;
 
-        // Let the buyback hook adjust the cash out parameters and optionally return a hook specification.
+        // Let the buyback hook adjust the cash-out parameters and optionally return a hook specification.
         JBCashOutHookSpecification[] memory buybackHookSpecifications;
         (cashOutTaxRate, cashOutCount,,, buybackHookSpecifications) =
             BUYBACK_HOOK.beforeCashOutRecordedWith(buybackHookContext);
@@ -325,11 +325,11 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         // totalSupply, cashOutTaxRate)` and add the fee spec on top. When local liquidity is the binding cap, that
         // sum can exceed local surplus and revert. `cashOutFrom` is linear in `surplus`, so scale the surplus we
         // report so the store-side reclaim is at most `localSurplus - feeAmount`, preserving room for the fee.
-        // The fee is NOT scaled here — it was already scaled by the PR #149 block above. Only the store-facing
-        // surplus is touched; the buyback hook already received the full pre-cap value for its routing decision.
+        // The fee was already scaled, if needed, by the local-liquidity block above. Only the store-facing surplus is
+        // touched; the buyback hook already received the full pre-cap value for its routing decision.
         //
         // Worked example (local=10, global=100, 500 of 1000 tokens at 50% tax):
-        //   above this block (PR #149):
+        //   local-liquidity scaling above:
         //     unscaledReclaim = cashOutFrom(100, 487.5, 1000, 5000)            ≈ 36 ETH        (global)
         //     feeAmount       = cashOutFrom(64, 12.5, 512.5, 5000)             ≈ 0.78 ETH      (global)
         //     grossOutflow ≈ 36.78 > 10  →  scale both proportionally to local liquidity:
@@ -343,10 +343,9 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         //     storeReclaim = 36 × (27.18 / 100) ≈ 9.786 ETH
         //     balanceDiff  = 9.786 + 0.214 = 10 ETH = localSurplus              ✓ no revert
         //
-        // Underflow safety on `localSurplus − feeAmount`: after PR #149 the relation
-        // `feeAmount ≤ localSurplus` holds in both branches — in the scaling branch because
-        // `feeAmount ≤ grossOutflow` and the multiplier is `localSurplus / grossOutflow ≤ 1`;
-        // in the else branch because `feeAmount ≤ grossOutflow ≤ localSurplus` already.
+        // Underflow safety: `feeAmount <= localSurplus` holds in both branches.
+        // In the scaling branch, `feeAmount <= grossOutflow` and the multiplier is
+        // `localSurplus / grossOutflow <= 1`. In the else branch, `feeAmount <= grossOutflow <= localSurplus`.
         uint256 reclaimCap = context.surplus.value - feeAmount;
         if (unscaledReclaim > reclaimCap) {
             effectiveSurplusValue = mulDiv({x: effectiveSurplusValue, y: reclaimCap, denominator: unscaledReclaim});
@@ -486,11 +485,11 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Process the fee from a cash out.
+    /// @notice Process the fee from a cash-out.
     /// @param context Cash out context passed in by the terminal.
     function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context) external payable override {
         // No caller validation needed — this hook only pays fees to the fee project using funds forwarded by the
-        // caller. A non-terminal caller would just be donating their own funds as fees. There's nothing to exploit.
+        // caller. A non-terminal caller would donate their own funds as fees. There's nothing to exploit.
 
         if (context.forwardedAmount.token == JBConstants.NATIVE_TOKEN) {
             // Native fee processing must be value-balanced by the current call. Otherwise a non-terminal caller could
@@ -568,14 +567,14 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         }
 
         // Store the cash-out delay if the deployer computed one (existing revnet landing on a new chain). A zero
-        // delay means cash outs are unlocked immediately, so skip the storage write to save gas in the common case.
+        // delay means cash-outs are unlocked immediately, so skip the storage write to save gas in the common case.
         if (init.cashOutDelay != 0) {
             cashOutDelayOf[revnetId] = init.cashOutDelay;
         }
 
-        // Bind the tiered ERC-721 hook the deployer just created for this revnet so `beforePayRecordedWith` can
-        // route NFT-tier mints through it. The deployer always deploys a hook (empty or pre-tiered), so the zero
-        // guard is defensive.
+        // Bind the tiered ERC-721 hook the deployer created for this revnet so `beforePayRecordedWith` can route
+        // NFT-tier mints through it. The deployer always deploys a hook (empty or pre-tiered), so the zero guard is
+        // defensive.
         if (address(init.tiered721Hook) != address(0)) {
             tiered721HookOf[revnetId] = init.tiered721Hook;
         }
@@ -647,7 +646,7 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
         PROJECTS = newDeployer.PROJECTS();
 
         // Grant the wildcard operator permissions used by every revnet, scoped on this contract's account.
-        // The loan contract is the singleton shared by all revnets and uses the surplus allowance of each
+        // The loan contract is the singleton shared by every revnet and uses the surplus allowance of each
         // revnet's terminal. The buyback hook registry configures pools on every revnet.
         uint8[] memory loanPermissionIds = new uint8[](1);
         loanPermissionIds[0] = JBPermissionIds.USE_ALLOWANCE;
@@ -774,8 +773,9 @@ contract REVOwner is IREVOwner, IJBRulesetDataHook, IJBCashOutHook, IJBPeerChain
 
     /// @notice Indicates if this contract adheres to the specified interface.
     /// @dev See `IERC165.supportsInterface`.
-    /// @return A flag indicating if the provided interface ID is supported.
-    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+    /// @param interfaceId The interface ID to check.
+    /// @return flag A flag indicating whether the interface is supported.
+    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool flag) {
         return interfaceId == type(IERC165).interfaceId || interfaceId == type(IJBRulesetDataHook).interfaceId
             || interfaceId == type(IJBCashOutHook).interfaceId
             || interfaceId == type(IJBPeerChainAdjustedAccounts).interfaceId;

package/src/interfaces/IREVDeployer.sol

@@ -52,9 +52,9 @@ interface IREVDeployer {
         address caller
     );
 
-    /// @notice Emitted when the cash out delay is set for a revnet.
+    /// @notice Emitted when the cash-out delay is set for a revnet.
     /// @param revnetId The ID of the revnet.
-    /// @param cashOutDelay The cash out delay in seconds.
+    /// @param cashOutDelay The cash-out delay in seconds.
     /// @param caller The address that set the delay.
     event SetCashOutDelay(uint256 indexed revnetId, uint256 cashOutDelay, address caller);
 
@@ -73,7 +73,7 @@ interface IREVDeployer {
     function BUYBACK_HOOK() external view returns (IJBBuybackHookRegistry);
 
     /// @notice The number of seconds until a revnet's participants can cash out after deploying to a new network.
-    /// @return The cash out delay in seconds.
+    /// @return The cash-out delay in seconds.
     function CASH_OUT_DELAY() external view returns (uint256);
 
     /// @notice The controller used to create and manage Juicebox projects for revnets.
@@ -92,7 +92,7 @@ interface IREVDeployer {
     /// @return The directory contract.
     function DIRECTORY() external view returns (IJBDirectory);
 
-    /// @notice The Juicebox project ID of the revnet that receives cash out fees.
+    /// @notice The Juicebox project ID of the revnet that receives cash-out fees.
     /// @return The fee revnet ID.
     function FEE_REVNET_ID() external view returns (uint256);
 
@@ -105,7 +105,7 @@ interface IREVDeployer {
     /// @return The hook deployer contract.
     function HOOK_DEPLOYER() external view returns (IJB721TiersHookDeployer);
 
-    /// @notice The loan contract used by all revnets.
+    /// @notice The loan contract used by every revnet.
     /// @return The loans contract address.
     function LOANS() external view returns (IREVLoans);
 
@@ -113,7 +113,7 @@ interface IREVDeployer {
     /// @return The multi terminal contract.
     function MULTI_TERMINAL() external view returns (IJBTerminal);
 
-    /// @notice The runtime data hook contract that handles pay and cash out callbacks for revnets.
+    /// @notice The runtime data hook contract that handles pay and cash-out callbacks for revnets.
     /// @return The owner contract address.
     function OWNER() external view returns (address);
 
@@ -125,7 +125,7 @@ interface IREVDeployer {
     /// @return The projects contract.
     function PROJECTS() external view returns (IJBProjects);
 
-    /// @notice The croptop publisher revnets can use to publish ERC-721 posts to their tiered ERC-721 hooks.
+    /// @notice The Croptop publisher revnets can use to publish ERC-721 posts to their tiered ERC-721 hooks.
     /// @return The publisher contract.
     function PUBLISHER() external view returns (CTPublisher);
 
@@ -137,14 +137,14 @@ interface IREVDeployer {
     /// @return The sucker registry contract.
     function SUCKER_REGISTRY() external view returns (IJBSuckerRegistry);
 
-    /// @notice Deploy a revnet with a tiered ERC-721 hook and optional croptop posting support.
+    /// @notice Deploy a revnet with a tiered ERC-721 hook and optional Croptop posting support.
     /// @dev Every revnet gets a 721 hook — pass an empty config if no tiers are needed initially.
     /// @param revnetId The ID of the Juicebox project to initialize. Send 0 to deploy a new revnet.
     /// @param configuration Core revnet configuration.
     /// @param accountingContextsToAccept The accounting contexts the canonical multi terminal should accept.
     /// @param suckerDeploymentConfiguration The suckers to set up for cross-chain token transfers.
     /// @param tiered721HookConfiguration How to configure the tiered ERC-721 hook for the revnet.
-    /// @param allowedPosts Restrictions on which croptop posts to allow on the revnet's ERC-721 tiers.
+    /// @param allowedPosts Restrictions on which Croptop posts to allow on the revnet's ERC-721 tiers.
     /// @return The ID of the newly created or initialized revnet.
     /// @return hook The tiered ERC-721 hook deployed for the revnet.
     function deployFor(

package/src/interfaces/IREVOwner.sol

@@ -54,7 +54,7 @@ interface IREVOwner {
     /// @return The directory instance.
     function DIRECTORY() external view returns (IJBDirectory);
 
-    /// @notice The Juicebox project ID of the revnet that receives cash out fees.
+    /// @notice The Juicebox project ID of the revnet that receives cash-out fees.
     /// @return The fee revnet's Juicebox project ID.
     function FEE_REVNET_ID() external view returns (uint256);
 
@@ -81,9 +81,9 @@ interface IREVOwner {
     /// @return The number of tokens available to auto-issue.
     function amountToAutoIssue(uint256 revnetId, uint256 stageId, address beneficiary) external view returns (uint256);
 
-    /// @notice The timestamp at which cash outs become available for a specific revnet's participants.
+    /// @notice The timestamp at which cash-outs become available for a specific revnet's participants.
     /// @param revnetId The ID of the revnet.
-    /// @return The cash out delay timestamp (0 if no delay applies).
+    /// @return The cash-out delay timestamp (0 if no delay applies).
     function cashOutDelayOf(uint256 revnetId) external view returns (uint256);
 
     /// @notice The canonical deployer that manages runtime hook state.

package/src/structs/REVCroptopAllowedPost.sol

@@ -5,7 +5,8 @@ pragma solidity ^0.8.0;
 /// @custom:member category The category to allow posts for.
 /// @custom:member minimumPrice The minimum price a post to the specified category must cost.
 /// @custom:member minimumTotalSupply The minimum total supply of NFTs to make available when minting.
-/// @custom:member maxTotalSupply The max total supply of NFTs to make available when minting. Leave as 0 for unlimited.
+/// @custom:member maximumTotalSupply The max total supply of NFTs to make available when minting. Leave as 0 for
+/// unlimited.
 /// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) a poster can
 /// set. 0 means splits are not allowed.
 /// @custom:member allowedAddresses The addresses allowed to post on the category through Croptop.

package/src/structs/REVDeploy721TiersHookConfig.sol

@@ -3,16 +3,13 @@ pragma solidity ^0.8.0;
 
 import {REVBaseline721HookConfig} from "./REVBaseline721HookConfig.sol";
 
-/// @custom:member baseline721HookConfiguration The baseline 721 hook config.
+/// @custom:member baseline721HookConfiguration The base tiered ERC-721 hook config.
 /// @custom:member salt The salt to derive the collection's address from.
-/// @custom:member preventOperatorAdjustingTiers Whether to prevent the operator from adding and removing
-/// tiers.
-/// @custom:member preventOperatorUpdatingMetadata Whether to prevent the operator from updating the 721's
-/// metadata.
-/// @custom:member preventOperatorMinting Whether to prevent the operator from minting 721s from tiers that
-/// allow it.
-/// @custom:member preventOperatorIncreasingDiscountPercent Whether to prevent the operator from increasing
-/// the discount of a tier.
+/// @custom:member preventOperatorAdjustingTiers Whether to prevent the operator from adding and removing tiers.
+/// @custom:member preventOperatorUpdatingMetadata Whether to prevent the operator from updating the 721's metadata.
+/// @custom:member preventOperatorMinting Whether to prevent the operator from minting 721s from tiers that allow it.
+/// @custom:member preventOperatorIncreasingDiscountPercent Whether to prevent the operator from increasing a tier's
+/// discount.
 struct REVDeploy721TiersHookConfig {
     REVBaseline721HookConfig baseline721HookConfiguration;
     bytes32 salt;

package/src/structs/REVStageConfig.sol

@@ -7,10 +7,10 @@ import {REVAutoIssuance} from "./REVAutoIssuance.sol";
 
 /// @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.
+/// 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).
+/// 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).

package/src/structs/REVSuckerDeploymentConfig.sol

@@ -3,8 +3,8 @@ pragma solidity ^0.8.0;
 
 import {JBSuckerDeployerConfig} from "@bananapus/suckers-v6/src/structs/JBSuckerDeployerConfig.sol";
 
-/// @custom:member deployerConfigurations The configuration for bridging tokens to other chains.
-/// @custom:member salt The salt to use for deterministic sucker addresses across chains.
+/// @custom:member deployerConfigurations The sucker deployers and token bridge mappings to configure.
+/// @custom:member salt Extra caller-provided entropy mixed with the revnet config hash and deployer caller.
 struct REVSuckerDeploymentConfig {
     JBSuckerDeployerConfig[] deployerConfigurations;
     bytes32 salt;