@rev-net/core-v6 0.0.37 → 0.0.40

package/CHANGELOG.md

@@ -52,8 +52,8 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 - `IREVDeployer.deployFor(...)` now has overloads that return `(uint256, IJB721TiersHook)`.
 - `IREVDeployer.BUYBACK_HOOK()`, `LOANS()`, and `OWNER()` are explicit v6 surface area.
 - `IREVOwner` is a new interface and runtime counterpart to the deployer.
-- `IREVHiddenTokens` is a new interface for temporary token hiding (burn to exclude from totalSupply, re-mint on reveal).
-- `REVHiddenTokens` is a new standalone contract that lets holders temporarily hide tokens to increase cash-out value for remaining holders.
+- `IREVHiddenTokens` is a new interface for temporary token hiding (burn to exclude from live totalSupply, re-mint on reveal).
+- `REVHiddenTokens` is a new standalone contract that lets holders temporarily hide tokens from visible/governance supply while `REVOwner` and `REVLoans` keep hidden balances in economic denominators.
 - The old caller-supplied `REVBuybackHookConfig` path is no longer part of the deployer interface.
 
 ## Breaking ABI changes

package/README.md

@@ -19,7 +19,8 @@ This package provides:
 - a deployer that launches Revnets and stores their long-lived configuration
 - a runtime hook that mediates pay, cash-out, mint-permission, and delayed-cash-out behavior
 - a loan system that burns token collateral on borrow and remints on repayment
-- a hidden-token system that temporarily removes tokens from visible supply
+- a hidden-token system that temporarily removes tokens from visible supply while preserving economic claim
+  denominators
 
 It also composes with the 721 hook stack, buyback hook, router terminal, Croptop, and suckers where needed.
 
@@ -32,7 +33,7 @@ Use this repo when the product is a treasury-backed network with encoded stage t
 | `REVDeployer` | Launches and configures Revnets, stages, split 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. |
-| `REVHiddenTokens` | Lets token holders temporarily hide tokens, excluding them from visible supply until reveal. |
+| `REVHiddenTokens` | Lets token holders temporarily hide tokens from visible/governance supply until reveal, while cash-out and loan denominators still count hidden supply. |
 
 ## Mental Model
 
@@ -71,7 +72,7 @@ Most mistakes come from assuming a deploy-time parameter can be changed later or
 2. `test/REVLoans.invariants.t.sol`
 3. `test/TestLongTailEconomics.t.sol`
 4. `test/fork/TestLoanBorrowFork.t.sol`
-5. `test/audit/CodexPhantomSurplusTerminal.t.sol`
+5. `test/audit/PhantomSurplusTerminal.t.sol`
 
 ## Install
 
@@ -83,16 +84,14 @@ npm install @rev-net/core-v6
 
 ```bash
 npm install
-forge build
-forge test
+forge build --deny notes
+forge test --deny notes
 ```
 
 Useful scripts:
 
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
-- `npm run deploy:mainnets:1_1`
-- `npm run deploy:testnets:1_1`
 
 ## Deployment Notes
 

package/foundry.toml

@@ -22,7 +22,7 @@ runs = 64
 depth = 50
 
 [lint]
-exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
+exclude_lints = ["mixed-case-variable", "pascal-case-struct"]
 lint_on_build = false
 
 [rpc_endpoints]

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@rev-net/core-v6",
-  "version": "0.0.37",
+  "version": "0.0.40",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rev-net/revnet-core-v6"
   },
+  "files": [
+    "CHANGELOG.md",
+    "foundry.toml",
+    "references/",
+    "remappings.txt",
+    "script/Deploy.s.sol",
+    "script/helpers/",
+    "src/"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -13,26 +22,24 @@
     "test": "forge test",
     "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
     "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
-    "deploy:mainnets:1_1": "source ./.env && npx sphinx propose ./script/Deploy1_1.s.sol --networks mainnets",
     "deploy:testnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
-    "deploy:testnets:1_1": "source ./.env && npx sphinx propose ./script/Deploy1_1.s.sol --networks testnets",
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'revnet-core-v6'"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.38",
-    "@bananapus/buyback-hook-v6": "^0.0.30",
-    "@bananapus/core-v6": "^0.0.36",
-    "@bananapus/ownable-v6": "^0.0.20",
-    "@bananapus/permission-ids-v6": "^0.0.19",
-    "@bananapus/router-terminal-v6": "^0.0.30",
-    "@bananapus/suckers-v6": "^0.0.28",
-    "@croptop/core-v6": "^0.0.36",
-    "@openzeppelin/contracts": "^5.6.1",
-    "@uniswap/v4-core": "^1.0.2",
-    "@uniswap/v4-periphery": "^1.0.3"
+    "@bananapus/721-hook-v6": "0.0.43",
+    "@bananapus/buyback-hook-v6": "0.0.37",
+    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/ownable-v6": "0.0.24",
+    "@bananapus/permission-ids-v6": "0.0.22",
+    "@bananapus/router-terminal-v6": "0.0.36",
+    "@bananapus/suckers-v6": "0.0.33",
+    "@croptop/core-v6": "0.0.39",
+    "@openzeppelin/contracts": "5.6.1",
+    "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219"
   },
   "devDependencies": {
-    "@bananapus/address-registry-v6": "^0.0.17",
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@bananapus/address-registry-v6": "0.0.25",
+    "@sphinx-labs/plugins": "0.33.3",
+    "@uniswap/v4-core": "1.0.2"
   }
 }

package/references/operations.md

@@ -143,7 +143,7 @@ Use this file when you need revnet-specific risks, state reads, constants, or ex
 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`.
 20. **REVDeployer always deploys a 721 hook** via `HOOK_DEPLOYER.deployHookFor` — even if `baseline721HookConfiguration` has empty tiers. This is correct by design: it lets the split operator add and sell NFTs later without migration. Non-revnet projects should follow the same pattern by using `JB721TiersHookProjectDeployer.launchProjectFor` (or `JBOmnichainDeployer.launchProjectFor`) instead of bare `launchProjectFor`.
 21. **REVOwner deployer binding is precomputed.** REVOwner records the account that created it as an internal one-time binder. That account must call `setDeployer(precomputedRevDeployerAddress)` exactly once before the canonical REVDeployer is deployed. This avoids an ambient public initializer while keeping the circular dependency manageable. If `setDeployer(...)` is never called, all DEPLOYER-gated runtime configuration breaks.
-22. **Hidden tokens are economic, not cosmetic.** Hiding burns visible tokens and lowers visible supply until reveal. That changes cash-out and loan-relative economics for everyone else.
+22. **Hidden tokens are economic, not cosmetic.** Hiding burns visible tokens and lowers visible/governance supply until reveal. Cash-out and loan denominators still include hidden balances because they are recoverable claims.
 
 ### NATIVE_TOKEN Accounting on Non-ETH Chains
 

package/references/runtime.md

@@ -102,6 +102,6 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 | Function | Permissions | What it does |
 |----------|------------|-------------|
-| `REVHiddenTokens.hideTokensOf(revnetId, tokenCount, holder)` | Holder only. The holder must either be allowlisted or personally hold `HIDE_TOKENS`. | Burns visible tokens, increases hidden balance, and lowers visible supply. |
+| `REVHiddenTokens.hideTokensOf(revnetId, tokenCount, holder)` | Holder only. The holder must either be allowlisted or personally hold `HIDE_TOKENS`. | Burns visible tokens, increases hidden balance, and lowers visible supply. Cash-out and loan denominators still include the hidden balance while it is revealable. |
 | `REVHiddenTokens.revealTokensOf(revnetId, tokenCount, holder)` | Holder only | Re-mints previously hidden tokens back to the holder and reduces hidden balance. |
 | `REVHiddenTokens.setTokenHidingAllowedFor(revnetId, holder, isAllowed)` | Operator with `HIDE_TOKENS` | Allows or revokes a holder's ability to hide their own tokens. |

package/script/Deploy.s.sol

@@ -289,14 +289,16 @@ contract DeployScript is Script, Sphinx {
             if (block.chainid == 1 || block.chainid == 11_155_111) {
                 suckerDeployerConfigurations = new JBSuckerDeployerConfig[](3);
                 // OP
-                suckerDeployerConfigurations[0] =
-                    JBSuckerDeployerConfig({deployer: suckers.optimismDeployer, mappings: tokenMappings});
+                suckerDeployerConfigurations[0] = JBSuckerDeployerConfig({
+                    deployer: suckers.optimismDeployer, peer: bytes32(0), mappings: tokenMappings
+                });
 
                 suckerDeployerConfigurations[1] =
-                    JBSuckerDeployerConfig({deployer: suckers.baseDeployer, mappings: tokenMappings});
+                    JBSuckerDeployerConfig({deployer: suckers.baseDeployer, peer: bytes32(0), mappings: tokenMappings});
 
-                suckerDeployerConfigurations[2] =
-                    JBSuckerDeployerConfig({deployer: suckers.arbitrumDeployer, mappings: tokenMappings});
+                suckerDeployerConfigurations[2] = JBSuckerDeployerConfig({
+                    deployer: suckers.arbitrumDeployer, peer: bytes32(0), mappings: tokenMappings
+                });
             } else {
                 suckerDeployerConfigurations = new JBSuckerDeployerConfig[](1);
                 // L2 -> Mainnet
@@ -304,6 +306,7 @@ contract DeployScript is Script, Sphinx {
                     deployer: address(suckers.optimismDeployer) != address(0)
                         ? suckers.optimismDeployer
                         : address(suckers.baseDeployer) != address(0) ? suckers.baseDeployer : suckers.arbitrumDeployer,
+                    peer: bytes32(0),
                     mappings: tokenMappings
                 });
 
@@ -493,8 +496,8 @@ contract DeployScript is Script, Sphinx {
                 directory: core.controller.DIRECTORY(),
                 feeRevnetId: FEE_PROJECT_ID,
                 suckerRegistry: suckers.registry,
-                loans: address(revloans),
-                hiddenTokens: address(revHiddenTokens)
+                loans: revloans,
+                hiddenTokens: revHiddenTokens
             });
 
         // Deploy REVDeployer with the REVLoans, buyback hook, and REVOwner addresses.
@@ -510,7 +513,7 @@ contract DeployScript is Script, Sphinx {
                     hook.hook_deployer,
                     croptop.publisher,
                     IJBBuybackHookRegistry(address(buybackHook.registry)),
-                    address(revloans),
+                    revloans,
                     TRUSTED_FORWARDER,
                     address(revOwner)
                 )
@@ -527,7 +530,7 @@ contract DeployScript is Script, Sphinx {
                 hookDeployer: hook.hook_deployer,
                 publisher: croptop.publisher,
                 buybackHook: IJBBuybackHookRegistry(address(buybackHook.registry)),
-                loans: address(revloans),
+                loans: revloans,
                 trustedForwarder: TRUSTED_FORWARDER,
                 owner: address(revOwner)
             });

package/src/REVDeployer.sol

@@ -22,6 +22,7 @@ import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
 import {JBRulesetConfig} from "@bananapus/core-v6/src/structs/JBRulesetConfig.sol";
 import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
 import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
+import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 import {JBTerminalConfig} from "@bananapus/core-v6/src/structs/JBTerminalConfig.sol";
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
@@ -33,6 +34,7 @@ import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Recei
 import {mulDiv, sqrt} from "@prb/math/src/Common.sol";
 
 import {IREVDeployer} from "./interfaces/IREVDeployer.sol";
+import {IREVLoans} from "./interfaces/IREVLoans.sol";
 import {REVOwner} from "./REVOwner.sol";
 import {REVAutoIssuance} from "./structs/REVAutoIssuance.sol";
 import {REVConfig} from "./structs/REVConfig.sol";
@@ -41,8 +43,15 @@ import {REVDeploy721TiersHookConfig} from "./structs/REVDeploy721TiersHookConfig
 import {REVStageConfig} from "./structs/REVStageConfig.sol";
 import {REVSuckerDeploymentConfig} from "./structs/REVSuckerDeploymentConfig.sol";
 
-/// @notice `REVDeployer` deploys, manages, and operates Revnets.
-/// @dev Revnets are unowned Juicebox projects which operate autonomously after deployment.
+/// @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.
+/// @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 {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -110,7 +119,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @notice The loan contract used by all revnets.
     /// @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.
-    address public immutable override LOANS;
+    IREVLoans public immutable override LOANS;
 
     /// @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`.
@@ -178,7 +187,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         IJB721TiersHookDeployer hookDeployer,
         CTPublisher publisher,
         IJBBuybackHookRegistry buybackHook,
-        address loans,
+        IREVLoans loans,
         address trustedForwarder,
         address owner
     )
@@ -193,20 +202,14 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         HOOK_DEPLOYER = hookDeployer;
         PUBLISHER = publisher;
         BUYBACK_HOOK = buybackHook;
-        // slither-disable-next-line missing-zero-check
         LOANS = loans;
         // slither-disable-next-line missing-zero-check
         OWNER = owner;
 
-        // Give the sucker registry permission to map tokens for all revnets.
-        _setPermission({
-            operator: address(SUCKER_REGISTRY), revnetId: 0, permissionId: JBPermissionIds.MAP_SUCKER_TOKEN
-        });
-
         // Give the loan contract permission to use the surplus allowance of all revnets.
         // Uses wildcard revnetId=0 intentionally — the loan contract is a singleton shared by all revnets,
         // and each revnet's surplus allowance limits already constrain how much can be drawn.
-        _setPermission({operator: LOANS, revnetId: 0, permissionId: JBPermissionIds.USE_ALLOWANCE});
+        _setPermission({operator: address(LOANS), revnetId: 0, permissionId: JBPermissionIds.USE_ALLOWANCE});
 
         // Give the buyback hook (registry) permission to configure pools on all revnets.
         _setPermission({operator: address(BUYBACK_HOOK), revnetId: 0, permissionId: JBPermissionIds.SET_BUYBACK_POOL});
@@ -356,12 +359,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         });
     }
 
-    /// @notice Returns the next project ID.
-    /// @return nextProjectId The next project ID.
-    function _nextProjectId() internal view returns (uint256) {
-        return PROJECTS.count() + 1;
-    }
-
     /// @notice Returns the permissions that the split operator should be granted for a revnet.
     /// @param revnetId The ID of the revnet to get split operator permissions for.
     /// @return allOperatorPermissions The permissions that the split operator should be granted for the revnet,
@@ -375,22 +372,21 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         uint256[] memory customSplitOperatorPermissionIndexes = _extraOperatorPermissions[revnetId];
 
         // Make the array that merges the default and custom operator permissions.
-        allOperatorPermissions = new uint256[](11 + customSplitOperatorPermissionIndexes.length);
+        allOperatorPermissions = new uint256[](10 + customSplitOperatorPermissionIndexes.length);
         allOperatorPermissions[0] = JBPermissionIds.SET_SPLIT_GROUPS;
         allOperatorPermissions[1] = JBPermissionIds.SET_BUYBACK_POOL;
         allOperatorPermissions[2] = JBPermissionIds.SET_BUYBACK_TWAP;
         allOperatorPermissions[3] = JBPermissionIds.SET_PROJECT_URI;
-        allOperatorPermissions[4] = JBPermissionIds.ADD_PRICE_FEED;
-        allOperatorPermissions[5] = JBPermissionIds.SUCKER_SAFETY;
-        allOperatorPermissions[6] = JBPermissionIds.SET_BUYBACK_HOOK;
-        allOperatorPermissions[7] = JBPermissionIds.SET_ROUTER_TERMINAL;
-        allOperatorPermissions[8] = JBPermissionIds.SET_TOKEN_METADATA;
-        allOperatorPermissions[9] = JBPermissionIds.SIGN_FOR_ERC20;
-        allOperatorPermissions[10] = JBPermissionIds.HIDE_TOKENS;
+        allOperatorPermissions[4] = JBPermissionIds.SUCKER_SAFETY;
+        allOperatorPermissions[5] = JBPermissionIds.SET_BUYBACK_HOOK;
+        allOperatorPermissions[6] = JBPermissionIds.SET_ROUTER_TERMINAL;
+        allOperatorPermissions[7] = JBPermissionIds.SET_TOKEN_METADATA;
+        allOperatorPermissions[8] = JBPermissionIds.SIGN_FOR_ERC20;
+        allOperatorPermissions[9] = JBPermissionIds.HIDE_TOKENS;
 
         // Copy the custom permissions into the array.
         for (uint256 i; i < customSplitOperatorPermissionIndexes.length;) {
-            allOperatorPermissions[11 + i] = customSplitOperatorPermissionIndexes[i];
+            allOperatorPermissions[10 + i] = customSplitOperatorPermissionIndexes[i];
             unchecked {
                 ++i;
             }
@@ -510,6 +506,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     /// @param allowedPosts Restrictions on which croptop posts are allowed 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 that was deployed for the revnet.
+    // The deployment flow makes external setup calls, but any observed state is revnet-scoped and reverts atomically.
+    // slither-disable-next-line reentrancy-benign
     function deployFor(
         uint256 revnetId,
         REVConfig calldata configuration,
@@ -525,9 +523,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // Keep a reference to the revnet ID which was passed in.
         bool shouldDeployNewRevnet = revnetId == 0;
 
-        // If the caller is deploying a new revnet, calculate its ID
-        // (which will be 1 greater than the current count).
-        if (shouldDeployNewRevnet) revnetId = _nextProjectId();
+        // If the caller is deploying a new revnet, reserve its project ID before deriving hook/sucker config.
+        if (shouldDeployNewRevnet) revnetId = PROJECTS.createFor(address(this));
 
         // Deploy the revnet with the specified tiered ERC-721 hook and croptop posting criteria.
         hook = _deploy721RevnetFor({
@@ -544,6 +541,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     }
 
     /// @inheritdoc IREVDeployer
+    // The deployment flow makes external setup calls, but any observed state is revnet-scoped and reverts atomically.
+    // slither-disable-next-line reentrancy-benign
     function deployFor(
         uint256 revnetId,
         REVConfig calldata configuration,
@@ -555,7 +554,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         returns (uint256, IJB721TiersHook hook)
     {
         bool shouldDeployNewRevnet = revnetId == 0;
-        if (shouldDeployNewRevnet) revnetId = _nextProjectId();
+        if (shouldDeployNewRevnet) revnetId = PROJECTS.createFor(address(this));
 
         // Deploy the revnet (project, rulesets, ERC-20, suckers, etc.).
         bytes32 encodedConfigurationHash = _deployRevnetFor({
@@ -583,6 +582,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         REVOwner(OWNER).setTiered721HookOf({revnetId: revnetId, hook: hook});
 
         // Grant the split operator all 721 permissions (no prevent* flags for default config).
+        // These permission IDs are only consumed by `_setSplitOperatorOf` below, after revnet setup has either
+        // completed or reverted atomically.
         _extraOperatorPermissions[revnetId].push(JBPermissionIds.ADJUST_721_TIERS);
         _extraOperatorPermissions[revnetId].push(JBPermissionIds.SET_721_METADATA);
         _extraOperatorPermissions[revnetId].push(JBPermissionIds.MINT_721);
@@ -656,6 +657,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     //*********************************************************************//
 
     /// @notice Deploy a revnet which sells tiered ERC-721s and (optionally) allows croptop posts to its ERC-721 tiers.
+    // The helper performs external hook/post setup after core revnet setup; any failure reverts the whole deployment.
+    // slither-disable-next-line reentrancy-benign
     function _deploy721RevnetFor(
         uint256 revnetId,
         bool shouldDeployNewRevnet,
@@ -706,6 +709,9 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // Store the tiered ERC-721 hook in the owner contract.
         REVOwner(OWNER).setTiered721HookOf({revnetId: revnetId, hook: hook});
 
+        // These permission IDs are only consumed by `_setSplitOperatorOf` below, after revnet setup has either
+        // completed or reverted atomically.
+
         // Give the split operator permission to add and remove tiers unless prevented.
         if (!tiered721HookConfiguration.preventSplitOperatorAdjustingTiers) {
             _extraOperatorPermissions[revnetId].push(JBPermissionIds.ADJUST_721_TIERS);
@@ -773,8 +779,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     ///   uninitialized.
     /// - The project's JBProjects NFT is permanently transferred to this contract. This is irreversible.
     /// @param revnetId The ID of the Juicebox project to initialize as a revnet. Send 0 to deploy a new revnet.
-    /// @param shouldDeployNewRevnet Whether to deploy a new revnet or convert an existing Juicebox project into a
-    /// revnet.
+    /// @param shouldDeployNewRevnet Whether the revnet ID was reserved by this deployment call, or the caller is
+    /// converting an existing Juicebox project into a revnet.
     /// @param configuration Core revnet configuration. See `REVConfig`.
     /// @param terminalConfigurations The terminals to set up for the revnet. Used for payments and cash outs.
     /// @param suckerDeploymentConfiguration The suckers to set up for the revnet. Suckers facilitate cross-chain
@@ -795,43 +801,37 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         (rulesetConfigurations, encodedConfigurationHash) = _makeRulesetConfigurations({
             revnetId: revnetId, configuration: configuration, terminalConfigurations: terminalConfigurations
         });
-        if (shouldDeployNewRevnet) {
-            // If we're deploying a new revnet, launch a Juicebox project for it.
-            // Sanity check that we deployed the `revnetId` that we expected to deploy.
-            // slither-disable-next-line incorrect-equality,reentrancy-benign,reentrancy-events
-            assert(
-                CONTROLLER.launchProjectFor({
-                    owner: address(this),
-                    projectUri: configuration.description.uri,
-                    rulesetConfigurations: rulesetConfigurations,
-                    terminalConfigurations: terminalConfigurations,
-                    memo: ""
-                }) == revnetId
-            );
-        } else {
+
+        address owner;
+        if (!shouldDeployNewRevnet) {
             // Keep a reference to the Juicebox project's owner.
-            address owner = PROJECTS.ownerOf(revnetId);
+            owner = PROJECTS.ownerOf(revnetId);
 
             // Make sure the caller is the owner of the Juicebox project.
             if (_msgSender() != owner) revert REVDeployer_Unauthorized(revnetId, _msgSender());
+        }
 
-            // Initialize the existing Juicebox project as a revnet by
-            // transferring the `JBProjects` NFT to this deployer. This is irreversible.
-            IERC721(PROJECTS).safeTransferFrom({from: owner, to: address(this), tokenId: revnetId});
-
-            // Launch the revnet rulesets for the pre-existing project.
-            // slither-disable-next-line unused-return
-            CONTROLLER.launchRulesetsFor({
-                projectId: revnetId,
-                rulesetConfigurations: rulesetConfigurations,
-                terminalConfigurations: terminalConfigurations,
-                memo: ""
-            });
+        // Store the hash before setup callbacks so reentrant readers cannot observe a zero configuration hash. Any
+        // subsequent revert rolls this write back.
+        hashedEncodedConfigurationOf[revnetId] = encodedConfigurationHash;
 
-            // Set the revnet's URI.
-            CONTROLLER.setUriOf({projectId: revnetId, uri: configuration.description.uri});
+        if (!shouldDeployNewRevnet) {
+            // Initialize the existing Juicebox project as a revnet by transferring the `JBProjects` NFT to this
+            // deployer. This is irreversible.
+            // slither-disable-next-line reentrancy-benign
+            IERC721(PROJECTS).safeTransferFrom({from: owner, to: address(this), tokenId: revnetId});
         }
 
+        // Launch the revnet rulesets for the reserved or pre-existing blank project.
+        // slither-disable-next-line unused-return
+        CONTROLLER.launchRulesetsFor({
+            projectId: revnetId,
+            projectUri: configuration.description.uri,
+            rulesetConfigurations: rulesetConfigurations,
+            terminalConfigurations: terminalConfigurations,
+            memo: ""
+        });
+
         // Store the cash out delay of the revnet if its stages are already in progress.
         // This prevents cash out liquidity/arbitrage issues for existing revnets which
         // are deploying to a new chain.
@@ -875,9 +875,6 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             });
         }
 
-        // Store the hashed encoded configuration.
-        hashedEncodedConfigurationOf[revnetId] = encodedConfigurationHash;
-
         emit DeployRevnet({
             revnetId: revnetId,
             configuration: configuration,
@@ -908,7 +905,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             caller: _msgSender()
         });
 
-        // Deploy the suckers.
+        // Include the caller so two revnets with identical configuration and user salt cannot collide. Same-address
+        // cross-chain deployment still works when the same operator calls this helper on each chain.
         // slither-disable-next-line unused-return
         suckers = SUCKER_REGISTRY.deploySuckersFor({
             projectId: revnetId,
@@ -1014,7 +1012,10 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
                 fundAccessLimitGroups: fundAccessLimitGroups
             });
 
-            // Add the stage's properties to the byte-encoded configuration.
+            // Add the stage's immutable economics to the byte-encoded configuration. `extraMetadata` is Juicebox
+            // ruleset metadata forwarded to the revnet data hook, so it remains part of the revnet identity.
+            // Reserved-token split recipients and individual weights are intentionally excluded below: the split
+            // limit (`splitPercent`) is the economic commitment, while split routing can change over time.
             encodedConfiguration = abi.encode(
                 encodedConfiguration,
                 // Use the effective start time (normalized from 0 to block.timestamp for the first stage).
@@ -1024,7 +1025,8 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
                 stageConfiguration.initialIssuance,
                 stageConfiguration.issuanceCutFrequency,
                 stageConfiguration.issuanceCutPercent,
-                stageConfiguration.cashOutTaxRate
+                stageConfiguration.cashOutTaxRate,
+                stageConfiguration.extraMetadata
             );
 
             // Add each auto-mint to the byte-encoded representation.

package/src/REVHiddenTokens.sol

@@ -13,8 +13,8 @@ import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
 
 /// @notice Allows authorized operators to hide (burn) revnet tokens on behalf of holders, excluding them from
-/// governance weight. Hidden tokens are burned from circulating supply, so they also stop contributing to
-/// cash-out and borrow valuations until revealed again.
+/// governance weight. Hidden tokens are burned from live circulating supply, but `REVOwner` and `REVLoans` add the
+/// hidden supply back into their economic denominators while those tokens remain revealable.
 /// Hidden tokens can be revealed (re-minted) at any time.
 contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
     //*********************************************************************//

package/src/REVLoans.sol

@@ -35,18 +35,15 @@ import {IREVOwner} from "./interfaces/IREVOwner.sol";
 import {REVLoan} from "./structs/REVLoan.sol";
 import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
-/// @notice A contract for borrowing from revnets.
-/// @dev Tokens used as collateral are burned, and reminted when the loan is paid off. This keeps the revnet's token
-/// structure orderly.
-/// @dev The borrowable amount is the same as the cash out amount.
-/// @dev An upfront fee is taken when a loan is created. 2.5% is charged by the underlying protocol, 2.5% is charged
-/// by the
-/// revnet issuing the loan, and a variable amount charged by the revnet that receives the fees. This variable amount is
-/// chosen by the borrower, the more paid upfront, the longer the prepaid duration. The loan can be repaid anytime
-/// within the prepaid duration without additional fees.
-/// After the prepaid duration, the loan will increasingly cost more to pay off. After 10 years, the loan collateral
-/// cannot be
-/// recouped.
+/// @notice Allows revnet token holders to borrow against their tokens instead of cashing out. The borrowable amount
+/// equals what a cash-out would return. Collateral tokens are burned on borrow and re-minted on repayment, keeping the
+/// 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
+/// 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.
 contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans {
     // A library that parses the packed ruleset metadata into a friendlier format.
@@ -359,10 +356,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Get the total amount of tokens in circulation.
         uint256 totalSupply = CONTROLLER.totalTokenSupplyWithReservedTokensOf(revnetId);
 
-        // Get a refeerence to the collateral being used to secure loans.
+        // Get a reference to the collateral being used to secure loans.
         uint256 totalCollateral = totalCollateralOf[revnetId];
 
-        // The local supply includes both circulating tokens and tokens locked as loan collateral.
+        // Hidden tokens are intentionally excluded from borrowing math. Operators can hide tokens as a security
+        // handle without changing the fair loan market for visible token holders.
         uint256 localSupply = totalSupply + totalCollateral;
 
         // The local surplus includes both the treasury surplus and the outstanding borrowed amounts.
@@ -469,10 +467,13 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
             revert REVLoans_LoanExpired(timeSinceLoanCreated, LOAN_LIQUIDATION_DURATION);
         }
 
-        // Get a reference to the amount prepaid for the full loan.
-        uint256 prepaid = JBFees.feeAmountFrom({amountBeforeFee: loan.amount, feePercent: loan.prepaidFeePercent});
+        // Get a reference to the amount prepaid for the full loan. This is an app-level loan fee, so keep it
+        // floor-rounded instead of applying the protocol fee helper's dust minimum.
+        uint256 prepaid = JBFees.feeAmountFromFloor({amountBeforeFee: loan.amount, feePercent: loan.prepaidFeePercent});
 
-        uint256 fullSourceFeeAmount = JBFees.feeAmountFrom({
+        // This source fee ramps with elapsed time. Use the floor-rounded fee helper so a one-second elapsed window
+        // with zero fee percent stays free instead of inheriting the protocol fee helper's anti-dust minimum.
+        uint256 fullSourceFeeAmount = JBFees.feeAmountFromFloor({
             amountBeforeFee: loan.amount - prepaid,
             feePercent: mulDiv({
                 x: timeSinceLoanCreated - loan.prepaidDuration,
@@ -1017,10 +1018,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Keep a reference to the fee terminal.
         IJBTerminal feeTerminal = DIRECTORY.primaryTerminalOf({projectId: REV_ID, token: loan.source.token});
 
-        // Get the amount of additional fee to take for REV.
+        // Get the amount of additional fee to take for REV. This is an app-level loan fee, not the terminal's
+        // protocol fee, so keep it floor-rounded instead of applying the protocol fee helper's dust minimum.
         uint256 revFeeAmount = address(feeTerminal) == address(0)
             ? 0
-            : JBFees.feeAmountFrom({amountBeforeFee: addedBorrowAmount, feePercent: REV_PREPAID_FEE_PERCENT});
+            : JBFees.feeAmountFromFloor({amountBeforeFee: addedBorrowAmount, feePercent: REV_PREPAID_FEE_PERCENT});
 
         // Try to pay the REV fee. If it fails, revFeeAmount is zeroed so the borrower receives it instead.
         if (revFeeAmount > 0) {
@@ -1238,9 +1240,11 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // Make sure the minimum borrow amount is met.
         if (borrowAmount < minBorrowAmount) revert REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount);
 
-        // Get the amount of additional fee to take for the revnet issuing the loan.
-        // Fee rounding may leave a few wei of dust — economically insignificant relative to gas costs.
-        uint256 sourceFeeAmount = JBFees.feeAmountFrom({amountBeforeFee: borrowAmount, feePercent: prepaidFeePercent});
+        // Get the amount of additional fee to take for the revnet issuing the loan. This is an app-level loan fee,
+        // not the terminal's protocol fee, so keep it floor-rounded instead of applying the protocol fee helper's dust
+        // minimum.
+        uint256 sourceFeeAmount =
+            JBFees.feeAmountFromFloor({amountBeforeFee: borrowAmount, feePercent: prepaidFeePercent});
 
         // Borrow the amount.
         _adjust({