@bananapus/core-v6 0.0.65 → 0.0.66

package/README.md

@@ -21,7 +21,7 @@ This package provides:
 - token issuance, ruleset queueing, token setup, and splits through `JBController`
 - multi-token terminal accounting through `JBMultiTerminal` and `JBTerminalStore`
 - operator permissions through `JBPermissions`
-- on-chain price-feed routing through `JBPrices`
+- on-chain price-feed routing and fallback feeds through `JBPrices`
 
 Use this repo when you need the protocol's canonical accounting and execution logic. Do not copy that logic into downstream repos unless the repo is explicitly meant to wrap or extend core.
 
@@ -72,6 +72,7 @@ The shortest reading path is:
 - Data hooks and cash-out hooks can change economics and side effects. They are part of the protocol surface.
 - Permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
 - Preview and execution are intentionally close, but callers should still treat them as separate surfaces when hooks or routing can change behavior.
+- Fee-bearing cash-out, payout, and allowance calls can carry a referral project ID. This credits fee volume; it does not redirect the fee itself.
 
 ## Where State Lives
 
@@ -79,6 +80,7 @@ The shortest reading path is:
 - controller and terminal routing: `JBDirectory`
 - ruleset history and activation: `JBRulesets`
 - balances, surplus, fees, and reclaim accounting: `JBTerminalStore`
+- referral fee-volume accounting: `JBTerminalStore`
 - operator authority: `JBPermissions`
 
 When a flow is unclear, read the contract that owns the state before the contract that forwards into it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.65",
+  "version": "0.0.66",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/entrypoints.md

@@ -20,9 +20,9 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBTokens` | Dual-balance system: credits (internal) + ERC-20. Credits burned first on burn. |
 | `JBSplits` | Split configurations per project/ruleset/group. Packed storage for gas efficiency. |
 | `JBFundAccessLimits` | Payout limits and surplus allowances per project/ruleset/terminal/token. |
-| `JBPrices` | Price feed registry with project-specific and protocol-wide default feeds. Immutable once set. |
+| `JBPrices` | Append-only price feed registry with project-specific feeds, protocol defaults, inverse lookup, and backup feeds. |
 | `JBERC20` | Cloneable ERC-20 with Votes + Permit + ERC-1271. Controlled by `JBTokens` via `onlyTokens`. Deployed via `Clones.clone()`. |
-| `JBFeelessAddresses` | Allowlist for fee-exempt addresses. |
+| `JBFeelessAddresses` | Static and hook-driven fee-exemption registry. |
 | `JBChainlinkV3PriceFeed` | Chainlink AggregatorV3 price feed with staleness threshold. Rejects negative/zero prices, incomplete rounds (`updatedAt == 0`), and stale answers carried from previous rounds (`answeredInRound < roundId`). |
 | `JBChainlinkV3SequencerPriceFeed` | L2 sequencer-aware Chainlink feed (Optimism/Arbitrum) with grace period after restart. Treats any non-zero sequencer answer as down (`answer != 0`). |
 | `JBDeadline` | Approval hook: rejects rulesets queued within `DURATION` seconds of start. Ships as `JBDeadline3Hours`, `JBDeadline1Day`, `JBDeadline3Days`, `JBDeadline7Days`. |
@@ -61,9 +61,9 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | Function | What it does |
 |----------|--------------|
 | `pay(uint256 projectId, address token, uint256 amount, address beneficiary, uint256 minReturnedTokens, string memo, bytes metadata)` | Pays a project. Mints project tokens to beneficiary based on ruleset weight. Returns token count. |
-| `cashOutTokensOf(address holder, uint256 projectId, uint256 cashOutCount, address tokenToReclaim, uint256 minTokensReclaimed, address payable beneficiary, bytes metadata)` | Burns project tokens and reclaims surplus terminal tokens via bonding curve. |
-| `sendPayoutsOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut)` | Distributes payouts from the project's balance to its payout split group, up to the payout limit. |
-| `useAllowanceOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut, address payable beneficiary, address payable feeBeneficiary, string memo)` | Withdraws from the project's surplus allowance to a beneficiary. The `feeBeneficiary` receives tokens minted by the fee payment. |
+| `cashOutTokensOf(address holder, uint256 projectId, uint256 cashOutCount, address tokenToReclaim, uint256 minTokensReclaimed, address payable beneficiary, bytes metadata, uint256 referralProjectId)` | Burns project tokens and reclaims surplus terminal tokens via bonding curve. Optional referral credits protocol fee volume. |
+| `sendPayoutsOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut, uint256 referralProjectId)` | Distributes payouts from the project's balance to its payout split group, up to the payout limit. Optional referral credits protocol fee volume. |
+| `useAllowanceOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut, address payable beneficiary, address payable feeBeneficiary, string memo, uint256 referralProjectId)` | Withdraws from the project's surplus allowance to a beneficiary. The `feeBeneficiary` receives tokens minted by the fee payment. Optional referral credits protocol fee volume. |
 | `addToBalanceOf(uint256 projectId, address token, uint256 amount, bool shouldReturnHeldFees, string memo, bytes metadata)` | Adds funds to a project's balance without minting tokens. Can unlock held fees. |
 | `migrateBalanceOf(uint256 projectId, address token, IJBTerminal to)` | Migrates a project's token balance to another terminal. Requires `allowTerminalMigration`. |
 | `processHeldFeesOf(uint256 projectId, address token, uint256 count)` | Processes up to `count` held fees for a project, sending them to the fee beneficiary project. |
@@ -74,6 +74,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `previewPayFor(uint256 projectId, address token, uint256 amount, address beneficiary, bytes metadata)` | Simulates a full payment including the reserved/beneficiary token split. Returns `(ruleset, beneficiaryTokenCount, reservedTokenCount, hookSpecifications)`. Composes `STORE.previewPayFrom` + `controller.previewMintOf`. |
 | `previewCashOutFrom(address holder, uint256 projectId, uint256 cashOutCount, address tokenToReclaim, address payable beneficiary, bytes metadata)` | Simulates a full cash out including bonding curve and data hook effects. Cash-out data hooks may alter pricing inputs, but not the caller-supplied burn count. Returns `(ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications)`. Delegates to `STORE.previewCashOutFrom`. |
 | `heldFeesOf(uint256 projectId, address token, uint256 count)` | Returns up to `count` held fees for a project/token. |
+| `currentReferralProjectId()` | Returns the in-flight packed referral `(chainId << 48) | projectId`, or 0 outside a fee-bearing call. |
 
 ### JBTerminalStore
 
@@ -93,8 +94,11 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `currentTotalReclaimableSurplusOf(uint256 projectId, uint256 cashOutCount, uint256 decimals, uint256 currency)` | Convenience view: reclaimable surplus across all terminals and all tokens. |
 | `currentSurplusOf(uint256 projectId, IJBTerminal[] terminals, address[] tokens, uint256 decimals, uint256 currency)` | Returns the current surplus across specified terminals and tokens. Empty arrays default to all. |
 | `currentTotalSurplusOf(uint256 projectId, uint256 decimals, uint256 currency)` | Convenience view: total surplus across all terminals and all tokens. |
+| `feeVolumeByReferralOf(address terminal, uint256 referralChainId, uint256 referralProjectId)` | Returns cumulative protocol fee volume credited to a referrer through a terminal. |
 | `previewPayFrom(address terminal, address payer, JBTokenAmount amount, uint256 projectId, address beneficiary, bytes metadata)` | Simulates a payment without modifying state. Uses the explicit `terminal` parameter for balance/surplus lookups. Invokes data hooks if configured. Returns ruleset, token count, and hook specifications. |
 | `previewCashOutFrom(address terminal, address holder, uint256 projectId, uint256 cashOutCount, address tokenToReclaim, bool beneficiaryIsFeeless, bytes metadata)` | Simulates a cash out without modifying state. Uses the explicit `terminal` parameter for balance/surplus lookups. Invokes data hooks if configured, including any pricing-only adjustments they return. Returns ruleset, reclaim amount, tax rate, and hook specifications. |
+| `recordFeeReferralCreditOf(uint256 referralProjectId, JBTokenAmount amount)` | Credits normalized fee volume to a packed referral project for the calling terminal. No-ops for zero referral, zero amount, or missing price feed. |
+| `totalFeeVolumeOf(address terminal)` | Returns total referral-creditable fee volume recorded for a terminal. |
 
 ### JBRulesets
 
@@ -130,8 +134,11 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 
 | Function | What it does |
 |----------|--------------|
-| `pricePerUnitOf(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, uint256 decimals)` | Returns the price of 1 `unitCurrency` in `pricingCurrency`. Checks project-specific, inverse, then default feeds. |
-| `addPriceFeedFor(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed)` | Registers a price feed. Project ID 0 sets protocol-wide defaults (owner-only). Immutable once set. |
+| `pricePerUnitOf(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, uint256 decimals)` | Returns the price of 1 `unitCurrency` in `pricingCurrency`. Checks project direct, project inverse, default direct, then default inverse feeds; skips feeds that revert or return zero. |
+| `addPriceFeedFor(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed)` | Appends a feed for an exact pair. Project ID 0 sets protocol-wide defaults (owner-only); nonzero project IDs are controller-only. |
+| `priceFeedAt(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, uint256 index)` | Returns the feed at an exact pair's index. |
+| `priceFeedCountFor(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency)` | Returns how many feeds are configured for an exact pair. |
+| `priceFeedFor(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency)` | Returns the primary feed for an exact pair, or zero if none is configured. |
 
 ### JBTokens
 
@@ -141,6 +148,8 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `totalBalanceOf(address holder, uint256 projectId)` | Returns combined credit + ERC-20 balance. |
 | `creditBalanceOf(address holder, uint256 projectId)` | Returns the holder's credit balance. |
 | `tokenOf(uint256 projectId)` | Returns the ERC-20 token for a project (`IJBToken`). |
+| `projectIdOf(IJBToken token)` | Returns the project ID associated with an ERC-20 token. |
+| `totalCreditSupplyOf(uint256 projectId)` | Returns the internal credit supply for a project. |
 | `setTokenMetadataFor(uint256 projectId, string name, string symbol)` | Sets the name and symbol of a project's token. Controller-only. |
 
 ### JBSplits
@@ -157,6 +166,9 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 |----------|--------------|
 | `setFeelessAddress(address addr, bool flag)` | Adds or removes an address from the global (all-project) fee exemption list. Owner-only. (`JBFeelessAddresses`) |
 | `setFeelessAddressFor(uint256 projectId, address addr, bool flag)` | Adds or removes an address from a project's fee exemption list. `projectId = 0` = global wildcard. Owner-only. (`JBFeelessAddresses`) |
-| `isFeelessFor(address addr, uint256 projectId)` | Returns whether an address is feeless for a project (checks both wildcard and project-specific). (`JBFeelessAddresses`) |
+| `setFeelessHook(IJBFeelessHook hook)` | Sets or clears the optional hook consulted by `isFeelessFor`. Owner-only. (`JBFeelessAddresses`) |
+| `isFeelessFor(address addr, uint256 projectId, address caller)` | Returns whether an address is feeless for a project, checking static grants and the optional caller-aware hook. (`JBFeelessAddresses`) |
+| `creationFee()` / `creationFeeReceiver()` | Return the current project creation fee and receiver. (`JBProjects`) |
+| `setCreationFee(uint256 fee, address payable receiver)` | Sets the native-token project creation fee. Owner-only. (`JBProjects`) |
 | `setControllerAllowed(uint256 projectId)` | Returns whether a project's controller can currently be set. (`IJBDirectoryAccessControl`) |
 | `setTerminalsAllowed(uint256 projectId)` | Returns whether a project's terminals can currently be set. (`IJBDirectoryAccessControl`) |

package/references/types-errors-events.md

@@ -17,7 +17,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `JBCurrencyAmount` | `amount (uint224)`, `currency (uint32)` | Payout limits and surplus allowances |
 | `JBFundAccessLimitGroup` | `terminal (address)`, `token (address)`, `payoutLimits (JBCurrencyAmount[])`, `surplusAllowances (JBCurrencyAmount[])` | `JBRulesetConfig.fundAccessLimitGroups` |
 | `JBPermissionsData` | `operator (address)`, `projectId (uint64)`, `permissionIds (uint8[])` | `setPermissionsFor()` input |
-| `JBFee` | `amount (uint256)`, `beneficiary (address)`, `unlockTimestamp (uint48)` | Held fees in `JBMultiTerminal` |
+| `JBFee` | `amount (uint224)`, `referralChainId (uint32)`, `beneficiary (address)`, `unlockTimestamp (uint48)`, `referralProjectId (uint48)` | Held fees in `JBMultiTerminal`; referral fields preserve fee attribution until processing |
 | `JBSingleAllowance` | `sigDeadline (uint256)`, `amount (uint160)`, `expiration (uint48)`, `nonce (uint48)`, `signature (bytes)` | Permit2 allowance in terminal payments |
 | `JBRulesetWithMetadata` | `ruleset (JBRuleset)`, `metadata (JBRulesetMetadata)` | `allRulesetsOf()`, `currentRulesetOf()` return values |
 | `JBRulesetWeightCache` | `weight (uint112)`, `weightCutMultiple (uint168)` | Weight caching for long-running rulesets in `JBRulesets` |
@@ -69,7 +69,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 | `projectId = 0` | `JBPermissionsData` | Wildcard: permission applies to ALL projects. Cannot be combined with ROOT (1). |
 | `permissionId = 1` | `JBPermissions` | ROOT: grants all permissions for the scoped project. |
 | `rulesetId = 0` | `JBSplits.splitsOf()` | Fallback split group used when no splits are set for a specific ruleset. |
-| `projectId = 0` | `JBPrices.addPriceFeedFor()` | Sets a protocol-wide default price feed (owner-only). |
+| `projectId = 0` | `JBPrices.addPriceFeedFor()` | Appends a protocol-wide default price feed (owner-only). |
 
 ## Gotchas
 
@@ -92,8 +92,10 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - **Fee-free cashout exemption is scoped to fee-free intra-terminal payout amounts.** `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds leave first, preserving the fee-free counter. During cashout with `cashOutTaxRate=0`, the 2.5% fee applies only up to this surplus, then depletes. Once consumed, subsequent cashouts are fee-free again. Cleared on terminal migration. This prevents a round-trip fee bypass (intra-terminal payout → zero-tax cashout) while scoping fees precisely to the fee-free inflow.
 - `JBProjects` constructor optionally mints project #1 to `feeProjectOwner` -- if `address(0)`, no fee project is created
 - `JBMultiTerminal` derives `DIRECTORY` from the provided `store` in its constructor -- not passed directly
-- `JBPrices.pricePerUnitOf()` checks project-specific feed, then inverse, then falls back to `DEFAULT_PROJECT_ID = 0`
-- `useAllowanceOf()` takes 8 args including `address payable feeBeneficiary` -- do NOT omit it
+- `JBPrices.pricePerUnitOf()` checks project direct feeds, project inverse feeds, default direct feeds, then default inverse feeds. It skips feeds that revert or return zero.
+- `useAllowanceOf()` takes 9 args including `address payable feeBeneficiary` and `uint256 referralProjectId` -- do NOT omit them
+- `sendPayoutsOf()` and `cashOutTokensOf()` also take `uint256 referralProjectId`; pass `0` for no referral credit
+- `JBFeelessAddresses.isFeelessFor()` takes 3 args: `(addr, projectId, caller)`. The optional hook can use `caller` to scope dynamic grants.
 - Cash out tax rate of 0% = proportional (1:1) redemption; 100% = nothing reclaimable (all surplus locked). Do NOT confuse with a "cash out rate" where 100% means full redemption.
 - `cashOutTaxRate` in `JBRulesetMetadata` is `uint16` (max 10,000 basis points), NOT 9-decimal precision
 - `reservedPercent` in `JBRulesetMetadata` is `uint16` (max 10,000 basis points), NOT 9-decimal precision
@@ -103,7 +105,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - `JBController`, `JBMultiTerminal`, `JBProjects`, `JBPrices`, `JBPermissions` all support ERC-2771 meta-transactions
 - `JBRulesetMetadataResolver` bit layout: version (4 bits), reservedPercent (16), cashOutTaxRate (16), baseCurrency (32), 14 boolean flags (1 bit each), dataHook address (160), metadata (14)
 - `IJBDirectoryAccessControl` has `setControllerAllowed()` and `setTerminalsAllowed()` -- NOT `setControllerAllowedFor()`
-- Price feeds are immutable once set in `JBPrices` -- they cannot be replaced or removed
+- Price feeds are append-only in `JBPrices`. Existing feeds cannot be replaced or removed; later feeds are fallbacks after the primary feed.
 - `JBFundAccessLimits` requires payout limits and surplus allowances to be in strictly increasing currency order to prevent duplicates
 - **Empty `fundAccessLimitGroups` = zero payouts, NOT unlimited.** If a ruleset's `fundAccessLimitGroups` array is empty (or has no entry for the terminal/token), `payoutLimitsOf()` returns an empty array → cumulative limit is 0 → `sendPayoutsOf()` caps to 0 and returns 0. To allow unlimited payouts, explicitly set a payout limit with `amount: type(uint224).max`.
 - **`groupId` (uint256) vs `currency` (uint32) are different types for the same address.** `JBSplitGroup.groupId` is `uint256(uint160(tokenAddress))` while `JBAccountingContext.currency` is `uint32(uint160(tokenAddress))`. These truncate differently — only `NATIVE_TOKEN` (0x000000000000000000000000000000000000EEEe) matches by coincidence. Don't confuse them.
@@ -180,7 +182,7 @@ Errors an agent is most likely to encounter. All are custom errors (revert with
 | `JBTokens_InsufficientCredits` | `JBTokens` | `claimTokensFor` count exceeds credit balance. |
 | `JBTokens_TokensMustHave18Decimals` | `JBTokens` | Custom token does not use 18 decimals. |
 | `JBSplits_TotalPercentExceeds100` | `JBSplits` | Split percentages sum exceeds `SPLITS_TOTAL_PERCENT`. |
-| `JBPrices_PriceFeedAlreadyExists` | `JBPrices` | Feed already set for that currency pair (immutable). |
+| `JBPrices_PriceFeedAlreadyAdded` | `JBPrices` | The same feed address is already configured for that exact pair. Other backup feeds can still be appended. |
 | `JBPrices_PriceFeedNotFound` | `JBPrices` | No feed found for the requested currency pair. |
 | `JBRulesets_InvalidWeight` | `JBRulesets` | Weight exceeds `uint112.max`. |
 | `JBRulesets_InvalidWeightCutPercent` | `JBRulesets` | `weightCutPercent` exceeds `MAX_WEIGHT_CUT_PERCENT`. |
@@ -211,7 +213,10 @@ The most important events for indexing and off-chain monitoring. Indexed params
 | `HoldFee` | `IJBFeeTerminal` | `projectId*`, `token*`, `amount*`, `fee`, `beneficiary` |
 | `ProcessFee` | `IJBFeeTerminal` | `projectId*`, `token*`, `amount*`, `wasHeld`, `beneficiary` |
 | `ReturnHeldFees` | `IJBFeeTerminal` | `projectId*`, `token*`, `amount*`, `returnedFees`, `leftoverAmount` |
+| `FeeReverted` | `IJBFeeTerminal` | `projectId*`, `token*`, `feeProjectId*`, `amount`, `reason` |
+| `ReferralCredit` | `IJBTerminalStore` | `terminal*`, `referralChainId*`, `referralProjectId*`, `amount`, `newTotal` |
 | `Create` | `IJBProjects` | `projectId*`, `owner*` |
+| `SetTokenMetadata` | `IJBTokens` | `projectId*`, `name`, `symbol` |
 | `OperatorPermissionsSet` | `IJBPermissions` | (operator, account, projectId, permissionIds, packed, caller) |
 | `RulesetQueued` | `IJBRulesets` | (rulesetId, projectId, duration, weight, weightCutPercent, approvalHook, metadata, mustStartAtOrAfter, caller) |
 | `SetSplit` | `IJBSplits` | (projectId, rulesetId, groupId, split, caller) |
@@ -241,11 +246,12 @@ function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata conte
         uint256 cashOutTaxRate,                               // Overrides the ruleset's cash out tax rate
         uint256 effectiveCashOutCount,                        // Overrides the token count used for pricing only
         uint256 effectiveTotalSupply,                         // Overrides total supply used for bonding curve calc
+        uint256 effectiveSurplusValue,                        // Overrides surplus used for bonding curve calc
         JBCashOutHookSpecification[] memory hookSpecifications // Cash out hooks to call + amounts to forward
     );
 ```
 
-The data hook can override `cashOutTaxRate` (0 = proportional, 10000 = nothing reclaimable), `effectiveCashOutCount`, and `effectiveTotalSupply` to shift cash-out pricing, and return `hookSpecifications` to redirect reclaimed funds to cash out hooks. The terminal still burns the caller-supplied `cashOutCount`.
+The data hook can override `cashOutTaxRate` (0 = proportional, 10000 = nothing reclaimable), `effectiveCashOutCount`, `effectiveTotalSupply`, and `effectiveSurplusValue` to shift cash-out pricing, and return `hookSpecifications` to redirect reclaimed funds to cash out hooks. The terminal still burns the caller-supplied `cashOutCount` and caps the reclaim at locally available funds.
 
 ### `IJBRulesetDataHook.hasMintPermissionFor()`
 

package/script/Deploy.s.sol

@@ -25,11 +25,11 @@ contract Deploy is Script, Sphinx {
     /// @notice The universal PERMIT2 address.
     IPermit2 private constant _PERMIT2 = IPermit2(0x000000000022D473030F116dDEE9F6B43aC78BA3);
 
-    /// @notice The address that is allowed to forward calls to the terminal and controller on a users behalf.
+    /// @notice The address that is allowed to forward calls to the terminal and controller on behalf of users.
     string private constant _TRUSTED_FORWARDER_NAME = "Juicebox";
     address private trustedForwarder;
 
-    /// @notice The address that will manage the few privileged functions of the protocol.
+    /// @notice The address that will manage privileged protocol functions.
     address private manager;
 
     /// @notice The address that will own the fee-project.

package/script/DeployPeriphery.s.sol

@@ -69,11 +69,10 @@ contract DeployPeriphery is Script, Sphinx {
         IJBPriceFeed matchingPriceFeed;
         matchingPriceFeed = new JBMatchingPriceFeed();
 
-        // Same as the chainlink example grace period.
+        // Same grace period used in Chainlink sequencer-feed examples.
         uint256 l2GracePeriod = 3600 seconds;
 
-        // NOTE: Feeds come from this url `https://data.chain.link/feeds/ethereum/mainnet/eth-usd`.
-        // Sequencer feeds come from this url `https://docs.chain.link/data-feeds/l2-sequencer-feeds`.
+        // Feed addresses come from Chainlink price-feed and L2 sequencer-feed docs.
 
         // Perform the deploy for L1(s).
         if (block.chainid == 1) {
@@ -162,8 +161,7 @@ contract DeployPeriphery is Script, Sphinx {
             "Unexpected USD/native price feed"
         );
 
-        // WARN: We are using the same price feed as the native token for the USD price feed. Which is only valid on
-        // chains where Ether is the native asset. We *NEED* to update this when we deploy to a non-ether chain!
+        // This feed also prices USD/ETH, which is valid only on ETH-native chains.
         try core.prices
             .addPriceFeedFor({
                 projectId: 0, pricingCurrency: JBCurrencyIds.USD, unitCurrency: JBCurrencyIds.ETH, feed: feed
@@ -179,9 +177,7 @@ contract DeployPeriphery is Script, Sphinx {
             "Unexpected USD/ETH price feed"
         );
 
-        // If the native asset for this chain is ether, then the conversion from native asset to ether is 1:1.
-        // NOTE: We need to refactor this the moment we add a chain where its native token is *NOT* ether.
-        // As otherwise prices for the `NATIVE_TOKEN` will be incorrect!
+        // ETH/native is 1:1 only on ETH-native chains. Add a separate feed before deploying elsewhere.
         try core.prices
             .addPriceFeedFor({
                 projectId: 0,

package/src/JBController.sol

@@ -42,9 +42,8 @@ import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
 import {JBTerminalConfig} from "./structs/JBTerminalConfig.sol";
 
 /// @notice The orchestrator for every Juicebox project's lifecycle. Use the controller to launch a project, queue new
-/// rulesets (funding cycles), mint or burn tokens, deploy an ERC-20, distribute reserved tokens, and manage
-/// permissions. The controller coordinates between the terminal (money), rulesets (rules), tokens (issuance), and
-/// splits (distribution).
+/// rulesets, mint or burn tokens, deploy an ERC-20, distribute reserved tokens, and manage permissions. The controller
+/// coordinates between the terminal (money), rulesets (rules), tokens (issuance), and splits (distribution).
 /// @dev Supports ERC-2771 meta-transactions. Implements `IJBMigratable` for controller-to-controller migration.
 /// An omnichain deployer address is trusted to launch and queue rulesets on behalf of any project for cross-chain
 /// coordination.

package/src/JBFundAccessLimits.sol

@@ -7,9 +7,9 @@ import {IJBFundAccessLimits} from "./interfaces/IJBFundAccessLimits.sol";
 import {JBCurrencyAmount} from "./structs/JBCurrencyAmount.sol";
 import {JBFundAccessLimitGroup} from "./structs/JBFundAccessLimitGroup.sol";
 
-/// @notice Controls how much a project can withdraw from its terminals each funding cycle. Two types of limits:
-/// **Payout limits** cap how much can be distributed to splits and the project owner. **Surplus allowances** cap how
-/// much the project owner can pull from the surplus (funds above payout limits). Both reset each ruleset cycle.
+/// @notice Controls how much a project can withdraw from its terminals during each ruleset. Two types of limits:
+/// **Payout limits** cap distributions to splits and the project owner. **Surplus allowances** cap how much the
+/// project owner can pull from surplus (funds above payout limits).
 /// @dev Limits are denominated in a currency (which may differ from the held token) and resolved at withdrawal time
 /// via `JBPrices`. An empty `fundAccessLimitGroups` array means zero access (not unlimited) — use `type(uint224).max`
 /// for unlimited.
@@ -74,7 +74,7 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
 
     /// @notice Configure how much a project can withdraw from each of its terminals during a ruleset. Payout limits
     /// cap how much can be distributed to splits/owner; surplus allowances cap how much extra the owner can pull from
-    /// surplus. Both reset each funding cycle.
+    /// surplus. Payout usage resets by ruleset cycle number; surplus-allowance usage resets by ruleset ID.
     /// @dev Only a project's controller can set fund access limits (called during `queueRulesetsOf`).
     /// @dev Limits within each group must be sorted by currency in strictly increasing order to prevent duplicates.
     /// @param projectId The ID of the project to set fund access limits for.

package/src/JBMultiTerminal.sol

@@ -115,13 +115,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     //*********************************************************************//
 
     /// @notice The cumulative amount of fee-free intra-terminal payouts a project has received for a given token.
-    /// @dev Incremented each time a fee-free payout lands (same terminal, no fee charged). During cashout with
+    /// @dev Incremented each time a fee-free payout lands (same terminal, no fee charged). During cash out with
     /// `cashOutTaxRate == 0`, fees are applied only up to this amount, then decremented. This prevents a round-trip
-    /// fee bypass (intra-terminal payout → zero-tax cashout) while scoping the fee precisely to the fee-free inflow
-    /// — legitimate cashouts beyond this amount remain fee-free.
+    /// fee bypass (intra-terminal payout -> zero-tax cash out) while scoping the fee precisely to the fee-free inflow
+    /// — legitimate cash outs beyond this amount remain fee-free.
     /// @dev Lifecycle: incremented on fee-free intra-terminal payouts. After any outflow (payouts, useAllowanceOf,
-    /// non-zero-tax or feeless cashouts), capped at remaining balance — non-fee-free funds are considered to leave
-    /// first, preserving the fee-free counter. Consumed during zero-tax cashouts. Cleared on terminal migration.
+    /// non-zero-tax or feeless cash outs), capped at remaining balance — non-fee-free funds are considered to leave
+    /// first, preserving the fee-free counter. Consumed during zero-tax cash outs. Cleared on terminal migration.
     /// @dev Persists across rulesets — projects switching from zero-tax to non-zero-tax carry forward any
     /// unconsumed balance. There is no admin function to reset it.
     /// @custom:param projectId The ID of the project that received the payout.
@@ -155,8 +155,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// their own chain ID.
     /// @dev Set by the three entry points via the `_setReferralProjectId` save-restore wrapper. Read inside `_pay`
     /// to credit `feeVolumeByReferralOf` when the fee project's pay call is recorded locally.
-    /// @dev Public so pay/cashout/split hooks can introspect which referral originated the in-flight call (e.g. to
-    /// apply referral-specific logic). Reads `0` outside any fee-paying call.
+    /// @dev Public so pay, cash out, and split hooks can introspect which referral originated the in-flight call (e.g.
+    /// to apply referral-specific logic). Reads `0` outside any fee-paying call.
     uint256 public transient override currentReferralProjectId;
 
     //*********************************************************************//
@@ -291,8 +291,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// call to succeed, as a fixed point number with the same number of decimals as the terminal token's accounting
     /// context. If fewer terminal tokens would be reclaimed, the cash out is reverted.
     /// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
-    /// data hook and cash out hook if applicable.
-    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
+    /// data hook and cash out hooks if applicable.
+    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hooks if
     /// applicable.
     /// @param referralProjectId Optional referrer reference to credit with the protocol fee volume taken by this
     /// call, encoded as `(referralChainId << 48) | referralProjectId` (chain ID in the upper 32 bits, project ID
@@ -1338,13 +1338,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         }
 
-        // Cap fee-free surplus at remaining balance.
-        // Why: this single call replaces per-branch calls so that EVERY cashout path (non-zero tax,
-        // zero tax, and feeless beneficiary) gets the cap. Without it, the zero-tax path would use
-        // a stale _feeFreeSurplusOf that may exceed STORE.balanceOf (e.g. if pay hooks reduced the
-        // balance during a prior inbound payout), overcharging fees on round-trip prevention.
-        // Placed after hook fulfillment so any further balance reductions from cashout hooks are
-        // also accounted for.
+        // Cap fee-free surplus after every cash-out path so stale `_feeFreeSurplusOf` cannot survive after
+        // associated surplus leaves. Do this after hook fulfillment so hook-driven balance reductions are included.
         _capFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
 
         // Take the fee from all outbound reclaimings.

package/src/JBTerminalStore.sol

@@ -289,8 +289,8 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Passed through to data
     /// hooks so they can skip their own fees when value stays in the protocol (e.g. project-to-project routing).
     /// @param metadata Bytes to send to the data hook, if the project's current ruleset specifies one.
-    /// @return ruleset The ruleset during the cash out was made during, as a `JBRuleset` struct. This ruleset will
-    /// have a cash out tax rate provided by the cash out hook if applicable.
+    /// @return ruleset The ruleset during the cash out was made during, as a `JBRuleset` struct. Its cash out tax
+    /// rate may be overridden by the data hook.
     /// @return reclaimAmount The amount of tokens reclaimed from the terminal, as a fixed point number with 18
     /// decimals.
     /// @return cashOutTaxRate The cash out tax rate influencing the reclaim amount.
@@ -574,6 +574,11 @@ contract JBTerminalStore is IJBTerminalStore {
                 })
             });
 
+        // If cross-currency conversion rounded to zero, return without consuming any surplus allowance.
+        if (usedAmount == 0) {
+            return (ruleset, 0);
+        }
+
         // Set the token being used as the only one to look for surplus within.
         JBAccountingContext[] memory accountingContexts = new JBAccountingContext[](1);
         accountingContexts[0] = accountingContext;
@@ -1388,7 +1393,7 @@ contract JBTerminalStore is IJBTerminalStore {
             {
                 // Saturating subtraction: if a new ruleset activates with a lower payout limit than
                 // what was already used under the previous limit, `used` can exceed `amount`. Clamping
-                // to zero prevents an underflow revert that would DOS cashouts and surplus views.
+                // to zero prevents an underflow revert that would DoS cash outs and surplus views.
                 uint256 used = usedPayoutLimitOf[
                     terminal
                 ][projectId][accountingContext.token][ruleset.cycleNumber][payoutLimit.currency];

package/src/interfaces/IJBCashOutTerminal.sol

@@ -85,7 +85,7 @@ interface IJBCashOutTerminal is IJBTerminal {
     /// @param beneficiary The address to send the reclaimed terminal tokens to.
     /// @param metadata Extra data to send to the data hook and cash out hooks.
     /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
-    /// to credit the project being cashed out.
+    /// for no referral credit.
     /// @return reclaimAmount The number of terminal tokens reclaimed from the project's surplus.
     function cashOutTokensOf(
         address holder,

package/src/interfaces/IJBMultiTerminal.sol

@@ -38,9 +38,9 @@ interface IJBMultiTerminal is IJBTerminal, IJBFeeTerminal, IJBCashOutTerminal, I
     /// resolved to the current execution chain via `block.chainid` at the entry point, so storage and indexers
     /// always see a fully-resolved `(chainId, projectId)` pair.
     /// @dev Backed by transient storage. Set by `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf` (save-
-    /// restore wrapper) so hooks invoked during that call (pay hooks, cashout hooks, split hooks) can introspect
+    /// restore wrapper) so hooks invoked during that call (pay hooks, cash out hooks, split hooks) can introspect
     /// which referrer originated the activity. Reads `0` outside any fee-paying call.
     /// @dev Per-referrer cumulative fee payment amounts credited via this terminal are stored in
-    /// `JBTerminalStore.feeVolumeByReferralOf(address terminal, uint256 referralProjectId)`.
+    /// `JBTerminalStore.feeVolumeByReferralOf(address terminal, uint256 referralChainId, uint256 referralProjectId)`.
     function currentReferralProjectId() external view returns (uint256);
 }

package/src/interfaces/IJBPayoutTerminal.sol

@@ -103,7 +103,7 @@ interface IJBPayoutTerminal is IJBTerminal {
     /// @param currency The currency the amount is denominated in.
     /// @param minTokensPaidOut The minimum number of terminal tokens expected to be paid out.
     /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
-    /// to credit the project sending payouts.
+    /// for no referral credit.
     /// @return amountPaidOut The total amount paid out.
     function sendPayoutsOf(
         uint256 projectId,
@@ -126,7 +126,7 @@ interface IJBPayoutTerminal is IJBTerminal {
     /// @param feeBeneficiary The address that will receive any project tokens minted from fees.
     /// @param memo A memo to pass along to the emitted event.
     /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
-    /// to credit the project whose surplus allowance is being used.
+    /// for no referral credit.
     /// @return netAmountPaidOut The net amount paid out to the beneficiary after fees.
     function useAllowanceOf(
         uint256 projectId,

package/src/interfaces/IJBTerminalStore.sol

@@ -17,9 +17,8 @@ import {JBTokenAmount} from "../structs/JBTokenAmount.sol";
 interface IJBTerminalStore {
     /// @notice Emitted when a referrer is credited with a fee payment amount.
     /// @dev `referralChainId` and `referralProjectId` are emitted as separate indexed topics so off-chain consumers
-    /// can filter directly on either dimension. The `feeVolumeByReferralOf` storage key is the packed
-    /// `(referralChainId << 48) | referralProjectId` form — indexers re-pack the two fields when looking up the
-    /// cumulative balance for a referrer.
+    /// can filter directly on either dimension. The public `feeVolumeByReferralOf` getter exposes the same unpacked
+    /// `(terminal, referralChainId, referralProjectId)` tuple.
     /// @param terminal The terminal that originated the fee-paying call (`msg.sender` on `recordFeeReferralCreditOf`).
     /// @param referralChainId The EIP-155 chain ID of the referrer's home chain.
     /// @param referralProjectId The referrer's bare project ID on `referralChainId` (no chain bits).

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -90,7 +90,7 @@ library JBRulesetMetadataResolver {
         return uint16(ruleset.metadata >> 242);
     }
 
-    /// @notice Pack the funding cycle metadata.
+    /// @notice Pack ruleset metadata.
     /// @param rulesetMetadata The ruleset metadata to validate and pack.
     /// @return packed The packed uint256 of all metadata params. The first 4 bits (bits 0-3) specify the version;
     /// supported values are 0-15. A future protocol version that needs more than 16 distinct metadata layouts must
@@ -131,18 +131,18 @@ library JBRulesetMetadataResolver {
         if (rulesetMetadata.holdFees) packed |= 1 << 78;
         // scopeCashOutsToLocalBalances in bit 79.
         if (rulesetMetadata.scopeCashOutsToLocalBalances) packed |= 1 << 79;
-        // use pay data source in bit 80.
+        // use pay data hook in bit 80.
         if (rulesetMetadata.useDataHookForPay) packed |= 1 << 80;
-        // use cash out data source in bit 81.
+        // use cash out data hook in bit 81.
         if (rulesetMetadata.useDataHookForCashOut) packed |= 1 << 81;
-        // data source address in bits 82-241.
+        // data hook address in bits 82-241.
         packed |= uint256(uint160(address(rulesetMetadata.dataHook))) << 82;
         // metadata in bits 242-255 (14 bits).
         packed |= (uint256(rulesetMetadata.metadata) & 0x3FFF) << 242;
     }
 
-    /// @notice Expand the funding cycle metadata.
-    /// @param ruleset The funding cycle having its metadata expanded.
+    /// @notice Expand ruleset metadata.
+    /// @param ruleset The ruleset whose metadata is expanded.
     /// @return rulesetMetadata The ruleset's metadata object.
     function expandMetadata(JBRuleset memory ruleset) internal pure returns (JBRulesetMetadata memory) {
         return JBRulesetMetadata({

package/src/structs/JBFee.sol

@@ -11,9 +11,9 @@ pragma solidity ^0.8.0;
 /// @custom:member beneficiary The address that will receive the tokens that are minted as a result of the fee payment.
 /// @custom:member unlockTimestamp The timestamp at which the fee is unlocked and can be processed.
 /// @custom:member referralProjectId The referrer's project ID on `referralChainId`. Captured from the lower bits of
-/// `currentReferralProjectId` at fee-take time so held-fee attribution survives the 28-day hold window. The on-chain
-/// transient slot, function argument, and `feeVolumeByReferralOf` mapping key all use the packed `uint256` form
-/// `(referralChainId << 48) | referralProjectId`; this struct stores the two halves separately for cheap storage.
+/// `currentReferralProjectId` at fee-take time so held-fee attribution survives the 28-day hold window. The transient
+/// slot and terminal entry-point arguments use the packed `(referralChainId << 48) | referralProjectId` form; this
+/// struct stores the two halves separately for cheap storage.
 struct JBFee {
     uint224 amount;
     uint32 referralChainId;

package/src/structs/JBFundAccessLimitGroup.sol

@@ -3,17 +3,17 @@ pragma solidity ^0.8.0;
 
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
-/// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @notice Defines how much a project can withdraw from a specific terminal and token during a ruleset.
 /// @dev A ruleset configuration should include at most one group for each `(terminal, token)` pair.
 /// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
-/// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
-/// from the surplus (balance above payout limits).
-/// @dev Multiple limits in different currencies are additive — each can be used independently within one cycle.
+/// its splits per ruleset cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD
+/// worth of ETH from the surplus (balance above payout limits) during the ruleset.
+/// @dev Multiple limits in different currencies are additive within their respective reset windows.
 /// @dev Amounts use the same decimal precision as the terminal token (e.g. 18 for ETH, 6 for USDC).
 /// @custom:member terminal The terminal address these limits apply to.
 /// @custom:member token The token address within that terminal these limits apply to.
-/// @custom:member payoutLimits Maximum amounts distributable to splits per cycle, each in a specific currency.
-/// @custom:member surplusAllowances Maximum amounts withdrawable from surplus per cycle, each in a specific currency.
+/// @custom:member payoutLimits Maximum amounts distributable to splits per ruleset cycle, each in a specific currency.
+/// @custom:member surplusAllowances Maximum amounts withdrawable from surplus per ruleset, each in a specific currency.
 struct JBFundAccessLimitGroup {
     address terminal;
     address token;