@rev-net/core-v6 0.0.32 → 0.0.34

package/AUDIT_INSTRUCTIONS.md

@@ -1,144 +1,90 @@
 # Audit Instructions
 
-Revnets are autonomous Juicebox projects with staged economics and token-collateralized loans. Audit this repo as both a privileged deployer layer and a live economic system.
+Revnet is a staged, owner-minimized product layer on top of Juicebox core. Audit it as an economic system, not just a deployer plus a loan contract.
 
-## Objective
+## Audit Objective
 
 Find issues that:
-- let a participant borrow more than intended against revnet collateral
-- break stage transitions or immutable revnet economics
-- mis-scale weights, fees, or split behavior in composed payment flows
-- grant owner-like or operator-like powers outside the documented model
-- leave deployed revnets or loans in states that cannot settle safely
+
+- break stage progression or let users act under the wrong stage assumptions
+- overstate or understate borrowability
+- mis-handle hidden tokens or burned-collateral accounting
+- give operators or integrations more power than the revnet model intends
+- make omnichain supply, surplus, or sucker assumptions drift from runtime behavior
 
 ## Scope
 
 In scope:
+
 - `src/REVDeployer.sol`
 - `src/REVOwner.sol`
 - `src/REVLoans.sol`
 - `src/REVHiddenTokens.sol`
-- `src/interfaces/`
-- `src/structs/`
-- deployment scripts in `script/`
-
-Key dependencies:
-- `nana-core-v6`
-- `nana-721-hook-v6`
-- `nana-buyback-hook-v6`
-- `nana-suckers-v6`
-- `croptop-core-v6`
+- structs, interfaces, and deployment helpers
 
 ## Start Here
 
-Read in this order:
-- `REVOwner`
-- `REVDeployer`
-- `REVLoans`
-
-`REVOwner` is the fastest way to understand how a live revnet differs from plain Juicebox behavior.
-`REVDeployer` explains why that behavior exists.
-`REVLoans` is where those economics are turned into extractable collateral value.
+1. `src/REVDeployer.sol`
+2. `src/REVOwner.sol`
+3. `src/REVLoans.sol`
+4. `src/REVHiddenTokens.sol`
 
-## System Model
+## Security Model
 
-The repo splits responsibilities:
-- `REVDeployer`: launches revnets, encodes stage configs, manages optional 721 and sucker composition
-- `REVOwner`: runtime data/cash-out hook used by deployed revnets
-- `REVLoans`: loan system that burns collateral on borrow and re-mints on repayment
-- `REVHiddenTokens`: temporary token hiding that burns tokens to exclude from totalSupply and re-mints on reveal
-
-Important composition behavior:
-- revnet payments may be proxied through 721 and buyback hooks
-- cash-out behavior may be altered for suckers or by revnet-specific fee handling
-- loan health depends on bonding-curve value and surplus, so core accounting and stage timing directly matter
-
-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
-
-## Critical Invariants
+Revnet composes several sensitive systems:
 
-1. Stage immutability
-Once a revnet is launched, future stage economics must follow the encoded schedule and not become mutable through helper paths.
+- staged rulesets and launch-time immutability
+- runtime pay and cash-out policy in `REVOwner`
+- burned-collateral lending in `REVLoans`
+- hidden-token supply exclusion in `REVHiddenTokens`
 
-2. Payment accounting is scaled correctly
-If only part of a payment enters the treasury because of split or hook routing, token issuance must reflect only that treasury-entering portion.
+The main audit mindset is composition:
 
-3. Loan collateralization is sound
-Borrow, repay, refinance, and liquidation paths must never let a borrower extract more value than the design permits.
+- stage economics affect borrowability
+- hidden supply affects cash-out math
+- omnichain state can affect reclaim and borrowing power
+- optional integrations can widen the effective trust surface
 
-4. Hook privilege stays narrow
-`REVOwner` and deployer-only setters must not be callable by arbitrary actors or stale deployment helpers.
+## Roles And Privileges
 
-5. Sucker and operator exemptions are precise
-Fee-free or mint-enabled paths meant for registered omnichain components must not be reusable by arbitrary callers.
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Revnet deployer path | Define long-lived stage and operator shape | Must not retain unexpected mutable governance |
+| Split operator | Use the allowed runtime envelope | Must stay within deployment-defined permissions |
+| Borrower or delegated operator | Open or manage loans | Must not escape collateral, delay, or source limits |
+| Hidden-token user or delegate | Burn and reveal visible supply | Must not create extra supply or break accounting |
 
-6. Collateral burn/remint symmetry holds
-Loan collateral that is burned on borrow and re-minted on repay must not be duplicable, strandable, or recoverable by the wrong party.
+## Integration Assumptions
 
-7. Hidden token accounting is sound
-Tokens hidden via REVHiddenTokens must be exactly recoverable on reveal. The hidden balance must not allow minting more tokens than were burned, and totalHiddenOf must equal the sum of all per-holder hidden balances.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | Rulesets, reclaim math, and surplus views stay coherent | Stage and cash-out behavior drift |
+| `nana-suckers-v6` | Remote supply/surplus snapshots are authentic | Omnichain reclaim and borrowability drift |
+| Buyback and 721 integrations | Hook composition remains consistent with revnet expectations | Pay-path and mint-permission behavior drift |
 
-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
+## Critical Invariants
 
-- `REVOwner.beforePayRecordedWith`
-- `REVOwner.beforeCashOutRecordedWith`
-- deployer-only linkage between `REVDeployer` and `REVOwner`
-- `REVLoans` borrowable amount, fee accrual, and liquidation logic
-- `REVHiddenTokens.hideTokensOf` and `revealTokensOf` burn/mint symmetry and `HIDE_TOKENS`/`REVEAL_TOKENS` permission checks
-- `REVLoans` operator delegation: `OPEN_LOAN`, `REPAY_LOAN`, `REALLOCATE_LOAN` inline permission checks — verify holder/owner receives collateral and loan NFTs in all delegation paths
-- any path that assumes a valid tiered 721 hook or sucker mapping exists
+1. Stage progression stays monotonic and follows deployed timing.
+2. Borrowability respects cash-out delay, surplus, supply, and source limits.
+3. Burned collateral is not accidentally treated like escrowed collateral.
+4. Hidden-token accounting preserves total claims while changing visible supply intentionally.
+5. Optional integrations do not silently widen revnet authority or mint rights.
 
-## Sequences Worth Replaying
+## Attack Surfaces
 
-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.
+- stage-transition boundaries
+- live borrowability and cross-currency debt aggregation
+- hidden-token burn and reveal flows
+- omnichain surplus and sucker exemptions
+- payment and cash-out hook composition in `REVOwner`
 
-## 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
+- Revnets intentionally trade recoverability for predictable launch-time economics.
+- Some economic surfaces are conservative by design and may refuse otherwise-valid actions rather than risk an unsafe result.
 
-## 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.

package/CHANGELOG.md

@@ -26,12 +26,12 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 ## Operator delegation (permission IDs 35–39)
 
 - Added five new `JBPermissionIds` for operator delegation in `@bananapus/permission-ids-v6`:
-  - `HIDE_TOKENS` (35) — hide tokens on behalf of a holder via `REVHiddenTokens.hideTokensOf`
+  - `HIDE_TOKENS` (35) — lets an authorized operator allow or disallow holders to hide their own tokens via `REVHiddenTokens`
   - `OPEN_LOAN` (36) — open a loan on behalf of a token holder via `REVLoans.borrowFrom`
   - `REALLOCATE_LOAN` (37) — reallocate loan collateral on behalf of a loan owner via `REVLoans.reallocateCollateralFromLoan`
   - `REPAY_LOAN` (38) — repay a loan on behalf of a loan owner via `REVLoans.repayLoan`
-  - `REVEAL_TOKENS` (39) — reveal hidden tokens on behalf of a holder via `REVHiddenTokens.revealTokensOf`
-- `REVHiddenTokens` now inherits `JBPermissioned` and accepts a `holder` parameter on `hideTokensOf` and `revealTokensOf`. An operator with the appropriate permission can act on behalf of the holder.
+  - `REVEAL_TOKENS` (39) — legacy permission id; hidden-token reveal no longer depends on it
+- `REVHiddenTokens` now inherits `JBPermissioned` and accepts a `holder` parameter on `hideTokensOf` and `revealTokensOf`. Hiding is available to an operator-managed holder allowlist, and also to the project owner or any operator with `HIDE_TOKENS`. Revealing is holder-only and does not require special permission.
 - `REVLoans.borrowFrom` now accepts a `holder` parameter. The loan NFT is minted to `holder`, and collateral is burned from `holder`. An operator with `OPEN_LOAN` permission can borrow on behalf of a holder.
 - `REVLoans.repayLoan` now allows permissioned operators with `REPAY_LOAN` to repay on behalf of the loan NFT owner. Replacement loans are minted to the original loan owner.
 - `REVLoans.reallocateCollateralFromLoan` now allows permissioned operators with `REALLOCATE_LOAN` to reallocate on behalf of the loan NFT owner. Returned collateral and replacement loans go to the original loan owner.
@@ -41,6 +41,7 @@ This file describes the verified change from `revnet-core-v5` to the current `re
 
 - `IREVHiddenTokens.hideTokensOf` signature changed: added `address holder` parameter
 - `IREVHiddenTokens.revealTokensOf` signature changed: added `address holder` parameter
+- `IREVHiddenTokens.setTokenHidingAllowedFor` added for operator-managed holder allowlisting
 - `IREVHiddenTokens.HideTokens` event: added `address holder` field
 - `IREVHiddenTokens.RevealTokens` event: added `address holder` field
 - `IREVLoans.borrowFrom` signature changed: added `address holder` as last parameter

package/README.md

@@ -1,25 +1,29 @@
 # 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, hidden-token mechanics, 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:
 
 - a deployer that launches Revnets and stores their long-lived configuration
 - a runtime hook that mediates pay, cash-out, mint-permission, and delayed-cash-out behavior
-- an ERC-721 loan system that burns token collateral on borrow and remints on repayment
+- a loan system that burns token collateral on borrow and remints on repayment
+- a hidden-token system that temporarily removes tokens from visible supply
 
 It also composes with the 721 hook stack, buyback hook, router terminal, Croptop, and suckers where needed.
 
-Use this repo when the product is 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.
-
-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.
+Use this repo when the product is a treasury-backed network with encoded stage transitions and a tightly constrained post-launch admin surface. Do not use it when the goal is ordinary governance or a simple project deploy.
 
 ## Key Contracts
 
@@ -28,48 +32,46 @@ The key point is that a Revnet is not just "a Juicebox project with presets." It
 | `REVDeployer` | Launches and configures Revnets, stages, split operators, and optional auxiliary features. |
 | `REVOwner` | Runtime data-hook and cash-out-hook surface used by active Revnets. |
 | `REVLoans` | Loan surface that lets users borrow against Revnet tokens with burned collateral and NFT loan positions. |
-| `REVHiddenTokens` | Lets token holders temporarily hide (burn) tokens, excluding them from totalSupply and increasing cash-out value for remaining holders. Hidden tokens can be revealed (re-minted) at any time. |
+| `REVHiddenTokens` | Lets token holders temporarily hide tokens, excluding them from visible supply until reveal. |
 
 ## Mental Model
 
 Read the package in two halves:
 
 1. deployment-time shape: `REVDeployer` decides what the network will be allowed to do
-2. runtime enforcement: `REVOwner` and `REVLoans` decide how that shape behaves over time
-
-That split matters because most mistakes are one of these:
-
-- assuming a deploy-time parameter can be changed later
-- assuming a runtime hook is only advisory rather than economically binding
+2. runtime enforcement: `REVOwner`, `REVLoans`, and `REVHiddenTokens` decide how that shape behaves over time
 
-The shortest useful reading order is:
-
-1. `REVDeployer`
-2. `REVOwner`
-3. `REVLoans`
-4. any integrated hook or bridge repo the deployment enables
+Most mistakes come from assuming a deploy-time parameter can be changed later or that a runtime hook is only advisory.
 
 ## Read These Files First
 
 1. `src/REVDeployer.sol`
 2. `src/REVOwner.sol`
 3. `src/REVLoans.sol`
-4. the integrated hook or bridge repo used by the deployment
+4. `src/REVHiddenTokens.sol`
+5. the integrated hook or bridge repo used by the deployment
 
 ## Integration Traps
 
-- the deployer holding the project NFT is not an implementation detail; it is part of the ownership model
+- the deployer holding the project NFT is part of the ownership model, not an implementation detail
 - split operators are constrained, not equivalent to general protocol governance
-- the loan system depends on live revnet economics, so it should be reviewed together with the runtime hook and treasury assumptions
-- optional integrations like buybacks, 721 hooks, and suckers are compositional, but they materially change the resulting network
+- the loan system depends on live revnet economics and should be reviewed together with the runtime hook
+- optional integrations like buybacks, 721 hooks, and suckers materially change the resulting network
 
 ## Where State Lives
 
 - deployment-time configuration and operator envelope live in `REVDeployer`
 - runtime pay and cash-out behavior live in `REVOwner`
 - loan positions and loan-specific state live in `REVLoans`
+- hidden-token state lives in `REVHiddenTokens`
+
+## High-Signal Tests
 
-Do not audit those contracts in isolation if the deployment enables cross-package features; the composed network is the real product.
+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
 
@@ -94,7 +96,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Revnet deployment assumes the core protocol, 721 hook, buyback hook, router terminal, suckers, and Croptop packages are available. 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 sense after deployment, but the deployer contract itself remains part of the ownership model.
 
 ## Repository Layout
 
@@ -103,6 +105,7 @@ src/
   REVDeployer.sol
   REVOwner.sol
   REVLoans.sol
+  REVHiddenTokens.sol
   interfaces/
   structs/
 test/
@@ -115,8 +118,12 @@ script/
 ## Risks And Notes
 
 - Revnets are intentionally hard to change after launch, so bad stage design is expensive
-- `REVLoans` relies on live treasury conditions and is therefore sensitive to surplus and pricing assumptions
-- the deployer and runtime hook have a tight relationship that should be treated as one design, not two independent contracts
-- burned-collateral lending is operationally different from escrowed-collateral lending and needs clear integrator expectations
+- `REVLoans` relies on live treasury conditions and is sensitive to surplus and pricing assumptions
+- the deployer and runtime hook should be treated as one design, not two separate systems
+- burned-collateral lending is operationally different from escrowed-collateral lending
+
+## For AI Agents
 
-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.
+- Describe Revnets as treasury-backed Juicebox project shapes with encoded stage transitions, not as simple presets.
+- Read `REVDeployer`, `REVOwner`, `REVLoans`, and `REVHiddenTokens` together before answering economic or admin-surface questions.
+- If a deployment enables buybacks, 721 hooks, or suckers, inspect those sibling repos before making definitive claims.