@bananapus/suckers-v6 0.0.49 → 0.0.51

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Bananapus/nana-suckers-v6"
   },
   "files": [
-    "CHANGELOG.md",
     "foundry.lock",
     "foundry.toml",
     "references/",
@@ -30,7 +29,7 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.57",
+    "@bananapus/core-v6": "^0.0.59",
     "@bananapus/permission-ids-v6": "^0.0.26",
     "@chainlink/contracts-ccip": "1.6.4",
     "@chainlink/local": "0.2.7",

package/src/JBSucker.sol

@@ -294,12 +294,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// project tokens for the beneficiary, and deposits the terminal tokens into the project's local balance.
     /// @param claimData The terminal token, merkle tree leaf, and proof for the claim.
     function claim(JBClaim calldata claimData) public virtual override {
-        // Attempt to validate the proof against the inbox tree for the terminal token.
+        // Attempt to validate the proof against the inbox tree for the terminal token. The leaf hash includes
+        // `claimData.leaf.metadata` so the proof is only valid for the exact (amount, beneficiary, metadata) tuple the
+        // origin committed to.
         _validate({
             projectTokenCount: claimData.leaf.projectTokenCount,
             terminalToken: claimData.token,
             terminalTokenAmount: claimData.leaf.terminalTokenAmount,
             beneficiary: claimData.leaf.beneficiary,
+            metadata: claimData.leaf.metadata,
             index: claimData.leaf.index,
             leaves: claimData.proof
         });
@@ -310,6 +313,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectTokenCount: claimData.leaf.projectTokenCount,
             terminalTokenAmount: claimData.leaf.terminalTokenAmount,
             index: claimData.leaf.index,
+            metadata: claimData.leaf.metadata,
             caller: _msgSender()
         });
 
@@ -330,7 +334,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         uint256 _projectId = projectId();
 
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(_projectId), projectId: _projectId, permissionId: JBPermissionIds.SUCKER_SAFETY
+            account: _ownerOf(_projectId), projectId: _projectId, permissionId: JBPermissionIds.SUCKER_SAFETY
         });
 
         // Enable the emergency hatch for each token.
@@ -352,12 +356,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @param claimData The terminal token, merkle tree leaf, and proof for the claim.
     function exitThroughEmergencyHatch(JBClaim calldata claimData) external override {
         // Does all the needed validation to ensure that the claim is valid *and* that claiming through the emergency
-        // hatch is allowed.
+        // hatch is allowed. The leaf hash covers `metadata` so a remote-attribution leaf is only exitable if the
+        // emergency exiter knows the exact `metadata` value the origin committed to.
         _validateForEmergencyExit({
             projectTokenCount: claimData.leaf.projectTokenCount,
             terminalToken: claimData.token,
             terminalTokenAmount: claimData.leaf.terminalTokenAmount,
             beneficiary: claimData.leaf.beneficiary,
+            metadata: claimData.leaf.metadata,
             index: claimData.leaf.index,
             leaves: claimData.proof
         });
@@ -532,7 +538,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         uint256 projectTokenCount,
         bytes32 beneficiary,
         uint256 minTokensReclaimed,
-        address token
+        address token,
+        bytes32 metadata
     )
         external
         override
@@ -564,12 +571,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectToken: projectToken, count: projectTokenCount, token: token, minTokensReclaimed: minTokensReclaimed
         });
 
-        // Insert the item into the outbox tree for the terminal `token`.
+        // Insert the item into the outbox tree for the terminal `token`. The `metadata` field travels inside the leaf
+        // hash so receivers can read attribution context from a proven claim — the sucker protocol itself never
+        // inspects it.
         _insertIntoTree({
             projectTokenCount: projectTokenCount,
             token: token,
             terminalTokenAmount: terminalTokenAmount,
-            beneficiary: beneficiary
+            beneficiary: beneficiary,
+            metadata: metadata
         });
     }
 
@@ -586,9 +596,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         // The caller must be the project owner or have the `SET_SUCKER_DEPRECATION` permission from them.
         _requirePermissionFrom({
-            account: PROJECTS.ownerOf(_projectId),
-            projectId: _projectId,
-            permissionId: JBPermissionIds.SET_SUCKER_DEPRECATION
+            account: _ownerOf(_projectId), projectId: _projectId, permissionId: JBPermissionIds.SET_SUCKER_DEPRECATION
         });
 
         // This is the earliest time for when the sucker can be considered deprecated.
@@ -996,16 +1004,20 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         uint256 projectTokenCount,
         address token,
         uint256 terminalTokenAmount,
-        bytes32 beneficiary
+        bytes32 beneficiary,
+        bytes32 metadata
     )
         internal
     {
         // Guard against amounts that would overflow uint128 on SVM (INTEROP-5).
         if (terminalTokenAmount > type(uint128).max) revert JBSucker_AmountExceedsUint128(terminalTokenAmount);
         if (projectTokenCount > type(uint128).max) revert JBSucker_AmountExceedsUint128(projectTokenCount);
-        // Build a hash based on the token amounts and the beneficiary.
+        // Build a hash based on the token amounts, the beneficiary, and the attribution metadata.
         bytes32 hashed = _buildTreeHash({
-            projectTokenCount: projectTokenCount, terminalTokenAmount: terminalTokenAmount, beneficiary: beneficiary
+            projectTokenCount: projectTokenCount,
+            terminalTokenAmount: terminalTokenAmount,
+            beneficiary: beneficiary,
+            metadata: metadata
         });
 
         // Get the outbox in storage.
@@ -1023,6 +1035,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             root: _computeOutboxRoot(outbox.tree),
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
+            metadata: metadata,
             caller: _msgSender()
         });
     }
@@ -1064,7 +1077,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         // The registry can map during authorized deployment. Otherwise, require the project's mapping permission.
         _requirePermissionAllowingOverrideFrom({
-            account: PROJECTS.ownerOf(_projectId),
+            account: _ownerOf(_projectId),
             projectId: _projectId,
             permissionId: JBPermissionIds.MAP_SUCKER_TOKEN,
             alsoGrantAccessIf: _msgSender() == address(REGISTRY)
@@ -1170,7 +1183,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Record the balance before the cash out for the sanity check.
         uint256 balanceBefore = _balanceOf({token: token, addr: address(this)});
 
-        // Cash out the project tokens for terminal tokens.
+        // Cash out the project tokens for terminal tokens. Suckers are a transparent value-mover (the bridge
+        // accounting is the entirety of their function) — they're not a fee-paying entry point for any referrer,
+        // so `referralProjectId: 0` is correct.
         reclaimedAmount = terminal.cashOutTokensOf({
             holder: address(this),
             projectId: cachedProjectId,
@@ -1178,7 +1193,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             tokenToReclaim: token,
             minTokensReclaimed: minTokensReclaimed,
             beneficiary: payable(address(this)),
-            metadata: bytes("")
+            metadata: bytes(""),
+            referralProjectId: 0
         });
 
         // Sanity check to make sure we received the expected amount.
@@ -1289,6 +1305,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         address terminalToken,
         uint256 terminalTokenAmount,
         bytes32 beneficiary,
+        bytes32 metadata,
         uint256 index,
         bytes32[_TREE_DEPTH] calldata leaves
     )
@@ -1312,6 +1329,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
             beneficiary: beneficiary,
+            metadata: metadata,
             index: index,
             leaves: leaves
         });
@@ -1331,6 +1349,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         uint256 projectTokenCount,
         uint256 terminalTokenAmount,
         bytes32 beneficiary,
+        bytes32 metadata,
         uint256 index,
         bytes32[_TREE_DEPTH] calldata leaves
     )
@@ -1341,7 +1360,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Delegates to JBSuckerLib (via DELEGATECALL) to keep MerkleLib.branchRoot bytecode out of each sucker.
         bytes32 root = JBSuckerLib.computeBranchRoot({
             item: _buildTreeHash({
-                projectTokenCount: projectTokenCount, terminalTokenAmount: terminalTokenAmount, beneficiary: beneficiary
+                projectTokenCount: projectTokenCount,
+                terminalTokenAmount: terminalTokenAmount,
+                beneficiary: beneficiary,
+                metadata: metadata
             }),
             branch: leaves,
             index: index
@@ -1385,6 +1407,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         address terminalToken,
         uint256 terminalTokenAmount,
         bytes32 beneficiary,
+        bytes32 metadata,
         uint256 index,
         bytes32[_TREE_DEPTH] calldata leaves
     )
@@ -1435,6 +1458,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
             beneficiary: beneficiary,
+            metadata: metadata,
             index: index,
             leaves: leaves
         });
@@ -1482,24 +1506,27 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @param projectTokenCount The number of project tokens to cash out.
     /// @param terminalTokenAmount The amount of terminal tokens to reclaim from the cash out.
     /// @param beneficiary The beneficiary which will receive the project tokens (bytes32 for cross-VM compatibility).
+    /// @param metadata Opaque caller-defined attribution payload travelling inside the leaf hash.
     /// @return hash The keccak256 hash of the leaf data.
     function _buildTreeHash(
         uint256 projectTokenCount,
         uint256 terminalTokenAmount,
-        bytes32 beneficiary
+        bytes32 beneficiary,
+        bytes32 metadata
     )
         internal
         pure
         returns (bytes32 hash)
     {
-        // All three arguments are 32 bytes — hash from free memory to avoid abi.encode allocation overhead.
+        // All four arguments are 32 bytes — hash from free memory to avoid abi.encode allocation overhead.
         // forge-lint: disable-next-line(asm-keccak256)
         assembly {
             let ptr := mload(0x40)
             mstore(ptr, projectTokenCount)
             mstore(add(ptr, 0x20), terminalTokenAmount)
             mstore(add(ptr, 0x40), beneficiary)
-            hash := keccak256(ptr, 0x60)
+            mstore(add(ptr, 0x60), metadata)
+            hash := keccak256(ptr, 0x80)
         }
     }
 
@@ -1543,6 +1570,20 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         return ERC2771Context._msgSender();
     }
 
+    /// @notice Resolve the current owner of the project this sucker belongs to.
+    /// @dev `PROJECTS.ownerOf(...)` is the source of truth for "project owner" permission checks; we hit it from
+    /// every permission-gated entrypoint (`enableEmergencyHatchFor`, `setDeprecation`, `_mapToken`). Routing all
+    /// three through this internal helper emits the abi-encode + STATICCALL + return-decode sequence once in the
+    /// child contract's bytecode instead of inlining it at each call site, which is what keeps `JBSwapCCIPSucker`
+    /// under the EIP-170 limit after the leaf-`metadata` thread-through landed.
+    /// @param forProjectId The project ID to look up — always the sucker's own `projectId()`, but accepted as a
+    /// parameter so callers can pass the cached local they already computed (avoiding a redundant `projectId()`
+    /// call against the read-only registry).
+    /// @return owner The address currently registered as the project's ERC-721 holder.
+    function _ownerOf(uint256 forProjectId) internal view returns (address owner) {
+        return PROJECTS.ownerOf(forProjectId);
+    }
+
     /// @notice Retain a failed `toRemoteFee` payment for later caller refund.
     /// @param account The account that can reclaim the retained fee.
     /// @param amount The retained fee amount.

package/src/JBSuckerRegistry.sol

@@ -485,7 +485,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     /// @notice Deploy one or more cross-chain suckers for a project in a single transaction. Each sucker is created via
     /// its deployer, registered in this registry, and immediately configured with its token mappings. Multiple suckers
     /// targeting the same peer chain are allowed for bridge resilience. The caller must have `DEPLOY_SUCKERS`
-    /// permission, and this registry must hold `MAP_SUCKER_TOKEN` permission for the project.
+    /// permission, which also authorizes the initial token mappings in each deployment configuration.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param salt The salt used to deploy the contract. For the suckers to be peers, this must be the same value on
     /// each chain where suckers are deployed.

package/src/interfaces/IJBSucker.sol

@@ -30,6 +30,7 @@ interface IJBSucker is IERC165 {
         uint256 projectTokenCount,
         uint256 terminalTokenAmount,
         uint256 index,
+        bytes32 metadata,
         address caller
     );
 
@@ -50,6 +51,7 @@ interface IJBSucker is IERC165 {
         bytes32 root,
         uint256 projectTokenCount,
         uint256 terminalTokenAmount,
+        bytes32 metadata,
         address caller
     );
 
@@ -191,11 +193,16 @@ interface IJBSucker is IERC165 {
     /// @param beneficiary The beneficiary on the remote chain (bytes32 for cross-VM compatibility).
     /// @param minTokensReclaimed The minimum terminal tokens to receive from the cash out.
     /// @param token The terminal token to cash out into.
+    /// @param metadata Opaque caller-defined attribution payload included in the leaf hash. The sucker protocol does
+    /// not inspect this value — it's covered by the merkle root, so the destination contract that consumes the claim
+    /// can
+    /// trust it once the proof verifies. Pass `bytes32(0)` for an ordinary bridge with no attribution context.
     function prepare(
         uint256 projectTokenCount,
         bytes32 beneficiary,
         uint256 minTokensReclaimed,
-        address token
+        address token,
+        bytes32 metadata
     )
         external;
 

package/src/interfaces/IJBSuckerRegistry.sol

@@ -130,8 +130,8 @@ interface IJBSuckerRegistry {
     function allowSuckerDeployers(address[] calldata deployers) external;
 
     /// @notice Deploy one or more suckers for the specified project.
-    /// @dev This call also applies each configuration's token mappings on the deployed suckers. Projects using this
-    /// path need the registry to be able to satisfy the corresponding `MAP_SUCKER_TOKEN` checks.
+    /// @dev This call also applies each configuration's token mappings on the deployed suckers. `DEPLOY_SUCKERS`
+    /// authorizes those initial mappings; use `MAP_SUCKER_TOKEN` for post-deployment mapping changes.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param salt The salt used for deterministic deployment.
     /// @param configurations The deployer configs to use.

package/src/structs/JBLeaf.sol

@@ -6,9 +6,15 @@ pragma solidity ^0.8.0;
 /// @custom:member beneficiary The beneficiary of the leaf.
 /// @custom:member projectTokenCount The number of project tokens to claim.
 /// @custom:member terminalTokenAmount The amount of terminal tokens to claim.
+/// @custom:member metadata Opaque, caller-defined attribution payload that travels with the leaf inside the merkle
+/// root. Use cases include cross-chain referral split hooks tagging a leaf with `(originChainId, referralProjectId)`
+/// so the destination contract can settle the bridged value atomically. The sucker protocol itself never inspects
+/// this field — it's covered by the leaf hash, so receivers can trust the value once the merkle proof verifies.
+/// Pass `bytes32(0)` when no attribution context is needed.
 struct JBLeaf {
     uint256 index;
     bytes32 beneficiary;
     uint256 projectTokenCount;
     uint256 terminalTokenAmount;
+    bytes32 metadata;
 }

package/CHANGELOG.md

@@ -1,81 +0,0 @@
-# Changelog
-
-## Scope
-
-This file describes the verified change from `nana-suckers-v5` to the current `nana-suckers-v6` repo.
-
-## Current v6 surface
-
-- `JBSucker`
-- `JBSuckerRegistry`
-- `JBOptimismSucker`
-- `JBArbitrumSucker`
-- `JBBaseSucker`
-- `JBCCIPSucker`
-- `JBCeloSucker`
-- the deployers, structs, and interfaces under `src/`
-
-## 0.0.46 — Bump nana-core-v6 to 0.0.53
-
-`@bananapus/core-v6@0.0.53` ([nana-core-v6 PR #145](https://github.com/Bananapus/nana-core-v6/pull/145)) drops the `via_ir` requirement on `JBCashOutHookSpecsLib`, which lets this package consume the cross-project cashout work (`payAfterCashOutTokensOf` / `addToBalanceAfterCashOutTokensOf`) without needing `via_ir = true` in its own foundry profile.
-
-- No src changes — suckers doesn't reference `IJBFeeTerminal.FEE()` or any of the touched core surfaces.
-- All `JBRulesetMetadata` test literals patched to include `pauseCrossProjectFeeFreeInflows: false`.
-
-`package.json`: version `0.0.44 → 0.0.46` (skipping 0.0.45 because nothing shipped at that intermediate revision), core dep `^0.0.48 → ^0.0.53`.
-
-## Summary
-
-- Cross-chain identifiers are now modeled for a wider address space. The v6 repo uses `bytes32` where the v5 repo used EVM `address` assumptions.
-- Message handling is versioned instead of implicitly trusting an older fixed format.
-- The anti-spam and fee model changed materially. v5's per-token minimum-bridge assumptions were replaced by a registry-level `toRemoteFee` flow in v6.
-- The old manual add-to-balance mode is gone from the current repo.
-- Celo support is now part of the repo's first-class contract set.
-- The repo moved from the v5 `0.8.23` baseline to `0.8.28`.
-
-## Verified deltas
-
-- `IJBSucker.peer()` now returns `bytes32`.
-- `IJBSucker.prepare(...)` now takes a `bytes32 beneficiary`.
-- `Claimed` and `InsertToOutboxTree` changed their `beneficiary` field from `address` to `bytes32`.
-- The `Claimed` event no longer carries the old `autoAddedToBalance` boolean.
-- The public `ADD_TO_BALANCE_MODE()` surface and the manual mode path are gone from the interface.
-- `StaleRootRejected(...)` is a new event on the interface.
-
-## Breaking ABI changes
-
-- `JBRemoteToken.addr` changed from `address` to `bytes32`.
-- `JBTokenMapping.remoteToken` changed from `address` to `bytes32`.
-- `JBMessageRoot` gained `version` and changed `token` from `address` to `bytes32`.
-- `IJBSucker.peer()` changed return type.
-- `IJBSucker.prepare(...)` changed parameter type for `beneficiary`.
-- The manual add-to-balance mode surface was removed.
-
-## Indexer impact
-
-- `Claimed` and `InsertToOutboxTree` require schema changes because `beneficiary` is no longer an EVM address.
-- Remote token and peer identifiers should be stored as raw 32-byte values.
-- `StaleRootRejected` is new and can be used to monitor out-of-order or duplicate delivery attempts.
-
-## Migration notes
-
-- Treat every cross-chain identifier schema as migrated, including indexers and bridge metadata.
-- Rebuild integrations around the current fee and registry model. Old `minBridgeAmount` assumptions are stale.
-- Use the current v6 structs and events for ABI regeneration. This repo has too many widened fields for manual patching to be safe.
-
-## ABI appendix
-
-- Changed functions
-  - `peer() -> bytes32`
-  - `prepare(..., bytes32 beneficiary, ...)`
-- Changed events
-  - `Claimed`
-  - `InsertToOutboxTree`
-- Added events
-  - `StaleRootRejected`
-- Removed surface
-  - manual add-to-balance mode / `ADD_TO_BALANCE_MODE()`
-- Changed structs
-  - `JBRemoteToken`
-  - `JBTokenMapping`
-  - `JBMessageRoot`