@rev-net/core-v6 0.0.29 → 0.0.31

package/ADMINISTRATION.md

@@ -6,8 +6,8 @@ Admin privileges and their scope in revnet-core-v6. Revnets are designed to be a
 
 | Item | Details |
 |------|---------|
-| Scope | Autonomous revnet deployment, split-operator powers, loan metadata ownership, and the boundaries imposed by revnet immutability. |
-| Operators | The per-revnet split operator, the global `REVLoans` owner for metadata cosmetics, the protocol-owned `REVDeployer`, loan NFT holders, and permissionless callers for open lifecycle actions. |
+| Scope | Autonomous revnet deployment, split-operator powers, loan metadata ownership, hidden token management, and the boundaries imposed by revnet immutability. |
+| Operators | The per-revnet split operator, the global `REVLoans` owner for metadata cosmetics, the protocol-owned `REVDeployer`, loan NFT holders (or operators with `REPAY_LOAN`/`REALLOCATE_LOAN`/`OPEN_LOAN` permissions), `REVHiddenTokens` callers (or operators with `HIDE_TOKENS`/`REVEAL_TOKENS` permissions), and permissionless callers for open lifecycle actions. |
 | Highest-risk actions | Converting an existing project into a revnet, changing or burning the split operator, and configuring buyback, router, price-feed, or sucker permissions inside the narrow allowed operator surface. |
 | Recovery posture | Revnet economics are intentionally not admin-recoverable. A bad deployment generally means abandoning the revnet and deploying a new one. |
 
@@ -49,8 +49,8 @@ Admin privileges and their scope in revnet-core-v6. Revnets are designed to be a
 
 ### Loan NFT Owner
 
-- **How assigned:** The `_msgSender()` who calls `borrowFrom()` receives the loan ERC-721. Transferable like any ERC-721.
-- **Scope:** Per-loan. Only the current NFT owner can repay the loan, return collateral, or reallocate collateral to a new loan.
+- **How assigned:** The `holder` specified in `borrowFrom()` receives the loan ERC-721. When no operator delegation is used, the caller passes themselves as `holder`. Transferable like any ERC-721.
+- **Scope:** Per-loan. The current NFT owner — or an operator with the relevant `JBPermissionIds` (`REPAY_LOAN`, `REALLOCATE_LOAN`) — can repay the loan, return collateral, or reallocate collateral to a new loan.
 
 ### Anyone (Permissionless)
 
@@ -98,9 +98,9 @@ Optional 721 permissions (granted only if enabled at deployment via `REVDeploy72
 
 | Function | Required Role | Access Control | What It Does |
 |----------|--------------|----------------|-------------|
-| `borrowFrom()` | Anyone (must hold revnet tokens) | None -- but caller's tokens are burned as collateral | Opens a loan against revnet token collateral. |
-| `repayLoan()` | Loan NFT Owner | `_ownerOf(loanId) == _msgSender()` | Repays a loan (partially or fully) and returns collateral. |
-| `reallocateCollateralFromLoan()` | Loan NFT Owner | `_ownerOf(loanId) == _msgSender()` | Splits excess collateral from an existing loan into a new loan. |
+| `borrowFrom()` | Holder or operator with `OPEN_LOAN` | `PERMISSIONS.hasPermission` if caller ≠ holder | Opens a loan against revnet token collateral. The `holder` parameter specifies whose tokens are burned; the loan NFT is minted to `holder`. |
+| `repayLoan()` | Loan NFT Owner or operator with `REPAY_LOAN` | `PERMISSIONS.hasPermission` if caller ≠ owner | Repays a loan (partially or fully) and returns collateral. Replacement loans are minted to the original loan owner. |
+| `reallocateCollateralFromLoan()` | Loan NFT Owner or operator with `REALLOCATE_LOAN` | `PERMISSIONS.hasPermission` if caller ≠ owner | Splits excess collateral from an existing loan into a new loan. Returned collateral and replacement loans go to the original loan owner. |
 | `liquidateExpiredLoansFrom()` | Anyone | None | Liquidates loans that have exceeded the 10-year liquidation duration. Permanently destroys collateral. |
 | `setTokenUriResolver()` | REVLoans Owner | `onlyOwner` (OpenZeppelin Ownable) | Sets the contract that resolves loan NFT metadata URIs. |
 
@@ -123,7 +123,7 @@ Revnets are designed to operate without a traditional project owner. The followi
 - **No approval hooks.** All rulesets are deployed with `approvalHook = address(0)`. There is no mechanism to block or delay stage transitions.
 - **Cash outs cannot be fully disabled.** The deployer enforces `cashOutTaxRate < MAX_CASH_OUT_TAX_RATE` for every stage, guaranteeing that token holders always retain some ability to cash out.
 - **Data hook is REVOwner.** `REVOwner` is set as the data hook (`metadata.dataHook = address(OWNER())`) for all rulesets, ensuring consistent fee and sucker logic without external admin control. REVOwner stores `cashOutDelayOf` and `tiered721HookOf` in its own storage (set by REVDeployer via DEPLOYER-restricted setters during deployment).
-- **Mint permission is restricted.** Only the loans contract, the buyback hook (and its delegates), and registered suckers can mint tokens (as determined by `REVOwner.hasMintPermissionFor`). The split operator cannot mint fungible revnet tokens.
+- **Mint permission is restricted.** Only the loans contract, the hidden tokens contract, the buyback hook (and its delegates), and registered suckers can mint tokens (as determined by `REVOwner.hasMintPermissionFor`). The split operator cannot mint fungible revnet tokens.
 - **No held fee manipulation.** The deployer has no function to process or return held fees arbitrarily.
 - **Owner minting is constrained.** While `allowOwnerMinting = true` is set in ruleset metadata, the "owner" is the `REVDeployer` contract. It only uses this to mint auto-issuance tokens (amounts fixed at deployment) and to return loan collateral.
 
@@ -133,9 +133,18 @@ The `REVLoans` contract has minimal admin surface by design:
 
 - **All economic parameters are constants.** Loan liquidation duration (10 years), fee percentages (MIN 2.5%, MAX 50%), and the REV fee (1%) are hardcoded as immutable constants. No admin can change them.
 - **The only admin function is `setTokenUriResolver()`**, which controls how loan NFTs render their metadata. This is purely cosmetic and has no effect on loan economics, collateral, or fund flows.
-- **Loan management is permissioned to NFT holders only.** Repayment, collateral reallocation, and refinancing require ownership of the specific loan's ERC-721 NFT.
+- **Loan management is permissioned to NFT holders or delegated operators.** Repayment requires loan NFT ownership or `REPAY_LOAN` permission. Collateral reallocation requires loan NFT ownership or `REALLOCATE_LOAN` permission. Borrowing on behalf of another holder requires `OPEN_LOAN` permission. In all delegated cases, collateral and loan NFTs flow to the original holder/owner, not the operator.
 - **Liquidation is permissionless.** Anyone can call `liquidateExpiredLoansFrom()` for loans past the 10-year duration.
 
+## Hidden Tokens Administration
+
+The `REVHiddenTokens` contract inherits `JBPermissioned` for operator delegation but has no admin surface:
+
+- **Operations are holder-initiated or operator-delegated.** Any token holder can hide or reveal their own tokens. An operator with `HIDE_TOKENS` permission can hide tokens on behalf of a holder; an operator with `REVEAL_TOKENS` permission can reveal on their behalf.
+- **No owner or admin role.** The contract has no `Ownable` or privileged functions.
+- **Mint permission is granted via REVOwner.** `REVHiddenTokens` is listed in `REVOwner.hasMintPermissionFor` so it can re-mint tokens on reveal. This is a global immutable set at REVOwner deployment.
+- **BURN_TOKENS permission is per-user.** Each user must individually grant `BURN_TOKENS` permission to the `REVHiddenTokens` contract before hiding tokens.
+
 ## Immutable Configuration
 
 The following parameters are set at deployment and can never be changed:
@@ -171,6 +180,7 @@ The following parameters are set at deployment and can never be changed:
 - `BUYBACK_HOOK` -- the buyback hook (shared immutable with REVDeployer)
 - `DIRECTORY` -- the Juicebox directory (shared immutable with REVDeployer)
 - `FEE_REVNET_ID` -- the project ID that receives cash-out fees (shared immutable)
+- `HIDDEN_TOKENS` -- the hidden tokens contract address (shared immutable)
 - `SUCKER_REGISTRY` -- the sucker registry (shared immutable)
 - `LOANS` -- the loans contract address (shared immutable)
 - `FEE` -- the cash-out fee constant (2.5%)

package/ARCHITECTURE.md

@@ -9,6 +9,7 @@
 - `REVDeployer` owns launch-time configuration and runtime wrapper behavior.
 - `REVOwner` owns owner-like data-hook behavior for revnet projects.
 - `REVLoans` owns the loan lifecycle.
+- `REVHiddenTokens` owns temporary token hiding and supply exclusion.
 - The repo composes several sibling repos instead of reimplementing them.
 
 ## Main Components
@@ -18,6 +19,7 @@
 | `REVDeployer` | Launches revnets, queues staged rulesets, wires hooks, grants operator permissions, and exposes runtime wrapper behavior |
 | `REVOwner` | Ownerless policy surface plugged into revnet rulesets |
 | `REVLoans` | Burn-collateral borrow/repay/liquidate flow represented as ERC-721 loans |
+| `REVHiddenTokens` | Temporary token hiding: burn to exclude from totalSupply, re-mint on reveal |
 | config structs | Stage, auto-issuance, loan source, and 721-hook configuration surfaces |
 
 ## Runtime Model
@@ -50,6 +52,7 @@ borrower
 - The project is designed to be ownerless after deployment. "Easy" admin recovery paths would break the product thesis.
 - Stage configuration is effectively permanent once queued.
 - Loan collateral is burned, not escrowed. Supply-sensitive logic must treat that as real destruction until repayment.
+- Hidden tokens are burned, not escrowed. They reduce totalSupply until revealed. This interacts with bonding curve valuations.
 - `REVOwner` and `REVDeployer` are tightly coupled. Their setup order is part of correctness.
 
 ## Where Complexity Lives

package/AUDIT_INSTRUCTIONS.md

@@ -17,6 +17,7 @@ In scope:
 - `src/REVDeployer.sol`
 - `src/REVOwner.sol`
 - `src/REVLoans.sol`
+- `src/REVHiddenTokens.sol`
 - `src/interfaces/`
 - `src/structs/`
 - deployment scripts in `script/`
@@ -45,6 +46,7 @@ The repo splits responsibilities:
 - `REVDeployer`: launches revnets, encodes stage configs, manages optional 721 and sucker composition
 - `REVOwner`: runtime data/cash-out hook used by deployed revnets
 - `REVLoans`: loan system that burns collateral on borrow and re-mints on repayment
+- `REVHiddenTokens`: temporary token hiding that burns tokens to exclude from totalSupply and re-mints on reveal
 
 Important composition behavior:
 - revnet payments may be proxied through 721 and buyback hooks
@@ -75,7 +77,10 @@ Fee-free or mint-enabled paths meant for registered omnichain components must no
 6. Collateral burn/remint symmetry holds
 Loan collateral that is burned on borrow and re-minted on repay must not be duplicable, strandable, or recoverable by the wrong party.
 
-7. Stage transitions do not create hidden refinancing windows
+7. Hidden token accounting is sound
+Tokens hidden via REVHiddenTokens must be exactly recoverable on reveal. The hidden balance must not allow minting more tokens than were burned, and totalHiddenOf must equal the sum of all per-holder hidden balances.
+
+8. Stage transitions do not create hidden refinancing windows
 Changes in issuance or cash-out economics across stages must not let a borrower lock in value that the system intended to become unavailable.
 
 ## Threat Model
@@ -87,11 +92,13 @@ Prioritize:
 - array or hook-spec assumptions that depend on non-empty returns
 - split-weight accounting during 721 compositions
 - Permit2 and ERC-2771 assisted loan flows
+- operator delegation abuse: `OPEN_LOAN`, `REPAY_LOAN`, `REALLOCATE_LOAN`, `HIDE_TOKENS`, `REVEAL_TOKENS` permission checks — verify collateral and loan NFTs always flow to the holder/owner, never the operator
 
 The best attacker mindsets here are:
 - a borrower who can move surplus or stage timing before and after borrowing
 - a caller exploiting the fact that revnets are composed from several optional subsystems, not one monolith
 - an operator or deployer helper that retained one capability too many
+- a delegated operator who tricks a holder into granting permission, then exploits the delegation to extract value (e.g., borrowing on behalf of a holder and directing funds to a beneficiary they control)
 
 ## Hotspots
 
@@ -99,6 +106,8 @@ The best attacker mindsets here are:
 - `REVOwner.beforeCashOutRecordedWith`
 - deployer-only linkage between `REVDeployer` and `REVOwner`
 - `REVLoans` borrowable amount, fee accrual, and liquidation logic
+- `REVHiddenTokens.hideTokensOf` and `revealTokensOf` burn/mint symmetry and `HIDE_TOKENS`/`REVEAL_TOKENS` permission checks
+- `REVLoans` operator delegation: `OPEN_LOAN`, `REPAY_LOAN`, `REALLOCATE_LOAN` inline permission checks — verify holder/owner receives collateral and loan NFTs in all delegation paths
 - any path that assumes a valid tiered 721 hook or sucker mapping exists
 
 ## Sequences Worth Replaying
@@ -108,6 +117,7 @@ The best attacker mindsets here are:
 3. Borrow after surplus inflation, then force or observe surplus contraction before liquidation.
 4. Cash out through a legitimate sucker path versus a near-sucker spoof path.
 5. Any path where `REVOwner` expects hook arrays or external replies to be non-empty.
+6. Hide tokens, have an accomplice cash out at the inflated rate, then reveal — check whether the net outcome is profitable.
 
 ## Finding Bar
 

package/CHANGELOG.md

@@ -9,9 +9,11 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 - `REVDeployer`
 - `REVOwner`
 - `REVLoans`
+- `REVHiddenTokens`
 - `IREVDeployer`
 - `IREVOwner`
 - `IREVLoans`
+- `IREVHiddenTokens`
 
 ## Summary
 
@@ -21,12 +23,36 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 - The v6 test tree is substantially broader than the v5 tree, with dedicated regression, fork, attack, and invariant coverage for loans, cash-outs, split weights, and lifecycle edges.
 - The repo moved from the v5 `0.8.23` baseline to `0.8.28`.
 
+## Operator delegation (permission IDs 35–39)
+
+- Added five new `JBPermissionIds` for operator delegation in `@bananapus/permission-ids-v6`:
+  - `HIDE_TOKENS` (35) — hide tokens on behalf of a holder via `REVHiddenTokens.hideTokensOf`
+  - `OPEN_LOAN` (36) — open a loan on behalf of a token holder via `REVLoans.borrowFrom`
+  - `REALLOCATE_LOAN` (37) — reallocate loan collateral on behalf of a loan owner via `REVLoans.reallocateCollateralFromLoan`
+  - `REPAY_LOAN` (38) — repay a loan on behalf of a loan owner via `REVLoans.repayLoan`
+  - `REVEAL_TOKENS` (39) — reveal hidden tokens on behalf of a holder via `REVHiddenTokens.revealTokensOf`
+- `REVHiddenTokens` now inherits `JBPermissioned` and accepts a `holder` parameter on `hideTokensOf` and `revealTokensOf`. An operator with the appropriate permission can act on behalf of the holder.
+- `REVLoans.borrowFrom` now accepts a `holder` parameter. The loan NFT is minted to `holder`, and collateral is burned from `holder`. An operator with `OPEN_LOAN` permission can borrow on behalf of a holder.
+- `REVLoans.repayLoan` now allows permissioned operators with `REPAY_LOAN` to repay on behalf of the loan NFT owner. Replacement loans are minted to the original loan owner.
+- `REVLoans.reallocateCollateralFromLoan` now allows permissioned operators with `REALLOCATE_LOAN` to reallocate on behalf of the loan NFT owner. Returned collateral and replacement loans go to the original loan owner.
+- `REVLoans` stores a `PERMISSIONS` immutable for inline permission checks (cannot inherit `JBPermissioned` due to existing `ERC721 + ERC2771Context + Ownable` inheritance).
+
+### Breaking ABI changes from delegation
+
+- `IREVHiddenTokens.hideTokensOf` signature changed: added `address holder` parameter
+- `IREVHiddenTokens.revealTokensOf` signature changed: added `address holder` parameter
+- `IREVHiddenTokens.HideTokens` event: added `address holder` field
+- `IREVHiddenTokens.RevealTokens` event: added `address holder` field
+- `IREVLoans.borrowFrom` signature changed: added `address holder` as last parameter
+
 ## Verified deltas
 
 - `IREVDeployer.deployWith721sFor(...)` is gone.
 - `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.
 - The old caller-supplied `REVBuybackHookConfig` path is no longer part of the deployer interface.
 
 ## Breaking ABI changes

package/README.md

@@ -28,6 +28,7 @@ The key point is that a Revnet is not just "a Juicebox project with presets." It
 | `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 (burn) tokens, excluding them from totalSupply and increasing cash-out value for remaining holders. Hidden tokens can be revealed (re-minted) at any time. |
 
 ## Mental Model
 

package/RISKS.md

@@ -63,6 +63,13 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 - **No automatic recovery mechanism.** Once a price feed returns 0, the affected source's debt remains invisible to `_totalBorrowedFrom` until the feed recovers. There is no event emitted when a source is skipped, no fallback oracle, and no circuit breaker that pauses borrowing when feed health degrades. Operators should actively monitor price feed health and treat any feed returning 0 as a risk event for the revnet's loan system.
 - **Decimal normalization truncation.** When converting from higher-decimal tokens (18) to lower-decimal targets (6), integer division truncates. For sources with large outstanding borrows in high-decimal tokens, this truncation can systematically undercount the total borrowed amount, allowing slightly more borrowing than intended. For example, converting 999,999,999,999 wei (18-decimal) to 6-decimal precision discards 12 digits of precision. Across many sources, these per-source truncation errors accumulate additively, further widening the gap between the reported and actual total debt.
 
+### Hidden token supply manipulation
+
+- **Hiding reduces totalSupply, inflating per-token cash-out value.** When a holder hides tokens via `REVHiddenTokens`, those tokens are burned and excluded from `totalSupply`. The bonding curve sees fewer tokens, so each remaining token is worth more on cash-out. A holder with a large position can hide tokens, have an accomplice cash out at the inflated rate, then reveal. The net effect depends on the `cashOutTaxRate` and the relative positions. Operator delegation (`HIDE_TOKENS`/`REVEAL_TOKENS` permissions) extends this to permissioned operators acting on behalf of holders.
+- **Hidden tokens must be revealed before use as loan collateral.** `REVHiddenTokens` and `REVLoans` are separate systems. A holder cannot borrow against hidden tokens — they must first reveal (re-mint) them, then borrow. This is by design but may confuse users.
+- **Reveal mints without reserved percent.** `revealTokensOf` calls `mintTokensOf` with `useReservedPercent: false`. This is correct because the tokens were previously burned and are being restored, not newly issued. But it means revealed tokens bypass the reserved-token mechanism entirely.
+- **REVHiddenTokens has mint permission via REVOwner.** The contract is added to `REVOwner.hasMintPermissionFor`. If `REVHiddenTokens` has a vulnerability, it could mint unbounded tokens for any revnet.
+
 ### Auto-issuance overflow potential
 
 - **`REVAutoIssuance.count` is `uint104` (~2.03e31).** Multiple auto-issuances for the same beneficiary in the same stage are summed via `+=` in `_makeRulesetConfigurations`. If cumulative auto-issuances exceed `uint256`, this wraps. In practice, `uint104` inputs limit each addition, but verify no path allows the mapping value to overflow.
@@ -121,7 +128,7 @@ REVOwner sits between the terminal and the actual hooks (buyback hook, 721 hook)
 
 ### Permission escalation through proxy
 
-- **`hasMintPermissionFor` grants mint to four categories.** `REVOwner.hasMintPermissionFor` grants mint to: the loans contract, buyback hook, buyback hook delegates, and suckers. If any of these contracts have a vulnerability that allows arbitrary calls, they can mint unlimited revnet tokens for any revnet.
+- **`hasMintPermissionFor` grants mint to five categories.** `REVOwner.hasMintPermissionFor` grants mint to: the loans contract, the hidden tokens contract, buyback hook, buyback hook delegates, and suckers. If any of these contracts have a vulnerability that allows arbitrary calls, they can mint unlimited revnet tokens for any revnet.
 - **Wildcard permissions.** REVDeployer grants `USE_ALLOWANCE` to `LOANS` with `projectId=0` (wildcard). This means the loans contract can drain surplus from ANY revnet deployed by this deployer, constrained only by the loan logic itself. A bug in `REVLoans._addTo` that miscalculates `addedBorrowAmount` could drain treasuries.
 
 ---
@@ -192,11 +199,17 @@ These MUST hold. Breaking any of them is a finding.
 - **Cash-out fees flow to fee revnet.** If the fee terminal `pay` succeeds, the fee goes to `FEE_REVNET_ID`. If it fails, the fee returns to the originating project via `addToBalanceOf`. Funds are never lost and never kept by the caller.
 - **Loan REV fees flow to REV revnet.** If `feeTerminal.pay` succeeds, the fee goes to `REV_ID`. If it fails (try-catch), the fee amount is zeroed and added to the borrower's payout. The fee is never lost -- it either reaches the REV revnet or goes to the borrower.
 
+### Hidden token accounting
+
+- **Hidden balance conservation.** `totalHiddenOf[revnetId]` == sum of `hiddenBalanceOf[holder][revnetId]` across all holders.
+- **Reveal bounded by hide.** No holder can reveal more tokens than they have hidden. `revealTokensOf` reverts with `REVHiddenTokens_InsufficientHiddenBalance` if `tokenCount > hiddenBalanceOf[caller][revnetId]`.
+- **No double-mint from reveal.** Each hidden token can only be revealed once. Decrementing `hiddenBalanceOf` before minting prevents double-reveal.
+
 ### Privilege isolation
 
 - **Sucker privilege.** Only addresses returning `true` from `SUCKER_REGISTRY.isSuckerOf(projectId, addr)` get 0% cashout tax. No other code path grants this exemption.
-- **Loan ownership.** Only `_ownerOf(loanId)` can call `repayLoan` and `reallocateCollateralFromLoan`. The loan NFT is burned before any state changes in repayment, preventing double-use.
-- **Mint permission.** Only `LOANS`, `BUYBACK_HOOK`, buyback hook delegates (via `BUYBACK_HOOK.hasMintPermissionFor`), and suckers (via `REVOwner._isSuckerOf`) can mint tokens. No other address passes the `REVOwner.hasMintPermissionFor` check.
+- **Loan ownership.** Only `_ownerOf(loanId)` — or an operator with the relevant `JBPermissionIds` (`REPAY_LOAN` for repayment, `REALLOCATE_LOAN` for reallocation) — can call `repayLoan` and `reallocateCollateralFromLoan`. Similarly, `borrowFrom` requires the caller to be the `holder` or to have `OPEN_LOAN` permission. The loan NFT is burned before any state changes in repayment, preventing double-use. Replacement loan NFTs are minted to the original holder/owner, not the operator. However, delegated operators control the `beneficiary` parameter and can direct borrowed funds, returned collateral, or revealed tokens to any address (see §8.5).
+- **Mint permission.** Only `LOANS`, `HIDDEN_TOKENS`, `BUYBACK_HOOK`, buyback hook delegates (via `BUYBACK_HOOK.hasMintPermissionFor`), and suckers (via `REVOwner._isSuckerOf`) can mint tokens. No other address passes the `REVOwner.hasMintPermissionFor` check.
 
 ---
 
@@ -218,6 +231,17 @@ These MUST hold. Breaking any of them is a finding.
 
 `_borrowableAmountFrom` reads live surplus. An attacker could inflate surplus via `addToBalanceOf`, but donations are permanent (no recovery), and the extra borrowable amount is always less than the donation. `pay` increases both surplus AND supply, neutralizing the effect. With non-zero `cashOutTaxRate`, the concave bonding curve makes this even worse for attackers. The attack is self-defeating by construction.
 
-### 8.5 Borrow-repay arbitrage is unprofitable (by design)
+### 8.5 Delegated operators control beneficiary independently of holder/owner (by design)
+
+When a holder grants `OPEN_LOAN`, `REALLOCATE_LOAN`, `REPAY_LOAN`, or `REVEAL_TOKENS` permission to an operator, the operator can set the `beneficiary` parameter to any address — including themselves. This means:
+
+- **`borrowFrom`**: An operator with `OPEN_LOAN` permission burns the holder's tokens as collateral but can direct the borrowed funds to an arbitrary beneficiary.
+- **`reallocateCollateralFromLoan`**: An operator with `REALLOCATE_LOAN` permission can direct the borrowed funds from the new loan to an arbitrary beneficiary.
+- **`repayLoan`**: An operator with `REPAY_LOAN` permission can direct returned collateral tokens to an arbitrary beneficiary.
+- **`revealTokensOf`**: An operator with `REVEAL_TOKENS` permission can direct revealed (re-minted) tokens to an arbitrary beneficiary instead of the original holder.
+
+This is accepted because the JBPermissions delegation model is opt-in: a holder explicitly grants permission to a specific operator for a specific project. The holder trusts the operator to act in their interest. Restricting `beneficiary` to the holder would break legitimate delegation use cases (e.g., automated vaults, multi-sig workflows, portfolio managers). Holders should only grant these permissions to operators they fully trust.
+
+### 8.6 Borrow-repay arbitrage is unprofitable (by design)
 
 A borrower who pays the prepaid fee upfront (minimum 2.5% + REV fee 1% = 3.5%) can repay at any time within the prepaid duration with no additional cost. If the bonding curve value of the collateral increases during the prepaid window, the borrower can repay, recover their collateral, and cash out at the higher value. This is not profitable as a standalone strategy because the 3.5% minimum fee exceeds the expected value gained from short-term surplus fluctuations. For borrowers who need liquidity anyway, it provides free optionality — which is the intended use case.

package/SKILLS.md

@@ -13,6 +13,7 @@
 | Deployment and stage config | [`src/REVDeployer.sol`](./src/REVDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
 | Runtime owner and data-hook behavior | [`src/REVOwner.sol`](./src/REVOwner.sol) |
 | Loan accounting and liquidation behavior | [`src/REVLoans.sol`](./src/REVLoans.sol) |
+| Temporary token hiding and supply exclusion | [`src/REVHiddenTokens.sol`](./src/REVHiddenTokens.sol) |
 | Types and helpers | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/), [`test/helpers/`](./test/helpers/) |
 | Loan regressions, economics, and forks | [`test/REVLoansRegressions.t.sol`](./test/REVLoansRegressions.t.sol), [`test/TestLongTailEconomics.t.sol`](./test/TestLongTailEconomics.t.sol), [`test/fork/`](./test/fork/), [`test/regression/`](./test/regression/) |
 
@@ -38,6 +39,6 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 ## Working Rules
 
-- Start in `REVDeployer` for launch-time behavior, `REVOwner` for runtime hook behavior, and `REVLoans` for collateral and debt accounting.
+- Start in `REVDeployer` for launch-time behavior, `REVOwner` for runtime hook behavior, `REVLoans` for collateral and debt accounting, and `REVHiddenTokens` for temporary supply exclusion.
 - Verify any economic assumption in code or tests before relying on it. Revnet docs carry more economic interpretation than most repos.
 - For anything cross-chain or stage-related, check both the deployer path and the reading-state reference before editing.

package/USER_JOURNEYS.md

@@ -43,6 +43,20 @@
 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.
 
+## Journey 3a: Hide Tokens To Increase Cash-Out Value For Remaining Holders
+
+**Starting state:** a holder wants to temporarily exclude some tokens from totalSupply without permanently giving them up.
+
+**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.
+
+**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.
+
+**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.
+
 ## Journey 4: Borrow Against Revnet Tokens Instead Of Selling Them
 
 **Starting state:** a holder wants liquidity but does not want to exit the Revnet position.
@@ -50,10 +64,10 @@
 **Success:** the holder opens a loan, receives borrowed value, and keeps an NFT loan position representing the debt.
 
 **Flow**
-1. The holder interacts with `REVLoans` using the eligible Revnet token exposure as collateral.
-2. The system burns or escrows the relevant token exposure and mints a loan-position NFT.
+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 can later repay, transfer the loan NFT, or face liquidation if conditions require it.
+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.
 
 ## Journey 5: Repay, Transfer, Or Liquidate A Loan Position
 
@@ -79,6 +93,17 @@
 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.
 
+## Journey 7: Receive Cross-Chain Payments With Correct Hook Routing
+
+**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.
+
+**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.
+
+**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.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rev-net/core-v6",
-    "version": "0.0.29",
+    "version": "0.0.31",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -19,14 +19,14 @@
         "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.32",
-        "@bananapus/buyback-hook-v6": "^0.0.26",
-        "@bananapus/core-v6": "^0.0.32",
+        "@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.15",
+        "@bananapus/permission-ids-v6": "^0.0.17",
         "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.22",
-        "@croptop/core-v6": "^0.0.30",
+        "@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"
@@ -35,4 +35,4 @@
         "@bananapus/address-registry-v6": "^0.0.17",
         "@sphinx-labs/plugins": "^0.33.2"
     }
-}
+}

package/references/operations.md

@@ -63,7 +63,7 @@ Use this file when you need revnet-specific risks, state reads, constants, or ex
 | `REVLoans_PermitAllowanceNotEnough(allowanceAmount, requiredAmount)` | When the permit2 allowance is insufficient for the repayment. |
 | `REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows(newBorrowAmount, loanAmount)` | When the collateral being transferred out would leave the original loan undercollateralized. |
 | `REVLoans_SourceMismatch()` | When `reallocateCollateralFromLoan` specifies a source that doesn't match the existing loan's source. |
-| `REVLoans_Unauthorized(caller, owner)` | When a non-owner tries to repay or reallocate someone else's loan. |
+| `JBPermissioned_Unauthorized(account, sender, projectId, permissionId)` | When a non-owner without the required permission (`OPEN_LOAN`, `REPAY_LOAN`, or `REALLOCATE_LOAN`) tries to act on someone else's loan. Inherited from `JBPermissioned`. |
 | `REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount)` | When the actual borrow amount is less than the caller's `minBorrowAmount`. |
 | `REVLoans_ZeroBorrowAmount()` | When a borrow or reallocation would result in zero borrowed funds. |
 | `REVLoans_ZeroCollateralLoanIsInvalid()` | When a loan would end up with zero collateral. |

package/script/Deploy.s.sol

@@ -37,6 +37,7 @@ import {REVConfig} from "../src/structs/REVConfig.sol";
 import {REVDescription} from "../src/structs/REVDescription.sol";
 import {REVStageConfig} from "../src/structs/REVStageConfig.sol";
 import {REVSuckerDeploymentConfig} from "../src/structs/REVSuckerDeploymentConfig.sol";
+import {REVHiddenTokens} from "./../src/REVHiddenTokens.sol";
 import {REVLoans} from "./../src/REVLoans.sol";
 import {REVDeploy721TiersHookConfig} from "../src/structs/REVDeploy721TiersHookConfig.sol";
 import {REVCroptopAllowedPost} from "../src/structs/REVCroptopAllowedPost.sol";
@@ -93,6 +94,8 @@ contract DeployScript is Script, Sphinx {
     // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 REVLOANS_SALT = "_REV_LOANS_SALT_V6_";
     // forge-lint: disable-next-line(mixed-case-variable)
+    bytes32 REVHIDDENTOKENS_SALT = "_REV_HIDDEN_TOKENS_SALT_V6_";
+    // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 REVOWNER_SALT = "_REV_OWNER_SALT_V6_";
     // forge-lint: disable-next-line(mixed-case-variable)
     address LOANS_OWNER;
@@ -369,10 +372,13 @@ contract DeployScript is Script, Sphinx {
 
         // Try to find an existing deployment by checking all project IDs that have already been created.
         bool _revloansExists;
+        bool _revHiddenTokensExists;
         bool _revOwnerExists;
         bool _revDeployerExists;
         // The address of the previously deployed REVLoans, if found.
         address _existingRevloansAddr;
+        // The address of the previously deployed REVHiddenTokens, if found.
+        address _existingHiddenTokensAddr;
         // The address of the previously deployed REVOwner, if found.
         address _existingOwnerAddr;
         // The address of the previously deployed REVDeployer, if found.
@@ -384,7 +390,7 @@ contract DeployScript is Script, Sphinx {
                 salt: REVLOANS_SALT,
                 creationCode: type(REVLoans).creationCode,
                 arguments: abi.encode(
-                    core.controller, core.projects, _candidateId, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER
+                    core.controller, suckers.registry, _candidateId, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER
                 )
             });
 
@@ -397,6 +403,13 @@ contract DeployScript is Script, Sphinx {
                     _existingRevloansAddr = _candidateRevloansAddr;
                     _revloansExists = true;
 
+                    // Also predict and verify the hidden tokens contract.
+                    (_existingHiddenTokensAddr, _revHiddenTokensExists) = _isDeployed({
+                        salt: REVHIDDENTOKENS_SALT,
+                        creationCode: type(REVHiddenTokens).creationCode,
+                        arguments: abi.encode(core.controller, TRUSTED_FORWARDER)
+                    });
+
                     // Also predict and verify the owner.
                     (_existingOwnerAddr, _revOwnerExists) = _isDeployed({
                         salt: REVOWNER_SALT,
@@ -406,7 +419,8 @@ contract DeployScript is Script, Sphinx {
                             core.controller.DIRECTORY(),
                             _candidateId,
                             suckers.registry,
-                            _candidateRevloansAddr
+                            _candidateRevloansAddr,
+                            _existingHiddenTokensAddr
                         )
                     });
 
@@ -457,13 +471,20 @@ contract DeployScript is Script, Sphinx {
             ? REVLoans(payable(_existingRevloansAddr))
             : new REVLoans{salt: REVLOANS_SALT}({
                 controller: core.controller,
-                projects: core.projects,
+                suckerRegistry: suckers.registry,
                 revId: FEE_PROJECT_ID,
                 owner: LOANS_OWNER,
                 permit2: PERMIT2,
                 trustedForwarder: TRUSTED_FORWARDER
             });
 
+        // Deploy REVHiddenTokens — allows revnet holders to temporarily hide tokens from totalSupply.
+        REVHiddenTokens revHiddenTokens = _revHiddenTokensExists
+            ? REVHiddenTokens(_existingHiddenTokensAddr)
+            : new REVHiddenTokens{salt: REVHIDDENTOKENS_SALT}({
+                controller: core.controller, trustedForwarder: TRUSTED_FORWARDER
+            });
+
         // Deploy REVOwner — the runtime data hook that handles pay and cash out callbacks.
         REVOwner revOwner = _revOwnerExists
             ? REVOwner(_existingOwnerAddr)
@@ -472,7 +493,8 @@ contract DeployScript is Script, Sphinx {
                 directory: core.controller.DIRECTORY(),
                 feeRevnetId: FEE_PROJECT_ID,
                 suckerRegistry: suckers.registry,
-                loans: address(revloans)
+                loans: address(revloans),
+                hiddenTokens: address(revHiddenTokens)
             });
 
         // Deploy REVDeployer with the REVLoans, buyback hook, and REVOwner addresses.

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[](9 + 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;
@@ -385,10 +385,11 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         allOperatorPermissions[6] = JBPermissionIds.SET_BUYBACK_HOOK;
         allOperatorPermissions[7] = JBPermissionIds.SET_ROUTER_TERMINAL;
         allOperatorPermissions[8] = JBPermissionIds.SET_TOKEN_METADATA;
+        allOperatorPermissions[9] = JBPermissionIds.SIGN_FOR_ERC20;
 
         // Copy the custom permissions into the array.
         for (uint256 i; i < customSplitOperatorPermissionIndexes.length;) {
-            allOperatorPermissions[9 + i] = customSplitOperatorPermissionIndexes[i];
+            allOperatorPermissions[10 + i] = customSplitOperatorPermissionIndexes[i];
             unchecked {
                 ++i;
             }
@@ -833,6 +834,7 @@ contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
         // 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.
+        // slither-disable-next-line reentrancy-events
         _setCashOutDelayIfNeeded({revnetId: revnetId, firstStageConfig: configuration.stageConfigurations[0]});
 
         // Deploy the revnet's ERC-20 token.