@bananapus/721-hook-v6 0.0.67 → 0.0.69

package/README.md

@@ -2,13 +2,17 @@
 
 `@bananapus/721-hook-v6` is the tiered NFT issuance layer for Juicebox V6. It lets a project mint ERC-721s on payment, attach tier-specific pricing and supply rules, mint reserves, and integrate custom token URI resolvers.
 
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
-User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
-Skills: [SKILLS.md](./SKILLS.md)  
-Risks: [RISKS.md](./RISKS.md)  
-Invariants: [INVARIANTS.md](./INVARIANTS.md)  
-Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
-Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — module layout, data flow, and the hook-store accounting model.
+- [INVARIANTS.md](./INVARIANTS.md) — per-contract operation inventory and the guarantees the hook makes to projects and integrators.
+- [ADMINISTRATION.md](./ADMINISTRATION.md) — admin surfaces, role matrix, immutable decisions, and recovery posture.
+- [RISKS.md](./RISKS.md) — threat model, accepted risks, and invariants to verify.
+- [USER_JOURNEYS.md](./USER_JOURNEYS.md) — example end-to-end flows for launching, paying, minting, and cashing out tiers.
+- [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — what to focus on for a security audit and how to start.
+- [SKILLS.md](./SKILLS.md) — implementation nuances, gotchas, and reading order for working on this codebase.
+- [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity conventions and repo layout used across the V6 ecosystem.
+- [CHANGELOG.md](./CHANGELOG.md) — v5 → v6 ABI and behavior deltas.
+- [references/runtime.md](./references/runtime.md) — contract roles, the runtime pay and cash-out path, and high-risk areas.
+- [references/operations.md](./references/operations.md) — deployment surface, change checklist, and common failure modes.
 
 ## Overview
 
@@ -25,7 +29,7 @@ Use this repo when a project's NFT logic should be part of its payment and cash-
 
 This repo does more than "mint NFTs on pay." It changes how payment value, tier state, reserves, and cash-out behavior interact.
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -36,7 +40,7 @@ This repo does more than "mint NFTs on pay." It changes how payment value, tier
 | `JB721Hook` | Abstract base for 721 pay and cash-out hook behavior. |
 | `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints plus per-tier eligible voting units (`getPastTierVotingUnits`) for tier-scoped reward distribution. |
 
-## Mental Model
+## Mental model
 
 Think about the repo in three pieces:
 
@@ -46,7 +50,7 @@ Think about the repo in three pieces:
 
 If a bug affects supply, reserve minting, or tier lookup, it usually lives in the hook-store interaction. If it affects project wiring, it usually lives in the deployer path or in how the hook is attached to rulesets.
 
-## Read These Files First
+## Read these files first
 
 1. `src/JB721TiersHook.sol`
 2. `src/JB721TiersHookStore.sol`
@@ -54,7 +58,7 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 4. `src/JB721TiersHookDeployer.sol` or `src/JB721TiersHookProjectDeployer.sol`
 5. the resolver contract in the downstream repo, if present
 
-## Integration Traps
+## Integration traps
 
 - this hook participates in treasury-facing execution, not only metadata
 - custom token URI resolvers should be treated as part of the trusted surface
@@ -62,7 +66,7 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 - projects should be explicit about whether the hook affects pay, cash out, or only metadata-facing paths
 - per-tier eligible voting units are queryable via `getPastTierVotingUnits(tierId, blockNumber)` for tier-scoped reward denominators, but minting alone does not enroll a token: a token only counts toward that total once it is enrolled (`delegate(address, uint256[])`) or transferred for the first time, and stops counting when burned
 
-## Where State Lives
+## Where state lives
 
 - tier definitions and accounting: `JB721TiersHookStore`
 - project-facing execution and permission checks: `JB721TiersHook`
@@ -70,7 +74,7 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 
 That split is why UI bugs, economic bugs, and deployment bugs often land in different repos even when users describe them all as "721 hook issues."
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/E2E/Pay_Mint_Redeem_E2E.t.sol`
 2. `test/invariants/TierLifecycleInvariant.t.sol`
@@ -97,11 +101,11 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Deployment Notes
+## Deployment notes
 
 Hooks are deployed as clones and typically registered in the address registry. The package is designed to compose with Omnichain, Croptop, Defifa, Banny, and other packages that rely on tier-aware NFT issuance.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -120,7 +124,7 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - tier accounting is sensitive to reserve minting, split routing, and cross-currency normalization
 - tiny split allocations can round down to zero recipient amounts
@@ -130,7 +134,7 @@ script/
 
 When people say "the 721 hook," they often mean three different things: the hook contract, the store, and the metadata resolver plugged into it.
 
-## For AI Agents
+## For AI agents
 
 - Separate hook behavior, store behavior, and resolver behavior in your explanation.
 - Read the store invariants and end-to-end pay/mint/redeem tests before summarizing lifecycle guarantees.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.67",
+  "version": "0.0.69",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "^0.0.33",
-    "@bananapus/core-v6": "^0.0.79",
+    "@bananapus/core-v6": "^0.0.81",
     "@bananapus/ownable-v6": "^0.0.36",
     "@bananapus/permission-ids-v6": "^0.0.29",
     "@openzeppelin/contracts": "5.6.1",

package/references/operations.md

@@ -1,12 +1,12 @@
 # 721 Hook Operations
 
-## Deployment Surface
+## Deployment surface
 
 - [`src/JB721TiersHookDeployer.sol`](../src/JB721TiersHookDeployer.sol) clones and initializes hooks for existing projects.
 - [`src/JB721TiersHookProjectDeployer.sol`](../src/JB721TiersHookProjectDeployer.sol) combines hook deployment with project launch or ruleset setup.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) is the deployment entry point when you need current deployment wiring rather than abstract runtime behavior.
 
-## Change Checklist
+## Change checklist
 
 - If you edit hook initialization, verify deployer config structs and project-launch helpers still encode the same assumptions.
 - If you edit tier config or metadata behavior, inspect the corresponding structs and interfaces in `src/structs/` and `src/interfaces/`.
@@ -16,14 +16,14 @@
 - If you touch permissions, verify the caller path and permission constants still line up with the downstream ecosystem package that defines them.
 - If you touch URI behavior, confirm whether the issue belongs in this repo or in a downstream resolver contract that the hook calls.
 
-## Common Failure Modes
+## Common failure modes
 
 - Payment metadata decodes to tier IDs that no longer match the intended mint path.
 - Reserve or owner-mint changes accidentally violate the store's supply guarantees.
 - Hook-side assumptions drift from deployer-side assumptions, especially around initialization flags and pricing context.
 - A change looks metadata-only but actually changes treasury behavior because split, credit, or cash-out logic moved with it.
 
-## Useful Proof Points
+## Useful proof points
 
 - [`test/Fork.t.sol`](../test/Fork.t.sol) for live-integration assumptions.
 - [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for known edge cases the repo authors considered worth pinning down.

package/references/runtime.md

@@ -1,13 +1,13 @@
 # 721 Hook Runtime
 
-## Contract Roles
+## Contract roles
 
 - [`src/abstract/JB721Hook.sol`](../src/abstract/JB721Hook.sol) is the shared pay and cash-out hook surface. It validates the calling terminal, decodes metadata, and delegates runtime behavior to the concrete hook.
 - [`src/JB721TiersHook.sol`](../src/JB721TiersHook.sol) is the main project-facing contract. It handles tier-aware minting, split forwarding, discount updates, metadata changes, reserve minting, and cash-out weight calculations.
 - [`src/JB721TiersHookStore.sol`](../src/JB721TiersHookStore.sol) is the shared storage and accounting backend. It owns tier definitions, supply counters, burn counts, reserve availability, and voting-unit state.
 - [`src/libraries/JB721TiersHookLib.sol`](../src/libraries/JB721TiersHookLib.sol) holds size-sensitive helper logic such as tier adjustment, split calculation/distribution, pricing normalization, and token-URI resolution.
 
-## Runtime Path
+## Runtime path
 
 1. Terminal calls [`src/abstract/JB721Hook.sol`](../src/abstract/JB721Hook.sol) through the pay or cash-out hook interface.
 2. The abstract hook validates the terminal and decodes metadata.
@@ -15,7 +15,7 @@
 4. [`src/JB721TiersHookStore.sol`](../src/JB721TiersHookStore.sol) records the mint, reserve, burn, and tier-state effects.
 5. If the flow forwards split funds or resolves token metadata, the hook delegates into [`src/libraries/JB721TiersHookLib.sol`](../src/libraries/JB721TiersHookLib.sol).
 
-## High-Risk Areas
+## High-risk areas
 
 - Reserve accounting: edits around `reserveFrequency`, pending reserves, or owner minting must preserve the store's supply protections.
 - Tier splits: split forwarding changes affect both payer economics and project treasury accounting. Check both `beforePayRecordedWith` and the distribution path.
@@ -24,7 +24,7 @@
 - Tier removal and cleanup: removing tiers is not the same as cleaning the sorted tier list. Storage cleanup behavior matters.
 - Default reserve beneficiary changes: they affect which tiers count pending reserves unless a tier-specific beneficiary overrides it. That is an economic change, not just an admin update.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`test/Fork.t.sol`](../test/Fork.t.sol) for launch and live integration flows.
 - [`test/TestVotingUnitsLifecycle.t.sol`](../test/TestVotingUnitsLifecycle.t.sol) for voting-unit lifecycle behavior.

package/src/JB721Checkpoints.sol

@@ -24,8 +24,13 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when `initialize` is called on a module whose hook has already been set.
     error JB721Checkpoints_AlreadyInitialized(address hook);
+
+    /// @notice Thrown when the caller tries to enroll a token they do not currently own.
     error JB721Checkpoints_NotOwner(uint256 tokenId, address caller);
+
+    /// @notice Thrown when a hook-only function is called by an address other than the module's hook.
     error JB721Checkpoints_Unauthorized(address caller, address hook);
 
     //*********************************************************************//
@@ -158,7 +163,10 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
-    /// @inheritdoc IJB721Checkpoints
+    /// @notice The total eligible voting units of a tier at a past block.
+    /// @param tierId The tier to get the eligible voting units of.
+    /// @param blockNumber The block number to look up (must be strictly in the past).
+    /// @return The tier's eligible voting units at `blockNumber`.
     function getPastTierVotingUnits(uint256 tierId, uint256 blockNumber) external view override returns (uint256) {
         // forge-lint: disable-next-line(unsafe-typecast)
         return _tierEligibleUnitsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));

package/src/JB721CheckpointsDeployer.sol

@@ -17,6 +17,7 @@ contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the caller of `deploy` is not the hook the module will serve.
     error JB721CheckpointsDeployer_Unauthorized(address caller, address hook);
 
     //*********************************************************************//

package/src/JB721TiersHook.sol

@@ -41,11 +41,22 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when `initialize` is called on a hook that has already been initialized.
     error JB721TiersHook_AlreadyInitialized(uint256 projectId);
+
+    /// @notice Thrown when the configured pricing decimals exceed 18.
     error JB721TiersHook_InvalidPricingDecimals(uint256 decimals);
+
+    /// @notice Thrown when minting reserved NFTs while the ruleset has reserve minting paused.
     error JB721TiersHook_MintReserveNftsPaused(uint256 projectId, uint256 tierId);
+
+    /// @notice Thrown when forwarded funds must be distributed to tier splits but no split metadata was provided.
     error JB721TiersHook_MissingSplitMetadata();
+
+    /// @notice Thrown when the hook is initialized with a project ID of zero.
     error JB721TiersHook_NoProjectId(uint256 projectId);
+
+    /// @notice Thrown when an NFT is transferred (to a non-zero address) while the ruleset has transfers paused.
     error JB721TiersHook_TierTransfersPaused(uint256 projectId, uint256 tokenId, address from, address to);
 
     //*********************************************************************//
@@ -97,7 +108,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     //*********************************************************************//
 
     /// @notice The first owner of each token ID, stored on first transfer out.
-    /// @custom:param The token ID of the NFT to get the stored first owner of.
+    /// @custom:param tokenId The token ID of the NFT to get the stored first owner of.
     mapping(uint256 tokenId => address) internal _firstOwnerOf;
 
     /// @notice Packed context for the pricing of this contract's tiers.
@@ -755,6 +766,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @notice Before transferring an NFT, register its first owner (if necessary).
     /// @param to The address to transfer the NFT to.
     /// @param tokenId The token ID of the NFT to transfer.
+    /// @return from The address the NFT is being transferred from.
     function _update(address to, uint256 tokenId, address auth) internal virtual override returns (address from) {
         // Get only the tier ID and transfersPausable flag (lightweight — avoids full struct construction).
         (uint256 tierId, bool transfersPausable) =

package/src/JB721TiersHookStore.sol

@@ -29,24 +29,62 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when an owner mint is attempted on a tier that does not allow owner minting.
     error JB721TiersHookStore_CantMintManually(uint256 tierId);
+
+    /// @notice Thrown when removing a tier that is flagged as non-removable.
     error JB721TiersHookStore_CantRemoveTier(uint256 tierId);
+
+    /// @notice Thrown when adding a tier with an initial supply of one and a non-zero reserve frequency, which would
+    /// deadlock reserve minting.
     error JB721TiersHookStore_DeadlockedReserve(uint256 tierId, uint256 initialSupply, uint256 reserveFrequency);
+
+    /// @notice Thrown when a tier's discount percent exceeds the discount denominator.
     error JB721TiersHookStore_DiscountPercentExceedsBounds(uint256 percent, uint256 limit);
+
+    /// @notice Thrown when increasing a tier's discount percent that is flagged as not allowing discount increases.
     error JB721TiersHookStore_DiscountPercentIncreaseNotAllowed(uint256 percent, uint256 storedPercent);
+
+    /// @notice Thrown when minting more reserved NFTs than the number currently pending for the tier.
     error JB721TiersHookStore_InsufficientPendingReserves(uint256 count, uint256 numberOfPendingReserves);
+
+    /// @notice Thrown when minting from a tier that has no remaining supply available for the mint.
     error JB721TiersHookStore_InsufficientSupplyRemaining(uint256 tierId);
+
+    /// @notice Thrown when tiers to add are not sorted by category in ascending order.
     error JB721TiersHookStore_InvalidCategorySortOrder(uint256 tierCategory, uint256 previousTierCategory);
+
+    /// @notice Thrown when a tier's initial supply exceeds the maximum allowed quantity.
     error JB721TiersHookStore_InvalidQuantity(uint256 quantity, uint256 limit);
+
+    /// @notice Thrown when adding a tier with owner minting enabled while the contract's flags disallow it.
     error JB721TiersHookStore_ManualMintingNotAllowed(uint256 tierId);
+
+    /// @notice Thrown when adding tiers would exceed the maximum number of tiers the contract can hold.
     error JB721TiersHookStore_MaxTiersExceeded(uint256 numberOfTiers, uint256 limit);
+
+    /// @notice Thrown when adding a tier with reserves but neither a tier-specific nor default reserve beneficiary set.
     error JB721TiersHookStore_MissingReserveBeneficiary(uint256 tierId);
+
+    /// @notice Thrown when a tier's price exceeds the amount left over to spend on it.
     error JB721TiersHookStore_PriceExceedsAmount(uint256 price, uint256 leftoverAmount);
+
+    /// @notice Thrown when adding a tier with a reserve frequency while the contract's flags disallow it.
     error JB721TiersHookStore_ReserveFrequencyNotAllowed(uint256 tierId);
+
+    /// @notice Thrown when a tier's split percent exceeds the total splits percent.
     error JB721TiersHookStore_SplitPercentExceedsBounds(uint256 percent, uint256 limit);
+
+    /// @notice Thrown when operating on a tier that has been removed.
     error JB721TiersHookStore_TierRemoved(uint256 tierId);
+
+    /// @notice Thrown when referencing a tier that does not exist.
     error JB721TiersHookStore_UnrecognizedTier(uint256 tierId);
+
+    /// @notice Thrown when adding a tier with voting units while the contract's flags disallow it.
     error JB721TiersHookStore_VotingUnitsNotAllowed(uint256 tierId);
+
+    /// @notice Thrown when adding a tier with an initial supply of zero.
     error JB721TiersHookStore_ZeroInitialSupply(uint256 tierId);
 
     //*********************************************************************//
@@ -544,13 +582,11 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         });
     }
 
-    /// @notice The total cash-out weight across all outstanding NFTs (including pending reserves). This is the
-    /// denominator used to determine what fraction of a project's surplus each NFT can reclaim on cash out.
     //*********************************************************************//
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
-    /// @notice Get the first tier ID from an 721 contract (when sorted by category) within a provided category.
+    /// @notice Get the first tier ID from a 721 contract (when sorted by category) within a provided category.
     /// @param hook The 721 contract to get the first sorted tier ID of.
     /// @param category The category to get the first sorted tier ID within. Send 0 for the first ID across all tiers,
     /// which may belong to any category.
@@ -561,7 +597,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         if (id == 0) id = 1;
     }
 
-    /// @notice Generate a token ID for an 721 given a tier ID and a token number within that tier.
+    /// @notice Generate a token ID for a 721 given a tier ID and a token number within that tier.
     /// @param tierId The ID of the tier to generate a token ID for.
     /// @param tokenNumber The token number of the 721 within the tier.
     /// @return The token ID of the 721.
@@ -644,7 +680,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         return bitmapWord.isTierIdRemoved(tierId);
     }
 
-    /// @notice The last sorted tier ID from an 721 contract (when sorted by category).
+    /// @notice The last sorted tier ID from a 721 contract (when sorted by category).
     /// @param hook The 721 contract to get the last sorted tier ID of.
     /// @return id The last sorted tier ID.
     function _lastSortedTierIdOf(address hook) internal view returns (uint256 id) {
@@ -771,6 +807,12 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @param cantBeRemoved Whether this tier is permanently locked and cannot be removed once added.
     /// @param cantIncreaseDiscountPercent Whether the discount percent can only stay the same or decrease.
     /// @param cantBuyWithCredits Whether this tier cannot be purchased using accumulated pay credits.
+    /// @return allowOwnerMint Whether the project owner can mint from this tier directly (without paying).
+    /// @return transfersPausable Whether transfers of NFTs from this tier can be paused by the ruleset.
+    /// @return useVotingUnits Whether this tier uses a custom voting power value instead of defaulting to its price.
+    /// @return cantBeRemoved Whether this tier is permanently locked and cannot be removed once added.
+    /// @return cantIncreaseDiscountPercent Whether the discount percent can only stay the same or decrease.
+    /// @return cantBuyWithCredits Whether this tier cannot be purchased using accumulated pay credits.
     function _unpackBools(uint8 packed)
         internal
         pure

package/src/abstract/JB721Hook.sol

@@ -31,10 +31,19 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when a cash out callback carries value, comes from a non-terminal, or targets the wrong project.
     error JB721Hook_InvalidCashOut(address caller, uint256 contextProjectId, uint256 projectId, uint256 msgValue);
+
+    /// @notice Thrown when a pay callback comes from a non-terminal or targets the wrong project.
     error JB721Hook_InvalidPay(address caller, uint256 contextProjectId, uint256 projectId);
+
+    /// @notice Thrown when the ETH attached to a pay callback does not match the terminal-forwarded amount.
     error JB721Hook_InvalidPayValue(address token, uint256 msgValue, uint256 forwardedValue);
+
+    /// @notice Thrown when cashing out an NFT whose owner is not the cash-out holder.
     error JB721Hook_UnauthorizedToken(uint256 tokenId, address holder);
+
+    /// @notice Thrown when fungible project tokens are cashed out alongside the NFTs (non-zero cash-out count).
     error JB721Hook_UnexpectedTokenCashedOut(uint256 cashOutCount);
 
     //*********************************************************************//

package/src/libraries/JB721TiersHookLib.sol

@@ -31,21 +31,55 @@ library JB721TiersHookLib {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the fresh payment value does not cover the cost of credit-restricted tiers being minted.
     error JB721TiersHook_CantBuyWithCredits(uint256 restrictedCost, uint256 freshValue);
+
+    /// @notice Thrown when funds are left over after minting but overspending is not allowed.
     error JB721TiersHook_Overspending(uint256 leftoverAmount);
+
+    /// @notice Thrown when leftover funds must be routed to the project but it has no primary terminal for the token.
     error JB721TiersHookLib_NoTerminalForLeftover(uint256 projectId, address token, uint256 leftoverAmount);
+
+    /// @notice Thrown when the per-tier split amounts do not sum to the total amount forwarded by the terminal.
     error JB721TiersHookLib_SplitAmountMismatch(uint256 expectedAmount, uint256 actualAmount);
+
+    /// @notice Thrown when routing leftover funds to the project's terminal reverts or under-consumes the allowance.
     error JB721TiersHookLib_SplitFallbackFailed(uint256 projectId, address token, uint256 amount, bytes reason);
+
+    /// @notice Thrown when the decoded split metadata's tier ID and amount arrays have different lengths.
     error JB721TiersHookLib_SplitMetadataLengthMismatch(uint256 tierIdCount, uint256 amountCount);
+
+    /// @notice Thrown when the ERC-20 amount actually received does not match the expected transfer amount.
     error JB721TiersHookLib_TokenTransferAmountMismatch(uint256 expectedAmount, uint256 receivedAmount);
 
     //*********************************************************************//
     // ------------------------------- events ---------------------------- //
     //*********************************************************************//
 
+    /// @notice Emitted when a new tier is added.
+    /// @param tierId The ID of the tier that was added.
+    /// @param tier The configuration of the tier that was added.
+    /// @param caller The address that called the function.
     event AddTier(uint256 indexed tierId, JB721TierConfig tier, address caller);
+
+    /// @notice Emitted when a tier is removed.
+    /// @param tierId The ID of the tier that was removed.
+    /// @param caller The address that called the function.
     event RemoveTier(uint256 indexed tierId, address caller);
+
+    /// @notice Emitted when a tier's discount percent is set.
+    /// @param tierId The ID of the tier whose discount percent was set.
+    /// @param discountPercent The new discount percent.
+    /// @param caller The address that called the function.
     event SetDiscountPercent(uint256 indexed tierId, uint256 discountPercent, address caller);
+
+    /// @notice Emitted when a split payout reverts during distribution. The failed split's funds route to the
+    /// project's balance.
+    /// @param projectId The project ID the split belongs to.
+    /// @param split The split that reverted.
+    /// @param amount The amount that was paid out.
+    /// @param reason The revert reason bytes.
+    /// @param caller The address that called the function.
     event SplitPayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
 
     //*********************************************************************//