@rev-net/core-v6 0.0.33 → 0.0.35

package/ADMINISTRATION.md

@@ -4,83 +4,70 @@
 
 | Item | Details |
 | --- | --- |
-| Scope | Revnet deployment shape, split-operator runtime authority, and cosmetic `REVLoans` ownership |
-| Control posture | Mostly immutable economics with a narrow runtime operator |
-| Highest-risk actions | Deploying the wrong stage design, assigning the wrong split operator, and overestimating `REVLoans` owner power |
-| Recovery posture | Core economic mistakes require new revnets; some optional integrations can be corrected by the split operator |
+| Scope | Revnet deployment shape, bounded runtime operators, loan-owner cosmetics, and optional integration control surfaces |
+| Control posture | Intentionally narrow and mostly deployment-defined |
+| Highest-risk actions | Bad stage design, wrong split-operator assignment, and misunderstanding which runtime surfaces stay live after launch |
+| Recovery posture | Usually replacement, not patching; the design intentionally avoids easy admin escape hatches |
 
 ## Purpose
 
-`revnet-core-v6` is designed to minimize ongoing human control. The core split is between deployment-time shape, the limited split-operator role, the globally owned-but-cosmetic `REVLoans` metadata surface, and the intentionally ownerless project pattern enforced through `REVDeployer` and `REVOwner`.
+`revnet-core-v6` is designed to collapse ordinary post-launch governance into deployment-time decisions plus a small set of bounded runtime roles. The main administration task is understanding which power still exists and which power was intentionally removed.
 
 ## Control Model
 
-- Deployment-time configuration is the real place where revnet economics are chosen.
-- The split operator is the only intended human-controlled runtime role for a revnet.
-- `REVLoans` owner only controls loan NFT metadata rendering.
-- `REVDeployer` holds the project NFT structurally, not as a discretionary human admin.
-- Many economically sensitive behaviors are intentionally not mutable after deployment.
+- `REVDeployer` holds the project NFT and therefore remains part of the ownership model.
+- Revnet economics are mainly fixed at deployment through staged rulesets.
+- `REVOwner` provides live runtime policy, but not broad human governance.
+- Split operators can hold narrow powers depending on stage and deployment config.
+- `REVLoans` has a cosmetic global owner surface, but loan economics are still bounded by revnet logic.
 
 ## Roles
 
 | Role | How Assigned | Scope | Notes |
 | --- | --- | --- | --- |
-| Split operator | `REVConfig.splitOperator` at deployment | Per revnet | Narrow runtime operator surface |
-| `REVLoans` owner | `Ownable(owner)` on `REVLoans` | Global | Cosmetic metadata role, not economic admin |
-| Loan NFT owner | ERC-721 loan ownership | Per loan | Can repay or reallocate subject to checks |
-| Hidden-token caller or delegate | Holder or delegated permission | Per holder | Manages hide and reveal flows |
-| Anyone | No assignment | Global or per revnet | Some lifecycle functions are permissionless |
+| `REVDeployer` | Deployed singleton | Global launcher and project-NFT holder | Part of the ownership model |
+| Split operator | Deployment config | Per revnet | Holds only the allowed operator envelope |
+| Auto-issuance beneficiary | Deployment config | Per stage | Can receive preconfigured stage issuance |
+| Borrower or delegated loan operator | Token holder plus permission | Per holder or loan | Can open or manage loans within loan rules |
+| `REVLoans` owner | Constructor owner | Global cosmetic/admin surface | Does not turn Revnets back into ordinary governed projects |
 
 ## Privileged Surfaces
 
-| Contract | Function | Who Can Call | Effect |
-| --- | --- | --- | --- |
-| `REVDeployer` | `deployFor(...)` | Anyone for new deployments, or current owner for conversion path | Creates or converts a project into a revnet |
-| `REVDeployer` | `deploySuckersFor(...)` | Split operator | Adds sucker infra where the revnet config allows it |
-| `REVDeployer` | `setSplitOperatorOf(...)` | Current split operator | Replaces or burns the split-operator role |
-| `REVLoans` | `setTokenUriResolver(...)` | `REVLoans` owner | Cosmetic loan-NFT metadata control |
-| `REVLoans` | `borrowFrom(...)`, `repayLoan(...)`, `reallocateCollateralFromLoan(...)` | Holder or delegated loan operator | Position-level administration, not protocol-level governance |
+- `deployFor(...)` defines the revnet's long-lived shape
+- split-operator paths can manage only the permissions left open by deployment
+- `autoIssueFor(...)` consumes preconfigured stage issuance
+- loan operators can redirect borrowed value if a holder delegates loan permissions
+- hidden-token flows require the holder's permission grant and mint permission wiring through `REVOwner`
 
 ## Immutable And One-Way
 
-- Stage schedule and core economics are chosen at deployment and then fixed.
-- Converting an existing project into a revnet is effectively irreversible.
-- Burning the split-operator role to `address(0)` is final.
-- `REVDeployer` structurally retains project-NFT ownership in the design.
-- Expired loans can eventually liquidate into permanently lost collateral if they are not repaid within the long liquidation window.
+- Stage configuration is effectively permanent after deployment.
+- The deployer-held project NFT is not a normal owner-recovery tool.
+- Loan collateral is burned at borrow time and only reminted through repayment or documented flows.
+- Hidden-token balances change visible supply until reveal.
 
 ## Operational Notes
 
-- Use the split operator only for the intentionally narrow surfaces left mutable.
-- Treat buyback, router, sucker, and optional 721 adjustments as operational extensions around a fixed economic core.
-- Keep `REVLoans` owner power limited to URI resolver maintenance.
-- Treat loan operations as position management with real long-tail irreversibility; after the liquidation duration expires, collateral recovery is no longer available.
+- Treat revnet launch as the real governance decision.
+- Validate stage timing, split-operator scope, and optional integrations before deployment.
+- Review cash-out delay, hidden-token semantics, and loan permissions together.
+- Do not assume there is a broad admin override for bad economics after launch.
 
 ## Machine Notes
 
-- Do not infer broad control from `REVDeployer` holding the project NFT; the design is intentionally constrained.
-- Treat `src/REVDeployer.sol`, `src/REVOwner.sol`, and `src/REVLoans.sol` together when crawling authority.
-- If stage config or split-operator assumptions differ from deployed state, stop; those are foundational revnet assumptions, not cosmetic metadata.
+- Do not describe Revnets as fully adminless if the deployer-held NFT still matters for the trust model.
+- Also do not describe them as ordinary owner-controlled projects. The point is that the available control surface is intentionally narrow.
+- If a question is about runtime cash-outs, buybacks, or mint permissions, inspect `REVOwner` before inferring behavior from deployment prose.
 
 ## Recovery
 
-- Wrong stage design is not realistically recoverable in place; deploy a new revnet.
-- Wrong optional integration can sometimes be corrected if the split operator still has the required scoped power.
-- There is no broad admin escape hatch that can rewrite revnet economics after launch.
-- Liquidated loan collateral is not an admin-recoverable asset; recovery must happen before liquidation through borrower action.
+- If launch-time economics are wrong, recovery usually means replacement, not in-place repair.
+- If optional integrations are misconfigured, fix only where the code still exposes a valid path.
+- If the design intentionally omitted a recovery path, do not invent one in documentation or ops guidance.
 
 ## Admin Boundaries
 
-- The split operator cannot rewrite issuance schedule, cash-out tax, or stage timing.
-- `REVLoans` owner cannot redirect collateral or treasury funds.
-- `REVDeployer` cannot act like a normal human owner despite holding the project NFT.
-- Nobody can change the revnet's fundamental staged design after deployment.
-- Nobody can administratively restore collateral after an expired loan has been liquidated.
-
-## Source Map
-
-- `src/REVDeployer.sol`
-- `src/REVOwner.sol`
-- `src/REVLoans.sol`
-- `src/REVHiddenTokens.sol`
-- `test/`
+- No ordinary owner can casually rewrite staged economics after launch.
+- Split operators are not general-purpose governors.
+- Loan mechanics, hidden-token mechanics, and cash-out policy remain bounded by the deployed revnet logic.
+- This repo should not be documented as if it had a normal mutable project-owner model.

package/ARCHITECTURE.md

@@ -6,16 +6,16 @@
 
 ## System Overview
 
-`REVDeployer` handles launch-time shape, staged rulesets, hook wiring, and runtime wrapper behavior. `REVOwner` provides the owner-like runtime policy surface for pay and cash-out hooks after launch. `REVLoans` manages burn-collateral loan positions represented as ERC-721 loans. `REVHiddenTokens` lets holders burn tokens to exclude them from total supply until they reveal them again.
+`REVDeployer` handles launch-time shape, staged rulesets, hook wiring, and runtime wrapper behavior. `REVOwner` provides the owner-like runtime policy surface for pay and cash-out hooks after launch. `REVLoans` manages burn-collateral loan positions represented as NFTs. `REVHiddenTokens` lets holders burn tokens to exclude them from visible supply until they reveal them again.
 
 ## Core Invariants
 
 - Revnets are intended to be ownerless after deployment; easy admin recovery paths would violate the product model.
 - Stage configuration is effectively permanent once queued.
-- Loan collateral is burned, not escrowed, and supply-sensitive logic must treat it as real destruction until repayment.
-- Hidden tokens are burned, not escrowed, and reduce total supply until revealed.
+- Loan collateral is burned, not escrowed.
+- Hidden tokens are burned, not escrowed, and reduce visible supply until revealed.
 - `REVOwner` and `REVDeployer` are tightly coupled; their setup order matters.
-- Cash-out delay affects both exits and borrowing power. If the current stage delays cash out, `REVLoans` should treat borrowability as zero until that delay expires.
+- Cash-out delay affects both exits and borrowing power.
 - Cross-chain supply and surplus are part of revnet economics. Local payouts and loans must not ignore remote sucker snapshots.
 
 ## Modules
@@ -62,17 +62,17 @@ borrower
 
 ## Accounting Model
 
-The repo does not replace core treasury accounting. Its critical economic logic is the interaction between staged revnet configuration, burned-collateral loan state, hidden-token supply exclusion, and omnichain revnet state imported from suckers.
+The repo does not replace core treasury accounting. Its critical economic logic is the interaction between staged revnet config, burned-collateral loan state, hidden-token supply exclusion, and omnichain revnet state imported from suckers.
 
-`REVOwner` also composes payment and cash-out hooks. On pay, it merges 721-tier split forwarding with buyback-hook behavior and scales mint weight so the terminal only mints against the share actually entering the project. On cash out, it uses omnichain supply and surplus for reclaim math, exempts trusted suckers from tax and fee routing, and may append a fee hook spec that forwards rev fees to the fee revnet.
+`REVOwner` also composes payment and cash-out hooks. On pay, it can merge 721-tier split forwarding with buyback-hook behavior and scale mint weight so the terminal only mints against the share that actually enters the project. On cash out, it can use omnichain supply and surplus for reclaim math, exempt trusted suckers, and append fee-hook specs.
 
 ## Security Model
 
 - The highest-risk interactions sit where stage economics, treasury state, and loan borrowability meet.
-- Ownerlessness removes convenient operational recovery from misconfiguration.
+- Ownerlessness removes convenient recovery from misconfiguration.
 - Hidden-token and burned-collateral semantics materially affect supply-sensitive pricing.
-- `REVOwner` is a live runtime policy surface, not just a launch helper. Cash-out delay, buyback composition, sucker exemptions, and fee routing all pass through it.
-- Rev cash-out fees stack on top of protocol-fee behavior rather than replacing it. Fee semantics should be reviewed with terminal behavior, not in isolation.
+- `REVOwner` is a live runtime policy surface, not just a launch helper.
+- Rev cash-out fees stack on top of protocol-fee behavior rather than replacing it.
 
 ## Safe Change Guide
 
@@ -80,8 +80,19 @@ The repo does not replace core treasury accounting. Its critical economic logic
 - If stage semantics change, inspect loan math, cash-out behavior, and downstream fee expectations together.
 - Do not casually add mutable admin escape hatches.
 - If you change borrowability, re-check cash-out-delay gating, omnichain surplus inputs, and local-surplus caps together.
-- If you change hook composition, re-check 721 split handling, buyback hook assumptions, and which callers retain mint permission through `REVOwner`.
-- If loan calculations change, review flash-loan and surplus-sensitive behavior adversarially.
+- If you change hook composition, re-check 721 split handling, buyback assumptions, and mint-permission flows.
+
+## Cross-Chain Configuration Hash
+
+`REVDeployer` produces an `encodedConfigurationHash` for each revnet that determines sucker deployment salts. This hash commits the revnet's identity across chains. It includes:
+
+- `baseCurrency`, `description.name`, `description.ticker`, `description.salt`
+- Terminal addresses (order-sensitive)
+- Stage parameters (timing, issuance, splits, tax rates, auto-issuances)
+
+Terminal addresses are included because they are deployed deterministically at the same address across chains. Accounting contexts (token addresses) are excluded because tokens like USDC legitimately differ per chain.
+
+This means a revnet can only expand to a new chain if it uses the exact same terminal contract it used on the host chain. Different terminal addresses produce a different hash, preventing accidental cross-chain mismatches in sucker deployments.
 
 ## Canonical Checks
 
@@ -91,6 +102,8 @@ The repo does not replace core treasury accounting. Its critical economic logic
   `test/TestStageTransitionBorrowable.t.sol`
 - omnichain or phantom-surplus edge cases:
   `test/audit/CodexPhantomSurplusTerminal.t.sol`
+- terminal encoding in configuration hash:
+  `test/TestTerminalEncodingInHash.t.sol`
 
 ## Source Map
 

package/AUDIT_INSTRUCTIONS.md

@@ -1,124 +1,87 @@
 # Audit Instructions
 
-Revnets are autonomous Juicebox projects with staged economics and token-collateralized loans. Audit this repo as both a privileged deployer layer and a live economic system.
+Revnet is a staged, owner-minimized product layer on top of Juicebox core. Audit it as an economic system, not just a deployer plus a loan contract.
 
 ## Audit Objective
 
 Find issues that:
-- let a participant borrow more than intended against revnet collateral
-- break stage transitions or immutable revnet economics
-- mis-scale weights, fees, or split behavior in composed payment flows
-- grant owner-like or operator-like powers outside the documented model
-- leave deployed revnets or loans in states that cannot settle safely
+
+- break stage progression or let users act under the wrong stage assumptions
+- overstate or understate borrowability
+- mis-handle hidden tokens or burned-collateral accounting
+- give operators or integrations more power than the revnet model intends
+- make omnichain supply, surplus, or sucker assumptions drift from runtime behavior
 
 ## Scope
 
 In scope:
+
 - `src/REVDeployer.sol`
 - `src/REVOwner.sol`
 - `src/REVLoans.sol`
 - `src/REVHiddenTokens.sol`
-- `src/interfaces/`
-- `src/structs/`
-- deployment scripts in `script/`
-
-Key dependencies:
-- `nana-core-v6`
-- `nana-721-hook-v6`
-- `nana-buyback-hook-v6`
-- `nana-suckers-v6`
-- `croptop-core-v6`
+- structs, interfaces, and deployment helpers
 
 ## Start Here
 
-Read in this order:
-- `REVOwner`
-- `REVDeployer`
-- `REVLoans`
-
-`REVOwner` is the fastest way to understand how a live revnet differs from plain Juicebox behavior.
-`REVDeployer` explains why that behavior exists.
-`REVLoans` is where those economics are turned into extractable collateral value.
+1. `src/REVDeployer.sol`
+2. `src/REVOwner.sol`
+3. `src/REVLoans.sol`
+4. `src/REVHiddenTokens.sol`
 
 ## Security Model
 
-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
+Revnet composes several sensitive systems:
+
+- staged rulesets and launch-time immutability
+- runtime pay and cash-out policy in `REVOwner`
+- burned-collateral lending in `REVLoans`
+- hidden-token supply exclusion in `REVHiddenTokens`
 
-Important composition behavior:
-- revnet payments may be proxied through 721 and buyback hooks
-- cash-out behavior may be altered for suckers or by revnet-specific fee handling
-- loan health depends on bonding-curve value and surplus, so core accounting and stage timing directly matter
+The main audit mindset is composition:
 
-Two mental models help here:
-- `REVDeployer` is mostly a launch-time authority that permanently shapes economics
-- `REVOwner` is a runtime hook that can make a launched revnet behave very differently from a plain Juicebox project
+- stage economics affect borrowability
+- hidden supply affects cash-out math
+- omnichain state can affect reclaim and borrowing power
+- optional integrations can widen the effective trust surface
 
 ## Roles And Privileges
 
 | Role | Powers | How constrained |
 |------|--------|-----------------|
-| Revnet launcher | Set the stage schedule and optional compositions | Must not retain hidden runtime privilege |
-| `REVOwner` | Alter payment and cash-out behavior at runtime | Must remain narrowly scoped to documented economics |
-| Borrower or operator | Open, repay, reallocate, hide, or reveal with delegated permissions | Must not redirect collateral or proceeds away from the holder |
+| Revnet deployer path | Define long-lived stage and operator shape | Must not retain unexpected mutable governance |
+| Split operator | Use the allowed runtime envelope | Must stay within deployment-defined permissions |
+| Borrower or delegated operator | Open or manage loans | Must not escape collateral, delay, or source limits |
+| Hidden-token user or delegate | Burn and reveal visible supply | Must not create extra supply or break accounting |
 
 ## Integration Assumptions
 
 | Dependency | Assumption | What breaks if wrong |
 |------------|------------|----------------------|
-| `nana-core-v6` | Surplus and issuance accounting remain coherent | Borrow limits and stage economics become unsound |
-| `nana-721-hook-v6` and `nana-buyback-hook-v6` | Optional composition does not distort accounting unexpectedly | Runtime economics diverge from the stage design |
-| `nana-suckers-v6` | Omnichain privilege surfaces identify real suckers only | Fee-free or mint exemptions widen |
+| `nana-core-v6` | Rulesets, reclaim math, and surplus views stay coherent | Stage and cash-out behavior drift |
+| `nana-suckers-v6` | Remote supply/surplus snapshots are authentic | Omnichain reclaim and borrowability drift |
+| Buyback and 721 integrations | Hook composition remains consistent with revnet expectations | Pay-path and mint-permission behavior drift |
 
 ## Critical Invariants
 
-1. Stage immutability
-Once a revnet is launched, future stage economics must follow the encoded schedule and not become mutable through helper paths.
-
-2. Payment accounting is scaled correctly
-If only part of a payment enters the treasury because of split or hook routing, token issuance must reflect only that treasury-entering portion.
-
-3. Loan collateralization is sound
-Borrow, repay, refinance, and liquidation paths must never let a borrower extract more value than the design permits.
-
-4. Hook privilege stays narrow
-`REVOwner` and deployer-only setters must not be callable by arbitrary actors or stale deployment helpers.
-
-5. Sucker and operator exemptions are precise
-Fee-free or mint-enabled paths meant for registered omnichain components must not be reusable by arbitrary callers.
-
-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. 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.
+1. Stage progression stays monotonic and follows deployed timing.
+2. Borrowability respects cash-out delay, surplus, supply, and source limits.
+3. Burned collateral is not accidentally treated like escrowed collateral.
+4. Hidden-token accounting preserves total claims while changing visible supply intentionally.
+5. Optional integrations do not silently widen revnet authority or mint rights.
 
 ## Attack Surfaces
 
-- `REVOwner.beforePayRecordedWith`
-- `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
-
-Replay these sequences:
-1. pay into a revnet with 721 and buyback composition enabled and inspect weight scaling
-2. borrow near a stage boundary, then repay, refinance, or liquidate in the next stage
-3. borrow after surplus inflation, then contract surplus before liquidation
-4. cash out through a legitimate sucker path versus a near-sucker spoof path
-5. hide tokens, let another actor cash out, then reveal
+- stage-transition boundaries
+- live borrowability and cross-currency debt aggregation
+- hidden-token burn and reveal flows
+- omnichain surplus and sucker exemptions
+- payment and cash-out hook composition in `REVOwner`
 
 ## Accepted Risks Or Behaviors
 
-- Composition is the default audit target here, not an edge case.
+- Revnets intentionally trade recoverability for predictable launch-time economics.
+- Some economic surfaces are conservative by design and may refuse otherwise-valid actions rather than risk an unsafe result.
 
 ## Verification
 

package/CHANGELOG.md

@@ -26,12 +26,12 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 ## 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`
+  - `HIDE_TOKENS` (35) — lets an authorized operator allow or disallow holders to hide their own tokens via `REVHiddenTokens`
   - `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.
+  - `REVEAL_TOKENS` (39) — legacy permission id; hidden-token reveal no longer depends on it
+- `REVHiddenTokens` now inherits `JBPermissioned` and accepts a `holder` parameter on `hideTokensOf` and `revealTokensOf`. Hiding is available to an operator-managed holder allowlist, and also to the project owner or any operator with `HIDE_TOKENS`. Revealing is holder-only and does not require special permission.
 - `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.
@@ -41,6 +41,7 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 
 - `IREVHiddenTokens.hideTokensOf` signature changed: added `address holder` parameter
 - `IREVHiddenTokens.revealTokensOf` signature changed: added `address holder` parameter
+- `IREVHiddenTokens.setTokenHidingAllowedFor` added for operator-managed holder allowlisting
 - `IREVHiddenTokens.HideTokens` event: added `address holder` field
 - `IREVHiddenTokens.RevealTokens` event: added `address holder` field
 - `IREVLoans.borrowFrom` signature changed: added `address holder` as last parameter

package/README.md

@@ -1,6 +1,6 @@
 # Revnet Core
 
-`@rev-net/core-v6` deploys and operates Revnets: Juicebox project shapes with staged economics, optional tiered NFTs, cross-chain support, buyback integration, and token-collateralized loans.
+`@rev-net/core-v6` deploys and operates Revnets: Juicebox project shapes with staged economics, optional tiered NFTs, cross-chain support, buyback integration, hidden-token mechanics, and token-collateralized loans.
 
 Docs: <https://docs.juicebox.money>
 Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
@@ -18,13 +18,12 @@ This package provides:
 
 - a deployer that launches Revnets and stores their long-lived configuration
 - a runtime hook that mediates pay, cash-out, mint-permission, and delayed-cash-out behavior
-- an ERC-721 loan system that burns token collateral on borrow and remints on repayment
+- a loan system that burns token collateral on borrow and remints on repayment
+- a hidden-token system that temporarily removes tokens from visible supply
 
 It also composes with the 721 hook stack, buyback hook, router terminal, Croptop, and suckers where needed.
 
-Use this repo when the product is a treasury-backed network with encoded stage transitions and a tightly constrained post-launch admin surface. Do not use it when governance, mutable operator control, or simple project deployment is the goal.
-
-The key point is that a Revnet is not just "a Juicebox project with presets." It is a project shape whose admin surface is intentionally collapsed into deployment-time configuration plus constrained runtime operators, even though the deployer contract still retains the project NFT.
+Use this repo when the product is a treasury-backed network with encoded stage transitions and a tightly constrained post-launch admin surface. Do not use it when the goal is ordinary governance or a simple project deploy.
 
 ## Key Contracts
 
@@ -33,48 +32,38 @@ 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. |
+| `REVHiddenTokens` | Lets token holders temporarily hide tokens, excluding them from visible supply until reveal. |
 
 ## Mental Model
 
 Read the package in two halves:
 
 1. deployment-time shape: `REVDeployer` decides what the network will be allowed to do
-2. runtime enforcement: `REVOwner` and `REVLoans` decide how that shape behaves over time
-
-That split matters because most mistakes are one of these:
-
-- assuming a deploy-time parameter can be changed later
-- assuming a runtime hook is only advisory rather than economically binding
+2. runtime enforcement: `REVOwner`, `REVLoans`, and `REVHiddenTokens` decide how that shape behaves over time
 
-The shortest useful reading order is:
-
-1. `REVDeployer`
-2. `REVOwner`
-3. `REVLoans`
-4. any integrated hook or bridge repo the deployment enables
+Most mistakes come from assuming a deploy-time parameter can be changed later or that a runtime hook is only advisory.
 
 ## Read These Files First
 
 1. `src/REVDeployer.sol`
 2. `src/REVOwner.sol`
 3. `src/REVLoans.sol`
-4. the integrated hook or bridge repo used by the deployment
+4. `src/REVHiddenTokens.sol`
+5. the integrated hook or bridge repo used by the deployment
 
 ## Integration Traps
 
-- the deployer holding the project NFT is not an implementation detail; it is part of the ownership model
+- the deployer holding the project NFT is part of the ownership model, not an implementation detail
 - split operators are constrained, not equivalent to general protocol governance
-- the loan system depends on live revnet economics, so it should be reviewed together with the runtime hook and treasury assumptions
-- optional integrations like buybacks, 721 hooks, and suckers are compositional, but they materially change the resulting network
+- the loan system depends on live revnet economics and should be reviewed together with the runtime hook
+- optional integrations like buybacks, 721 hooks, and suckers materially change the resulting network
 
 ## Where State Lives
 
 - deployment-time configuration and operator envelope live in `REVDeployer`
 - runtime pay and cash-out behavior live in `REVOwner`
 - loan positions and loan-specific state live in `REVLoans`
-
-Do not audit those contracts in isolation if the deployment enables cross-package features; the composed network is the real product.
+- hidden-token state lives in `REVHiddenTokens`
 
 ## High-Signal Tests
 
@@ -107,7 +96,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Revnet deployment assumes the core protocol, 721 hook, buyback hook, router terminal, suckers, and Croptop packages are available. Revnets are intentionally unowned in the direct human-EOA sense after deployment, but the deployer contract itself retains the project NFT and remains part of the ownership model.
+Revnet deployment assumes the core protocol, 721 hook, buyback hook, router terminal, suckers, and Croptop packages are available. Revnets are intentionally unowned in the direct human sense after deployment, but the deployer contract itself remains part of the ownership model.
 
 ## Repository Layout
 
@@ -116,6 +105,7 @@ src/
   REVDeployer.sol
   REVOwner.sol
   REVLoans.sol
+  REVHiddenTokens.sol
   interfaces/
   structs/
 test/
@@ -128,14 +118,12 @@ script/
 ## Risks And Notes
 
 - Revnets are intentionally hard to change after launch, so bad stage design is expensive
-- `REVLoans` relies on live treasury conditions and is therefore sensitive to surplus and pricing assumptions
-- the deployer and runtime hook have a tight relationship that should be treated as one design, not two independent contracts
-- burned-collateral lending is operationally different from escrowed-collateral lending and needs clear integrator expectations
-
-The usual review failure mode is to focus on the loans or the stages in isolation. The real system is the combination of stage economics, runtime hook behavior, and who is still allowed to act after deployment.
+- `REVLoans` relies on live treasury conditions and is sensitive to surplus and pricing assumptions
+- the deployer and runtime hook should be treated as one design, not two separate systems
+- burned-collateral lending is operationally different from escrowed-collateral lending
 
 ## For AI Agents
 
-- Describe Revnets as treasury-backed Juicebox project shapes with encoded stage transitions, not as simple deploy presets.
-- Read `REVDeployer`, `REVOwner`, and `REVLoans` together before answering economic or admin-surface questions.
+- Describe Revnets as treasury-backed Juicebox project shapes with encoded stage transitions, not as simple presets.
+- Read `REVDeployer`, `REVOwner`, `REVLoans`, and `REVHiddenTokens` together before answering economic or admin-surface questions.
 - If a deployment enables buybacks, 721 hooks, or suckers, inspect those sibling repos before making definitive claims.