@rev-net/core-v6 0.0.32 → 0.0.34

package/USER_JOURNEYS.md

@@ -1,110 +1,195 @@
 # User Journeys
 
-## Who This Repo Serves
+## 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.
+
+## Primary Actors
 
 - teams launching autonomous Revnets with encoded stage transitions
 - participants buying, holding, and cashing out Revnet exposure over time
 - borrowers using Revnet tokens as collateral instead of selling them
 - operators working inside the narrow post-launch envelope the deployer allows
 
+## Key Surfaces
+
+- `REVDeployer`: launch-time packaging, stage config, and operator envelope
+- `REVOwner`: runtime pay and cash-out behavior for active Revnets
+- `REVLoans`: borrowing, repayment, transfer, reallocation, and liquidation
+- `REVHiddenTokens`: temporarily hide and later reveal token supply
+- `autoIssueFor(...)`, `hideTokensOf(...)`, `revealTokensOf(...)`, `borrowFrom(...)`: high-signal runtime entrypoints
+
 ## Journey 1: Launch A Revnet With Its Long-Lived Rules Encoded Up Front
 
-**Starting state:** you know the stage schedule, issuance behavior, optional integrations, and runtime controls the Revnet should allow.
+**Actor:** launch team.
+
+**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 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**
 
-**Success:** the Revnet launches as a Juicebox project whose deploy-time shape already encodes its economic envelope.
+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 project identity stays constant.
 
-**Flow**
-1. Use `REVDeployer` with the staged config, split operators, and optional integrations such as 721 hooks, buyback routing, router terminal support, or suckers.
-2. The deployer launches the underlying project and keeps the ownership model aligned with the Revnet runtime contracts.
-3. Stage config, issuance behavior, and auxiliary surfaces are committed as part of the launch instead of being left to human operators later.
-4. The network can now accept payments and transition across stages without ordinary project-owner governance.
+**Failure Modes**
 
-## Journey 2: Participate In The Revnet Across Stage Transitions
+- stage parameters are misread as mutable when they are fixed
+- delayed cash-out behavior is misunderstood
+- optional integrations materially change the participant experience
 
-**Starting state:** the Revnet is live and a participant wants to pay in, hold exposure, or cash out later.
+**Postconditions**
 
-**Success:** participation follows the current stage's rules without requiring the user to reason about every deploy-time parameter directly.
+- the participant's buys and exits follow the active stage's constraints
 
-**Flow**
-1. Users pay through the configured terminal or router surface.
-2. `REVOwner` enforces runtime behavior such as pay handling, cash-out rules, delayed exits, and other stage-sensitive constraints.
-3. As stages advance, later pays and cash outs follow the newly active parameters while the project identity stays constant.
+## Journey 3: Claim Stage-Based Auto-Issuance
 
-**Failure cases that matter:** assuming a stage parameter is mutable when it is fixed at launch, misreading delayed cash-out behavior, and forgetting that optional integrations materially change the participant experience.
+**Actor:** auto-issuance beneficiary.
 
-## Journey 3: Claim Stage-Based Auto-Issuance When It Becomes Available
+**Intent:** claim stage-specific issuance only when it is actually live.
 
-**Starting state:** the Revnet was deployed with auto-issuance allocations for one or more beneficiaries.
+**Preconditions**
 
-**Success:** the beneficiary claims the right amount for the right stage only after that stage is actually live.
+- the Revnet was deployed with auto-issuance allocations
+- the target stage has started
 
-**Flow**
-1. Check `amountToAutoIssue(...)` for the revnet, stage, and beneficiary.
-2. Call `autoIssueFor(...)` only once the target stage has started.
-3. The stored allocation is consumed so the same stage allocation cannot be claimed twice.
+**Main Flow**
 
-## Journey 3a: Hide Tokens To Increase Cash-Out Value For Remaining Holders
+1. Check `amountToAutoIssue(...)`.
+2. Call `autoIssueFor(...)` once the stage is active.
+3. The stored allocation is consumed and cannot be claimed twice.
 
-**Starting state:** a holder wants to temporarily exclude some tokens from totalSupply without permanently giving them up.
+**Failure Modes**
 
-**Success:** the holder burns tokens via REVHiddenTokens, reducing totalSupply and increasing the per-token cash-out value for everyone else. The holder can reveal (re-mint) their hidden tokens at any time.
+- callers try to claim before the stage is active
+- reviewers assume auto-issuance is a generic mint path rather than a bounded stage allocation
 
-**Flow**
-1. The holder grants `BURN_TOKENS` permission to the `REVHiddenTokens` contract for the revnet.
-2. Call `hideTokensOf(revnetId, tokenCount, holder)` to burn the tokens and track the hidden balance. An operator with `HIDE_TOKENS` permission can call this on behalf of the holder.
-3. The bonding curve now sees a smaller totalSupply, so each remaining token is worth more on cash out.
-4. When the holder wants their tokens back, call `revealTokensOf(revnetId, tokenCount, beneficiary, holder)` to re-mint them. An operator with `REVEAL_TOKENS` permission can call this on behalf of the holder.
+**Postconditions**
 
-**Failure cases that matter:** trying to reveal more tokens than were hidden, forgetting that revealed tokens increase totalSupply again (reducing per-token cash-out value), and not realizing that hidden tokens must be revealed before they can be used as loan collateral.
+- the stage allocation is either claimed once or remains reserved until valid
 
-## Journey 4: Borrow Against Revnet Tokens Instead Of Selling Them
+## Journey 4: Hide Tokens To Change Visible Supply
 
-**Starting state:** a holder wants liquidity but does not want to exit the Revnet position.
+**Actor:** holder or authorized operator.
 
-**Success:** the holder opens a loan, receives borrowed value, and keeps an NFT loan position representing the debt.
+**Intent:** remove tokens from visible supply temporarily and later restore them.
 
-**Flow**
-1. The holder (or an operator with `OPEN_LOAN` permission) interacts with `REVLoans` using the eligible Revnet token exposure as collateral. The `holder` parameter specifies whose tokens are burned; the loan NFT is minted to `holder`.
-2. The system burns the relevant token exposure and mints a loan-position NFT to the holder.
-3. Loan terms depend on the live Revnet economics rather than a static side system.
-4. The borrower (or an operator with `REPAY_LOAN` / `REALLOCATE_LOAN` permission) can later repay, reallocate collateral, transfer the loan NFT, or face liquidation if conditions require it.
+**Preconditions**
 
-## Journey 5: Repay, Transfer, Or Liquidate A Loan Position
+- 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
 
-**Starting state:** a loan already exists and either the borrower or another actor needs to change its state.
+**Main Flow**
 
-**Success:** the debt path settles cleanly and the collateral outcome matches the Revnet's current rules.
+1. Grant `BURN_TOKENS` to `REVHiddenTokens`.
+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.
 
-**Flow**
-1. Repayment burns the debt and remints or releases the collateralized Revnet token position.
-2. Transfers move the loan NFT, not the original collateralized exposure.
-3. Liquidation consumes the loan under the rules encoded by `REVLoans` and the current Revnet state.
+**Failure Modes**
 
-**Edge conditions that change user experience:** cross-ruleset loan behavior, zero-amount or zero-price edge cases, and sourced versus unsourced loan paths.
+- more tokens are revealed than were hidden
+- 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 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 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 becomes a live loan position under Revnet economics
 
 ## Journey 6: Operate Inside The Bounded Post-Launch Control Envelope
 
-**Starting state:** the Revnet is live and an operator wants to use whatever ongoing controls the deployment allowed.
+**Actor:** operator with ongoing powers.
+
+**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.
 
-**Success:** the operator can use sanctioned controls without escaping the "autonomous after launch" model.
+**Failure Modes**
 
-**Flow**
-1. Review what `REVDeployer` allowed for split operators, stage evolution, and auxiliary integrations.
-2. Use only those surfaces rather than treating the project like a normal owner-governed Juicebox project.
-3. Audit cross-package behavior whenever the Revnet enabled buybacks, 721 hooks, router terminals, or suckers.
+- operators behave as though the Revnet were a normal owner-governed project
+- reviewers inspect controls in isolation and miss integrated runtime behavior
 
-## Journey 7: Receive Cross-Chain Payments With Correct Hook Routing
+**Postconditions**
 
-**Starting state:** a sucker pays the Revnet on behalf of a remote user via `payRemote`, and the hooks attached via `REVOwner.beforePayRecordedWith` need to see the real user.
+- post-launch control remains inside the bounded envelope left by deployment
 
-**Success:** the 721 hook and buyback hook see the real remote user as the beneficiary so NFTs mint to and buyback routing benefits the correct person.
+## Trust Boundaries
 
-**Flow**
-1. The sucker calls `terminal.pay()` with relay-beneficiary metadata.
-2. `REVOwner.beforePayRecordedWith()` resolves the relay beneficiary from the metadata when the payer is a registered sucker.
-3. The swapped beneficiary is forwarded to both the 721 hook and the buyback hook.
+- 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/foundry.toml

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

package/package.json

@@ -1,38 +1,38 @@
 {
-    "name": "@rev-net/core-v6",
-    "version": "0.0.32",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/rev-net/revnet-core-v6"
-    },
-    "engines": {
-        "node": ">=20.0.0"
-    },
-    "scripts": {
-        "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.33",
-        "@bananapus/buyback-hook-v6": "^0.0.27",
-        "@bananapus/core-v6": "^0.0.34",
-        "@bananapus/ownable-v6": "^0.0.17",
-        "@bananapus/permission-ids-v6": "^0.0.17",
-        "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.25",
-        "@croptop/core-v6": "github:mejango/croptop-core-v6",
-        "@openzeppelin/contracts": "^5.6.1",
-        "@uniswap/v4-core": "^1.0.2",
-        "@uniswap/v4-periphery": "^1.0.3"
-    },
-    "devDependencies": {
-        "@bananapus/address-registry-v6": "^0.0.17",
-        "@sphinx-labs/plugins": "^0.33.2"
-    }
+  "name": "@rev-net/core-v6",
+  "version": "0.0.34",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rev-net/revnet-core-v6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "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.35",
+    "@bananapus/buyback-hook-v6": "^0.0.27",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/ownable-v6": "^0.0.17",
+    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/router-terminal-v6": "^0.0.26",
+    "@bananapus/suckers-v6": "^0.0.25",
+    "@croptop/core-v6": "github:mejango/croptop-core-v6",
+    "@openzeppelin/contracts": "^5.6.1",
+    "@uniswap/v4-core": "^1.0.2",
+    "@uniswap/v4-periphery": "^1.0.3"
+  },
+  "devDependencies": {
+    "@bananapus/address-registry-v6": "^0.0.17",
+    "@sphinx-labs/plugins": "^0.33.2"
+  }
 }

package/references/operations.md

@@ -143,6 +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.
 
 ### NATIVE_TOKEN Accounting on Non-ETH Chains
 
@@ -198,6 +199,12 @@ Quick-reference for common read operations. All functions are `view`/`pure` and
 |------|------|---------|
 | Remaining auto-issuance for beneficiary | `REVDeployer.amountToAutoIssue(revnetId, stageId, beneficiary)` | `uint256` (0 if already claimed) |
 
+### Hidden Tokens
+
+| What | Call | Returns |
+|------|------|---------|
+| Hidden balance for holder | `REVHiddenTokens.hiddenBalanceOf(holder, revnetId)` | `uint256` |
+
 ### Loans
 
 | What | Call | Returns |

package/references/runtime.md

@@ -13,6 +13,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REVDeployer` | Deploys revnets, permanently owns the project NFT. Manages stages, splits, auto-issuance, buyback hooks, suckers, split operators, and configuration state storage. Exposes `OWNER()` view returning the REVOwner address. Calls DEPLOYER-restricted setters on REVOwner during deployment to store `cashOutDelayOf` and `tiered721HookOf`. |
 | `REVOwner` | Runtime hook contract for all revnets. Implements `IJBRulesetDataHook` + `IJBCashOutHook`. Set as the `dataHook` in each revnet's ruleset metadata. Handles pay hooks, cash-out hooks, mint permissions, and sucker verification. Stores `cashOutDelayOf` and `tiered721HookOf` mappings (set by REVDeployer via DEPLOYER-restricted setters `setCashOutDelayOf()` and `setTiered721HookOf()`). |
 | `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). |
+| `REVHiddenTokens` | Burns tokens into a hidden balance and can later re-mint them. This is a supply-management primitive, not just a wallet convenience feature. |
 
 ## Key Functions
 
@@ -66,6 +67,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REVLoans.loanOf(loanId)` | Returns the full `REVLoan` struct for a loan. |
 | `REVLoans.loanSourcesOf(revnetId)` | Returns all `(terminal, token)` pairs used for loans by a revnet. |
 | `REVLoans.revnetIdOfLoanWith(loanId)` | Decode the revnet ID from a loan ID (`loanId / 1_000_000_000_000`). |
+| `REVHiddenTokens.hiddenBalanceOf(holder, revnetId)` | Returns how many tokens a holder has hidden from visible supply. |
 
 ## Integration Points
 
@@ -96,3 +98,10 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REV721TiersHookFlags` | `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting`, `preventOverspending` | Same as `JB721TiersHookFlags` minus `issueTokensForSplits`. Revnets do their own weight adjustment for splits. |
 | `REVCroptopAllowedPost` | `category` (uint24), `minimumPrice` (uint104), `minimumTotalSupply` (uint32), `maximumTotalSupply` (uint32), `allowedAddresses[]` | Croptop posting criteria |
 | `REVSuckerDeploymentConfig` | `deployerConfigurations[]`, `salt` | Cross-chain sucker deployment |
+### Hidden Tokens
+
+| 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.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;
             }

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;