@bananapus/core-v6 0.0.38 → 0.0.39

package/src/JBMultiTerminal.sol

@@ -45,8 +45,13 @@ import {JBSplit} from "./structs/JBSplit.sol";
 import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
 import {JBTokenAmount} from "./structs/JBTokenAmount.sol";
 
-/// @notice `JBMultiTerminal` manages native/ERC-20 payments, cash outs, and surplus allowance usage for any number of
-/// projects. Terminals are the entry point for operations involving inflows and outflows of funds.
+/// @notice The main entry point for all money movement in Juicebox. Handles payments (ETH or ERC-20), cash outs
+/// (burning tokens to reclaim funds), payouts (distributing funds to splits), and surplus allowance withdrawals.
+/// Charges a 2.5% protocol fee on outflows (held for 28 days before processing). Supports Permit2 for gasless
+/// ERC-20 approvals.
+/// @dev Each project can have multiple terminals for different tokens. The terminal delegates accounting to
+/// `JBTerminalStore` and splits distribution to `JBSplits`. Fees are sent to project #1 (the fee beneficiary).
+/// All external hook calls (pay hooks, cash-out hooks, split hooks) are wrapped in try-catch to prevent griefing.
 contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // A library that parses the packed ruleset metadata into a friendlier format.
     using JBRulesetMetadataResolver for JBRuleset;
@@ -185,10 +190,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Adds accounting contexts for a project to this terminal so the project can begin accepting the tokens in
-    /// those contexts.
-    /// @dev Only a project's owner, an operator with the `ADD_ACCOUNTING_CONTEXTS` permission from that owner, or a
-    /// project's controller can add accounting contexts for the project.
+    /// @notice Registers new tokens that this terminal can accept for a project. Once a token's accounting context is
+    /// added, the project can receive payments in that token.
+    /// @dev Only the project's owner, an operator with `ADD_ACCOUNTING_CONTEXTS` permission, or the project's
+    /// controller can call this.
     /// @param projectId The ID of the project having to add accounting contexts for.
     /// @param accountingContexts The accounting contexts to add.
     function addAccountingContextsFor(
@@ -219,8 +224,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Adds funds to a project's balance without minting tokens.
-    /// @dev Adding to balance can unlock held fees if `shouldUnlockHeldFees` is true.
+    /// @notice Adds funds to a project's balance without minting tokens. Useful for topping up a project or returning
+    /// funds. Can also unlock previously held fees by returning them to the project's balance.
+    /// @dev If `shouldReturnHeldFees` is true, the added amount offsets held fees proportionally.
     /// @param projectId The ID of the project to add funds to the balance of.
     /// @param amount The amount of tokens to add to the balance, as a fixed point number with the same number of
     /// decimals as this terminal. If this is a native token terminal, this is ignored and `msg.value` is used instead.
@@ -251,10 +257,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Holders can cash out a project's tokens to reclaim some of that project's surplus tokens, or to trigger
-    /// rules determined by the current ruleset's data hook and cash out hook.
-    /// @dev Only a token's holder or an operator with the `CASH_OUT_TOKENS` permission from that holder can cash out
-    /// those tokens.
+    /// @notice Burns project tokens to reclaim a share of the project's surplus (determined by the bonding curve) or
+    /// to trigger custom logic through the ruleset's data hook and cash out hook.
+    /// @dev Only the token holder or an operator with `CASH_OUT_TOKENS` permission from that holder can call this.
     /// @param holder The account whose tokens are being cashed out.
     /// @param projectId The ID of the project the project tokens belong to.
     /// @param cashOutCount The number of project tokens to cash out and burn, as a fixed point number with 18
@@ -563,7 +568,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
+    /// @notice Pay a project with tokens. The project's current ruleset determines how many project tokens the
+    /// beneficiary receives in return.
     /// @param projectId The ID of the project being paid.
     /// @param amount The amount of terminal tokens being received, as a fixed point number with the same number of
     /// decimals as this terminal. If this terminal's token is native, this is ignored and `msg.value` is used in its
@@ -622,19 +628,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _checkMin({value: beneficiaryTokenCount, min: minReturnedTokens});
     }
 
-    /// @notice Process any fees that are being held for the project.
-    /// @dev Reentrancy safety: the loop re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the
-    /// index before the external `_processFee` call, so a reentrant call cannot double-process the same fee entry.
-    /// @dev Held fees after migration: held fees remain in this terminal after `migrateBalanceOf` because their backing
-    /// tokens are not part of `balanceOf` — they were already deducted from the recorded balance during the payout
-    /// that
-    /// created them. The actual fee-backing tokens remain in this terminal's token holdings. If `_processFee` reverts
-    /// (e.g. the fee terminal rejects the payment), the catch block calls `_recordAddedBalanceFor` to credit the fee
-    /// amount back to the project. This credit is backed by the tokens that failed to transfer out. No phantom balance
-    /// is created because the tokens never left.
-    /// @dev The index-increment-before-`_processFee` pattern is intentional: locked (not-yet-unlocked) fees are skipped
-    /// via the `unlockTimestamp` check, and advancing the index before the external call prevents reentrancy from
-    /// reprocessing the same fee entry.
+    /// @notice Processes held fees for a project, sending them to the protocol's fee project. Fees are held for 28 days
+    /// after a payout — processing them finalizes the fee payment.
+    /// @dev Only processes fees whose `unlockTimestamp` has passed. Stops early if it encounters a still-locked fee.
+    /// @dev Reentrancy-safe: re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the index before
+    /// the external `_processFee` call, preventing double-processing.
+    /// @dev If `_processFee` reverts (fee terminal rejects), the fee amount is returned to the project's balance
+    /// (forgiven, not retried). A `FeeReverted` event is emitted for off-chain observability.
     /// @param projectId The ID of the project to process held fees for.
     /// @param token The token to process held fees for.
     /// @param count The number of fees to process.
@@ -657,6 +657,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // Can't process fees that aren't yet unlocked. Fees unlock sequentially in the array, so nothing left to do
             // if the current fee isn't yet unlocked.
+            // forge-lint: disable-next-line(block-timestamp)
             if (heldFee.unlockTimestamp > block.timestamp) break;
 
             // Delete the entry and advance the index *before* the external call. This is intentional:
@@ -694,15 +695,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Sends payouts to a project's current payout split group, according to its ruleset, up to its current
-    /// payout limit.
-    /// @dev If the percentages of the splits in the project's payout split group do not add up to 100%, the remainder
-    /// is sent to the project's owner.
-    /// @dev Anyone can send payouts on a project's behalf. Projects can include a wildcard split (a split with no
-    /// `hook`, `projectId`, or `beneficiary`) to send funds to the `_msgSender()` which calls this function. This can
-    /// be used to incentivize calling this function.
-    /// @dev payouts sent to addresses which aren't feeless incur the protocol fee.
-    /// @dev Payouts a projects don't incur fees if its terminal is feeless.
+    /// @notice Distributes funds from a project's balance to its payout split recipients, up to the current ruleset's
+    /// payout limit. Anyone can call this on behalf of any project.
+    /// @dev If splits don't add up to 100%, the remainder goes to the project owner. A wildcard split (no hook,
+    /// projectId, or beneficiary) sends its share to `msg.sender` — useful for incentivizing the call.
+    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee. Projects whose terminal is feeless are
+    /// exempt.
     /// @param projectId The ID of the project having its payouts sent.
     /// @param token The token being sent.
     /// @param amount The total number of terminal tokens to send, as a fixed point number with same number of decimals
@@ -730,10 +728,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _checkMin({value: amountPaidOut, min: minTokensPaidOut});
     }
 
-    /// @notice Allows a project to pay out funds from its surplus up to the current surplus allowance.
-    /// @dev Only a project's owner or an operator with the `USE_ALLOWANCE` permission from that owner can use the
-    /// surplus allowance.
-    /// @dev Incurs the protocol fee unless the caller is a feeless address.
+    /// @notice Withdraws funds from a project's surplus (beyond what's needed for payouts) up to the current ruleset's
+    /// surplus allowance. Sent directly to a beneficiary address rather than through splits.
+    /// @dev Only the project's owner or an operator with `USE_ALLOWANCE` permission can call this.
+    /// @dev Incurs the 2.5% protocol fee unless the caller is a feeless address.
     /// @param projectId The ID of the project to use the surplus allowance of.
     /// @param token The token being paid out from the surplus.
     /// @param amount The amount of terminal tokens to use from the project's current surplus allowance, as a fixed
@@ -787,8 +785,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice A project's accounting context for a token.
-    /// @dev See the `JBAccountingContext` struct for more information.
+    /// @notice Returns the accounting context (decimals, currency) for a specific token that a project accepts.
     /// @param projectId The ID of the project to get token accounting context of.
     /// @param token The token to check the accounting context of.
     /// @return The token's accounting context for the token.
@@ -804,15 +801,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         return STORE.accountingContextOf({terminal: address(this), projectId: projectId, token: token});
     }
 
-    /// @notice The tokens accepted by a project.
+    /// @notice Returns accounting contexts for all tokens a project currently accepts through this terminal.
     /// @param projectId The ID of the project to get the accepted tokens of.
     /// @return tokenContexts The accounting contexts of the accepted tokens.
     function accountingContextsOf(uint256 projectId) external view override returns (JBAccountingContext[] memory) {
         return STORE.accountingContextsOf({terminal: address(this), projectId: projectId});
     }
 
-    /// @notice Gets the current surplus amount in this terminal for a project, in terms of a given currency.
-    /// @dev If `tokens` is empty, includes all tokens the project accepts (as returned by `accountingContextsOf(...)`).
+    /// @notice Returns the project's current surplus in this terminal, converted to a specified currency. The surplus
+    /// is the balance minus what's needed for payout limits.
+    /// @dev If `tokens` is empty, includes all tokens the project accepts.
     /// @param projectId The ID of the project to get the current surplus of.
     /// @param tokens The tokens to include in the surplus calculation. If empty, all tokens are included.
     /// @param decimals The number of decimals to include in the fixed point returned value.
@@ -837,9 +835,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Fees that are being held for a project.
-    /// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
-    /// @dev Held fees can be processed at any time by this terminal's owner.
+    /// @notice Returns the fees currently being held for a project. Fees are held for 28 days after a payout before
+    /// they can be processed (sent to the fee project).
+    /// @dev Held fees can be returned to the project by calling `addToBalanceOf` with `shouldReturnHeldFees = true`
+    /// before the 28-day lock expires.
     /// @param projectId The ID of the project that is holding fees.
     /// @param token The token that the fees are held in.
     /// @param count The maximum number of held fees to return.
@@ -878,7 +877,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Simulates cashing out project tokens from this terminal without modifying state.
+    /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
+    /// reclaim.
     /// @param holder The address whose tokens are being cashed out.
     /// @param projectId The ID of the project whose tokens are being cashed out.
     /// @param cashOutCount The number of project tokens to cash out.
@@ -919,7 +919,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
     }
 
-    /// @notice Simulates paying a project through this terminal without modifying state.
+    /// @notice Simulates a payment without modifying state — use this to preview how many project tokens a payer
+    /// would
+    /// receive.
     /// @param projectId The ID of the project being paid.
     /// @param token The token being paid in.
     /// @param amount The amount of tokens being paid.
@@ -1586,7 +1588,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
+    /// @notice Internal implementation of payment logic. Records the payment in the store, mints tokens via the
+    /// controller, and fulfills any pay hook specifications from the data hook.
     /// @param projectId The ID of the project being paid.
     /// @param token The address of the token which the project is being paid with.
     /// @param amount The amount of terminal tokens being received, as a fixed point number with the same number of

package/src/JBPermissions.sol

@@ -7,8 +7,11 @@ import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol"
 import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
 import {JBPermissionsData} from "./structs/JBPermissionsData.sol";
 
-/// @notice Stores permissions for all addresses and operators. Addresses can give permissions to any other address
-/// (i.e. an *operator*) to execute specific operations on their behalf.
+/// @notice The permission system for Juicebox. Any address can authorize another address (an "operator") to perform
+/// specific actions on its behalf — like queuing rulesets, distributing payouts, or managing terminals.
+/// @dev Permissions are stored as a packed `uint256` bitmap: each of the 256 bits represents one permission's
+/// on/off state. Project ID 0 is a wildcard that grants an operator access across all projects — use with caution.
+/// @dev The ROOT permission (ID 1) implicitly grants every other permission for the scoped project.
 contract JBPermissions is ERC2771Context, IJBPermissions {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -23,19 +26,19 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ------------------------- public constants ------------------------ //
     //*********************************************************************//
 
-    /// @notice The project ID considered a wildcard, meaning it will grant permissions to all projects.
+    /// @notice The project ID that acts as a wildcard — granting the operator permissions across all projects owned
+    /// by
+    /// the account. Setting permissions for project ID 0 is powerful and should be done carefully.
     uint256 public constant override WILDCARD_PROJECT_ID = 0;
 
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The permissions that an operator has been given by an account for a specific project.
-    /// @dev An account can give an operator permissions that only pertain to a specific project ID.
-    /// @dev There is no project with a ID of 0 – this ID is a wildcard which gives an operator permissions pertaining
-    /// to *all* project IDs on an account's behalf. Use this with caution.
-    /// @dev Permissions are stored in a packed `uint256`. Each of the 256 bits represents the on/off state of a
-    /// permission. Applications can specify the significance of each permission ID.
+    /// @notice The packed permission bitmap that an account has granted to an operator for a specific project.
+    /// @dev Each bit in the returned `uint256` corresponds to a permission ID (0–255). A `1` bit means that
+    /// permission
+    /// is granted. See `JBPermissionIds` for the meaning of each ID.
     /// @custom:param operator The address of the operator.
     /// @custom:param account The address of the account being operated on behalf of.
     /// @custom:param projectId The project ID the permissions are scoped to. An ID of 0 grants permissions across all
@@ -55,14 +58,12 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets permissions for an operator.
-    /// @dev Only the `account` itself (i.e. `msg.sender == account`) can grant or revoke its operators' permissions
-    /// without restriction — including ROOT on the wildcard project ID (`projectId = 0`).
-    /// @dev A third-party caller who holds ROOT for a specific project may set *non-ROOT* permissions for that project
-    /// on someone else's behalf, but **cannot**: (a) grant ROOT to others, or (b) set any permissions on the wildcard
-    /// project ID. This prevents ROOT operators from escalating their own privileges.
-    /// @param account The account setting its operators' permissions.
-    /// @param permissionsData The data which specifies the permissions the operator is being given.
+    /// @notice Grant or revoke permissions for an operator on a specific project.
+    /// @dev Only the account itself can set permissions without restriction. A ROOT operator on a specific project can
+    /// set non-ROOT permissions for that same project on the account's behalf, but cannot grant ROOT or set wildcard
+    /// (project ID 0) permissions — preventing privilege escalation.
+    /// @param account The account whose operator permissions are being configured.
+    /// @param permissionsData The operator address, project scope, and permission IDs to set.
     function setPermissionsFor(address account, JBPermissionsData calldata permissionsData) external override {
         // Pack the permission IDs into a uint256.
         uint256 packed = _packedPermissions(permissionsData.permissionIds);
@@ -113,16 +114,14 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Check if an operator has all of the specified permissions for a specific address and project ID.
-    /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
-    /// @param projectId The project ID that the operator has permission to operate under. 0 represents all projects.
-    /// @param permissionIds An array of permission IDs to check for.
-    /// @param includeRoot A flag indicating if the return value should default to true if the operator has the ROOT
-    /// permission.
-    /// @param includeWildcardProjectId A flag indicating if the return value should return true if the operator has the
-    /// specified permission on the wildcard project ID.
-    /// @return A flag indicating whether the operator has all specified permissions.
+    /// @notice Check whether an operator has *all* of the specified permissions for an account and project.
+    /// @param operator The address to check permissions for.
+    /// @param account The account that granted (or didn't grant) the permissions.
+    /// @param projectId The project ID to check within. Pass 0 to check the wildcard scope directly.
+    /// @param permissionIds The permission IDs that must all be present.
+    /// @param includeRoot If `true`, returns `true` immediately when the operator has the ROOT permission.
+    /// @param includeWildcardProjectId If `true`, also checks wildcard (project 0) permissions as a fallback.
+    /// @return Whether the operator holds every requested permission.
     function hasPermissions(
         address operator,
         address account,
@@ -187,16 +186,14 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Check if an operator has a specific permission for a specific address and project ID.
-    /// @param operator The operator to check.
-    /// @param account The account being operated on behalf of.
-    /// @param projectId The project ID that the operator has permission to operate under. 0 represents all projects.
-    /// @param permissionId The permission ID to check for.
-    /// @param includeRoot A flag indicating if the return value should default to true if the operator has the ROOT
-    /// permission.
-    /// @param includeWildcardProjectId A flag indicating if the return value should return true if the operator has the
-    /// specified permission on the wildcard project ID.
-    /// @return A flag indicating whether the operator has the specified permission.
+    /// @notice Check whether an operator has a single permission for an account and project.
+    /// @param operator The address to check.
+    /// @param account The account that granted (or didn't grant) the permission.
+    /// @param projectId The project ID to check within. Pass 0 to check the wildcard scope directly.
+    /// @param permissionId The specific permission ID to look for (0–255).
+    /// @param includeRoot If `true`, returns `true` immediately when the operator has the ROOT permission.
+    /// @param includeWildcardProjectId If `true`, also checks wildcard (project 0) permissions as a fallback.
+    /// @return Whether the operator holds the requested permission.
     function hasPermission(
         address operator,
         address account,

package/src/JBPrices.sol

@@ -13,12 +13,13 @@ import {IJBPriceFeed} from "./interfaces/IJBPriceFeed.sol";
 import {IJBPrices} from "./interfaces/IJBPrices.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 
-/// @notice Manages and normalizes price feeds. Price feeds are contracts which return the "pricing currency" cost of 1
-/// "unit currency".
-/// @dev Price feeds are immutable once set and cannot be replaced or removed. This prevents oracle manipulation via
-/// admin-key attacks, but means a misconfigured or failing feed will cause operations using that currency pair to
-/// revert (DoS, not fund loss). Select feeds carefully — recovery requires deploying a new JBPrices contract and
-/// migrating projects.
+/// @notice Provides currency conversion for the protocol. When a project's payout limits or surplus allowances are
+/// denominated in a currency different from the token held in its terminal (e.g. USD limits with ETH held), this
+/// contract resolves the exchange rate via registered price feeds (typically Chainlink oracles).
+/// @dev Price feeds are immutable once set — they cannot be replaced or removed. This protects against oracle
+/// manipulation via admin-key attacks. If a feed is misconfigured, operations using that pair will revert (DoS, not
+/// fund loss). The inverse of any registered feed is auto-calculated. Projects can have their own feeds; project ID 0
+/// holds protocol-wide defaults.
 contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBPrices {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -85,13 +86,14 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Add a price feed for the `unitCurrency`, priced in terms of the `pricingCurrency`.
-    /// @dev Price feeds can only be added, not modified or removed. Once a feed is set for a currency pair (in either
-    /// direction), it is permanent for that project ID. Recovery from a misconfigured feed requires deploying a new
-    /// JBPrices contract.
-    /// @dev This contract's owner can add protocol-wide default price feed by passing a `projectId` of 0.
-    /// @param projectId The ID of the project to add a feed for. If `projectId` is 0, add a protocol-wide default price
-    /// feed.
+    /// @notice Register a price feed that provides the exchange rate between two currencies. For example, registering
+    /// an ETH/USD feed allows payout limits denominated in USD to be enforced against ETH balances.
+    /// @dev Price feeds are immutable — once set for a currency pair, they cannot be replaced or removed. This
+    /// prevents
+    /// admin-key oracle manipulation. The inverse rate is auto-calculated, so registering A→B also provides B→A.
+    /// @dev Pass `projectId` = 0 to set a protocol-wide default (owner only). Non-zero project IDs require controller
+    /// authorization. A default feed for a pair blocks per-project overrides for that same pair.
+    /// @param projectId The ID of the project to add a feed for. Pass 0 for a protocol-wide default.
     /// @param pricingCurrency The currency the feed's output price is in terms of.
     /// @param unitCurrency The currency being priced by the feed.
     /// @param feed The address of the price feed to add.
@@ -156,11 +158,14 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Gets the `pricingCurrency` cost for one unit of the `unitCurrency`.
-    /// @param projectId The ID of the project to check the feed for. Feeds stored in ID 0 are used by default for all
-    /// projects.
-    /// @param pricingCurrency The currency the feed's resulting price is in terms of.
-    /// @param unitCurrency The currency being priced by the feed.
+    /// @notice Convert between currencies — returns how much of `pricingCurrency` one unit of `unitCurrency` is
+    /// worth.
+    /// For example, `pricePerUnitOf(id, USD, ETH, 18)` returns the USD price of 1 ETH with 18 decimals.
+    /// @dev Lookup order: project-specific feed → inverse of project feed → default feed (project 0) → inverse of
+    /// default. Reverts with `JBPrices_PriceFeedNotFound` if no feed exists in any direction.
+    /// @param projectId The ID of the project to check the feed for. Falls back to project 0 (protocol defaults).
+    /// @param pricingCurrency The currency the result is denominated in.
+    /// @param unitCurrency The currency being priced.
     /// @param decimals The number of decimals the returned fixed point price should include.
     /// @return The `pricingCurrency` price of 1 `unitCurrency`, as a fixed point number with the specified number of
     /// decimals.

package/src/JBProjects.sol

@@ -9,8 +9,9 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBTokenUriResolver} from "./interfaces/IJBTokenUriResolver.sol";
 
-/// @notice Stores project ownership and metadata.
-/// @dev Projects are represented as ERC-721s.
+/// @notice Each Juicebox project is an ERC-721 NFT. Whoever holds the NFT owns the project and can configure its
+/// rulesets, terminals, and permissions. Projects are created with `createFor` and the resulting token ID is used as
+/// the project's ID across the entire protocol.
 contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
@@ -50,7 +51,9 @@ contract JBProjects is ERC721, ERC2771Context, Ownable, IJBProjects {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets the address of the resolver used to retrieve the tokenURI of projects.
+    /// @notice Set the contract that resolves project NFT metadata (the `tokenURI`). This controls what artwork and
+    /// JSON metadata is returned for each project's ERC-721 token.
+    /// @dev Only this contract's owner can change the resolver.
     /// @param resolver The address of the new resolver.
     function setTokenUriResolver(IJBTokenUriResolver resolver) external override onlyOwner {
         // Store the new resolver.