@rev-net/core-v6 0.0.32 → 0.0.34

package/ADMINISTRATION.md

@@ -1,237 +1,73 @@
 # 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, 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 |
 
-- 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 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.
 
-- 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.
+- `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
 
-### 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.
-
-### REVLoans Owner (Ownable)
-
-- **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.
-
-### REVDeployer (as Juicebox project owner)
-
-- **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.
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| `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 |
 
-### Loan NFT Owner
+## Privileged Surfaces
 
-- **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.
+- `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`
 
-### Anyone (Permissionless)
+## Immutable And One-Way
 
-- **Scope:** Several functions are callable by any address with no access control, as documented in the Privileged Functions tables below.
+- 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.
 
-## Privileged Functions
+## Operational Notes
 
-### REVDeployer
+- 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.
 
-| 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. |
+## Machine Notes
 
-### Split Operator Permissions (granted via JBPermissions)
+- 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.
 
-The split operator receives the following Juicebox permission IDs, scoped to its revnet:
+## Recovery
 
-| 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`)
+- 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
 
-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)
+- 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

@@ -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 NFTs. `REVHiddenTokens` lets holders burn tokens to exclude them from visible 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.
+- 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.
+- 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,49 @@ 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 config, 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 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.
 
-## 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 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.
+- Rev cash-out fees stack on top of protocol-fee behavior rather than replacing it.
 
 ## 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 assumptions, and mint-permission flows.
+
+## 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`