@rev-net/core-v6 0.0.33 → 0.0.35

package/USER_JOURNEYS.md

@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-This repo packages autonomous Revnets: staged Juicebox projects whose runtime behavior is intentionally constrained
-after launch. It owns deploy-time stage encoding, runtime enforcement, hidden-token mechanics, and lending against
-Revnet token exposure. It does not turn the project back into an ordinary owner-governed treasury after deployment.
+This repo packages autonomous Revnets: staged Juicebox projects whose runtime behavior is intentionally constrained after launch. It owns deploy-time stage encoding, runtime enforcement, hidden-token mechanics, and lending against revnet token exposure.
 
 ## Primary Actors
 
@@ -28,135 +26,136 @@ Revnet token exposure. It does not turn the project back into an ordinary owner-
 **Intent:** deploy a Revnet whose economic envelope is encoded up front and stays bounded afterward.
 
 **Preconditions**
+
 - the team knows the stage schedule, issuance behavior, operator envelope, and optional integrations
 - the team accepts that many choices become expensive or impossible to change later
 
 **Main Flow**
+
 1. Use `REVDeployer` with the staged config, split operators, and optional integrations.
 2. The deployer launches the underlying project and preserves the intended ownership model.
 3. Stage and auxiliary behavior are committed at launch instead of left to ordinary owner discretion.
 4. The Revnet can now accept payments and progress through stages under the encoded rules.
 
 **Failure Modes**
+
 - teams assume deploy-time parameters can be revisited casually
 - optional integrations are enabled without auditing their effect on the resulting network
 
 **Postconditions**
+
 - the Revnet launches with its long-lived stage envelope encoded up front
 
-## Journey 2: Participate In The Revnet Across Stage Transitions
+## Journey 2: Participate Across Stage Transitions
 
 **Actor:** participant.
 
 **Intent:** buy, hold, and exit Revnet exposure across stage changes.
 
 **Preconditions**
+
 - the Revnet is already live
 - the participant understands active stage parameters can change behavior over time
 
 **Main Flow**
+
 1. Pay through the configured terminal or router.
 2. Let `REVOwner` enforce runtime behavior such as pay handling, delayed exits, and stage-sensitive constraints.
-3. As stages advance, later pays and exits follow the new active parameters while identity stays constant.
+3. As stages advance, later pays and exits follow the new active parameters while project identity stays constant.
 
 **Failure Modes**
+
 - stage parameters are misread as mutable when they are fixed
 - delayed cash-out behavior is misunderstood
-- optional integrations materially change the participant experience in ways the caller ignored
+- optional integrations materially change the participant experience
 
 **Postconditions**
-- the participant's buys and exits now follow the active stage's constraints
 
-## Journey 3: Claim Stage-Based Auto-Issuance When It Becomes Available
+- the participant's buys and exits follow the active stage's constraints
+
+## Journey 3: Claim Stage-Based Auto-Issuance
 
 **Actor:** auto-issuance beneficiary.
 
 **Intent:** claim stage-specific issuance only when it is actually live.
 
 **Preconditions**
+
 - the Revnet was deployed with auto-issuance allocations
 - the target stage has started
 
 **Main Flow**
+
 1. Check `amountToAutoIssue(...)`.
 2. Call `autoIssueFor(...)` once the stage is active.
 3. The stored allocation is consumed and cannot be claimed twice.
 
 **Failure Modes**
+
 - callers try to claim before the stage is active
 - reviewers assume auto-issuance is a generic mint path rather than a bounded stage allocation
 
 **Postconditions**
-- the stage allocation is either claimed once or remains reserved until it becomes valid
 
-## Journey 3a: Hide Tokens To Increase Cash-Out Value For Remaining Holders
+- the stage allocation is either claimed once or remains reserved until valid
+
+## Journey 4: Hide Tokens To Change Visible Supply
 
 **Actor:** holder or authorized operator.
 
 **Intent:** remove tokens from visible supply temporarily and later restore them.
 
 **Preconditions**
-- the holder granted the required permissions
+
+- the holder granted `BURN_TOKENS` to `REVHiddenTokens`
+- either the holder has been allowlisted for hidden-token actions, or the caller is the project owner / an operator with `HIDE_TOKENS`
 - the holder accepts the supply and collateral implications of hiding tokens
 
 **Main Flow**
+
 1. Grant `BURN_TOKENS` to `REVHiddenTokens`.
-2. Call `hideTokensOf(...)` to burn tokens and track the hidden balance.
-3. The lower visible supply changes per-token cash-out value.
-4. Later call `revealTokensOf(...)` to re-mint hidden tokens.
+2. An operator calls `setTokenHidingAllowedFor(...)` to allow the holder to hide their own tokens.
+3. The holder, project owner, or a `HIDE_TOKENS` operator calls `hideTokensOf(...)` to burn tokens and track the hidden balance.
+4. The lower visible supply changes per-token cash-out value.
+5. Later, the holder calls `revealTokensOf(...)` to remint hidden tokens back to themselves.
 
 **Failure Modes**
+
 - more tokens are revealed than were hidden
-- holders forget revealed tokens increase visible supply again
+- holders attempt to hide tokens without being allowlisted
+- non-holders attempt to reveal hidden tokens
 - hidden tokens are assumed to remain usable as loan collateral
 
 **Postconditions**
+
 - visible supply is reduced or restored according to the holder's hidden-token state
 
-## Journey 4: Borrow Against Revnet Tokens Instead Of Selling Them
+## Journey 5: Borrow Against Revnet Tokens Instead Of Selling Them
 
 **Actor:** holder or delegated loan operator.
 
 **Intent:** borrow against Revnet exposure instead of selling it.
 
 **Preconditions**
+
 - the holder has eligible Revnet token exposure
 - the holder trusts any delegated operator with `OPEN_LOAN`
 
 **Main Flow**
+
 1. Interact with `REVLoans` using eligible token exposure as collateral.
-2. The system burns the collateralized token exposure and mints a loan NFT.
+2. The system burns the collateralized exposure and mints a loan NFT.
 3. Borrowed value is issued under live Revnet economics.
 4. The borrower can later repay, reallocate, transfer, or face liquidation.
 
 **Failure Modes**
+
 - delegated operators redirect value in ways the holder did not intend
 - reviewers model the loan system as escrowed collateral when it is burned-collateral lending
 
 **Postconditions**
-- collateralized exposure is transformed into a live loan position under Revnet economics
-
-## Journey 5: Repay, Transfer, Or Liquidate A Loan Position
-
-**Actor:** borrower, loan owner, or liquidator.
 
-**Intent:** change or settle an existing loan position.
-
-**Preconditions**
-- a loan already exists
-- the actor has the rights or economic incentives required for the chosen path
-
-**Main Flow**
-1. Repay to burn debt and restore the collateralized exposure.
-2. Transfer the loan NFT if ownership of the debt position should move.
-3. Liquidate if the encoded conditions permit it.
-
-**Failure Modes**
-- cross-ruleset behavior is misread
-- zero-value or sourced-versus-unsourced paths are handled incorrectly by integrations
-
-**Postconditions**
-- the loan position is repaid, transferred, or liquidated according to the chosen path
+- collateralized exposure becomes a live loan position under Revnet economics
 
 ## Journey 6: Operate Inside The Bounded Post-Launch Control Envelope
 
@@ -165,50 +164,32 @@ Revnet token exposure. It does not turn the project back into an ordinary owner-
 **Intent:** use the sanctioned post-launch controls without violating the autonomous model.
 
 **Preconditions**
+
 - the Revnet is live
 - the operator knows exactly which controls the deployment left available
 
 **Main Flow**
+
 1. Review what `REVDeployer` allowed.
 2. Use only those sanctioned surfaces.
 3. Audit cross-package behavior whenever optional integrations are enabled.
 
 **Failure Modes**
+
 - operators behave as though the Revnet were a normal owner-governed project
 - reviewers inspect controls in isolation and miss integrated runtime behavior
 
 **Postconditions**
-- post-launch control remains inside the bounded envelope the deployment left available
 
-## Journey 7: Receive Cross-Chain Payments With Correct Hook Routing
-
-**Actor:** remote participant or integrator using suckers.
-
-**Intent:** preserve the real beneficiary during cross-chain payments into a Revnet.
-
-**Preconditions**
-- the Revnet is configured with suckers and optional hooks that depend on the beneficiary
-- relay-beneficiary metadata is provided correctly
-
-**Main Flow**
-1. The sucker calls `terminal.pay()` with relay-beneficiary metadata.
-2. `REVOwner.beforePayRecordedWith()` resolves the real beneficiary when the payer is a registered sucker.
-3. Downstream hooks observe the remote user rather than the sucker contract.
-
-**Failure Modes**
-- relay metadata is absent or malformed
-- downstream hooks accidentally attribute minting or routing to the sucker instead of the user
-
-**Postconditions**
-- cross-chain payments preserve the intended remote beneficiary through the Revnet hook stack
+- post-launch control remains inside the bounded envelope left by deployment
 
 ## Trust Boundaries
 
-- `REVDeployer` is trusted for the launch-time envelope the Revnet will live inside
-- `REVOwner` is economically binding runtime logic, not advisory middleware
-- optional integrations such as 721 hooks, buybacks, router terminals, and suckers materially alter the resulting network
+- this repo is trusted for revnet-specific economics and runtime policy
+- treasury accounting still comes from core
+- optional integrations materially change revnet behavior and must be reviewed together with the local code
 
 ## Hand-Offs
 
-- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the underlying project, terminal, and ruleset mechanics that Revnets package and constrain.
-- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md), [nana-buyback-hook-v6](../nana-buyback-hook-v6/USER_JOURNEYS.md), and [nana-suckers-v6](../nana-suckers-v6/USER_JOURNEYS.md) when a Revnet deployment enables those optional features.
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for underlying terminal and project accounting.
+- Use [nana-buyback-hook-v6](../nana-buyback-hook-v6/USER_JOURNEYS.md), [nana-suckers-v6](../nana-suckers-v6/USER_JOURNEYS.md), and [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) when those integrations are enabled.

package/package.json

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

package/references/runtime.md

@@ -102,5 +102,6 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 | Function | Permissions | What it does |
 |----------|------------|-------------|
-| `REVHiddenTokens.hideTokensOf(holder, revnetId, tokenCount)` | Holder or delegated permission | Burns visible tokens, increases hidden balance, and lowers visible supply. |
-| `REVHiddenTokens.revealTokensOf(holder, revnetId, tokenCount, beneficiary)` | Holder or delegated permission | Re-mints previously hidden tokens to a beneficiary and reduces hidden balance. |
+| `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.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/src/REVDeployer.sol

@@ -375,7 +375,7 @@ 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[](10 + customSplitOperatorPermissionIndexes.length);
+        allOperatorPermissions = new uint256[](11 + customSplitOperatorPermissionIndexes.length);
         allOperatorPermissions[0] = JBPermissionIds.SET_SPLIT_GROUPS;
         allOperatorPermissions[1] = JBPermissionIds.SET_BUYBACK_POOL;
         allOperatorPermissions[2] = JBPermissionIds.SET_BUYBACK_TWAP;
@@ -386,10 +386,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         allOperatorPermissions[7] = JBPermissionIds.SET_ROUTER_TERMINAL;
         allOperatorPermissions[8] = JBPermissionIds.SET_TOKEN_METADATA;
         allOperatorPermissions[9] = JBPermissionIds.SIGN_FOR_ERC20;
+        allOperatorPermissions[10] = JBPermissionIds.HIDE_TOKENS;
 
         // Copy the custom permissions into the array.
         for (uint256 i; i < customSplitOperatorPermissionIndexes.length;) {
-            allOperatorPermissions[10 + i] = customSplitOperatorPermissionIndexes[i];
+            allOperatorPermissions[11 + i] = customSplitOperatorPermissionIndexes[i];
             unchecked {
                 ++i;
             }
@@ -955,6 +956,16 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
             configuration.description.salt
         );
 
+        // Include terminal addresses in the hash so cross-chain expansions must use the same terminals.
+        // Terminal addresses are deterministic across chains. Accounting contexts are excluded because
+        // token addresses (e.g. USDC) legitimately differ per chain.
+        for (uint256 i; i < terminalConfigurations.length;) {
+            encodedConfiguration = abi.encode(encodedConfiguration, terminalConfigurations[i].terminal);
+            unchecked {
+                ++i;
+            }
+        }
+
         // Initialize fund access limit groups for the loan contract.
         JBFundAccessLimitGroup[] memory fundAccessLimitGroups =
             _makeLoanFundAccessLimits({terminalConfigurations: terminalConfigurations});

package/src/REVHiddenTokens.sol

@@ -4,6 +4,7 @@ pragma solidity 0.8.28;
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBPermissioned} from "@bananapus/core-v6/src/interfaces/IJBPermissioned.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
 import {JBPermissioned} from "@bananapus/core-v6/src/abstract/JBPermissioned.sol";
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
@@ -11,14 +12,17 @@ import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 
 import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
 
-/// @notice Allows revnet token holders to temporarily hide (burn) tokens, excluding them from totalSupply and
-/// increasing cash-out value for remaining holders. Hidden tokens can be revealed (re-minted) at any time.
+/// @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.
+/// Hidden tokens can be revealed (re-minted) at any time.
 contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
     error REVHiddenTokens_InsufficientHiddenBalance(uint256 hiddenBalance, uint256 requested);
+    error REVHiddenTokens_Unauthorized(uint256 revnetId, address caller);
 
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
@@ -27,6 +31,9 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
     /// @notice The controller that manages revnets using this contract.
     IJBController public immutable override CONTROLLER;
 
+    /// @notice The projects contract used to resolve revnet owners.
+    IJBProjects public immutable PROJECTS;
+
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
@@ -40,6 +47,11 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
     /// @custom:param revnetId The ID of the revnet.
     mapping(uint256 revnetId => uint256 count) public override totalHiddenOf;
 
+    /// @notice Whether a holder is allowed to hide their own tokens.
+    /// @custom:param holder The holder whose tokens are being managed.
+    /// @custom:param revnetId The ID of the revnet.
+    mapping(address holder => mapping(uint256 revnetId => bool isAllowed)) public override tokenHidingIsAllowedFor;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -54,20 +66,27 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
         JBPermissioned(IJBPermissioned(address(controller)).PERMISSIONS())
     {
         CONTROLLER = controller;
+        PROJECTS = controller.PROJECTS();
     }
 
-    //*********************************************************************//
-    // --------------------- external transactions ----------------------- //
-    //*********************************************************************//
-
     /// @notice Hide tokens by burning them and tracking them for later reveal.
+    /// @dev The caller must be the holder. Hiding is allowed for holders on the operator-managed allowlist,
+    /// and also for holders who are themselves the project owner or an operator with `HIDE_TOKENS`.
     /// @dev The holder must have granted BURN_TOKENS permission to this contract.
     /// @param revnetId The ID of the revnet whose tokens to hide.
     /// @param tokenCount The number of tokens to hide.
     /// @param holder The address whose tokens to hide.
     function hideTokensOf(uint256 revnetId, uint256 tokenCount, address holder) external override {
-        // Only the holder or a permissioned operator can hide tokens.
-        _requirePermissionFrom({account: holder, projectId: revnetId, permissionId: JBPermissionIds.HIDE_TOKENS});
+        address caller = _msgSender();
+        if (caller != holder) revert REVHiddenTokens_Unauthorized(revnetId, caller);
+
+        bool isAllowlistedHolder = tokenHidingIsAllowedFor[holder][revnetId];
+        bool isPermissionedOperator =
+            _hasPermissionFrom(caller, PROJECTS.ownerOf(revnetId), revnetId, JBPermissionIds.HIDE_TOKENS);
+
+        if (!isAllowlistedHolder && !isPermissionedOperator) {
+            revert REVHiddenTokens_Unauthorized(revnetId, caller);
+        }
 
         // Increment the holder's hidden balance.
         hiddenBalanceOf[holder][revnetId] += tokenCount;
@@ -83,24 +102,14 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
     }
 
     /// @notice Reveal previously hidden tokens by re-minting them.
-    /// @dev A delegated operator (with REVEAL_TOKENS permission) can set `beneficiary` to any address, directing
-    /// revealed tokens away from the holder. Grant this permission only to trusted operators.
+    /// @dev Any holder can reveal their own hidden tokens without special permissions.
+    /// Revealed tokens always return to the holder.
     /// @param revnetId The ID of the revnet whose tokens to reveal.
     /// @param tokenCount The number of tokens to reveal.
-    /// @param beneficiary The address that will receive the revealed tokens.
     /// @param holder The address whose hidden balance to decrement.
-    function revealTokensOf(
-        uint256 revnetId,
-        uint256 tokenCount,
-        address beneficiary,
-        address holder
-    )
-        external
-        override
-    {
-        // Only the holder or a permissioned operator can reveal tokens.
-        // Note: the operator controls `beneficiary`, so they can direct revealed tokens to any address.
-        _requirePermissionFrom({account: holder, projectId: revnetId, permissionId: JBPermissionIds.REVEAL_TOKENS});
+    function revealTokensOf(uint256 revnetId, uint256 tokenCount, address holder) external override {
+        address caller = _msgSender();
+        if (caller != holder) revert REVHiddenTokens_Unauthorized(revnetId, caller);
 
         uint256 hidden = hiddenBalanceOf[holder][revnetId];
 
@@ -118,12 +127,25 @@ contract REVHiddenTokens is ERC2771Context, JBPermissioned, IREVHiddenTokens {
         // Mint the tokens to the beneficiary without applying the reserved percent.
         // slither-disable-next-line unused-return,reentrancy-events
         CONTROLLER.mintTokensOf({
-            projectId: revnetId, tokenCount: tokenCount, beneficiary: beneficiary, memo: "", useReservedPercent: false
+            projectId: revnetId, tokenCount: tokenCount, beneficiary: holder, memo: "", useReservedPercent: false
         });
 
-        emit RevealTokens({
-            revnetId: revnetId, tokenCount: tokenCount, beneficiary: beneficiary, holder: holder, caller: _msgSender()
+        emit RevealTokens({revnetId: revnetId, tokenCount: tokenCount, holder: holder, caller: _msgSender()});
+    }
+
+    /// @notice Allow or disallow a holder to hide their own tokens.
+    /// @dev The caller must have `HIDE_TOKENS` permission for the revnet.
+    /// @param revnetId The ID of the revnet.
+    /// @param holder The holder to update.
+    /// @param isAllowed Whether the holder should be allowed.
+    function setTokenHidingAllowedFor(uint256 revnetId, address holder, bool isAllowed) external override {
+        _requirePermissionFrom({
+            account: PROJECTS.ownerOf(revnetId), projectId: revnetId, permissionId: JBPermissionIds.HIDE_TOKENS
         });
+
+        tokenHidingIsAllowedFor[holder][revnetId] = isAllowed;
+
+        emit SetTokenHidingAllowed({revnetId: revnetId, holder: holder, isAllowed: isAllowed});
     }
 
     //*********************************************************************//

package/src/REVLoans.sol

@@ -374,8 +374,8 @@ contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans
         // collateral. This is by design: loan value tracks the current bonding curve parameters, just as cash-out
         // value does. Borrowers benefit from decreasing tax rates and are constrained by increasing ones.
         // Add cross-chain remote values for proportional reclaim.
-        uint256 omnichainSurplus =
-            localSurplus + SUCKER_REGISTRY.remoteSurplusOf({projectId: revnetId, decimals: 18, currency: currency});
+        uint256 omnichainSurplus = localSurplus
+            + SUCKER_REGISTRY.remoteSurplusOf({projectId: revnetId, decimals: decimals, currency: currency});
         uint256 omnichainSupply = localSupply + SUCKER_REGISTRY.remoteTotalSupplyOf(revnetId);
         uint256 reclaimable = JBCashOuts.cashOutFrom({
             surplus: omnichainSurplus,

package/src/REVOwner.sol

@@ -184,8 +184,13 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         // feeless (e.g. the router terminal routing value between projects), proxy to the buyback hook with our
         // totalSupply and effectiveSurplusValue.
         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
+            // for its swap-vs-passthrough routing decision.
+            JBBeforeCashOutRecordedContext memory routedContext = context;
+            routedContext.totalSupply = totalSupply;
+            routedContext.surplus.value = effectiveSurplusValue;
             // slither-disable-next-line unused-return
-            (cashOutTaxRate, cashOutCount,,, hookSpecifications) = BUYBACK_HOOK.beforeCashOutRecordedWith(context);
+            (cashOutTaxRate, cashOutCount,,, hookSpecifications) = BUYBACK_HOOK.beforeCashOutRecordedWith(routedContext);
             return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
         }
 
@@ -227,9 +232,12 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             feeAmount = context.surplus.value - postFeeReclaimedAmount;
         }
 
-        // Build a context for the buyback hook using only the non-fee token count.
+        // Build a context for the buyback hook using the non-fee token count and cross-chain-adjusted values
+        // so the buyback hook sees the global state for its swap-vs-passthrough routing decision.
         JBBeforeCashOutRecordedContext memory buybackHookContext = context;
         buybackHookContext.cashOutCount = nonFeeCashOutCount;
+        buybackHookContext.totalSupply = totalSupply;
+        buybackHookContext.surplus.value = effectiveSurplusValue;
 
         // Let the buyback hook adjust the cash out parameters and optionally return a hook specification.
         JBCashOutHookSpecification[] memory buybackHookSpecifications;

package/src/interfaces/IREVHiddenTokens.sol

@@ -5,6 +5,12 @@ import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol
 
 /// @notice Manages hiding (burning) and revealing (re-minting) revnet tokens to exclude them from totalSupply.
 interface IREVHiddenTokens {
+    /// @notice Emitted when a holder is allowed or disallowed to hide their own tokens.
+    /// @param revnetId The ID of the revnet.
+    /// @param holder The holder whose tokens are being allowed or disallowed.
+    /// @param isAllowed Whether the holder is allowed.
+    event SetTokenHidingAllowed(uint256 indexed revnetId, address indexed holder, bool isAllowed);
+
     /// @notice Emitted when tokens are hidden (burned and tracked for later reveal).
     /// @param revnetId The ID of the revnet whose tokens are hidden.
     /// @param tokenCount The number of tokens hidden.
@@ -15,12 +21,9 @@ interface IREVHiddenTokens {
     /// @notice Emitted when previously hidden tokens are revealed (re-minted).
     /// @param revnetId The ID of the revnet whose tokens are revealed.
     /// @param tokenCount The number of tokens revealed.
-    /// @param beneficiary The address receiving the revealed tokens.
     /// @param holder The address whose hidden balance is decremented.
     /// @param caller The address that revealed the tokens.
-    event RevealTokens(
-        uint256 indexed revnetId, uint256 tokenCount, address beneficiary, address holder, address caller
-    );
+    event RevealTokens(uint256 indexed revnetId, uint256 tokenCount, address holder, address caller);
 
     /// @notice The controller that manages revnets using this contract.
     /// @return The controller contract.
@@ -37,6 +40,12 @@ interface IREVHiddenTokens {
     /// @return The total hidden token count.
     function totalHiddenOf(uint256 revnetId) external view returns (uint256);
 
+    /// @notice Whether a holder is allowed to hide their own tokens.
+    /// @param holder The holder whose tokens are being managed.
+    /// @param revnetId The ID of the revnet.
+    /// @return Whether the holder is allowed.
+    function tokenHidingIsAllowedFor(address holder, uint256 revnetId) external view returns (bool);
+
     /// @notice Hide tokens by burning them and tracking them for later reveal.
     /// @dev The holder must have granted BURN_TOKENS permission to this contract.
     /// @param revnetId The ID of the revnet whose tokens to hide.
@@ -47,7 +56,13 @@ interface IREVHiddenTokens {
     /// @notice Reveal previously hidden tokens by re-minting them.
     /// @param revnetId The ID of the revnet whose tokens to reveal.
     /// @param tokenCount The number of tokens to reveal.
-    /// @param beneficiary The address that will receive the revealed tokens.
     /// @param holder The address whose hidden balance to decrement.
-    function revealTokensOf(uint256 revnetId, uint256 tokenCount, address beneficiary, address holder) external;
+    function revealTokensOf(uint256 revnetId, uint256 tokenCount, address holder) external;
+
+    /// @notice Allow or disallow a holder to hide their own tokens.
+    /// @dev The caller must have `HIDE_TOKENS` permission for the revnet.
+    /// @param revnetId The ID of the revnet.
+    /// @param holder The holder to update.
+    /// @param isAllowed Whether the holder should be allowed.
+    function setTokenHidingAllowedFor(uint256 revnetId, address holder, bool isAllowed) external;
 }