@bananapus/suckers-v6 0.0.73 → 0.0.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.73",
+  "version": "0.0.75",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.82",
-    "@bananapus/permission-ids-v6": "^0.0.30",
+    "@bananapus/core-v6": "^0.0.86",
+    "@bananapus/permission-ids-v6": "^0.0.31",
     "@chainlink/contracts-ccip": "1.6.4",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.2",
@@ -37,8 +37,8 @@
   },
   "devDependencies": {
     "@chainlink/local": "0.2.9",
+    "@sphinx-labs/plugins": "0.33.3",
     "@uniswap/v3-core": "1.0.1",
-    "@uniswap/v3-periphery": "1.4.4",
-    "@sphinx-labs/plugins": "0.33.3"
+    "@uniswap/v3-periphery": "1.4.4"
   }
 }

package/references/entrypoints.md

@@ -0,0 +1,111 @@
+# Sucker Entry Points
+
+Use this file when you already know the task is in `nana-suckers-v6` and need the concrete contract/function surface to open next.
+
+> V6 is testnet-only. Deployed sucker, registry, and deployer addresses live in `deploy-all-v6`'s address output, not here.
+
+## Purpose
+
+A sucker bridges a Juicebox project's token economy between two chains. Cashed-out positions are committed to a local outbox merkle tree, the root is relayed to the peer sucker on the remote chain, and beneficiaries prove inclusion against the inbox root to recreate their position on the destination chain. The `JBSucker` base owns the shared flow; chain-specific subclasses (`JBArbitrumSucker`, `JBOptimismSucker`, `JBCCIPSucker`, `JBBaseSucker`) own transport delivery and verification.
+
+## Contracts
+
+| Contract | Role |
+|----------|------|
+| `JBSucker` | Abstract base. Owns the prepare/relay/claim/token-mapping/deprecation/emergency flow and dual merkle (outbox/inbox) state. |
+| `JBArbitrumSucker` | Arbitrum bridge transport. |
+| `JBOptimismSucker` | OP Stack bridge transport. |
+| `JBCCIPSucker` | Chainlink CCIP transport. |
+| `JBBaseSucker` | Base/OP Stack transport. |
+| `JBSuckerRegistry` | Project-to-sucker inventory, deployer allowlist, shared `toRemote` fee, deprecation removal, cross-chain surplus/supply aggregation. |
+
+`IJBSucker` is the minimal interface; `IJBSuckerExtended` adds the deprecation, emergency-hatch, and retained-fee surface.
+
+## Structs
+
+### `JBTokenMapping` (argument to `mapToken` / `mapTokens`)
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `localToken` | `address` | The local token address. |
+| `minGas` | `uint32` | The minimum gas to use when bridging this token. |
+| `remoteToken` | `bytes32` | The remote token address (bytes32 for cross-VM compatibility). |
+
+### `JBClaim` (argument to `claim` / `exitThroughEmergencyHatch`)
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `token` | `address` | The local terminal token to claim. |
+| `leaf` | `JBLeaf` | The leaf to claim from (see below). |
+| `proof` | `bytes32[32]` | The merkle proof. Must be of length `JBSucker._TREE_DEPTH` (32). |
+
+### `JBLeaf` (the `leaf` field of `JBClaim`)
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `index` | `uint256` | The leaf's index in the tree. |
+| `beneficiary` | `bytes32` | The beneficiary (bytes32 for cross-VM compatibility). |
+| `projectTokenCount` | `uint256` | The number of project tokens to claim. |
+| `terminalTokenAmount` | `uint256` | The amount of terminal tokens to claim. |
+| `metadata` | `bytes32` | Opaque, caller-defined payload covered by the leaf hash. `bytes32(0)` when no extra context. |
+
+## Key functions
+
+### JBSucker — bridge flow (`IJBSucker`)
+
+| Function | What it does |
+|----------|--------------|
+| `prepare(uint256 projectTokenCount, bytes32 beneficiary, uint256 minTokensReclaimed, address token, bytes32 metadata)` | Cash out `projectTokenCount` project tokens into `token` and insert a leaf for `beneficiary` into the outbox tree for bridging. `minTokensReclaimed` bounds slippage; `metadata` is an opaque attribution payload carried in the leaf hash (`bytes32(0)` for a plain bridge). |
+| `toRemote(address token) payable` | Send the current outbox tree root and bridged assets for `token` to the remote peer through the chain-specific transport. `payable` to fund the transport message and the registry's `toRemoteFee`. |
+| `claim(JBClaim calldata claimData)` | Claim bridged project tokens for the leaf's beneficiary by proving inclusion against the inbox root. |
+| `claim(JBClaim[] calldata claims)` | Claim multiple leaves in one call. Each leaf is routed through an external `this.claim` sub-call, so one failing leaf emits `ClaimFailed` and is reverted in isolation while the rest of the batch proceeds; the failed leaf stays claimable later. |
+| `mapToken(JBTokenMapping calldata map) payable` | Map a single local token to a remote token for bridging. Mappings are immutable once the outbox tree has entries (can only be disabled, not remapped). Requires `MAP_SUCKER_TOKEN` permission (initial mappings are applied at deploy under `DEPLOY_SUCKERS`). |
+| `mapTokens(JBTokenMapping[] calldata maps) payable` | Map multiple local tokens to remote tokens in one call. |
+
+### JBSucker — deprecation & emergency (`IJBSuckerExtended`)
+
+| Function | What it does |
+|----------|--------------|
+| `setDeprecation(uint40 timestamp)` | Set or update the deprecation timestamp. Drives the `JBSuckerState` lifecycle: `ENABLED` → `DEPRECATION_PENDING` → `SENDING_DISABLED` → `DEPRECATED`. Requires `SET_SUCKER_DEPRECATION` permission. |
+| `enableEmergencyHatchFor(address[] calldata tokens)` | Open the emergency hatch for the given tokens, allowing direct claims without bridging when transport is unavailable. Requires `SUCKER_SAFETY` permission (project owner). |
+| `exitThroughEmergencyHatch(JBClaim calldata claimData)` | Claim a leaf directly through an open emergency hatch when bridging cannot complete. |
+| `claimRetainedToRemoteFee(address payable beneficiary)` | Withdraw ETH from a `toRemote` fee payment that previously failed and was retained for the caller. |
+| `claimRetainedTransportPaymentRefund(address payable beneficiary)` | Withdraw ETH from a transport-payment refund that previously failed and was retained for the caller. |
+
+### JBSucker — key views (`IJBSucker` / `IJBSuckerExtended`)
+
+| Function | What it does |
+|----------|--------------|
+| `state()` | Returns the current `JBSuckerState` (deprecation lifecycle stage). |
+| `peer()` | Returns the peer sucker address on the remote chain (bytes32). |
+| `peerChainId()` | Returns the remote peer chain ID. |
+| `projectId()` | Returns the local project ID this sucker serves. |
+| `isMapped(address token)` | Whether a token has been mapped for bridging. |
+| `remoteTokenFor(address token)` | The `JBRemoteToken` info a local token maps to. |
+| `inboxOf(address token)` | The inbox merkle tree root (`JBInboxTreeRoot`) for a token. |
+| `outboxOf(address token)` | The outbox merkle tree (`JBOutboxTree`) for a token. |
+| `amountToAddToBalanceOf(address token)` | Tokens received from bridging that are waiting to be added to the project's terminal balance. |
+| `executedLeafHashOf(address token, uint256 index)` | The committed leaf hash at `(token, index)`, or `bytes32(0)` if unexecuted. Beneficiary contracts re-derive this to authenticate a settlement that a front-runner's direct `claim` already executed. |
+| `peerChainTotalSupply()` | The last-known peer-chain total token supply (used by data hooks to compute effective cross-chain supply). |
+| `peerChainContextsOf()` | Per-context raw surplus and balance from the latest peer snapshot, with chain ID and freshness key. Un-valued (each context in its own currency/decimals). |
+| `retainedToRemoteFeeOf(address account)` | ETH owed to `account` from a failed `toRemote` fee payment. |
+| `retainedTransportPaymentRefundOf(address account)` | ETH owed to `account` from a failed transport-payment refund. |
+
+### JBSuckerRegistry (`IJBSuckerRegistry`)
+
+| Function | What it does |
+|----------|--------------|
+| `deploySuckersFor(uint256 projectId, bytes32 salt, JBSuckerDeployerConfig[] calldata configurations)` | Deploy one or more suckers for a project and apply each config's initial token mappings. Requires `DEPLOY_SUCKERS`. Returns the deployed sucker addresses. |
+| `removeDeprecatedSucker(uint256 projectId, address sucker)` | Remove a fully deprecated sucker from a project's inventory. |
+| `allowSuckerDeployer(address deployer)` / `allowSuckerDeployers(address[] calldata deployers)` | Add deployer(s) to the allowlist. Owner-only. |
+| `removeSuckerDeployer(address deployer)` | Remove a deployer from the allowlist. Owner-only. |
+| `setToRemoteFee(uint256 fee)` | Set the ETH fee (wei) paid into the fee project on each `toRemote` call. Reverts if `fee > MAX_TO_REMOTE_FEE`. Owner-only. |
+| `suckersOf(uint256 projectId)` | All active suckers for a project. |
+| `allSuckersOf(uint256 projectId)` | Every sucker ever registered for a project, including deprecated ones. |
+| `suckerPairsOf(uint256 projectId)` | The local/remote sucker pairs (`JBSuckersPair[]`) for a project. |
+| `isSuckerOf(uint256 projectId, address addr)` | Whether `addr` is a registry-deployed sucker for the project. |
+| `suckerDeployerIsAllowed(address deployer)` | Whether a deployer is on the allowlist. |
+| `remoteTotalSupplyOf(uint256 projectId)` | Combined peer-chain total supply across all remote chains (dedups same-peer suckers by freshest snapshot). |
+| `totalRemoteSurplusOf(uint256 projectId, uint256 currency, uint256 decimals)` | Combined peer-chain surplus valued into `currency`. Matching-currency contexts taken at par; missing cross-currency feed skips that sucker (conservative). |
+| `totalRemoteBalanceOf(uint256 projectId, uint256 currency, uint256 decimals)` | Combined peer-chain balance valued into `currency`, same valuation rules as above. |
+| `toRemoteFee()` / `MAX_TO_REMOTE_FEE()` | The current `toRemote` fee and its hardcoded ceiling. |

package/src/JBSucker.sol

@@ -143,6 +143,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @notice Thrown when `msg.value` is sent for an action that expects none.
     error JBSucker_UnexpectedMsgValue(uint256 value);
 
+    /// @notice Thrown when an ERC-20 terminal balance does not decrease by the amount added to the project balance.
+    error JBSucker_UnexpectedTokenBalance(address token, uint256 expectedBalance, uint256 actualBalance);
+
     /// @notice Thrown when a required beneficiary address is the zero address.
     error JBSucker_ZeroBeneficiary(bytes32 beneficiary);
 
@@ -648,42 +651,34 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @param maps A list of local and remote terminal token addresses to map, and minimum amount/gas limits for
     /// bridging them.
     function mapTokens(JBTokenMapping[] calldata maps) external payable override {
-        uint256 numberToDisable;
+        uint256 disableCandidates;
 
-        // Loop over the number of mappings and increase numberToDisable to correctly set transportPaymentValue.
-        // Note: if all mappings are enable-only (no disables), `numberToDisable` stays 0 and `transportPaymentValue`
-        // is set to 0 for each call. Any ETH sent with the transaction is refunded after the second loop.
+        // Count mappings that currently need a final outbox flush. This is an upper bound because duplicated disables
+        // in the same batch can become no-ops after the first one updates `numberOfClaimsSent`.
         for (uint256 h; h < maps.length;) {
             JBOutboxTree storage _outbox = _outboxOf[maps[h].localToken];
             if (maps[h].remoteToken == bytes32(0) && _outbox.numberOfClaimsSent != _outbox.tree.count) {
-                numberToDisable++;
+                ++disableCandidates;
             }
             unchecked {
                 ++h;
             }
         }
 
-        // Perform each token mapping.
+        // Split the attached value across disable candidates, then refund any value not actually used by a final
+        // outbox flush. Enable-only and duplicate/no-op disable entries do not consume transport payment.
+        uint256 transportPaymentValue = disableCandidates == 0 ? 0 : msg.value / disableCandidates;
+        uint256 transportPaymentSpent;
         for (uint256 i; i < maps.length;) {
-            _mapToken({map: maps[i], transportPaymentValue: numberToDisable > 0 ? msg.value / numberToDisable : 0});
+            transportPaymentSpent += _mapToken({map: maps[i], transportPaymentValue: transportPaymentValue});
             unchecked {
                 ++i;
             }
         }
 
-        // If no tokens were disabled, the full `msg.value` is unused — refund it.
-        if (numberToDisable == 0) {
-            if (msg.value > 0) {
-                _sendNativeTo({beneficiary: payable(_msgSender()), amount: msg.value});
-            }
-        } else {
-            // Refund any remainder from integer division so dust wei isn't stuck in the contract.
-            uint256 remainder = msg.value % numberToDisable;
-            if (remainder > 0) {
-                // Best-effort refund — don't revert if caller can't accept ETH.
-                (bool _ok,) = _msgSender().call{value: remainder}("");
-                _ok; // Silence unused-variable warning; failure is intentionally ignored.
-            }
+        // Return enable-only value, duplicate/no-op disable value, and integer-division dust to the caller.
+        if (msg.value > transportPaymentSpent) {
+            _sendNativeTo({beneficiary: payable(_msgSender()), amount: msg.value - transportPaymentSpent});
         }
     }
 
@@ -1123,8 +1118,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         });
 
         if (isErc20) {
-            // Sanity check: catches fee-on-transfer / non-conforming ERC-20s that move less than `amount`.
-            assert(IERC20(token).balanceOf(address(this)) == balanceBefore - amount);
+            // The terminal must pull exactly `amount`; fee-on-transfer or non-conforming tokens are unsupported.
+            uint256 expectedBalance = balanceBefore - amount;
+            uint256 actualBalance = IERC20(token).balanceOf(address(this));
+            if (actualBalance != expectedBalance) {
+                revert JBSucker_UnexpectedTokenBalance({
+                    token: token, expectedBalance: expectedBalance, actualBalance: actualBalance
+                });
+            }
         }
     }
 
@@ -1229,7 +1230,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @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.
-    function _mapToken(JBTokenMapping calldata map, uint256 transportPaymentValue) internal {
+    /// @return transportPaymentSpent The amount of transport payment used by a final outbox flush.
+    function _mapToken(
+        JBTokenMapping calldata map,
+        uint256 transportPaymentValue
+    )
+        internal
+        returns (uint256 transportPaymentSpent)
+    {
         address token = map.localToken;
         JBRemoteToken memory currentMapping = _remoteTokenFor[token];
 
@@ -1288,6 +1296,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             // _sendRoot uses the `currentMapping` parameter, not storage, so this is safe.
             _remoteTokenFor[token].enabled = false;
             _sendRoot({transportPayment: transportPaymentValue, token: token, remoteToken: currentMapping});
+            transportPaymentSpent = transportPaymentValue;
         }
 
         // Update the reverse reservation if an unused local token is being remapped to a new remote token.

package/src/libraries/JBRelayBeneficiary.sol

@@ -45,8 +45,19 @@ library JBRelayBeneficiary {
             return beneficiary;
         }
 
-        // Decode the relay beneficiary address.
-        address relayBeneficiary = abi.decode(data, (address));
+        // Load the first metadata word directly so malformed trailing bytes still fall back instead of reverting the
+        // surrounding payment.
+        uint256 relayBeneficiaryWord;
+        assembly ("memory-safe") {
+            relayBeneficiaryWord := mload(add(data, 32))
+        }
+        if (relayBeneficiaryWord > type(uint160).max) {
+            return beneficiary;
+        }
+
+        // The range guard above ensures the address cast cannot truncate.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        address relayBeneficiary = address(uint160(relayBeneficiaryWord));
         if (relayBeneficiary == address(0)) {
             return beneficiary;
         }