@bananapus/suckers-v6 1.0.0 → 1.0.2

package/src/interfaces/IJBSucker.sol

@@ -1,10 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+import {JBSuckerState} from "../enums/JBSuckerState.sol";
+
 import {JBAccountingSnapshot} from "../structs/JBAccountingSnapshot.sol";
 import {JBChainAccounting} from "../structs/JBChainAccounting.sol";
 import {JBClaim} from "../structs/JBClaim.sol";
@@ -13,7 +16,6 @@ import {JBOutboxTree} from "../structs/JBOutboxTree.sol";
 import {JBPeerChainContext} from "../structs/JBPeerChainContext.sol";
 import {JBPeerChainValue} from "../structs/JBPeerChainValue.sol";
 import {JBRemoteToken} from "../structs/JBRemoteToken.sol";
-import {JBSuckerState} from "../enums/JBSuckerState.sol";
 import {JBTokenMapping} from "../structs/JBTokenMapping.sol";
 
 /// @notice The minimal interface for a sucker contract.
@@ -158,10 +160,11 @@ interface IJBSucker is IERC165 {
     /// @return The peer address.
     function peer() external view returns (bytes32);
 
-    /// @notice The raw, un-valued accounting record this sucker holds for every peer chain it has heard about.
+    /// @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. Records are
-    /// returned exactly as received so the next receiver resolves them to its own local currencies independently.
-    /// @return accounts One raw accounting record per known peer chain.
+    /// keyed to this sucker's local token when a source token matches a remote-token mapping. The next receiver only
+    /// needs its mapping to this peer's token.
+    /// @return accounts One accounting record per known peer chain.
     function peerChainAccountsOf() external view returns (JBChainAccounting[] memory accounts);
 
     /// @notice One peer chain's per-currency surplus and balance from its latest accepted record, plus its freshness

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;

package/src/libraries/JBSuckerLib.sol

@@ -5,22 +5,24 @@ import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBMultiTerminal} from "@bananapus/core-v6/src/interfaces/IJBMultiTerminal.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
-import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
 import {JBRulesetMetadataResolver} from "@bananapus/core-v6/src/libraries/JBRulesetMetadataResolver.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
 import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
 import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 
 import {IJBPeerChainAdjustedAccounts} from "../interfaces/IJBPeerChainAdjustedAccounts.sol";
 import {IJBSuckerRegistry} from "../interfaces/IJBSuckerRegistry.sol";
+
 import {JBPeerChainAdjustedAccountsLib} from "./JBPeerChainAdjustedAccountsLib.sol";
+import {MerkleLib} from "../utils/MerkleLib.sol";
+
 import {JBAccountingSnapshot} from "../structs/JBAccountingSnapshot.sol";
 import {JBChainAccounting} from "../structs/JBChainAccounting.sol";
 import {JBInboxTreeRoot} from "../structs/JBInboxTreeRoot.sol";
 import {JBMessageRoot} from "../structs/JBMessageRoot.sol";
 import {JBPeerChainContext} from "../structs/JBPeerChainContext.sol";
 import {JBSourceContext} from "../structs/JBSourceContext.sol";
-import {MerkleLib} from "../utils/MerkleLib.sol";
 
 /// @notice Library with bytecode-heavy functions extracted from JBSucker to reduce child contract sizes.
 /// @dev These are `external` library functions, so they are deployed as a separate contract and called via
@@ -186,23 +188,20 @@ library JBSuckerLib {
         }
     }
 
-    /// @notice Folds a peer chain's raw source contexts into per-currency surplus and balance, resolving each to a
-    /// local currency.
+    /// @notice Folds a peer chain's source contexts into per-currency surplus and balance.
     /// @dev Extracted from `JBSucker.peerChainContextsOf` to reduce child contract bytecode. Called via DELEGATECALL.
-    /// Each `localTokens[i]` is the local token the sucker resolved `rawContexts[i].token` to (via its token mapping or
-    /// identity); this derives that token's authoritative accounting-context currency and merges entries that share
-    /// BOTH currency AND decimals. The accounting-context currency is immutable, so re-resolving on each read is safe.
-    /// Entries that share a currency but carry different decimals stay separate, since the raw amounts are on different
-    /// scales. No price oracle is consulted.
+    /// The caller stores mapped remote-token keys in its local token namespace before this runs. This derives each
+    /// token's authoritative accounting-context currency and merges entries that share BOTH currency AND decimals. The
+    /// accounting-context currency is immutable, so re-resolving on each read is safe. Entries that share a currency
+    /// but carry different decimals stay separate, since the raw amounts are on different scales. No price oracle is
+    /// consulted.
     /// @param directory The JB directory to look up the project's terminals.
     /// @param projectId The project whose accounting contexts to read.
-    /// @param localTokens The local token each raw context resolves to, parallel to `rawContexts`.
-    /// @param rawContexts The peer chain's raw per-context surplus and balance.
+    /// @param rawContexts The peer chain's per-context surplus and balance.
     /// @return contexts The per-currency surplus and balance for the chain.
     function foldPeerContexts(
         IJBDirectory directory,
         uint256 projectId,
-        address[] memory localTokens,
         JBSourceContext[] memory rawContexts
     )
         external
@@ -219,7 +218,8 @@ library JBSuckerLib {
             uint8 ctxDecimals = rawContexts[i].decimals;
             uint128 ctxSurplus = rawContexts[i].surplus;
             uint128 ctxBalance = rawContexts[i].balance;
-            uint32 ctxCurrency = _currencyOf({directory: directory, projectId: projectId, token: localTokens[i]});
+            address token = address(uint160(uint256(rawContexts[i].token)));
+            uint32 ctxCurrency = _currencyOf({directory: directory, projectId: projectId, token: token});
 
             // Fold into an existing entry that matches on BOTH currency AND decimals, or append a new one.
             bool merged;
@@ -265,7 +265,8 @@ library JBSuckerLib {
     /// peer records are gathered from the registry, which is the only contract that sees a hub chain's per-peer
     /// suckers together; it dedups them to the freshest per chain. A reverting or unset registry yields a local-only
     /// bundle, so a standalone sucker still propagates its own record. Forwarded peer records keep their own origin
-    /// chain and freshness key so the receiver gates each chain independently.
+    /// chain and freshness key, while their context token keys are already localized by the sucker they were gathered
+    /// from so the receiver only needs its mapping to the direct peer's token.
     /// @param directory The JB directory to look up controllers and terminals.
     /// @param registry The sucker registry that aggregates the project's per-chain records.
     /// @param projectId The project to snapshot.
@@ -297,7 +298,7 @@ library JBSuckerLib {
             peers = gathered;
         } catch {}
 
-        // The local record leads; forwarded peer records follow verbatim, keeping their own origin chain and freshness.
+        // The local record leads; forwarded peer records follow, keeping their own origin chain and freshness.
         accounts = new JBChainAccounting[](peers.length + 1);
         accounts[0] = JBChainAccounting({
             chainId: block.chainid, totalSupply: localTotalSupply, contexts: localContexts, timestamp: sourceTimestamp

package/src/structs/JBChainAccounting.sol

@@ -4,24 +4,23 @@ pragma solidity ^0.8.0;
 import {JBSourceContext} from "./JBSourceContext.sol";
 
 /// @notice One source chain's project-wide accounting, carried as a record in a cross-chain gossip bundle.
-/// @dev A sucker sends its own chain's record alongside every peer-chain record it already holds, each stamped with
-/// the originating chain's own freshness key. The receiving chain stores the freshest record per source chain, so a
-/// project's accounting propagates across a hub-and-spoke sucker mesh (L2s bridged only through mainnet) without a
-/// direct sucker between every pair of chains. `contexts` carry the source chain's own token addresses, so each
-/// receiver resolves them to its own local currencies independently. Trust is transitive across the mesh: a receiver
-/// authenticates only the directly-bridged peer that delivers a bundle, not the origin of each forwarded record, so
-/// any authenticated peer can forward a record for any other chain. A record is therefore only as trustworthy as the
-/// project's same-address sucker invariant — the same CREATE2 same-bytecode assumption every paired sucker already
-/// relies on — and a peer running adversarial bytecode could forge another chain's record. The freshest-per-chain
-/// gate bounds rollback, not authorship; the supply view it feeds is clamped downstream by each chain's own local
-/// surplus, so a forged record cannot by itself over-credit a cash out.
+/// @dev A sucker sends its own chain's record alongside every peer-chain record it already holds. Each record is
+/// stamped with its originating chain's freshness key. The receiving chain stores the freshest record per source chain,
+/// so a project's accounting propagates across a hub-and-spoke sucker mesh without a direct sucker between every pair
+/// of chains. `contexts` are un-valued token-denominated amounts. A direct sender's own record carries source-chain
+/// token addresses. Forwarded peer records use the forwarding hub's local same-asset token when a mapping exists, so
+/// the next receiver only needs a mapping to that hub token. Trust is transitive across the mesh: a receiver
+/// authenticates only the directly-bridged peer that delivers a bundle, not the origin of each forwarded record. A
+/// record is therefore only as trustworthy as the project's same-address sucker invariant — the same CREATE2
+/// same-bytecode assumption every paired sucker already relies on — and a peer running adversarial bytecode could
+/// forge another chain's record. The freshest-per-chain gate bounds rollback, not authorship; the supply view it feeds
+/// is clamped downstream by each chain's own local surplus, so a forged record cannot by itself over-credit a cash out.
 /// @custom:member chainId The source chain this record describes. A receiver ignores a record for its own chain, since
 /// it reads its own local accounting directly.
 /// @custom:member totalSupply The total token supply (including reserved tokens) on the source chain when the record
 /// was taken. Used by the receiving chain to track cross-chain supply for cash out tax calculations.
-/// @custom:member contexts The source chain's surplus and balance per accounting context, each in the context's own
-/// currency and decimals, un-valued. The receiver resolves each entry to its same-asset local context and folds it in
-/// at par.
+/// @custom:member contexts The source chain's surplus and balance per accounting context, each in its own decimals and
+/// un-valued. The token key may be the source token for direct records or a forwarding hub's local same-asset token.
 /// @custom:member timestamp A monotonic source-chain freshness key for the record. The receiver keeps the freshest
 /// record per source chain, so stale relays cannot roll back surplus, balance, or supply.
 struct JBChainAccounting {

package/src/structs/JBPeerChainContext.sol

@@ -3,10 +3,10 @@ pragma solidity ^0.8.0;
 
 /// @notice A remote chain's surplus and balance for one local currency, as last received.
 /// @dev One entry per local currency in the latest snapshot. The local currency is the project's authoritative
-/// accounting-context currency for the token a remote context resolves to (identity for same-address tokens, or via
-/// the sucker's token mapping for same-asset tokens at different addresses). `surplus`/`balance` are raw, un-valued
-/// amounts in that currency's own units; a read values them into a requested currency via the prices contract, exactly
-/// as the terminal store values local surplus (an identity short-circuit means same-currency reads are taken at par).
+/// accounting-context currency for the stored token key. A receiver stores mapped remote-token keys under its local
+/// same-asset token before this view is built. `surplus`/`balance` are raw, un-valued amounts in that currency's own
+/// units; a read values them into a requested currency via the prices contract, exactly as the terminal store values
+/// local surplus (an identity short-circuit means same-currency reads are taken at par).
 /// @custom:member currency The local currency this context resolves to.
 /// @custom:member decimals The context's native decimal precision, used to rescale to a requested precision.
 /// @custom:member surplus The raw surplus held in this currency on the peer chain.

package/src/structs/JBSourceContext.sol

@@ -1,17 +1,14 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice One source-chain accounting context, carried raw (un-valued) in a cross-chain snapshot.
+/// @notice One source-chain accounting context, carried un-valued in a cross-chain snapshot.
 /// @dev The source chain reports its surplus and balance per accounting context in that context's own decimals — it
-/// performs no price-feed valuation. The destination chain resolves `token` to its own local token (identity for
-/// same-address tokens, or via the sucker's remote-to-local token mapping for same-asset tokens at different
-/// addresses), derives that local token's currency as `uint32(uint160(localToken))`, and folds the context into its
-/// same-currency local context at par. The destination derives the currency from the resolved local token rather than
-/// trusting a wire-carried currency, so a same-asset token at a different address (e.g. USDC) still folds under the
-/// receiver's own currency. The only conversions ever performed are the ones a project already needs for its own local
-/// surplus.
-/// @custom:member token The source-local token this context was read from, resolved to a local token (and thence a
-/// local currency) on receipt. Padded to bytes32 for cross-VM compatibility.
+/// performs no price-feed valuation. A receiver stores `token` as its own local token when a remote-token mapping
+/// exists, or leaves the token key unchanged otherwise. Read paths derive the context's currency from that stored token
+/// key instead of trusting a wire-carried currency, so same-asset tokens at different addresses (e.g. USDC) still fold
+/// under the receiver's own currency. Any later valuation uses the project's normal local surplus conversions.
+/// @custom:member token The source token key, or a receiver-local token key after a remote-token mapping has been
+/// applied. Padded to bytes32 for cross-VM compatibility.
 /// @custom:member decimals The context's native decimal precision (e.g. 18 for ETH, 6 for USDC).
 /// @custom:member surplus The raw, un-valued surplus held in this context, in the context's own units. Capped to
 /// `uint128` for cross-VM (SVM) compatibility, matching the leaf-amount cap.