@rev-net/core-v6 0.0.37 → 0.0.40

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`

package/RISKS.md

@@ -1,107 +0,0 @@
-# Revnet Core Risk Register
-
-This file focuses on the staged-economics, runtime-hook, hidden-supply, and loan risks that matter in Revnets. The main question is whether the deployed economic shape still holds under real runtime behavior.
-
-## How to use this file
-
-- Read `Priority risks` first.
-- Use the detailed sections to separate stage design, hook composition, hidden supply, and loan accounting.
-- Treat `Accepted Behaviors` and `Invariants to Verify` as the line between intended product tradeoffs and defects.
-
-## Priority risks
-
-| Priority | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P0 | Borrowability drift from live surplus or cross-chain state | Loans can overextend or under-credit if revnet state is read incorrectly. | Borrowability tests, omnichain-state checks, and cash-out-delay gating. |
-| P1 | Stage configuration mistakes | Revnet economics are hard to change after launch, so bad stages are expensive. | Deployment review, stage-transition tests, and launch-time validation. |
-| P1 | Hidden-supply and burned-collateral misunderstandings | Hidden tokens and loans both change visible supply in non-obvious ways. | Explicit supply invariants and product-level review. |
-
-## 1. Trust Assumptions
-
-- **`REVDeployer` and `REVOwner` are one design.** Misreading them independently is a review hazard.
-- **Core protocol state is still upstream truth.** Revnet economics sit on top of `nana-core-v6`, not outside it.
-- **Optional integrations matter.** Buybacks, 721 hooks, and suckers can materially change runtime behavior.
-- **Price feeds and source accounting matter for loans.** Cross-currency debt aggregation depends on working feed assumptions.
-
-## 2. Economic Risks
-
-- **Stage immutability cuts both ways.** A bad stage schedule or bad cash-out tax choice is expensive to unwind.
-- **Borrowability depends on live economics.** If surplus, supply, or cross-chain state are wrong, loan capacity becomes wrong.
-- **Zero or degraded price feeds can undercount debt.** If a source becomes invisible to debt aggregation, later borrowing can become too permissive. Specifically, `_debtOf` skips sources where `pricePerUnitOf` returns zero, treating them as if the borrower has no debt in that source. If a feed breaks or returns zero, existing debt in that currency is effectively invisible, inflating the borrower's apparent borrowable amount.
-- **Hidden-token mechanics change visible supply.** That affects per-token cash-out value and can change the economics seen by other holders.
-- **Auto-issuance dilutes holders predictably but still materially.** Timing is permissionless, even if the amounts are fixed at deployment.
-- **Omnichain expansion can corrupt surplus aggregation.** Since borrowability aggregates surplus from all registered terminals across chains, a compromised or misconfigured terminal on a remote chain affects global surplus accounting.
-
-## 3. Loan Risks
-
-- **Burned collateral is not escrow.** Reviewers and integrators who model it as escrow will misread liquidation and repayment behavior.
-- **No short-term liquidation model.** Under-collateralized loans can persist until the long expiry model allows cleanup.
-- **Loan sources grow over time.** Debt aggregation cost and complexity increase as new source pairs are used.
-- **Reallocation still depends on live state.** Reallocate flows can change outcomes around stage boundaries.
-
-## 4. Hidden-Token Risks
-
-- **Visible-supply manipulation is intentional.** Hiding tokens changes visible supply and therefore changes redemption economics.
-- **Hidden tokens are not usable collateral while hidden.** They must be revealed before borrowing.
-- **Reveal is restoration, not fresh issuance.** It intentionally bypasses reserved-percent behavior.
-
-## 5. Hook-Composition Risks
-
-- **`REVOwner` is a real runtime authority surface.** It composes pay hooks, cash-out hooks, sucker exemptions, and fee logic.
-- **Suckers can bypass tax and fee paths by design.** That privilege is safe only if registry and deployer assumptions are correct.
-- **Mint-permission surfaces are broad enough to matter.** Loans, hidden tokens, buyback flows, and suckers all touch mint authority in some deployments.
-
-## 6. Access-Control Risks
-
-- **The deployer-held project NFT can be misunderstood.** Revnets are owner-minimized, but the deployer path still matters for the trust model.
-- **Split operator mistakes are high-impact.** Narrow powers like price-feed installation, split updates, sucker deployment, or router setup still matter.
-- **There is intentionally no broad admin recovery path.** Operational teams may try to reach for powers the design never intended to leave available.
-
-## 7. Invariants to Verify
-
-- Collateral and debt conservation across all active loans.
-- Stage immutability after deployment.
-- Borrowability dropping to zero when cash-out delay should still block borrowing.
-- Hidden-balance conservation across hide and reveal flows.
-- Sucker-only privileges staying restricted to real registered suckers.
-- Mint permission remaining limited to the documented runtime surfaces.
-
-## 8. Accepted Behaviors
-
-### 8.1 Suckers receive 0% cash-out tax
-
-Trusted suckers are intentionally exempt so bridged value preserves its economic meaning across chains.
-
-### 8.2 There is no short-horizon liquidation model
-
-Revnet loans are designed more like long-dated economic positions than instantly mark-to-market margin loans.
-
-### 8.3 Auto-issuance dilution is permissionless but predictable
-
-Anyone can trigger a valid auto-issuance once a stage is live, but the amount was fixed at deployment.
-
-### 8.4 Surplus manipulation by pure donation is economically self-defeating
-
-The model assumes that attempts to inflate surplus through donations are not profitable once the surrounding bonding-curve math is considered.
-
-### 8.5 Omnichain terminal expansion inherits remote-chain trust
-
-A project that expands to a new chain can register additional terminals on that chain. Because borrowability calculations aggregate surplus from all registered terminals across all chains, a compromised or misconfigured terminal on a remote chain can corrupt the project's surplus accounting globally. This is mitigated by including terminal addresses in the `encodedConfigurationHash` — cross-chain expansions via suckers must use the exact same terminal address as the host chain. Terminal addresses are deterministic across chains (same CREATE2 deployment), so this prevents expansions from silently using a different terminal. Project operators should still treat each chain expansion as a trust-boundary decision since bridge integrity and network assumptions remain outside protocol control.
-
-### 8.6 Cross-chain surplus staleness
-
-`REVLoans._borrowableAmountFrom` and `REVOwner.beforeCashOutRecordedWith` add `remoteSurplusOf()` and `remoteTotalSupplyOf()` to local values. These remote values update only when `toRemote()` is called on the peer chain -- no heartbeat or staleness check. Stale data can inflate per-token borrowable amounts when remote supply has grown since the last bridge message. Primary safeguard: borrowable is capped at `localSurplus` (REVLoans line 386-387), preventing extraction beyond what the local terminal holds.
-
-### 8.7 REVLoans CEI violation in `_adjust`
-
-In `REVLoans._adjust`, `totalCollateralOf[revnetId]` is incremented after external calls (`useAllowanceOf`, fee payment). A reentrant `borrowFrom` would see a lower `totalCollateralOf`. This is documented inline (lines 1128-1132) and requires an adversarial pay hook on the revnet's own terminal -- a trust-level configuration that is not realistic in standard deployments.
-
-### 8.8 Remote loan corrections not reflected in local borrowability
-
-`_borrowableAmountFrom` adds back local `totalBorrowed` and `totalCollateral` to reconstitute pre-loan economic state for the bonding curve. However, remote chain snapshots (built by `JBSuckerLib.buildSnapshotMessage`) capture raw surplus/supply WITHOUT loan corrections from the remote chain. This is accepted because:
-
-1. Suckers are a general-purpose bridging layer and should not need knowledge of revnet-specific loan mechanics.
-2. The `localSurplus` cap (REVLoans line 386-387) prevents extraction beyond what the local terminal actually holds.
-3. The over-lending exposure is bounded by the difference between corrected and uncorrected remote values, which is proportional to remote outstanding loans — typically a small fraction of total surplus.
-
-Project operators deploying cross-chain revnets with active loan markets on multiple chains should understand that local borrowability calculations do not account for remote outstanding loans.

package/SKILLS.md

@@ -1,46 +0,0 @@
-# Revnet Core
-
-## Use This File For
-
-- Use this file when the task involves revnet deployment, staged issuance, split-operator logic, auto-issuance, hidden tokens, or the revnet loan system.
-- Start here, then decide whether the issue is really in `REVDeployer`, `REVOwner`, `REVLoans`, or `REVHiddenTokens`.
-
-## Read This Next
-
-| If you need... | Open this next |
-|---|---|
-| Repo overview and operator flow | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Deployment and stage config | [`src/REVDeployer.sol`](./src/REVDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Runtime owner and data-hook behavior | [`src/REVOwner.sol`](./src/REVOwner.sol), [`references/runtime.md`](./references/runtime.md) |
-| Loan accounting and liquidation behavior | [`src/REVLoans.sol`](./src/REVLoans.sol) |
-| Temporary token hiding and supply exclusion | [`src/REVHiddenTokens.sol`](./src/REVHiddenTokens.sol) |
-| Types and helpers | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/), [`test/helpers/`](./test/helpers/) |
-| Lifecycle, loans, and economic proofs | [`test/REVLifecycle.t.sol`](./test/REVLifecycle.t.sol), [`test/REVLoansRegressions.t.sol`](./test/REVLoansRegressions.t.sol), [`test/REVLoans.invariants.t.sol`](./test/REVLoans.invariants.t.sol), [`test/TestLongTailEconomics.t.sol`](./test/TestLongTailEconomics.t.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contracts | [`src/`](./src/) |
-| Scripts | [`script/`](./script/) |
-| Types | [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-Deploy and manage Revnets: autonomous Juicebox project shapes with staged issuance schedules, optional buyback pools, cross-chain suckers, hidden-token mechanics, and token-collateralized lending.
-
-## Reference Files
-
-- Open [`references/runtime.md`](./references/runtime.md) for contract roles, deploy/runtime entrypoints, integration points, and key structs.
-- Open [`references/operations.md`](./references/operations.md) for events, errors, constants, storage, gotchas, and state-reading recipes.
-
-## Working Rules
-
-- Start in `REVDeployer` for launch-time behavior, `REVOwner` for runtime hook behavior, `REVLoans` for debt accounting, and `REVHiddenTokens` for supply exclusion.
-- Revnets are intentionally ownerless after deployment. Treat any admin-recovery instinct as suspect unless the code proves it.
-- `REVOwner` is not a minor helper; it is a live runtime policy surface.
-- Loan collateral is burned and re-minted, not escrowed. Any change that assumes escrow semantics is likely wrong.
-- Cash-out delay is enforced in both runtime cash-outs and loan borrowing. If one path changes without the other, the protection is broken.
-- Hidden tokens are supply exclusion, not a side balance.
-- Loan behavior, stage transitions, hidden supply, and split-weight adjustments interact. Do not treat them as independent subsystems.