@bananapus/suckers-v6 0.0.74 → 0.0.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.74",
+  "version": "0.0.76",
   "license": "MIT",
   "repository": {
     "type": "git",

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/JBPeerChainAdjustedAccountsLib.sol

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {JBSourceContext} from "../structs/JBSourceContext.sol";
+
+/// @notice Helpers for reading optional `IJBPeerChainAdjustedAccounts` return data.
+library JBPeerChainAdjustedAccountsLib {
+    /// @notice Decodes peer-chain adjusted accounting return data, falling back to no contribution if malformed.
+    /// @param data The raw return data from a `peerChainAdjustedAccountsOf` call.
+    /// @return supply The extra supply to include in `sourceTotalSupply`.
+    /// @return contexts The extra per-context surplus and balance to include in the snapshot, un-valued.
+    function decode(bytes memory data) internal pure returns (uint256 supply, JBSourceContext[] memory contexts) {
+        // `data` is a Solidity `bytes` value. In memory, its first word is the byte length, and the hook's ABI return
+        // payload begins one word later at `data + 32`.
+        //
+        // The payload for `(uint256, JBSourceContext[])` is:
+        //   word 0: supply
+        //   word 1: offset to the dynamic `contexts` array tail, relative to the payload start
+        //   tail word 0: contexts.length
+        //   tail words: each `JBSourceContext`, encoded as 4 ABI words.
+        //
+        // A valid return needs at least the two-word tuple head plus the array-length word. Anything shorter would
+        // make the reads below point outside the returned buffer, so the optional contribution is ignored.
+        if (data.length < 96) return (0, new JBSourceContext[](0));
+
+        // The tuple head is fixed-width, so read it directly instead of `abi.decode`:
+        // - `supply` is word 0 of the ABI payload.
+        // - `contextsOffset` is word 1 and points to the dynamic-array tail.
+        // Manual reads let malformed optional hooks fail soft instead of reverting the whole snapshot.
+        uint256 contextsOffset;
+        assembly ("memory-safe") {
+            // Skip the `bytes` length word and read payload word 0.
+            supply := mload(add(data, 32))
+            // Read payload word 1. The value is payload-relative, not memory-object-relative.
+            contextsOffset := mload(add(data, 64))
+        }
+
+        // The dynamic array tail must start after the two-word tuple head (`>= 64`), be ABI-word aligned, and leave
+        // room for its own length word. If any of these fail, `abi.decode` would revert; this helper treats the
+        // optional hook as absent.
+        if (contextsOffset < 64 || contextsOffset % 32 != 0 || contextsOffset > data.length - 32) {
+            return (0, new JBSourceContext[](0));
+        }
+
+        // `contextsOffset` was proven to leave room for the array length word, so this read is in-bounds. Add `32` to
+        // `data` first because offsets are relative to the payload start, not the `bytes` length word.
+        uint256 contextCount;
+        assembly ("memory-safe") {
+            contextCount := mload(add(add(data, 32), contextsOffset))
+        }
+
+        // Skip the array-length word to reach the first encoded `JBSourceContext`.
+        uint256 contextsStart = contextsOffset + 32;
+        // Each `JBSourceContext` is four ABI words: token, decimals, surplus, balance. This bounds check prevents both
+        // oversized allocation from a hostile length word and out-of-bounds reads in the loop.
+        if (contextCount > (data.length - contextsStart) / 128) return (0, new JBSourceContext[](0));
+
+        // Only allocate after proving the claimed array length fits inside the returned bytes.
+        contexts = new JBSourceContext[](contextCount);
+
+        for (uint256 i; i < contextCount; i++) {
+            // Move to the encoded struct for this index. The multiplication is safe because `contextCount` already
+            // proved every 128-byte struct fits in the buffer.
+            uint256 contextOffset = contextsStart + i * 128;
+            // Read narrowed fields as full words first. The ABI decoder would reject out-of-range values for
+            // `uint8`/`uint128`, so the manual decoder must check those ranges before casting.
+            bytes32 token;
+            uint256 decimals;
+            uint256 surplus;
+            uint256 contextBalance;
+
+            assembly ("memory-safe") {
+                // Point at the first word of the encoded `JBSourceContext`.
+                let contextPointer := add(add(data, 32), contextOffset)
+                // Struct word 0: source-local token, padded to bytes32.
+                token := mload(contextPointer)
+                // Struct word 1: decimal precision, encoded as a full ABI word.
+                decimals := mload(add(contextPointer, 32))
+                // Struct word 2: raw surplus in the context's own decimals.
+                surplus := mload(add(contextPointer, 64))
+                // Struct word 3: raw recorded balance in the context's own decimals.
+                contextBalance := mload(add(contextPointer, 96))
+            }
+
+            // Mirror ABI decoder type checks before narrowing. Returning `(0, [])` avoids silently truncating a
+            // malformed hook's values into smaller wire types.
+            if (decimals > type(uint8).max || surplus > type(uint128).max || contextBalance > type(uint128).max) {
+                return (0, new JBSourceContext[](0));
+            }
+
+            // Casting is safe because the guard above rejected larger values, but forge lint cannot infer that.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            uint8 checkedDecimals = uint8(decimals);
+            // Casting is safe for the same reason as `checkedDecimals`.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            uint128 checkedSurplus = uint128(surplus);
+            // Casting is safe for the same reason as `checkedDecimals`.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            uint128 checkedBalance = uint128(contextBalance);
+
+            // Store the checked values using the struct's actual wire types. At this point every memory read was
+            // inside the buffer and every narrowed cast has been proven safe.
+            contexts[i] = JBSourceContext({
+                token: token, decimals: checkedDecimals, surplus: checkedSurplus, balance: checkedBalance
+            });
+        }
+    }
+}

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;
         }

package/src/libraries/JBSuckerLib.sol

@@ -12,6 +12,7 @@ import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadat
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 
 import {IJBPeerChainAdjustedAccounts} from "../interfaces/IJBPeerChainAdjustedAccounts.sol";
+import {JBPeerChainAdjustedAccountsLib} from "./JBPeerChainAdjustedAccountsLib.sol";
 import {JBInboxTreeRoot} from "../structs/JBInboxTreeRoot.sol";
 import {JBMessageRoot} from "../structs/JBMessageRoot.sol";
 import {JBSourceContext} from "../structs/JBSourceContext.sol";
@@ -249,15 +250,13 @@ library JBSuckerLib {
         address dataHook = ruleset.dataHook();
         if (dataHook == address(0) || dataHook.code.length == 0) return (0, new JBSourceContext[](0));
 
-        // Ask the hook for any off-terminal supply and per-context surplus/balance. A non-supporting or broken hook is
-        // caught and ignored so the baseline snapshot still goes out.
-        try IJBPeerChainAdjustedAccounts(dataHook).peerChainAdjustedAccountsOf(projectId) returns (
-            uint256 supply, JBSourceContext[] memory contexts
-        ) {
-            return (supply, contexts);
-        } catch {
-            return (0, new JBSourceContext[](0));
-        }
+        // Ask the hook for any off-terminal supply and per-context surplus/balance. Non-supporting, broken, or
+        // malformed hooks are ignored so the baseline snapshot still goes out.
+        (bool hookCallSucceeded, bytes memory hookData) =
+            dataHook.staticcall(abi.encodeCall(IJBPeerChainAdjustedAccounts.peerChainAdjustedAccountsOf, (projectId)));
+        if (!hookCallSucceeded) return (0, new JBSourceContext[](0));
+
+        return JBPeerChainAdjustedAccountsLib.decode(hookData);
     }
 
     /// @notice Reads one accounting context's raw surplus and balance into a `JBSourceContext`, performing no price