@bananapus/suckers-v6 1.0.1 → 1.0.2

package/README.md

@@ -37,7 +37,7 @@ The main idea is not "bridge the token contract." The main idea is "bridge a Jui
 | Contract | Role |
 | --- | --- |
 | `JBSucker` | Base bridge logic for prepare, relay, accounting sync, claim, token mapping, and lifecycle controls. |
-| `JBSuckerRegistry` | Registry for per-project sucker deployments, deployer allowlists, and shared bridge fee settings. |
+| `JBSuckerRegistry` | Registry for per-project sucker deployments, deployer and owner-gated token-pair allowlists, and shared bridge fee settings. |
 | Chain-specific suckers | Transport-specific implementations for OP Stack, Arbitrum, CCIP, and related environments. |
 
 ## Mental model
@@ -66,6 +66,7 @@ That means every bridge path has two trust surfaces:
 - do not reason about suckers as if they were generic ERC-20 bridges
 - root ordering and message delivery semantics matter as much as proof format
 - token mapping is part of the economic invariant
+- native/native mappings and different-address local/remote token mappings must be approved by the registry owner for the specific `(localToken, remoteChainId, remoteToken)` route before a project can choose them; non-native same-address mappings and disabled mappings do not need owner approval
 - peer contexts are merged only when they share both currency and decimals; same-currency contexts with different decimals are kept separate and valued independently at read time, never summed across precisions — and this merge applies per source chain, since each chain's record is stored and folded on its own
 - accounting propagates as a gossip bundle: a sucker sends its own chain's record plus every peer-chain record the project knows (gathered through the registry), so one sync round from a hub propagates every chain's data to every spoke without a direct sucker between each pair
 - `syncAccountingData` pays no registry `toRemoteFee`, but bridge-specific transport costs still apply and duplicate bundles can still consume bridge/indexer resources

package/package.json

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

package/references/entrypoints.md

@@ -17,7 +17,7 @@ A sucker bridges a Juicebox project's token economy between two chains. Cashed-o
 | `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. |
+| `JBSuckerRegistry` | Project-to-sucker inventory, deployer allowlist, owner-gated token-pair 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.
 
@@ -81,7 +81,7 @@ The same `JBChainAccounting[] accounts` bundle is also carried by the root messa
 | `fromRemoteAccounting(JBAccountingSnapshot calldata snapshot)` | Authenticated receive path for an accounting-only gossip bundle. Stores the freshest record per source chain, without touching any token-local inbox root. |
 | `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`). |
+| `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`). Native/native mappings and different-address mappings must also be approved by the registry owner for this sucker's peer chain. |
 | `mapTokens(JBTokenMapping[] calldata maps) payable` | Map multiple local tokens to remote tokens in one call. |
 
 ### JBSucker — deprecation & emergency (`IJBSuckerExtended`)
@@ -125,6 +125,10 @@ The same `JBChainAccounting[] accounts` bundle is also carried by the root messa
 | `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. |
+| `allowTokenMapping(address localToken, uint256 remoteChainId, bytes32 remoteToken)` / `allowTokenMappings(address[] calldata localTokens, uint256[] calldata remoteChainIds, bytes32[] calldata remoteTokens)` | Add route-scoped approvals for native/native or different-address local/remote token mappings. Owner-only. |
+| `removeTokenMapping(address localToken, uint256 remoteChainId, bytes32 remoteToken)` / `removeTokenMappings(address[] calldata localTokens, uint256[] calldata remoteChainIds, bytes32[] calldata remoteTokens)` | Remove route-scoped token-mapping approvals. Owner-only. |
+| `requireTokenMappingAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken)` | Revert unless the mapping can be chosen. Disabled mappings and non-native same-address mappings pass directly; native/native and different-address mappings require route approval. |
+| `tokenMappingIsAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken)` | Stored owner approval for an owner-gated token route. |
 | `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. |

package/references/operations.md

@@ -2,7 +2,7 @@
 
 ## Configuration surface
 
-- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) is the first stop for deployer allowlists, shared fees, project inventory, and deprecation helpers.
+- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) is the first stop for deployer allowlists, owner-gated token-pair allowlists, shared fees, project inventory, and deprecation helpers.
 - Transport-specific deployers in `src/deployers/` are where chain-specific constants and bridge addresses live.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) is where deployment-time environment wiring belongs.
 
@@ -10,6 +10,7 @@
 
 - If you edit base sucker accounting, verify claim flow across at least one chain-specific implementation.
 - If you edit token mapping logic, re-check the registry and deployer assumptions that feed it.
+- If you edit owner-gated token mapping rules, verify native/native, different-address, non-native same-address, disabled, deploy-time, and route-scoped cases.
 - If you edit token mapping semantics, verify that remapping is still impossible once outbox activity has made economic equivalence depend on permanence.
 - If you edit deprecation or emergency paths, verify the intended operator workflow still works end to end.
 - If you edit snapshot or claim-boundary logic, verify `numberOfClaimsSent`, peer snapshots, `syncAccountingData`, and emergency exit behavior together.
@@ -18,6 +19,7 @@
 ## Common failure modes
 
 - Cross-chain issue is blamed on transport when the root or token mapping was wrong before message delivery.
+- A token-pair approval is assumed to be global when it is actually scoped to one `(localToken, remoteChainId, remoteToken)` route.
 - Registry configuration drifts from what a deployer or external operator expects.
 - Emergency hatches or deprecation paths are stale because nobody exercises them until stress conditions arrive.
 

package/references/runtime.md

@@ -3,7 +3,7 @@
 ## Core roles
 
 - [`src/JBSucker.sol`](../src/JBSucker.sol) owns the shared prepare, relay, claim, token-mapping, and lifecycle logic.
-- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) owns project-to-sucker inventory, deployer allowlists, and shared remote-fee settings.
+- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) owns project-to-sucker inventory, deployer allowlists, owner-gated token-pair allowlists, and shared remote-fee settings.
 - Chain-specific sucker contracts such as [`src/JBArbitrumSucker.sol`](../src/JBArbitrumSucker.sol), [`src/JBOptimismSucker.sol`](../src/JBOptimismSucker.sol), [`src/JBCCIPSucker.sol`](../src/JBCCIPSucker.sol), and [`src/JBCeloSucker.sol`](../src/JBCeloSucker.sol) own transport-specific delivery and verification.
 - Matching deployers under `src/deployers/` own clone and transport configuration.
 
@@ -17,7 +17,7 @@
 
 ## High-risk areas
 
-- Token mapping: mapping mistakes break economic equivalence, not just UX.
+- Token mapping: mapping mistakes break economic equivalence, not just UX. Native/native and different-address mappings require route-scoped registry-owner approval before a project can choose them.
 - Root ordering and replay protection: message sequencing is part of correctness.
 - Emergency and deprecation paths: these are operational safety surfaces that must remain reliable.
 - Shared accounting vs transport logic: many incidents stem from confusing these layers.

package/src/JBSucker.sol

@@ -1307,6 +1307,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         returns (uint256 transportPaymentSpent)
     {
         address token = map.localToken;
+        bytes32 remoteToken = map.remoteToken;
         JBRemoteToken memory currentMapping = _remoteTokenFor[token];
 
         // Once the emergency hatch for a token is enabled it can't be disabled.
@@ -1328,12 +1329,15 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             alsoGrantAccessIf: _msgSender() == address(REGISTRY)
         });
 
+        // The registry owner gates mappings that assert economic equivalence across distinct chain assets.
+        REGISTRY.requireTokenMappingAllowed({localToken: token, remoteChainId: peerChainId(), remoteToken: remoteToken});
+
         // Make sure that the token does not get remapped to another remote token.
         // As this would cause the funds for this token to be double spendable on the other side.
         // It should not be possible to cause any issues even without this check
         // a bridge *should* never accept such a request. This is mostly a sanity check.
         if (
-            currentMapping.addr != bytes32(0) && currentMapping.addr != map.remoteToken && map.remoteToken != bytes32(0)
+            currentMapping.addr != bytes32(0) && currentMapping.addr != remoteToken && remoteToken != bytes32(0)
                 && _outboxOf[token].tree.count != 0
         ) {
             revert JBSucker_TokenAlreadyMapped({localToken: token, mappedTo: currentMapping.addr});
@@ -1342,10 +1346,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // 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 (remoteToken != bytes32(0)) {
+            address mappedLocalToken = _localTokenForRemoteToken[remoteToken];
             if (mappedLocalToken != address(0) && mappedLocalToken != token) {
-                revert JBSucker_RemoteTokenAlreadyMapped({remoteToken: map.remoteToken, localToken: mappedLocalToken});
+                revert JBSucker_RemoteTokenAlreadyMapped({remoteToken: remoteToken, localToken: mappedLocalToken});
             }
         }
 
@@ -1359,7 +1363,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // created and the mapping cannot be changed to a different remote token. If tokens are stuck in this state
         // (e.g., the bridge is non-functional), the project owner can call `enableEmergencyHatchFor` to allow
         // local withdrawals via `exitThroughEmergencyHatch`.
-        if (map.remoteToken == bytes32(0) && _outboxOf[token].numberOfClaimsSent != _outboxOf[token].tree.count) {
+        if (remoteToken == bytes32(0) && _outboxOf[token].numberOfClaimsSent != _outboxOf[token].tree.count) {
             // Disable before external call to prevent reentrancy via prepare().
             // _sendRoot uses the `currentMapping` parameter, not storage, so this is safe.
             _remoteTokenFor[token].enabled = false;
@@ -1369,13 +1373,13 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         // 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
+            remoteToken != bytes32(0) && currentMapping.addr != bytes32(0) && currentMapping.addr != remoteToken
                 && _localTokenForRemoteToken[currentMapping.addr] == token
         ) {
             delete _localTokenForRemoteToken[currentMapping.addr];
         }
 
-        bytes32 remoteToken = map.remoteToken == bytes32(0) ? currentMapping.addr : map.remoteToken;
+        remoteToken = remoteToken == bytes32(0) ? currentMapping.addr : remoteToken;
         if (remoteToken != bytes32(0)) _localTokenForRemoteToken[remoteToken] = token;
 
         // Update the token mapping.
@@ -2022,17 +2026,18 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @notice Allow sucker implementations to add/override mapping rules to suit their specific needs.
     /// @param map The token mapping to validate.
     function _validateTokenMapping(JBTokenMapping calldata map) internal pure virtual {
-        bool isNative = map.localToken == JBConstants.NATIVE_TOKEN;
-
         // If the token being mapped is the native token, the `remoteToken` must also be the native token.
         // The native token can also be mapped to the 0 address, which is used to disable native token bridging.
-        if (isNative && map.remoteToken != _toBytes32(JBConstants.NATIVE_TOKEN) && map.remoteToken != bytes32(0)) {
-            revert JBSucker_InvalidNativeRemoteAddress({remoteToken: map.remoteToken});
+        if (map.localToken == JBConstants.NATIVE_TOKEN) {
+            if (map.remoteToken != _toBytes32(JBConstants.NATIVE_TOKEN) && map.remoteToken != bytes32(0)) {
+                revert JBSucker_InvalidNativeRemoteAddress({remoteToken: map.remoteToken});
+            }
+            return;
         }
 
         // Enforce a reasonable minimum gas limit for bridging. A minimum which is too low could lead to the loss of
         // funds.
-        if (map.minGas < MESSENGER_ERC20_MIN_GAS_LIMIT && !isNative) {
+        if (map.minGas < MESSENGER_ERC20_MIN_GAS_LIMIT) {
             revert JBSucker_BelowMinGas({minGas: map.minGas, minGasLimit: MESSENGER_ERC20_MIN_GAS_LIMIT});
         }
     }

package/src/JBSuckerRegistry.sol

@@ -6,6 +6,7 @@ import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
 import {IJBPrices} from "@bananapus/core-v6/src/interfaces/IJBPrices.sol";
 import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBFixedPointNumber} from "@bananapus/core-v6/src/libraries/JBFixedPointNumber.sol";
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
@@ -14,13 +15,13 @@ import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {EnumerableMap} from "@openzeppelin/contracts/utils/structs/EnumerableMap.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
 
-import {JBChainAccounting} from "./structs/JBChainAccounting.sol";
-import {JBPeerChainContext} from "./structs/JBPeerChainContext.sol";
-import {JBPeerChainValue} from "./structs/JBPeerChainValue.sol";
 import {JBSuckerState} from "./enums/JBSuckerState.sol";
 import {IJBSucker} from "./interfaces/IJBSucker.sol";
 import {IJBSuckerDeployer} from "./interfaces/IJBSuckerDeployer.sol";
 import {IJBSuckerRegistry} from "./interfaces/IJBSuckerRegistry.sol";
+import {JBChainAccounting} from "./structs/JBChainAccounting.sol";
+import {JBPeerChainContext} from "./structs/JBPeerChainContext.sol";
+import {JBPeerChainValue} from "./structs/JBPeerChainValue.sol";
 import {JBSuckerDeployerConfig} from "./structs/JBSuckerDeployerConfig.sol";
 import {JBSuckersPair} from "./structs/JBSuckersPair.sol";
 import {PeerAccountScratch} from "./structs/PeerAccountScratch.sol";
@@ -50,6 +51,14 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     /// @notice Thrown when a sucker is being removed from active listings but is not deprecated.
     error JBSuckerRegistry_SuckerIsNotDeprecated(address sucker, JBSuckerState suckerState);
 
+    /// @notice Thrown when token mapping arrays have different lengths.
+    error JBSuckerRegistry_TokenMappingLengthMismatch(
+        uint256 localTokenCount, uint256 remoteChainIdCount, uint256 remoteTokenCount
+    );
+
+    /// @notice Thrown when a project chooses an owner-gated token mapping that has not been approved.
+    error JBSuckerRegistry_TokenMappingNotAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken);
+
     /// @notice Thrown when a sucker reports a zero peer chain ID and cannot identify a real peer chain.
     error JBSuckerRegistry_ZeroPeerChainId(address sucker);
 
@@ -79,10 +88,10 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
 
-    /// @notice The Juicebox directory used to look up project terminals and controllers.
+    /// @notice The Juicebox directory for project terminals and controllers.
     IJBDirectory public immutable override DIRECTORY;
 
-    /// @notice The prices contract used to value remote per-context surplus and balance into a requested currency,
+    /// @notice The prices contract for valuing remote per-context surplus and balance into a requested currency,
     /// exactly as the terminal store values local surplus.
     IJBPrices public immutable PRICES;
 
@@ -97,6 +106,15 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     /// @custom:param deployer The address of the deployer to check.
     mapping(address deployer => bool) public override suckerDeployerIsAllowed;
 
+    /// @notice Tracks whether projects may choose an owner-gated token mapping.
+    /// @dev Disable mappings and non-native same-address mappings pass through the mapping checks directly.
+    /// @custom:param localToken The local token address.
+    /// @custom:param remoteChainId The ID of the remote chain.
+    /// @custom:param remoteToken The remote token address encoded as bytes32.
+    mapping(address localToken => mapping(uint256 remoteChainId => mapping(bytes32 remoteToken => bool)))
+        public
+        override tokenMappingIsAllowed;
+
     /// @notice The ETH fee (in wei) paid into the fee project via terminal.pay() on each toRemote() call.
     uint256 public override toRemoteFee;
 
@@ -114,7 +132,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
 
     /// @param directory The juicebox directory.
     /// @param permissions A contract storing permissions.
-    /// @param prices The prices contract used to value remote per-context surplus/balance into a requested currency.
+    /// @param prices The prices contract for valuing remote per-context surplus/balance into a requested currency.
     /// @param initialOwner The initial owner of this contract.
     constructor(
         IJBDirectory directory,
@@ -216,108 +234,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
-    /// @notice Values one peer chain's raw balance held by one sucker into a currency, with peer chain ID and
-    /// freshness.
-    /// @dev Exposed as an external self-call boundary so `totalRemoteBalanceOf` can `try` it and drop a single
-    /// (sucker, chain) whose price feed is missing without losing that sucker's other chains. A context whose currency
-    /// already matches `currency` folds in at par (no feed read); a missing cross-currency feed reverts, and the
-    /// aggregator catches it and skips just this (sucker, chain).
-    /// @param sucker The sucker to read.
-    /// @param chainId The peer chain to read.
-    /// @param projectId The project whose price feeds to use.
-    /// @param currency The currency to value into.
-    /// @param decimals The decimal precision for the returned value.
-    /// @return A `JBPeerChainValue` with the valued balance, the peer chain ID, and its snapshot freshness key.
-    function remoteBalanceOf(
-        address sucker,
-        uint256 chainId,
-        uint256 projectId,
-        uint256 currency,
-        uint256 decimals
-    )
-        external
-        view
-        returns (JBPeerChainValue memory)
-    {
-        // Read this sucker's raw contexts for the chain: one per distinct local currency, plus the freshness key.
-        (JBPeerChainContext[] memory contexts, uint256 snapshot) = IJBSucker(sucker).peerChainContextsOf(chainId);
-
-        // Value each context's balance out of the currency and decimals it was recorded in, into the requested
-        // `currency` and `decimals`, and sum across every context. A context already denominated in `currency` folds
-        // in at par; a cross-currency context is converted through the project's price feed.
-        uint256 value;
-        uint256 numContexts = contexts.length;
-        for (uint256 i; i < numContexts;) {
-            value += _valued({
-                amount: contexts[i].balance,
-                fromCurrency: contexts[i].currency,
-                fromDecimals: contexts[i].decimals,
-                toCurrency: currency,
-                toDecimals: decimals,
-                projectId: projectId
-            });
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Carry the peer chain ID and snapshot freshness alongside the summed value so the aggregator can deduplicate
-        // peers and keep only the freshest snapshot per chain.
-        return JBPeerChainValue({value: value, peerChainId: chainId, snapshotTimestamp: snapshot});
-    }
-
-    /// @notice Values one peer chain's raw surplus held by one sucker into a currency, with peer chain ID and
-    /// freshness.
-    /// @dev Exposed as an external self-call boundary so `totalRemoteSurplusOf` can `try` it and drop a single
-    /// (sucker, chain) whose price feed is missing without losing that sucker's other chains. A context whose currency
-    /// already matches `currency` folds in at par (no feed read); a missing cross-currency feed reverts, and the
-    /// aggregator catches it and skips just this (sucker, chain).
-    /// @param sucker The sucker to read.
-    /// @param chainId The peer chain to read.
-    /// @param projectId The project whose price feeds to use.
-    /// @param currency The currency to value into.
-    /// @param decimals The decimal precision for the returned value.
-    /// @return A `JBPeerChainValue` with the valued surplus, the peer chain ID, and its snapshot freshness key.
-    function remoteSurplusOf(
-        address sucker,
-        uint256 chainId,
-        uint256 projectId,
-        uint256 currency,
-        uint256 decimals
-    )
-        external
-        view
-        returns (JBPeerChainValue memory)
-    {
-        // Read this sucker's raw contexts for the chain: one per distinct local currency, plus the freshness key.
-        (JBPeerChainContext[] memory contexts, uint256 snapshot) = IJBSucker(sucker).peerChainContextsOf(chainId);
-
-        // Value each context's surplus out of the currency and decimals it was recorded in, into the requested
-        // `currency` and `decimals`, and sum across every context. A context already denominated in `currency` folds
-        // in at par; a cross-currency context is converted through the project's price feed.
-        uint256 value;
-        uint256 numContexts = contexts.length;
-        for (uint256 i; i < numContexts;) {
-            value += _valued({
-                amount: contexts[i].surplus,
-                fromCurrency: contexts[i].currency,
-                fromDecimals: contexts[i].decimals,
-                toCurrency: currency,
-                toDecimals: decimals,
-                projectId: projectId
-            });
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Carry the peer chain ID and snapshot freshness alongside the summed value so the aggregator can deduplicate
-        // peers and keep only the freshest snapshot per chain.
-        return JBPeerChainValue({value: value, peerChainId: chainId, snapshotTimestamp: snapshot});
-    }
-
     /// @notice The cumulative total supply across all remote peer chains for a project.
-    /// @dev Each sucker now holds an accounting record per source chain it has heard about (its direct peer plus chains
+    /// @dev Each sucker holds an accounting record per source chain it has heard about (its direct peer plus chains
     /// gossiped through it), so this aggregates over every (sucker, chain) pair and dedups per chain. Includes
     /// deprecated suckers only when no active sucker answers for the same peer chain, to prevent undercounting during
     /// migration windows without letting stale deprecated records dominate live routes. Silently skips suckers and
@@ -367,6 +285,24 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
+    /// @notice Reverts unless a local-to-remote token mapping can be chosen by a project.
+    /// @dev Disable mappings never require owner approval. Non-native same-address mappings pass through directly.
+    /// Native-to-native and differing-address mappings must be explicitly allowed.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function requireTokenMappingAllowed(
+        address localToken,
+        uint256 remoteChainId,
+        bytes32 remoteToken
+    )
+        external
+        view
+        override
+    {
+        _requireTokenMappingAllowed({localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken});
+    }
+
     /// @notice All active (non-deprecated) suckers for a project, with their remote peer address and chain ID.
     /// @param projectId The ID of the project to get the suckers of.
     /// @return pairs The pairs of suckers and their metadata.
@@ -489,9 +425,9 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     //*********************************************************************//
 
     /// @notice Values every known peer chain held by one sucker and folds each into the per-chain dedup scratch.
-    /// @dev Each (sucker, chain) is valued through a registry self-call so a missing price feed reverts only that one
-    /// pair (caught here), not the sucker's other chains. Reads the sucker's chains itself, and is extracted from the
-    /// aggregate view, to keep both stacks shallow.
+    /// @dev Each (sucker, chain) is valued independently so a reverted sucker read or missing cross-currency price
+    /// feed drops only that one chain. Reads the sucker's chains itself, and is extracted from the aggregate view to
+    /// keep both stacks shallow.
     /// @param scratch The per-chain dedup scratch to fold values into.
     /// @param sucker The sucker whose chains to value.
     /// @param isActive Whether the sucker is active (vs deprecated).
@@ -506,9 +442,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         view
     {
         uint256[] memory chainIds;
-        // Aggregate over the full set — directly-connected plus gossiped (virtual) chains — so cross-chain
-        // accounting
-        // reflects every chain the project knows, not only its direct bridges.
+        // Aggregate over direct peer chains and gossiped virtual chains so the result reflects every chain the project
+        // knows, not only its direct bridges.
         try IJBSucker(sucker).peerChainIds(true) returns (uint256[] memory ids) {
             chainIds = ids;
         } catch {
@@ -517,37 +452,20 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
 
         uint256 numChains = chainIds.length;
         for (uint256 c; c < numChains;) {
-            // A registry self-call values one chain's raw contexts so a missing feed reverts only this (sucker, chain)
-            // (caught here). Recording inside the `try` keeps this function under the stack-slot limit.
-            if (params.surplus) {
-                try this.remoteSurplusOf({
-                    sucker: sucker,
-                    chainId: chainIds[c],
-                    projectId: params.projectId,
-                    currency: params.currency,
-                    decimals: params.decimals
-                }) returns (
-                    JBPeerChainValue memory value
-                ) {
-                    scratch.chainCount = _recordPeerChainValue({
-                        scratch: scratch, read: value, sucker: sucker, isActive: isActive
-                    });
-                } catch {}
-            } else {
-                try this.remoteBalanceOf({
-                    sucker: sucker,
-                    chainId: chainIds[c],
-                    projectId: params.projectId,
-                    currency: params.currency,
-                    decimals: params.decimals
-                }) returns (
-                    JBPeerChainValue memory value
-                ) {
-                    scratch.chainCount = _recordPeerChainValue({
-                        scratch: scratch, read: value, sucker: sucker, isActive: isActive
-                    });
-                } catch {}
+            (bool ok, JBPeerChainValue memory value) = _remoteValueOf({
+                sucker: sucker,
+                chainId: chainIds[c],
+                projectId: params.projectId,
+                currency: params.currency,
+                decimals: params.decimals,
+                surplus: params.surplus
+            });
+
+            if (ok) {
+                scratch.chainCount =
+                    _recordPeerChainValue({scratch: scratch, read: value, sucker: sucker, isActive: isActive});
             }
+
             unchecked {
                 ++c;
             }
@@ -693,7 +611,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
-    /// @notice Allocates scratch arrays used to collapse many suckers into one aggregate value per peer chain.
+    /// @notice Allocates scratch arrays for collapsing many suckers into one aggregate value per peer chain.
     /// @dev `len` is the number of suckers being scanned, which is the maximum possible number of distinct peer
     /// chains. `chainCount` starts at zero and is incremented as new peer chains are discovered.
     /// @param len The maximum number of peer-chain entries the aggregation can need.
@@ -751,9 +669,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
 
     /// @notice Records a combined peer-chain read (value, peer chain ID, snapshot freshness key) from one sucker.
     /// @dev A wrapper over `_recordPeerValue` that unpacks the single-call `JBPeerChainValue` read and enforces the
-    /// same non-zero peer-chain requirement the registry applies everywhere else. The peer-chain check reverts here
-    /// (inside the caller's `try` success body, so the revert propagates) to preserve the prior behavior where a
-    /// sucker reporting a zero peer chain ID fails the whole aggregate view.
+    /// same non-zero peer-chain requirement the registry applies everywhere else. A zero peer chain ID fails the whole
+    /// aggregate view because it makes the source chain unidentifiable.
     /// @param scratch The per-chain aggregate values and freshness keys recorded so far.
     /// @param read The combined value, peer chain ID, and snapshot freshness key returned by the sucker.
     /// @param sucker The sucker the read came from, used only for the zero-peer-chain error.
@@ -847,18 +764,115 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
-    /// @notice Values an amount held in one currency/decimals into another, mirroring the terminal store.
-    /// @dev Adjusts decimals, then converts currency via the prices contract. Both steps short-circuit on identity, and
-    /// the currency step also short-circuits on a zero amount, so a same-currency context consults no feed. A missing
-    /// feed reverts (fail-closed), and the caller catches it to drop just the affected sucker.
+    /// @notice Values one peer chain's raw balance or surplus held by one sucker into a currency.
+    /// @dev Returns `false` if the sucker read reverts or any cross-currency price read fails, allowing aggregate
+    /// views to skip only the affected (sucker, chain) record.
+    /// @param sucker The sucker to read.
+    /// @param chainId The peer chain to read.
+    /// @param projectId The project whose price feeds to use.
+    /// @param currency The currency to value into.
+    /// @param decimals The decimal precision for the returned value.
+    /// @param surplus Whether to value surplus (true) or balance (false).
+    /// @return ok Whether the peer-chain value was read and valued successfully.
+    /// @return read The peer-chain value, peer chain ID, and snapshot freshness key.
+    function _remoteValueOf(
+        address sucker,
+        uint256 chainId,
+        uint256 projectId,
+        uint256 currency,
+        uint256 decimals,
+        bool surplus
+    )
+        internal
+        view
+        returns (bool ok, JBPeerChainValue memory read)
+    {
+        JBPeerChainContext[] memory contexts;
+        uint256 snapshot;
+
+        // The sucker read is isolated so one reverting sucker/chain does not make the aggregate view unusable.
+        try IJBSucker(sucker).peerChainContextsOf(chainId) returns (
+            JBPeerChainContext[] memory readContexts, uint256 readSnapshot
+        ) {
+            contexts = readContexts;
+            snapshot = readSnapshot;
+        } catch {
+            return (false, read);
+        }
+
+        uint256 value;
+        uint256 numContexts = contexts.length;
+        for (uint256 i; i < numContexts;) {
+            // The same context set backs both aggregate views; select the requested side before pricing.
+            uint256 amount = surplus ? contexts[i].surplus : contexts[i].balance;
+
+            // If one context cannot be valued, the caller skips the whole (sucker, chain) record instead of returning a
+            // partially priced total.
+            (bool priced, uint256 valued) = _tryValued({
+                amount: amount,
+                fromCurrency: contexts[i].currency,
+                fromDecimals: contexts[i].decimals,
+                toCurrency: currency,
+                toDecimals: decimals,
+                projectId: projectId
+            });
+
+            if (!priced) return (false, read);
+
+            // Contexts have already been folded by currency/decimals on the sucker, so valued outputs share the
+            // requested units and can be added directly.
+            value += valued;
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        read = JBPeerChainValue({value: value, peerChainId: chainId, snapshotTimestamp: snapshot});
+        ok = true;
+    }
+
+    /// @notice Reverts unless a local-to-remote token mapping is allowed.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function _requireTokenMappingAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken) internal view {
+        if (_tokenMappingPassesWithoutApproval({localToken: localToken, remoteToken: remoteToken})) return;
+
+        // All economically asserted mappings must be allowlisted by the registry owner before project owners choose
+        // them.
+        if (!tokenMappingIsAllowed[localToken][remoteChainId][remoteToken]) {
+            revert JBSuckerRegistry_TokenMappingNotAllowed({
+                localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken
+            });
+        }
+    }
+
+    /// @notice Whether a local-to-remote token mapping can be chosen without owner approval.
+    /// @param localToken The local token address.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    /// @return Whether the mapping passes without owner approval.
+    function _tokenMappingPassesWithoutApproval(address localToken, bytes32 remoteToken) internal pure returns (bool) {
+        // Disabling a mapping is a project-local safety action, not a claim about remote token equivalence.
+        if (remoteToken == bytes32(0)) return true;
+
+        // Non-native same-address mappings are unambiguous across EVM chains. Native tokens use the same sentinel
+        // even when the underlying assets differ, so native-to-native still needs registry owner approval.
+        return localToken != JBConstants.NATIVE_TOKEN && remoteToken == bytes32(uint256(uint160(localToken)));
+    }
+
+    /// @notice Tries to value an amount held in one currency/decimals into another.
+    /// @dev Returns `false` when the needed cross-currency price read reverts or returns zero. Same-currency and
+    /// zero-amount values never consult the price feed.
     /// @param amount The raw amount in `fromCurrency`/`fromDecimals`.
     /// @param fromCurrency The currency the amount is held in.
     /// @param fromDecimals The decimals the amount is held in.
     /// @param toCurrency The currency to value into.
     /// @param toDecimals The decimals to value into.
     /// @param projectId The project whose price feeds to use.
-    /// @return The amount valued into `toCurrency`/`toDecimals`.
-    function _valued(
+    /// @return ok Whether the amount was valued successfully.
+    /// @return converted The amount valued into `toCurrency`/`toDecimals`.
+    function _tryValued(
         uint256 amount,
         uint256 fromCurrency,
         uint256 fromDecimals,
@@ -868,23 +882,34 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     )
         internal
         view
-        returns (uint256)
+        returns (bool ok, uint256 converted)
     {
-        // Step 1: adjust decimals.
-        uint256 value = fromDecimals == toDecimals
+        // Convert the raw context amount to the caller's requested decimals before any currency comparison, matching
+        // terminal-store valuation semantics.
+        converted = fromDecimals == toDecimals
             ? amount
             : JBFixedPointNumber.adjustDecimals({value: amount, decimals: fromDecimals, targetDecimals: toDecimals});
 
-        // Step 2: convert currency. The price is the denominator: pricePerUnitOf returns the `fromCurrency` price of
-        // one `toCurrency`, so dividing the amount by it yields the amount in `toCurrency`.
-        if (value == 0 || fromCurrency == toCurrency) return value;
-        return mulDiv({
-            x: value,
-            y: 10 ** _PRICE_FIDELITY,
-            denominator: PRICES.pricePerUnitOf({
-                projectId: projectId, pricingCurrency: fromCurrency, unitCurrency: toCurrency, decimals: _PRICE_FIDELITY
-            })
-        });
+        // Zero and same-currency values need no price feed. This is what lets same-asset remote accounting work even
+        // when a project has not configured a price feed.
+        if (converted == 0 || fromCurrency == toCurrency) return (true, converted);
+
+        // Cross-currency valuation is best-effort. A reverting or zero price makes the caller drop this (sucker, chain)
+        // record rather than mix priced and unpriced contexts.
+        try PRICES.pricePerUnitOf({
+            projectId: projectId, pricingCurrency: fromCurrency, unitCurrency: toCurrency, decimals: _PRICE_FIDELITY
+        }) returns (
+            uint256 price
+        ) {
+            if (price == 0) return (false, 0);
+
+            // `pricePerUnitOf` returns the `fromCurrency` price of one `toCurrency`, so division expresses the source
+            // amount in `toCurrency`.
+            converted = mulDiv({x: converted, y: 10 ** _PRICE_FIDELITY, denominator: price});
+            ok = true;
+        } catch {
+            return (false, 0);
+        }
     }
 
     //*********************************************************************//
@@ -920,12 +945,74 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         }
     }
 
+    /// @notice Adds a local-to-remote token mapping to the allowlist.
+    /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function allowTokenMapping(
+        address localToken,
+        uint256 remoteChainId,
+        bytes32 remoteToken
+    )
+        public
+        override
+        onlyOwner
+    {
+        tokenMappingIsAllowed[localToken][remoteChainId][remoteToken] = true;
+        emit TokenMappingAllowed({
+            localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken, caller: _msgSender()
+        });
+    }
+
+    /// @notice Adds multiple local-to-remote token mappings to the allowlist.
+    /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
+    /// @param localTokens The local token addresses.
+    /// @param remoteChainIds The remote chain IDs.
+    /// @param remoteTokens The remote token addresses encoded as bytes32.
+    function allowTokenMappings(
+        address[] calldata localTokens,
+        uint256[] calldata remoteChainIds,
+        bytes32[] calldata remoteTokens
+    )
+        public
+        override
+        onlyOwner
+    {
+        uint256 localTokenCount = localTokens.length;
+        if (localTokenCount != remoteChainIds.length || localTokenCount != remoteTokens.length) {
+            revert JBSuckerRegistry_TokenMappingLengthMismatch({
+                localTokenCount: localTokenCount,
+                remoteChainIdCount: remoteChainIds.length,
+                remoteTokenCount: remoteTokens.length
+            });
+        }
+
+        // Cache _msgSender() to avoid redundant calls in the loop.
+        address sender = _msgSender();
+
+        // Iterate over each parallel pair exactly once so a single admin transaction configures a full route set.
+        for (uint256 i; i < localTokenCount;) {
+            address localToken = localTokens[i];
+            uint256 remoteChainId = remoteChainIds[i];
+            bytes32 remoteToken = remoteTokens[i];
+
+            tokenMappingIsAllowed[localToken][remoteChainId][remoteToken] = true;
+            emit TokenMappingAllowed({
+                localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken, caller: sender
+            });
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     /// @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, 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
+    /// @param salt The deployment salt. For the suckers to be peers, this must be the same value on
     /// each chain where suckers are deployed.
     /// @param configurations The sucker deployer configs to use to deploy the suckers.
     /// @return suckers The addresses of the deployed suckers.
@@ -1030,6 +1117,68 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         emit SuckerDeployerRemoved({deployer: deployer, caller: _msgSender()});
     }
 
+    /// @notice Removes a local-to-remote token mapping from the allowlist.
+    /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function removeTokenMapping(
+        address localToken,
+        uint256 remoteChainId,
+        bytes32 remoteToken
+    )
+        public
+        override
+        onlyOwner
+    {
+        tokenMappingIsAllowed[localToken][remoteChainId][remoteToken] = false;
+        emit TokenMappingRemoved({
+            localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken, caller: _msgSender()
+        });
+    }
+
+    /// @notice Removes multiple local-to-remote token mappings from the allowlist.
+    /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
+    /// @param localTokens The local token addresses.
+    /// @param remoteChainIds The remote chain IDs.
+    /// @param remoteTokens The remote token addresses encoded as bytes32.
+    function removeTokenMappings(
+        address[] calldata localTokens,
+        uint256[] calldata remoteChainIds,
+        bytes32[] calldata remoteTokens
+    )
+        public
+        override
+        onlyOwner
+    {
+        uint256 localTokenCount = localTokens.length;
+        if (localTokenCount != remoteChainIds.length || localTokenCount != remoteTokens.length) {
+            revert JBSuckerRegistry_TokenMappingLengthMismatch({
+                localTokenCount: localTokenCount,
+                remoteChainIdCount: remoteChainIds.length,
+                remoteTokenCount: remoteTokens.length
+            });
+        }
+
+        // Cache _msgSender() to avoid redundant calls in the loop.
+        address sender = _msgSender();
+
+        // Iterate over each parallel pair exactly once so a single admin transaction can remove a route set.
+        for (uint256 i; i < localTokenCount;) {
+            address localToken = localTokens[i];
+            uint256 remoteChainId = remoteChainIds[i];
+            bytes32 remoteToken = remoteTokens[i];
+
+            tokenMappingIsAllowed[localToken][remoteChainId][remoteToken] = false;
+            emit TokenMappingRemoved({
+                localToken: localToken, remoteChainId: remoteChainId, remoteToken: remoteToken, caller: sender
+            });
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     /// @notice Set the ETH fee (in wei) paid into the fee project on each toRemote() call.
     /// @dev Only callable by the contract owner. Fee cannot exceed MAX_TO_REMOTE_FEE.
     /// @param fee The new fee amount in wei.

package/src/interfaces/IJBSuckerRegistry.sol

@@ -35,6 +35,20 @@ interface IJBSuckerRegistry {
     /// @param caller The address that removed the sucker.
     event SuckerDeprecated(uint256 projectId, address sucker, address caller);
 
+    /// @notice Emitted when a local-to-remote token mapping is added to the allowlist.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    /// @param caller The address that allowed the token mapping.
+    event TokenMappingAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken, address caller);
+
+    /// @notice Emitted when a local-to-remote token mapping is removed from the allowlist.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    /// @param caller The address that removed the token mapping.
+    event TokenMappingRemoved(address localToken, uint256 remoteChainId, bytes32 remoteToken, address caller);
+
     /// @notice Emitted when the toRemoteFee is changed.
     /// @param oldFee The previous fee.
     /// @param newFee The new fee.
@@ -90,6 +104,14 @@ interface IJBSuckerRegistry {
     /// @return totalSupply The combined peer chain total supply.
     function remoteTotalSupplyOf(uint256 projectId) external view returns (uint256 totalSupply);
 
+    /// @notice Reverts unless a token mapping can be chosen by a project.
+    /// @dev Disable mappings never require owner approval. Non-native same-address mappings pass through directly.
+    /// Native-to-native and differing-address mappings must be explicitly allowed.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function requireTokenMappingAllowed(address localToken, uint256 remoteChainId, bytes32 remoteToken) external view;
+
     /// @notice Whether the specified sucker deployer is approved by this registry.
     /// @param deployer The address of the deployer to check.
     /// @return Whether the deployer is allowed.
@@ -105,6 +127,20 @@ interface IJBSuckerRegistry {
     /// @return The addresses of the suckers.
     function suckersOf(uint256 projectId) external view returns (address[] memory);
 
+    /// @notice Whether a local-to-remote token mapping is approved by this registry.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    /// @return Whether the token mapping is allowed.
+    function tokenMappingIsAllowed(
+        address localToken,
+        uint256 remoteChainId,
+        bytes32 remoteToken
+    )
+        external
+        view
+        returns (bool);
+
     /// @notice The ETH fee (in wei) paid into the fee project on each toRemote() call.
     /// @return The current fee.
     function toRemoteFee() external view returns (uint256);
@@ -153,6 +189,23 @@ interface IJBSuckerRegistry {
     /// @param deployers The addresses of the deployers to allow.
     function allowSuckerDeployers(address[] calldata deployers) external;
 
+    /// @notice Add a local-to-remote token mapping to the allowlist.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function allowTokenMapping(address localToken, uint256 remoteChainId, bytes32 remoteToken) external;
+
+    /// @notice Add multiple local-to-remote token mappings to the allowlist.
+    /// @param localTokens The local token addresses.
+    /// @param remoteChainIds The remote chain IDs.
+    /// @param remoteTokens The remote token addresses encoded as bytes32.
+    function allowTokenMappings(
+        address[] calldata localTokens,
+        uint256[] calldata remoteChainIds,
+        bytes32[] calldata remoteTokens
+    )
+        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. `DEPLOY_SUCKERS`
     /// authorizes those initial mappings; use `MAP_SUCKER_TOKEN` for post-deployment mapping changes.
@@ -177,6 +230,23 @@ interface IJBSuckerRegistry {
     /// @param deployer The address of the deployer to remove.
     function removeSuckerDeployer(address deployer) external;
 
+    /// @notice Remove a local-to-remote token mapping from the allowlist.
+    /// @param localToken The local token address.
+    /// @param remoteChainId The ID of the remote chain.
+    /// @param remoteToken The remote token address encoded as bytes32.
+    function removeTokenMapping(address localToken, uint256 remoteChainId, bytes32 remoteToken) external;
+
+    /// @notice Remove multiple local-to-remote token mappings from the allowlist.
+    /// @param localTokens The local token addresses.
+    /// @param remoteChainIds The remote chain IDs.
+    /// @param remoteTokens The remote token addresses encoded as bytes32.
+    function removeTokenMappings(
+        address[] calldata localTokens,
+        uint256[] calldata remoteChainIds,
+        bytes32[] calldata remoteTokens
+    )
+        external;
+
     /// @notice Set the ETH fee (in wei) paid on each toRemote() call. Owner only.
     /// @param fee The new fee amount in wei.
     function setToRemoteFee(uint256 fee) external;