@rev-net/core-v6 0.0.37 → 0.0.39

package/src/REVOwner.sol

@@ -9,12 +9,14 @@ import {IJBRulesetDataHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetDa
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {JBCashOuts} from "@bananapus/core-v6/src/libraries/JBCashOuts.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
 import {JBAfterCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBAfterCashOutRecordedContext.sol";
 import {JBBeforeCashOutRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforeCashOutRecordedContext.sol";
 import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
 import {JBCashOutHookSpecification} from "@bananapus/core-v6/src/structs/JBCashOutHookSpecification.sol";
 import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {IJBPeerChainAdjustedAccounts} from "@bananapus/suckers-v6/src/interfaces/IJBPeerChainAdjustedAccounts.sol";
 import {IJBSuckerRegistry} from "@bananapus/suckers-v6/src/interfaces/IJBSuckerRegistry.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
@@ -22,11 +24,14 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {IREVDeployer} from "./interfaces/IREVDeployer.sol";
+import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
+import {IREVLoans} from "./interfaces/IREVLoans.sol";
+import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
 /// @notice Handles the runtime data hook and cash out hook behavior for revnets.
 /// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit.
 /// This contract is set as the `dataHook` in each revnet's ruleset metadata.
-contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
+contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAccounts {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
 
@@ -61,10 +66,10 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     uint256 public immutable FEE_REVNET_ID;
 
     /// @notice The hidden tokens contract used by all revnets.
-    address public immutable HIDDEN_TOKENS;
+    IREVHiddenTokens public immutable HIDDEN_TOKENS;
 
     /// @notice The loan contract used by all revnets.
-    address public immutable LOANS;
+    IREVLoans public immutable LOANS;
 
     /// @notice Deploys and tracks suckers for revnets.
     IJBSuckerRegistry public immutable SUCKER_REGISTRY;
@@ -102,23 +107,21 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     /// @param directory The directory of terminals and controllers.
     /// @param feeRevnetId The Juicebox project ID of the fee revnet.
     /// @param suckerRegistry The sucker registry.
-    /// @param loans The loan contract address.
-    /// @param hiddenTokens The hidden tokens contract address.
+    /// @param loans The loan contract.
+    /// @param hiddenTokens The hidden tokens contract.
     constructor(
         IJBBuybackHookRegistry buybackHook,
         IJBDirectory directory,
         uint256 feeRevnetId,
         IJBSuckerRegistry suckerRegistry,
-        address loans,
-        address hiddenTokens
+        IREVLoans loans,
+        IREVHiddenTokens hiddenTokens
     ) {
         BUYBACK_HOOK = buybackHook;
         DIRECTORY = directory;
         FEE_REVNET_ID = feeRevnetId;
         SUCKER_REGISTRY = suckerRegistry;
-        // slither-disable-next-line missing-zero-check
         LOANS = loans;
-        // slither-disable-next-line missing-zero-check
         HIDDEN_TOKENS = hiddenTokens;
         _DEPLOYER_BINDER = msg.sender;
     }
@@ -153,11 +156,23 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
+        // Treat outstanding local loans as temporarily off-terminal revnet assets. Borrowed funds are owed back to
+        // the revnet, while burned loan collateral can be re-minted on repayment, so both affect fair cash-out math.
+        (uint256 totalBorrowed, uint256 totalCollateral) = _localLoanStateOf({
+            revnetId: context.projectId, decimals: context.surplus.decimals, currency: context.surplus.currency
+        });
+
         // If the cash out is from a sucker, return the full cash out amount without taxes or fees.
         // This relies on the sucker registry to only contain trusted sucker contracts deployed via
         // the registry's own deploySuckersFor flow — external addresses cannot register as suckers.
         if (_isSuckerOf({revnetId: context.projectId, addr: context.holder})) {
-            return (0, context.cashOutCount, context.totalSupply, context.surplus.value, hookSpecifications);
+            return (
+                0,
+                context.cashOutCount,
+                context.totalSupply + totalCollateral,
+                context.surplus.value + totalBorrowed,
+                hookSpecifications
+            );
         }
 
         // Keep a reference to the cash out delay of the revnet.
@@ -173,8 +188,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
 
         // Compute the cross-chain total supply (local + remote peer chain supplies) for cross-chain-aware bonding
         // curve.
-        totalSupply = context.totalSupply + SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
-        effectiveSurplusValue = context.surplus.value
+        totalSupply = context.totalSupply + totalCollateral + SUCKER_REGISTRY.remoteTotalSupplyOf(context.projectId);
+        effectiveSurplusValue = context.surplus.value + totalBorrowed
             + SUCKER_REGISTRY.remoteSurplusOf({
                 projectId: context.projectId,
                 decimals: context.surplus.decimals,
@@ -350,11 +365,35 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     {
         // The loans contract, hidden tokens contract, buyback hook (and its delegates), and suckers are allowed to mint
         // the revnet's tokens.
-        return addr == LOANS || addr == HIDDEN_TOKENS || addr == address(BUYBACK_HOOK)
+        return addr == address(LOANS) || addr == address(HIDDEN_TOKENS) || addr == address(BUYBACK_HOOK)
             || BUYBACK_HOOK.hasMintPermissionFor({projectId: revnetId, ruleset: ruleset, addr: addr})
             || _isSuckerOf({revnetId: revnetId, addr: addr});
     }
 
+    /// @notice Additional revnet accounts that peer-chain snapshots should include.
+    /// @dev Hidden tokens are intentionally excluded. Revnet operators can hide tokens as a security handle without
+    /// changing loan or cash-out math for other holders. Outstanding loan debt is counted as both surplus and balance:
+    /// it is value owed back to this chain's revnet and should travel to peer snapshots with the collateral supply.
+    /// @param revnetId The ID of the revnet being snapshotted.
+    /// @param decimals The decimals the returned surplus should use.
+    /// @param currency The currency the returned surplus should be in terms of.
+    /// @return supply The loan-collateral supply to include in the peer snapshot.
+    /// @return surplus The outstanding loan debt to include in `sourceSurplus`.
+    /// @return balance The outstanding loan debt to include in `sourceBalance`.
+    function peerChainAdjustedAccountsOf(
+        uint256 revnetId,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        override
+        returns (uint256 supply, uint256 surplus, uint256 balance)
+    {
+        (surplus, supply) = _localLoanStateOf({revnetId: revnetId, decimals: decimals, currency: currency});
+        balance = surplus;
+    }
+
     //*********************************************************************//
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
@@ -460,7 +499,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
     /// @return A flag indicating if the provided interface ID is supported.
     function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
         return interfaceId == type(IERC165).interfaceId || interfaceId == type(IJBRulesetDataHook).interfaceId
-            || interfaceId == type(IJBCashOutHook).interfaceId;
+            || interfaceId == type(IJBCashOutHook).interfaceId
+            || interfaceId == type(IJBPeerChainAdjustedAccounts).interfaceId;
     }
 
     //*********************************************************************//
@@ -475,6 +515,73 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook {
         return SUCKER_REGISTRY.isSuckerOf({projectId: revnetId, addr: addr});
     }
 
+    /// @notice Total outstanding local loan debt and collateral for a revnet.
+    /// @dev This is included in cash-out and peer-snapshot math because borrowed funds are still owed to the revnet
+    /// and collateral can re-enter supply when the loan is repaid.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param decimals The decimals the resulting fixed point debt value should use.
+    /// @param currency The currency the resulting debt value should be in terms of.
+    /// @return borrowedAmount The local outstanding loan debt converted into `currency`.
+    /// @return collateralCount The local burned loan collateral count.
+    function _localLoanStateOf(
+        uint256 revnetId,
+        uint256 decimals,
+        uint256 currency
+    )
+        internal
+        view
+        returns (uint256 borrowedAmount, uint256 collateralCount)
+    {
+        IREVLoans loans = LOANS;
+        if (address(loans) == address(0) || address(loans).code.length == 0) return (0, 0);
+
+        collateralCount = loans.totalCollateralOf(revnetId);
+
+        REVLoanSource[] memory sources = loans.loanSourcesOf(revnetId);
+        // Loan sources are project configuration, and this read-only aggregation needs the latest terminal/pricing
+        // state for each configured source.
+        for (uint256 i; i < sources.length; i++) {
+            REVLoanSource memory source = sources[i];
+            // Each configured source must be queried live so cash-out math includes current outstanding debt.
+            // slither-disable-next-line calls-loop
+            uint256 tokensLoaned =
+                loans.totalBorrowedFrom({revnetId: revnetId, terminal: source.terminal, token: source.token});
+            if (tokensLoaned == 0) continue;
+
+            // Read the source token's accounting context so debt can be normalized before cross-currency conversion.
+            // slither-disable-next-line calls-loop
+            JBAccountingContext memory accountingContext =
+                source.terminal.accountingContextForTokenOf({projectId: revnetId, token: source.token});
+
+            // Normalize each source from its native token decimals into the caller's requested decimals.
+            uint256 normalizedTokens;
+            if (accountingContext.decimals > decimals) {
+                normalizedTokens = tokensLoaned / (10 ** (accountingContext.decimals - decimals));
+            } else if (accountingContext.decimals < decimals) {
+                normalizedTokens = tokensLoaned * (10 ** (decimals - accountingContext.decimals));
+            } else {
+                normalizedTokens = tokensLoaned;
+            }
+
+            if (accountingContext.currency == currency) {
+                borrowedAmount += normalizedTokens;
+            } else {
+                // Convert source-token debt into the requested currency using the loans contract's shared prices.
+                // slither-disable-next-line calls-loop
+                uint256 pricePerUnit = loans.PRICES()
+                    .pricePerUnitOf({
+                    projectId: revnetId,
+                    pricingCurrency: accountingContext.currency,
+                    unitCurrency: currency,
+                    decimals: decimals
+                });
+                if (pricePerUnit == 0) continue;
+
+                borrowedAmount += mulDiv({x: normalizedTokens, y: 10 ** decimals, denominator: pricePerUnit});
+            }
+        }
+    }
+
     //*********************************************************************//
     // --------------------- internal transactions ----------------------- //
     //*********************************************************************//

package/src/interfaces/IREVDeployer.sol

@@ -16,6 +16,7 @@ import {REVConfig} from "../structs/REVConfig.sol";
 import {REVCroptopAllowedPost} from "../structs/REVCroptopAllowedPost.sol";
 import {REVDeploy721TiersHookConfig} from "../structs/REVDeploy721TiersHookConfig.sol";
 import {REVSuckerDeploymentConfig} from "../structs/REVSuckerDeploymentConfig.sol";
+import {IREVLoans} from "./IREVLoans.sol";
 
 /// @notice Deploys and manages revnets -- Juicebox projects with pre-configured tokenomics.
 interface IREVDeployer {
@@ -143,7 +144,7 @@ interface IREVDeployer {
 
     /// @notice The loan contract used by all revnets.
     /// @return The loans contract address.
-    function LOANS() external view returns (address);
+    function LOANS() external view returns (IREVLoans);
 
     /// @notice The runtime data hook contract that handles pay and cash out callbacks for revnets.
     /// @return The owner contract address.

package/src/interfaces/IREVHiddenTokens.sol

@@ -3,7 +3,10 @@ pragma solidity ^0.8.0;
 
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 
-/// @notice Manages hiding (burning) and revealing (re-minting) revnet tokens to exclude them from totalSupply.
+/// @notice Manages hiding (burning) and revealing (re-minting) revnet tokens to exclude them from live totalSupply.
+/// @dev Hidden balances are an operator-controlled security handle. They remain revealable, but cash-out and loan
+/// accounting intentionally excludes `totalHiddenOf` so hidden inventory cannot dilute other holders' access to
+/// revnet capital.
 interface IREVHiddenTokens {
     /// @notice Emitted when a holder is allowed or disallowed to hide their own tokens.
     /// @param revnetId The ID of the revnet.

package/src/interfaces/IREVOwner.sol

@@ -2,9 +2,14 @@
 pragma solidity ^0.8.0;
 
 import {IREVDeployer} from "./IREVDeployer.sol";
+import {IREVHiddenTokens} from "./IREVHiddenTokens.sol";
 
 /// @notice Interface for the REVOwner contract that handles runtime data hook and cash out hook behavior for revnets.
 interface IREVOwner {
+    /// @notice The hidden tokens contract used by the revnet owner hook.
+    /// @return The hidden tokens contract.
+    function HIDDEN_TOKENS() external view returns (IREVHiddenTokens);
+
     /// @notice The timestamp of when cashouts will become available to a specific revnet's participants.
     /// @param revnetId The ID of the revnet.
     /// @return The cash out delay timestamp.

package/ADMINISTRATION.md

@@ -1,73 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Revnet deployment shape, bounded runtime operators, loan-owner cosmetics, and optional integration control surfaces |
-| Control posture | Intentionally narrow and mostly deployment-defined |
-| Highest-risk actions | Bad stage design, wrong split-operator assignment, and misunderstanding which runtime surfaces stay live after launch |
-| Recovery posture | Usually replacement, not patching; the design intentionally avoids easy admin escape hatches |
-
-## Purpose
-
-`revnet-core-v6` is designed to collapse ordinary post-launch governance into deployment-time decisions plus a small set of bounded runtime roles. The main administration task is understanding which power still exists and which power was intentionally removed.
-
-## Control Model
-
-- `REVDeployer` holds the project NFT and therefore remains part of the ownership model.
-- Revnet economics are mainly fixed at deployment through staged rulesets.
-- `REVOwner` provides live runtime policy, but not broad human governance.
-- Split operators can hold narrow powers depending on stage and deployment config.
-- `REVLoans` has a cosmetic global owner surface, but loan economics are still bounded by revnet logic.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| `REVDeployer` | Deployed singleton | Global launcher and project-NFT holder | Part of the ownership model |
-| Split operator | Deployment config | Per revnet | Holds only the allowed operator envelope |
-| Auto-issuance beneficiary | Deployment config | Per stage | Can receive preconfigured stage issuance |
-| Borrower or delegated loan operator | Token holder plus permission | Per holder or loan | Can open or manage loans within loan rules |
-| `REVLoans` owner | Constructor owner | Global cosmetic/admin surface | Does not turn Revnets back into ordinary governed projects |
-
-## Privileged Surfaces
-
-- `deployFor(...)` defines the revnet's long-lived shape
-- split-operator paths can manage only the permissions left open by deployment
-- `autoIssueFor(...)` consumes preconfigured stage issuance
-- loan operators can redirect borrowed value if a holder delegates loan permissions
-- hidden-token flows require the holder's permission grant and mint permission wiring through `REVOwner`
-
-## Immutable And One-Way
-
-- Stage configuration is effectively permanent after deployment.
-- The deployer-held project NFT is not a normal owner-recovery tool.
-- Loan collateral is burned at borrow time and only reminted through repayment or documented flows.
-- Hidden-token balances change visible supply until reveal.
-
-## Operational Notes
-
-- Treat revnet launch as the real governance decision.
-- Validate stage timing, split-operator scope, and optional integrations before deployment.
-- Review cash-out delay, hidden-token semantics, and loan permissions together.
-- Do not assume there is a broad admin override for bad economics after launch.
-
-## Machine Notes
-
-- Do not describe Revnets as fully adminless if the deployer-held NFT still matters for the trust model.
-- Also do not describe them as ordinary owner-controlled projects. The point is that the available control surface is intentionally narrow.
-- If a question is about runtime cash-outs, buybacks, or mint permissions, inspect `REVOwner` before inferring behavior from deployment prose.
-
-## Recovery
-
-- 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
-
-- 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

@@ -1,116 +0,0 @@
-# Architecture
-
-## 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 in the human sense: behavior follows staged configuration and constrained runtime hooks instead of ongoing governance.
-
-## System Overview
-
-`REVDeployer` handles launch-time shape, staged rulesets, hook wiring, and runtime wrapper behavior. `REVOwner` provides the owner-like runtime policy surface for pay and cash-out hooks after launch. `REVLoans` manages burn-collateral loan positions represented as NFTs. `REVHiddenTokens` lets holders burn tokens to exclude them from visible supply until they reveal them again.
-
-## Core Invariants
-
-- Revnets are intended to be ownerless after deployment; easy admin recovery paths would violate the product model.
-- Stage configuration is effectively permanent once queued.
-- Loan collateral is burned, not escrowed.
-- 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
-
-- 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 stage sequence
-stage transitions
-  -> activate automatically over time through rulesets
-participants
-  -> pay in, receive tokens, cash out, and interact with enabled integrations
-operators or permissionless callers
-  -> perform bounded maintenance such as auto-issuance claims
-```
-
-### Loan Lifecycle
-
-```text
-borrower
-  -> burns revnet tokens as collateral
-  -> 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 is liquidated after the expiration window
-```
-
-## Accounting Model
-
-The repo does not replace core treasury accounting. Its critical economic logic is the interaction between staged revnet config, burned-collateral loan state, hidden-token supply exclusion, and omnichain revnet state imported from suckers.
-
-`REVOwner` also composes payment and cash-out hooks. On pay, it can merge 721-tier split forwarding with buyback-hook behavior and scale mint weight so the terminal only mints against the share that actually enters the project. On cash out, it can use omnichain supply and surplus for reclaim math, exempt trusted suckers, and append fee-hook specs.
-
-## Security Model
-
-- The highest-risk interactions sit where stage economics, treasury state, and loan borrowability meet.
-- Ownerlessness removes convenient 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
-
-- 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.
-- 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.
-
-## Cross-Chain Configuration Hash
-
-`REVDeployer` produces an `encodedConfigurationHash` for each revnet that determines sucker deployment salts. This hash commits the revnet's identity across chains. It includes:
-
-- `baseCurrency`, `description.name`, `description.ticker`, `description.salt`
-- Terminal addresses (order-sensitive)
-- Stage parameters (timing, issuance, splits, tax rates, auto-issuances)
-
-Terminal addresses are included because they are deployed deterministically at the same address across chains. Accounting contexts (token addresses) are excluded because tokens like USDC legitimately differ per chain.
-
-This means a revnet can only expand to a new chain if it uses the exact same terminal contract it used on the host chain. Different terminal addresses produce a different hash, preventing accidental cross-chain mismatches in sucker deployments.
-
-## Canonical Checks
-
-- 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`
-- terminal encoding in configuration hash:
-  `test/TestTerminalEncodingInHash.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

@@ -1,90 +0,0 @@
-# Audit Instructions
-
-Revnet is a staged, owner-minimized product layer on top of Juicebox core. Audit it as an economic system, not just a deployer plus a loan contract.
-
-## Audit Objective
-
-Find issues that:
-
-- 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`
-- structs, interfaces, and deployment helpers
-
-## Start Here
-
-1. `src/REVDeployer.sol`
-2. `src/REVOwner.sol`
-3. `src/REVLoans.sol`
-4. `src/REVHiddenTokens.sol`
-
-## Security Model
-
-Revnet composes several sensitive systems:
-
-- staged rulesets and launch-time immutability
-- runtime pay and cash-out policy in `REVOwner`
-- burned-collateral lending in `REVLoans`
-- hidden-token supply exclusion in `REVHiddenTokens`
-
-The main audit mindset is composition:
-
-- stage economics affect borrowability
-- hidden supply affects cash-out math
-- omnichain state can affect reclaim and borrowing power
-- optional integrations can widen the effective trust surface
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Revnet deployer path | Define long-lived stage and operator shape | Must not retain unexpected mutable governance |
-| Split operator | Use the allowed runtime envelope | Must stay within deployment-defined permissions |
-| Borrower or delegated operator | Open or manage loans | Must not escape collateral, delay, or source limits |
-| Hidden-token user or delegate | Burn and reveal visible supply | Must not create extra supply or break accounting |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| `nana-core-v6` | Rulesets, reclaim math, and surplus views stay coherent | Stage and cash-out behavior drift |
-| `nana-suckers-v6` | Remote supply/surplus snapshots are authentic | Omnichain reclaim and borrowability drift |
-| Buyback and 721 integrations | Hook composition remains consistent with revnet expectations | Pay-path and mint-permission behavior drift |
-
-## Critical Invariants
-
-1. Stage progression stays monotonic and follows deployed timing.
-2. Borrowability respects cash-out delay, surplus, supply, and source limits.
-3. Burned collateral is not accidentally treated like escrowed collateral.
-4. Hidden-token accounting preserves total claims while changing visible supply intentionally.
-5. Optional integrations do not silently widen revnet authority or mint rights.
-
-## Attack Surfaces
-
-- stage-transition boundaries
-- live borrowability and cross-currency debt aggregation
-- hidden-token burn and reveal flows
-- omnichain surplus and sucker exemptions
-- payment and cash-out hook composition in `REVOwner`
-
-## Accepted Risks Or Behaviors
-
-- Revnets intentionally trade recoverability for predictable launch-time economics.
-- Some economic surfaces are conservative by design and may refuse otherwise-valid actions rather than risk an unsafe result.
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`