@bananapus/suckers-v6 1.0.0 → 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.0",
+  "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

@@ -332,12 +332,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// project's chain count.
     uint256[] private _peerChainIds;
 
-    /// @notice Each peer chain's raw, un-valued per-context surplus and balance from its latest accepted record.
-    /// @dev Stored exactly as received — in the source chain's own token addresses and decimals — so the record can
-    /// be
-    /// re-gossiped to other chains faithfully and resolved to local currencies at read time. A fresher record for a
-    /// chain replaces that chain's set from scratch; a context dropped by the fresher record simply vanishes.
-    /// @custom:param chainId The peer chain to read the raw contexts of.
+    /// @notice Each peer chain's un-valued per-context surplus and balance from its latest accepted record.
+    /// @dev Stored in this sucker's token namespace where a remote-token mapping exists; unmapped tokens stay as
+    /// received. `peerChainContextsOf` resolves these token keys for local valuation.
+    /// A fresher record for a chain replaces that chain's set from scratch; a context dropped by the fresher record
+    /// simply vanishes.
+    /// @custom:param chainId The peer chain to read the contexts of.
     mapping(uint256 chainId => JBSourceContext[]) private _peerContextsOf;
 
     //*********************************************************************//
@@ -882,11 +882,11 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         return _outboxOf[token];
     }
 
-    /// @notice The raw, un-valued accounting record this sucker holds for every peer chain it has heard about.
-    /// @dev The registry reads this to gather a project's full cross-chain knowledge and re-gossip it. Records are
-    /// returned exactly as received (in each source chain's own token addresses and decimals) so the next receiver
-    /// resolves them to its own local currencies independently.
-    /// @return accounts One raw accounting record per known peer chain.
+    /// @notice The un-valued accounting record this sucker holds for every peer chain it has heard about.
+    /// @dev The registry reads this to gather a project's full cross-chain knowledge and re-gossip it. Incoming
+    /// contexts are stored in this sucker's token namespace where a mapping exists, so a hub forwards sibling-chain
+    /// accounting in hub-local token terms and the next spoke only needs its mapping to the hub token.
+    /// @return accounts One accounting record per known peer chain.
     function peerChainAccountsOf() external view returns (JBChainAccounting[] memory accounts) {
         uint256[] storage chainIds = _peerChainIds;
         uint256 numChains = chainIds.length;
@@ -907,10 +907,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
     /// @notice One peer chain's per-currency surplus and balance from its latest accepted record, plus that record's
     /// freshness key.
-    /// @dev Resolves each raw stored context to its local currency and folds same-currency, same-decimals entries
-    /// together. The result is un-valued — the registry values each context into a requested currency; the sucker
-    /// consults no price oracle. Contexts that share a currency but carry different decimals are kept separate because
-    /// the raw amounts are on different scales and cannot be summed directly.
+    /// @dev Stored contexts are already keyed in this sucker's token namespace where a mapping exists. This folds
+    /// same-currency, same-decimals entries together. The result is un-valued — the registry values each context into
+    /// a requested currency; the sucker consults no price oracle. Contexts that share a currency but carry different
+    /// decimals are kept separate because the raw amounts are on different scales and cannot be summed directly.
     /// @param chainId The peer chain to read the contexts of.
     /// @return contexts The per-currency surplus and balance for the chain.
     /// @return snapshot The source freshness key of the chain's latest accepted record.
@@ -919,25 +919,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         view
         returns (JBPeerChainContext[] memory contexts, uint256 snapshot)
     {
-        JBSourceContext[] storage rawContexts = _peerContextsOf[chainId];
-        uint256 numRaw = rawContexts.length;
-
-        // Copy the raw contexts to memory and resolve each source-local token to a local token (mapping first, identity
-        // fallback). The bytecode-heavy currency resolution and fold then run in the library.
-        JBSourceContext[] memory raw = new JBSourceContext[](numRaw);
-        address[] memory localTokens = new address[](numRaw);
-        for (uint256 i; i < numRaw;) {
-            JBSourceContext storage ctx = rawContexts[i];
-            raw[i] = ctx;
-            address contextToken = _localTokenForRemoteToken[ctx.token];
-            localTokens[i] = contextToken == address(0) ? _toAddress(ctx.token) : contextToken;
-            unchecked {
-                ++i;
-            }
-        }
-
         contexts = JBSuckerLib.foldPeerContexts({
-            directory: DIRECTORY, projectId: projectId(), localTokens: localTokens, rawContexts: raw
+            directory: DIRECTORY, projectId: projectId(), rawContexts: _peerContextsOf[chainId]
         });
         snapshot = snapshotTimestampOf[chainId];
     }
@@ -1324,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.
@@ -1345,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});
@@ -1359,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});
             }
         }
 
@@ -1376,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;
@@ -1386,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.
@@ -1600,12 +1587,13 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @notice Store one source chain's accounting record if it is fresher than the one already held for that chain.
     /// @dev A record for the local chain is ignored — a chain reads its own accounting directly. Each peer chain is
     /// gated independently on a strictly-newer freshness key, so a stale relay cannot roll back any chain and records
-    /// delivered out of order converge. Contexts are stored raw (in the source chain's own token addresses) so the
-    /// record can be re-gossiped faithfully; each receiver resolves them to its own local currencies at read time.
+    /// delivered out of order converge. Any source token that matches this sucker's remote-token mapping is re-keyed
+    /// to this sucker's local token before storage, so forwarded records are already in the current hop's token
+    /// namespace.
     /// @param chainId The source chain the record describes.
     /// @param sourceTimestamp The record's source-chain freshness key.
     /// @param sourceTotalSupply The source chain's total project-token supply.
-    /// @param sourceContexts The source chain's raw per-context surplus and balance.
+    /// @param sourceContexts The source chain's per-context surplus and balance.
     function _storeChainAccounting(
         uint256 chainId,
         uint256 sourceTimestamp,
@@ -1634,15 +1622,17 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             _peerChainIds.push(chainId);
         }
 
-        // Rebuild this chain's raw context set from scratch. A context dropped by the fresher record is simply absent.
-        // Each context is stored verbatim so it can be re-gossiped faithfully; folding to a local currency happens at
-        // read time in `peerChainContextsOf`.
+        // Rebuild this chain's context set from scratch. A context dropped by the fresher record is simply absent.
+        // Each context keeps its source amount and decimals, while its token key is localized for this hop when a
+        // mapping exists.
         delete _peerContextsOf[chainId];
         JBSourceContext[] storage storedContexts = _peerContextsOf[chainId];
 
         uint256 numContexts = sourceContexts.length;
         for (uint256 i; i < numContexts;) {
             storedContexts.push(sourceContexts[i]);
+            address localToken = _localTokenForRemoteToken[sourceContexts[i].token];
+            if (localToken != address(0)) storedContexts[i].token = bytes32(uint256(uint160(localToken)));
             unchecked {
                 ++i;
             }
@@ -2036,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});
         }
     }