@bananapus/suckers-v6 0.0.48 → 0.0.50

package/CHANGELOG.md

@@ -15,6 +15,41 @@ This file describes the verified change from `nana-suckers-v5` to the current `n
 - `JBCeloSucker`
 - the deployers, structs, and interfaces under `src/`
 
+## Unreleased — `JBLeaf.metadata` attribution field
+
+The merkle leaf now carries a fifth field: a `bytes32 metadata` payload that travels inside the leaf hash but is
+opaque to the sucker protocol itself.
+
+**What changed**
+
+- `JBLeaf` struct: new trailing `bytes32 metadata` field.
+- `IJBSucker.prepare`: new trailing `bytes32 metadata` parameter. The metadata is included in the leaf hash, so it's
+  covered by the merkle root — receivers can trust it once the claim's merkle proof verifies.
+- `_buildTreeHash` hashes 128 bytes (was 96): `keccak256(projectTokenCount || terminalTokenAmount || beneficiary || metadata)`.
+- `_insertIntoTree`, `_validate`, `_validateBranchRoot`, `_validateForEmergencyExit` all thread `metadata` through.
+- Events `InsertToOutboxTree` and `Claimed` carry the field so off-chain indexers can read it directly without
+  cracking the leaf.
+- SVM leaf encoding widens from 96 bytes to 128 bytes; the new 32-byte suffix is the `metadata` field. The
+  `_svmBuildTreeHash` interop test mirrors the layout exactly so EVM↔SVM hash equality is preserved.
+
+**Intended use**
+
+The original motivator is the cross-chain referral split hook (`nana-referral-split-hook-v6`): when a referrer
+on chain Y earns credit for fee-paying activity on chain X, the hook on X uses the fee project's sucker to
+bridge the entitled fee-project tokens. The leaf's `metadata` carries `(originChainId, referralProjectId)` so the
+sibling hook on chain Y can atomically claim, re-pay the fee project locally, and push to the local distributor
+for the right referrer — all under the merkle proof's authentication, no off-chain coordination needed.
+
+The field is generic: any future leaf consumer (NFT split hooks, buyback hooks, etc.) can use it for its own
+attribution scheme without further sucker changes. Pass `bytes32(0)` for ordinary bridges that don't need it.
+
+**Risk surface**
+
+Zero new trust paths. The bridge protocol stays leaf-in-leaf-out; we just put one more 32-byte field under the
+same root. Existing claim, emergency-exit, and root-relay flows behave identically when `metadata == bytes32(0)`.
+The leaf-hash domain changes (96 → 128 bytes), but since nothing is deployed yet there's no on-chain
+compatibility concern.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.54",
-    "@bananapus/permission-ids-v6": "^0.0.25",
+    "@bananapus/core-v6": "^0.0.59",
+    "@bananapus/permission-ids-v6": "^0.0.26",
     "@chainlink/contracts-ccip": "1.6.4",
     "@chainlink/local": "0.2.7",
     "@openzeppelin/contracts": "5.6.1",

package/src/JBArbitrumSucker.sol

@@ -255,12 +255,13 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
         // If the token is an ERC-20, bridge it to the peer.
         // If the amount is `0` then we do not need to bridge any ERC20.
         if (token != JBConstants.NATIVE_TOKEN && amount != 0) {
+            address gateway;
             uint256 tokenTransportCost;
             uint256 maxSubmissionCostERC20;
             {
                 // Get the exact calldata length the gateway will create for the retryable ticket.
                 // The Arbitrum Inbox validates maxSubmissionCost against this actual payload, not the user data.
-                address gateway = GATEWAYROUTER.getGateway(token);
+                gateway = GATEWAYROUTER.getGateway(token);
                 uint256 outboundCalldataLength =
                     IL1ArbitrumGateway(gateway)
                 .getOutboundCalldata({
@@ -299,6 +300,8 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
                 gasPriceBid: maxFeePerGas,
                 data: bytes(abi.encode(maxSubmissionCostERC20, bytes("")))
             });
+
+            SafeERC20.forceApprove({token: IERC20(token), spender: gateway, value: 0});
         } else {
             // Ensure we bridge enough for gas costs on L2 side
             if (transportPayment < callTransportCost) {

package/src/JBCeloSucker.sol

@@ -164,6 +164,8 @@ contract JBCeloSucker is JBOptimismSucker {
                 minGasLimit: remoteToken.minGas,
                 extraData: bytes("")
             });
+
+            SafeERC20.forceApprove({token: IERC20(bridgeToken), spender: address(OPBRIDGE), value: 0});
         }
 
         // Send the messenger message with nativeValue = 0.

package/src/JBOptimismSucker.sol

@@ -126,6 +126,8 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
                 minGasLimit: remoteToken.minGas,
                 extraData: bytes("")
             });
+
+            SafeERC20.forceApprove({token: IERC20(token), spender: address(OPBRIDGE), value: 0});
         } else {
             // Otherwise, the token is the native token, and the amount will be sent as `msg.value`.
             nativeValue = amount;

package/src/JBSucker.sol

@@ -83,6 +83,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     error JBSucker_NoRetainedToRemoteFee(address account);
     error JBSucker_NoRetainedTransportPaymentRefund(address account);
     error JBSucker_RefundFailed(address beneficiary, uint256 amount);
+    error JBSucker_RemoteTokenAlreadyMapped(bytes32 remoteToken, address localToken);
     error JBSucker_TokenAlreadyMapped(address localToken, bytes32 mappedTo);
     error JBSucker_TokenHasInvalidEmergencyHatchState(address token);
     error JBSucker_TokenNotMapped(address token);
@@ -175,6 +176,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @custom:param token The local terminal token to get the inbox for.
     mapping(address token => JBInboxTreeRoot root) internal _inboxOf;
 
+    /// @notice The local token that has reserved each remote token address in this sucker.
+    /// @dev Inbound roots are keyed by `root.token` on the destination chain. Within a single sucker, allowing two
+    /// local tokens to send roots to the same remote token would give them independent source nonces but one shared
+    /// destination inbox, causing stale rejections or root overwrites. Each sucker keeps its own reservation map, so
+    /// separate bridge lanes for the same asset pair can coexist.
+    /// @custom:param remoteToken The remote terminal token address encoded as bytes32.
+    mapping(bytes32 remoteToken => address localToken) internal _localTokenForRemoteToken;
+
     /// @notice The outbox merkle tree for a given token.
     /// @custom:param token The local terminal token to get the outbox for.
     mapping(address token => JBOutboxTree) internal _outboxOf;
@@ -285,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
         });
@@ -301,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()
         });
 
@@ -321,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.
@@ -343,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
         });
@@ -523,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
@@ -555,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
         });
     }
 
@@ -577,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.
@@ -987,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.
@@ -1014,6 +1035,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             root: _computeOutboxRoot(outbox.tree),
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
+            metadata: metadata,
             caller: _msgSender()
         });
     }
@@ -1031,6 +1053,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// after outbox activity, the same local funds could be claimed against two different remote tokens. A
     /// misconfigured mapping therefore requires deploying a new sucker. Re-enabling a previously disabled mapping
     /// (back to the same remote token) is supported.
+    /// @dev Remote tokens are also unique per local token within this sucker. The source side keeps separate
+    /// outboxes/nonces per local token, but the destination side stores roots under the remote token address. Sharing
+    /// one remote token across multiple local tokens in the same sucker would merge those inboxes on the destination
+    /// chain. Separate suckers can still map the same local/remote token pair, letting users choose a bridge lane.
     /// @param map The local and remote terminal token addresses to map, and minimum amount/gas limits for bridging
     /// them.
     /// @param transportPaymentValue The amount of `msg.value` to send for the token mapping.
@@ -1051,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)
@@ -1068,6 +1094,16 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             revert JBSucker_TokenAlreadyMapped({localToken: token, mappedTo: currentMapping.addr});
         }
 
+        // A remote token can back only one local token's outbox in this sucker. Otherwise two independent source
+        // nonces would race into the same destination inbox key (`root.token`), making one token's root stale or
+        // overwriting the other. Other suckers have separate inbox/outbox storage and are unaffected.
+        if (map.remoteToken != bytes32(0)) {
+            address mappedLocalToken = _localTokenForRemoteToken[map.remoteToken];
+            if (mappedLocalToken != address(0) && mappedLocalToken != token) {
+                revert JBSucker_RemoteTokenAlreadyMapped({remoteToken: map.remoteToken, localToken: mappedLocalToken});
+            }
+        }
+
         // No inbox guard needed here. Token remapping only affects the outbound (sending) path —
         // it changes where tokens get bridged TO. Existing inbox claims are resolved against the inbox merkle
         // tree keyed by the local token address. Changing the remote token doesn't invalidate those claims
@@ -1085,6 +1121,17 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             _sendRoot({transportPayment: transportPaymentValue, token: token, remoteToken: currentMapping});
         }
 
+        // Update the reverse reservation if an unused local token is being remapped to a new remote token.
+        if (
+            map.remoteToken != bytes32(0) && currentMapping.addr != bytes32(0) && currentMapping.addr != map.remoteToken
+                && _localTokenForRemoteToken[currentMapping.addr] == token
+        ) {
+            delete _localTokenForRemoteToken[currentMapping.addr];
+        }
+
+        bytes32 remoteToken = map.remoteToken == bytes32(0) ? currentMapping.addr : map.remoteToken;
+        if (remoteToken != bytes32(0)) _localTokenForRemoteToken[remoteToken] = token;
+
         // Update the token mapping.
         _remoteTokenFor[token] = JBRemoteToken({
             enabled: map.remoteToken != bytes32(0),
@@ -1092,7 +1139,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             minGas: map.minGas,
             // This is done so that a token can be disabled and then enabled again
             // while ensuring the remoteToken never changes (unless it hasn't been used yet)
-            addr: map.remoteToken == bytes32(0) ? currentMapping.addr : map.remoteToken
+            addr: remoteToken
         });
     }
 
@@ -1136,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,
@@ -1144,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.
@@ -1255,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
     )
@@ -1278,6 +1329,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
             beneficiary: beneficiary,
+            metadata: metadata,
             index: index,
             leaves: leaves
         });
@@ -1297,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
     )
@@ -1307,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
@@ -1351,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
     )
@@ -1401,6 +1458,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             projectTokenCount: projectTokenCount,
             terminalTokenAmount: terminalTokenAmount,
             beneficiary: beneficiary,
+            metadata: metadata,
             index: index,
             leaves: leaves
         });
@@ -1448,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)
         }
     }
 
@@ -1509,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.