@rev-net/core-v6 0.0.7 → 0.0.9

package/ADMINISTRATION.md

@@ -0,0 +1,186 @@
+# Administration
+
+Admin privileges and their scope in revnet-core-v6. Revnets are designed to be autonomous Juicebox projects with no traditional owner. This document covers what privileged operations exist, who can perform them, and -- critically -- what is intentionally made impossible.
+
+## Roles
+
+### Split Operator
+
+- **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).
+
+### REVLoans Owner (Ownable)
+
+- **How assigned:** Set at `REVLoans` contract deployment via the `owner` constructor parameter. Transferable via OpenZeppelin `Ownable.transferOwnership()`.
+- **Scope:** Global across all revnets using this loans contract. Controls only the loan NFT metadata URI resolver -- has no power over loan parameters, collateral, or funds.
+
+### REVDeployer (as Juicebox project owner)
+
+- **How assigned:** Automatic. When a revnet is deployed, the `REVDeployer` contract becomes the permanent owner of the Juicebox project NFT. If initializing an existing project, the caller's project NFT is irreversibly transferred to `REVDeployer`.
+- **Scope:** The deployer holds the project NFT and uses its owner authority to enforce revnet rules. It acts as a protocol-level constraint layer, not as a discretionary admin. No human can exercise this ownership.
+
+### Loan NFT Owner
+
+- **How assigned:** The `_msgSender()` who calls `borrowFrom()` receives the loan ERC-721. Transferable like any ERC-721.
+- **Scope:** Per-loan. Only the current NFT owner can repay the loan, return collateral, or reallocate collateral to a new loan.
+
+### Anyone (Permissionless)
+
+- **Scope:** Several functions are callable by any address with no access control, as documented in the Privileged Functions tables below.
+
+## Privileged Functions
+
+### REVDeployer
+
+| Function | Required Role | Permission ID | What It Does |
+|----------|--------------|---------------|-------------|
+| `deployFor()` | Anyone (new revnet) or Juicebox project owner (existing project) | None | Deploys a new revnet or irreversibly converts an existing Juicebox project into a revnet. |
+| `deployWith721sFor()` | Anyone (new revnet) or Juicebox project owner (existing project) | None | Same as `deployFor()` but also deploys a tiered ERC-721 hook and optional croptop posting rules. |
+| `deploySuckersFor()` | Split Operator | Checked via `_checkIfIsSplitOperatorOf()` | Deploys new cross-chain suckers for an existing revnet. Also requires the current ruleset's `extraMetadata` bit 2 to be set (allows deploying suckers). |
+| `setSplitOperatorOf()` | Split Operator | Checked via `_checkIfIsSplitOperatorOf()` | Replaces the current split operator with a new address. Revokes all operator permissions from the caller and grants them to the new address. |
+| `autoIssueFor()` | Anyone | None | Mints pre-configured auto-issuance tokens for a beneficiary once the relevant stage has started. Amounts are set at deployment and can only be claimed once. |
+| `burnHeldTokensOf()` | Anyone | None | Burns any of a revnet's tokens held by the `REVDeployer` contract (e.g., from reserved token splits that did not sum to 100%). |
+| `afterCashOutRecordedWith()` | Anyone (called by terminal) | None | Processes cash-out fees. No caller validation needed because a non-terminal caller would only be donating their own funds. |
+
+### Split Operator Permissions (granted via JBPermissions)
+
+The split operator receives the following Juicebox permission IDs, scoped to its revnet:
+
+| Permission ID | What It Allows |
+|---------------|----------------|
+| `SET_SPLIT_GROUPS` | Change how reserved tokens are distributed among split recipients. |
+| `SET_BUYBACK_POOL` | Configure which Uniswap V4 pool is used for the buyback hook. |
+| `SET_BUYBACK_TWAP` | Adjust the TWAP window for the buyback hook. |
+| `SET_PROJECT_URI` | Update the revnet's metadata URI. |
+| `ADD_PRICE_FEED` | Add a new price feed for the revnet. |
+| `SUCKER_SAFETY` | Manage sucker safety settings (e.g., emergency hatch). |
+| `SET_BUYBACK_HOOK` | Configure the buyback hook. |
+| `SET_ROUTER_TERMINAL` | Set the router terminal. |
+
+Optional 721 permissions (granted only if enabled at deployment via `REVDeploy721TiersHookConfig`):
+
+| Permission ID | Deployment Flag | What It Allows |
+|---------------|----------------|----------------|
+| `ADJUST_721_TIERS` | `splitOperatorCanAdjustTiers` | Add or remove ERC-721 tiers. |
+| `SET_721_METADATA` | `splitOperatorCanUpdateMetadata` | Update ERC-721 tier metadata. |
+| `MINT_721` | `splitOperatorCanMint` | Mint ERC-721s without payment from tiers with `allowOwnerMint`. |
+| `SET_721_DISCOUNT_PERCENT` | `splitOperatorCanIncreaseDiscountPercent` | Increase the discount percentage of a tier. |
+
+### REVLoans
+
+| Function | Required Role | Access Control | What It Does |
+|----------|--------------|----------------|-------------|
+| `borrowFrom()` | Anyone (must hold revnet tokens) | None -- but caller's tokens are burned as collateral | Opens a loan against revnet token collateral. |
+| `repayLoan()` | Loan NFT Owner | `_ownerOf(loanId) == _msgSender()` | Repays a loan (partially or fully) and returns collateral. |
+| `reallocateCollateralFromLoan()` | Loan NFT Owner | `_ownerOf(loanId) == _msgSender()` | Splits excess collateral from an existing loan into a new loan. |
+| `liquidateExpiredLoansFrom()` | Anyone | None | Liquidates loans that have exceeded the 10-year liquidation duration. Permanently destroys collateral. |
+| `setTokenUriResolver()` | REVLoans Owner | `onlyOwner` (OpenZeppelin Ownable) | Sets the contract that resolves loan NFT metadata URIs. |
+
+### Constructor-Level Permissions (set once at deployment)
+
+These permissions are granted in the `REVDeployer` constructor and apply globally (wildcard `projectId = 0`):
+
+| Grantee | Permission ID | Purpose |
+|---------|---------------|---------|
+| `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. |
+
+## Autonomous Design
+
+Revnets are designed to operate without a traditional project owner. The following mechanisms enforce autonomy:
+
+- **Ownership transfer is permanent.** When a revnet is deployed, the Juicebox project NFT is transferred to the `REVDeployer` contract. No human holds the project NFT. There is no function to transfer it back.
+- **No ruleset queuing.** The `REVDeployer` does not expose any function to queue new rulesets after deployment. The stage progression is fully determined at deploy time. Nobody -- not the split operator, not the deployer, not anyone -- can change the issuance schedule, cash-out tax rates, or stage timing after deployment.
+- **No approval hooks.** All rulesets are deployed with `approvalHook = address(0)`. There is no mechanism to block or delay stage transitions.
+- **Cash outs cannot be fully disabled.** The deployer enforces `cashOutTaxRate < MAX_CASH_OUT_TAX_RATE` for every stage, guaranteeing that token holders always retain some ability to cash out.
+- **Data hook is the deployer itself.** The `REVDeployer` is set as the data hook (`metadata.dataHook = address(this)`) for all rulesets, ensuring consistent fee and sucker logic without external admin control.
+- **Mint permission is restricted.** Only the loans contract, the buyback hook (and its delegates), and registered suckers can mint tokens. The split operator cannot mint fungible revnet tokens.
+- **No held fee manipulation.** The deployer has no function to process or return held fees arbitrarily.
+- **Owner minting is constrained.** While `allowOwnerMinting = true` is set in ruleset metadata, the "owner" is the `REVDeployer` contract. It only uses this to mint auto-issuance tokens (amounts fixed at deployment) and to return loan collateral.
+
+## Loan Administration
+
+The `REVLoans` contract has minimal admin surface by design:
+
+- **All economic parameters are constants.** Loan liquidation duration (10 years), fee percentages (MIN 2.5%, MAX 50%), and the REV fee (1%) are hardcoded as immutable constants. No admin can change them.
+- **The only admin function is `setTokenUriResolver()`**, which controls how loan NFTs render their metadata. This is purely cosmetic and has no effect on loan economics, collateral, or fund flows.
+- **Loan management is permissioned to NFT holders only.** Repayment, collateral reallocation, and refinancing require ownership of the specific loan's ERC-721 NFT.
+- **Liquidation is permissionless.** Anyone can call `liquidateExpiredLoansFrom()` for loans past the 10-year duration.
+
+## Immutable Configuration
+
+The following parameters are set at deployment and can never be changed:
+
+### REVDeployer (per-revnet, set at `deployFor` / `deployWith721sFor` time)
+- Stage schedule (start times, issuance rates, cut frequencies, cut percentages)
+- Cash-out tax rates per stage
+- Split percentages per stage
+- Auto-issuance amounts and beneficiaries
+- Base currency
+- ERC-20 token name and symbol
+- Encoded configuration hash (used for cross-chain sucker deployment verification)
+
+### REVDeployer (global, set at contract deployment)
+- `CONTROLLER` -- the Juicebox controller
+- `DIRECTORY` -- the Juicebox directory
+- `PROJECTS` -- the Juicebox projects NFT contract
+- `PERMISSIONS` -- the Juicebox permissions contract
+- `SUCKER_REGISTRY` -- the sucker registry
+- `BUYBACK_HOOK` -- the buyback hook / data hook
+- `HOOK_DEPLOYER` -- the 721 tiers hook deployer
+- `PUBLISHER` -- the croptop publisher
+- `LOANS` -- the loans contract address
+- `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
+
+### REVLoans (global, set at contract deployment)
+- `CONTROLLER`, `DIRECTORY`, `PRICES`, `PROJECTS` -- protocol infrastructure
+- `REV_ID` -- the REV revnet that receives loan fees
+- `PERMIT2` -- the permit2 contract
+- `LOAN_LIQUIDATION_DURATION` -- 10 years (3650 days)
+- `MIN_PREPAID_FEE_PERCENT` -- 2.5% (`25` out of `MAX_FEE = 1000`)
+- `MAX_PREPAID_FEE_PERCENT` -- 50% (`500` out of `MAX_FEE = 1000`)
+- `REV_PREPAID_FEE_PERCENT` -- 1% (`10` out of `MAX_FEE = 1000`)
+
+## Admin Boundaries
+
+What admins **cannot** do -- this is the most important section for understanding revnet security guarantees:
+
+### The Split Operator Cannot:
+- Change issuance rates, schedules, or weight decay
+- Modify cash-out tax rates
+- Queue new rulesets or stages
+- Pause or disable cash outs
+- Mint fungible revnet tokens (only 721 minting if explicitly enabled at deploy)
+- Access or redirect treasury funds (no payout limit control)
+- Upgrade or migrate the revnet's controller
+- Change the revnet's terminals
+- Transfer the project NFT
+- Modify fund access limits or surplus allowances
+- Change the data hook or approval hook
+- Affect loan parameters or collateral
+
+### The REVLoans Owner Cannot:
+- Change loan interest rates, fees, or liquidation timing
+- Access or redirect collateral or borrowed funds
+- Prevent loan creation, repayment, or liquidation
+- Mint or burn tokens
+- Affect any revnet's configuration
+
+### The REVDeployer Contract Cannot (even though it holds the project NFT):
+- Queue new rulesets (no public or internal function exists for this)
+- Transfer the project NFT to any other address
+- Change terminals or the controller
+- Modify fund access limits after deployment
+- Override the data hook logic
+- Selectively block cash outs (beyond the time-limited `CASH_OUT_DELAY` for cross-chain deployments)
+
+### Nobody Can:
+- Change a revnet's stage schedule after deployment
+- Prevent token holders from eventually cashing out
+- Extract funds from the treasury without going through the bonding curve
+- Modify the fee structure (2.5% cash-out fee, loan fees)
+- Change which contract is the data hook for a revnet
+- Alter auto-issuance amounts after deployment (they can only be claimed, not changed)

package/ARCHITECTURE.md

@@ -0,0 +1,87 @@
+# revnet-core-v6 — Architecture
+
+## Purpose
+
+Autonomous revenue networks ("revnets") built on Juicebox V6. REVDeployer creates projects with pre-programmed multi-stage rulesets that cannot be changed after deployment. REVLoans enables borrowing against locked revnet tokens.
+
+## Contract Map
+
+```
+src/
+├── REVDeployer.sol  — Deploys revnets: stages → rulesets, data hook, buyback, suckers, 721 tiers
+├── REVLoans.sol     — Borrow against locked revnet tokens (10-year max, gradual liquidation)
+├── interfaces/
+│   ├── IREVDeployer.sol
+│   └── IREVLoans.sol
+└── structs/         — REVConfig, REVStageConfig, REVLoanSource, REVAutoIssuance, etc.
+```
+
+## Key Data Flows
+
+### Revnet Deployment
+```
+Deployer → REVDeployer.deployFor()
+  → Create JB project via JBController
+  → Convert REV stages → JBRulesetConfigs
+    → Each stage: duration, weight, cashOutTaxRate, splits
+    → Auto-issuance: pre-mint tokens to specified beneficiaries per chain
+  → Set REVDeployer as data hook (controls pay + cashout behavior)
+  → Configure buyback hook (swap vs mint decision)
+  → Deploy suckers for cross-chain operation
+  → Deploy 721 tiers if specified
+  → Compute matching hash for cross-chain deployment verification
+```
+
+### Data Hook Behavior
+```
+Payment → REVDeployer.beforePayRecordedWith()
+  → Delegate to buyback hook for swap-vs-mint decision
+  → Return pay hook specifications
+
+Cash Out → REVDeployer.beforeCashOutRecordedWith()
+  → If caller is a sucker: 0% cash out tax (bridging privilege)
+  → Otherwise: apply configured cashOutTaxRate
+  → Return cash out hook specifications
+```
+
+### Loan Flow
+```
+Borrower → REVLoans.borrowFrom()
+  → Lock borrower's revnet tokens as collateral
+  → Calculate max borrow based on bonding curve value
+  → Transfer borrowed funds to borrower
+  → Create loan with 10-year max term
+
+Repay → REVLoans.repayLoan()
+  → Accept repayment (principal + prepay fee)
+  → Return locked collateral tokens to borrower
+
+Liquidate → REVLoans.liquidateLoan()
+  → After loan term, gradually release collateral
+  → Liquidation schedule spreads over time
+```
+
+## Extension Points
+
+| Point | Interface | Purpose |
+|-------|-----------|---------|
+| Data hook | `IJBRulesetDataHook` | REVDeployer acts as data hook for all revnets |
+| Buyback hook | `IJBBuybackHook` | Swap-vs-mint decision on payments |
+| Sucker integration | `IJBSucker` | Cross-chain token bridging |
+| 721 tiers | `IJB721TiersHook` | NFT tier rewards |
+
+## Dependencies
+- `@bananapus/core-v6` — Core protocol
+- `@bananapus/721-hook-v6` — NFT tiers
+- `@bananapus/buyback-hook-v6` — DEX buyback
+- `@bananapus/suckers-v6` — Cross-chain bridging
+- `@bananapus/router-terminal-v6` — Payment routing
+- `@bananapus/permission-ids-v6` — Permission constants
+- `@croptop/core-v6` — Croptop integration
+- `@openzeppelin/contracts` — Standard utilities
+
+## Key Design Decisions
+- Stages are immutable after deployment — no owner can change ruleset parameters
+- Matching hash ensures cross-chain deployments have identical economic parameters
+- REVDeployer is the data hook for all revnets it deploys — centralizes behavioral control
+- Loans use bonding curve value, not market price — immune to external price manipulation

package/README.md

@@ -62,7 +62,7 @@ Revnets are autonomous Juicebox projects with predetermined economic stages. Eac
 
 | Contract | Description |
 |----------|-------------|
-| `REVDeployer` | 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. |
+| `REVDeployer` | 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. When 721 tier splits are active, adjusts the payment weight so the terminal only mints tokens proportional to the amount entering the project treasury (the split portion is forwarded separately). |
 | `REVLoans` | 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
@@ -114,7 +114,9 @@ src/
     REVAutoIssuance.sol                          # Per-stage cross-chain premint
     REVLoan.sol                                  # Loan state
     REVLoanSource.sol                            # Terminal + token pair for loans
-    REVDeploy721TiersHookConfig.sol              # 721 hook deployment config
+    REVBaseline721HookConfig.sol                 # 721 hook config (omits issueTokensForSplits)
+    REV721TiersHookFlags.sol                     # 721 hook flags for revnets (no issueTokensForSplits)
+    REVDeploy721TiersHookConfig.sol              # 721 hook deployment config wrapper
     REVCroptopAllowedPost.sol                    # Croptop posting criteria
     REVSuckerDeploymentConfig.sol                # Cross-chain sucker deployment
 test/

package/RISKS.md

@@ -0,0 +1,49 @@
+# revnet-core-v6 — Risks
+
+## Trust Assumptions
+
+1. **REVDeployer Contract** — Acts as data hook for all deployed revnets. A bug in REVDeployer affects every revnet's pay and cashout behavior.
+2. **Immutable Stages** — Once deployed, stage parameters cannot be changed. If configured incorrectly, there is no fix (by design — this IS the trust model).
+3. **Buyback Hook** — REVDeployer delegates to the buyback hook for swap-vs-mint decisions. Buyback hook failure falls back to direct minting.
+4. **Suckers** — Cross-chain bridge implementations trusted for token transport. Bridge compromise = fund loss.
+5. **Core Protocol** — Relies on JBController, JBMultiTerminal, JBTerminalStore for correct operation.
+
+## Known Risks
+
+| Risk | Description | Mitigation |
+|------|-------------|------------|
+| Irreversible deployment | Stage parameters cannot be changed after deployment | Thorough testing before deploy; matching hash verification |
+| Loan collateral manipulation | Attacker inflates surplus to borrow more, then deflates | Borrow based on bonding curve value at time of borrow; existing loans unaffected by surplus changes |
+| 10-year liquidation drift | Collateral real value may diverge from loan over 10 years | Gradual liquidation schedule; early repayment available |
+| Loans beat cash-outs | Above ~39% cashOutTaxRate, borrowing is more capital-efficient than cashing out | By design (CryptoEconLab finding); creates natural demand for loans |
+| Matching hash gap | Hash covers economic parameters but NOT terminal configs, accounting contexts, or token mappings | Verify full configuration manually before cross-chain deploy |
+
+## INTEROP-6: NATIVE_TOKEN on Non-ETH Chains
+
+**Severity:** Medium
+**Status:** Acknowledged — by design
+
+When a revnet expands to a chain where the native token is not ETH (e.g., Celo), using `NATIVE_TOKEN` as the accounting context creates a semantic mismatch — CELO payments priced as ETH without a price feed.
+
+**Impact:** Issuance mispricing, surplus fragmentation, cross-chain arbitrage.
+
+**Safe chains:** Ethereum, Optimism, Base, Arbitrum
+**Affected chains:** Celo, Polygon, Avalanche, BNB Chain
+
+**Mitigation:** Use WETH ERC20 (not NATIVE_TOKEN) on non-ETH chains. Map `WETH → WETH` in sucker token mappings.
+
+## Privileged Roles
+
+| Role | Capabilities | Notes |
+|------|-------------|-------|
+| Deployer (one-time) | Configures all stage parameters | Parameters immutable after deploy |
+| Auto-issuance beneficiaries | Receive pre-minted tokens per stage | Configured at deploy time |
+| Suckers | 0% cashout tax privilege | Enables cross-chain bridging without fee |
+
+## Reentrancy Considerations
+
+| Function | Protection | Risk |
+|----------|-----------|------|
+| `REVLoans.borrowFrom` | Collateral locked BEFORE funds transferred | LOW |
+| `REVLoans.repayLoan` | Loan state cleared BEFORE collateral returned | LOW |
+| `REVDeployer.beforePayRecordedWith` | View function, no state changes | NONE |

package/SKILLS.md

@@ -25,7 +25,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 | Function | What it does |
 |----------|-------------|
-| `REVDeployer.beforePayRecordedWith(context)` | Returns adjusted weight from buyback hook and assembles pay hook specs (721 hook if present + buyback hook). |
+| `REVDeployer.beforePayRecordedWith(context)` | Calls the 721 hook first for split specs, then calls the buyback hook with a reduced amount context (payment minus split amount). Adjusts the returned weight proportionally for splits (`weight = mulDiv(weight, amount - splitAmount, amount)`) so the terminal only mints tokens for the amount entering the project. Assembles pay hook specs (721 hook specs first, then buyback spec). |
 | `REVDeployer.beforeCashOutRecordedWith(context)` | If sucker: returns full amount with 0 tax (fee exempt). Otherwise: calculates 2.5% fee, enforces 30-day cash-out delay, returns modified count + fee hook spec. |
 | `REVDeployer.afterCashOutRecordedWith(context)` | Cash-out hook callback. Receives fee amount and pays it to the fee revnet's terminal. Falls back to returning funds if fee payment fails. |
 | `REVDeployer.hasMintPermissionFor(revnetId, ruleset, addr)` | Returns `true` for: loans contract, buyback hook, buyback hook delegates, or suckers. |
@@ -86,7 +86,9 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REVAutoIssuance` | `chainId` (uint32), `count` (uint104), `beneficiary` | Per-stage cross-chain token auto-minting |
 | `REVLoan` | `amount` (uint112), `collateral` (uint112), `createdAt` (uint48), `prepaidFeePercent` (uint16), `prepaidDuration` (uint32), `source` (REVLoanSource) | Per-loan state in `REVLoans` |
 | `REVLoanSource` | `token`, `terminal` (IJBPayoutTerminal) | Identifies which terminal and token a loan draws from |
-| `REVDeploy721TiersHookConfig` | `baseline721HookConfiguration`, `salt`, `splitOperatorCanAdjustTiers`, `CanUpdateMetadata`, `CanMint`, `CanIncreaseDiscountPercent` | 721 hook deployment with operator permissions |
+| `REVDeploy721TiersHookConfig` | `baseline721HookConfiguration` (REVBaseline721HookConfig), `salt`, `splitOperatorCanAdjustTiers`, `CanUpdateMetadata`, `CanMint`, `CanIncreaseDiscountPercent` | 721 hook deployment with operator permissions. Uses `REVBaseline721HookConfig` (not `JBDeploy721TiersHookConfig`) to omit `issueTokensForSplits` — revnets always force it to `false`. |
+| `REVBaseline721HookConfig` | `name`, `symbol`, `baseUri`, `tokenUriResolver`, `contractUri`, `tiersConfig`, `reserveBeneficiary`, `flags` (REV721TiersHookFlags) | Same as `JBDeploy721TiersHookConfig` but uses `REV721TiersHookFlags` which omits `issueTokensForSplits`. |
+| `REV721TiersHookFlags` | `noNewTiersWithReserves`, `noNewTiersWithVotes`, `noNewTiersWithOwnerMinting`, `preventOverspending` | Same as `JB721TiersHookFlags` minus `issueTokensForSplits`. Revnets do their own weight adjustment for splits. |
 | `REVCroptopAllowedPost` | `category` (uint24), `minimumPrice` (uint104), `minimumTotalSupply` (uint32), `maximumTotalSupply` (uint32), `allowedAddresses[]` | Croptop posting criteria |
 | `REVSuckerDeploymentConfig` | `deployerConfigurations[]`, `salt` | Cross-chain sucker deployment |
 
@@ -154,6 +156,8 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 16. **Cross-chain config matching.** `hashedEncodedConfigurationOf` covers economic parameters (baseCurrency, stages, auto-issuances) but NOT terminal configurations, accounting contexts, or sucker token mappings. Two deployments with identical hashes can have different terminal setups.
 17. **Loan fee model.** Three layers: (1) REV protocol fee (1%) taken when funds pulled, (2) terminal fee (2.5%) charged by `useAllowanceOf`, (3) prepaid source fee (2.5%-50%, borrower-chosen) that buys an interest-free window. After the prepaid window, time-proportional source fee accrues linearly over the remaining 10-year loan duration.
 18. **Permit2 fallback.** `REVLoans` uses permit2 for ERC-20 transfers as a fallback when standard allowance is insufficient. Wrapped in try-catch.
+19. **39.16% cash-out tax crossover.** Below ~39% cash-out tax, cashing out is more capital-efficient than borrowing. Above ~39%, loans become more efficient because they preserve upside while providing liquidity. Based on CryptoEconLab academic research. Design implication: revnets intended for active token trading should consider this threshold when setting `cashOutTaxRate`.
+20. **REVDeployer always deploys a 721 hook** via `HOOK_DEPLOYER.deployHookFor` — even if `baseline721HookConfiguration` has empty tiers. This is correct by design: it lets the split operator add and sell NFTs later without migration. Non-revnet projects should follow the same pattern by using `JB721TiersHookProjectDeployer.launchProjectFor` (or `JBOmnichainDeployer.launch721ProjectFor`) instead of bare `launchProjectFor`.
 
 ### NATIVE_TOKEN Accounting on Non-ETH Chains
 
@@ -242,6 +246,22 @@ loans.borrowFrom({
     prepaidFeePercent: 25                  // 2.5% prepaid fee (minimum)
 });
 
+// --- Reallocate collateral (refinance) ---
+// Remove 500 tokens of collateral from an existing loan,
+// use them (plus 200 new tokens) to open a fresh loan.
+// The original loan shrinks, and a new loan NFT is minted.
+(uint256 reallocatedLoanId, uint256 newLoanId, , ) = loans.reallocateCollateralFromLoan({
+    loanId: loanId,
+    collateralCountToTransfer: 500e18,     // Move 500 tokens out of existing loan
+    source: REVLoanSource({ token: JBConstants.NATIVE_TOKEN, terminal: terminal }),
+    minBorrowAmount: 0,
+    collateralCountToAdd: 200e18,          // Add 200 fresh tokens on top
+    beneficiary: payable(msg.sender),      // Receive new loan proceeds
+    prepaidFeePercent: 25                  // 2.5% prepaid fee on new loan
+});
+// Result: original loan now has 500 fewer collateral tokens (reallocatedLoanId),
+// new loan has 700 tokens of collateral (newLoanId).
+
 // --- Repay a loan ---
 
 loans.repayLoan({