@rev-net/core-v6 0.0.14 → 0.0.16

package/SKILLS.md

@@ -15,42 +15,43 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 ### Deployment
 
-| Function | What it does |
-|----------|-------------|
-| `REVDeployer.deployFor(revnetId, config, terminals, suckerConfig)` | Deploy a new revnet (`revnetId=0`) or convert an existing Juicebox project. Encodes stage configs into rulesets, deploys ERC-20 token, initializes buyback pool at 1:1 price, sets up split operator, suckers, loans permissions, and deploys a default empty tiered ERC-721 hook. |
-| `REVDeployer.deployFor(revnetId, config, terminals, suckerConfig, hookConfig, allowedPosts)` | Same as `deployFor` but deploys a tiered ERC-721 hook with pre-configured tiers. Optionally configures Croptop posting criteria and grants publisher permission to add tiers. |
-| `REVDeployer.deploySuckersFor(revnetId, suckerConfig)` | Deploy new cross-chain suckers post-launch. Split operator only. Validates ruleset allows sucker deployment (bit 2 of `extraMetadata`). Uses stored config hash for cross-chain matching. |
+| Function | Permissions | What it does |
+|----------|------------|-------------|
+| `REVDeployer.deployFor(revnetId, config, terminals, suckerConfig)` | Permissionless | Deploy a new revnet (`revnetId=0`) or convert an existing Juicebox project. Encodes stage configs into rulesets, deploys ERC-20 token, initializes buyback pool at 1:1 price, sets up split operator, suckers, loans permissions, and deploys a default empty tiered ERC-721 hook. |
+| `REVDeployer.deployFor(revnetId, config, terminals, suckerConfig, hookConfig, allowedPosts)` | Permissionless | Same as `deployFor` but deploys a tiered ERC-721 hook with pre-configured tiers. Optionally configures Croptop posting criteria and grants publisher permission to add tiers. |
+| `REVDeployer.deploySuckersFor(revnetId, suckerConfig)` | Split operator | Deploy new cross-chain suckers post-launch. Validates ruleset allows sucker deployment (bit 2 of `extraMetadata`). Uses stored config hash for cross-chain matching. |
 
 ### Data Hooks
 
-| Function | What it does |
-|----------|-------------|
-| `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. |
+| Function | Permissions | What it does |
+|----------|------------|-------------|
+| `REVDeployer.beforePayRecordedWith(context)` | Terminal callback | 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)` | Terminal callback | 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)` | Permissionless | 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)` | View | Returns `true` for: loans contract, buyback hook, buyback hook delegates, or suckers. |
 
 ### Split Operator
 
-| Function | What it does |
-|----------|-------------|
-| `REVDeployer.setSplitOperatorOf(revnetId, newOperator)` | Replace the current split operator. Only callable by the current split operator. Revokes old permissions, grants new ones. |
+| Function | Permissions | What it does |
+|----------|------------|-------------|
+| `REVDeployer.setSplitOperatorOf(revnetId, newOperator)` | Split operator | Replace the current split operator. Revokes old permissions, grants new ones. |
 
 ### Auto-Issuance
 
-| Function | What it does |
-|----------|-------------|
-| `REVDeployer.autoIssueFor(revnetId, stageId, beneficiary)` | **Permissionless.** Mint pre-configured auto-issuance tokens for a beneficiary once a stage has started. One-time per stage per beneficiary. |
-| `REVDeployer.burnHeldTokensOf(revnetId)` | **Permissionless.** Burn any reserved tokens held by the deployer (when splits < 100%). |
+| Function | Permissions | What it does |
+|----------|------------|-------------|
+| `REVDeployer.autoIssueFor(revnetId, stageId, beneficiary)` | Permissionless | Mint pre-configured auto-issuance tokens for a beneficiary once a stage has started. One-time per stage per beneficiary. |
+| `REVDeployer.burnHeldTokensOf(revnetId)` | Permissionless | Burn any reserved tokens held by the deployer (when splits < 100%). |
 
 ### Loans -- Borrowing
 
-| Function | What it does |
-|----------|-------------|
-| `REVLoans.borrowFrom(revnetId, source, minBorrowAmount, collateralCount, beneficiary, prepaidFeePercent)` | Open a loan: burn collateral tokens, pull funds from revnet via `useAllowanceOf`, pay REV fee (1%) + terminal fee (2.5%), transfer remainder to beneficiary, mint loan NFT. |
-| `REVLoans.repayLoan(loanId, maxRepayAmount, collateralToReturn, beneficiary, allowance)` | Repay fully or partially. Returns funds to revnet via `addToBalanceOf`, re-mints collateral tokens, burns/replaces the loan NFT. Supports permit2 signatures. |
-| `REVLoans.reallocateCollateralFromLoan(loanId, collateralToRemove, source, minBorrowAmount, collateralToAdd, beneficiary, prepaidFeePercent)` | Refinance: remove excess collateral from an existing loan and open a new loan with the freed collateral. Burns original, mints two replacements. |
-| `REVLoans.liquidateExpiredLoansFrom(revnetId, startingLoanId, count)` | **Permissionless.** Clean up loans past the 10-year liquidation duration. Burns NFTs and decrements accounting totals. Collateral is permanently lost. |
+| Function | Permissions | What it does |
+|----------|------------|-------------|
+| `REVLoans.borrowFrom(revnetId, source, minBorrowAmount, collateralCount, beneficiary, prepaidFeePercent)` | Permissionless (caller must grant BURN_TOKENS to REVLoans) | Open a loan: burn collateral tokens, pull funds from revnet via `useAllowanceOf`, pay REV fee (1%) + terminal fee (2.5%), transfer remainder to beneficiary, mint loan NFT. |
+| `REVLoans.repayLoan(loanId, maxRepayBorrowAmount, collateralCountToReturn, beneficiary, allowance)` | Loan NFT owner | Repay fully or partially. Returns funds to revnet via `addToBalanceOf`, re-mints collateral tokens, burns/replaces the loan NFT. Supports permit2 signatures. |
+| `REVLoans.reallocateCollateralFromLoan(loanId, collateralCountToTransfer, source, minBorrowAmount, collateralCountToAdd, beneficiary, prepaidFeePercent)` | Loan NFT owner | Refinance: remove excess collateral from an existing loan and open a new loan with the freed collateral. Burns original, mints two replacements. |
+| `REVLoans.liquidateExpiredLoansFrom(revnetId, startingLoanId, count)` | Permissionless | Clean up loans past the 10-year liquidation duration. Burns NFTs and decrements accounting totals. Collateral is permanently lost. |
+| `REVLoans.setTokenUriResolver(resolver)` | Contract owner (`onlyOwner`) | Set the `IJBTokenUriResolver` used for loan NFT token URIs. |
 
 ### Loans -- Views
 
@@ -68,7 +69,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 |------------|--------|----------|
 | `@bananapus/core-v6` | `IJBController`, `IJBDirectory`, `IJBPermissions`, `IJBProjects`, `IJBTerminal`, `IJBPrices`, `JBConstants`, `JBCashOuts`, `JBSurplus` | Project lifecycle, rulesets, token minting/burning, fund access, terminal payments, price feeds, bonding curve |
 | `@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/buyback-hook-v6` | `IJBBuybackHookRegistry` | 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.) |
@@ -92,6 +93,71 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `REVCroptopAllowedPost` | `category` (uint24), `minimumPrice` (uint104), `minimumTotalSupply` (uint32), `maximumTotalSupply` (uint32), `allowedAddresses[]` | Croptop posting criteria |
 | `REVSuckerDeploymentConfig` | `deployerConfigurations[]`, `salt` | Cross-chain sucker deployment |
 
+## Events
+
+### REVDeployer
+
+| Event | When It Fires |
+|-------|---------------|
+| `AutoIssue(revnetId, stageId, beneficiary, count, caller)` | When tokens are auto-issued for a beneficiary during a stage via `autoIssueFor`. |
+| `BurnHeldTokens(revnetId, count, caller)` | When held tokens are burned from the deployer contract via `burnHeldTokensOf`. |
+| `DeployRevnet(revnetId, configuration, terminalConfigurations, suckerDeploymentConfiguration, rulesetConfigurations, encodedConfigurationHash, caller)` | When a new revnet is deployed via `deployFor`. |
+| `DeploySuckers(revnetId, encodedConfigurationHash, suckerDeploymentConfiguration, caller)` | When suckers are deployed for a revnet via `deploySuckersFor`. |
+| `ReplaceSplitOperator(revnetId, newSplitOperator, caller)` | When the split operator of a revnet is replaced via `setSplitOperatorOf`. |
+| `SetCashOutDelay(revnetId, cashOutDelay, caller)` | When the cash out delay is set for a revnet during deployment to a new chain. |
+| `StoreAutoIssuanceAmount(revnetId, stageId, beneficiary, count, caller)` | When an auto-issuance amount is stored for a beneficiary during deployment. |
+
+### REVLoans
+
+| Event | When It Fires |
+|-------|---------------|
+| `Borrow(loanId, revnetId, loan, source, borrowAmount, collateralCount, sourceFeeAmount, beneficiary, caller)` | When a loan is created by borrowing from a revnet via `borrowFrom`. |
+| `Liquidate(loanId, revnetId, loan, caller)` | When a loan is liquidated after exceeding the 10-year liquidation duration via `liquidateExpiredLoansFrom`. |
+| `ReallocateCollateral(loanId, revnetId, reallocatedLoanId, reallocatedLoan, removedCollateralCount, caller)` | When collateral is reallocated from one loan to a new loan via `reallocateCollateralFromLoan`. |
+| `RepayLoan(loanId, revnetId, paidOffLoanId, loan, paidOffLoan, repayBorrowAmount, sourceFeeAmount, collateralCountToReturn, beneficiary, caller)` | When a loan is repaid via `repayLoan`. |
+| `SetTokenUriResolver(resolver, caller)` | When the token URI resolver is changed via `setTokenUriResolver`. |
+
+## Errors
+
+### REVDeployer
+
+| Error | When It Fires |
+|-------|---------------|
+| `REVDeployer_AutoIssuanceBeneficiaryZeroAddress()` | When an auto-issuance config has a zero-address beneficiary. |
+| `REVDeployer_CashOutDelayNotFinished(cashOutDelay, blockTimestamp)` | When a cash out is attempted before the 30-day delay has elapsed. |
+| `REVDeployer_CashOutsCantBeTurnedOffCompletely(cashOutTaxRate, maxCashOutTaxRate)` | When `cashOutTaxRate` equals `MAX_CASH_OUT_TAX_RATE` (10,000). Must be strictly less. |
+| `REVDeployer_MustHaveSplits()` | When a stage with `splitPercent > 0` has no splits configured. |
+| `REVDeployer_NothingToAutoIssue()` | When `autoIssueFor` is called but no tokens are available for auto-issuance. |
+| `REVDeployer_NothingToBurn()` | When `burnHeldTokensOf` is called but the deployer holds no tokens. |
+| `REVDeployer_RulesetDoesNotAllowDeployingSuckers()` | When `deploySuckersFor` is called but the current ruleset's `extraMetadata` bit 2 is not set. |
+| `REVDeployer_StageNotStarted(stageId)` | When `autoIssueFor` is called for a stage that hasn't started yet. |
+| `REVDeployer_StagesRequired()` | When `deployFor` is called with zero stage configurations. |
+| `REVDeployer_StageTimesMustIncrease()` | When stage `startsAtOrAfter` values are not strictly increasing. |
+| `REVDeployer_Unauthorized(revnetId, caller)` | When a non-split-operator calls a split-operator-only function. |
+
+### REVLoans
+
+| Error | When It Fires |
+|-------|---------------|
+| `REVLoans_CollateralExceedsLoan(collateralToReturn, loanCollateral)` | When trying to return more collateral than the loan holds. |
+| `REVLoans_InvalidPrepaidFeePercent(prepaidFeePercent, min, max)` | When `prepaidFeePercent` is outside the allowed range (2.5%--50%). |
+| `REVLoans_InvalidTerminal(terminal, revnetId)` | When the specified terminal is not registered for the revnet. |
+| `REVLoans_LoanExpired(timeSinceLoanCreated, loanLiquidationDuration)` | When trying to repay or reallocate an expired loan. |
+| `REVLoans_LoanIdOverflow()` | When the loan ID counter exceeds the per-revnet trillion-ID namespace. |
+| `REVLoans_NewBorrowAmountGreaterThanLoanAmount(newBorrowAmount, loanAmount)` | When a reallocation would produce a reduced loan with a larger borrow amount than the original. |
+| `REVLoans_NoMsgValueAllowed()` | When `msg.value > 0` on a non-native-token repayment. |
+| `REVLoans_NotEnoughCollateral()` | When the caller does not have enough tokens for the requested collateral. |
+| `REVLoans_NothingToRepay()` | When `repayLoan` is called with zero repay amount and zero collateral to return. |
+| `REVLoans_OverMaxRepayBorrowAmount(maxRepayBorrowAmount, repayBorrowAmount)` | When the actual repay cost exceeds the caller's `maxRepayBorrowAmount`. |
+| `REVLoans_OverflowAlert(value, limit)` | When a value would overflow `uint112` storage. |
+| `REVLoans_PermitAllowanceNotEnough(allowanceAmount, requiredAmount)` | When the permit2 allowance is insufficient for the repayment. |
+| `REVLoans_ReallocatingMoreCollateralThanBorrowedAmountAllows(newBorrowAmount, loanAmount)` | When the collateral being transferred out would leave the original loan undercollateralized. |
+| `REVLoans_SourceMismatch()` | When `reallocateCollateralFromLoan` specifies a source that doesn't match the existing loan's source. |
+| `REVLoans_Unauthorized(caller, owner)` | When a non-owner tries to repay or reallocate someone else's loan. |
+| `REVLoans_UnderMinBorrowAmount(minBorrowAmount, borrowAmount)` | When the actual borrow amount is less than the caller's `minBorrowAmount`. |
+| `REVLoans_ZeroBorrowAmount()` | When a borrow or reallocation would result in zero borrowed funds. |
+| `REVLoans_ZeroCollateralLoanIsInvalid()` | When a loan would end up with zero collateral. |
+
 ## Constants
 
 ### REVDeployer
@@ -102,6 +168,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | `FEE` | 25 (of MAX_FEE=1000) | 2.5% cash-out fee paid to fee revnet |
 | `DEFAULT_BUYBACK_POOL_FEE` | 10,000 | 1% Uniswap fee tier for default buyback pools |
 | `DEFAULT_BUYBACK_TWAP_WINDOW` | 2 days | TWAP observation window for buyback price |
+| `DEFAULT_BUYBACK_TICK_SPACING` | 200 | Tick spacing for default buyback V4 pools |
 
 ### REVLoans
 
@@ -117,24 +184,25 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 
 ### REVDeployer
 
-| Mapping | Type | Purpose |
-|---------|------|---------|
-| `amountToAutoIssue` | `revnetId => stageId => beneficiary => uint256` | Premint tokens per stage per beneficiary |
-| `cashOutDelayOf` | `revnetId => uint256` | Timestamp when cash outs unlock (0 = no delay) |
-| `hashedEncodedConfigurationOf` | `revnetId => bytes32` | Config hash for cross-chain sucker validation |
-| `tiered721HookOf` | `revnetId => address` | Deployed 721 hook address (if any) |
-| `_extraOperatorPermissions` | `revnetId => uint256[]` | Custom permissions for split operator |
+| Mapping | Visibility | Type | Purpose |
+|---------|-----------|------|---------|
+| `amountToAutoIssue` | `public` | `revnetId => stageId => beneficiary => uint256` | Premint tokens per stage per beneficiary |
+| `cashOutDelayOf` | `public` | `revnetId => uint256` | Timestamp when cash outs unlock (0 = no delay) |
+| `hashedEncodedConfigurationOf` | `public` | `revnetId => bytes32` | Config hash for cross-chain sucker validation |
+| `tiered721HookOf` | `public` | `revnetId => address` | Deployed 721 hook address (if any) |
+| `_extraOperatorPermissions` | `internal` | `revnetId => uint256[]` | Custom permissions for split operator (no auto-getter) |
 
 ### REVLoans
 
-| Mapping | Type | Purpose |
-|---------|------|---------|
-| `isLoanSourceOf` | `revnetId => terminal => token => bool` | Is this (terminal, token) pair used for loans? |
-| `totalLoansBorrowedFor` | `revnetId => uint256` | Counter for loan numbering |
-| `totalBorrowedFrom` | `revnetId => terminal => token => uint256` | Tracks debt per loan source |
-| `totalCollateralOf` | `revnetId => uint256` | Sum of all burned collateral |
-| `_loanOf` | `loanId => REVLoan` | Per-loan state |
-| `_loanSourcesOf` | `revnetId => REVLoanSource[]` | Array of all loan sources used |
+| Mapping | Visibility | Type | Purpose |
+|---------|-----------|------|---------|
+| `isLoanSourceOf` | `public` | `revnetId => terminal => token => bool` | Is this (terminal, token) pair used for loans? |
+| `totalLoansBorrowedFor` | `public` | `revnetId => uint256` | Counter for loan numbering |
+| `totalBorrowedFrom` | `public` | `revnetId => terminal => token => uint256` | Tracks debt per loan source |
+| `totalCollateralOf` | `public` | `revnetId => uint256` | Sum of all burned collateral |
+| `_loanOf` | `internal` | `loanId => REVLoan` | Per-loan state (use `loanOf(loanId)` view) |
+| `_loanSourcesOf` | `internal` | `revnetId => REVLoanSource[]` | Array of all loan sources used (use `loanSourcesOf(revnetId)` view) |
+| `tokenUriResolver` | `public` | `IJBTokenUriResolver` | Resolver for loan NFT token URIs |
 
 ## Gotchas
 
@@ -154,10 +222,10 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 14. **Fee revnet must have terminals.** Cash-out fees and loan protocol fees are paid to `FEE_REVNET_ID`. If that project has no terminal for the token, the fee silently fails (try-catch).
 15. **Buyback hook is immutable per deployer.** `REVDeployer.BUYBACK_HOOK` is set at construction time. All revnets deployed by the same deployer share the same buyback hook.
 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.
+17. **Loan fee model has three layers.** See Constants table for exact values: REV protocol fee, terminal fee, and prepaid source fee (borrower-chosen, buys interest-free window). After the prepaid window, source fee accrues linearly over the remaining 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`.
+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.launchProjectFor`) instead of bare `launchProjectFor`.
 
 ### NATIVE_TOKEN Accounting on Non-ETH Chains
 
@@ -181,6 +249,60 @@ JBAccountingContext({
 })
 ```
 
+## Reading Revnet State
+
+Quick-reference for common read operations. All functions are `view`/`pure` and permissionless.
+
+### Current Stage & Ruleset
+
+| What | Call | Returns |
+|------|------|---------|
+| Current ruleset (stage) | `IJBController(CONTROLLER).currentRulesetOf(revnetId)` | `(JBRuleset, JBRulesetMetadata)` -- the active stage's parameters |
+| All queued rulesets | `IJBController(CONTROLLER).allRulesetsOf(revnetId, startingId, size)` | `JBRulesetWithMetadata[]` -- paginated list of stages |
+| Specific stage by ID | `IJBController(CONTROLLER).getRulesetOf(revnetId, stageId)` | `(JBRuleset, JBRulesetMetadata)` for that stage |
+
+### Split Operator
+
+| What | Call | Returns |
+|------|------|---------|
+| Check if address is split operator | `REVDeployer.isSplitOperatorOf(revnetId, addr)` | `bool` |
+
+### Token Supply & Surplus
+
+| What | Call | Returns |
+|------|------|---------|
+| Total supply (incl. pending reserved) | `IJBController(CONTROLLER).totalTokenSupplyWithReservedTokensOf(revnetId)` | `uint256` |
+| Pending reserved tokens | `IJBController(CONTROLLER).pendingReservedTokenBalanceOf(revnetId)` | `uint256` |
+| Current surplus (single terminal) | `IJBTerminalStore(STORE).currentSurplusOf(terminal, revnetId, configs, decimals, currency)` | `uint256` |
+
+### Auto-Issuance
+
+| What | Call | Returns |
+|------|------|---------|
+| Remaining auto-issuance for beneficiary | `REVDeployer.amountToAutoIssue(revnetId, stageId, beneficiary)` | `uint256` (0 if already claimed) |
+
+### Loans
+
+| What | Call | Returns |
+|------|------|---------|
+| Borrowable amount for collateral | `REVLoans.borrowableAmountFrom(revnetId, collateralCount, decimals, currency)` | `uint256` |
+| Total borrowed (per source) | `REVLoans.totalBorrowedFrom(revnetId, terminal, token)` | `uint256` |
+| Total collateral locked | `REVLoans.totalCollateralOf(revnetId)` | `uint256` |
+| Loan details | `REVLoans.loanOf(loanId)` | `REVLoan` struct |
+| All loan sources | `REVLoans.loanSourcesOf(revnetId)` | `REVLoanSource[]` |
+| Loan count | `REVLoans.totalLoansBorrowedFor(revnetId)` | `uint256` |
+| Source fee for repayment | `REVLoans.determineSourceFeeAmount(loan, amount)` | `uint256` |
+| Revnet ID from loan ID | `REVLoans.revnetIdOfLoanWith(loanId)` | `uint256` (pure) |
+| Loan NFT owner | `REVLoans.ownerOf(loanId)` | `address` (ERC-721) |
+
+### Deployer Config
+
+| What | Call | Returns |
+|------|------|---------|
+| Config hash (cross-chain matching) | `REVDeployer.hashedEncodedConfigurationOf(revnetId)` | `bytes32` |
+| 721 hook address | `REVDeployer.tiered721HookOf(revnetId)` | `IJB721TiersHook` |
+| Cash-out delay timestamp | `REVDeployer.cashOutDelayOf(revnetId)` | `uint256` (0 = no delay) |
+
 ## Example Integration
 
 ```solidity
@@ -258,9 +380,9 @@ loans.borrowFrom({
 
 loans.repayLoan({
     loanId: loanId,
-    maxRepayAmount: type(uint256).max,     // Repay in full
-    collateralToReturn: loan.collateral,   // Return all collateral
-    beneficiary: msg.sender,               // Receive re-minted tokens
-    allowance: IAllowanceTransfer.PermitSingle({ ... }) // Optional permit2
+    maxRepayBorrowAmount: type(uint256).max,     // Repay in full
+    collateralCountToReturn: loan.collateral,    // Return all collateral
+    beneficiary: msg.sender,                     // Receive re-minted tokens
+    allowance: JBSingleAllowance({ ... })        // Optional permit2
 });
 ```

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;

package/USER_JOURNEYS.md

@@ -74,6 +74,12 @@ Or: `REVDeployer.deployFor(revnetId=0, configuration, terminalConfigurations, su
 5. Cash-out delay applied if first stage has already started
 6. Same remaining steps as new deployment (ERC-20, buyback pools, suckers, 721 hook)
 
+**Events:**
+- `DeployRevnet(revnetId, configuration, terminalConfigurations, suckerDeploymentConfiguration, rulesetConfigurations, encodedConfigurationHash, caller)`
+- `StoreAutoIssuanceAmount(revnetId, stageId, beneficiary, count, caller)` for each auto-issuance on this chain
+- `DeploySuckers(...)` if suckers are deployed
+- `SetCashOutDelay(revnetId, cashOutDelay, caller)` if applicable
+
 **Edge cases:**
 - This is a **one-way operation**. The project NFT is permanently locked in REVDeployer.
 - `launchRulesetsFor` reverts if rulesets already exist. `setControllerOf` reverts if a controller is already set.
@@ -102,6 +108,10 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
    - 721 hook processes tier purchases
    - Buyback hook processes swap (if applicable)
 
+**Preview**: Call `JBMultiTerminal.previewPayFor(revnetId, token, amount, beneficiary, metadata)` to simulate the full payment including REVDeployer's data hook effects (buyback routing, 721 tier splits, weight adjustment). Returns the expected token count and hook specifications. When the buyback hook is active, noop specs may carry routing diagnostics (TWAP tick, liquidity, pool ID) even when the protocol mint path wins.
+
+**Events:** No revnet-specific events. The payment is handled by `JBMultiTerminal` and `JBController` (see nana-core-v6). REVDeployer's `beforePayRecordedWith` is a `view` function and emits nothing.
+
 **Edge cases:**
 - If the buyback hook determines a DEX swap is better, weight = 0 and the buyback hook spec receives the full project amount. The buyback hook buys tokens on the DEX and mints them to the payer.
 - If `totalSplitAmount >= context.amount.value`, `projectAmount = 0`, weight = 0, and no tokens are minted by the terminal. All funds go to 721 tier splits.
@@ -133,12 +143,16 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
    - Pays fee to fee revnet's terminal via `feeTerminal.pay`
    - On failure: returns funds to the originating project via `addToBalanceOf`
 
+**Preview**: Call `JBMultiTerminal.previewCashOutFrom(holder, revnetId, cashOutCount, tokenToReclaim, beneficiary, metadata)` to simulate the full cash out including REVDeployer's data hook effects (fee splitting, tax rate). Returns the expected reclaim amount and hook specifications. For a simpler estimate without data hook effects, use `JBTerminalStore.currentTotalReclaimableSurplusOf(revnetId, cashOutCount, decimals, currency)`.
+
+**Events:** No revnet-specific events. Cash-out events are emitted by `JBMultiTerminal` and `JBController`. REVDeployer's `beforeCashOutRecordedWith` is a `view` function. The `afterCashOutRecordedWith` hook processes fees but does not emit events.
+
 **Edge cases:**
 - Suckers bypass both the cash-out fee AND the cash-out delay. The `_isSuckerOf` check is the only gate.
-- `cashOutTaxRate == 0` means no tax and no revnet fee (but the terminal's 2.5% protocol fee still applies).
+- `cashOutTaxRate == 0` means no tax and no revnet fee. The terminal's 2.5% protocol fee only applies up to the `feeFreeSurplusOf` amount (round-trip prevention), not the full reclaim.
 - Micro cash-outs (< 40 wei at 2.5%) round `feeCashOutCount` to 0, bypassing the fee. Gas cost far exceeds the bypassed fee.
 - The fee is paid to `FEE_REVNET_ID`, not `REV_ID`. These may be different projects.
-- Cash-out fees stack: the terminal takes its 2.5% protocol fee, THEN the revnet takes its 2.5% fee from the remaining amount.
+- Both the revnet fee and the terminal protocol fee apply. The revnet fee is computed first (at the data hook level, by splitting the cashout token count into fee and non-fee portions), then the terminal's 2.5% protocol fee is applied to all outbound fund amounts (both the beneficiary's reclaim and the hook-forwarded fee amount).
 
 ---
 
@@ -185,7 +199,7 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
      - Pays REV fee (1%) to `REV_ID` via `feeTerminal.pay` (try-catch; zeroed on failure)
      - Transfers remaining: `netAmountPaidOut - revFeeAmount - sourceFeeAmount` to beneficiary
    - `_addCollateralTo`: increments `totalCollateralOf`, burns collateral via `CONTROLLER.burnTokensOf`
-   - Pays source fee to revnet via `terminal.pay` (NOT try-catch -- reverts on failure)
+   - Pays source fee to revnet via `terminal.pay` (try-catch — on failure, returns fee amount to beneficiary)
 8. **Mint loan ERC-721** to `_msgSender()`
 
 **Events:** `Borrow(loanId, revnetId, loan, source, borrowAmount, collateralCount, sourceFeeAmount, beneficiary, caller)`
@@ -194,7 +208,7 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
 - Revnets always deploy an ERC-20 at creation, so collateral is always ERC-20 tokens (never credits).
 - The `minBorrowAmount` check is against the raw bonding curve output, BEFORE fees are deducted. The actual amount received is less.
 - `prepaidDuration` at minimum (25): `25 * 3650 days / 500 = 182.5 days`. At maximum (500): `500 * 3650 days / 500 = 3650 days`.
-- The REV fee payment failure is non-fatal (borrower gets the fee amount instead). The source fee payment failure IS fatal (entire transaction reverts).
+- Both the REV fee payment and the source fee payment failures are non-fatal. If either `feeTerminal.pay` or `source.terminal.pay` reverts, the fee amount is transferred to the beneficiary instead.
 - Loan NFT is minted to `_msgSender()`, not `beneficiary`. The caller owns the loan; the beneficiary receives the funds.
 
 ---
@@ -224,7 +238,7 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
 4. **Nothing-to-do check:** Reverts if `repayBorrowAmount == 0 && collateralCountToReturn == 0`
 5. **Source fee calculation:**
    - If within prepaid window (`timeSinceCreated <= prepaidDuration`): fee = 0
-   - If expired (`timeSinceCreated >= LOAN_LIQUIDATION_DURATION`): revert `REVLoans_LoanExpired`
+   - If expired (`timeSinceCreated > LOAN_LIQUIDATION_DURATION`): revert `REVLoans_LoanExpired`
    - Otherwise: linear fee based on time elapsed beyond prepaid window
    - `repayBorrowAmount += sourceFeeAmount` (fee added to repayment)
 6. **Accept funds:** `_acceptFundsFor` handles native token (uses `msg.value`) or ERC-20 (with optional permit2)
@@ -378,7 +392,7 @@ This is a standard Juicebox payment, but REVDeployer intervenes as the data hook
 2. Reverts with `REVDeployer_NothingToBurn` if balance is 0
 3. Burns all held tokens via `CONTROLLER.burnTokensOf`
 
-**Events:** `BurnHeldTokens(revnetId, balance, caller)`
+**Events:** `BurnHeldTokens(revnetId, count, caller)`
 
 ---
 

package/foundry.toml

@@ -14,6 +14,13 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[profile.ci.fuzz]
+runs = 256
+
+[profile.ci.invariant]
+runs = 64
+depth = 50
+
 [lint]
 lint_on_build = false
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rev-net/core-v6",
-    "version": "0.0.14",
+    "version": "0.0.16",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -10,7 +10,6 @@
         "node": ">=20.0.0"
     },
     "scripts": {
-        "postinstall": "find node_modules -name '*.sol' -type f | xargs grep -l 'pragma solidity 0.8.23;' 2>/dev/null | xargs sed -i '' 's/pragma solidity 0.8.23;/pragma solidity 0.8.26;/g' 2>/dev/null || true",
         "test": "forge test",
         "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
         "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
@@ -20,14 +19,14 @@
         "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'revnet-core-v6'"
     },
     "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.17",
-        "@bananapus/buyback-hook-v6": "^0.0.13",
-        "@bananapus/core-v6": "^0.0.17",
-        "@bananapus/ownable-v6": "^0.0.10",
-        "@bananapus/permission-ids-v6": "^0.0.10",
-        "@bananapus/router-terminal-v6": "^0.0.13",
-        "@bananapus/suckers-v6": "^0.0.11",
-        "@croptop/core-v6": "^0.0.18",
+        "@bananapus/721-hook-v6": "^0.0.20",
+        "@bananapus/buyback-hook-v6": "^0.0.19",
+        "@bananapus/core-v6": "^0.0.26",
+        "@bananapus/ownable-v6": "^0.0.13",
+        "@bananapus/permission-ids-v6": "^0.0.12",
+        "@bananapus/router-terminal-v6": "^0.0.19",
+        "@bananapus/suckers-v6": "^0.0.16",
+        "@croptop/core-v6": "^0.0.21",
         "@openzeppelin/contracts": "^5.6.1",
         "@uniswap/v4-core": "^1.0.2",
         "@uniswap/v4-periphery": "^1.0.3"

package/script/Deploy.s.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 // forge-lint: disable-next-line(unaliased-plain-import)
 import "@bananapus/721-hook-v6/script/helpers/Hook721DeploymentLib.sol";
@@ -342,20 +342,86 @@ contract DeployScript is Script, Sphinx {
     }
 
     function deploy() public sphinx {
-        // TODO figure out how to reference project ID if the contracts are already deployed.
+        // Check if singletons are already deployed before creating a new fee project.
+        // This prevents creating orphan projects on script restarts.
         // forge-lint: disable-next-line(mixed-case-variable)
-        uint256 FEE_PROJECT_ID = core.projects.createFor(safeAddress());
+        uint256 FEE_PROJECT_ID;
+
+        // Predict the REVLoans address for an arbitrary fee project ID to check if it exists.
+        // We can't predict without a fee project ID, so we first check the REVDeployer which also stores it.
+        // Try a two-step approach: compute addresses assuming singletons exist, then check.
+
+        // First, check if REVLoans is already deployed by trying with project ID = 0 (placeholder).
+        // We need to iterate: if either singleton exists, extract the fee project ID from it.
+        // Since both encode FEE_PROJECT_ID, we check if any code exists at the predicted address
+        // for sequential project IDs starting from 1.
+
+        // A simpler approach: predict the REVDeployer address for each possible fee project ID
+        // until we find one that's deployed, or give up and create a new one.
+        // In practice, the fee project is always one of the first few projects created.
+
+        // Check the next project ID that would be created — if singletons were deployed with a previous ID,
+        // that ID must be less than the current count.
+        uint256 _nextProjectId = core.projects.count() + 1;
+
+        // Try to find an existing deployment by checking all project IDs that have already been created.
+        // Whether previously deployed singletons were found.
+        bool _singletonsExist;
+        // The address of the previously deployed REVLoans, if found.
+        address _existingRevloansAddr;
+        // The address of the previously deployed REVDeployer, if found.
+        address _existingDeployerAddr;
+
+        for (uint256 _candidateId = 1; _candidateId < _nextProjectId; _candidateId++) {
+            // Predict REVLoans address for this candidate fee project ID.
+            (address _candidateRevloansAddr, bool _candidateRevloansDeployed) = _isDeployed({
+                salt: REVLOANS_SALT,
+                creationCode: type(REVLoans).creationCode,
+                arguments: abi.encode(
+                    core.controller, core.projects, _candidateId, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER
+                )
+            });
+
+            if (_candidateRevloansDeployed) {
+                // Verify the fee project ID matches by reading the immutable.
+                if (REVLoans(payable(_candidateRevloansAddr)).REV_ID() == _candidateId) {
+                    // Record the fee project ID from the existing deployment.
+                    FEE_PROJECT_ID = _candidateId;
+                    // Record the existing REVLoans address.
+                    _existingRevloansAddr = _candidateRevloansAddr;
+                    // Flag that singletons were found.
+                    _singletonsExist = true;
+
+                    // Also predict and verify the deployer.
+                    (_existingDeployerAddr,) = _isDeployed({
+                        salt: DEPLOYER_SALT,
+                        creationCode: type(REVDeployer).creationCode,
+                        arguments: abi.encode(
+                            core.controller,
+                            suckers.registry,
+                            _candidateId,
+                            hook.hook_deployer,
+                            croptop.publisher,
+                            IJBBuybackHookRegistry(address(buybackHook.registry)),
+                            _candidateRevloansAddr,
+                            TRUSTED_FORWARDER
+                        )
+                    });
+                    // Stop searching — we found the deployed singletons.
+                    break;
+                }
+            }
+        }
+
+        // Only create a new fee project if no singletons were found.
+        if (!_singletonsExist) {
+            // forge-lint: disable-next-line(mixed-case-variable)
+            FEE_PROJECT_ID = core.projects.createFor(safeAddress());
+        }
 
         // Deploy REVLoans first — it only depends on the controller.
-        (address _revloansAddr, bool _revloansIsDeployed) = _isDeployed({
-            salt: REVLOANS_SALT,
-            creationCode: type(REVLoans).creationCode,
-            arguments: abi.encode(
-                core.controller, core.projects, FEE_PROJECT_ID, LOANS_OWNER, PERMIT2, TRUSTED_FORWARDER
-            )
-        });
-        REVLoans revloans = _revloansIsDeployed
-            ? REVLoans(payable(_revloansAddr))
+        REVLoans revloans = _singletonsExist
+            ? REVLoans(payable(_existingRevloansAddr))
             : new REVLoans{salt: REVLOANS_SALT}({
                 controller: core.controller,
                 projects: core.projects,
@@ -410,6 +476,8 @@ contract DeployScript is Script, Sphinx {
         });
     }
 
+    /// @notice Check whether a contract has already been deployed at its deterministic address.
+    /// @dev Uses the Arachnid deterministic-deployment-proxy address to predict the CREATE2 address.
     function _isDeployed(
         bytes32 salt,
         bytes memory creationCode,
@@ -419,10 +487,6 @@ contract DeployScript is Script, Sphinx {
         view
         returns (address deployedTo, bool isDeployed)
     {
-        // Note: This uses the Arachnid deterministic-deployment-proxy address, which differs from
-        // the Sphinx deployer used at runtime. As a result, the predicted address won't match and
-        // _isDeployed will always return false when deploying via Sphinx. This is benign — it just
-        // means contracts are always freshly deployed rather than skipped.
         address _deployedTo = vm.computeCreate2Address({
             salt: salt,
             initCodeHash: keccak256(abi.encodePacked(creationCode, arguments)),

package/script/helpers/RevnetCoreDeploymentLib.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity ^0.8.26;
 
 import {stdJson} from "forge-std/Script.sol";
 import {Vm} from "forge-std/Vm.sol";