@rev-net/core-v6 0.0.32 → 0.0.33

package/README.md

@@ -1,13 +1,18 @@
 # Revnet Core
 
-`@rev-net/core-v6` deploys and operates Revnets: autonomous Juicebox projects 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, and token-collateralized loans.
 
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-A Revnet is meant to run without a human owner after launch. Its economics are encoded up front as a sequence of stages, and the runtime hook plus loan system enforce those rules over time.
+A Revnet is meant to minimize human administration after launch. Its economics are encoded up front as a sequence of stages, and the runtime hook plus loan system enforce those rules over time.
 
 This package provides:
 
@@ -17,9 +22,9 @@ This package provides:
 
 It also composes with the 721 hook stack, buyback hook, router terminal, Croptop, and suckers where needed.
 
-Use this repo when the product is an autonomous treasury-backed network with encoded stage transitions. Do not use it when governance, mutable operator control, or simple project deployment is the goal.
+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.
+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.
 
 ## Key Contracts
 
@@ -71,6 +76,14 @@ The shortest useful reading order is:
 
 Do not audit those contracts in isolation if the deployment enables cross-package features; the composed network is the real product.
 
+## High-Signal Tests
+
+1. `test/REVLifecycle.t.sol`
+2. `test/REVLoans.invariants.t.sol`
+3. `test/TestLongTailEconomics.t.sol`
+4. `test/fork/TestLoanBorrowFork.t.sol`
+5. `test/audit/CodexPhantomSurplusTerminal.t.sol`
+
 ## Install
 
 ```bash
@@ -94,7 +107,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Revnet deployment assumes the core protocol, 721 hook, buyback hook, router terminal, suckers, and Croptop packages are available. Every Revnet is intentionally unowned after deployment in the human sense; the deployer contract itself retains the project NFT.
+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.
 
 ## Repository Layout
 
@@ -120,3 +133,9 @@ script/
 - 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.
+
+## 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.
+- If a deployment enables buybacks, 721 hooks, or suckers, inspect those sibling repos before making definitive claims.

package/RISKS.md

@@ -28,6 +28,8 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 - **Bonding curve is the sole collateral oracle.** `REVLoans` uses `JBCashOuts.cashOutFrom` to value collateral. There is no external price oracle, no liquidation margin, and no health factor. The borrowable amount equals the cash-out value at the moment of borrowing.
 - **Juicebox core contracts are correct.** `JBController`, `JBMultiTerminal`, `JBTerminalStore`, `JBTokens`, `JBPrices` -- a bug in any of these is a bug in every revnet.
 - **Buyback hook operates correctly.** `BUYBACK_HOOK` handles swap-vs-mint routing. All revnets from the same deployer share one instance. Failure falls back to direct minting (not a revert), so the failure mode is economic inefficiency, not fund loss.
+- **Buyback pool auto-initialization is best-effort, not guaranteed.** `REVDeployer._tryInitializeBuybackPoolFor` silently catches `initializePoolFor(...)` failures. That means a revnet can deploy successfully while the expected default buyback pool is missing, misconfigured, or already initialized differently. Operators must verify pool state after deployment instead of assuming launch implies the buyback pool is ready.
+- **REVOwner expects at most one buyback cash-out hook spec.** In `beforeCashOutRecordedWith`, `REVOwner` keeps only `buybackHookSpecifications[0]` when composing the buyback path with the rev fee hook. If a future buyback hook implementation returns multiple cash-out hook specs, the additional specs are silently dropped.
 - **Suckers are honest bridges.** Suckers get 0% cashout tax in `beforeCashOutRecordedWith`. A compromised or malicious sucker registered in `SUCKER_REGISTRY` can extract funds from any revnet at zero cost.
 - **Auto-issuance beneficiaries are set at deployment.** Beneficiary addresses are baked into the stage configuration. If a beneficiary address is a contract that becomes compromised, or an EOA whose keys are lost, those auto-issuance tokens are either captured or permanently unclaimable.
 - **REVLoans contract address is immutable per deployer.** `LOANS` is set once in the REVDeployer constructor (and shared as an immutable on REVOwner) with wildcard `USE_ALLOWANCE` permission (`projectId=0`). If the loans contract has a vulnerability, every revnet's surplus is exposed.
@@ -93,7 +95,7 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 ### Loan source rotation after deployment
 
 - **Loan sources grow monotonically.** `_loanSourcesOf[revnetId]` is append-only. Each new `(terminal, token)` pair used for borrowing adds an entry. Entries are never removed, even if all loans from that source are repaid. `_totalBorrowedFrom` iterates the entire array on every borrow/repay.
-- **Removed terminals remain as loan sources.** If a terminal is de-registered from `JBDirectory` (via migration), existing loans from that terminal remain valid (the loan struct stores a direct reference to the terminal contract). New borrows against that terminal are blocked by `DIRECTORY.isTerminalOf` check in `borrowFrom`. But `_totalBorrowedFrom` still queries the de-registered terminal's `accountingContextForTokenOf` -- verify this doesn't revert.
+- **Removed terminals remain as loan sources.** If a terminal is de-registered from `JBDirectory` (via migration), existing loans from that terminal remain valid because each loan stores a direct terminal reference. New borrows against that terminal are blocked by the `DIRECTORY.isTerminalOf` check in `borrowFrom`, but `_totalBorrowedFrom` still queries the old terminal's `accountingContextForTokenOf`. On current core terminals that call returns the stored accounting context rather than reverting, so debt accounting continues to depend on that legacy terminal's retained token configuration even after directory migration.
 
 ### `reallocateCollateralFromLoan` sandwich potential
 
@@ -193,6 +195,7 @@ These MUST hold. Breaking any of them is a finding.
 - **Stage progression monotonicity.** `startsAtOrAfter` values strictly increase between stages. The first stage can be 0 (mapped to `block.timestamp`).
 - **Auto-issuance single-claim.** Each `(revnetId, stageId, beneficiary)` can only be claimed once. `amountToAutoIssue` is zeroed BEFORE the external `mintTokensOf` call (CEI pattern).
 - **Split percentages.** Per-stage `splitPercent > 0` requires `splits.length > 0`. Split percentages are validated by `JBSplits` in core (must sum to <= `SPLITS_TOTAL_PERCENT`).
+- **Buyback pool readiness is not implied by successful deployment.** `deployFor` can finish even when `_tryInitializeBuybackPoolFor` failed internally. Post-deploy verification must check the actual buyback pool registration and initialization state rather than inferring success from the absence of a revert.
 
 ### Fee flows
 
@@ -245,3 +248,7 @@ This is accepted because the JBPermissions delegation model is opt-in: a holder
 ### 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.
+
+### 8.7 REVOwner only forwards the first buyback cash-out hook spec
+
+When `REVOwner.beforeCashOutRecordedWith` combines the buyback hook response with its own rev-fee hook spec, it only preserves the first element of `buybackHookSpecifications`. This is accepted because the current buyback-hook design is expected to return at most one cash-out hook spec. The trade-off is forward-compatibility risk: if a future buyback hook starts returning multiple cash-out hook specs, revnets using this owner contract will silently drop the extras unless `REVOwner` is updated too.

package/SKILLS.md

@@ -3,19 +3,20 @@
 ## Use This File For
 
 - Use this file when the task involves revnet deployment, staged issuance, split operator logic, auto-issuance, or the revnet loan system built on top of Juicebox core.
-- Start here, then open the deployer, owner, or loans contract depending on whether the issue is launch-time config, runtime hook behavior, or debt accounting.
+- Start here, then decide whether the issue is really in `REVDeployer` deployment shape, `REVOwner` runtime-hook behavior, or `REVLoans` debt accounting. Most confusion in this repo comes from mixing those three roles.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and operator flow | [`README.md`](./README.md) |
+| Repo overview and operator flow | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | 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) |
+| Runtime owner and data-hook behavior | [`src/REVOwner.sol`](./src/REVOwner.sol), [`references/runtime.md`](./references/runtime.md) |
 | 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/) |
+| Lifecycle, loans, and economic proofs | [`test/REVLifecycle.t.sol`](./test/REVLifecycle.t.sol), [`test/REVLoansRegressions.t.sol`](./test/REVLoansRegressions.t.sol), [`test/REVLoans.invariants.t.sol`](./test/REVLoans.invariants.t.sol), [`test/TestLongTailEconomics.t.sol`](./test/TestLongTailEconomics.t.sol) |
+| Stage, fee, and adversarial edge cases | [`test/TestStageTransitionBorrowable.t.sol`](./test/TestStageTransitionBorrowable.t.sol), [`test/TestSplitWeightE2E.t.sol`](./test/TestSplitWeightE2E.t.sol), [`test/TestLoansCashOutDelay.t.sol`](./test/TestLoansCashOutDelay.t.sol), [`test/REVLoansAttacks.t.sol`](./test/REVLoansAttacks.t.sol), [`test/TestFlashLoanSurplus.t.sol`](./test/TestFlashLoanSurplus.t.sol) |
 
 ## Repo Map
 
@@ -40,5 +41,13 @@ 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, `REVLoans` for collateral and debt accounting, and `REVHiddenTokens` for temporary supply exclusion.
+- Revnets are intentionally ownerless after deployment. Treat any “admin recovery” instinct as suspect unless the code proves it.
+- `REVOwner` is not a minor helper; it is the live ruleset data hook. Cash-out fees, sucker exemptions, buyback composition, and mint permission checks all run through it.
+- `REVOwner.beforePayRecordedWith(...)` intentionally composes 721 split specs before buyback routing and then rescales weight to the amount that actually enters the project. Treat that ordering as an invariant.
+- Loan collateral is burned and re-minted, not escrowed. Any change that assumes escrow semantics is likely wrong.
+- Cash-out delay is enforced in both runtime cash-outs and loan borrowing. If one path changes without the other, the protection is broken.
+- Hidden tokens are supply exclusion, not a side balance. They change redemption economics by reducing visible supply until revealed.
 - Verify any economic assumption in code or tests before relying on it. Revnet docs carry more economic interpretation than most repos.
+- Loan behavior, stage transitions, and split-weight adjustments interact. Do not treat them as independent subsystems when editing economics.
+- Cash-out delay, buyback defaults, and sucker deployment rules all exist to protect cross-chain and launch-time economics. They are not optional configuration sugar.
 - For anything cross-chain or stage-related, check both the deployer path and the reading-state reference before editing.

package/USER_JOURNEYS.md

@@ -1,108 +1,212 @@
 # 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. It does not turn the project back into an ordinary owner-governed treasury after deployment.
+
+## 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.
 
-**Success:** the Revnet launches as a Juicebox project whose deploy-time shape already encodes its economic envelope.
+**Failure Modes**
+- teams assume deploy-time parameters can be revisited casually
+- optional integrations are enabled without auditing their effect on the resulting network
 
-**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.
+**Postconditions**
+- the Revnet launches with its long-lived stage envelope encoded up front
 
 ## Journey 2: Participate In The Revnet Across Stage Transitions
 
-**Starting state:** the Revnet is live and a participant wants to pay in, hold exposure, or cash out later.
+**Actor:** participant.
 
-**Success:** participation follows the current stage's rules without requiring the user to reason about every deploy-time parameter directly.
+**Intent:** buy, hold, and exit Revnet exposure across stage changes.
 
-**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.
+**Preconditions**
+- the Revnet is already live
+- the participant understands active stage parameters can change behavior over time
 
-**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.
+**Main Flow**
+1. Pay through the configured terminal or router.
+2. Let `REVOwner` enforce runtime behavior such as pay handling, delayed exits, and stage-sensitive constraints.
+3. As stages advance, later pays and exits follow the new active parameters while identity stays constant.
+
+**Failure Modes**
+- stage parameters are misread as mutable when they are fixed
+- delayed cash-out behavior is misunderstood
+- optional integrations materially change the participant experience in ways the caller ignored
+
+**Postconditions**
+- the participant's buys and exits now follow the active stage's constraints
 
 ## Journey 3: Claim Stage-Based Auto-Issuance When It Becomes Available
 
-**Starting state:** the Revnet was deployed with auto-issuance allocations for one or more beneficiaries.
+**Actor:** auto-issuance beneficiary.
+
+**Intent:** claim stage-specific issuance only when it is actually live.
+
+**Preconditions**
+- the Revnet was deployed with auto-issuance allocations
+- the target stage has started
 
-**Success:** the beneficiary claims the right amount for the right stage only after that stage is actually live.
+**Main Flow**
+1. Check `amountToAutoIssue(...)`.
+2. Call `autoIssueFor(...)` once the stage is active.
+3. The stored allocation is consumed and cannot be claimed twice.
 
-**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.
+**Failure Modes**
+- callers try to claim before the stage is active
+- reviewers assume auto-issuance is a generic mint path rather than a bounded stage allocation
+
+**Postconditions**
+- the stage allocation is either claimed once or remains reserved until it becomes valid
 
 ## Journey 3a: Hide Tokens To Increase Cash-Out Value For Remaining Holders
 
-**Starting state:** a holder wants to temporarily exclude some tokens from totalSupply without permanently giving them up.
+**Actor:** holder or authorized operator.
+
+**Intent:** remove tokens from visible supply temporarily and later restore them.
+
+**Preconditions**
+- the holder granted the required permissions
+- the holder accepts the supply and collateral implications of hiding tokens
 
-**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.
+**Main Flow**
+1. Grant `BURN_TOKENS` to `REVHiddenTokens`.
+2. Call `hideTokensOf(...)` to burn tokens and track the hidden balance.
+3. The lower visible supply changes per-token cash-out value.
+4. Later call `revealTokensOf(...)` to re-mint hidden tokens.
 
-**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 Modes**
+- more tokens are revealed than were hidden
+- holders forget revealed tokens increase visible supply again
+- hidden tokens are assumed to remain usable as loan collateral
 
-**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.
+**Postconditions**
+- visible supply is reduced or restored according to the holder's hidden-token state
 
 ## Journey 4: Borrow Against Revnet Tokens Instead Of Selling Them
 
-**Starting state:** a holder wants liquidity but does not want to exit the Revnet position.
+**Actor:** holder or delegated loan operator.
 
-**Success:** the holder opens a loan, receives borrowed value, and keeps an NFT loan position representing the debt.
+**Intent:** borrow against Revnet exposure instead of selling it.
 
-**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**
+- the holder has eligible Revnet token exposure
+- the holder trusts any delegated operator with `OPEN_LOAN`
+
+**Main Flow**
+1. Interact with `REVLoans` using eligible token exposure as collateral.
+2. The system burns the collateralized token exposure and mints a loan NFT.
+3. Borrowed value is issued under live Revnet economics.
+4. The borrower can later repay, reallocate, transfer, or face liquidation.
+
+**Failure Modes**
+- delegated operators redirect value in ways the holder did not intend
+- reviewers model the loan system as escrowed collateral when it is burned-collateral lending
+
+**Postconditions**
+- collateralized exposure is transformed into a live loan position under Revnet economics
 
 ## Journey 5: Repay, Transfer, Or Liquidate A Loan Position
 
-**Starting state:** a loan already exists and either the borrower or another actor needs to change its state.
+**Actor:** borrower, loan owner, or liquidator.
+
+**Intent:** change or settle an existing loan position.
 
-**Success:** the debt path settles cleanly and the collateral outcome matches the Revnet's current rules.
+**Preconditions**
+- a loan already exists
+- the actor has the rights or economic incentives required for the chosen path
 
-**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.
+**Main Flow**
+1. Repay to burn debt and restore the collateralized exposure.
+2. Transfer the loan NFT if ownership of the debt position should move.
+3. Liquidate if the encoded conditions permit it.
 
-**Edge conditions that change user experience:** cross-ruleset loan behavior, zero-amount or zero-price edge cases, and sourced versus unsourced loan paths.
+**Failure Modes**
+- cross-ruleset behavior is misread
+- zero-value or sourced-versus-unsourced paths are handled incorrectly by integrations
+
+**Postconditions**
+- the loan position is repaid, transferred, or liquidated according to the chosen path
 
 ## 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
 
-**Success:** the operator can use sanctioned controls without escaping the "autonomous after launch" model.
+**Main Flow**
+1. Review what `REVDeployer` allowed.
+2. Use only those sanctioned surfaces.
+3. Audit cross-package behavior whenever optional integrations are enabled.
 
-**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.
+**Failure Modes**
+- operators behave as though the Revnet were a normal owner-governed project
+- reviewers inspect controls in isolation and miss integrated runtime behavior
+
+**Postconditions**
+- post-launch control remains inside the bounded envelope the deployment left available
 
 ## Journey 7: Receive Cross-Chain Payments With Correct Hook Routing
 
-**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.
+**Actor:** remote participant or integrator using suckers.
+
+**Intent:** preserve the real beneficiary during cross-chain payments into a Revnet.
 
-**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.
+**Preconditions**
+- the Revnet is configured with suckers and optional hooks that depend on the beneficiary
+- relay-beneficiary metadata is provided correctly
 
-**Flow**
+**Main 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.
+2. `REVOwner.beforePayRecordedWith()` resolves the real beneficiary when the payer is a registered sucker.
+3. Downstream hooks observe the remote user rather than the sucker contract.
+
+**Failure Modes**
+- relay metadata is absent or malformed
+- downstream hooks accidentally attribute minting or routing to the sucker instead of the user
+
+**Postconditions**
+- cross-chain payments preserve the intended remote beneficiary through the Revnet hook stack
+
+## Trust Boundaries
+
+- `REVDeployer` is trusted for the launch-time envelope the Revnet will live inside
+- `REVOwner` is economically binding runtime logic, not advisory middleware
+- optional integrations such as 721 hooks, buybacks, router terminals, and suckers materially alter the resulting network
 
 ## Hand-Offs
 

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.33",
+  "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,9 @@ 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(holder, revnetId, tokenCount)` | Holder or delegated permission | Burns visible tokens, increases hidden balance, and lowers visible supply. |
+| `REVHiddenTokens.revealTokensOf(holder, revnetId, tokenCount, beneficiary)` | Holder or delegated permission | Re-mints previously hidden tokens to a beneficiary and reduces hidden balance. |

package/src/structs/REV721TiersHookFlags.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// @custom:member noNewTiersWithOwnerMinting A flag indicating if new tiers with owner minting are forbidden.
 /// @custom:member preventOverspending A flag indicating if payments exceeding the price of minted NFTs should be
 /// prevented.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REV721TiersHookFlags {
     bool noNewTiersWithReserves;
     bool noNewTiersWithVotes;

package/src/structs/REVAutoIssuance.sol

@@ -4,7 +4,6 @@ pragma solidity ^0.8.0;
 /// @custom:member chainId The ID of the chain on which the mint should be honored.
 /// @custom:member count The number of tokens that should be minted.
 /// @custom:member beneficiary The address that will receive the minted tokens.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVAutoIssuance {
     uint32 chainId;
     uint104 count;

package/src/structs/REVBaseline721HookConfig.sol

@@ -14,7 +14,6 @@ import {REV721TiersHookFlags} from "./REV721TiersHookFlags.sol";
 /// @custom:member tiersConfig The tier configuration for the NFT collection.
 /// @custom:member flags A set of flags that configure the 721 hook. Omits `issueTokensForSplits` since revnets
 /// always force it to `false`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVBaseline721HookConfig {
     string name;
     string symbol;

package/src/structs/REVConfig.sol

@@ -9,7 +9,6 @@ import {REVStageConfig} from "./REVStageConfig.sol";
 /// @custom:member splitOperator The address that will receive the token premint and initial production split,
 /// and who is allowed to change who the operator is. Only the operator can replace itself after deployment.
 /// @custom:member stageConfigurations The periods of changing constraints.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVConfig {
     REVDescription description;
     uint32 baseCurrency;

package/src/structs/REVCroptopAllowedPost.sol

@@ -10,7 +10,6 @@ pragma solidity ^0.8.0;
 /// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) that a
 /// poster can set. 0 means splits are not allowed.
 /// @custom:member allowedAddresses A list of addresses that are allowed to post on the category through Croptop.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVCroptopAllowedPost {
     uint24 category;
     uint104 minimumPrice;

package/src/structs/REVDeploy721TiersHookConfig.sol

@@ -13,7 +13,6 @@ import {REVBaseline721HookConfig} from "./REVBaseline721HookConfig.sol";
 /// minting 721's from tiers that allow it.
 /// @custom:member preventSplitOperatorIncreasingDiscountPercent A flag indicating if the revnet's split operator should
 /// be prevented from increasing the discount of a tier.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVDeploy721TiersHookConfig {
     REVBaseline721HookConfig baseline721HookConfiguration;
     bytes32 salt;

package/src/structs/REVDescription.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// @custom:member uri The metadata URI containing revnet's info.
 /// @custom:member salt Revnets deployed across chains by the same address with the same salt will have the same
 /// address.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct REVDescription {
     string name;
     string ticker;