@rev-net/core-v6 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Revnet Research Network 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# revnet-core-v5
+
+Deploy and operate Revnets: unowned Juicebox projects that run autonomously according to predefined stages, with built-in token-collateralized loans.
+
+## What is a Revnet?
+
+A Revnet is a Retailistic network — a treasury-backed token that runs itself. No owners, no governors, no multisigs. Once deployed, a revnet follows its predefined stages forever, backed by the Juicebox and Uniswap protocols.
+
+For a Retailism TLDR, see [Retailism](https://jango.eth.sucks/9E01E72C-6028-48B7-AD04-F25393307132/).
+
+For more Retailism information, see:
+
+- [A Retailistic View on CAC and LTV](https://jango.eth.limo/572BD957-0331-4977-8B2D-35F84D693276/)
+- [Modeling Retailism](https://jango.eth.limo/B762F3CC-AEFE-4DE0-B08C-7C16400AF718/)
+- [Retailism for Devs, Investors, and Customers](https://jango.eth.limo/3EB05292-0376-4B7D-AFCF-042B70673C3D/)
+- [Observations: Network dynamics similar between atoms, cells, organisms, groups, dance parties](https://jango.eth.limo/CF40F5D2-7BFE-43A3-9C15-1C6547FBD15C/)
+
+Join the conversation: [Discord](https://discord.gg/nT3XqbzNEr)
+
+## Architecture
+
+| Contract | Description |
+|----------|-------------|
+| [`REVDeployer`](src/REVDeployer.sol) | Deploys revnets as Juicebox projects owned by the deployer contract itself (no human owner). Translates stage configurations into Juicebox rulesets, manages buyback hooks, tiered 721 hooks, suckers, split operators, auto-issuance, and cash out fees. Acts as the ruleset data hook and cash out hook for every revnet it deploys. |
+| [`REVLoans`](src/REVLoans.sol) | Lets participants borrow against their revnet tokens. Collateral tokens are burned on borrow and re-minted on repayment. Each loan is an ERC-721 NFT. Charges a prepaid fee (2.5% min, 50% max) that determines the interest-free duration; after that window, a time-proportional source fee accrues. Loans liquidate after 10 years. |
+
+### How they relate
+
+`REVDeployer` owns every revnet's Juicebox project NFT and holds all administrative permissions. During deployment it grants `REVLoans` the `USE_ALLOWANCE` permission so loans can pull funds from the revnet's terminal. `REVLoans` verifies that a revnet was deployed by its expected `REVDeployer` before issuing any loan.
+
+### Deployer Variants
+
+This repo includes several deployer patterns for different use cases:
+
+- **Basic revnet** — Deploy a simple revnet with `REVDeployer` using stage configurations that map to Juicebox rulesets.
+- **Pay hook revnet** — Accept additional pay hooks that run throughout the revnet's lifetime as it receives payments.
+- **Tiered 721 revnet** — Deploy a tiered 721 pay hook (NFT tiers) that mints NFTs as people pay into the revnet.
+- **Croptop revnet** — A tiered 721 revnet where the public can post content through the [Croptop](https://croptop.eth.limo) publisher contract.
+
+You can use these contracts to deploy treasuries from Etherscan, or wherever else they've been exposed from.
+
+## Install
+
+```bash
+npm install @rev-net/core-v5
+```
+
+## Develop
+
+This repo uses [npm](https://www.npmjs.com/) for package management and [Foundry](https://github.com/foundry-rs/foundry) for builds and tests.
+
+```bash
+npm install && forge install
+```
+
+If `forge install` has issues, try `git submodule update --init --recursive`.
+
+| Command | Description |
+|---------|-------------|
+| `forge build` | Compile contracts |
+| `forge test` | Run tests |
+| `forge test -vvvv` | Run tests with full traces |
+| `forge fmt` | Lint |
+| `forge coverage` | Generate test coverage report |
+| `forge build --sizes` | Get contract sizes |

package/REVNET_SECURITY_CHECKLIST.md

@@ -0,0 +1,164 @@
+# Revnet Pre-Deployment Security Checklist
+
+**Status**: All findings documented, tests written. Fixes required before deployment.
+**Test Suite**: `forge test --match-contract REVInvincibility -vvv`
+**Date**: 2026-02-21
+
+---
+
+## Critical Findings (5)
+
+### C-1: uint112 Truncation in REVLoans._adjust
+- **File**: `REVLoans.sol:922-923`
+- **Code**: `loan.amount = uint112(newBorrowAmount); loan.collateral = uint112(newCollateralCount);`
+- **Impact**: Silently truncates borrow amounts > 5.19e33 (uint112.max), allowing loans with near-zero recorded debt but full ETH disbursement
+- **Fix Required**: Add `require(newBorrowAmount <= type(uint112).max)` and `require(newCollateralCount <= type(uint112).max)` before the casts
+- **Test**: `test_fixVerify_C1_uint112Truncation` — proves the truncation math
+- **Status**: [ ] UNFIXED
+
+### C-2: Array OOB in REVDeployer.beforePayRecordedWith
+- **File**: `REVDeployer.sol:248-258`
+- **Code**: `hookSpecifications[1] = buybackHookSpecifications[0]` hardcoded to index [1]
+- **Impact**: Payment to any revnet with buyback hook but no 721 hook reverts (OOB on size-1 array)
+- **Fix Required**: Change line 258 to use dynamic index: `hookSpecifications[usesTiered721Hook ? 1 : 0]`
+- **Test**: `test_fixVerify_C2_arrayOOB_noBuybackWithBuyback` — proves the index logic
+- **Status**: [ ] UNFIXED
+
+### C-3: Reentrancy in REVLoans._adjust
+- **File**: `REVLoans.sol:910 vs 922-923`
+- **Code**: `terminal.pay()` at line 910 before `loan.amount = ...` at line 922
+- **Impact**: Malicious fee terminal can reenter borrowFrom() with stale loan state, potentially extracting more than collateral supports
+- **Fix Required**: Either add `nonReentrant` modifier or move state writes (lines 922-923) before external calls (line 910)
+- **Test**: `test_fixVerify_C3_reentrancyDoubleBorrow` — confirms CEI violation pattern
+- **Status**: [ ] UNFIXED
+
+### C-4: hasMintPermissionFor Reverts on address(0)
+- **File**: `REVDeployer.sol:353-354`
+- **Code**: `buybackHook.hasMintPermissionFor(...)` called when `buybackHook == address(0)`
+- **Impact**: Blocks ALL sucker claims and external mint operations for revnets without buyback hooks
+- **Fix Required**: Add `address(buybackHook) != address(0) &&` guard before the call
+- **Test**: `test_fixVerify_C4_hasMintPermission_noBuyback` — triggers the revert
+- **Status**: [ ] UNFIXED
+
+### C-5: Zero-Supply Cash Out Drains Surplus
+- **File**: `JBCashOuts.sol:31`
+- **Code**: `if (cashOutCount >= totalSupply) return surplus;` — 0 >= 0 is true
+- **Impact**: When totalSupply=0, cashing out 0 tokens returns the ENTIRE surplus
+- **Fix Required**: Add `if (cashOutCount == 0) return 0;` before the totalSupply check
+- **Test**: `test_fixVerify_C5_zeroSupplyCashOutDrain` — proves 0/0 returns full surplus
+- **Status**: [ ] UNFIXED (in JBCashOuts library)
+
+---
+
+## High Findings (4 revnet-specific)
+
+### H-1: Double Fee on Cash-Outs
+- **File**: `REVDeployer.sol:567-624`
+- **Impact**: Cash-out fees are charged twice — once by JBMultiTerminal (protocol fee) and once by REVDeployer's afterCashOutRecordedWith (revnet fee). REVDeployer is not registered as feeless.
+- **Fix Required**: Register REVDeployer as feeless address, or adjust fee calculation to account for the protocol fee already taken
+- **Test**: `test_econ_doubleFeeH1` — measures actual fee amounts
+- **Status**: [ ] UNFIXED
+
+### H-2: Broken Fee Terminal Bricks Cash-Outs
+- **File**: `REVDeployer.sol:615`
+- **Impact**: In the catch block of afterCashOutRecordedWith, `addToBalanceOf()` is NOT wrapped in try/catch. If both feeTerminal.pay() and addToBalanceOf() revert, ALL cash-outs for the revnet become permanently impossible.
+- **Fix Required**: Wrap the fallback `addToBalanceOf()` at line 615 in its own try/catch
+- **Test**: `test_fixVerify_H2_brokenFeeTerminalBricksCashOuts` — demonstrates both paths revert
+- **Status**: [ ] UNFIXED
+
+### H-5: Auto-Issuance Stage ID Mismatch
+- **File**: `REVDeployer.sol:1223`
+- **Code**: `amountToAutoIssue[revnetId][block.timestamp + i][...] += ...`
+- **Impact**: Stage ID computed as `block.timestamp + i` but actual ruleset IDs from JBRulesets may differ. Auto-issuance tokens for non-first stages become permanently unclaimable.
+- **Fix Required**: Use the actual ruleset IDs returned by `jbController().queueRulesetsOf()` instead of `block.timestamp + i`
+- **Test**: `test_fixVerify_H5_autoIssuanceStageIdMismatch` — confirms mismatch for stage 1+
+- **Status**: [ ] UNFIXED
+
+### H-6: Unvalidated Source Terminal
+- **File**: `REVLoans.sol:788-791`
+- **Impact**: Any terminal can be registered as a loan source. Attacker can grow `_loanSourcesOf` array unboundedly, causing gas DoS on functions that iterate loan sources.
+- **Fix Required**: Validate that `loan.source.terminal` is a registered terminal for the project via `DIRECTORY.isTerminalOf(revnetId, loan.source.terminal)`
+- **Test**: `test_fixVerify_H6_unvalidatedSourceTerminal` — documents the unvalidated registration
+- **Status**: [ ] UNFIXED
+
+---
+
+## Medium Findings (3 revnet-specific)
+
+### M-7: Silent Fee Failure in REVLoans._addTo
+- **File**: `REVLoans.sol:833-841`
+- **Impact**: REV fee payment in `_addTo` is wrapped in try/catch. If the fee terminal reverts, the fee is silently lost — REV holders lose fee revenue without any notification.
+- **Fix Required**: At minimum, emit an event on fee failure. Consider reverting to ensure fees are always collected.
+- **Status**: [ ] UNFIXED
+
+### M-10: Cross-Source Value Extraction via reallocateCollateralFromLoan
+- **File**: `REVLoans.sol:619-654`
+- **Impact**: Collateral from one loan source can be transferred to create a loan from a different source. If source terminals have different fee structures, this enables fee arbitrage.
+- **Fix Required**: Consider restricting collateral reallocation to same-source loans
+- **Status**: [ ] UNFIXED
+
+### M-11: Flash Loan Surplus Inflation
+- **File**: `REVLoans.sol:308-332`
+- **Impact**: `borrowableAmountFrom` reads live surplus. An attacker can `addToBalance` (inflating surplus without minting tokens) then immediately borrow at an inflated rate within the same block.
+- **Fix Required**: Consider using a time-weighted average surplus or adding a borrowing delay
+- **Test**: `test_econ_flashLoanSurplusInflation` — quantifies exact inflation factor
+- **Status**: [ ] UNFIXED
+
+---
+
+## Invariant Properties (Verified by Fuzzing)
+
+| ID | Property | Handler Operations | Runs |
+|----|----------|-------------------|------|
+| INV-REV-1 | Terminal balance covers outstanding loans | payAndBorrow, repayLoan, addToBalance | 256 |
+| INV-REV-2 | Ghost collateral sum == totalCollateralOf | payAndBorrow, repayLoan, reallocate | 256 |
+| INV-REV-3 | Ghost borrowed sum == totalBorrowedFrom | payAndBorrow, repayLoan | 256 |
+| INV-REV-4 | No undercollateralized loans (when no cash-outs) | payAndBorrow, advanceTime | 256 |
+| INV-REV-5 | totalSupply + totalCollateral coherent | All 10 operations | 256 |
+| INV-REV-6 | Fee project balance monotonically increasing | payAndBorrow (generates fees) | 256 |
+
+---
+
+## Test Execution
+
+```bash
+# Section A+B: Fix verification + economic attacks (18 tests)
+forge test --match-contract REVInvincibility_FixVerify -vvv
+
+# Section C: Invariant properties (6 invariants)
+forge test --match-contract REVInvincibility_Invariants -vvv
+
+# Full suite
+forge test --match-contract REVInvincibility -vvv
+
+# Full regression (all existing tests still pass)
+forge test -vvv
+```
+
+---
+
+## Post-Deployment Monitoring Recommendations
+
+1. **Loan Health Monitor**: Track `totalBorrowedFrom` vs terminal balance for each revnet. Alert if borrowed exceeds 80% of surplus.
+2. **Fee Collection Monitor**: Verify fee project token supply increases after every borrow operation. Alert on silent fee failures.
+3. **Collateral Consistency**: Periodically verify `sum(loan.collateral)` for all active loans matches `totalCollateralOf(revnetId)`.
+4. **Loan Source Array**: Monitor `_loanSourcesOf` array length. Alert if it exceeds expected number of terminals.
+5. **Auto-Issuance Claims**: After each stage transition, verify auto-issuance can be claimed at the correct ruleset ID.
+6. **Cash-Out Availability**: Monitor that cash-outs succeed after fee terminal configuration changes.
+
+---
+
+## Fix Priority Order
+
+1. **C-3** (Reentrancy) — Highest risk, enables active exploitation
+2. **C-5** (Zero-supply drain) — Direct fund loss
+3. **C-1** (uint112 truncation) — Fund loss at extreme values
+4. **C-4** (hasMintPermission revert) — Blocks sucker claims
+5. **C-2** (Array OOB) — Breaks payments for buyback-only revnets
+6. **H-2** (Broken fee terminal) — Permanent cash-out DoS
+7. **H-5** (Auto-issuance mismatch) — Permanent token loss
+8. **H-6** (Unvalidated terminal) — Gas DoS vector
+9. **H-1** (Double fee) — Economic loss for users
+10. **M-11** (Flash surplus inflation) — Economic exploitation
+11. **M-10** (Cross-source extraction) — Fee arbitrage
+12. **M-7** (Silent fee failure) — Revenue leakage

package/SECURITY.md

@@ -0,0 +1,68 @@
+# Security Considerations
+
+## [INTEROP-6] Cross-Chain Accounting Mismatch: NATIVE_TOKEN on Non-ETH Chains
+
+**Severity:** Medium
+**Status:** Acknowledged — by design, not fixable without oracle dependencies
+
+### Description
+
+When a revnet expands to a chain where the native token is not ETH (e.g., Celo where native = CELO), using `JBConstants.NATIVE_TOKEN` as the terminal accounting context and sucker token mapping creates a semantic mismatch. The protocol treats CELO payments as ETH-equivalent.
+
+### What the Matching Hash Covers
+
+The hash computed in `REVDeployer._makeRulesetConfigurations()` ensures both sides of a cross-chain deployment agree on:
+- `baseCurrency`, `loans`, `name`, `ticker`, `salt`
+- Per stage: timing, splits, issuance, cash-out tax
+- Per auto-issuance: chainId, beneficiary, count
+
+### What the Matching Hash Does NOT Cover
+
+- Terminal configurations (which tokens are accepted)
+- Accounting contexts (token address, decimals, currency)
+- Sucker token mappings (localToken → remoteToken)
+
+Two deployments can produce identical hashes while one accepts ETH-native and the other accepts CELO-native. The hash is a safety check for economic parameter alignment, not a guarantee of asset compatibility.
+
+### Impact on Revnets
+
+1. **Issuance mispricing** — A revnet with `baseCurrency = ETH` that accepts `NATIVE_TOKEN` on Celo prices CELO payments as ETH (1:1 without a price feed), massively overvaluing them.
+2. **Surplus fragmentation** — Cash-out bonding curve on each chain only sees that chain's surplus. Token holders must bridge to the chain with more surplus for fair cash-out values.
+3. **Cash-out arbitrage** — Different effective valuations across chains let arbitrageurs buy tokens cheaply on one chain and cash out on another.
+
+### Recommended Configuration for Non-ETH Chains
+
+When deploying a revnet to Celo or other non-ETH-native chains:
+
+```solidity
+// DO: Use WETH ERC20 as accounting context
+accountingContextsToAccept[0] = JBAccountingContext({
+    token: WETH_ADDRESS,  // e.g., 0xD221812... on Celo
+    decimals: 18,
+    currency: ETH_CURRENCY
+});
+
+// DO: Map WETH → WETH in sucker token mappings
+tokenMappings[0] = JBTokenMapping({
+    localToken: WETH_ADDRESS,
+    remoteToken: WETH_ADDRESS,
+    minGas: 200_000,
+    minBridgeAmount: 0.01 ether
+});
+
+// DON'T: Use NATIVE_TOKEN on non-ETH chains
+// This maps CELO → ETH which are different assets
+tokenMappings[0] = JBTokenMapping({
+    localToken: JBConstants.NATIVE_TOKEN,   // = CELO on Celo
+    remoteToken: JBConstants.NATIVE_TOKEN,  // = ETH on Ethereum
+    ...
+});
+```
+
+### Safe Chains
+
+OP Stack L2s where native token IS ETH: Ethereum, Optimism, Base, Arbitrum.
+
+### Affected Chains
+
+Any chain where native token ≠ ETH: Celo (CELO), Polygon (MATIC), Avalanche (AVAX), BNB Chain (BNB).

package/SKILLS.md

@@ -0,0 +1,166 @@
+# revnet-core-v5
+
+## Purpose
+
+Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged issuance schedules and token-collateralized lending.
+
+## Contracts
+
+| Contract | Role |
+|----------|------|
+| `REVDeployer` | Deploys revnets, acts as project owner, data hook, and cash out hook. Manages stages, splits, auto-issuance, buyback hooks, 721 hooks, suckers, and split operators. |
+| `REVLoans` | Issues token-collateralized loans from revnet treasuries. Each loan is an ERC-721. Burns collateral on borrow, re-mints on repay. Charges tiered fees (REV protocol fee + source fee + prepaid fee). |
+
+## Key Functions
+
+| Function | Contract | What it does |
+|----------|----------|--------------|
+| `deployFor` | REVDeployer | Deploy a new revnet (or convert an existing Juicebox project) with stages, terminals, buyback hook, suckers, and loans. |
+| `deployWith721sFor` | REVDeployer | Same as `deployFor` but also deploys a tiered ERC-721 hook and configures croptop allowed posts. |
+| `autoIssueFor` | REVDeployer | Mint pre-configured auto-issuance tokens for a beneficiary once a stage has started. |
+| `setSplitOperatorOf` | REVDeployer | Replace the current split operator (only callable by the current split operator). |
+| `deploySuckersFor` | REVDeployer | Deploy new cross-chain suckers for an existing revnet (split operator only, ruleset must allow it). |
+| `beforePayRecordedWith` | REVDeployer | Data hook callback: returns the buyback hook weight and assembles pay hook specs (721 hook + buyback hook). |
+| `beforeCashOutRecordedWith` | REVDeployer | Data hook callback: enforces cash out delay, exempts suckers from fees/taxes, calculates and routes the 2.5% cash out fee. |
+| `afterCashOutRecordedWith` | REVDeployer | Cash out hook callback: transfers the fee amount to the fee revnet's terminal. Falls back to returning funds if the fee payment fails. |
+| `hasMintPermissionFor` | REVDeployer | Returns true for the loans contract, buyback hook, or any sucker. |
+| `borrowFrom` | REVLoans | Open a loan: burn collateral tokens, pull funds from the revnet via `useAllowanceOf`, pay REV fee + source fee, transfer remainder to beneficiary, mint loan NFT. |
+| `repayLoan` | REVLoans | Repay (partially or fully): accept repayment funds, return them to the revnet via `addToBalanceOf`, re-mint collateral to beneficiary, burn/replace the loan NFT. |
+| `reallocateCollateralFromLoan` | REVLoans | Refinance: remove excess collateral from an existing loan (when collateral has appreciated) and open a new loan with the freed collateral. Burns the original, mints two replacements. |
+| `liquidateExpiredLoansFrom` | REVLoans | Clean up loans past the 10-year liquidation duration. Burns their NFTs and decrements accounting totals. |
+| `borrowableAmountFrom` | REVLoans | View: calculate how much can be borrowed for a given collateral amount using the bonding curve formula. |
+| `determineSourceFeeAmount` | REVLoans | View: calculate the time-proportional source fee for a loan repayment. |
+
+## Integration Points
+
+| Dependency | Import | Used For |
+|------------|--------|----------|
+| `@bananapus/core-v6` | `IJBController`, `IJBDirectory`, `IJBPermissions`, `IJBProjects`, `IJBTerminal`, `IJBPrices` | Project lifecycle, rulesets, token minting/burning, fund access, terminal payments, price feeds |
+| `@bananapus/721-hook-v6` | `IJB721TiersHook`, `IJB721TiersHookDeployer` | Deploying and registering tiered ERC-721 pay hooks |
+| `@bananapus/buyback-hook-v6` | `IJBBuybackHook` | Configuring Uniswap buyback pools per revnet |
+| `@bananapus/suckers-v6` | `IJBSuckerRegistry` | Deploying cross-chain suckers, checking sucker status for fee exemption |
+| `@croptop/core-v6` | `CTPublisher` | Configuring croptop posting criteria for 721 tiers |
+| `@bananapus/permission-ids-v6` | `JBPermissionIds` | Permission ID constants (SET_SPLIT_GROUPS, USE_ALLOWANCE, etc.) |
+| `@openzeppelin/contracts` | `ERC721`, `ERC2771Context`, `Ownable`, `SafeERC20` | Loan NFTs, meta-transactions, ownership, safe token transfers |
+| `@uniswap/permit2` | `IPermit2`, `IAllowanceTransfer` | Gasless token approvals for loan repayments |
+| `@prb/math` | `mulDiv` | Precise fixed-point multiplication and division |
+
+## Key Types
+
+| Struct/Enum | Key Fields | Used In |
+|-------------|------------|---------|
+| `REVConfig` | `description`, `baseCurrency`, `splitOperator`, `stageConfigurations[]`, `loanSources[]`, `loans` | `deployFor`, `deployWith721sFor` |
+| `REVStageConfig` | `startsAtOrAfter` (uint48), `initialIssuance` (uint112), `issuanceCutFrequency` (uint32), `issuanceCutPercent` (uint32), `cashOutTaxRate` (uint16), `splitPercent` (uint16), `splits[]`, `autoIssuances[]`, `extraMetadata` (uint16) | Translated into `JBRulesetConfig` by `REVDeployer` |
+| `REVDescription` | `name`, `ticker`, `uri`, `salt` | ERC-20 token deployment and project metadata |
+| `REVAutoIssuance` | `chainId` (uint32), `count` (uint104), `beneficiary` | Per-stage token auto-minting, cross-chain aware |
+| `REVLoan` | `amount` (uint112), `collateral` (uint112), `createdAt` (uint48), `prepaidFeePercent` (uint16), `prepaidDuration` (uint32), `source` | Stored per loan ID in `REVLoans` |
+| `REVLoanSource` | `token`, `terminal` (IJBPayoutTerminal) | Identifies which terminal and token a loan draws from |
+| `REVBuybackHookConfig` | `dataHook`, `hookToConfigure`, `poolConfigurations[]` | Buyback hook setup during deployment |
+| `REVBuybackPoolConfig` | `token`, `fee` (uint24), `twapWindow` (uint32) | Uniswap pool configuration for buyback |
+| `REVSuckerDeploymentConfig` | `deployerConfigurations[]`, `salt` | Cross-chain sucker deployment |
+| `REVDeploy721TiersHookConfig` | `baseline721HookConfiguration`, `salt`, `splitOperatorCanAdjustTiers`, `splitOperatorCanUpdateMetadata`, `splitOperatorCanMint`, `splitOperatorCanIncreaseDiscountPercent` | 721 hook deployment with operator permissions |
+| `REVCroptopAllowedPost` | `category` (uint24), `minimumPrice` (uint104), `minimumTotalSupply` (uint32), `maximumTotalSupply` (uint32), `allowedAddresses[]` | Croptop posting criteria |
+
+## Gotchas
+
+- `REVLoan.amount` and `REVLoan.collateral` are `uint112` -- truncation risk with very large values (Critical audit finding C-1).
+- `REVDeployer` stage configuration arrays must have increasing `startsAtOrAfter` values or deployment reverts (array out-of-bounds risk, C-2).
+- `REVLoans` token callbacks during borrow/repay create reentrancy surface (C-3). The contract uses burn-before-transfer and mint-after-transfer patterns.
+- `hasMintPermissionFor` calls `buybackHookOf[revnetId]` which could be `address(0)` -- the call chain through the buyback hook can revert (C-4).
+- The `REVDeployer` project NFT is permanently locked in the deployer contract. There is no function to release it. This is by design -- revnets are ownerless.
+- Auto-issuance stage IDs are based on `block.timestamp + i` where `i` is the stage index. If the first stage's `startsAtOrAfter` is 0, it becomes the deployment block timestamp (H-5).
+- `cashOutTaxRate` must be strictly less than `MAX_CASH_OUT_TAX_RATE` -- revnets cannot fully disable cash outs.
+- Cash out delay is 30 days (`CASH_OUT_DELAY = 2_592_000`), applied only when deploying an existing revnet to a new chain (first stage already started).
+- Loan IDs encode the revnet ID: `loanId = revnetId * 1_000_000_000_000 + loanNumber`. Use `revnetIdOfLoanWith(loanId)` to decode.
+- Loan liquidation duration is 10 years (`LOAN_LIQUIDATION_DURATION = 3650 days`). After this, collateral is forfeit.
+- The split operator has 6 default permissions (SET_SPLIT_GROUPS, SET_BUYBACK_POOL, SET_BUYBACK_TWAP, SET_PROJECT_URI, ADD_PRICE_FEED, SUCKER_SAFETY) plus any extras from 721 hook config.
+- `REVLoans` uses `permit2` for ERC-20 transfers as a fallback when standard allowance is insufficient.
+- The `FEE` constant is `25` (out of `MAX_FEE = 1000`), meaning a 2.5% cash out fee paid to the fee revnet.
+- `REV_PREPAID_FEE_PERCENT` is `10` (1%) -- this is the protocol-level fee on loans paid to the $REV revnet.
+- `MIN_PREPAID_FEE_PERCENT` is `25` (2.5%) and `MAX_PREPAID_FEE_PERCENT` is `500` (50%) -- bounds on the borrower-chosen prepaid fee.
+
+### CRITICAL: NATIVE_TOKEN Accounting on Non-ETH Chains
+
+When deploying a revnet to a chain where the native token is NOT ETH (e.g. Celo, Polygon), the terminal must NOT use `JBConstants.NATIVE_TOKEN` as its accounting context. `NATIVE_TOKEN` represents whatever is native on that chain (CELO on Celo, MATIC on Polygon), but `baseCurrency=1` (ETH) assumes ETH-denominated value.
+
+**The matching hash does NOT catch this.** It covers economic parameters (baseCurrency, stages, auto-issuances) but NOT terminal configurations, accounting contexts, or sucker token mappings. Two deployments with identical matching hashes can have completely different terminal setups.
+
+**On non-ETH chains:** Use ERC-20 WETH (e.g. `0xD221812de1BD094f35587EE8E174B07B6167D9Af` on Celo) or USDC as the terminal's accounting context.
+
+**Correct (Celo):**
+```solidity
+JBAccountingContext({
+    token: WETH_CELO,     // ERC-20 WETH, not native CELO
+    decimals: 18,
+    currency: uint32(uint160(WETH_CELO))
+})
+```
+
+**Wrong (Celo):**
+```solidity
+JBAccountingContext({
+    token: JBConstants.NATIVE_TOKEN,  // This is CELO, not ETH!
+    decimals: 18,
+    currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+})
+```
+
+See also: `SECURITY.md` in this repo and INTEROP-6 in `AUDIT_FINDINGS.md`.
+
+## Example Integration
+
+```solidity
+import {REVConfig} from "@rev-net/core-v6/src/structs/REVConfig.sol";
+import {REVStageConfig} from "@rev-net/core-v6/src/structs/REVStageConfig.sol";
+import {REVDescription} from "@rev-net/core-v6/src/structs/REVDescription.sol";
+import {REVBuybackHookConfig} from "@rev-net/core-v6/src/structs/REVBuybackHookConfig.sol";
+import {REVSuckerDeploymentConfig} from "@rev-net/core-v6/src/structs/REVSuckerDeploymentConfig.sol";
+import {IREVDeployer} from "@rev-net/core-v6/src/interfaces/IREVDeployer.sol";
+
+// Deploy a simple revnet with one stage.
+function deployRevnet(IREVDeployer deployer, JBTerminalConfig[] memory terminals) external {
+    // Define the stage: 1M tokens per unit, 10% issuance cut every 30 days, 20% cash out tax.
+    REVStageConfig[] memory stages = new REVStageConfig[](1);
+    stages[0] = REVStageConfig({
+        startsAtOrAfter: 0, // Start immediately (uses block.timestamp).
+        autoIssuances: new REVAutoIssuance[](0),
+        splitPercent: 2000, // 20% of new tokens go to splits.
+        splits: splits,     // Must have at least one split if splitPercent > 0.
+        initialIssuance: 1_000_000e18,
+        issuanceCutFrequency: 30 days,
+        issuanceCutPercent: 100_000_000, // 10% cut per period.
+        cashOutTaxRate: 2000, // 20% tax on cash outs.
+        extraMetadata: 0
+    });
+
+    REVConfig memory config = REVConfig({
+        description: REVDescription({
+            name: "My Revnet Token",
+            ticker: "MYREV",
+            uri: "ipfs://...",
+            salt: bytes32(0)
+        }),
+        baseCurrency: 1, // USD
+        splitOperator: msg.sender,
+        stageConfigurations: stages,
+        loanSources: new REVLoanSource[](0),
+        loans: address(0) // No loans contract.
+    });
+
+    // revnetId 0 = deploy new.
+    deployer.deployFor({
+        revnetId: 0,
+        configuration: config,
+        terminalConfigurations: terminals,
+        buybackHookConfiguration: REVBuybackHookConfig({
+            dataHook: IJBRulesetDataHook(address(0)),
+            hookToConfigure: IJBBuybackHook(address(0)),
+            poolConfigurations: new REVBuybackPoolConfig[](0)
+        }),
+        suckerDeploymentConfiguration: REVSuckerDeploymentConfig({
+            deployerConfigurations: new JBSuckerDeployerConfig[](0),
+            salt: bytes32(0)
+        })
+    });
+}
+```