@rev-net/core-v6 0.0.39 → 0.0.41

package/src/REVOwner.sol

@@ -28,9 +28,13 @@ import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
 import {IREVLoans} from "./interfaces/IREVLoans.sol";
 import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
-/// @notice Handles the runtime data hook and cash out hook behavior for revnets.
-/// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit.
-/// This contract is set as the `dataHook` in each revnet's ruleset metadata.
+/// @notice The runtime hook for all revnets — set as every revnet's `dataHook` in ruleset metadata. At pay time, it
+/// coordinates the 721 hook (NFT tier minting) with the buyback hook (secondary market swap routing) and scales weight
+/// for split deductions. At cash-out time, it aggregates cross-chain total supply and surplus (including outstanding
+/// loan debt and collateral), grants suckers 0% tax, splits a 2.5% fee from non-sucker cash outs, and routes fee
+/// proceeds to the fee revnet via `afterCashOutRecordedWith`.
+/// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit. Also implements
+/// `IJBPeerChainAdjustedAccounts` to expose loan state to peer-chain supply/surplus snapshots.
 contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAccounts {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
@@ -79,12 +83,12 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     //*********************************************************************//
 
     /// @notice The timestamp of when cashouts will become available to a specific revnet's participants.
-    /// @dev Only applies to existing revnets which are deploying onto a new network.
-    /// @custom:param revnetId The ID of the revnet to get the cash out delay for.
+    /// @dev Only applies to existing revnets deploying onto a new network.
+    /// @custom:param revnetId The ID of the revnet to check the cash out delay for.
     mapping(uint256 revnetId => uint256 cashOutDelay) public cashOutDelayOf;
 
     /// @notice Each revnet's tiered ERC-721 hook.
-    /// @custom:param revnetId The ID of the revnet to get the tiered ERC-721 hook for.
+    /// @custom:param revnetId The ID of the revnet to look up.
     // slither-disable-next-line uninitialized-state
     mapping(uint256 revnetId => IJB721TiersHook tiered721Hook) public tiered721HookOf;
 
@@ -130,20 +134,20 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Determine how a cash out from a revnet should be processed.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a cash out.
-    /// @dev If a sucker is cashing out, no taxes or fees are imposed.
-    /// @dev REVOwner is intentionally not registered as a feeless address. The protocol fee (2.5%) applies on top
-    /// of the rev fee — this is by design. The fee hook spec amount sent to `afterCashOutRecordedWith` will have the
-    /// protocol fee deducted by the terminal before reaching this contract, so the rev fee is computed on the
-    /// post-protocol-fee amount.
+    /// @notice Called before a cash out is recorded. Suckers get 0% tax (bridged tokens redeem at face value). For
+    /// regular holders, aggregates cross-chain total supply and surplus (including outstanding loan debt/collateral),
+    /// splits a 2.5% fee from the cashed-out token count, computes bonding curve reclaims for both the holder's portion
+    /// and the fee portion, then delegates to the buyback hook for potential swap routing.
+    /// @dev Part of `IJBRulesetDataHook`. REVOwner is intentionally not registered as a feeless address — the
+    /// protocol
+    /// fee (2.5%) applies on top of the rev fee. The fee hook spec amount sent to `afterCashOutRecordedWith` will have
+    /// the protocol fee deducted by the terminal before reaching this contract.
     /// @param context Standard Juicebox cash out context. See `JBBeforeCashOutRecordedContext`.
-    /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
-    /// out.
-    /// @return cashOutCount The number of revnet tokens that are cashed out.
+    /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens reclaimed.
+    /// @return cashOutCount The number of revnet tokens to cash out.
     /// @return totalSupply The total token supply across all chains (for both proportional reclaim and tax).
     /// @return effectiveSurplusValue The global surplus across all chains for proportional reclaim.
-    /// @return hookSpecifications The amount of funds and the data to send to cash out hooks (this contract).
+    /// @return hookSpecifications The amount of funds and data to send to cash out hooks (this contract).
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
         external
         view
@@ -289,13 +293,16 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
     }
 
-    /// @notice Before a revnet processes an incoming payment, determine the weight and pay hooks to use.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a payment.
+    /// @notice Called before a payment is recorded. Coordinates the 721 hook (NFT tier minting with split deductions)
+    /// with the buyback hook (which may route funds through a Uniswap pool for a better token price). Merges their hook
+    /// specifications and scales the minting weight so payers only receive tokens proportional to funds entering the
+    /// project (not the split portion).
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook spec comes first in the returned array.
     /// @param context Standard Juicebox payment context. See `JBBeforePayRecordedContext`.
     /// @return weight The weight which revnet tokens are minted relative to. This can be used to customize how many
     /// tokens get minted by a payment.
-    /// @return hookSpecifications Amounts (out of what's being paid in) to be sent to pay hooks instead of being paid
-    /// into the revnet. Useful for automatically routing funds from a treasury as payments come in.
+    /// @return hookSpecifications Amounts (out of what's paid in) to send to pay hooks instead of adding to the
+    /// revnet. Useful for automatically routing funds from a treasury as payments come in.
     function beforePayRecordedWith(JBBeforePayRecordedContext calldata context)
         external
         view
@@ -347,11 +354,13 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         if (usesBuybackHook) hookSpecifications[usesTiered721Hook ? 1 : 0] = buybackHookSpecs[0];
     }
 
-    /// @notice A flag indicating whether an address has permission to mint a revnet's tokens on-demand.
-    /// @dev Required by the `IJBRulesetDataHook` interface.
-    /// @param revnetId The ID of the revnet to check permissions for.
-    /// @param ruleset The ruleset to check the mint permission for.
-    /// @param addr The address to check the mint permission of.
+    /// @notice Returns whether an address may mint a revnet's tokens on-demand. Grants permission to: the loans
+    /// contract (re-mints collateral on repayment), hidden tokens contract (re-mints on reveal), buyback hook and its
+    /// delegates (mints tokens from pool swaps), and suckers (mints bridged tokens on the destination chain).
+    /// @dev Part of `IJBRulesetDataHook`.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param ruleset The ruleset to check against.
+    /// @param addr The address to check.
     /// @return flag A flag indicating whether the address has permission to mint the revnet's tokens on-demand.
     function hasMintPermissionFor(
         uint256 revnetId,
@@ -374,9 +383,9 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @dev Hidden tokens are intentionally excluded. Revnet operators can hide tokens as a security handle without
     /// changing loan or cash-out math for other holders. Outstanding loan debt is counted as both surplus and balance:
     /// it is value owed back to this chain's revnet and should travel to peer snapshots with the collateral supply.
-    /// @param revnetId The ID of the revnet being snapshotted.
-    /// @param decimals The decimals the returned surplus should use.
-    /// @param currency The currency the returned surplus should be in terms of.
+    /// @param revnetId The ID of the revnet to snapshot.
+    /// @param decimals The decimals to use for the returned surplus.
+    /// @param currency The currency to denominate the returned surplus in.
     /// @return supply The loan-collateral supply to include in the peer snapshot.
     /// @return surplus The outstanding loan debt to include in `sourceSurplus`.
     /// @return balance The outstanding loan debt to include in `sourceBalance`.
@@ -398,7 +407,7 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     // --------------------- external transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Processes the fee from a cash out.
+    /// @notice Process the fee from a cash out.
     /// @param context Cash out context passed in by the terminal.
     function afterCashOutRecordedWith(JBAfterCashOutRecordedContext calldata context) external payable override {
         // No caller validation needed — this hook only pays fees to the fee project using funds forwarded by the
@@ -508,8 +517,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     //*********************************************************************//
 
     /// @notice A flag indicating whether an address is a revnet's sucker.
-    /// @param revnetId The ID of the revnet to check sucker status for.
-    /// @param addr The address being checked.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param addr The address to check.
     /// @return isSucker A flag indicating whether the address is one of the revnet's suckers.
     function _isSuckerOf(uint256 revnetId, address addr) internal view returns (bool) {
         return SUCKER_REGISTRY.isSuckerOf({projectId: revnetId, addr: addr});
@@ -519,8 +528,8 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     /// @dev This is included in cash-out and peer-snapshot math because borrowed funds are still owed to the revnet
     /// and collateral can re-enter supply when the loan is repaid.
     /// @param revnetId The ID of the revnet to check.
-    /// @param decimals The decimals the resulting fixed point debt value should use.
-    /// @param currency The currency the resulting debt value should be in terms of.
+    /// @param decimals The decimals to use for the resulting fixed point debt value.
+    /// @param currency The currency to denominate the resulting debt value in.
     /// @return borrowedAmount The local outstanding loan debt converted into `currency`.
     /// @return collateralCount The local burned loan collateral count.
     function _localLoanStateOf(
@@ -586,12 +595,12 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     // --------------------- internal transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Logic to be triggered before transferring tokens from this contract.
-    /// @param to The address the transfer is going to.
-    /// @param token The token being transferred.
-    /// @param amount The number of tokens being transferred, as a fixed point number with the same number of decimals
+    /// @notice Logic to trigger before transferring tokens from this contract.
+    /// @param to The address to transfer to.
+    /// @param token The token to transfer.
+    /// @param amount The number of tokens to transfer, as a fixed point number with the same number of decimals
     /// as the token specifies.
-    /// @return payValue The value to attach to the transaction being sent.
+    /// @return payValue The value to attach to the transaction.
     function _beforeTransferTo(address to, address token, uint256 amount) internal returns (uint256) {
         // If the token is the native token, no allowance needed.
         if (token == JBConstants.NATIVE_TOKEN) return amount;

package/src/interfaces/IREVDeployer.sol

@@ -136,8 +136,8 @@ interface IREVDeployer {
     /// @return The hook deployer contract.
     function HOOK_DEPLOYER() external view returns (IJB721TiersHookDeployer);
 
-    /// @notice Whether an address is a revnet's split operator.
-    /// @param revnetId The ID of the revnet.
+    /// @notice Check whether an address is a revnet's split operator.
+    /// @param revnetId The ID of the revnet to check.
     /// @param addr The address to check.
     /// @return A flag indicating whether the address is the revnet's split operator.
     function isSplitOperatorOf(uint256 revnetId, address addr) external view returns (bool);
@@ -167,13 +167,13 @@ interface IREVDeployer {
     function SUCKER_REGISTRY() external view returns (IJBSuckerRegistry);
 
     /// @notice Auto-mint a revnet's tokens from a stage for a beneficiary.
-    /// @param revnetId The ID of the revnet to auto-mint tokens from.
-    /// @param stageId The ID of the stage auto-mint tokens are available from.
-    /// @param beneficiary The address to auto-mint tokens to.
+    /// @param revnetId The ID of the revnet to auto-mint tokens for.
+    /// @param stageId The ID of the stage to auto-mint tokens from.
+    /// @param beneficiary The address to send auto-minted tokens to.
     function autoIssueFor(uint256 revnetId, uint256 stageId, address beneficiary) external;
 
     /// @notice Burn any of a revnet's tokens held by this contract.
-    /// @param revnetId The ID of the revnet whose tokens should be burned.
+    /// @param revnetId The ID of the revnet to burn tokens for.
     function burnHeldTokensOf(uint256 revnetId) external;
 
     /// @notice Deploy a revnet with a tiered ERC-721 hook and optional croptop posting support.
@@ -182,10 +182,10 @@ interface IREVDeployer {
     /// @param configuration Core revnet configuration.
     /// @param terminalConfigurations The terminals to set up for the revnet.
     /// @param suckerDeploymentConfiguration The suckers to set up for cross-chain token transfers.
-    /// @param tiered721HookConfiguration How to set up the tiered ERC-721 hook for the revnet.
-    /// @param allowedPosts Restrictions on which croptop posts are allowed on the revnet's ERC-721 tiers.
+    /// @param tiered721HookConfiguration How to configure the tiered ERC-721 hook for the revnet.
+    /// @param allowedPosts Restrictions on which croptop posts to allow on the revnet's ERC-721 tiers.
     /// @return The ID of the newly created or initialized revnet.
-    /// @return hook The tiered ERC-721 hook that was deployed for the revnet.
+    /// @return hook The tiered ERC-721 hook deployed for the revnet.
     function deployFor(
         uint256 revnetId,
         REVConfig memory configuration,
@@ -204,7 +204,7 @@ interface IREVDeployer {
     /// @param terminalConfigurations The terminals to set up for the revnet.
     /// @param suckerDeploymentConfiguration The suckers to set up for cross-chain token transfers.
     /// @return The ID of the newly created or initialized revnet.
-    /// @return hook The tiered ERC-721 hook that was deployed for the revnet.
+    /// @return hook The tiered ERC-721 hook deployed for the revnet.
     function deployFor(
         uint256 revnetId,
         REVConfig memory configuration,

package/src/interfaces/IREVHiddenTokens.sol

@@ -10,14 +10,14 @@ import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol
 interface IREVHiddenTokens {
     /// @notice Emitted when a holder is allowed or disallowed to hide their own tokens.
     /// @param revnetId The ID of the revnet.
-    /// @param holder The holder whose tokens are being allowed or disallowed.
+    /// @param holder The holder to allow or disallow.
     /// @param isAllowed Whether the holder is allowed.
     event SetTokenHidingAllowed(uint256 indexed revnetId, address indexed holder, bool isAllowed);
 
     /// @notice Emitted when tokens are hidden (burned and tracked for later reveal).
-    /// @param revnetId The ID of the revnet whose tokens are hidden.
+    /// @param revnetId The ID of the revnet whose tokens were hidden.
     /// @param tokenCount The number of tokens hidden.
-    /// @param holder The address whose tokens are hidden.
+    /// @param holder The address whose tokens were hidden.
     /// @param caller The address that hid the tokens.
     event HideTokens(uint256 indexed revnetId, uint256 tokenCount, address holder, address caller);
 
@@ -44,7 +44,7 @@ interface IREVHiddenTokens {
     function totalHiddenOf(uint256 revnetId) external view returns (uint256);
 
     /// @notice Whether a holder is allowed to hide their own tokens.
-    /// @param holder The holder whose tokens are being managed.
+    /// @param holder The holder to check.
     /// @param revnetId The ID of the revnet.
     /// @return Whether the holder is allowed.
     function tokenHidingIsAllowedFor(address holder, uint256 revnetId) external view returns (bool);

package/src/interfaces/IREVLoans.sol

@@ -89,10 +89,10 @@ interface IREVLoans {
     event SetTokenUriResolver(IJBTokenUriResolver indexed resolver, address caller);
 
     /// @notice The amount that can be borrowed from a revnet given a certain amount of collateral.
-    /// @param revnetId The ID of the revnet to check for borrowable assets from.
-    /// @param collateralCount The amount of collateral used to secure the loan.
-    /// @param decimals The decimals the resulting fixed point value will include.
-    /// @param currency The currency that the resulting amount should be in terms of.
+    /// @param revnetId The ID of the revnet to borrow from.
+    /// @param collateralCount The amount of collateral to secure the loan with.
+    /// @param decimals The decimals to use for the resulting fixed point value.
+    /// @param currency The currency to denominate the resulting amount in.
     /// @return The amount that can be borrowed from the revnet.
     function borrowableAmountFrom(
         uint256 revnetId,
@@ -108,9 +108,9 @@ interface IREVLoans {
     /// @return The controller contract.
     function CONTROLLER() external view returns (IJBController);
 
-    /// @notice Determines the source fee amount for a loan being paid off a certain amount.
-    /// @param loan The loan having its source fee amount determined.
-    /// @param amount The amount being paid off.
+    /// @notice Determines the source fee amount for a loan when paying off a certain amount.
+    /// @param loan The loan to determine the source fee for.
+    /// @param amount The amount to pay off.
     /// @return sourceFeeAmount The source fee amount for the loan.
     function determineSourceFeeAmount(
         REVLoan memory loan,
@@ -125,9 +125,9 @@ interface IREVLoans {
     function DIRECTORY() external view returns (IJBDirectory);
 
     /// @notice Whether a revnet currently has outstanding loans from the specified terminal in the specified token.
-    /// @param revnetId The ID of the revnet issuing the loan.
-    /// @param terminal The terminal that the loan is issued from.
-    /// @param token The token being loaned.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param terminal The terminal to check.
+    /// @param token The token to check.
     /// @return A flag indicating if the revnet has an active loan source.
     function isLoanSourceOf(uint256 revnetId, IJBPayoutTerminal terminal, address token) external view returns (bool);
 
@@ -135,8 +135,8 @@ interface IREVLoans {
     /// @return The loan liquidation duration in seconds.
     function LOAN_LIQUIDATION_DURATION() external view returns (uint256);
 
-    /// @notice Get a loan's details.
-    /// @param loanId The ID of the loan to retrieve.
+    /// @notice Get a loan's full details -- amount, collateral, creation time, prepaid fee, and source.
+    /// @param loanId The ID of the loan to look up.
     /// @return The loan data.
     function loanOf(uint256 loanId) external view returns (REVLoan memory);
 
@@ -176,8 +176,8 @@ interface IREVLoans {
     /// @return The REV prepaid fee percent.
     function REV_PREPAID_FEE_PERCENT() external view returns (uint256);
 
-    /// @notice The revnet ID for the loan with the provided loan ID.
-    /// @param loanId The loan ID to get the revnet ID of.
+    /// @notice The revnet ID for a given loan ID.
+    /// @param loanId The loan ID to look up.
     /// @return The ID of the revnet.
     function revnetIdOfLoanWith(uint256 loanId) external view returns (uint256);
 
@@ -186,9 +186,9 @@ interface IREVLoans {
     function tokenUriResolver() external view returns (IJBTokenUriResolver);
 
     /// @notice The total amount loaned out by a revnet from a specified terminal in a specified token.
-    /// @param revnetId The ID of the revnet issuing the loan.
-    /// @param terminal The terminal that the loan is issued from.
-    /// @param token The token being loaned.
+    /// @param revnetId The ID of the revnet to check.
+    /// @param terminal The terminal the loans were issued from.
+    /// @param token The token loaned.
     /// @return The total amount borrowed.
     function totalBorrowedFrom(
         uint256 revnetId,
@@ -213,15 +213,15 @@ interface IREVLoans {
     function totalLoansBorrowedFor(uint256 revnetId) external view returns (uint256);
 
     /// @notice Open a loan by borrowing from a revnet. Collateral tokens are burned and only re-minted upon repayment.
-    /// @param revnetId The ID of the revnet being borrowed from.
+    /// @param revnetId The ID of the revnet to borrow from.
     /// @param source The source of the loan (terminal and token).
     /// @param minBorrowAmount The minimum amount to borrow, denominated in the source's token.
     /// @param collateralCount The amount of tokens to use as collateral for the loan.
     /// @param beneficiary The address that will receive the borrowed funds and fee payment tokens.
     /// @param prepaidFeePercent The fee percent to charge upfront, in terms of `JBConstants.MAX_FEE`.
-    /// @param holder The address whose tokens are used as collateral and who receives the loan NFT.
-    /// @return loanId The ID of the loan created from borrowing.
-    /// @return The loan created from borrowing.
+    /// @param holder The address whose tokens to use as collateral and who receives the loan NFT.
+    /// @return loanId The ID of the loan created.
+    /// @return The loan created.
     function borrowFrom(
         uint256 revnetId,
         REVLoanSource calldata source,
@@ -234,7 +234,7 @@ interface IREVLoans {
         external
         returns (uint256 loanId, REVLoan memory);
 
-    /// @notice Liquidates loans that have exceeded the liquidation duration, permanently destroying their collateral.
+    /// @notice Liquidate loans that have exceeded the liquidation duration, permanently destroying their collateral.
     /// @param revnetId The ID of the revnet to liquidate loans from.
     /// @param startingLoanId The loan number to start iterating from.
     /// @param count The number of loans to iterate over.
@@ -245,7 +245,7 @@ interface IREVLoans {
     /// @param collateralCountToTransfer The amount of collateral to transfer from the original loan.
     /// @param source The source of the new loan (terminal and token). Must match the existing loan's source.
     /// @param minBorrowAmount The minimum amount to borrow for the new loan.
-    /// @param collateralCountToAdd Additional collateral to add to the new loan from the caller's balance.
+    /// @param collateralCountToAdd Additional collateral to add to the new loan from your balance.
     /// @param beneficiary The address that will receive the borrowed funds and fee payment tokens.
     /// @param prepaidFeePercent The fee percent to charge upfront for the new loan.
     /// @return reallocatedLoanId The ID of the reallocated (reduced) loan.
@@ -265,13 +265,13 @@ interface IREVLoans {
         returns (uint256 reallocatedLoanId, uint256 newLoanId, REVLoan memory reallocatedLoan, REVLoan memory newLoan);
 
     /// @notice Repay a loan or return excess collateral no longer needed to support the loan.
-    /// @param loanId The ID of the loan being repaid.
+    /// @param loanId The ID of the loan to repay.
     /// @param maxRepayBorrowAmount The maximum amount to repay, denominated in the source's token.
     /// @param collateralCountToReturn The amount of collateral to return from the loan.
-    /// @param beneficiary The address receiving the returned collateral and fee payment tokens.
+    /// @param beneficiary The address to receive the returned collateral and fee payment tokens.
     /// @param allowance A permit2 allowance to facilitate the repayment transfer.
-    /// @return paidOffLoanId The ID of the loan after it has been paid off.
-    /// @return paidOffloan The loan after it has been paid off.
+    /// @return paidOffLoanId The ID of the loan after repayment.
+    /// @return paidOffloan The loan after repayment.
     function repayLoan(
         uint256 loanId,
         uint256 maxRepayBorrowAmount,
@@ -283,7 +283,7 @@ interface IREVLoans {
         payable
         returns (uint256 paidOffLoanId, REVLoan memory paidOffloan);
 
-    /// @notice Sets the address of the resolver used to retrieve the token URI of loans.
+    /// @notice Set the address of the resolver used to retrieve the token URI of loans.
     /// @param resolver The new token URI resolver.
     function setTokenUriResolver(IJBTokenUriResolver resolver) external;
 }

package/src/structs/REV721TiersHookFlags.sol

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member noNewTiersWithReserves A flag indicating if new tiers with non-zero reserve frequency are forbidden.
-/// @custom:member noNewTiersWithVotes A flag indicating if new tiers with voting units are forbidden.
-/// @custom:member noNewTiersWithOwnerMinting A flag indicating if new tiers with owner minting are forbidden.
-/// @custom:member preventOverspending A flag indicating if payments exceeding the price of minted NFTs should be
-/// prevented.
+/// @custom:member noNewTiersWithReserves Whether to forbid new tiers with non-zero reserve frequency.
+/// @custom:member noNewTiersWithVotes Whether to forbid new tiers with voting units.
+/// @custom:member noNewTiersWithOwnerMinting Whether to forbid new tiers with owner minting.
+/// @custom:member preventOverspending Whether to prevent payments exceeding the price of minted NFTs.
 struct REV721TiersHookFlags {
     bool noNewTiersWithReserves;
     bool noNewTiersWithVotes;

package/src/structs/REVAutoIssuance.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member chainId The ID of the chain on which the mint should be honored.
-/// @custom:member count The number of tokens that should be minted.
+/// @notice A per-stage token mint that happens without any payment — think of it as a scheduled premint. Each auto
+/// issuance specifies a chain, beneficiary, and token count. Can be claimed once per stage via `autoIssueFor`.
+/// @custom:member chainId The chain ID where this auto-issuance should be honored (only mints on the matching chain).
+/// @custom:member count The number of tokens to mint for the beneficiary.
 /// @custom:member beneficiary The address that will receive the minted tokens.
 struct REVAutoIssuance {
     uint32 chainId;

package/src/structs/REVConfig.sol

@@ -4,11 +4,14 @@ pragma solidity ^0.8.0;
 import {REVDescription} from "./REVDescription.sol";
 import {REVStageConfig} from "./REVStageConfig.sol";
 
-/// @custom:member description The description of the revnet.
-/// @custom:member baseCurrency The currency that the issuance is based on.
-/// @custom:member splitOperator The address that will receive the token premint and initial production split,
-/// and who is allowed to change who the operator is. Only the operator can replace itself after deployment.
-/// @custom:member stageConfigurations The periods of changing constraints.
+/// @notice Top-level configuration for deploying a revnet. Defines the revnet's identity, base currency for issuance
+/// pricing, the split operator (who receives production splits and can reassign that role), and the ordered list of
+/// stages that govern the revnet's lifecycle.
+/// @custom:member description The revnet's name, ticker, metadata URI, and deployment salt.
+/// @custom:member baseCurrency The currency that issuance pricing is denominated in (e.g. ETH or USD).
+/// @custom:member splitOperator The address that receives production splits and can reassign the operator role.
+/// Only the current operator can replace itself after deployment.
+/// @custom:member stageConfigurations The ordered stages that define how the revnet's tokenomics evolve over time.
 struct REVConfig {
     REVDescription description;
     uint32 baseCurrency;

package/src/structs/REVCroptopAllowedPost.sol

@@ -2,14 +2,13 @@
 pragma solidity ^0.8.0;
 
 /// @notice Criteria for allowed posts.
-/// @custom:member category A category that should allow posts.
-/// @custom:member minimumPrice The minimum price that a post to the specified category should cost.
-/// @custom:member minimumTotalSupply The minimum total supply of NFTs that can be made available when minting.
-/// @custom:member maxTotalSupply The max total supply of NFTs that can be made available when minting. Leave as 0 for
-/// max.
-/// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) that a
-/// poster can set. 0 means splits are not allowed.
-/// @custom:member allowedAddresses A list of addresses that are allowed to post on the category through Croptop.
+/// @custom:member category The category to allow posts for.
+/// @custom:member minimumPrice The minimum price a post to the specified category must cost.
+/// @custom:member minimumTotalSupply The minimum total supply of NFTs to make available when minting.
+/// @custom:member maxTotalSupply The max total supply of NFTs to make available when minting. Leave as 0 for unlimited.
+/// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) a poster can
+/// set. 0 means splits are not allowed.
+/// @custom:member allowedAddresses The addresses allowed to post on the category through Croptop.
 struct REVCroptopAllowedPost {
     uint24 category;
     uint104 minimumPrice;

package/src/structs/REVDeploy721TiersHookConfig.sol

@@ -3,16 +3,16 @@ pragma solidity ^0.8.0;
 
 import {REVBaseline721HookConfig} from "./REVBaseline721HookConfig.sol";
 
-/// @custom:member baseline721HookConfiguration The baseline config.
-/// @custom:member salt The salt to base the collection's address on.
-/// @custom:member preventSplitOperatorAdjustingTiers A flag indicating if the revnet's split operator should be
-/// prevented from adding tiers and removing tiers that are allowed to be removed.
-/// @custom:member preventSplitOperatorUpdatingMetadata A flag indicating if the revnet's split operator should be
-/// prevented from updating the 721's metadata.
-/// @custom:member preventSplitOperatorMinting A flag indicating if the revnet's split operator should be prevented from
-/// minting 721's from tiers that allow it.
-/// @custom:member preventSplitOperatorIncreasingDiscountPercent A flag indicating if the revnet's split operator should
-/// be prevented from increasing the discount of a tier.
+/// @custom:member baseline721HookConfiguration The baseline 721 hook config.
+/// @custom:member salt The salt to derive the collection's address from.
+/// @custom:member preventSplitOperatorAdjustingTiers Whether to prevent the split operator from adding and removing
+/// tiers.
+/// @custom:member preventSplitOperatorUpdatingMetadata Whether to prevent the split operator from updating the 721's
+/// metadata.
+/// @custom:member preventSplitOperatorMinting Whether to prevent the split operator from minting 721s from tiers that
+/// allow it.
+/// @custom:member preventSplitOperatorIncreasingDiscountPercent Whether to prevent the split operator from increasing
+/// the discount of a tier.
 struct REVDeploy721TiersHookConfig {
     REVBaseline721HookConfig baseline721HookConfiguration;
     bytes32 salt;

package/src/structs/REVDescription.sol

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member name The name of the ERC-20 token being create for the revnet.
-/// @custom:member ticker The ticker of the ERC-20 token being created for the revnet.
-/// @custom:member uri The metadata URI containing revnet's info.
-/// @custom:member salt Revnets deployed across chains by the same address with the same salt will have the same
-/// address.
+/// @notice Identity and metadata for a revnet deployment.
+/// @custom:member name The name of the ERC-20 token created for the revnet.
+/// @custom:member ticker The ticker symbol of the ERC-20 token created for the revnet.
+/// @custom:member uri The metadata URI containing the revnet's off-chain info (logo, description, links).
+/// @custom:member salt A deployment salt — revnets deployed across chains by the same address with the same salt get
+/// deterministic matching addresses.
 struct REVDescription {
     string name;
     string ticker;

package/src/structs/REVLoan.sol

@@ -3,12 +3,16 @@ pragma solidity ^0.8.0;
 
 import {REVLoanSource} from "./REVLoanSource.sol";
 
-/// @custom:member borrowedAmount The amount that is being borrowed.
-/// @custom:member collateralTokenCount The number of collateral tokens currently accounted for.
+/// @notice An active loan against a revnet. The borrower locked collateral tokens (which were burned) and received
+/// funds from the revnet's terminal. The loan can be repaid within the prepaid duration at no extra cost; after that,
+/// repayment cost increases linearly until liquidation at 10 years.
+/// @custom:member amount The amount borrowed (includes fees taken at creation).
+/// @custom:member collateral The number of revnet tokens burned as collateral.
 /// @custom:member createdAt The timestamp when the loan was created.
-/// @custom:member prepaidFeePercent The percentage of the loan's fees that were prepaid.
-/// @custom:member prepaidDuration The duration that the loan was prepaid for.
-/// @custom:member source The source of the loan.
+/// @custom:member prepaidFeePercent The percentage of fees prepaid at creation (determines prepaid duration).
+/// @custom:member prepaidDuration The duration (seconds) during which repayment costs nothing beyond the original
+/// amount.
+/// @custom:member source The terminal and token from which funds were drawn.
 struct REVLoan {
     uint112 amount;
     uint112 collateral;

package/src/structs/REVLoanSource.sol

@@ -3,8 +3,8 @@ pragma solidity ^0.8.0;
 
 import {IJBPayoutTerminal} from "@bananapus/core-v6/src/interfaces/IJBPayoutTerminal.sol";
 
-/// @custom:member token The token that is being loaned.
-/// @custom:member terminal The terminal that the loan is being made from.
+/// @custom:member token The token to loan.
+/// @custom:member terminal The terminal to loan from.
 struct REVLoanSource {
     address token;
     IJBPayoutTerminal terminal;

package/src/structs/REVStageConfig.sol

@@ -5,22 +5,20 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
 import {REVAutoIssuance} from "./REVAutoIssuance.sol";
 
-/// @custom:member startsAtOrAfter The timestamp to start a stage at the given rate at or after.
-/// @custom:member autoIssuances The configurations of mints during this stage.
-/// @custom:member splitPercent The percentage of newly issued tokens that should be split with the operator, out
-/// of 10_000 (JBConstants.MAX_RESERVED_PERCENT).
-/// @custom:member splits The splits for the revnet.
-/// @custom:member initialIssuance The number of revnet tokens that one unit of the revnet's base currency will buy, as
-/// a fixed point number
-/// with 18 decimals.
-/// @custom:member issuanceCutFrequency The number of seconds between applied issuance decreases. This
-/// should be at least 24 hours.
-/// @custom:member issuanceCutPercent The percent that issuance should decrease over time. This percentage is out
-/// of 1_000_000_000 (JBConstants.MAX_CUT_PERCENT). 0% corresponds to no issuance increase.
-/// @custom:member cashOutTaxRate The factor determining how much each token can cash out from the revnet once
-/// cashed out. This rate is out of 10_000 (JBConstants.MAX_CASH_OUT_TAX_RATE). 0% corresponds to no tax when cashing
-/// out.
-/// @custom:member extraMetadata Extra info to attach set into this stage that may affect hooks.
+/// @notice A stage in a revnet's lifecycle. Each stage defines the token issuance rate, how quickly it decays, what
+/// percentage goes to splits, and the cash-out tax rate. Stages are processed in order — each one activates at or
+/// after
+/// its `startsAtOrAfter` timestamp.
+/// @custom:member startsAtOrAfter The earliest timestamp this stage can begin. Must be strictly increasing across
+/// stages. @custom:member autoIssuances Tokens to mint without payment during this stage (per-chain, per-beneficiary).
+/// @custom:member splitPercent The percentage of newly issued tokens routed to splits, out of 10,000.
+/// @custom:member splits The split recipients for this stage's production allocation.
+/// @custom:member initialIssuance Tokens per unit of base currency at stage start (18-decimal fixed point).
+/// @custom:member issuanceCutFrequency Seconds between each issuance reduction. Should be >= 24 hours.
+/// @custom:member issuanceCutPercent How much issuance decreases each period, out of 1,000,000,000. 0 = no decay.
+/// @custom:member cashOutTaxRate The tax on cash outs, out of 10,000. 0 = no tax (full reclaim). Higher = more tax
+/// retained by the treasury.
+/// @custom:member extraMetadata Additional metadata bits passed to hooks for stage-specific behavior.
 struct REVStageConfig {
     uint48 startsAtOrAfter;
     REVAutoIssuance[] autoIssuances;