@rev-net/core-v6 0.0.24 → 0.0.25

package/ADMINISTRATION.md

@@ -2,6 +2,33 @@
 
 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, 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, 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
+
+- 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.
+
+## One-Way Or High-Risk Actions
+
+- 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.
+
+## 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.
+
 ## Roles
 
 ### Split Operator

package/ARCHITECTURE.md

@@ -1,149 +1,73 @@
-# revnet-core-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Autonomous revenue networks ("revnets") built on Juicebox V6. REVDeployer creates projects with pre-programmed multi-stage rulesets that cannot be changed after deployment. REVOwner handles all runtime hook behavior (pay hooks, cash-out hooks, mint permissions) as the `dataHook` for every revnet. REVLoans enables borrowing against locked revnet tokens.
+`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.
 
-## Contract Map
+## Boundaries
 
-```
-src/
-├── REVDeployer.sol  — Deploys revnets: stages → rulesets, buyback, suckers, 721 tiers, state storage
-├── REVOwner.sol     — Runtime data hook + cash-out hook for all revnets, stores cashOutDelayOf + tiered721HookOf (~310 lines)
-├── REVLoans.sol     — Borrow against burned revnet tokens (10-year max, permissionless liquidation)
-├── interfaces/
-│   ├── IREVDeployer.sol
-│   ├── IREVOwner.sol
-│   └── IREVLoans.sol
-└── structs/         — REVConfig, REVStageConfig, REVLoanSource, REVAutoIssuance, etc.
-```
+- `REVDeployer` owns launch-time configuration and runtime wrapper behavior.
+- `REVOwner` owns owner-like data-hook behavior for revnet projects.
+- `REVLoans` owns the loan lifecycle.
+- The repo composes several sibling repos instead of reimplementing them.
 
-## Key Data Flows
+## Main Components
 
-### Revnet Deployment
-```
-Deployer → REVDeployer.deployFor()
-  → Create JB project via JBController
-  → Convert REV stages → JBRulesetConfigs (see Stage-to-Ruleset Mapping below)
-    → Each stage: duration, weight, cashOutTaxRate, splits
-    → Auto-issuance: record per-beneficiary token counts for later claiming
-  → Set REVOwner as data hook (controls pay + cashout behavior)
-  → Initialize buyback pools at fair issuance price (derived from initialIssuance)
-  → Deploy suckers for cross-chain operation
-  → Deploy tiered ERC-721 hook (always — empty by default, pre-configured if specified)
-  → Compute matching hash and store it for cross-chain sucker deployment
-```
+| 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 |
+| config structs | Stage, auto-issuance, loan source, and 721-hook configuration surfaces |
 
-#### Matching Hash
+## Runtime Model
 
-The matching hash ensures that revnet deployments on different chains share identical economic parameters. It is computed inside `_makeRulesetConfigurations` by incrementally ABI-encoding the configuration fields, then taking the `keccak256` of the result.
+### Revnet Lifecycle
 
-Fields included in the hash (in encoding order):
-1. **Base fields:** `baseCurrency`, `description.name`, `description.ticker`, `description.salt`
-2. **Per-stage fields** (appended for each stage): `startsAtOrAfter` (defaults to `block.timestamp` for the first stage if zero), `splitPercent`, `initialIssuance`, `issuanceCutFrequency`, `issuanceCutPercent`, `cashOutTaxRate`
-3. **Per-auto-issuance fields** (appended for each auto-issuance within a stage): `chainId`, `beneficiary`, `count`
-
-The hash is stored in `hashedEncodedConfigurationOf[revnetId]` and used as part of the CREATE2 salt when deploying suckers via `SUCKER_REGISTRY.deploySuckersFor`. This guarantees that cross-chain sucker peers can only be deployed for revnets whose economic configuration matches exactly — a deployment on Chain B with different stage parameters would produce a different hash, a different salt, and therefore a different sucker address, preventing it from peering with Chain A's suckers.
+```text
+creator
+  -> deploys a revnet with a fixed sequence of stages
+stage transitions
+  -> happen automatically over time through ruleset activation
+participants
+  -> pay in, receive tokens, cash out, and interact with downstream hooks
+operators or permissionless callers
+  -> perform bounded maintenance actions such as auto-issuance claims
+```
 
-Note that `splits` (the specific split recipient addresses) are **not** included in the hash. Splits may contain chain-specific addresses, so they are excluded to allow legitimate cross-chain deployments where the only difference is the split recipient addresses.
+### Loan Lifecycle
 
-#### Auto-Issuance
+```text
+borrower
+  -> burns revnet tokens as collateral
+  -> receives funds from the treasury through REVLoans
+  -> later repays to remint collateral
+  -> or gets liquidated after the long expiration window
+```
 
-Auto-issuance pre-allocates tokens to specified beneficiaries when a stage begins. Each `REVAutoIssuance` entry specifies a `chainId`, a `beneficiary` address, and a token `count`.
+## Critical Invariants
 
-During deployment, the deployer records auto-issuance amounts in `amountToAutoIssue[revnetId][stageId][beneficiary]` — but only for entries whose `chainId` matches `block.chainid`. Entries for other chains are still included in the matching hash (ensuring cross-chain consistency) but are skipped for on-chain storage.
+- 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.
+- `REVOwner` and `REVDeployer` are tightly coupled. Their setup order is part of correctness.
 
-Claiming is a separate step: anyone can call `autoIssueFor(revnetId, stageId, beneficiary)` after the stage has started. This function verifies the stage's ruleset has begun (`ruleset.start <= block.timestamp`), zeroes the stored amount, and calls `CONTROLLER.mintTokensOf` to mint tokens directly to the beneficiary — bypassing the reserved percent so the full count goes to the beneficiary.
+## Where Complexity Lives
 
-Stage IDs are assigned as `block.timestamp + i` (where `i` is the stage index), matching the JBRulesets ID assignment scheme when all stages are queued in a single transaction.
+- 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.
 
-### Data Hook Behavior (REVOwner)
-```
-Payment → REVOwner.beforePayRecordedWith()
-  → Read tiered721HookOf from REVOwner storage
-  → Query 721 tier hook for tier split specs (if configured)
-  → Delegate remaining amount to buyback hook for swap-vs-mint decision
-  → Scale weight so tokens are only minted for the project's share (after tier splits)
-  → Return merged hook specifications (721 hook + buyback hook)
-
-Cash Out → REVOwner.beforeCashOutRecordedWith()
-  → If caller is a sucker: 0% cash out tax, full reclaim (bridging privilege)
-  → Enforce cash out delay (reads cashOutDelayOf from REVOwner storage)
-  → If no tax, no fee terminal, or feeless beneficiary: delegate directly to buyback hook
-  → Otherwise: split tokens into fee/non-fee portions via bonding curve
-  → Delegate non-fee portion to buyback hook
-  → Build fee hook spec routing fee amount to afterCashOutRecordedWith for processing
-  → Return merged hook specifications (buyback hook + fee hook)
-```
+## Dependencies
 
-### Loan Flow
-```
-Borrower → REVLoans.borrowFrom()
-  → Enforce cash-out delay if set (cross-chain deployment protection)
-  → Burn borrower's revnet tokens as collateral
-  → Calculate borrow amount from bonding curve value of collateral
-  → Pull funds from treasury via USE_ALLOWANCE
-  → Mint loan ERC-721 NFT to borrower
-
-Repay → REVLoans.repayLoan()
-  → Accept repayment (principal + prepaid fee)
-  → Re-mint collateral tokens to borrower
-
-Liquidate → REVLoans.liquidateExpiredLoansFrom()
-  → After 10-year term, anyone can liquidate
-  → Collateral permanently destroyed (was burned at borrow time)
-```
+- `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
 
-## Stage-to-Ruleset Mapping
-
-Each `REVStageConfig` is converted to a `JBRulesetConfig` by `_makeRulesetConfiguration`. The mapping is direct — revnet stages are a constrained interface over Juicebox rulesets:
-
-| REVStageConfig field | JBRulesetConfig field | Notes |
-|---|---|---|
-| `startsAtOrAfter` | `mustStartAtOrAfter` | Passed through directly |
-| `issuanceCutFrequency` | `duration` | How often the issuance rate decays |
-| `initialIssuance` | `weight` | Tokens per unit of base currency |
-| `issuanceCutPercent` | `weightCutPercent` | Percent decrease each cycle (out of 1,000,000,000) |
-| `splitPercent` | `metadata.reservedPercent` | Percent of new tokens split to recipients (out of 10,000) |
-| `cashOutTaxRate` | `metadata.cashOutTaxRate` | Bonding curve tax on cash outs (out of 10,000) |
-| `splits` | `splitGroups[0].splits` | Reserved token split recipients (group ID: RESERVED_TOKENS) |
-| `extraMetadata` | `metadata.metadata` | 14-bit field for hook-specific flags |
-
-Fields set automatically by the deployer (not configurable per stage):
-- `metadata.baseCurrency` — from `REVConfig.baseCurrency`
-- `metadata.useTotalSurplusForCashOuts` — always `true`
-- `metadata.allowOwnerMinting` — always `true` (required for auto-issuance)
-- `metadata.useDataHookForPay` — always `true`
-- `metadata.useDataHookForCashOut` — always `true`
-- `metadata.dataHook` — always `address(REVOwner)`
-- `approvalHook` — always `address(0)` (no approval hook; stages are immutable)
-- `fundAccessLimitGroups` — set to `uint224.max` surplus allowance per terminal token for loan withdrawals
-
-## Extension Points
-
-| Point | Interface | Purpose |
-|-------|-----------|---------|
-| Data hook | `IJBRulesetDataHook` | REVOwner acts as data hook for all revnets |
-| Buyback hook | `IJBBuybackHook` | Swap-vs-mint decision on payments |
-| Sucker integration | `IJBSucker` | Cross-chain token bridging |
-| 721 tiers | `IJB721TiersHook` | NFT tier rewards |
+## Safe Change Guide
 
-## Dependencies
-- `@bananapus/core-v6` — Core protocol
-- `@bananapus/721-hook-v6` — NFT tiers
-- `@bananapus/buyback-hook-v6` — DEX buyback
-- `@bananapus/suckers-v6` — Cross-chain bridging
-- `@bananapus/router-terminal-v6` — Payment routing
-- `@bananapus/permission-ids-v6` — Permission constants
-- `@croptop/core-v6` — Croptop integration
-- `@openzeppelin/contracts` — Standard utilities
-- `@prb/math` — Fixed-point math (`mulDiv`, `sqrt`)
-- `@uniswap/permit2` — Permit2 token allowances (REVLoans)
-
-## Key Design Decisions
-- Stages are immutable after deployment — no owner can change ruleset parameters
-- Matching hash ensures cross-chain deployments have identical economic parameters. It covers all economic fields (issuance, decay, tax rates, auto-issuances) but intentionally excludes split recipient addresses, which may differ by chain. The hash is used as a CREATE2 salt component for sucker deployment, so mismatched configs produce different sucker addresses that cannot peer with each other.
-- REVOwner is the data hook for all revnets — centralizes runtime behavioral control (pay hooks, cash-out hooks, mint permissions) and stores `cashOutDelayOf` and `tiered721HookOf` per revnet. REVDeployer handles deployment and configuration state storage. The split was necessary to stay under the EIP-170 contract size limit (24,576 bytes). Deploy order: REVOwner first, then REVDeployer(owner=REVOwner) -- the constructor calls `REVOwner.setDeployer()` atomically. REVDeployer calls DEPLOYER-restricted setters on REVOwner (`setCashOutDelayOf`, `setTiered721HookOf`) during deployment.
-- Loans use bonding curve value, not market price — independent of external DEX pricing
-- Auto-issuance is deferred, not instant — token amounts are recorded at deploy time but minted via a separate `autoIssueFor` call after the stage starts. This separates deployment from issuance, allows anyone to trigger the mint permissionlessly, and ensures tokens are not minted before their stage is active.
-- No approval hook — revnet rulesets set `approvalHook` to `address(0)` because stages are configured immutably at deployment. There is no governance or owner who could queue a change that would need approval.
+- 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.
+- 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.