@rev-net/core-v6 0.0.12 → 0.0.14

package/AUDIT_INSTRUCTIONS.md

@@ -0,0 +1,295 @@
+# Audit Instructions -- revnet-core-v6
+
+You are auditing the Revnet + Loans system for Juicebox V6. Revnets are autonomous, ownerless Juicebox projects with pre-programmed multi-stage tokenomics. REVLoans enables borrowing against locked revnet tokens using the bonding curve as the sole collateral valuation mechanism.
+
+Read [RISKS.md](./RISKS.md) for the trust model and known risks. Read [ARCHITECTURE.md](./ARCHITECTURE.md) for the system overview. Read [SKILLS.md](./SKILLS.md) for the complete function reference. Then come back here.
+
+## Scope
+
+**In scope:**
+
+| 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/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 |
+
+**Dependencies (assumed correct, but verify integration points):**
+- `@bananapus/core-v6` -- JBController, JBMultiTerminal, JBTerminalStore, JBTokens, JBPrices, JBRulesets
+- `@bananapus/721-hook-v6` -- IJB721TiersHook, IJB721TiersHookDeployer
+- `@bananapus/buyback-hook-v6` -- IJBBuybackHookRegistry
+- `@bananapus/suckers-v6` -- IJBSuckerRegistry
+- `@croptop/core-v6` -- CTPublisher
+- `@openzeppelin/contracts` -- ERC721, ERC2771Context, Ownable, SafeERC20
+- `@uniswap/permit2` -- IPermit2, IAllowanceTransfer
+- `@prb/math` -- mulDiv
+
+## The System in 90 Seconds
+
+A **revnet** is a Juicebox project that nobody owns. REVDeployer deploys it, permanently holds its project NFT, and acts as the data hook for all payments and cash-outs. The revnet's economics are encoded as a sequence of **stages** that map 1:1 to Juicebox rulesets. Stages are immutable after deployment.
+
+Each stage defines:
+- **Initial issuance** (`initialIssuance`): tokens minted per unit of base currency
+- **Issuance decay** (`issuanceCutFrequency` + `issuanceCutPercent`): how issuance decreases over time
+- **Cash-out tax** (`cashOutTaxRate`): bonding curve parameter (0 = no tax, 9999 = max allowed)
+- **Split percent** (`splitPercent`): percentage of minted tokens sent to reserved splits
+- **Auto-issuances**: pre-configured token mints that can be claimed once per stage per beneficiary
+
+**REVLoans** lets users borrow against their revnet tokens:
+1. Burn tokens as collateral
+2. Borrow up to the bonding curve cash-out value of those tokens
+3. Pay a three-layer fee (2.5% protocol + 1% REV + 2.5%-50% source prepaid)
+4. Receive an ERC-721 representing the loan
+5. Repay anytime to re-mint collateral tokens
+6. After 10 years, anyone can liquidate (collateral permanently lost)
+
+## How Revnets Interact with Juicebox Core
+
+Understanding this interaction is essential. REVDeployer wraps core Juicebox functions with revnet-specific logic.
+
+### Payment Flow
+
+```
+User pays terminal
+  -> Terminal calls JBTerminalStore.recordPaymentFrom()
+    -> Store calls REVDeployer.beforePayRecordedWith() [data hook]
+      -> REVDeployer calls 721 hook's beforePayRecordedWith() for split specs
+      -> REVDeployer calls buyback hook's beforePayRecordedWith() for swap decision
+      -> REVDeployer scales weight: mulDiv(weight, projectAmount, totalAmount)
+      -> Returns merged specs: [721 hook spec, buyback hook spec]
+    -> Store records payment with modified weight
+  -> Terminal mints tokens via Controller
+  -> Terminal executes pay hook specs (721 hook first, then buyback hook)
+```
+
+**Key insight:** The weight scaling in `beforePayRecordedWith` ensures the terminal only mints tokens proportional to the amount entering the project (excluding 721 tier split amounts). Without this scaling, payers would get token credit for the split portion too.
+
+### Cash-Out Flow
+
+```
+User cashes out via terminal
+  -> Terminal calls JBTerminalStore.recordCashOutFor()
+    -> Store calls REVDeployer.beforeCashOutRecordedWith() [data hook]
+      -> If sucker: return 0% tax, full amount (fee exempt)
+      -> If cashOutDelay not passed: revert
+      -> If cashOutTaxRate == 0 or no fee terminal: return as-is
+      -> Otherwise: split cashOutCount into fee portion + non-fee portion
+        -> Compute reclaim for non-fee portion via bonding curve
+        -> Compute fee amount via bonding curve on remaining surplus
+        -> Return modified cashOutCount + hook spec for fee payment
+    -> Store records cash-out with modified parameters
+  -> Terminal burns tokens
+  -> Terminal transfers reclaimed amount to user
+  -> Terminal calls REVDeployer.afterCashOutRecordedWith() [cash-out hook]
+    -> REVDeployer pays fee to fee revnet terminal
+    -> On failure: returns funds to originating project
+```
+
+**Key insight:** The cash-out fee is computed as a two-step bonding curve calculation, not a simple percentage of the reclaimed amount. This is because burning fewer tokens (non-fee portion) changes the surplus-to-supply ratio for the fee portion.
+
+### Loan Flow
+
+```
+Borrower calls REVLoans.borrowFrom()
+  -> Prerequisite: caller must have granted BURN_TOKENS permission to REVLoans via JBPermissions
+  -> Validate: collateral > 0, terminal registered, prepaidFeePercent in range
+  -> Generate loan ID: revnetId * 1T + loanNumber
+  -> Create loan in storage
+  -> Calculate borrowAmount via bonding curve:
+    -> totalSurplus = aggregate from all terminals
+    -> totalBorrowed = aggregate from all loan sources
+    -> borrowable = JBCashOuts.cashOutFrom(surplus + borrowed, collateral, supply + totalCollateral, taxRate)
+  -> Calculate source fee: JBFees.feeAmountFrom(borrowAmount, prepaidFeePercent)
+  -> _adjust():
+    -> Write loan.amount and loan.collateral to storage (CEI)
+    -> _addTo(): pull funds via useAllowanceOf, pay REV fee, transfer to beneficiary
+    -> _addCollateralTo(): burn collateral tokens via Controller
+    -> Pay source fee to terminal
+  -> Mint loan ERC-721 to borrower
+```
+
+**Key insight:** `_borrowableAmountFrom` includes `totalBorrowed` in the surplus calculation (`surplus + totalBorrowed`) and `totalCollateral` in the supply calculation (`totalSupply + totalCollateral`). This means outstanding loans don't reduce the borrowable amount for new loans -- the virtual surplus and virtual supply are used.
+
+## Key State Variables
+
+### REVDeployer Storage
+
+| Variable | Purpose | Audit Focus |
+|----------|---------|-------------|
+| `amountToAutoIssue[revnetId][stageId][beneficiary]` | Premint tokens per stage per beneficiary | Single-claim enforcement (zeroed before mint) |
+| `cashOutDelayOf[revnetId]` | Timestamp when cash-outs unlock | Applied only for existing revnets deployed to new chains |
+| `hashedEncodedConfigurationOf[revnetId]` | Config hash for cross-chain sucker validation | Gap: does NOT cover terminal configs |
+| `tiered721HookOf[revnetId]` | 721 hook address | Set once during deploy, never changed |
+| `_extraOperatorPermissions[revnetId]` | Custom permissions for split operator | Set during deploy based on 721 hook prevention flags |
+
+### REVLoans Storage
+
+| Variable | Purpose | Audit Focus |
+|----------|---------|-------------|
+| `_loanOf[loanId]` | Per-loan state (REVLoan struct) | Deleted on repay/liquidate; verify no stale reads |
+| `totalCollateralOf[revnetId]` | Sum of all burned collateral for a revnet | Must match sum of active loan collaterals |
+| `totalBorrowedFrom[revnetId][terminal][token]` | Total debt per loan source | Must match sum of active loan amounts per source |
+| `totalLoansBorrowedFor[revnetId]` | Monotonically increasing loan counter | Used for loan ID generation; never decrements |
+| `isLoanSourceOf[revnetId][terminal][token]` | Whether a source has been used | Only set to true, never back to false |
+| `_loanSourcesOf[revnetId]` | Array of all loan sources | Only grows; iterated in `_totalBorrowedFrom` |
+
+### REVLoan Struct (packed storage)
+
+```solidity
+struct REVLoan {
+    uint112 amount;          // Borrowed amount in source token's decimals
+    uint112 collateral;      // Number of revnet tokens burned as collateral
+    uint48  createdAt;       // Block timestamp when loan was created
+    uint16  prepaidFeePercent; // Fee percent prepaid (25-500, out of MAX_FEE=1000)
+    uint32  prepaidDuration;   // Seconds of interest-free window
+    REVLoanSource source;    // (token, terminal) pair
+}
+```
+
+**Note:** `uint112` max is ~5.19e33. Amounts above this are checked in `_adjust` and revert with `REVLoans_OverflowAlert`.
+
+## Priority Audit Areas
+
+Audit in this order. Earlier items have higher blast radius:
+
+### 1. Loan collateral valuation and manipulation
+
+The bonding curve is the sole collateral oracle. Verify:
+
+- `_borrowableAmountFrom` correctly aggregates surplus across all terminals
+- `totalBorrowed` and `totalCollateral` adjustments in the virtual surplus/supply calculation are correct
+- Stage transitions don't allow arbitrage (borrow under old tax rate, benefit from new rate)
+- Rounding in `JBCashOuts.cashOutFrom` doesn't favor the borrower
+- Cross-currency aggregation in `_totalBorrowedFrom` handles decimal normalization correctly
+- Price feed failures (zero price) are handled gracefully (sources skipped, not reverted)
+
+### 2. CEI pattern in loan operations
+
+No reentrancy guard. Verify the CEI ordering in:
+
+- `_adjust`: writes `loan.amount` and `loan.collateral` before `_addTo` / `_removeFrom` / `_addCollateralTo` / `_returnCollateralFrom`
+- `borrowFrom`: `_adjust` before `_mint` (ERC-721 onReceived callback)
+- `repayLoan`: `_burn` before `_adjust` before `_mint` (for partial repay)
+- `reallocateCollateralFromLoan`: `_reallocateCollateralFromLoan` before `borrowFrom` -- two full loan operations in sequence
+- `liquidateExpiredLoansFrom`: `_burn` and `delete` before storage updates
+
+**Specific concern:** In `reallocateCollateralFromLoan`, the reallocation creates a new loan NFT and then `borrowFrom` creates another. Between these two operations, tokens are minted back to the caller (returned collateral) which are then immediately burned (new loan collateral). If `borrowFrom` triggers an external callback (via pay hooks or the ERC-721 mint), can the caller manipulate state between the two operations?
+
+### 3. Data hook composition
+
+REVDeployer proxies between the terminal and two hooks. Verify:
+
+- The 721 hook's `beforePayRecordedWith` is called with the full context, but the buyback hook's is called with a reduced amount. Is this always correct?
+- When the 721 hook returns specs with `amount >= context.amount.value`, `projectAmount` is 0 and weight is 0. This means no tokens are minted by the terminal (all funds go to 721 splits). Verify this is safe -- does the buyback hook handle a zero-amount context gracefully?
+- The `hookSpecifications` array sizing assumes at most one spec from each hook. Verify neither hook can return multiple specs.
+- The weight scaling `mulDiv(weight, projectAmount, context.amount.value)` -- can this produce a weight of 0 when it shouldn't, or a weight > 0 when it should be 0?
+
+### 4. Cash-out fee calculation
+
+The two-step bonding curve fee calculation in `beforeCashOutRecordedWith`:
+
+```solidity
+feeCashOutCount = mulDiv(cashOutCount, FEE, MAX_FEE)  // 2.5% of tokens
+nonFeeCashOutCount = cashOutCount - feeCashOutCount
+
+postFeeReclaimedAmount = JBCashOuts.cashOutFrom(surplus, nonFeeCashOutCount, totalSupply, taxRate)
+feeAmount = JBCashOuts.cashOutFrom(surplus - postFeeReclaimedAmount, feeCashOutCount, totalSupply - nonFeeCashOutCount, taxRate)
+```
+
+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.
+
+### 5. Permission model
+
+REVDeployer grants wildcard permissions during construction:
+
+```solidity
+constructor() {
+    _setPermission(SUCKER_REGISTRY, 0, MAP_SUCKER_TOKEN);     // All revnets
+    _setPermission(LOANS, 0, USE_ALLOWANCE);                   // All revnets
+    _setPermission(BUYBACK_HOOK, 0, SET_BUYBACK_POOL);        // All revnets
+}
+```
+
+These are projectId=0 (wildcard) permissions. Verify:
+- `JBPermissions` resolves wildcard correctly -- these grant the permission for ALL revnets owned by REVDeployer, not just project 0
+- The LOANS contract can call `useAllowanceOf` on any revnet's terminal -- verify this is constrained by the bonding curve calculation in `borrowFrom`
+- No other permission is granted at wildcard level
+
+### 6. Auto-issuance timing
+
+Stage IDs computed during deployment must match JBRulesets-assigned IDs:
+
+```solidity
+amountToAutoIssue[revnetId][block.timestamp + i][beneficiary] += count;
+```
+
+Later claimed via:
+```solidity
+(JBRuleset memory ruleset,) = CONTROLLER.getRulesetOf(revnetId, stageId);
+if (ruleset.start > block.timestamp) revert REVDeployer_StageNotStarted(stageId);
+```
+
+Verify:
+- JBRulesets assigns IDs as `latestId >= block.timestamp ? latestId + 1 : block.timestamp`. Does this produce `block.timestamp, block.timestamp+1, block.timestamp+2, ...` when all stages are queued in one transaction?
+- What if another contract queued a ruleset for the same project in the same block? (Shouldn't be possible since REVDeployer owns the project, but verify.)
+- `getRulesetOf` returns the ruleset by ID. If the stage hasn't started yet, `ruleset.start` is the derived start time, not the queue time. The timing guard uses `ruleset.start`, which is correct. But what if `startsAtOrAfter` is 0 for the first stage and `block.timestamp` is used? The stage starts immediately -- can auto-issuance be claimed in the same transaction as deployment?
+
+### 7. Loan fee model
+
+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.
+
+On repay, the source fee is time-proportional:
+
+```solidity
+if (timeSinceLoanCreated <= prepaidDuration) return 0;  // Free window
+// After prepaid window: linear accrual
+fullSourceFeeAmount = JBFees.feeAmountFrom(
+    loan.amount - prepaid,
+    mulDiv(timeSinceLoanCreated - prepaidDuration, MAX_FEE, LOAN_LIQUIDATION_DURATION - prepaidDuration)
+);
+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 `>`.
+
+## How to Run Tests
+
+```bash
+cd revnet-core-v6
+npm install
+forge build
+forge test
+
+# Run with verbosity for debugging
+forge test -vvvv --match-test testName
+
+# Write a PoC
+forge test --match-path test/audit/ExploitPoC.t.sol -vvv
+
+# Gas analysis
+forge test --gas-report
+```
+
+## Anti-Patterns to Hunt
+
+| 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) |
+| `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. |

package/CHANGE_LOG.md

@@ -0,0 +1,321 @@
+# 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).
+
+---
+
+## 1. Breaking Changes
+
+### 1.1 Removed Structs
+
+| Struct | Notes |
+|--------|-------|
+| `REVBuybackHookConfig` | Removed entirely. Buyback hook configuration is no longer passed by the caller. The deployer auto-configures buyback pools via an immutable `BUYBACK_HOOK` registry. |
+| `REVBuybackPoolConfig` | Removed entirely. Was used within `REVBuybackHookConfig`. Buyback pools are now auto-initialized with default parameters. |
+
+### 1.2 Struct Field Changes
+
+#### REVConfig
+
+| Change | v5 | v6 |
+|--------|----|----|
+| `loanSources` field | `REVLoanSource[] loanSources` | Removed |
+| `loans` field | `address loans` | Removed |
+
+Loan sources and the loans contract address are no longer part of the per-revnet configuration. In v6, loans are managed via a single immutable `LOANS` address on the deployer, and fund access limits for loans are derived from terminal configurations rather than explicit loan sources.
+
+#### REVDeploy721TiersHookConfig
+
+| Change | v5 | v6 |
+|--------|----|----|
+| `baseline721HookConfiguration` type | `JBDeploy721TiersHookConfig` | `REVBaseline721HookConfig` |
+| `splitOperatorCanAdjustTiers` | `bool splitOperatorCanAdjustTiers` | Renamed to `bool preventSplitOperatorAdjustingTiers` |
+| `splitOperatorCanUpdateMetadata` | `bool splitOperatorCanUpdateMetadata` | Renamed to `bool preventSplitOperatorUpdatingMetadata` |
+| `splitOperatorCanMint` | `bool splitOperatorCanMint` | Renamed to `bool preventSplitOperatorMinting` |
+| `splitOperatorCanIncreaseDiscountPercent` | `bool splitOperatorCanIncreaseDiscountPercent` | Renamed to `bool preventSplitOperatorIncreasingDiscountPercent` |
+
+The boolean semantics are **inverted**: v5 used opt-in flags (`splitOperatorCan*`), v6 uses opt-out flags (`preventSplitOperator*`). In v6, the permissions are granted by default unless explicitly prevented.
+
+#### REVCroptopAllowedPost
+
+| Change | v5 | v6 |
+|--------|----|----|
+| `maximumSplitPercent` field | Not present | Added: `uint32 maximumSplitPercent` |
+
+### 1.3 IREVDeployer Interface Changes
+
+| Change | v5 | v6 |
+|--------|----|----|
+| `deployFor` (no 721s) return type | `returns (uint256)` | `returns (uint256, IJB721TiersHook)` |
+| `deployFor` (no 721s) parameters | `(uint256, REVConfig, JBTerminalConfig[], REVBuybackHookConfig, REVSuckerDeploymentConfig)` | `(uint256, REVConfig, JBTerminalConfig[], REVSuckerDeploymentConfig)` |
+| `deployWith721sFor` | `deployWith721sFor(uint256, REVConfig, JBTerminalConfig[], REVBuybackHookConfig, REVSuckerDeploymentConfig, REVDeploy721TiersHookConfig, REVCroptopAllowedPost[])` | Removed. Replaced by `deployFor` overload with 6 parameters. |
+| `buybackHookOf` view | `buybackHookOf(uint256) returns (IJBRulesetDataHook)` | Removed. Replaced by immutable `BUYBACK_HOOK()`. |
+| `loansOf` view | `loansOf(uint256) returns (address)` | Removed. Replaced by immutable `LOANS()`. |
+
+### 1.4 IREVLoans Interface Changes
+
+| Change | v5 | v6 |
+|--------|----|----|
+| `REVNETS` view | `REVNETS() returns (IREVDeployer)` | Removed. The loans contract no longer stores a reference to the deployer. |
+| `numberOfLoansFor` view | `numberOfLoansFor(uint256) returns (uint256)` | Renamed to `totalLoansBorrowedFor(uint256) returns (uint256)` |
+| `reallocateCollateralFromLoan` mutability | `external payable` | `external` (not payable) |
+| Constructor | `constructor(IREVDeployer, uint256, address, IPermit2, address)` | `constructor(IJBController, IJBProjects, uint256, address, IPermit2, address)` |
+
+### 1.5 Removed Errors
+
+| Contract | v5 Error | v6 Replacement |
+|----------|----------|----------------|
+| `REVDeployer` | `REVDeployer_LoanSourceDoesntMatchTerminalConfigurations(address, address)` | Removed. Loan sources are no longer validated against terminal configurations. |
+| `REVLoans` | `REVLoans_RevnetsMismatch(address, address)` | Replaced by `REVLoans_InvalidTerminal(address, uint256)`. Terminal validation replaces deployer ownership check. |
+
+---
+
+## 2. New Features
+
+### 2.1 New Functions
+
+#### IREVDeployer / REVDeployer
+
+| Function | Description |
+|----------|-------------|
+| `burnHeldTokensOf(uint256 revnetId)` | Burns any of the revnet's tokens held by the deployer contract. Project tokens can accumulate here from reserved token distribution when splits do not sum to 100%. |
+| `deployFor` (4-arg overload) | Convenience overload that deploys a revnet with a default empty 721 hook. Constructs an empty 721 config internally. Returns `(uint256, IJB721TiersHook)`. |
+| `BUYBACK_HOOK()` | Returns the immutable `IJBBuybackHookRegistry` used as a data hook to route payments through buyback pools. |
+| `LOANS()` | Returns the immutable address of the single loan contract shared by all revnets. |
+| `DEFAULT_BUYBACK_POOL_FEE()` | Returns the default Uniswap pool fee tier (`10_000` = 1%) for auto-configured buyback pools. |
+| `DEFAULT_BUYBACK_TWAP_WINDOW()` | Returns the default TWAP window (`2 days`) for auto-configured buyback pools. |
+
+### 2.2 New Events
+
+| Contract | Event |
+|----------|-------|
+| `IREVDeployer` | `BurnHeldTokens(uint256 indexed revnetId, uint256 count, address caller)` |
+
+### 2.3 New Errors
+
+| Contract | Error |
+|----------|-------|
+| `REVDeployer` | `REVDeployer_NothingToBurn()` |
+| `REVLoans` | `REVLoans_InvalidTerminal(address terminal, uint256 revnetId)` |
+| `REVLoans` | `REVLoans_NothingToRepay()` |
+| `REVLoans` | `REVLoans_ZeroBorrowAmount()` |
+| `REVLoans` | `REVLoans_SourceMismatch()` |
+| `REVLoans` | `REVLoans_LoanIdOverflow()` |
+
+### 2.4 New Constants
+
+| Contract | Constant | Description |
+|----------|----------|-------------|
+| `REVDeployer` | `DEFAULT_BUYBACK_POOL_FEE = 10_000` | Default Uniswap pool fee tier (1%) for auto-configured buyback pools. |
+| `REVDeployer` | `DEFAULT_BUYBACK_TICK_SPACING = 200` | Default tick spacing for buyback pools, aligned with `UniV4DeploymentSplitHook.TICK_SPACING`. |
+| `REVDeployer` | `DEFAULT_BUYBACK_TWAP_WINDOW = 2 days` | Default TWAP window for buyback pools. |
+
+### 2.5 New Structs
+
+| Struct | Description |
+|--------|-------------|
+| `REVBaseline721HookConfig` | Replaces `JBDeploy721TiersHookConfig` as the type for `REVDeploy721TiersHookConfig.baseline721HookConfiguration`. Contains `name`, `symbol`, `baseUri`, `tokenUriResolver`, `contractUri`, `tiersConfig`, `reserveBeneficiary`, and `flags` (`REV721TiersHookFlags`). |
+| `REV721TiersHookFlags` | A subset of `JB721TiersHookFlags` that omits `issueTokensForSplits` (revnets always force it to `false`). Contains `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting`, `preventOverspending`. |
+
+---
+
+## 3. Event Changes
+
+### 3.1 Added Events
+
+See section 2.2 above.
+
+### 3.2 Removed Events
+
+| Contract | Event | Notes |
+|----------|-------|-------|
+| `IREVDeployer` | `SetAdditionalOperator(uint256 revnetId, address additionalOperator, uint256[] permissionIds, address caller)` | Removed entirely. |
+
+### 3.3 Modified Events
+
+| Contract | Event | Change |
+|----------|-------|--------|
+| `IREVDeployer` | `DeployRevnet` | Removed `REVBuybackHookConfig buybackHookConfiguration` parameter. |
+| `IREVLoans` | `ReallocateCollateral` | Typo fix: `removedcollateralCount` (lowercase 'c') renamed to `removedCollateralCount` (uppercase 'C'). |
+
+### 3.4 NatSpec Documentation
+
+All events in v6 interfaces gained comprehensive NatSpec documentation (`@notice`, `@param`). This is a documentation-only change that does not affect the ABI.
+
+---
+
+## 4. Error Changes
+
+### 4.1 Removed Errors
+
+| Contract | Error | Notes |
+|----------|-------|-------|
+| `REVDeployer` | `REVDeployer_LoanSourceDoesntMatchTerminalConfigurations(address, address)` | Loan sources removed from `REVConfig`. |
+| `REVLoans` | `REVLoans_RevnetsMismatch(address, address)` | Replaced by terminal validation via `DIRECTORY.isTerminalOf`. |
+
+### 4.2 New Errors
+
+See section 2.3 above.
+
+### 4.3 Unchanged Errors
+
+The following errors are identical between v5 and v6:
+
+**REVDeployer:**
+- `REVDeployer_AutoIssuanceBeneficiaryZeroAddress()`
+- `REVDeployer_CashOutDelayNotFinished(uint256, uint256)`
+- `REVDeployer_CashOutsCantBeTurnedOffCompletely(uint256, uint256)`
+- `REVDeployer_MustHaveSplits()`
+- `REVDeployer_NothingToAutoIssue()`
+- `REVDeployer_RulesetDoesNotAllowDeployingSuckers()`
+- `REVDeployer_StageNotStarted(uint256)`
+- `REVDeployer_StagesRequired()`
+- `REVDeployer_StageTimesMustIncrease()`
+- `REVDeployer_Unauthorized(uint256, address)`
+
+**REVLoans:**
+- `REVLoans_CollateralExceedsLoan(uint256, uint256)`
+- `REVLoans_InvalidPrepaidFeePercent(uint256, uint256, uint256)`
+- `REVLoans_LoanExpired(uint256, uint256)`
+- `REVLoans_NewBorrowAmountGreaterThanLoanAmount(uint256, uint256)`
+- `REVLoans_NoMsgValueAllowed()`
+- `REVLoans_NotEnoughCollateral()`
+- `REVLoans_OverflowAlert(uint256, uint256)`
+- `REVLoans_OverMaxRepayBorrowAmount(uint256, uint256)`
+- `REVLoans_PermitAllowanceNotEnough(uint256, uint256)`
+- `REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows(uint256, uint256)`
+- `REVLoans_Unauthorized(address, address)`
+- `REVLoans_UnderMinBorrowAmount(uint256, uint256)`
+- `REVLoans_ZeroCollateralLoanIsInvalid()`
+
+---
+
+## 5. Struct Changes
+
+### 5.1 Removed Structs
+
+| Struct | Notes |
+|--------|-------|
+| `REVBuybackHookConfig` | Buyback hook is now an immutable on the deployer; configuration is automatic. |
+| `REVBuybackPoolConfig` | Was used within `REVBuybackHookConfig`. |
+
+### 5.2 New Structs
+
+| Struct | Notes |
+|--------|-------|
+| `REVBaseline721HookConfig` | Replaces `JBDeploy721TiersHookConfig` in `REVDeploy721TiersHookConfig`. Provides a revnet-specific 721 config that uses `REV721TiersHookFlags` instead of `JB721TiersHookFlags`, omitting `issueTokensForSplits`. |
+| `REV721TiersHookFlags` | A subset of `JB721TiersHookFlags` without `issueTokensForSplits` (always forced to `false` for revnets). |
+
+### 5.3 Modified Structs
+
+| Struct | Field | v5 | v6 |
+|--------|-------|----|----|
+| `REVConfig` | `loanSources` | `REVLoanSource[] loanSources` | Removed |
+| `REVConfig` | `loans` | `address loans` | Removed |
+| `REVCroptopAllowedPost` | `maximumSplitPercent` | Not present | `uint32 maximumSplitPercent` |
+| `REVDeploy721TiersHookConfig` | `baseline721HookConfiguration` | `JBDeploy721TiersHookConfig` | `REVBaseline721HookConfig` |
+| `REVDeploy721TiersHookConfig` | `splitOperatorCanAdjustTiers` | `bool splitOperatorCanAdjustTiers` | Renamed/inverted: `bool preventSplitOperatorAdjustingTiers` |
+| `REVDeploy721TiersHookConfig` | `splitOperatorCanUpdateMetadata` | `bool splitOperatorCanUpdateMetadata` | Renamed/inverted: `bool preventSplitOperatorUpdatingMetadata` |
+| `REVDeploy721TiersHookConfig` | `splitOperatorCanMint` | `bool splitOperatorCanMint` | Renamed/inverted: `bool preventSplitOperatorMinting` |
+| `REVDeploy721TiersHookConfig` | `splitOperatorCanIncreaseDiscountPercent` | `bool splitOperatorCanIncreaseDiscountPercent` | Renamed/inverted: `bool preventSplitOperatorIncreasingDiscountPercent` |
+
+### 5.4 Unchanged Structs
+
+The following structs are identical between v5 and v6 (only `forge-lint` comments added):
+- `REVAutoIssuance`
+- `REVDescription`
+- `REVLoan`
+- `REVLoanSource`
+- `REVStageConfig`
+- `REVSuckerDeploymentConfig`
+
+---
+
+## 6. Implementation Changes
+
+### 6.1 REVDeployer
+
+| Change | Description |
+|--------|-------------|
+| **Solidity version** | Upgraded from `0.8.23` to `0.8.26`. |
+| **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`. |
+| **Deploy function consolidation** | `deployFor` and `deployWith721sFor` merged into two `deployFor` overloads: a 6-arg version (with 721 config and allowed posts) and a 4-arg convenience version (auto-creates empty 721 hook). Both return `(uint256, IJB721TiersHook)`. |
+| **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. |
+| **`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. |
+| **Split operator permissions expanded** | Default permissions increased from 6 (v5) to 9 (v6). Added `SET_BUYBACK_HOOK`, `SET_ROUTER_TERMINAL`, and `SET_TOKEN_METADATA`. |
+| **Encoded configuration hash** | v5 included `configuration.loans` in the encoded configuration. v6 does not, since loans are no longer per-revnet. |
+| **Deploy ordering** | v6 `_deploy721RevnetFor` deploys the revnet first via `_deployRevnetFor`, then deploys the 721 hook and sets split operator permissions. v5 deployed the 721 hook then called `_deployRevnetFor`. |
+| **Croptop `maximumSplitPercent`** | v6 passes the new `maximumSplitPercent` field from `REVCroptopAllowedPost` to `CTAllowedPost`. |
+| **Auto-initialized buyback pools** | During deployment, `_tryInitializeBuybackPoolFor` is called for every terminal token to set up Uniswap V4 buyback pools at a generic 1:1 `sqrtPriceX96`. Failures (e.g., pool already initialized) are silently caught via try-catch. |
+| **Feeless beneficiary cashout routing** | `beforeCashOutRecordedWith` now checks `context.beneficiaryIsFeeless` and skips the 2.5% revnet fee when the cashout is routed by a feeless address (e.g., the router terminal routing value between projects). v5 did not have this check. The cash out tax rate still applies -- only the protocol fee is waived. |
+
+### 6.2 REVLoans
+
+| Change | Description |
+|--------|-------------|
+| **Solidity version** | Upgraded from `0.8.23` to `0.8.26`. |
+| **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. |
+| **`numberOfLoansFor` renamed** | Renamed to `totalLoansBorrowedFor` to clarify that it is a monotonically increasing counter, not a count of active loans. |
+| **`reallocateCollateralFromLoan` not payable** | v5 marked this function as `external payable`. v6 removes `payable` since the function only moves existing collateral between loans and does not accept new funds. |
+| **Source mismatch check** | `reallocateCollateralFromLoan` now validates that the provided source matches the existing loan's source, reverting with `REVLoans_SourceMismatch()` if they differ. |
+| **Zero borrow amount check** | `borrowFrom` now reverts with `REVLoans_ZeroBorrowAmount()` if the bonding curve returns zero. v5 did not have this check and would create a zero-amount loan. |
+| **Nothing to repay check** | `repayLoan` now reverts with `REVLoans_NothingToRepay()` if both `repayBorrowAmount` and `collateralCountToReturn` are zero, preventing unbounded `totalLoansBorrowedFor` inflation. |
+| **Liquidation loop behavior** | v5 broke out of the loop when encountering a loan with `createdAt == 0` (`break`). v6 continues iterating (`continue`), skipping gaps from repaid or previously liquidated loans. |
+| **Liquidation cleanup** | v6 adds `delete _loanOf[loanId]` after burning a liquidated loan, clearing stale loan data for a gas refund. v5 did not clean up the loan data. |
+| **`_totalBorrowedFrom` decimal normalization** | v6 normalizes token amounts from the source's native decimals to the target decimals before currency conversion. v5 did not perform decimal normalization, which could cause mixed-decimal arithmetic errors for tokens with non-18 decimals (e.g., USDC with 6 decimals). |
+| **`_totalBorrowedFrom` zero-price safety** | v6 skips sources with a zero price to prevent division-by-zero panics that would DoS all loan operations. v5 did not handle this case. |
+| **`_determineSourceFeeAmount` boundary fix** | An intermediate v6 revision used `>=` for the liquidation check, which created a 1-second window where neither repay nor liquidate could execute. This was fixed back to `>` (matching v5) so the exact boundary second is still repayable, while the liquidation path uses `<=`. |
+| **BURN_TOKENS permission prerequisite (NatSpec only)** | `borrowFrom` documents via a `@dev` NatSpec comment that callers must first grant `BURN_TOKENS` permission to the loans contract via `JBPermissions.setPermissionsFor()`. This is required because collateral posting burns the caller's tokens through the controller. However, there is no runtime `hasPermission` check in `borrowFrom` itself -- if the permission is missing, the transaction will revert later inside `JBController.burnTokensOf`. v5 did not document this requirement. |
+| **Cross-revnet liquidation guard** | `liquidateExpiredLoansFrom` now validates that `startingLoanId + count` does not exceed `_ONE_TRILLION`, preventing callers from overflowing into a different revnet's loan ID namespace via `_generateLoanId`. Reverts with `REVLoans_LoanIdOverflow()`. v5 did not have this bounds check. |
+| **Source fee try-catch hardening** | The source fee payment in `_adjust` is now wrapped in a try-catch block. If the source terminal's `pay` call reverts, the ERC-20 allowance is reclaimed and the fee amount is returned to the beneficiary instead of blocking the entire loan operation. v5 called `terminal.pay` directly without error handling. |
+| **Timestamp cast fix** | `borrowFrom` now casts `block.timestamp` to `uint48` when setting `loan.createdAt`, matching the `REVLoan.createdAt` field width. v5 used `uint40`, which would silently truncate timestamps after the year 36812. |
+| **`ReallocateCollateral` event typo fix** | v5 used `removedcollateralCount` (lowercase 'c'). v6 fixes it to `removedCollateralCount` (uppercase 'C'). |
+| **NatSpec documentation** | Extensive NatSpec added to all functions, views, and internal helpers. Flash loan safety analysis documented in `_borrowableAmountFrom`. |
+
+### 6.3 Named Arguments
+
+Throughout the codebase, function calls were updated to use named argument syntax (e.g., `foo({bar: 1, baz: 2})`) for improved readability.
+
+---
+
+## 7. Migration Table
+
+### Interfaces
+
+| v5 | v6 | Notes |
+|----|----|-------|
+| `IREVDeployer` | `IREVDeployer` | `deployWith721sFor` removed; two `deployFor` overloads (both return `IJB721TiersHook`). `buybackHookOf` and `loansOf` removed. `BUYBACK_HOOK`, `LOANS`, `DEFAULT_BUYBACK_POOL_FEE`, `DEFAULT_BUYBACK_TWAP_WINDOW`, `burnHeldTokensOf` added. `BurnHeldTokens` event added, `SetAdditionalOperator` event removed. `DeployRevnet` event lost `buybackHookConfiguration` param. NatSpec added. |
+| `IREVLoans` | `IREVLoans` | `REVNETS` removed. `numberOfLoansFor` renamed to `totalLoansBorrowedFor`. `reallocateCollateralFromLoan` no longer payable. Constructor takes `IJBController` + `IJBProjects` instead of `IREVDeployer`. `ReallocateCollateral` event typo fixed. NatSpec added. |
+
+### Contracts
+
+| v5 | v6 | Notes |
+|----|----|-------|
+| `REVDeployer` | `REVDeployer` | Buyback hook architecture changed from per-revnet mapping to immutable registry. Loans changed from per-revnet to single immutable. Deploy functions consolidated. Every revnet gets a 721 hook. 721 permission flags inverted. `beforePayRecordedWith` rewritten for split-aware weight scaling. `burnHeldTokensOf` added. Split operator gains 3 new default permissions (`SET_BUYBACK_HOOK`, `SET_ROUTER_TERMINAL`, `SET_TOKEN_METADATA`). Feeless beneficiary cashout routing skips fee for feeless addresses. |
+| `REVLoans` | `REVLoans` | Deployer dependency removed. Terminal validation replaces deployer ownership check. `numberOfLoansFor` renamed. `reallocateCollateralFromLoan` not payable. Source mismatch, zero borrow, and nothing-to-repay checks added. BURN_TOKENS permission requirement documented via NatSpec (no runtime check). Cross-revnet liquidation guard prevents loan ID namespace overflow. Liquidation loop uses `continue` instead of `break`. Stale loan data cleaned up on liquidation. Decimal normalization and zero-price safety in `_totalBorrowedFrom`. Source fee payment wrapped in try-catch. Timestamp cast fixed from `uint40` to `uint48`. |
+
+### Structs
+
+| v5 | v6 | Notes |
+|----|----|-------|
+| `REVAutoIssuance` | `REVAutoIssuance` | Identical (lint comment added) |
+| `REVBuybackHookConfig` | (removed) | Buyback hook is now an immutable on the deployer |
+| `REVBuybackPoolConfig` | (removed) | Was used within `REVBuybackHookConfig` |
+| (not present) | `REVBaseline721HookConfig` | New struct for revnet-specific 721 hook configuration |
+| (not present) | `REV721TiersHookFlags` | New subset of `JB721TiersHookFlags` without `issueTokensForSplits` |
+| `REVConfig` | `REVConfig` | Removed `loanSources` and `loans` fields |
+| `REVCroptopAllowedPost` | `REVCroptopAllowedPost` | Added `maximumSplitPercent` field |
+| `REVDeploy721TiersHookConfig` | `REVDeploy721TiersHookConfig` | `baseline721HookConfiguration` type changed. Boolean flags inverted from opt-in to opt-out. |
+| `REVDescription` | `REVDescription` | Identical (lint comment added) |
+| `REVLoan` | `REVLoan` | Identical (lint comment added) |
+| `REVLoanSource` | `REVLoanSource` | Identical (lint comment added) |
+| `REVStageConfig` | `REVStageConfig` | Identical (lint comment added) |
+| `REVSuckerDeploymentConfig` | `REVSuckerDeploymentConfig` | Identical (lint comment added) |

package/README.md

@@ -47,7 +47,7 @@ Revnets are autonomous Juicebox projects with predetermined economic stages. Eac
 
 `REVLoans` lets participants borrow against their revnet tokens. Unlike traditional lending:
 
-- **Collateral is burned, not held.** Tokens are destroyed on borrow and re-minted on repay. This keeps the token supply accurate -- collateral tokens don't exist during the loan.
+- **Collateral is burned, not held.** Tokens are destroyed on borrow and re-minted on repay. This keeps the token supply accurate -- collateral tokens don't exist during the loan. Callers must first grant `BURN_TOKENS` permission to the loans contract via `JBPermissions.setPermissionsFor()`.
 - **Borrowable amount = cash-out value.** The bonding curve determines how much you can borrow for a given amount of collateral.
 - **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.
@@ -183,7 +183,7 @@ Plus optional from 721 hook config: `ADJUST_721_TIERS`, `SET_721_METADATA`, `MIN
 - **Loan flash-loan exposure.** `borrowableAmountFrom` reads live surplus, which can be inflated via flash loans. A borrower could temporarily inflate the treasury to borrow more than the sustained value would support.
 - **uint112 truncation.** `REVLoan.amount` and `REVLoan.collateral` are `uint112` -- values above ~5.19e33 truncate silently.
 - **Cash-out fee stacking.** Cash outs incur both the Juicebox terminal fee (2.5%) and the revnet cash-out fee (2.5% to fee revnet). These compound.
-- **Auto-issuance stage ID mismatch.** Stage IDs are computed as `block.timestamp + i` during deployment, but actual Juicebox ruleset IDs depend on queuing logic. If timestamps don't align, auto-issuance for later stages may be unclaimed.
+- **Auto-issuance stage IDs.** Stage IDs are `block.timestamp + i` during deployment. These match the Juicebox ruleset IDs because `JBRulesets` assigns IDs the same way (`latestId >= block.timestamp ? latestId + 1 : block.timestamp`), producing identical sequential IDs when all stages are queued in a single `deployFor()` call.
 - **NATIVE_TOKEN on non-ETH chains.** Using `JBConstants.NATIVE_TOKEN` on Celo or Polygon means CELO/MATIC, not ETH. Use ERC-20 WETH instead. The matching hash does NOT catch this -- it covers economic parameters but NOT terminal configurations.
 - **30-day cash-out delay.** When deploying an existing revnet to a new chain where the first stage has already started, a 30-day delay is imposed before cash outs are allowed, preventing cross-chain liquidity arbitrage.
 - **Loan source array growth.** `_loanSourcesOf[revnetId]` is unbounded. If an attacker creates loans from many different terminals/tokens, the array grows without limit.