@bananapus/suckers-v6 1.0.0 → 1.0.1

package/package.json

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

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];
     }
@@ -1600,12 +1583,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 +1618,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;
             }

package/src/JBSuckerRegistry.sol

@@ -610,7 +610,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         return ERC2771Context._contextSuffixLength();
     }
 
-    /// @notice Reads one sucker's raw records and folds each into the per-chain gather scratch.
+    /// @notice Reads one sucker's locally-keyed records and folds each into the per-chain gather scratch.
     /// @dev Extracted from `peerChainAccountsOf` to keep its stack shallow. A sucker that reverts contributes nothing.
     /// The destination chain, the local chain, and chain 0 are excluded.
     /// @param scratch The per-chain gather scratch to fold records into.
@@ -706,8 +706,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         scratch.hasActiveValue = new bool[](len);
     }
 
-    /// @notice Records one source chain's raw accounting record into a per-chain gather scratch, keeping the freshest.
-    /// @dev Mirrors `_recordPeerValue`'s selection rule for raw records: an active sucker's record supersedes a
+    /// @notice Records one source chain's accounting record into a per-chain gather scratch, keeping the freshest.
+    /// @dev Mirrors `_recordPeerValue`'s selection rule for gathered records: an active sucker's record supersedes a
     /// deprecated one's for the same chain; among same-state records the strictly-fresher timestamp wins; equal
     /// freshness keeps the first writer, since records from one origin chain at one freshness key are identical. Used
     /// to gather records for re-gossiping.

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