@rev-net/core-v6 0.0.31 → 0.0.33

package/ADMINISTRATION.md

@@ -1,237 +1,86 @@
 # Administration
 
-Admin privileges and their scope in revnet-core-v6. Revnets are designed to be autonomous Juicebox projects with no traditional owner. This document covers what privileged operations exist, who can perform them, and -- critically -- what is intentionally made impossible.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| 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. |
-
-## Routine Operations
+| --- | --- |
+| 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 |
 
-- Use the split operator only for the limited post-launch surfaces the protocol deliberately leaves mutable: reserved-token split routing, selected hook metadata, router selection, and related operator-scoped settings.
-- Keep `REVLoans` owner actions limited to URI resolver maintenance; that role should never be treated as an economic admin.
-- Treat `deploySuckersFor`, buyback configuration, and router-terminal changes as operational extensions around a fixed revnet, not as tools to rewrite the revnet's stage economics.
-- If autonomy is the goal, consider relinquishing the split operator to `address(0)` only after all intended mutable integrations are finalized.
+## Purpose
 
-## One-Way Or High-Risk Actions
+`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`.
 
-- Deploying a revnet or converting an existing project into one is irreversible from an ownership and stage-design perspective.
-- Setting the split operator to `address(0)` permanently burns the human-controlled role.
-- Stage schedules, issuance curves, cash-out tax rates, and core economic parameters are fixed at deployment.
+## Control Model
 
-## Recovery Notes
-
-- There is no admin escape hatch for broken revnet stage design. The recovery path is a new revnet deployment with corrected parameters.
-- If an auxiliary integration such as a buyback hook or sucker is wrong but the split operator still has the relevant scoped power, fix that integration without expecting to change the underlying revnet economics.
+- 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.
 
 ## Roles
 
-### Split Operator
-
-- **How assigned:** Specified at deployment via `REVConfig.splitOperator`. After deployment, only the current split operator can transfer the role to a new address by calling `setSplitOperatorOf()`.
-- **Scope:** Per-revnet. Each revnet has at most one split operator. The operator is the only human-controlled role in a deployed revnet.
-- **Can be permanently relinquished:** The split operator can transfer the role to `address(0)` via `setSplitOperatorOf()`, which permanently relinquishes operator powers. Permissions are granted to the zero address (which cannot execute transactions), effectively burning them. This is irreversible.
+| 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 |
 
-### REVLoans Owner (Ownable)
+## Privileged Surfaces
 
-- **How assigned:** Set at `REVLoans` contract deployment via the `owner` constructor parameter. Transferable via OpenZeppelin `Ownable.transferOwnership()`.
-- **Scope:** Global across all revnets using this loans contract. Controls only the loan NFT metadata URI resolver -- has no power over loan parameters, collateral, or funds.
+| 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 |
 
-### REVDeployer (as Juicebox project owner)
+## Immutable And One-Way
 
-- **How assigned:** Automatic. When a revnet is deployed, the `REVDeployer` contract becomes the permanent owner of the Juicebox project NFT. If initializing an existing project, the caller's project NFT is irreversibly transferred to `REVDeployer`.
-- **Scope:** The deployer holds the project NFT and uses its owner authority to enforce revnet rules. It acts as a protocol-level constraint layer, not as a discretionary admin. No human can exercise this ownership.
+- 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.
 
-### Loan NFT Owner
+## Operational Notes
 
-- **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.
+- 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.
 
-### Anyone (Permissionless)
+## Machine Notes
 
-- **Scope:** Several functions are callable by any address with no access control, as documented in the Privileged Functions tables below.
+- 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.
 
-## Privileged Functions
+## Recovery
 
-### REVDeployer
+- 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.
 
-| Function | Required Role | Permission ID | What It Does |
-|----------|--------------|---------------|-------------|
-| `deployFor()` | Anyone (new revnet) or Juicebox project owner (existing project) | None | Deploys a new revnet or irreversibly converts an existing Juicebox project into a revnet. Both variants deploy a tiered ERC-721 hook: the 4-arg variant deploys a default empty hook; the 6-arg variant deploys a hook with pre-configured tiers and optional croptop posting rules. |
-| `deploySuckersFor()` | Split Operator | Checked via `_checkIfIsSplitOperatorOf()` | Deploys new cross-chain suckers for an existing revnet. Also requires the current ruleset's `extraMetadata` bit 2 to be set (allows deploying suckers). |
-| `setSplitOperatorOf()` | Split Operator | Checked via `_checkIfIsSplitOperatorOf()` | Replaces the current split operator with a new address. Revokes all operator permissions from the caller and grants them to the new address. |
-| `autoIssueFor()` | Anyone | None | Mints pre-configured auto-issuance tokens for a beneficiary once the relevant stage has started. Amounts are set at deployment and can only be claimed once. |
-| `burnHeldTokensOf()` | Anyone | None | Burns any of a revnet's tokens held by the `REVDeployer` contract (e.g., from reserved token splits that did not sum to 100%). |
-| `afterCashOutRecordedWith()` | Anyone (called by terminal) | None | **Note: This function lives on REVOwner, not REVDeployer.** Processes cash-out fees. No caller validation needed because a non-terminal caller would only be donating their own funds. |
-
-### Split Operator Permissions (granted via JBPermissions)
-
-The split operator receives the following Juicebox permission IDs, scoped to its revnet:
+## Admin Boundaries
 
-| Permission ID | What It Allows |
-|---------------|----------------|
-| `SET_SPLIT_GROUPS` | Change how reserved tokens are distributed among split recipients. |
-| `SET_BUYBACK_POOL` | Configure which Uniswap V4 pool is used for the buyback hook. |
-| `SET_BUYBACK_TWAP` | Adjust the TWAP window for the buyback hook. |
-| `SET_PROJECT_URI` | Update the revnet's metadata URI. |
-| `ADD_PRICE_FEED` | Add a new price feed for the revnet. |
-| `SUCKER_SAFETY` | Manage sucker safety settings (e.g., emergency hatch). |
-| `SET_BUYBACK_HOOK` | Configure the buyback hook. |
-| `SET_ROUTER_TERMINAL` | Set the router terminal. |
-| `SET_TOKEN_METADATA` | Update the revnet token's name and symbol. |
-
-Optional 721 permissions (granted only if enabled at deployment via `REVDeploy721TiersHookConfig`):
-
-| Permission ID | Deployment Flag | What It Allows |
-|---------------|----------------|----------------|
-| `ADJUST_721_TIERS` | `preventSplitOperatorAdjustingTiers` | Add or remove ERC-721 tiers. Allowed unless prevented. |
-| `SET_721_METADATA` | `preventSplitOperatorUpdatingMetadata` | Update ERC-721 tier metadata. Allowed unless prevented. |
-| `MINT_721` | `preventSplitOperatorMinting` | Mint ERC-721s without payment from tiers with `allowOwnerMint`. Allowed unless prevented. |
-| `SET_721_DISCOUNT_PERCENT` | `preventSplitOperatorIncreasingDiscountPercent` | Increase the discount percentage of a tier. Allowed unless prevented. |
-
-### REVLoans
-
-| Function | Required Role | Access Control | What It Does |
-|----------|--------------|----------------|-------------|
-| `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. |
-
-### Constructor-Level Permissions (set once at deployment)
-
-These permissions are granted in the `REVDeployer` constructor and apply globally (wildcard `projectId = 0`):
-
-| Grantee | Permission ID | Purpose |
-|---------|---------------|---------|
-| `SUCKER_REGISTRY` | `MAP_SUCKER_TOKEN` | Allows the sucker registry to map tokens for all revnets. |
-| `LOANS` | `USE_ALLOWANCE` | Allows the loans contract to use surplus allowance from all revnets to fund loans. |
-| `BUYBACK_HOOK` | `SET_BUYBACK_POOL` | Allows the buyback hook registry to configure Uniswap V4 pools for all revnets. |
-
-## Autonomous Design
-
-Revnets are designed to operate without a traditional project owner. The following mechanisms enforce autonomy:
-
-- **Ownership transfer is permanent.** When a revnet is deployed, the Juicebox project NFT is transferred to the `REVDeployer` contract. No human holds the project NFT. There is no function to transfer it back.
-- **No ruleset queuing.** The `REVDeployer` does not expose any function to queue new rulesets after deployment. The stage progression is fully determined at deploy time. Nobody -- not the split operator, not the deployer, not anyone -- can change the issuance schedule, cash-out tax rates, or stage timing after deployment.
-- **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 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.
-
-## Loan Administration
-
-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 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:
-
-### REVDeployer (per-revnet, set at `deployFor` time)
-- Stage schedule (start times, issuance rates, cut frequencies, cut percentages)
-- Cash-out tax rates per stage
-- Split percentages per stage
-- Auto-issuance amounts and beneficiaries
-- Base currency
-- ERC-20 token name and symbol
-- Encoded configuration hash (used for cross-chain sucker deployment verification)
-
-### REVDeployer (global, set at contract deployment)
-- `CONTROLLER` -- the Juicebox controller
-- `DIRECTORY` -- the Juicebox directory
-- `PROJECTS` -- the Juicebox projects NFT contract
-- `PERMISSIONS` -- the Juicebox permissions contract
-- `SUCKER_REGISTRY` -- the sucker registry
-- `BUYBACK_HOOK` -- the buyback hook / data hook
-- `HOOK_DEPLOYER` -- the 721 tiers hook deployer
-- `PUBLISHER` -- the croptop publisher
-- `LOANS` -- the loans contract address
-- `FEE_REVNET_ID` -- the project ID that receives cash-out fees
-- `FEE` -- the cash-out fee (2.5%)
-- `CASH_OUT_DELAY` -- 30 days for cross-chain deployments
-- `DEFAULT_BUYBACK_POOL_FEE` -- 10,000 (1% Uniswap V4 fee tier)
-- `DEFAULT_BUYBACK_TICK_SPACING` -- 200
-- `DEFAULT_BUYBACK_TWAP_WINDOW` -- 2 days
-- `OWNER()` -- view returning the REVOwner address
-
-### REVOwner (global, set at contract deployment)
-- `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%)
-- `DEPLOYER` -- the REVDeployer address (storage variable, set once by the REVOwner initializer account using the precomputed canonical deployer address)
-
-### REVLoans (global, set at contract deployment)
-- `CONTROLLER`, `DIRECTORY`, `PRICES`, `PROJECTS` -- protocol infrastructure
-- `REV_ID` -- the REV revnet that receives loan fees
-- `PERMIT2` -- the permit2 contract
-- `LOAN_LIQUIDATION_DURATION` -- 10 years (3650 days)
-- `MIN_PREPAID_FEE_PERCENT` -- 2.5% (`25` out of `MAX_FEE = 1000`)
-- `MAX_PREPAID_FEE_PERCENT` -- 50% (`500` out of `MAX_FEE = 1000`)
-- `REV_PREPAID_FEE_PERCENT` -- 1% (`10` out of `MAX_FEE = 1000`)
+- 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.
 
-## Admin Boundaries
+## Source Map
 
-What admins **cannot** do -- this is the most important section for understanding revnet security guarantees:
-
-### The Split Operator Cannot:
-- Change issuance rates, schedules, or weight decay
-- Modify cash-out tax rates
-- Queue new rulesets or stages
-- Pause or disable cash outs
-- Mint fungible revnet tokens (only 721 minting if explicitly enabled at deploy)
-- Access or redirect treasury funds (no payout limit control)
-- Upgrade or migrate the revnet's controller
-- Change the revnet's terminals
-- Transfer the project NFT
-- Modify fund access limits or surplus allowances
-- Change the data hook or approval hook
-- Affect loan parameters or collateral
-
-### The REVLoans Owner Cannot:
-- Change loan interest rates, fees, or liquidation timing
-- Access or redirect collateral or borrowed funds
-- Prevent loan creation, repayment, or liquidation
-- Mint or burn tokens
-- Affect any revnet's configuration
-
-### The REVDeployer Contract Cannot (even though it holds the project NFT):
-- Queue new rulesets (no public or internal function exists for this)
-- Transfer the project NFT to any other address
-- Change terminals or the controller
-- Modify fund access limits after deployment
-- Override the data hook logic
-- Selectively block cash outs (beyond the time-limited `CASH_OUT_DELAY` for cross-chain deployments)
-
-### Nobody Can:
-- Change a revnet's stage schedule after deployment
-- Prevent token holders from eventually cashing out
-- Extract funds from the treasury without going through the bonding curve
-- Modify the fee structure (2.5% cash-out fee, loan fees)
-- Change which contract is the data hook for a revnet (always REVOwner)
-- Alter auto-issuance amounts after deployment (they can only be claimed, not changed)
+- `src/REVDeployer.sol`
+- `src/REVOwner.sol`
+- `src/REVLoans.sol`
+- `src/REVHiddenTokens.sol`
+- `test/`

package/ARCHITECTURE.md

@@ -2,39 +2,51 @@
 
 ## Purpose
 
-`revnet-core-v6` defines an autonomous Juicebox project pattern with staged, precommitted economics and token-collateralized loans. A revnet is intentionally ownerless after deployment: project behavior follows its queued stages and integrated hooks rather than ongoing governance.
+`revnet-core-v6` defines an autonomous Juicebox project pattern with staged, precommitted economics and token-collateralized loans. A revnet is intentionally ownerless after deployment in the human sense: behavior follows staged configuration and constrained runtime hooks instead of ongoing governance.
 
-## Boundaries
+## System Overview
 
-- `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.
+`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.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `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 |
+- 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.
+- `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.
+- Cross-chain supply and surplus are part of revnet economics. Local payouts and loans must not ignore remote sucker snapshots.
+
+## Modules
+
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `REVDeployer` | Launch, staged rulesets, hook wiring, permissions, runtime wrapper behavior | Launch-time and runtime wrapper |
+| `REVOwner` | Runtime owner-like policy surface | Hook-facing policy |
+| `REVLoans` | Borrow, repay, and liquidate burned-collateral loan positions | Economic core |
+| `REVHiddenTokens` | Temporary supply exclusion through burn and reveal | Supply-sensitive utility |
+| config structs | Stage, loan-source, auto-issuance, and hook config | Launch-time inputs |
+
+## Trust Boundaries
 
-## Runtime Model
+- Treasury and ruleset mechanics remain rooted in `nana-core-v6`.
+- Optional integrations come from `nana-buyback-hook-v6`, `nana-router-terminal-v6`, `nana-suckers-v6`, and `nana-721-hook-v6`.
+- This repo composes those systems into an ownerless product shape instead of reimplementing them.
+
+## Critical Flows
 
 ### Revnet Lifecycle
 
 ```text
 creator
-  -> deploys a revnet with a fixed sequence of stages
+  -> deploys a revnet with a fixed stage sequence
 stage transitions
-  -> happen automatically over time through ruleset activation
+  -> activate automatically over time through rulesets
 participants
-  -> pay in, receive tokens, cash out, and interact with downstream hooks
+  -> pay in, receive tokens, cash out, and interact with enabled integrations
 operators or permissionless callers
-  -> perform bounded maintenance actions such as auto-issuance claims
+  -> perform bounded maintenance such as auto-issuance claims
 ```
 
 ### Loan Lifecycle
@@ -42,35 +54,50 @@ operators or permissionless callers
 ```text
 borrower
   -> burns revnet tokens as collateral
-  -> receives funds from the treasury through REVLoans
+  -> borrowability is computed from the current stage, omnichain supply/surplus, and local liquidity caps
+  -> receives treasury-backed funds through REVLoans
   -> later repays to remint collateral
-  -> or gets liquidated after the long expiration window
+  -> or is liquidated after the expiration window
 ```
 
-## Critical Invariants
-
-- 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.
+## Accounting Model
 
-## Where Complexity Lives
+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.
 
-- Revnets span deployment-time guarantees, runtime hook behavior, and loan-state transitions.
-- The most subtle risks sit where treasury state, stage economics, and loan borrowability interact.
-- Ownerlessness is a feature, but it also removes easy operational recovery from misconfiguration.
+`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.
 
-## Dependencies
+## Security Model
 
-- `nana-core-v6` for treasury and ruleset mechanics
-- `nana-buyback-hook-v6`, `nana-suckers-v6`, `nana-router-terminal-v6`, and optionally `nana-721-hook-v6` for composed features
-- `croptop-core-v6` and other product repos when revnets are used as economic backends
+- The highest-risk interactions sit where stage economics, treasury state, and loan borrowability meet.
+- Ownerlessness removes convenient operational 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.
 
 ## Safe Change Guide
 
-- Treat deployer-time behavior and runtime wrapper behavior as one system.
-- Any change to stage semantics should be checked against loan math, cash-out semantics, and downstream fee-project expectations.
+- Review deploy-time behavior and runtime wrapper behavior together.
+- If stage semantics change, inspect loan math, cash-out behavior, and downstream fee expectations together.
 - Do not casually add mutable admin escape hatches.
-- Flash-loan and surplus-sensitive logic deserves adversarial review whenever loan calculations change.
-- If a change affects borrowability or repayment, test both sourced and unsourced loan paths.
+- 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.
+
+## Canonical Checks
+
+- cash-out-delay interaction with loans:
+  `test/TestLoansCashOutDelay.t.sol`
+- stage transitions and borrowability drift:
+  `test/TestStageTransitionBorrowable.t.sol`
+- omnichain or phantom-surplus edge cases:
+  `test/audit/CodexPhantomSurplusTerminal.t.sol`
+
+## Source Map
+
+- `src/REVDeployer.sol`
+- `src/REVOwner.sol`
+- `src/REVLoans.sol`
+- `src/REVHiddenTokens.sol`
+- `test/TestLoansCashOutDelay.t.sol`
+- `test/TestStageTransitionBorrowable.t.sol`
+- `test/audit/CodexPhantomSurplusTerminal.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 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.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - let a participant borrow more than intended against revnet collateral
@@ -40,7 +40,7 @@ Read in this order:
 `REVDeployer` explains why that behavior exists.
 `REVLoans` is where those economics are turned into extractable collateral value.
 
-## System Model
+## Security Model
 
 The repo splits responsibilities:
 - `REVDeployer`: launches revnets, encodes stage configs, manages optional 721 and sucker composition
@@ -57,6 +57,22 @@ 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
 
+## 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 |
+
+## 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 |
+
 ## Critical Invariants
 
 1. Stage immutability
@@ -83,24 +99,7 @@ Tokens hidden via REVHiddenTokens must be exactly recoverable on reveal. The hid
 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
-
-Prioritize:
-- surplus manipulation before and after borrowing
-- stage-boundary timing attacks
-- cash-out delay bypasses
-- 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
+## Attack Surfaces
 
 - `REVOwner.beforePayRecordedWith`
 - `REVOwner.beforeCashOutRecordedWith`
@@ -110,35 +109,19 @@ The best attacker mindsets here are:
 - `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
-
-1. Pay into a revnet with 721 and buyback composition enabled, then inspect how weight is scaled before and after hook specs are consumed.
-2. Borrow near a stage boundary, then repay, refinance, or liquidate after the next stage becomes active.
-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.
+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
 
-## Finding Bar
+## Accepted Risks Or Behaviors
 
-The best findings in this repo usually prove one of these:
-- a revnet mints or redeems on economics different from the stage schedule users think they are on
-- the runtime hook scales payment or cash-out accounting incorrectly during composition
-- the loan system can externalize loss to the treasury through timing, surplus movement, or fee math
-- a deployer-only or operator-only assumption survives launch and remains exploitable at runtime
+- Composition is the default audit target here, not an edge case.
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Current tests emphasize:
-- lifecycle and invincibility properties
-- loan invariants and attacks
-- fee recovery
-- split-weight adjustments
-- regressions around low-severity edge cases
-
-Strong findings in this repo usually combine economics and composition: a bug is especially valuable if it only appears once a revnet is wired into the rest of the ecosystem.