@bananapus/721-hook-v6 0.0.31 → 0.0.33

package/CHANGELOG.md

@@ -39,7 +39,7 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
 
 ## Indexer impact
 
-- New events: `AddToBalanceReverted`, `SetName`, `SetSymbol`, `SplitPayoutReverted`.
+- New events: `AddToBalanceReverted` (declared but no longer emitted -- replaced by `JB721TiersHookLib_SplitFallbackFailed` revert error), `SetName`, `SetSymbol`, `SplitPayoutReverted`.
 - Tier config decoding changed because `JB721TierConfig` is no longer v5-compatible.
 - Collection metadata can now change after deployment, so one-time indexing of `name` and `symbol` is no longer sufficient.
 
@@ -58,7 +58,7 @@ This file describes the verified change from `nana-721-hook-v5` to the current `
   - `pricingContext()`
   - `setMetadata(...)`
 - Added events
-  - `AddToBalanceReverted`
+  - `AddToBalanceReverted` (declared in interface but no longer emitted; the library now reverts with `JB721TiersHookLib_SplitFallbackFailed` instead)
   - `SetName`
   - `SetSymbol`
   - `SplitPayoutReverted`

package/RISKS.md

@@ -46,7 +46,7 @@ This file focuses on the tiered-NFT accounting, reserve-mint, and cash-out risks
 - **Split hook callbacks (`processSplitWith`).** During `afterPayRecordedWith` -> `_processPayment` -> `distributeAll`, the library calls `split.hook.processSplitWith{value}()` for each split with a hook. This executes arbitrary code. At callback time: NFTs already minted, `payCreditsOf` updated, `remainingSupply` decremented in the store. Reentering `afterPayRecordedWith` requires terminal authentication and processes as an independent payment. All split hook and terminal calls are wrapped in try-catch to prevent a single reverting recipient from bricking all payments to the project. For native token hooks, a revert returns false (ETH stays in the contract and routes to project balance). For ERC20 hooks, tokens are transferred before the callback; a revert still returns true because the tokens have already left the contract. Tested: `TestAuditGaps_Reentrancy` confirms reentrancy is blocked by terminal check.
 - **Split beneficiary ETH sends.** `_sendPayoutToSplit` uses `beneficiary.call{value: amount}("")`. If the beneficiary reverts, the function returns `false` and the failed amount is accumulated separately, then routed to the project's balance after the distribution loop via `addToBalanceOf`. Later split recipients receive only their proportional share, not the failed recipient's share. Does not revert the entire payment.
 - **Terminal `.pay()` / `.addToBalanceOf()` during split distribution.** For project-targeted splits, the library calls the target project's primary terminal via try-catch. A reverting terminal returns false, routing the funds to the project's balance instead. For ERC20 terminal calls, approval is reset to zero on failure to prevent dangling approvals. The target terminal could call back into the hook, but the hook's state is fully settled (supply, credits, mint state). Reentrancy through this path cannot double-mint or corrupt state.
-- **`afterCashOutRecordedWith` execution order.** Burns tokens via `_burn()` -> `_update()` -> `STORE.recordTransferForTier()` in a loop, then calls `STORE.recordBurn()`. ERC721 `_update` triggers the store's tier balance decrement. Burns go to `address(0)`, so no `onERC721Received` callback.
+- **`afterCashOutRecordedWith` execution order.** Burns tokens via `_burn()` -> `_update()` -> `STORE.tierTransferInfoOfTokenId()` in a loop, then calls `STORE.recordBurn()`. ERC721 `_update` triggers the store's tier balance decrement. Burns go to `address(0)`, so no `onERC721Received` callback.
 - **No `ReentrancyGuard`.** Protection relies on state ordering (all `STORE.record*` calls before external calls), terminal authentication checks, and try-catch wrapping of all external calls in `_sendPayoutToSplit`. `_mint()` uses the non-safe variant, avoiding `onERC721Received` callbacks during minting.
 
 ## 4. Gas/DoS Vectors

package/USER_JOURNEYS.md

@@ -81,6 +81,17 @@
 2. Keep collection-specific behavior in the downstream repo while leaving pay, reserve, and cash-out semantics in this repo.
 3. Audit hook-store interactions here first, then audit the downstream resolver or wrapper.
 
+## Journey 7: Mint NFTs To The Correct Beneficiary During Cross-Chain Payments
+
+**Starting state:** a sucker pays the project on behalf of a remote user via `payRemote`, and the 721 hook needs to mint NFTs and accrue credits to the real user instead of the sucker contract.
+
+**Success:** NFTs mint to and pay credits accrue to the real remote user.
+
+**Flow**
+1. The sucker calls `terminal.pay()` with itself as both payer and beneficiary, embedding the real user's address in the `JB_RELAY_BENEFICIARY` metadata key.
+2. `_mintAndUpdateCredits` detects that `payer == beneficiary` and finds relay-beneficiary metadata.
+3. All NFT minting and credit accounting uses the resolved relay beneficiary instead of the sucker address.
+
 ## Hand-Offs
 
 - Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the treasury, ruleset, and permission surfaces the hook plugs into.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "^0.0.17",
-    "@bananapus/core-v6": "^0.0.31",
+    "@bananapus/core-v6": "^0.0.34",
     "@bananapus/ownable-v6": "^0.0.17",
-    "@bananapus/permission-ids-v6": "^0.0.15",
+    "@bananapus/permission-ids-v6": "^0.0.17",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.0",
     "solady": "^0.1.8"

package/script/Deploy.s.sol

@@ -10,6 +10,8 @@ import {
 import {Sphinx} from "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script} from "forge-std/Script.sol";
 
+import {JB721CheckpointsDeployer} from "../src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "../src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JB721TiersHookDeployer} from "../src/JB721TiersHookDeployer.sol";
 import {JB721TiersHookProjectDeployer} from "../src/JB721TiersHookProjectDeployer.sol";
 import {JB721TiersHookStore} from "../src/JB721TiersHookStore.sol";
@@ -34,6 +36,8 @@ contract DeployScript is Script, Sphinx {
     bytes32 HOOK_STORE_SALT = "JB721TiersHookStoreV6_";
     // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 PROJECT_DEPLOYER_SALT = "JB721TiersHookProjectDeployerV6";
+    // forge-lint: disable-next-line(mixed-case-variable)
+    bytes32 CHECKPOINTS_DEPLOYER_SALT = "JB721CheckpointsDeployerV6";
 
     function configureSphinx() public override {
         sphinxConfig.projectName = "nana-721-hook-v6";
@@ -69,28 +73,58 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookStore store;
         {
             // Perform the check for the store.
-            (address _store, bool _storeIsDeployed) =
-                _isDeployed(HOOK_STORE_SALT, type(JB721TiersHookStore).creationCode, "");
+            (address _store, bool _storeIsDeployed) = _isDeployed({
+                salt: HOOK_STORE_SALT, creationCode: type(JB721TiersHookStore).creationCode, arguments: ""
+            });
 
             // Deploy it if it has not been deployed yet.
             store = !_storeIsDeployed ? new JB721TiersHookStore{salt: HOOK_STORE_SALT}() : JB721TiersHookStore(_store);
         }
 
+        JB721CheckpointsDeployer checkpointsDeployer;
+        {
+            // Perform the check for the deployer.
+            (address _deployer, bool _deployerIsDeployed) = _isDeployed({
+                salt: CHECKPOINTS_DEPLOYER_SALT,
+                creationCode: type(JB721CheckpointsDeployer).creationCode,
+                arguments: ""
+            });
+
+            // Deploy it if it has not been deployed yet.
+            checkpointsDeployer = !_deployerIsDeployed
+                ? new JB721CheckpointsDeployer{salt: CHECKPOINTS_DEPLOYER_SALT}()
+                : JB721CheckpointsDeployer(_deployer);
+        }
+
         JB721TiersHook hook;
         {
             // Perform the check for the registry.
-            (address _hook, bool _hookIsDeployed) = _isDeployed(
-                HOOK_SALT,
-                type(JB721TiersHook).creationCode,
-                abi.encode(
-                    core.directory, core.permissions, core.prices, core.rulesets, store, core.splits, TRUSTED_FORWARDER
+            (address _hook, bool _hookIsDeployed) = _isDeployed({
+                salt: HOOK_SALT,
+                creationCode: type(JB721TiersHook).creationCode,
+                arguments: abi.encode(
+                    core.directory,
+                    core.permissions,
+                    core.prices,
+                    core.rulesets,
+                    store,
+                    core.splits,
+                    checkpointsDeployer,
+                    TRUSTED_FORWARDER
                 )
-            );
+            });
 
             // Deploy it if it has not been deployed yet.
             hook = !_hookIsDeployed
                 ? new JB721TiersHook{salt: HOOK_SALT}(
-                    core.directory, core.permissions, core.prices, core.rulesets, store, core.splits, TRUSTED_FORWARDER
+                    core.directory,
+                    core.permissions,
+                    core.prices,
+                    core.rulesets,
+                    store,
+                    core.splits,
+                    IJB721CheckpointsDeployer(address(checkpointsDeployer)),
+                    TRUSTED_FORWARDER
                 )
                 : JB721TiersHook(_hook);
         }
@@ -98,11 +132,11 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookDeployer hookDeployer;
         {
             // Perform the check for the registry.
-            (address _hookDeployer, bool _hookDeployerIsDeployed) = _isDeployed(
-                HOOK_DEPLOYER_SALT,
-                type(JB721TiersHookDeployer).creationCode,
-                abi.encode(hook, store, registry.registry, TRUSTED_FORWARDER)
-            );
+            (address _hookDeployer, bool _hookDeployerIsDeployed) = _isDeployed({
+                salt: HOOK_DEPLOYER_SALT,
+                creationCode: type(JB721TiersHookDeployer).creationCode,
+                arguments: abi.encode(hook, store, registry.registry, TRUSTED_FORWARDER)
+            });
 
             hookDeployer = !_hookDeployerIsDeployed
                 ? new JB721TiersHookDeployer{salt: HOOK_DEPLOYER_SALT}(
@@ -114,11 +148,11 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookProjectDeployer projectDeployer;
         {
             // Perform the check for the registry.
-            (address _projectDeployer, bool _projectDeployerIsdeployed) = _isDeployed(
-                PROJECT_DEPLOYER_SALT,
-                type(JB721TiersHookProjectDeployer).creationCode,
-                abi.encode(core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER)
-            );
+            (address _projectDeployer, bool _projectDeployerIsdeployed) = _isDeployed({
+                salt: PROJECT_DEPLOYER_SALT,
+                creationCode: type(JB721TiersHookProjectDeployer).creationCode,
+                arguments: abi.encode(core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER)
+            });
 
             projectDeployer = !_projectDeployerIsdeployed
                 ? new JB721TiersHookProjectDeployer{salt: PROJECT_DEPLOYER_SALT}(

package/src/JB721Checkpoints.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+import {Votes} from "@openzeppelin/contracts/governance/utils/Votes.sol";
+import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
+
+/// @title JB721Checkpoints
+/// @notice Provides IVotes-compatible checkpointed voting power for a JB721TiersHook. Deployed as an EIP-1167 clone
+/// via JB721CheckpointsDeployer — one module per hook. The hook calls `onTransfer` on every NFT transfer to
+/// maintain accurate vote checkpoints.
+/// @dev EIP712 on clones: OZ stores name/version as immutables (accessible via DELEGATECALL). The storage cache
+/// (`_cachedThis`) is uninitialized on clones, so `domainSeparatorV4()` always rebuilds using the clone's
+/// `address(this)` — correct behavior, tiny gas overhead.
+contract JB721Checkpoints is Votes, IJB721Checkpoints {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JB721Checkpoints_AlreadyInitialized();
+    error JB721Checkpoints_Unauthorized();
+
+    //*********************************************************************//
+    // --------------------- private stored properties ------------------ //
+    //*********************************************************************//
+
+    /// @notice Whether this contract has been initialized.
+    bool private _initialized;
+
+    //*********************************************************************//
+    // ---------------------- public stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice The hook that this module tracks voting power for.
+    address public override HOOK;
+
+    /// @notice The store that holds tier and voting data for the hook's NFTs.
+    IJB721TiersHookStore public override STORE;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @dev Parameterless. The implementation contract is initialized in the constructor to prevent direct use.
+    /// Clones are initialized via `initialize()`.
+    constructor() EIP712("JB721Checkpoints", "1") {
+        _initialized = true;
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Initializes a cloned module with its hook and store references.
+    /// @dev Can only be called once. Called by the deployer after cloning.
+    /// @param hook The hook this module serves.
+    /// @param store The store that holds tier data for the hook's NFTs.
+    function initialize(address hook, IJB721TiersHookStore store) external override {
+        if (_initialized) revert JB721Checkpoints_AlreadyInitialized();
+        _initialized = true;
+        HOOK = hook;
+        STORE = store;
+    }
+
+    /// @notice Called by the hook after every NFT transfer to update checkpointed voting power.
+    /// @dev Only callable by the HOOK. Looks up the token's tier voting units from the store.
+    /// @param from The previous owner (address(0) on mint).
+    /// @param to The new owner (address(0) on burn).
+    /// @param tokenId The token ID being transferred.
+    function onTransfer(address from, address to, uint256 tokenId) external override {
+        if (msg.sender != HOOK) revert JB721Checkpoints_Unauthorized();
+
+        // Look up this token's tier to get its voting units.
+        uint256 votingUnits = STORE.tierOfTokenId({hook: HOOK, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
+
+        // Move checkpointed voting power from the previous owner to the new owner.
+        _transferVotingUnits({from: from, to: to, amount: votingUnits});
+    }
+
+    //*********************************************************************//
+    // ------------------------ internal functions ----------------------- //
+    //*********************************************************************//
+
+    /// @notice Returns the total voting units held by an account (across all tiers).
+    /// @dev Called by OZ Votes when re-delegating to compute the account's total voting units.
+    /// @param account The address to get the voting units of.
+    /// @return The total voting units the account holds.
+    function _getVotingUnits(address account) internal view override returns (uint256) {
+        return STORE.votingUnitsOf({hook: HOOK, account: account});
+    }
+}

package/src/JB721CheckpointsDeployer.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {LibClone} from "solady/src/utils/LibClone.sol";
+import {JB721Checkpoints} from "./JB721Checkpoints.sol";
+import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721CheckpointsDeployer} from "./interfaces/IJB721CheckpointsDeployer.sol";
+import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
+
+/// @title JB721CheckpointsDeployer
+/// @notice Deploys EIP-1167 clones of JB721Checkpoints for each JB721TiersHook instance.
+/// @dev The implementation is deployed once in the constructor. Each `deploy()` call clones it (~45k gas) and
+/// initializes the clone with the hook and store references.
+contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The checkpoint module implementation that clones delegate to.
+    address public immutable override IMPLEMENTATION;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    constructor() {
+        IMPLEMENTATION = address(new JB721Checkpoints());
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Deploys a new deterministic checkpoint clone for the given hook.
+    /// @dev Uses CREATE2 with the hook address as salt so the clone address is the same across chains.
+    /// @param hook The hook address the module will serve.
+    /// @param store The store that holds tier data for the hook's NFTs.
+    /// @return module The newly deployed and initialized checkpoint module.
+    function deploy(address hook, IJB721TiersHookStore store) external override returns (IJB721Checkpoints module) {
+        module = IJB721Checkpoints(
+            LibClone.cloneDeterministic({implementation: IMPLEMENTATION, salt: bytes32(uint256(uint160(hook)))})
+        );
+        module.initialize({hook: hook, store: store});
+    }
+}