@bananapus/721-hook-v6 0.0.33 → 0.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JB721TiersHook.sol

@@ -24,6 +24,7 @@ import {IJB721CheckpointsDeployer} from "./interfaces/IJB721CheckpointsDeployer.
 import {IJB721TiersHook} from "./interfaces/IJB721TiersHook.sol";
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./interfaces/IJB721TokenUriResolver.sol";
+import {JB721Constants} from "./libraries/JB721Constants.sol";
 import {JB721TiersHookLib} from "./libraries/JB721TiersHookLib.sol";
 import {JB721TiersRulesetMetadataResolver} from "./libraries/JB721TiersRulesetMetadataResolver.sol";
 import {JB721InitTiersConfig} from "./structs/JB721InitTiersConfig.sol";
@@ -201,40 +202,23 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     {
         hookSpecifications = new JBPayHookSpecification[](1);
 
-        // Calculate per-tier split amounts via the library.
-        (uint256 totalSplitAmount, bytes memory splitMetadata) = JB721TiersHookLib.calculateSplitAmounts({
-            store: STORE, hook: address(this), metadataIdTarget: METADATA_ID_TARGET, metadata: context.metadata
-        });
-
-        // Convert split amounts from tier pricing to payment token denomination (if currencies differ)
-        // and cap at the actual payment value so the terminal never forwards more than was paid.
-        if (totalSplitAmount != 0) {
-            (totalSplitAmount, splitMetadata) = JB721TiersHookLib.convertAndCapSplitAmounts({
-                totalSplitAmount: totalSplitAmount,
-                splitMetadata: splitMetadata,
-                packedPricingContext: _packedPricingContext,
-                prices: PRICES,
-                projectId: context.projectId,
-                amountCurrency: context.amount.currency,
-                amountDecimals: context.amount.decimals,
-                amountValue: 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,
-            amountValue: context.amount.value,
-            totalSplitAmount: totalSplitAmount,
+        // Compute split amounts, adjusted weight, and resolved beneficiary in a single library call.
+        uint256 totalSplitAmount;
+        bytes memory splitMetadata;
+        address beneficiary;
+        (weight, totalSplitAmount, splitMetadata, beneficiary) = JB721TiersHookLib.computeSplitsAndWeight({
             store: STORE,
-            hook: address(this)
+            metadataIdTarget: METADATA_ID_TARGET,
+            packedPricingContext: _packedPricingContext,
+            prices: PRICES,
+            context: context
         });
 
         hookSpecifications[0] = JBPayHookSpecification({
             hook: this,
             noop: false,
             amount: totalSplitAmount,
-            metadata: abi.encode(context.beneficiary, context.payer, splitMetadata)
+            metadata: abi.encode(beneficiary, context.payer, splitMetadata)
         });
     }
 
@@ -662,74 +646,27 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         // Keep a reference to the number of NFT credits the beneficiary already has.
         uint256 payCredits = payCreditsOf[beneficiary];
 
-        // Set the leftover amount as the initial value.
-        uint256 leftoverAmount = value;
-
-        // If the payer is the effective beneficiary, combine their NFT credits with the amount paid.
-        uint256 unusedPayCredits;
-        if (payer == beneficiary) {
-            leftoverAmount += payCredits;
-        } else {
-            // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
-            unusedPayCredits = payCredits;
-        }
-
-        // Keep a reference to the boolean indicating whether paying more than the price of the NFTs being minted
-        // is allowed. Defaults to the collection's flag.
-        bool allowOverspending = !STORE.flagsOf(address(this)).preventOverspending;
-
-        // Resolve the metadata.
-        (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
-            id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}), metadata: payerMetadata
+        // Compute the mint: combine credits, decode metadata, record mint, and check overspending.
+        (uint256[] memory tokenIds, uint16[] memory tierIdsToMint, uint256 newPayCredits) = JB721TiersHookLib.prepareMint({
+            store: STORE,
+            metadataIdTarget: METADATA_ID_TARGET,
+            value: value,
+            payer: payer,
+            beneficiary: beneficiary,
+            payCredits: payCredits,
+            payerMetadata: payerMetadata
         });
 
-        if (found) {
-            // Keep a reference to the IDs of the tier be to minted.
-            uint16[] memory tierIdsToMint;
-
-            // Keep a reference to the payer's flag indicating whether overspending is allowed.
-            bool payerAllowsOverspending;
-
-            // Decode the metadata.
-            (payerAllowsOverspending, tierIdsToMint) = abi.decode(metadata, (bool, uint16[]));
-
-            // Make sure overspending is allowed if requested.
-            if (allowOverspending && !payerAllowsOverspending) {
-                allowOverspending = false;
-            }
-
-            // Mint NFTs from the tiers as specified.
-            if (tierIdsToMint.length != 0) {
-                uint256[] memory tokenIds;
-                uint256 restrictedCost;
-                uint256 totalAmountPaid = leftoverAmount;
-
-                // Record the mints.
-                // slither-disable-next-line reentrancy-events,reentrancy-no-eth
-                (tokenIds, leftoverAmount, restrictedCost) =
-                    STORE.recordMint({amount: leftoverAmount, tierIds: tierIdsToMint, isOwnerMint: false});
-
-                // Enforce `cantBuyWithCredits`: only tiers explicitly configured as credit-restricted must be fully
-                // covered by fresh payment (not stored credits). Split-bearing tiers are not automatically restricted;
-                // deployers must set that flag in tier configuration when they need that invariant.
-                if (restrictedCost > value) revert JB721TiersHook_CantBuyWithCredits();
-
-                // Mint each token to the effective beneficiary.
-                _mintTokens({
-                    tokenIds: tokenIds,
-                    tierIds: tierIdsToMint,
-                    beneficiary: beneficiary,
-                    totalAmountPaid: totalAmountPaid
-                });
-            }
+        // Mint each token to the effective beneficiary.
+        if (tokenIds.length != 0) {
+            // totalAmountPaid is the full amount available before recordMint deducted tier prices.
+            uint256 totalAmountPaid = (payer == beneficiary) ? value + payCredits : value;
+            _mintTokens({
+                tokenIds: tokenIds, tierIds: tierIdsToMint, beneficiary: beneficiary, totalAmountPaid: totalAmountPaid
+            });
         }
 
-        // If overspending isn't allowed, revert.
-        if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
-
         // Update NFT credits if they changed.
-        uint256 newPayCredits = leftoverAmount + unusedPayCredits;
-
         if (newPayCredits != payCredits) {
             if (newPayCredits > payCredits) {
                 emit AddPayCredits({
@@ -747,6 +684,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 });
             }
 
+            // slither-disable-next-line reentrancy-no-eth
             payCreditsOf[beneficiary] = newPayCredits;
         }
     }

package/src/libraries/JB721Constants.sol

@@ -4,4 +4,10 @@ pragma solidity 0.8.28;
 /// @notice Global constants used across 721 hook contracts.
 library JB721Constants {
     uint16 public constant DISCOUNT_DENOMINATOR = 200;
+
+    /// @notice The metadata ID used to identify the 721 beneficiary entry in payment metadata.
+    /// @dev When a sucker pays on behalf of a remote user, the real user's address is embedded under this key
+    /// so NFTs mint to the correct recipient.
+    // forge-lint: disable-next-line(mixed-case-variable)
+    bytes4 public constant BENEFICIARY_METADATA_ID = bytes4(keccak256("JB_721_BENEFICIARY"));
 }

package/src/libraries/JB721TiersHookLib.sol

@@ -6,32 +6,50 @@ import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
 import {IJBSplits} from "@bananapus/core-v6/src/interfaces/IJBSplits.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
-import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
-import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {JBBeforePayRecordedContext} from "@bananapus/core-v6/src/structs/JBBeforePayRecordedContext.sol";
+import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
+import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
+import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
 
-import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
-
 import {IJB721TiersHookStore} from "../interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "../interfaces/IJB721TokenUriResolver.sol";
-import {JB721TierConfig} from "../structs/JB721TierConfig.sol";
+
 import {JB721Constants} from "./JB721Constants.sol";
 import {JBIpfsDecoder} from "./JBIpfsDecoder.sol";
 
+import {JB721TierConfig} from "../structs/JB721TierConfig.sol";
+
 /// @notice External library for JB721TiersHook operations extracted to stay within the EIP-170 contract size limit.
 /// @dev Handles tier adjustments, split calculations, price normalization, and split fund distribution.
 library JB721TiersHookLib {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JB721TiersHook_CantBuyWithCredits();
+    error JB721TiersHook_Overspending(uint256 leftoverAmount);
     error JB721TiersHookLib_NoTerminalForLeftover(uint256 projectId, address token, uint256 leftoverAmount);
     error JB721TiersHookLib_SplitFallbackFailed(uint256 projectId, address token, uint256 amount, bytes reason);
     error JB721TiersHookLib_TokenTransferAmountMismatch(uint256 expectedAmount, uint256 receivedAmount);
+
+    //*********************************************************************//
+    // ------------------------------- events ---------------------------- //
+    //*********************************************************************//
+
     event AddTier(uint256 indexed tierId, JB721TierConfig tier, address caller);
     event RemoveTier(uint256 indexed tierId, address caller);
+    event SetDiscountPercent(uint256 indexed tierId, uint256 discountPercent, address caller);
     event SplitPayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
 
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
     /// @notice Handles the full tier adjustment logic: removes tiers, adds tiers, emits events, and sets splits.
     /// @dev Called via DELEGATECALL from the hook, so events are emitted from the hook's address.
     /// @param store The 721 tiers hook store.
@@ -89,6 +107,137 @@ library JB721TiersHookLib {
         }
     }
 
+    /// @notice Pulls ERC-20 tokens from the terminal (if needed) and distributes forwarded funds to tier splits.
+    /// @dev For ERC-20 tokens, pulls from the terminal using the allowance it granted via _beforeTransferTo.
+    /// @param directory The directory to look up terminals.
+    /// @param splits The splits contract to read tier split groups from.
+    /// @param projectId The project ID of the hook.
+    /// @param hookAddress The hook address (for computing split group IDs).
+    /// @param token The token being distributed.
+    /// @param amount The total amount to distribute.
+    /// @param decimals The token decimals.
+    /// @param encodedSplitData The encoded per-tier breakdown from hookMetadata.
+    function distributeAll(
+        IJBDirectory directory,
+        IJBSplits splits,
+        uint256 projectId,
+        address hookAddress,
+        address token,
+        uint256 amount,
+        uint256 decimals,
+        bytes calldata encodedSplitData
+    )
+        external
+    {
+        // For ERC20 tokens, pull from terminal using the allowance it granted via _beforeTransferTo.
+        if (token != JBConstants.NATIVE_TOKEN) {
+            uint256 balanceBefore = IERC20(token).balanceOf(address(this));
+            SafeERC20.safeTransferFrom({token: IERC20(token), from: msg.sender, to: address(this), value: amount});
+            uint256 receivedAmount = IERC20(token).balanceOf(address(this)) - balanceBefore;
+            if (receivedAmount != amount) {
+                revert JB721TiersHookLib_TokenTransferAmountMismatch(amount, receivedAmount);
+            }
+        }
+
+        (uint16[] memory tierIds, uint256[] memory amounts) = abi.decode(encodedSplitData, (uint16[], uint256[]));
+
+        for (uint256 i; i < tierIds.length;) {
+            if (amounts[i] == 0) {
+                unchecked {
+                    ++i;
+                }
+                continue;
+            }
+            uint256 groupId = uint256(uint160(hookAddress)) | (uint256(tierIds[i]) << 160);
+            _distributeSingleSplit({
+                directory: directory,
+                splitsContract: splits,
+                projectId: projectId,
+                token: token,
+                groupId: groupId,
+                amount: amounts[i],
+                decimals: decimals
+            });
+
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice Prepares NFT minting data for a payment: combines credits, decodes metadata, records mint, and checks
+    /// overspending.
+    /// @dev Called via DELEGATECALL from the hook; uses address(this) as the hook address.
+    /// Reverts with JB721TiersHook_CantBuyWithCredits or JB721TiersHook_Overspending on failure.
+    /// @param store The 721 tiers hook store.
+    /// @param metadataIdTarget The metadata ID target for resolving pay metadata.
+    /// @param value The normalized payment value.
+    /// @param payer The address that initiated the payment.
+    /// @param beneficiary The address to mint NFTs to and track credits for.
+    /// @param payCredits The beneficiary's current pay credits balance.
+    /// @param payerMetadata The metadata provided by the payer.
+    /// @return tokenIds The token IDs minted (empty if none).
+    /// @return tierIdsToMint The tier IDs corresponding to each minted token (empty if none).
+    /// @return newPayCredits The beneficiary's updated pay credits balance.
+    function prepareMint(
+        IJB721TiersHookStore store,
+        address metadataIdTarget,
+        uint256 value,
+        address payer,
+        address beneficiary,
+        uint256 payCredits,
+        bytes calldata payerMetadata
+    )
+        external
+        returns (uint256[] memory tokenIds, uint16[] memory tierIdsToMint, uint256 newPayCredits)
+    {
+        // Resolve metadata first (minimal stack: only 3 return vars). Scope block frees temporaries.
+        bool payerDisallowsOverspending;
+        {
+            (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
+                id: JBMetadataResolver.getId({purpose: "pay", target: metadataIdTarget}), metadata: payerMetadata
+            });
+
+            if (found) {
+                bool payerAllowsOverspending;
+                (payerAllowsOverspending, tierIdsToMint) = abi.decode(metadata, (bool, uint16[]));
+                payerDisallowsOverspending = !payerAllowsOverspending;
+            }
+        }
+
+        // Set the leftover amount as the initial value.
+        uint256 leftoverAmount = value;
+
+        // If the payer is the effective beneficiary, combine their NFT credits with the amount paid.
+        // Reuse newPayCredits to hold unused credits (avoids an extra local variable).
+        if (payer == beneficiary) {
+            leftoverAmount += payCredits;
+        } else {
+            newPayCredits = payCredits;
+        }
+
+        // Determine whether overspending is allowed (collection flag AND payer preference).
+        bool allowOverspending = !store.flagsOf(address(this)).preventOverspending && !payerDisallowsOverspending;
+
+        // Record the mints.
+        if (tierIdsToMint.length != 0) {
+            uint256 restrictedCost;
+
+            // slither-disable-next-line reentrancy-events,reentrancy-no-eth
+            (tokenIds, leftoverAmount, restrictedCost) =
+                store.recordMint({amount: leftoverAmount, tierIds: tierIdsToMint, isOwnerMint: false});
+
+            // Credit-restricted tiers must be fully covered by fresh payment (not stored credits).
+            if (restrictedCost > value) revert JB721TiersHook_CantBuyWithCredits();
+        }
+
+        // If overspending isn't allowed, revert.
+        if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
+
+        // Compute the new pay credits balance: leftover + unused credits (held in newPayCredits).
+        newPayCredits = leftoverAmount + newPayCredits;
+    }
+
     /// @notice Records new tiers, emits events, and sets their split groups.
     /// @dev Used during initialization when tier configs are in memory.
     /// @param store The 721 tiers hook store.
@@ -128,6 +277,87 @@ library JB721TiersHookLib {
         });
     }
 
+    /// @notice Set the discount percent for a tier, emitting an event and recording it in the store.
+    /// @param store The 721 tiers hook store.
+    /// @param tierId The ID of the tier.
+    /// @param discountPercent The discount percent to set.
+    /// @param caller The msg.sender of the original call.
+    function setDiscountPercentOf(
+        IJB721TiersHookStore store,
+        uint256 tierId,
+        uint256 discountPercent,
+        address caller
+    )
+        external
+    {
+        emit SetDiscountPercent({tierId: tierId, discountPercent: discountPercent, caller: caller});
+        store.recordSetDiscountPercentOf({tierId: tierId, discountPercent: discountPercent});
+    }
+
+    //*********************************************************************//
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice Computes split amounts, weight adjustment, and resolved beneficiary for a payment.
+    /// @dev Called via DELEGATECALL from the hook; uses address(this) as the hook address.
+    /// @param store The 721 tiers hook store.
+    /// @param metadataIdTarget The metadata ID target for resolving pay metadata.
+    /// @param packedPricingContext The packed pricing context (currency, decimals).
+    /// @param prices The prices contract used for currency conversion.
+    /// @param context The full payment context.
+    /// @return weight The adjusted weight for token minting.
+    /// @return totalSplitAmount The total amount to forward for splits.
+    /// @return splitMetadata Encoded per-tier breakdown (tierIds, amounts).
+    /// @return beneficiary The resolved beneficiary address.
+    function computeSplitsAndWeight(
+        IJB721TiersHookStore store,
+        address metadataIdTarget,
+        uint256 packedPricingContext,
+        IJBPrices prices,
+        JBBeforePayRecordedContext calldata context
+    )
+        external
+        view
+        returns (uint256 weight, uint256 totalSplitAmount, bytes memory splitMetadata, address beneficiary)
+    {
+        // Calculate per-tier split amounts.
+        (totalSplitAmount, splitMetadata) = _calculateSplitAmounts({
+            store: store, hook: address(this), metadataIdTarget: metadataIdTarget, metadata: context.metadata
+        });
+
+        // Convert split amounts from tier pricing to payment token denomination (if currencies differ)
+        // and cap at the actual payment value so the terminal never forwards more than was paid.
+        if (totalSplitAmount != 0) {
+            (totalSplitAmount, splitMetadata) = _convertAndCapSplitAmounts({
+                totalSplitAmount: totalSplitAmount,
+                splitMetadata: splitMetadata,
+                packedPricingContext: packedPricingContext,
+                prices: prices,
+                context: context
+            });
+        }
+
+        // Adjust weight so the terminal mints tokens only for the amount that actually enters the project.
+        weight = _calculateWeight({
+            contextWeight: context.weight,
+            amountValue: context.amount.value,
+            totalSplitAmount: totalSplitAmount,
+            store: store,
+            hook: address(this)
+        });
+
+        // Resolve the effective beneficiary from payment metadata.
+        beneficiary = context.beneficiary;
+        {
+            (bool found, bytes memory data) =
+                JBMetadataResolver.getDataFor({id: JB721Constants.BENEFICIARY_METADATA_ID, metadata: context.metadata});
+            if (found && data.length >= 32) {
+                address metadataBeneficiary = abi.decode(data, (address));
+                if (metadataBeneficiary != address(0)) beneficiary = metadataBeneficiary;
+            }
+        }
+    }
+
     /// @notice Normalizes a payment value based on the packed pricing context.
     /// @param packedPricingContext The packed pricing context (currency, decimals).
     /// @param prices The prices contract used for currency conversion.
@@ -176,6 +406,40 @@ library JB721TiersHookLib {
         valid = true;
     }
 
+    /// @notice Resolves the token URI for a given NFT token ID.
+    /// @dev Extracted to the library to keep JBIpfsDecoder bytecode out of the hook contract (EIP-170 compliance).
+    /// @param store The 721 tiers hook store.
+    /// @param hook The hook address.
+    /// @param baseUri The base URI for IPFS-based token URIs.
+    /// @param tokenId The token ID to resolve the URI for.
+    /// @return The resolved token URI string.
+    function resolveTokenURI(
+        IJB721TiersHookStore store,
+        address hook,
+        string memory baseUri,
+        uint256 tokenId
+    )
+        external
+        view
+        returns (string memory)
+    {
+        // Get a reference to the `tokenUriResolver`.
+        IJB721TokenUriResolver resolver = store.tokenUriResolverOf(hook);
+
+        // If a `tokenUriResolver` is set, use it to resolve the token URI.
+        if (address(resolver) != address(0)) return resolver.tokenUriOf({nft: hook, tokenId: tokenId});
+
+        // Otherwise, return the token URI corresponding with the NFT's tier.
+        return
+            JBIpfsDecoder.decode({
+                baseUri: baseUri, hexString: store.encodedTierIPFSUriOf({hook: hook, tokenId: tokenId})
+            });
+    }
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
     /// @notice Calculates per-tier split amounts for a pay event.
     /// @param store The 721 tiers hook store.
     /// @param hook The hook address.
@@ -183,13 +447,13 @@ library JB721TiersHookLib {
     /// @param metadata The payer metadata.
     /// @return totalSplitAmount The total amount to forward for splits.
     /// @return hookMetadata Encoded per-tier breakdown (tierIds, amounts) for afterPay.
-    function calculateSplitAmounts(
+    function _calculateSplitAmounts(
         IJB721TiersHookStore store,
         address hook,
         address metadataIdTarget,
         bytes calldata metadata
     )
-        external
+        internal
         view
         returns (uint256 totalSplitAmount, bytes memory hookMetadata)
     {
@@ -256,14 +520,14 @@ library JB721TiersHookLib {
     /// @param store The 721 tiers hook store (to read flags).
     /// @param hook The hook address.
     /// @return weight The adjusted weight for token minting.
-    function calculateWeight(
+    function _calculateWeight(
         uint256 contextWeight,
         uint256 amountValue,
         uint256 totalSplitAmount,
         IJB721TiersHookStore store,
         address hook
     )
-        external
+        internal
         view
         returns (uint256 weight)
     {
@@ -281,28 +545,22 @@ library JB721TiersHookLib {
 
     /// @notice Converts split amounts from tier pricing to payment denomination (if currencies differ), then caps
     /// the total at the actual payment value — proportionally reducing per-tier amounts when the cap applies.
-    /// @dev Combines currency conversion and cap into one external call to keep hook bytecode under EIP-170.
+    /// @dev Combines currency conversion and cap into one call to keep hook bytecode under EIP-170.
     /// @param totalSplitAmount The total split amount in tier pricing denomination.
     /// @param splitMetadata The encoded per-tier breakdown (tierIds, amounts).
     /// @param packedPricingContext The packed pricing context (currency in bits 0-31, decimals in bits 32-39).
     /// @param prices The prices contract used for currency conversion.
-    /// @param projectId The project ID.
-    /// @param amountCurrency The payment amount currency.
-    /// @param amountDecimals The payment amount decimals.
-    /// @param amountValue The actual payment value (used as the cap).
+    /// @param context The full payment context (provides projectId, amount currency/decimals/value).
     /// @return convertedTotal The total split amount after conversion and capping.
     /// @return convertedMetadata The re-encoded per-tier breakdown with adjusted amounts.
-    function convertAndCapSplitAmounts(
+    function _convertAndCapSplitAmounts(
         uint256 totalSplitAmount,
         bytes memory splitMetadata,
         uint256 packedPricingContext,
         IJBPrices prices,
-        uint256 projectId,
-        uint256 amountCurrency,
-        uint256 amountDecimals,
-        uint256 amountValue
+        JBBeforePayRecordedContext calldata context
     )
-        external
+        internal
         view
         returns (uint256 convertedTotal, bytes memory convertedMetadata)
     {
@@ -316,7 +574,7 @@ library JB721TiersHookLib {
 
         // Convert each per-tier amount from the tier pricing currency to the payment currency.
         // forge-lint: disable-next-line(unsafe-typecast)
-        if (amountCurrency != uint256(uint32(packedPricingContext))) {
+        if (context.amount.currency != uint256(uint32(packedPricingContext))) {
             // No price oracle available — return 0 to skip the split rather than forwarding an unconverted
             // amount denominated in the wrong currency, which would over- or under-pay.
             if (address(prices) == address(0)) return (0, convertedMetadata);
@@ -325,11 +583,11 @@ library JB721TiersHookLib {
                 // Get the price ratio: how many payment-currency units per one tier-pricing-currency unit.
                 // forge-lint: disable-next-line(unsafe-typecast)
                 uint256 ratio = prices.pricePerUnitOf({
-                    projectId: projectId,
-                    pricingCurrency: amountCurrency,
+                    projectId: context.projectId,
+                    pricingCurrency: context.amount.currency,
                     // forge-lint: disable-next-line(unsafe-typecast)
                     unitCurrency: uint256(uint32(packedPricingContext)),
-                    decimals: amountDecimals
+                    decimals: context.amount.decimals
                 });
 
                 // The denominator scales each amount from tier-pricing decimals to payment-token decimals.
@@ -354,7 +612,7 @@ library JB721TiersHookLib {
                 // Re-encode with the converted amounts.
                 convertedMetadata = abi.encode(tierIds, amounts);
             }
-        } else if (amountDecimals != pricingDecimals) {
+        } else if (context.amount.decimals != pricingDecimals) {
             // Same currency but different decimal scales (e.g. pricing at 18 decimals, payment token at 6).
             // Without this branch, split amounts stay in pricing decimals while the cap comparison uses
             // payment decimals — causing orders-of-magnitude mis-scaling. This mirrors the same-currency
@@ -367,12 +625,12 @@ library JB721TiersHookLib {
             convertedTotal = 0;
             for (uint256 i; i < amounts.length;) {
                 // Scale each amount from pricing decimals to payment decimals.
-                if (amountDecimals > pricingDecimals) {
+                if (context.amount.decimals > pricingDecimals) {
                     // Payment has more decimals — multiply to add precision (e.g. 6→18: multiply by 10^12).
-                    amounts[i] = amounts[i] * (10 ** (amountDecimals - pricingDecimals));
+                    amounts[i] = amounts[i] * (10 ** (context.amount.decimals - pricingDecimals));
                 } else {
                     // Payment has fewer decimals — divide to remove precision (e.g. 18→6: divide by 10^12).
-                    amounts[i] = amounts[i] / (10 ** (pricingDecimals - amountDecimals));
+                    amounts[i] = amounts[i] / (10 ** (pricingDecimals - context.amount.decimals));
                 }
                 convertedTotal += amounts[i];
 
@@ -388,7 +646,7 @@ library JB721TiersHookLib {
         // Cap the total 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.
-        if (convertedTotal > amountValue) {
+        if (convertedTotal > context.amount.value) {
             // Proportionally reduce each per-tier amount to stay in sync with the capped total.
             if (convertedMetadata.length != 0) {
                 (uint16[] memory tierIds, uint256[] memory amounts) =
@@ -397,7 +655,7 @@ library JB721TiersHookLib {
                 convertedTotal = 0;
                 for (uint256 i; i < amounts.length;) {
                     // Scale down: amount * amountValue / originalTotal.
-                    amounts[i] = mulDiv({x: amounts[i], y: amountValue, denominator: uncappedTotal});
+                    amounts[i] = mulDiv({x: amounts[i], y: context.amount.value, denominator: uncappedTotal});
                     convertedTotal += amounts[i];
 
                     unchecked {
@@ -407,104 +665,14 @@ library JB721TiersHookLib {
                 convertedMetadata = abi.encode(tierIds, amounts);
             } else {
                 // Clamp the total to the payment value.
-                convertedTotal = amountValue;
+                convertedTotal = context.amount.value;
             }
         }
     }
 
-    /// @notice Sets split groups in JBSplits for tiers that have splits configured.
-    function _setSplitGroupsFor(
-        IJBSplits splits,
-        uint256 projectId,
-        address hookAddress,
-        JB721TierConfig[] memory tiersToAdd,
-        uint256[] memory tierIdsAdded
-    )
-        private
-    {
-        uint256 splitGroupCount;
-        for (uint256 i; i < tiersToAdd.length;) {
-            if (tiersToAdd[i].splits.length != 0) splitGroupCount++;
-
-            unchecked {
-                ++i;
-            }
-        }
-        if (splitGroupCount == 0) return;
-
-        JBSplitGroup[] memory splitGroups = new JBSplitGroup[](splitGroupCount);
-        uint256 groupIndex;
-        for (uint256 i; i < tiersToAdd.length;) {
-            if (tiersToAdd[i].splits.length != 0) {
-                splitGroups[groupIndex] = JBSplitGroup({
-                    groupId: uint256(uint160(hookAddress)) | (tierIdsAdded[i] << 160), splits: tiersToAdd[i].splits
-                });
-                groupIndex++;
-            }
-
-            unchecked {
-                ++i;
-            }
-        }
-        splits.setSplitGroupsOf({projectId: projectId, rulesetId: 0, splitGroups: splitGroups});
-    }
-
-    /// @notice Pulls ERC-20 tokens from the terminal (if needed) and distributes forwarded funds to tier splits.
-    /// @dev For ERC-20 tokens, pulls from the terminal using the allowance it granted via _beforeTransferTo.
-    /// @param directory The directory to look up terminals.
-    /// @param splits The splits contract to read tier split groups from.
-    /// @param projectId The project ID of the hook.
-    /// @param hookAddress The hook address (for computing split group IDs).
-    /// @param token The token being distributed.
-    /// @param amount The total amount to distribute.
-    /// @param encodedSplitData The encoded per-tier breakdown from hookMetadata.
-    function distributeAll(
-        IJBDirectory directory,
-        IJBSplits splits,
-        uint256 projectId,
-        address hookAddress,
-        address token,
-        uint256 amount,
-        uint256 decimals,
-        bytes calldata encodedSplitData
-    )
-        external
-    {
-        // For ERC20 tokens, pull from terminal using the allowance it granted via _beforeTransferTo.
-        if (token != JBConstants.NATIVE_TOKEN) {
-            uint256 balanceBefore = IERC20(token).balanceOf(address(this));
-            SafeERC20.safeTransferFrom({token: IERC20(token), from: msg.sender, to: address(this), value: amount});
-            uint256 receivedAmount = IERC20(token).balanceOf(address(this)) - balanceBefore;
-            if (receivedAmount != amount) {
-                revert JB721TiersHookLib_TokenTransferAmountMismatch(amount, receivedAmount);
-            }
-        }
-
-        (uint16[] memory tierIds, uint256[] memory amounts) = abi.decode(encodedSplitData, (uint16[], uint256[]));
-
-        for (uint256 i; i < tierIds.length;) {
-            if (amounts[i] == 0) {
-                unchecked {
-                    ++i;
-                }
-                continue;
-            }
-            uint256 groupId = uint256(uint160(hookAddress)) | (uint256(tierIds[i]) << 160);
-            _distributeSingleSplit({
-                directory: directory,
-                splitsContract: splits,
-                projectId: projectId,
-                token: token,
-                groupId: groupId,
-                amount: amounts[i],
-                decimals: decimals
-            });
-
-            unchecked {
-                ++i;
-            }
-        }
-    }
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
 
     /// @notice Distributes funds for a single tier's split group.
     /// @dev Edge case: if both `_sendPayoutToSplit` returns false (reverting hook/terminal/beneficiary) AND the
@@ -773,52 +941,40 @@ library JB721TiersHookLib {
         return false;
     }
 
-    /// @notice Resolves the token URI for a given NFT token ID.
-    /// @dev Extracted to the library to keep JBIpfsDecoder bytecode out of the hook contract (EIP-170 compliance).
-    /// @param store The 721 tiers hook store.
-    /// @param hook The hook address.
-    /// @param baseUri The base URI for IPFS-based token URIs.
-    /// @param tokenId The token ID to resolve the URI for.
-    /// @return The resolved token URI string.
-    function resolveTokenURI(
-        IJB721TiersHookStore store,
-        address hook,
-        string memory baseUri,
-        uint256 tokenId
+    /// @notice Sets split groups in JBSplits for tiers that have splits configured.
+    function _setSplitGroupsFor(
+        IJBSplits splits,
+        uint256 projectId,
+        address hookAddress,
+        JB721TierConfig[] memory tiersToAdd,
+        uint256[] memory tierIdsAdded
     )
-        external
-        view
-        returns (string memory)
+        private
     {
-        // Get a reference to the `tokenUriResolver`.
-        IJB721TokenUriResolver resolver = store.tokenUriResolverOf(hook);
-
-        // If a `tokenUriResolver` is set, use it to resolve the token URI.
-        if (address(resolver) != address(0)) return resolver.tokenUriOf({nft: hook, tokenId: tokenId});
+        uint256 splitGroupCount;
+        for (uint256 i; i < tiersToAdd.length;) {
+            if (tiersToAdd[i].splits.length != 0) splitGroupCount++;
 
-        // Otherwise, return the token URI corresponding with the NFT's tier.
-        return
-            JBIpfsDecoder.decode({
-                baseUri: baseUri, hexString: store.encodedTierIPFSUriOf({hook: hook, tokenId: tokenId})
-            });
-    }
+            unchecked {
+                ++i;
+            }
+        }
+        if (splitGroupCount == 0) return;
 
-    event SetDiscountPercent(uint256 indexed tierId, uint256 discountPercent, address caller);
+        JBSplitGroup[] memory splitGroups = new JBSplitGroup[](splitGroupCount);
+        uint256 groupIndex;
+        for (uint256 i; i < tiersToAdd.length;) {
+            if (tiersToAdd[i].splits.length != 0) {
+                splitGroups[groupIndex] = JBSplitGroup({
+                    groupId: uint256(uint160(hookAddress)) | (tierIdsAdded[i] << 160), splits: tiersToAdd[i].splits
+                });
+                groupIndex++;
+            }
 
-    /// @notice Set the discount percent for a tier, emitting an event and recording it in the store.
-    /// @param store The 721 tiers hook store.
-    /// @param tierId The ID of the tier.
-    /// @param discountPercent The discount percent to set.
-    /// @param caller The msg.sender of the original call.
-    function setDiscountPercentOf(
-        IJB721TiersHookStore store,
-        uint256 tierId,
-        uint256 discountPercent,
-        address caller
-    )
-        external
-    {
-        emit SetDiscountPercent({tierId: tierId, discountPercent: discountPercent, caller: caller});
-        store.recordSetDiscountPercentOf({tierId: tierId, discountPercent: discountPercent});
+            unchecked {
+                ++i;
+            }
+        }
+        splits.setSplitGroupsOf({projectId: projectId, rulesetId: 0, splitGroups: splitGroups});
     }
 }

package/test/unit/relayBeneficiary_Unit.t.sol

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+// forge-lint: disable-next-line(unaliased-plain-import)
+import "../utils/UnitTestSetup.sol";
+
+/// @notice Tests that the 721 hook resolves the relay beneficiary from payment metadata.
+contract Test_relayBeneficiary_Unit is UnitTestSetup {
+    /// @notice The metadata ID the 721 hook uses to look up the relay beneficiary.
+    /// Must match `_721_BENEFICIARY_METADATA_ID` in JB721TiersHook.
+    /// @notice Must match `BENEFICIARY_METADATA_ID` in JB721TiersHook.
+    bytes4 constant BENEFICIARY_METADATA_ID = bytes4(keccak256("JB_721_BENEFICIARY"));
+
+    address relayUser = makeAddr("relayUser");
+    address sucker = makeAddr("sucker");
+
+    function setUp() public override {
+        super.setUp();
+
+        // Mock directory: terminal is valid for all calls.
+        vm.mockCall(
+            address(mockJBDirectory),
+            abi.encodeWithSelector(IJBDirectory.isTerminalOf.selector, projectId, mockTerminalAddress),
+            abi.encode(true)
+        );
+    }
+
+    /// @notice When metadata contains a relay beneficiary, the spec should use that address (not context.beneficiary).
+    function test_beforePay_relayBeneficiary_usedInSpec() public {
+        JB721TiersHook tiersHook = _initHookDefaultTiers(3);
+
+        // Build metadata with tier selection + relay beneficiary.
+        uint16[] memory tierIdsToMint = new uint16[](1);
+        tierIdsToMint[0] = 1;
+
+        // Encode tier selection metadata (for the hook's own metadata ID).
+        bytes memory tierData = abi.encode(false, tierIdsToMint, new bytes[](0));
+
+        // Build metadata with two entries: hook tier data + relay beneficiary.
+        bytes4[] memory ids = new bytes4[](2);
+        bytes[] memory datas = new bytes[](2);
+
+        ids[0] = JBMetadataResolver.getId({purpose: "pay", target: address(tiersHook)});
+        datas[0] = tierData;
+        ids[1] = BENEFICIARY_METADATA_ID;
+        datas[1] = abi.encode(relayUser);
+
+        bytes memory metadata = metadataHelper.createMetadata(ids, datas);
+
+        // Build pay context with sucker as beneficiary (simulating cross-chain payment).
+        JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
+            terminal: mockTerminalAddress,
+            payer: sucker,
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 10,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            projectId: projectId,
+            rulesetId: block.timestamp,
+            beneficiary: sucker,
+            weight: 10e18,
+            reservedPercent: 5000,
+            metadata: metadata
+        });
+
+        (, JBPayHookSpecification[] memory specs) = tiersHook.beforePayRecordedWith(context);
+
+        // The spec's metadata should encode relayUser as the beneficiary, not sucker.
+        assertEq(specs.length, 1, "should return one spec");
+        (address specBeneficiary,,) = abi.decode(specs[0].metadata, (address, address, bytes));
+        assertEq(specBeneficiary, relayUser, "spec should use relay beneficiary, not context.beneficiary");
+    }
+
+    /// @notice When no relay metadata is present, the spec should use context.beneficiary as-is.
+    function test_beforePay_noRelayMetadata_usesContextBeneficiary() public {
+        JB721TiersHook tiersHook = _initHookDefaultTiers(3);
+
+        // Build metadata with only tier selection (no relay beneficiary).
+        uint16[] memory tierIdsToMint = new uint16[](1);
+        tierIdsToMint[0] = 1;
+        bytes memory tierData = abi.encode(false, tierIdsToMint, new bytes[](0));
+
+        bytes4[] memory ids = new bytes4[](1);
+        bytes[] memory datas = new bytes[](1);
+        ids[0] = JBMetadataResolver.getId({purpose: "pay", target: address(tiersHook)});
+        datas[0] = tierData;
+
+        bytes memory metadata = metadataHelper.createMetadata(ids, datas);
+
+        JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
+            terminal: mockTerminalAddress,
+            payer: makeAddr("payer"),
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 10,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            projectId: projectId,
+            rulesetId: block.timestamp,
+            beneficiary: beneficiary,
+            weight: 10e18,
+            reservedPercent: 5000,
+            metadata: metadata
+        });
+
+        (, JBPayHookSpecification[] memory specs) = tiersHook.beforePayRecordedWith(context);
+
+        assertEq(specs.length, 1, "should return one spec");
+        (address specBeneficiary,,) = abi.decode(specs[0].metadata, (address, address, bytes));
+        assertEq(specBeneficiary, beneficiary, "spec should use context.beneficiary when no relay metadata");
+    }
+
+    /// @notice When relay metadata is present but the address is zero, fall back to context.beneficiary.
+    function test_beforePay_relayBeneficiaryZero_fallsBackToContext() public {
+        JB721TiersHook tiersHook = _initHookDefaultTiers(3);
+
+        uint16[] memory tierIdsToMint = new uint16[](1);
+        tierIdsToMint[0] = 1;
+        bytes memory tierData = abi.encode(false, tierIdsToMint, new bytes[](0));
+
+        bytes4[] memory ids = new bytes4[](2);
+        bytes[] memory datas = new bytes[](2);
+        ids[0] = JBMetadataResolver.getId({purpose: "pay", target: address(tiersHook)});
+        datas[0] = tierData;
+        ids[1] = BENEFICIARY_METADATA_ID;
+        datas[1] = abi.encode(address(0));
+
+        bytes memory metadata = metadataHelper.createMetadata(ids, datas);
+
+        JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
+            terminal: mockTerminalAddress,
+            payer: sucker,
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 10,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            projectId: projectId,
+            rulesetId: block.timestamp,
+            beneficiary: beneficiary,
+            weight: 10e18,
+            reservedPercent: 5000,
+            metadata: metadata
+        });
+
+        (, JBPayHookSpecification[] memory specs) = tiersHook.beforePayRecordedWith(context);
+
+        (address specBeneficiary,,) = abi.decode(specs[0].metadata, (address, address, bytes));
+        assertEq(specBeneficiary, beneficiary, "zero relay address should fall back to context.beneficiary");
+    }
+
+    /// @notice When metadata is empty, use context.beneficiary.
+    function test_beforePay_emptyMetadata_usesContextBeneficiary() public {
+        JB721TiersHook tiersHook = _initHookDefaultTiers(3);
+
+        JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
+            terminal: mockTerminalAddress,
+            payer: makeAddr("payer"),
+            amount: JBTokenAmount({
+                token: JBConstants.NATIVE_TOKEN,
+                value: 10,
+                decimals: 18,
+                currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            }),
+            projectId: projectId,
+            rulesetId: block.timestamp,
+            beneficiary: beneficiary,
+            weight: 10e18,
+            reservedPercent: 5000,
+            metadata: ""
+        });
+
+        (, JBPayHookSpecification[] memory specs) = tiersHook.beforePayRecordedWith(context);
+
+        (address specBeneficiary,,) = abi.decode(specs[0].metadata, (address, address, bytes));
+        assertEq(specBeneficiary, beneficiary, "empty metadata should use context.beneficiary");
+    }
+}