@rev-net/core-v6 0.0.15 → 0.0.17

package/ADMINISTRATION.md

@@ -8,7 +8,7 @@ Admin privileges and their scope in revnet-core-v6. Revnets are designed to be a
 
 - **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.
-- **Cannot be removed:** The split operator can be replaced but there is no mechanism to entirely revoke the role (it can be set to an unreachable address like `address(0)` to effectively disable it).
+- **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)
 
@@ -85,6 +85,7 @@ These permissions are granted in the `REVDeployer` constructor and apply globall
 |---------|---------------|---------|
 | `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
 
@@ -134,6 +135,9 @@ The following parameters are set at deployment and can never be changed:
 - `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
 
 ### REVLoans (global, set at contract deployment)
 - `CONTROLLER`, `DIRECTORY`, `PRICES`, `PROJECTS` -- protocol infrastructure

package/ARCHITECTURE.md

@@ -22,33 +22,62 @@ src/
 ```
 Deployer → REVDeployer.deployFor()
   → Create JB project via JBController
-  → Convert REV stages → JBRulesetConfigs
+  → Convert REV stages → JBRulesetConfigs (see Stage-to-Ruleset Mapping below)
     → Each stage: duration, weight, cashOutTaxRate, splits
-    → Auto-issuance: pre-mint tokens to specified beneficiaries per chain
+    → Auto-issuance: record per-beneficiary token counts for later claiming
   → Set REVDeployer as data hook (controls pay + cashout behavior)
-  → Initialize buyback pools at 1:1 price, configure buyback hook
+  → 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 for cross-chain deployment verification
+  → Compute matching hash and store it for cross-chain sucker deployment
 ```
 
+#### Matching Hash
+
+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.
+
+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.
+
+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.
+
+#### Auto-Issuance
+
+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`.
+
+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.
+
+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.
+
+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.
+
 ### Data Hook Behavior
 ```
 Payment → REVDeployer.beforePayRecordedWith()
-  → Delegate to buyback hook for swap-vs-mint decision
-  → Return pay hook specifications
+  → 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 → REVDeployer.beforeCashOutRecordedWith()
-  → If caller is a sucker: 0% cash out tax (bridging privilege)
-  → Otherwise: apply configured cashOutTaxRate
-  → Return cash out hook specifications
+  → If caller is a sucker: 0% cash out tax, full reclaim (bridging privilege)
+  → Enforce cash out delay (for cross-chain deployments of existing revnets)
+  → 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)
 ```
 
 ### Loan Flow
 ```
 Borrower → REVLoans.borrowFrom()
   → Burn borrower's revnet tokens as collateral
-  → Calculate max borrow based on bonding curve value
+  → Calculate borrow amount from bonding curve value of collateral
   → Pull funds from treasury via USE_ALLOWANCE
   → Mint loan ERC-721 NFT to borrower
 
@@ -61,6 +90,31 @@ Liquidate → REVLoans.liquidateExpiredLoansFrom()
   → Collateral permanently destroyed (was burned at borrow time)
 ```
 
+## 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(REVDeployer)`
+- `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 |
@@ -79,9 +133,13 @@ Liquidate → REVLoans.liquidateExpiredLoansFrom()
 - `@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
+- 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.
 - REVDeployer is the data hook for all revnets it deploys — centralizes behavioral control
 - 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.

package/AUDIT_INSTRUCTIONS.md

@@ -10,10 +10,10 @@ Read [RISKS.md](./RISKS.md) for the trust model and known risks. Read [ARCHITECT
 
 | Contract | Lines | Role |
 |----------|-------|------|
-| `src/REVDeployer.sol` | ~1,287 | Deploys revnets. Acts as data hook and cash-out hook for all revnets. Manages stages, splits, auto-issuance, buyback hook delegation, 721 hook deployment, suckers, and split operator permissions. |
+| `src/REVDeployer.sol` | ~1,373 | Deploys revnets. Acts as data hook and cash-out hook for all revnets. Manages stages, splits, auto-issuance, buyback hook delegation, 721 hook deployment, suckers, and split operator permissions. |
 | `src/REVLoans.sol` | ~1,359 | Token-collateralized lending. Burns collateral on borrow, re-mints on repay. ERC-721 loan NFTs. Three-layer fee model. Permit2 integration. |
 | `src/interfaces/` | ~525 | Interface definitions for both contracts |
-| `src/structs/` | ~150 | All struct definitions |
+| `src/structs/` | ~212 | All struct definitions |
 
 **Dependencies (assumed correct, but verify integration points):**
 - `@bananapus/core-v6` -- JBController, JBMultiTerminal, JBTerminalStore, JBTokens, JBPrices, JBRulesets
@@ -200,7 +200,7 @@ feeAmount = JBCashOuts.cashOutFrom(surplus - postFeeReclaimedAmount, feeCashOutC
 Verify:
 - `postFeeReclaimedAmount + feeAmount <= directReclaim` (total <= what you'd get without fee splitting)
 - Micro cash-outs (< 40 wei at 2.5%) round `feeCashOutCount` to zero, bypassing the fee. This is documented as economically insignificant. Verify.
-- The `cashOutCount` returned to the terminal is `nonFeeCashOutCount`, but the terminal still burns the full `cashOutCount` tokens. **Wait, is this correct?** Trace through the terminal to verify how many tokens are actually burned.
+- The `cashOutCount` returned to the terminal is `nonFeeCashOutCount`, but the terminal still burns the full `cashOutCount` tokens. **Open question**: Does the terminal burn the full original `cashOutCount` or only the `nonFeeCashOutCount`? Trace through `JBMultiTerminal.cashOutTokensOf()` to verify. If the full count is burned, the fee tokens are effectively destroyed -- this may be intentional (fee is taken from the surplus).
 
 ### 5. Permission model
 
@@ -244,7 +244,7 @@ Three layers of fees on borrow:
 
 1. **Protocol fee (2.5%)** -- charged by `useAllowanceOf` (JBMultiTerminal takes it automatically)
 2. **REV fee (1%)** -- `JBFees.feeAmountFrom(borrowAmount, REV_PREPAID_FEE_PERCENT=10)` paid to REV revnet. Try-catch; zeroed on failure.
-3. **Source prepaid fee (2.5%-50%)** -- `JBFees.feeAmountFrom(borrowAmount, prepaidFeePercent)` paid back to the revnet via `terminal.pay`. NOT try-catch; reverts on failure.
+3. **Source prepaid fee (2.5%-50%)** -- `JBFees.feeAmountFrom(borrowAmount, prepaidFeePercent)` paid back to the revnet via `terminal.pay`. Try-catch; on failure the fee is refunded to the borrower instead of being paid to the revnet.
 
 On repay, the source fee is time-proportional:
 
@@ -260,8 +260,18 @@ sourceFeeAmount = mulDiv(fullSourceFeeAmount, amount, loan.amount);
 
 Verify:
 - The `prepaidDuration` calculation: `mulDiv(prepaidFeePercent, LOAN_LIQUIDATION_DURATION, MAX_PREPAID_FEE_PERCENT)`. At 2.5% (25), this is `25 * 3650 days / 500 = 182.5 days`. At 50% (500), it's `500 * 3650 days / 500 = 3650 days` (full duration). Is this the intended mapping?
-- The linear accrual formula: at `timeSinceLoanCreated = LOAN_LIQUIDATION_DURATION`, the fee percent approaches MAX_FEE (100%). Is this correct? The borrower would owe the full remaining loan amount as a fee, making repayment impossible.
-- Actually, at liquidation time, `_determineSourceFeeAmount` reverts with `REVLoans_LoanExpired`. So the fee approaches but never reaches 100%. Verify the revert boundary is correct: `>=` vs `>`.
+- The linear accrual formula: at `timeSinceLoanCreated = LOAN_LIQUIDATION_DURATION`, the fee percent approaches MAX_FEE (100%). The borrower would owe the full remaining loan amount as a fee, making repayment impossible.
+- At the boundary, `_determineSourceFeeAmount` reverts with `REVLoans_LoanExpired` before the fee reaches 100%. The revert uses `>` (not `>=`) so the exact boundary second is still repayable -- verify this matches the liquidation path which uses `<=`.
+
+## Invariants
+
+Fuzzable properties that should hold for all valid inputs:
+
+1. **Collateral accounting**: `totalCollateralOf[revnetId]` equals the sum of `_loanOf[loanId].collateral` for all active loans belonging to that revnet.
+2. **Borrowed amount accounting**: `totalBorrowedFrom[revnetId][terminal][token]` equals the sum of `_loanOf[loanId].amount` for all active loans with that source.
+3. **Loan NFT ownership**: The ERC-721 owner of a loan NFT is the only address authorized to repay, reallocate, or manage that loan (absent ROOT or explicit permission grants).
+4. **No flash-loan profit**: Borrowing and repaying in the same block (zero time elapsed) should never yield a net profit to the borrower after all fees.
+5. **Stage monotonicity**: Stage transitions are monotonically increasing in time -- a later stage's `startsAtOrAfter` is always strictly greater than the previous stage's.
 
 ## How to Run Tests
 
@@ -286,10 +296,83 @@ forge test --gas-report
 | Pattern | Where | Why |
 |---------|-------|-----|
 | `mulDiv` rounding direction | `beforePayRecordedWith` weight scaling, `_determineSourceFeeAmount`, `_borrowableAmountFrom` | Rounding in borrower's favor compounds over many loans |
-| Source fee `pay` without try-catch | `_adjust` line 1086 | If source fee terminal reverts, entire borrow/repay reverts (DoS) |
+| Source fee `pay` silently caught on revert | `REVLoans._adjust` try-catch block | The catch block silently returns funds to the borrower instead of paying the fee, which could allow borrowers to intentionally cause fee payment reverts to avoid paying the source fee |
 | `delete _loanOf[loanId]` after external calls | `_repayLoan`, `_reallocateCollateralFromLoan` | Verify delete happens after all references to the loan are resolved |
 | Loan storage read after `_adjust` mutates it | `_repayLoan` partial repay path | `_adjust` modifies `loan` via storage pointer; subsequent reads see mutated values |
 | Unbounded loop in `_totalBorrowedFrom` | Called during every borrow operation | Gas griefing if many distinct loan sources accumulate |
 | `uint112` truncation | `_adjust` explicit check | Verify all paths that set `loan.amount` or `loan.collateral` go through `_adjust` |
 | Permit2 try-catch swallowing | `_acceptFundsFor` | If permit fails, fall through to regular transfer. Is the state consistent? |
 | ERC-721 `_mint` callback | `borrowFrom`, `_repayLoan`, `_reallocateCollateralFromLoan` | `onERC721Received` can re-enter. Verify all state is settled before mint. |
+
+## Previous Audit Findings
+
+No prior formal audit with finding IDs has been conducted on this codebase. All risk analysis is internal. See [RISKS.md](./RISKS.md) for the trust model and known risks.
+
+## Coverage Gaps
+
+- **Stage transition during active loans**: No test for borrowing under one stage's tax rate and the stage transitioning before repayment.
+- **Multi-source loan aggregation**: `_totalBorrowedFrom` iterates all sources, but no test with >3 active sources testing gas and precision.
+- **Concurrent borrow + cash out**: No test for a borrow and cash out on the same revnet in the same block.
+- **Auto-issuance with sucker deployment**: No test for claiming auto-issuance on a cross-chain revnet during the cashOutDelay window.
+- **Partial repay + reallocation**: No test for `reallocateCollateralFromLoan` with a partial repay in the same transaction.
+- **Loan fee approaching 100%**: No test for repayment at `LOAN_LIQUIDATION_DURATION - 1 second` where the fee should be just under 100%.
+
+## Error Reference
+
+| Error | Contract | Trigger |
+|-------|----------|---------|
+| `REVDeployer_AutoIssuanceBeneficiaryZeroAddress` | REVDeployer | Auto-issuance configured with `beneficiary == address(0)` |
+| `REVDeployer_CashOutDelayNotFinished` | REVDeployer | Cash-out attempted before `cashOutDelayOf[revnetId]` timestamp has passed |
+| `REVDeployer_CashOutsCantBeTurnedOffCompletely` | REVDeployer | Stage configured with `cashOutTaxRate >= MAX_CASH_OUT_TAX_RATE` (10,000) |
+| `REVDeployer_MustHaveSplits` | REVDeployer | Stage has `splitPercent > 0` but empty `splits` array |
+| `REVDeployer_NothingToAutoIssue` | REVDeployer | `autoIssueFor` called but `amountToAutoIssue` is zero for the given beneficiary and stage |
+| `REVDeployer_NothingToBurn` | REVDeployer | `burnFrom` called but REVDeployer holds zero tokens for the revnet |
+| `REVDeployer_RulesetDoesNotAllowDeployingSuckers` | REVDeployer | `deploySuckersFor` called but current ruleset metadata disallows sucker deployment |
+| `REVDeployer_StageNotStarted` | REVDeployer | `autoIssueFor` called for a stage whose `ruleset.start > block.timestamp` |
+| `REVDeployer_StagesRequired` | REVDeployer | `deployFor` / `launchChainsFor` called with empty `stageConfigurations` array |
+| `REVDeployer_StageTimesMustIncrease` | REVDeployer | Stage `startsAtOrAfter` timestamps are not strictly increasing |
+| `REVDeployer_Unauthorized` | REVDeployer | Caller is not the split operator (for operator-gated functions) or not the project owner (for `launchChainsFor`) |
+| `REVLoans_CollateralExceedsLoan` | REVLoans | `reallocateCollateralFromLoan` called with `collateralCountToReturn > loan.collateral` |
+| `REVLoans_InvalidPrepaidFeePercent` | REVLoans | `prepaidFeePercent` outside `[MIN_PREPAID_FEE_PERCENT, MAX_PREPAID_FEE_PERCENT]` range (25-500) |
+| `REVLoans_InvalidTerminal` | REVLoans | Loan source references a terminal not registered in `JBDirectory` for the revnet |
+| `REVLoans_LoanExpired` | REVLoans | Repay/reallocation attempted after `LOAN_LIQUIDATION_DURATION` has elapsed since loan creation |
+| `REVLoans_LoanIdOverflow` | REVLoans | Loan counter for a revnet exceeds 1 trillion (namespace collision with next revnet ID) |
+| `REVLoans_NewBorrowAmountGreaterThanLoanAmount` | REVLoans | Partial repay would increase the loan's borrow amount above the original |
+| `REVLoans_NoMsgValueAllowed` | REVLoans | `msg.value > 0` sent when the loan source token is not the native token |
+| `REVLoans_NotEnoughCollateral` | REVLoans | `_reallocateCollateralFromLoan` attempts to remove more collateral than the loan holds |
+| `REVLoans_NothingToRepay` | REVLoans | `repayLoan` called with both `repayBorrowAmount == 0` and `collateralCountToReturn == 0` |
+| `REVLoans_OverMaxRepayBorrowAmount` | REVLoans | Actual repay cost (principal + accrued fee) exceeds caller's `maxRepayBorrowAmount` |
+| `REVLoans_OverflowAlert` | REVLoans | Loan amount or collateral exceeds `uint112` max, or Permit2 amount exceeds `uint160` max |
+| `REVLoans_PermitAllowanceNotEnough` | REVLoans | Permit2 allowance is less than the required transfer amount |
+| `REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows` | REVLoans | After reallocation, the remaining collateral's bonding curve value is less than the remaining borrow amount |
+| `REVLoans_SourceMismatch` | REVLoans | Repay/reallocation called with a source (token, terminal) that does not match the loan's original source |
+| `REVLoans_Unauthorized` | REVLoans | Caller is not the ERC-721 owner of the loan being managed |
+| `REVLoans_UnderMinBorrowAmount` | REVLoans | Bonding curve returns a borrow amount below the caller's `minBorrowAmount` (slippage protection) |
+| `REVLoans_ZeroBorrowAmount` | REVLoans | Bonding curve returns zero for the given collateral (e.g., zero surplus) |
+| `REVLoans_ZeroCollateralLoanIsInvalid` | REVLoans | `borrowFrom` called with `collateralCount == 0` |
+
+## Compiler and Version Info
+
+- **Solidity**: 0.8.28
+- **EVM target**: Cancun
+- **Optimizer**: via-IR, 100 runs
+- **Dependencies**: OpenZeppelin 5.x, PRBMath, Permit2, nana-core-v6, nana-721-hook-v6, nana-buyback-hook-v6, nana-suckers-v6
+- **Build**: `forge build` (Foundry)
+
+## How to Report Findings
+
+For each finding:
+
+1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **Affected contract(s)** -- exact file path and line numbers
+3. **Description** -- what is wrong, in plain language
+4. **Trigger sequence** -- step-by-step, minimal steps to reproduce
+5. **Impact** -- what an attacker gains, what a user loses (with numbers if possible)
+6. **Proof** -- code trace showing the exact execution path, or a Foundry test
+7. **Fix** -- minimal code change that resolves the issue
+
+**Severity guide:**
+- **CRITICAL**: Direct fund loss, collateral manipulation enabling undercollateralized loans, or permanent DoS.
+- **HIGH**: Conditional fund loss, loan fee bypass, or broken invariant.
+- **MEDIUM**: Value leakage, fee calculation inaccuracy, griefing.
+- **LOW**: Informational, edge-case-only with no material impact.

package/CHANGE_LOG.md

@@ -1,6 +1,14 @@
 # revnet-core-v6 Changelog (v5 -> v6)
 
-This document describes all changes between `revnet-core` (v5, Solidity 0.8.23) and `revnet-core-v6` (v6, Solidity 0.8.26).
+This document describes all changes between `revnet-core` (v5, Solidity 0.8.23) and `revnet-core-v6` (v6, Solidity 0.8.28).
+
+## Summary
+
+- **Buyback hook centralized**: Per-revnet `buybackHookOf` mapping replaced by a single immutable `BUYBACK_HOOK` registry — pools auto-initialized with default parameters during deployment.
+- **Loans simplified**: Per-revnet `loansOf` mapping replaced by a single immutable `LOANS` address; fund access limits derived automatically from terminal configurations.
+- **Every revnet gets a 721 hook**: The 4-arg `deployFor` overload auto-deploys an empty-tier 721 hook. `deployWith721sFor` merged into a 6-arg `deployFor` overload.
+- **Permission flags inverted**: `splitOperatorCan*` (opt-in) → `preventSplitOperator*` (opt-out) — permissions granted by default unless explicitly prevented.
+- **Weight scaling for tier splits**: `beforePayRecordedWith` now reduces minting weight proportionally when 721 tier splits consume part of the payment, preventing double-counting.
 
 ---
 
@@ -237,7 +245,7 @@ The following structs are identical between v5 and v6 (only `forge-lint` comment
 
 | Change | Description |
 |--------|-------------|
-| **Solidity version** | Upgraded from `0.8.23` to `0.8.26`. |
+| **Solidity version** | Upgraded from `0.8.23` to `0.8.28`. |
 | **Buyback hook architecture** | Per-revnet `buybackHookOf` mapping replaced with a single immutable `BUYBACK_HOOK` (`IJBBuybackHookRegistry`). Pools are auto-initialized for each terminal token during deployment via `_tryInitializeBuybackPoolFor`. |
 | **Loans architecture** | Per-revnet `loansOf` mapping replaced with a single immutable `LOANS` address. The deployer grants `USE_ALLOWANCE` permission to the loans contract for all revnets in the constructor (wildcard `revnetId=0`). |
 | **Constructor permissions** | v6 constructor grants three wildcard permissions: `MAP_SUCKER_TOKEN` to the sucker registry, `USE_ALLOWANCE` to the loans contract, and `SET_BUYBACK_POOL` to the buyback hook. v5 only granted `MAP_SUCKER_TOKEN`. |
@@ -245,6 +253,9 @@ The following structs are identical between v5 and v6 (only `forge-lint` comment
 | **Every revnet gets a 721 hook** | The 4-arg `deployFor` overload auto-deploys a default empty 721 hook with all split operator permissions granted. In v5, the simple `deployFor` did not deploy any 721 hook. |
 | **721 permission semantics inverted** | v5 used opt-in flags (`splitOperatorCanAdjustTiers` etc.) that conditionally pushed permissions. v6 uses opt-out flags (`preventSplitOperatorAdjustingTiers` etc.) that grant permissions by default unless prevented. |
 | **`beforePayRecordedWith` rewrite** | v5 fetched the buyback hook from `buybackHookOf[revnetId]` and the 721 hook separately, passing the 721 hook as a zero-amount `JBPayHookSpecification`. v6 queries the 721 hook first as a data hook to determine its tier split amount, reduces the payment context amount for the buyback hook query, and scales the buyback weight proportionally (`weight * projectAmount / totalAmount`) to prevent minting tokens for the split portion of payments. |
+
+> **Why weight scaling matters**: Without proportional scaling, a payment of 1 ETH where 0.3 ETH goes to tier splits would still mint tokens as if the full 1 ETH entered the treasury. The `mulDiv(weight, projectAmount, totalAmount)` formula ensures tokens are only minted for the 0.7 ETH that actually enters the project, preventing dilution of existing token holders.
+
 | **`hasMintPermissionFor` updated** | v5 checked `loansOf[revnetId]`, `buybackHookOf[revnetId]`, and suckers. v6 checks the immutable `LOANS`, the immutable `BUYBACK_HOOK`, and delegates to `BUYBACK_HOOK.hasMintPermissionFor` for buyback delegates. |
 | **Loan fund access limits simplified** | v5 derived fund access limits from `configuration.loanSources` and validated them against terminal configurations via `_matchingCurrencyOf`. v6 derives them from all terminal configurations directly (one unlimited surplus allowance per terminal+token pair). The `_matchingCurrencyOf` helper is removed. |
 | **`burnHeldTokensOf` added** | New function to burn any project tokens held by the deployer. Reverts with `REVDeployer_NothingToBurn` if the balance is zero. |
@@ -259,7 +270,7 @@ The following structs are identical between v5 and v6 (only `forge-lint` comment
 
 | Change | Description |
 |--------|-------------|
-| **Solidity version** | Upgraded from `0.8.23` to `0.8.26`. |
+| **Solidity version** | Upgraded from `0.8.23` to `0.8.28`. |
 | **Deployer dependency removed** | v5 stored `REVNETS` (`IREVDeployer`) and validated that the revnet was owned by the expected deployer via `RevnetsMismatch`. v6 does not reference the deployer at all. Validation now checks the terminal directly via `DIRECTORY.isTerminalOf`. |
 | **Constructor refactored** | v5 accepted `IREVDeployer revnets` and derived `CONTROLLER`, `DIRECTORY`, etc. from it. v6 accepts `IJBController controller` and `IJBProjects projects` directly. |
 | **Terminal validation** | `borrowFrom` now validates that the source terminal is registered in the directory for the revnet, reverting with `REVLoans_InvalidTerminal` if not. v5 validated deployer ownership instead. |
@@ -319,3 +330,5 @@ Throughout the codebase, function calls were updated to use named argument synta
 | `REVLoanSource` | `REVLoanSource` | Identical (lint comment added) |
 | `REVStageConfig` | `REVStageConfig` | Identical (lint comment added) |
 | `REVSuckerDeploymentConfig` | `REVSuckerDeploymentConfig` | Identical (lint comment added) |
+
+> **Cross-repo impact**: Uses `nana-721-hook-v6` tier splits system for NFT payment routing. Uses `nana-buyback-hook-v6` registry for automatic pool configuration. `nana-omnichain-deployers-v6` implements a similar dual-hook composition pattern. `nana-fee-project-deployer-v6` removed its buyback/loan configuration in favor of the centralized approach here.

package/README.md

@@ -52,13 +52,39 @@ Revnets are autonomous Juicebox projects with predetermined economic stages. Eac
 - **Prepaid fee model.** Borrowers choose a prepaid fee (2.5%-50%) that buys an interest-free window. After that window, a time-proportional source fee accrues.
 - **Each loan is an ERC-721 NFT.** Loans can be transferred, and expired loans (10 years) can be liquidated by anyone.
 
+#### Loan Flow
+
+```mermaid
+sequenceDiagram
+    participant Borrower
+    participant REVLoans
+    participant JBController
+    participant JBMultiTerminal
+    participant Beneficiary
+
+    Note over Borrower,Beneficiary: Borrow
+    Borrower->>REVLoans: borrowFrom(revnetId, source, collateral, ...)
+    REVLoans->>JBController: burnTokensOf(borrower, collateral)
+    REVLoans->>JBMultiTerminal: useAllowanceOf(revnetId, borrowAmount)
+    JBMultiTerminal-->>REVLoans: net funds (minus protocol fee)
+    REVLoans-->>Beneficiary: borrowed funds (minus prepaid fee)
+    REVLoans-->>Borrower: mint loan ERC-721 NFT
+
+    Note over Borrower,Beneficiary: Repay
+    Borrower->>REVLoans: repayLoan(loanId, collateralToReturn, ...)
+    REVLoans->>REVLoans: burn loan ERC-721 NFT
+    REVLoans->>JBMultiTerminal: addToBalanceOf(revnetId, repayAmount)
+    REVLoans->>JBController: mintTokensOf(beneficiary, collateral)
+    Note right of Beneficiary: Collateral tokens re-minted
+```
+
 ### Deployer Variants
 
 Every revnet gets a tiered ERC-721 hook deployed automatically — even if no tiers are configured at launch. This lets the split operator add and sell NFTs later without migration.
 
-- **Basic revnet** -- `deployFor` with stage configurations mapped to Juicebox rulesets and an empty 721 hook.
-- **Tiered 721 revnet** -- `deployFor` adds a tiered 721 pay hook with pre-configured tiers that mint NFTs as people pay.
-- **Croptop revnet** -- A tiered 721 revnet with Croptop posting criteria, allowing the public to post content.
+- **Basic revnet** -- `deployFor` with stage configurations mapped to Juicebox rulesets and an empty 721 hook. Choose this when the revnet only needs fungible token issuance and the split operator may optionally add NFT tiers later.
+- **Tiered 721 revnet** -- `deployFor` adds a tiered 721 pay hook with pre-configured tiers that mint NFTs as people pay. Choose this when the revnet should sell specific NFT tiers from day one, such as membership passes or limited editions.
+- **Croptop revnet** -- A tiered 721 revnet with Croptop posting criteria, allowing the public to post content. Choose this when the revnet should function as an open publishing platform where anyone can submit content that gets minted as NFTs according to the configured posting rules.
 
 ## Architecture
 
@@ -97,15 +123,15 @@ If `forge install` has issues, try `git submodule update --init --recursive`.
 | Command | Description |
 |---------|-------------|
 | `forge build` | Compile contracts |
-| `forge test` | Run tests (20+ test files covering deployment, lifecycle, loans, attacks, invariants) |
+| `forge test` | Run tests (55 test files covering deployment, lifecycle, loans, attacks, invariants, fork tests, regressions) |
 | `forge test -vvvv` | Run tests with full traces |
 
 ## Repository Layout
 
 ```
 src/
-  REVDeployer.sol                                # Revnet deployer + data hook (~1,287 lines)
-  REVLoans.sol                                   # Token-collateralized lending (~1,359 lines)
+  REVDeployer.sol                                # Revnet deployer + data hook (~1,373 lines)
+  REVLoans.sol                                   # Token-collateralized lending (~1,391 lines)
   interfaces/
     IREVDeployer.sol                             # Deployer interface + events
     IREVLoans.sol                                # Loans interface + events
@@ -134,7 +160,6 @@ test/
   REVLoansAttacks.t.sol                          # Flash loan, reentrancy scenarios
   REVLoans.invariants.t.sol                      # Loan fuzzing invariants
   REVLoansRegressions.t.sol                      # Loan regressions
-  TestPR09-32_*.t.sol                            # Per-PR regression tests
   helpers/
     MaliciousContracts.sol                       # Attack contract mocks
   mock/

package/RISKS.md

@@ -34,7 +34,6 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 - **100% LTV with no safety margin.** Borrowable amount equals exact bonding curve cash-out value. When `cashOutTaxRate == 0`, this is true 100% LTV. Any decrease in surplus (other cash-outs, payouts, stage transitions) makes existing loans effectively under-collateralized. The protocol has no liquidation trigger for under-collateralized loans -- only the 10-year expiry.
 - **Loans beat cash-outs above ~39% tax.** Above approximately 39.16% `cashOutTaxRate`, borrowing is more capital-efficient than cashing out because loans preserve upside while providing immediate liquidity. Based on CryptoEconLab research. This is by design but creates an incentive to borrow rather than cash out at higher tax rates, concentrating risk in the loan system.
 - **10-year free put option.** Over the loan's lifetime, if the collateral's real value drops below the borrowed amount, the borrower has no incentive to repay. The borrower keeps the borrowed funds and forfeits worthless collateral. This is equivalent to a free put option with a 10-year expiry. The protocol absorbs this loss through permanent supply reduction (burned collateral never re-minted).
-- **Surplus manipulation is economically irrational.** `_borrowableAmountFrom` reads live surplus. An attacker could inflate surplus via `addToBalanceOf`, but donations are permanent (no recovery), and the extra borrowable amount is always less than the donation. `pay` increases both surplus AND supply, neutralizing the effect. With non-zero `cashOutTaxRate`, the concave bonding curve makes this even worse for attackers.
 
 ### Stage transition edge cases
 
@@ -68,7 +67,7 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 ### Liquidation concerns
 
 - **No cascading liquidation mechanism.** There is no health factor, no margin call, and no keeper-triggered liquidation for under-collateralized loans. The only liquidation path is `liquidateExpiredLoansFrom` after 10 years. Under-collateralized loans persist indefinitely within that window.
-- **Liquidation iterates by loan number.** `liquidateExpiredLoansFrom` takes `startingLoanId` and `count`, iterating sequentially. Repaid and already-liquidated loans are skipped (`createdAt == 0`), but the caller pays gas for every skip. If a revnet has thousands of loans with sparse gaps (many repaid), liquidation becomes expensive. The `count` parameter bounds gas per call, but a malicious actor could create many small loans to increase cleanup costs. **Mitigated:** `startingLoanId + count` is now bounded to `_ONE_TRILLION` to prevent cross-revnet accounting corruption (reverts with `REVLoans_LoanIdOverflow`).
+- **Liquidation iterates by loan number.** `liquidateExpiredLoansFrom` takes `startingLoanId` and `count`, iterating sequentially. Repaid and already-liquidated loans are skipped (`createdAt == 0`), but the caller pays gas for every skip. If a revnet has thousands of loans with sparse gaps (many repaid), liquidation becomes expensive. The `count` parameter bounds gas per call, but a malicious actor could create many small loans to increase cleanup costs.
 - **Liquidation permanently destroys collateral.** Collateral was burned at borrow time. Upon liquidation, `totalCollateralOf` is decremented but no tokens are minted or returned. The collateral is permanently removed from the token supply. This deflates the total supply, increasing per-token value for remaining holders -- a mild positive externality from defaults.
 
 ### Loan source rotation after deployment
@@ -86,11 +85,6 @@ Read [ARCHITECTURE.md](./ARCHITECTURE.md) and [SKILLS.md](./SKILLS.md) for proto
 
 - **Borrowers must grant BURN_TOKENS permission before calling `borrowFrom`.** The loans contract burns the caller's tokens as collateral via `JBController.burnTokensOf`, which requires the caller to have granted `BURN_TOKENS` permission to the loans contract for the revnet's project ID. Without this, the transaction reverts deep in `JBController` with `JBPermissioned_Unauthorized`. The prerequisite is documented in `borrowFrom`'s NatSpec.
 
-### Borrow-repay arbitrage
-
-- **Immediate repayment within prepaid window incurs zero source fee.** A borrower who pays the prepaid fee upfront can repay at any time within the prepaid duration with no additional cost. The prepaid fee is the minimum 2.5% + REV fee 1% = 3.5%. If the bonding curve value of the collateral increases (e.g., from new payments into the revnet) during the prepaid window, the borrower can repay, recover their collateral, and cash out at the higher value.
-- **This is not profitable as a standalone strategy** because the 3.5% minimum fee exceeds the expected value gained from short-term surplus fluctuations. But for borrowers who need liquidity anyway, it provides free optionality.
-
 ---
 
 ## 4. Data Hook Proxy Risks
@@ -101,7 +95,7 @@ REVDeployer sits between the terminal and the actual hooks (buyback hook, 721 ho
 
 - **721 hook revert in `beforePayRecordedWith`.** The call to `IJBRulesetDataHook(tiered721Hook).beforePayRecordedWith(context)` is NOT wrapped in try-catch. If the 721 hook reverts (e.g., due to a storage corruption or out-of-gas), the entire payment reverts. This is a single point of failure for all payments to revnets with 721 hooks.
 - **Buyback hook is more resilient.** The `BUYBACK_HOOK.beforePayRecordedWith(buybackHookContext)` call is also not try-caught, but the buyback hook is a shared singleton controlled by the protocol. If it reverts, all revnets from that deployer are affected.
-- **Cash-out fee terminal revert.** In `afterCashOutRecordedWith`, the fee payment to the fee terminal IS wrapped in try-catch with a fallback to `addToBalanceOf`. If the fallback also fails, funds could be stuck in the deployer contract. However, the deployer has no withdrawal mechanism for arbitrary tokens -- only `burnHeldTokensOf` for project tokens.
+- **Cash-out fee terminal revert.** In `afterCashOutRecordedWith`, the fee payment to the fee terminal IS wrapped in try-catch with a fallback to `addToBalanceOf`. If the fallback also reverts, the entire cashout transaction reverts — no funds are stuck, but the cashout is blocked until the terminal is available.
 
 ### Sucker bypass path (0% cashout tax)
 
@@ -154,12 +148,6 @@ REVDeployer sits between the terminal and the actual hooks (buyback hook, 721 ho
 - **`_totalBorrowedFrom` iterates ALL sources on every borrow and repay.** Gas cost: ~20k per source (external `accountingContextForTokenOf` call + storage read + potential price feed call). With 10 sources, this adds ~200k gas per loan operation. With 50+ sources (unlikely but possible), operations become prohibitively expensive.
 - **Mitigation.** `borrowFrom` checks `DIRECTORY.isTerminalOf` before accepting a new source. The number of registered terminals per project is practically bounded. But nothing prevents a terminal from being registered, used for one loan, de-registered, and then a new terminal registered -- leaving stale entries in the source array.
 
-### Fee terminal unavailability
-
-- **Source fee payment in `_adjust` IS try-caught.** If `loan.source.terminal.pay` reverts when paying the source fee, the fee amount is returned to the borrower instead. This prevents a reverting terminal from blocking all loan operations.
-- **REV fee payment in `_addTo` IS try-caught.** If the REV fee terminal is unavailable, the fee is zeroed and the borrower receives it. This is graceful degradation.
-- **Cash-out fee in `afterCashOutRecordedWith` IS try-caught.** Falls back to `addToBalanceOf`. If fallback also fails, the transaction still doesn't revert (the deployer absorbs the funds, which can only be recovered via `burnHeldTokensOf` for project tokens, not arbitrary tokens).
-
 ---
 
 ## 7. Invariants to Verify
@@ -192,3 +180,27 @@ These MUST hold. Breaking any of them is a finding.
 - **Sucker privilege.** Only addresses returning `true` from `SUCKER_REGISTRY.isSuckerOf(projectId, addr)` get 0% cashout tax. No other code path grants this exemption.
 - **Loan ownership.** Only `_ownerOf(loanId)` can call `repayLoan` and `reallocateCollateralFromLoan`. The loan NFT is burned before any state changes in repayment, preventing double-use.
 - **Mint permission.** Only `LOANS`, `BUYBACK_HOOK`, buyback hook delegates (via `BUYBACK_HOOK.hasMintPermissionFor`), and suckers (via `_isSuckerOf`) can mint tokens. No other address passes the `hasMintPermissionFor` check.
+
+---
+
+## 8. Accepted Behaviors
+
+### 8.1 Suckers receive 0% cashout tax (by design)
+
+`beforeCashOutRecordedWith` returns `cashOutTaxRate = 0` for any address where `SUCKER_REGISTRY.isSuckerOf(projectId, addr)` returns true. This grants suckers the full pro-rata reclaim with no tax retention. This is intentional: suckers burn tokens on the source chain and mint equivalent tokens on the destination chain. The zero-tax path ensures bridged tokens preserve their full economic value across chains. The security boundary is the sucker registry — only addresses registered by authorized deployers (gated by `DEPLOY_SUCKERS` permission and per-stage `extraMetadata` bit 2) receive this privilege.
+
+### 8.2 No liquidation trigger for under-collateralized loans (by design)
+
+`REVLoans` has no health factor, no margin call, and no keeper-triggered liquidation. The only liquidation path is `liquidateExpiredLoansFrom` after 10 years. This is a conscious design choice: the protocol treats under-collateralized loans as free put options where the borrower forfeits worthless collateral and keeps the borrowed funds. The protocol absorbs this "loss" through permanent supply reduction (burned collateral), which is deflationary for remaining holders. A liquidation mechanism would add complexity, require oracles, and introduce MEV extraction opportunities at liquidation boundaries — all of which conflict with the revnet's minimal-trust design philosophy.
+
+### 8.3 Auto-issuance dilution is permissionless but predictable
+
+`autoIssueFor` can be called by anyone, diluting existing holders by minting pre-configured token amounts to beneficiaries. This is accepted because: (1) auto-issuance amounts are set immutably at deployment, so dilution is fully predictable, (2) the dilution only occurs once per `(revnetId, stageId, beneficiary)` tuple (single-claim guarantee), and (3) delaying the call only delays the inevitable — the configured amounts will eventually be minted. A griefing vector exists where someone calls `autoIssueFor` immediately before another user's cash-out, but the dilution magnitude is deterministic and can be priced in.
+
+### 8.4 Surplus manipulation via donations is economically irrational (by design)
+
+`_borrowableAmountFrom` reads live surplus. An attacker could inflate surplus via `addToBalanceOf`, but donations are permanent (no recovery), and the extra borrowable amount is always less than the donation. `pay` increases both surplus AND supply, neutralizing the effect. With non-zero `cashOutTaxRate`, the concave bonding curve makes this even worse for attackers. The attack is self-defeating by construction.
+
+### 8.5 Borrow-repay arbitrage is unprofitable (by design)
+
+A borrower who pays the prepaid fee upfront (minimum 2.5% + REV fee 1% = 3.5%) can repay at any time within the prepaid duration with no additional cost. If the bonding curve value of the collateral increases during the prepaid window, the borrower can repay, recover their collateral, and cash out at the higher value. This is not profitable as a standalone strategy because the 3.5% minimum fee exceeds the expected value gained from short-term surplus fluctuations. For borrowers who need liquidity anyway, it provides free optionality — which is the intended use case.