@bananapus/721-hook-v6 0.0.21 → 0.0.22

package/SKILLS.md

@@ -86,7 +86,7 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 | `JB721Tier` | `uint32 id`, `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint104 votingUnits`, `uint16 reserveFrequency`, `address reserveBeneficiary`, `bytes32 encodedIPFSUri`, `uint24 category`, `uint8 discountPercent`, `bool allowOwnerMint`, `bool transfersPausable`, `bool cannotBeRemoved`, `bool cannotIncreaseDiscountPercent`, `uint32 splitPercent`, `string resolvedUri` | Return type from `tierOf`, `tiersOf`, `tierOfTokenId` |
 | `JBStored721Tier` | `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint32 splitPercent`, `uint24 category`, `uint8 discountPercent`, `uint16 reserveFrequency`, `uint8 packedBools` (allowOwnerMint, transfersPausable, useVotingUnits, cannotBeRemoved, cannotIncreaseDiscountPercent) | Internal storage in `JB721TiersHookStore`. Voting units stored separately in `_tierVotingUnitsOf` when `useVotingUnits` is true. |
 | `JB721InitTiersConfig` | `JB721TierConfig[] tiers`, `uint32 currency`, `uint8 decimals` | `initialize` -- defines tiers and pricing context. The prices contract is an immutable on the hook, not passed per-config. |
-| `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `address reserveBeneficiary`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
+| `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
 | `JB721TiersHookFlags` | `bool noNewTiersWithReserves`, `bool noNewTiersWithVotes`, `bool noNewTiersWithOwnerMinting`, `bool preventOverspending`, `bool issueTokensForSplits` | `initialize`, `recordFlags` |
 | `JB721TiersRulesetMetadata` | `bool pauseTransfers`, `bool pauseMintPendingReserves` | Packed into `JBRulesetMetadata.metadata` per-ruleset (bit 0 = pauseTransfers, bit 1 = pauseMintPendingReserves) |
 | `JBPayDataHookRulesetConfig` | `uint48 mustStartAtOrAfter`, `uint32 duration`, `uint112 weight`, `uint32 weightCutPercent`, `IJBRulesetApprovalHook approvalHook`, `JBPayDataHookRulesetMetadata metadata`, `JBSplitGroup[] splitGroups`, `JBFundAccessLimitGroup[] fundAccessLimitGroups` | `JB721TiersHookProjectDeployer` -- wraps core ruleset config with `useDataHookForPay: true` hardcoded |
@@ -145,8 +145,10 @@ Each tier has configurable voting power:
   - Computes `mulDiv(effectivePrice, splitPercent, SPLITS_TOTAL_PERCENT)` per tier.
   - Returns the total to be forwarded to the hook.
   - If the payment currency differs from the tier pricing currency, `convertSplitAmounts` converts amounts to the payment token denomination via `JBPrices`.
+  - **Pay credits cap**: `totalSplitAmount` is capped at `context.amount.value` before weight calculation and before being returned in the hook specification. Pay credits fund NFT minting (virtual -- they reduce the price threshold in `recordMint`), but splits require real tokens to distribute. Without this cap, a payer with sufficient pay credits but insufficient actual payment value would cause the terminal to attempt forwarding more tokens than were actually received, reverting the transaction. This means the project receiving the NFT payment must have received the full amount including what would have gone to splits -- split recipients are paid from the project's balance, not directly from the payer's contribution.
   - Weight is adjusted down proportionally (`weight = mulDiv(weight, amount - totalSplitAmount, amount)`) unless the `issueTokensForSplits` flag is set, in which case the full `context.weight` is returned.
 - In `afterPayRecordedWith`, `distributeAll` distributes forwarded funds to each tier's split group recipients. Leftover after all splits goes back to the project's balance via `addToBalance`.
+- **Leftover accounting in `_distributeSingleSplit`**: `leftoverAmount` is always decremented **before** the send attempt. If `_sendPayoutToSplit` returns `false` (i.e., the send reverted or had no valid recipient), the amount is added **back** to `leftoverAmount` so it routes to the project's balance with the remaining leftover. This "decrement-first, restore-on-failure" pattern prevents a failed split from inflating subsequent split recipients' shares (since `leftoverPercentage` still decreases regardless of success).
 - Split recipients follow the same priority chain as `JBMultiTerminal`: `split.hook` > `split.projectId` > `split.beneficiary`:
   - **Split hooks**: receive a `JBSplitHookContext` struct (`token`, `amount`, `decimals`, `projectId`, `groupId`, full `split`). Native tokens forwarded via `{value: amount}`; ERC-20s transferred via `SafeERC20.safeTransfer` before calling `processSplitWith`.
   - **Project splits**: route via `terminal.pay` or `terminal.addToBalance`.
@@ -154,7 +156,7 @@ Each tier has configurable voting power:
   - **Empty splits** (no hook, no project ID, no beneficiary): skipped -- their share stays in the leftover and routes to the project's balance via `addToBalanceOf`, preventing a misconfigured split from bricking the payout distribution.
 - All external calls in `_sendPayoutToSplit` are wrapped in try-catch to prevent a single reverting recipient from bricking all payments to the project:
   - **Native token hooks**: a revert returns `false` (ETH stays in the contract and routes to the project balance).
-  - **ERC-20 hooks**: tokens are transferred via `safeTransfer` before the callback; the function always returns `true` regardless of callback outcome because the tokens have already left -- returning `false` would cause double-spend accounting in the leftover calculation.
+  - **ERC-20 hooks**: tokens are transferred via `safeTransfer` before the callback; the function always returns `true` regardless of callback outcome because the tokens have already left this contract. Since leftoverAmount was already decremented before the send, returning `true` is required to prevent the caller from adding the amount back -- which would create a double-spend (tokens sent to the hook AND counted toward leftover routed to the project).
   - **ERC-20 terminal calls** (`pay`/`addToBalanceOf`): approval is reset to zero on failure to prevent dangling approvals.
 
 ## Gotchas
@@ -292,7 +294,6 @@ tiers[0] = JB721TierConfig({
             currency: 1,        // ETH
             decimals: 18
         }),
-        reserveBeneficiary: address(0),
         flags: JB721TiersHookFlags({
             noNewTiersWithReserves: false,
             noNewTiersWithVotes: false,

package/USER_JOURNEYS.md

@@ -315,7 +315,6 @@ Deploy a 721 tiers hook for an existing project.
     - `JB721TierConfig[] tiers` -- initial tiers (sorted by category).
     - `uint32 currency` -- pricing currency (`uint32(uint160(tokenAddress))` for concrete, or abstract like 1=ETH, 2=USD).
     - `uint8 decimals` -- pricing decimals (must be <= 18).
-  - `address reserveBeneficiary` -- (unused in current initialize; set via tier configs).
   - `JB721TiersHookFlags flags` -- collection-level behavior flags.
 - `bytes32 salt` -- for deterministic deployment (bytes32(0) for non-deterministic).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,9 +17,9 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-721-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.15",
-    "@bananapus/core-v6": "^0.0.27",
-    "@bananapus/ownable-v6": "^0.0.14",
+    "@bananapus/address-registry-v6": "^0.0.16",
+    "@bananapus/core-v6": "^0.0.28",
+    "@bananapus/ownable-v6": "^0.0.15",
     "@bananapus/permission-ids-v6": "^0.0.14",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.0",

package/src/JB721TiersHook.sol

@@ -202,6 +202,16 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             });
         }
 
+        // Cap the split amount at the actual payment value. Pay credits fund NFT minting (virtual), but splits
+        // require real tokens to distribute. Without this cap, a user with sufficient pay credits but insufficient
+        // ETH would revert because the terminal can't forward more than what was actually paid.
+        // This requires the project receiving the NFT payment to have received the full amount including what
+        // would have gone to splits — the split recipients get paid from the project's balance, not directly
+        // from the payer's contribution.
+        if (totalSplitAmount > context.amount.value) {
+            totalSplitAmount = context.amount.value;
+        }
+
         // Adjust weight so the terminal mints tokens only for the amount that actually enters the project.
         weight = JB721TiersHookLib.calculateWeight({
             contextWeight: context.weight,

package/src/libraries/JB721TiersHookLib.sol

@@ -400,10 +400,13 @@ library JB721TiersHookLib {
             uint256 payoutAmount =
                 mulDiv({x: leftoverAmount, y: tierSplits[j].percent, denominator: leftoverPercentage});
             if (payoutAmount != 0) {
-                // Only subtract from leftover if the split has a valid recipient.
-                // Splits with no projectId and no beneficiary are skipped — their share
-                // stays in leftoverAmount and is added to the project's balance below.
-                if (_sendPayoutToSplit({
+                // Always subtract from leftover to prevent failed splits from inflating later recipients'
+                // shares. Failed amounts stay in the contract and are routed to the project's balance with
+                // the leftover below.
+                unchecked {
+                    leftoverAmount -= payoutAmount;
+                }
+                if (!_sendPayoutToSplit({
                         directory: directory,
                         split: tierSplits[j],
                         token: token,
@@ -412,8 +415,10 @@ library JB721TiersHookLib {
                         groupId: groupId,
                         decimals: decimals
                     })) {
+                    // The payout failed — the funds are still in this contract. Add back to leftover so they
+                    // route to the project's balance after the loop.
                     unchecked {
-                        leftoverAmount -= payoutAmount;
+                        leftoverAmount += payoutAmount;
                     }
                 }
             }

package/src/structs/JBDeploy721TiersHookConfig.sol

@@ -11,7 +11,6 @@ import {IJB721TokenUriResolver} from "../interfaces/IJB721TokenUriResolver.sol";
 /// @custom:member tokenUriResolver The contract responsible for resolving the URI for each NFT.
 /// @custom:member contractUri The URI where this contract's metadata can be found.
 /// @custom:member tiersConfig The NFT tiers and pricing config to launch the hook with.
-/// @custom:member reserveBeneficiary The default reserved beneficiary for all tiers.
 /// @custom:member flags A set of boolean options to configure the hook with.
 // forge-lint: disable-next-line(pascal-case-struct)
 struct JBDeploy721TiersHookConfig {
@@ -21,6 +20,5 @@ struct JBDeploy721TiersHookConfig {
     IJB721TokenUriResolver tokenUriResolver;
     string contractUri;
     JB721InitTiersConfig tiersConfig;
-    address reserveBeneficiary;
     JB721TiersHookFlags flags;
 }

package/test/E2E/Pay_Mint_Redeem_E2E.t.sol

@@ -815,7 +815,6 @@ contract Test_TiersHook_E2E is TestBaseWorkflow {
             tiersConfig: JB721InitTiersConfig({
                 tiers: tierConfigs, currency: uint32(uint160(JBConstants.NATIVE_TOKEN)), decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,
@@ -908,7 +907,6 @@ contract Test_TiersHook_E2E is TestBaseWorkflow {
             tiersConfig: JB721InitTiersConfig({
                 tiers: tierConfigs, currency: uint32(uint160(JBConstants.NATIVE_TOKEN)), decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,

package/test/Fork.t.sol

@@ -272,7 +272,6 @@ contract Fork_721Hook_Test is Test {
                 currency: uint32(uint160(NATIVE_TOKEN)),
                 decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: flags
         });
 

package/test/audit/{CodexNemesis_CrossCurrencySplitNoPrices.t.sol → CrossCurrencySplitNoPrices.t.sol}

@@ -11,7 +11,7 @@ import {IJBRulesets} from "@bananapus/core-v6/src/interfaces/IJBRulesets.sol";
 import {IJBSplits} from "@bananapus/core-v6/src/interfaces/IJBSplits.sol";
 import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
 
-contract CodexNemesis_CrossCurrencySplitNoPrices is UnitTestSetup {
+contract CrossCurrencySplitNoPrices is UnitTestSetup {
     function test_crossCurrencySplit_withoutPrices_locksForwardedNativeFunds() public {
         JB721TiersHook noPricesOrigin = new JB721TiersHook(
             IJBDirectory(mockJBDirectory),

package/test/audit/SplitFailureRedistribution.t.sol

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+// forge-lint: disable-next-line(unaliased-plain-import)
+import "../utils/UnitTestSetup.sol";
+import {IJB721TiersHookStore} from "../../src/interfaces/IJB721TiersHookStore.sol";
+import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
+import {IJBSplits} from "@bananapus/core-v6/src/interfaces/IJBSplits.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+
+contract SplitFailureRedistribution is UnitTestSetup {
+    address internal alice = makeAddr("alice");
+    address internal bob = makeAddr("bob");
+
+    function test_failedEarlierSplit_overpaysLaterSplit() public {
+        ForTest_JB721TiersHook testHook = _initializeForTestHook(0);
+        IJB721TiersHookStore hookStore = testHook.STORE();
+
+        JB721TierConfig[] memory tierConfigs = new JB721TierConfig[](1);
+        tierConfigs[0].price = 1 ether;
+        tierConfigs[0].initialSupply = uint32(100);
+        tierConfigs[0].category = uint24(1);
+        tierConfigs[0].encodedIPFSUri = bytes32(uint256(0x1234));
+        tierConfigs[0].splitPercent = 1_000_000_000;
+
+        vm.prank(address(testHook));
+        uint256[] memory tierIds = hookStore.recordAddTiers(tierConfigs);
+
+        mockAndExpect(
+            address(mockJBDirectory),
+            abi.encodeWithSelector(IJBDirectory.isTerminalOf.selector, projectId, mockTerminalAddress),
+            abi.encode(true)
+        );
+
+        RevertOnReceive revertingBeneficiary = new RevertOnReceive();
+
+        JBSplit[] memory splits = new JBSplit[](2);
+        splits[0] = JBSplit({
+            percent: uint32(JBConstants.SPLITS_TOTAL_PERCENT / 2),
+            projectId: 0,
+            beneficiary: payable(address(revertingBeneficiary)),
+            preferAddToBalance: false,
+            lockedUntil: 0,
+            hook: IJBSplitHook(address(0))
+        });
+        splits[1] = JBSplit({
+            percent: uint32(JBConstants.SPLITS_TOTAL_PERCENT / 2),
+            projectId: 0,
+            beneficiary: payable(bob),
+            preferAddToBalance: false,
+            lockedUntil: 0,
+            hook: IJBSplitHook(address(0))
+        });
+
+        uint256 groupId = uint256(uint160(address(testHook))) | (uint256(tierIds[0]) << 160);
+        mockAndExpect(
+            mockJBSplits, abi.encodeWithSelector(IJBSplits.splitsOf.selector, projectId, 0, groupId), abi.encode(splits)
+        );
+
+        bytes memory payerMetadata = _buildPayMetadata(address(testHook), uint16(tierIds[0]));
+        bytes memory hookMetadata = abi.encode(_singleTierId(uint16(tierIds[0])), _singleAmount(1 ether));
+
+        JBAfterPayRecordedContext memory payContext = JBAfterPayRecordedContext({
+            payer: beneficiary,
+            projectId: projectId,
+            rulesetId: 0,
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 1 ether,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            forwardedAmount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 1 ether,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            weight: 10e18,
+            newlyIssuedTokenCount: 0,
+            beneficiary: beneficiary,
+            hookMetadata: hookMetadata,
+            payerMetadata: payerMetadata
+        });
+
+        uint256 bobBalanceBefore = bob.balance;
+
+        vm.deal(mockTerminalAddress, 1 ether);
+        vm.prank(mockTerminalAddress);
+        testHook.afterPayRecordedWith{value: 1 ether}(payContext);
+
+        assertEq(
+            bob.balance - bobBalanceBefore,
+            1 ether,
+            "later split receives the failed split's share instead of only its own allocation"
+        );
+    }
+
+    function _buildPayMetadata(address hookAddress, uint16 tierId) internal view returns (bytes memory) {
+        bytes[] memory data = new bytes[](1);
+        data[0] = abi.encode(false, _singleTierId(tierId));
+        bytes4[] memory ids = new bytes4[](1);
+        ids[0] = metadataHelper.getId("pay", hookAddress);
+        return metadataHelper.createMetadata(ids, data);
+    }
+
+    function _singleTierId(uint16 tierId) internal pure returns (uint16[] memory tierIds) {
+        tierIds = new uint16[](1);
+        tierIds[0] = tierId;
+    }
+
+    function _singleAmount(uint256 amount) internal pure returns (uint256[] memory amounts) {
+        amounts = new uint256[](1);
+        amounts[0] = amount;
+    }
+}
+
+contract RevertOnReceive {
+    receive() external payable {
+        revert("NO_ETH");
+    }
+}

package/test/fork/ERC20CashOutFork.t.sol

@@ -249,7 +249,6 @@ contract ERC20CashOutFork is Test {
             tokenUriResolver: IJB721TokenUriResolver(address(0)),
             contractUri: "ipfs://contract",
             tiersConfig: JB721InitTiersConfig({tiers: tierConfigs, currency: currency, decimals: 6}),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,

package/test/fork/ERC20TierSplitFork.t.sol

@@ -226,7 +226,6 @@ contract ERC20TierSplitFork is Test {
             tokenUriResolver: IJB721TokenUriResolver(address(0)),
             contractUri: "ipfs://contract",
             tiersConfig: JB721InitTiersConfig({tiers: tierConfigs, currency: currency, decimals: tokenDecimals}),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,
@@ -300,7 +299,6 @@ contract ERC20TierSplitFork is Test {
             tiersConfig: JB721InitTiersConfig({
                 tiers: tierConfigs, currency: uint32(uint160(JBConstants.NATIVE_TOKEN)), decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,

package/test/fork/IssueTokensForSplitsFork.t.sol

@@ -246,7 +246,6 @@ contract IssueTokensForSplitsFork is Test {
                 currency: uint32(uint160(NATIVE_TOKEN)),
                 decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: issueTokensForSplits,

package/test/regression/ProjectDeployerRulesets.t.sol

@@ -138,7 +138,6 @@ contract Test_ProjectDeployerRulesets is UnitTestSetup {
             tiersConfig: JB721InitTiersConfig({
                 tiers: tierConfigs, currency: uint32(uint160(JBConstants.NATIVE_TOKEN)), decimals: 18
             }),
-            reserveBeneficiary: reserveBeneficiary,
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,

package/test/unit/getters_constructor_Unit.t.sol

@@ -29,7 +29,6 @@ contract Test_Getters_Constructor_Unit is UnitTestSetup {
             tokenUriResolver: IJB721TokenUriResolver(mockTokenUriResolver),
             contractUri: contractUri,
             tiersConfig: JB721InitTiersConfig({tiers: tiers, currency: currency, decimals: decimals}),
-            reserveBeneficiary: address(0),
             flags: JB721TiersHookFlags({
                 preventOverspending: false,
                 issueTokensForSplits: false,