@bananapus/suckers-v6 0.0.78 → 1.0.0

package/src/interfaces/IJBSucker.sol

@@ -6,6 +6,7 @@ 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 {JBAccountingSnapshot} from "../structs/JBAccountingSnapshot.sol";
+import {JBChainAccounting} from "../structs/JBChainAccounting.sol";
 import {JBClaim} from "../structs/JBClaim.sol";
 import {JBInboxTreeRoot} from "../structs/JBInboxTreeRoot.sol";
 import {JBOutboxTree} from "../structs/JBOutboxTree.sol";
@@ -157,33 +158,51 @@ interface IJBSucker is IERC165 {
     /// @return The peer address.
     function peer() external view returns (bytes32);
 
-    /// @notice The chain ID of the remote peer.
-    /// @return chainId The remote chain ID.
-    function peerChainId() external view returns (uint256 chainId);
-
-    /// @notice The peer chain's raw per-context surplus and balance from the latest snapshot, bundled with the peer
-    /// chain ID and snapshot freshness key.
-    /// @dev Un-valued — each context is in its own currency and decimals. The registry dedups same-peer suckers by
-    /// freshness, then values each context into a requested currency. The sucker consults no price oracle.
-    /// @return contexts The per-currency surplus and balance from the latest snapshot.
-    /// @return chainId The peer chain these contexts belong to.
-    /// @return snapshot The source freshness key of the latest snapshot.
-    function peerChainContextsOf()
+    /// @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 so the next receiver resolves them to its own local currencies independently.
+    /// @return accounts One raw 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
+    /// key.
+    /// @dev Un-valued — each context is in its own currency and decimals. The registry values each context into a
+    /// requested currency; the sucker consults no price oracle.
+    /// @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.
+    function peerChainContextsOf(uint256 chainId)
         external
         view
-        returns (JBPeerChainContext[] memory contexts, uint256 chainId, uint256 snapshot);
+        returns (JBPeerChainContext[] memory contexts, uint256 snapshot);
+
+    /// @notice The chain ID of the remote peer this sucker is directly paired with.
+    /// @return chainId The remote chain ID.
+    function peerChainId() external view returns (uint256 chainId);
 
-    /// @notice The last known total token supply on the peer chain, updated each time a bridge message is received.
-    /// @dev Used by data hooks to compute `effectiveTotalSupply = localSupply + sum(peerChainTotalSupply)` across all
-    /// suckers, preventing cash out tax bypass on chains where a holder dominates the local supply.
+    /// @notice The peer chains this sucker reports accounting for. With `includeVirtual` false, returns only the
+    /// directly-connected peer chain (the one it is bridged to); with `includeVirtual` true, also returns every chain
+    /// learned about through gossip relayed by that peer.
+    /// @dev The directly-connected peer is always present (with a zero value until its first record) so a
+    /// freshly-deployed active sucker immediately owns that chain's accounting during a migration window.
+    /// @param includeVirtual Whether to also include virtually-known (gossiped) peer chains.
+    /// @return chainIds The peer chain IDs.
+    function peerChainIds(bool includeVirtual) external view returns (uint256[] memory chainIds);
+
+    /// @notice The last known total token supply on a peer chain, updated each time a bridge message carries that
+    /// chain's accounting record.
+    /// @dev The registry sums the freshest value across every peer chain to drive cross-chain cash out tax, preventing
+    /// a holder who dominates one chain's local supply from bypassing the tax.
+    /// @param chainId The peer chain to read the total supply of.
     /// @return The peer chain's total supply.
-    function peerChainTotalSupply() external view returns (uint256);
+    function peerChainTotalSupplyOf(uint256 chainId) external view returns (uint256);
 
-    /// @notice The peer chain total supply bundled with the peer chain ID and snapshot freshness key.
-    /// @dev Lets aggregators read the value, the peer chain it belongs to, and its freshness in one call. The
-    /// `value` matches `peerChainTotalSupply`.
+    /// @notice One peer chain's total supply bundled with the peer chain ID and the record's freshness key.
+    /// @dev Lets the registry read the value, the peer chain it belongs to, and its freshness in one call. The `value`
+    /// matches `peerChainTotalSupplyOf(chainId)`.
+    /// @param chainId The peer chain to read the total supply value of.
     /// @return A `JBPeerChainValue` with the total supply, peer chain ID, and snapshot freshness key.
-    function peerChainTotalSupplyValue() external view returns (JBPeerChainValue memory);
+    function peerChainTotalSupplyValue(uint256 chainId) external view returns (JBPeerChainValue memory);
 
     /// @notice The ID of the project on the local chain that this sucker is associated with.
     /// @return The project ID.
@@ -194,10 +213,11 @@ interface IJBSucker is IERC165 {
     /// @return The remote token info.
     function remoteTokenFor(address token) external view returns (JBRemoteToken memory);
 
-    /// @notice The freshness key of the latest accepted peer-chain economic snapshot.
+    /// @notice The freshness key of the latest accepted accounting record for a peer chain.
     /// @dev Higher values are fresher. The key is source-chain monotonic, not a value magnitude.
-    /// @return The latest peer-chain snapshot freshness key.
-    function snapshotTimestamp() external view returns (uint256);
+    /// @param chainId The peer chain to read the latest accepted freshness key of.
+    /// @return The latest accepted freshness key for the chain.
+    function snapshotTimestampOf(uint256 chainId) external view returns (uint256);
 
     /// @notice The current deprecation state of this sucker.
     /// @return The sucker state.

package/src/interfaces/IJBSuckerRegistry.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.0;
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
 
+import {JBChainAccounting} from "../structs/JBChainAccounting.sol";
 import {JBSuckerDeployerConfig} from "../structs/JBSuckerDeployerConfig.sol";
 import {JBSuckersPair} from "../structs/JBSuckersPair.sol";
 
@@ -68,9 +69,23 @@ interface IJBSuckerRegistry {
     /// @return Whether the sucker belongs to the project.
     function isSuckerOf(uint256 projectId, address addr) external view returns (bool);
 
+    /// @notice The freshest accounting record per source chain that a project's suckers hold, for re-gossiping.
+    /// @dev A sucker building an outbound gossip bundle calls this to gather the project's full cross-chain knowledge,
+    /// deduped per chain (freshest wins; active supersedes deprecated), excluding the destination and local chains.
+    /// @param projectId The ID of the project.
+    /// @param exceptChainId The destination chain to exclude.
+    /// @return accounts The deduped raw accounting records, one per known source chain.
+    function peerChainAccountsOf(
+        uint256 projectId,
+        uint256 exceptChainId
+    )
+        external
+        view
+        returns (JBChainAccounting[] memory accounts);
+
     /// @notice The cumulative total supply across all remote peer chains for a project.
-    /// @dev Dedupes same-peer active suckers by freshest snapshot, then sums peer-chain values. Silently skips suckers
-    /// that revert.
+    /// @dev Aggregates over every (sucker, chain) pair and dedups per chain by freshest record. Silently skips suckers
+    /// and records that revert.
     /// @param projectId The ID of the project.
     /// @return totalSupply The combined peer chain total supply.
     function remoteTotalSupplyOf(uint256 projectId) external view returns (uint256 totalSupply);
@@ -95,9 +110,9 @@ interface IJBSuckerRegistry {
     function toRemoteFee() external view returns (uint256);
 
     /// @notice The cumulative peer-chain balance across all remote peer chains for a project, valued into a currency.
-    /// @dev Dedups same-peer active suckers by freshest snapshot, then sums each sucker's balance valued into
-    /// `currency`. A context whose currency already matches is taken at par (no feed); a missing cross-currency feed
-    /// reverts and that sucker is silently skipped (conservative, bias-low).
+    /// @dev Aggregates over every (sucker, chain) pair and dedups per chain by freshest record, then sums each chain's
+    /// balance valued into `currency`. A context whose currency already matches is taken at par (no feed); a missing
+    /// cross-currency feed reverts and that (sucker, chain) is silently skipped (conservative, bias-low).
     /// @param projectId The ID of the project.
     /// @param currency The currency to value the combined balance into.
     /// @param decimals The decimal precision for the returned value.
@@ -112,9 +127,9 @@ interface IJBSuckerRegistry {
         returns (uint256 balance);
 
     /// @notice The cumulative peer-chain surplus across all remote peer chains for a project, valued into a currency.
-    /// @dev Dedups same-peer active suckers by freshest snapshot, then sums each sucker's surplus valued into
-    /// `currency`. A context whose currency already matches is taken at par (no feed); a missing cross-currency feed
-    /// reverts and that sucker is silently skipped (conservative, bias-low).
+    /// @dev Aggregates over every (sucker, chain) pair and dedups per chain by freshest record, then sums each chain's
+    /// surplus valued into `currency`. A context whose currency already matches is taken at par (no feed); a missing
+    /// cross-currency feed reverts and that (sucker, chain) is silently skipped (conservative, bias-low).
     /// @param projectId The ID of the project.
     /// @param currency The currency to value the combined surplus into.
     /// @param decimals The decimal precision for the returned value.

package/src/libraries/JBSuckerLib.sol

@@ -12,10 +12,13 @@ import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadat
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 
 import {IJBPeerChainAdjustedAccounts} from "../interfaces/IJBPeerChainAdjustedAccounts.sol";
+import {IJBSuckerRegistry} from "../interfaces/IJBSuckerRegistry.sol";
 import {JBPeerChainAdjustedAccountsLib} from "./JBPeerChainAdjustedAccountsLib.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";
 
@@ -34,20 +37,25 @@ library JBSuckerLib {
     uint256 internal constant _CURRENT_RULESET_OF_RETURN_BYTES = (9 + 19) * 32;
 
     //*********************************************************************//
-    // ---------------------- external transactions ---------------------- //
+    // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Build the cross-chain accounting snapshot (total supply plus per-context surplus and balance).
+    /// @notice Build the cross-chain accounting gossip bundle (the local chain's record plus known peer records).
     /// @dev Extracted from `JBSucker.syncAccountingData` to reduce child contract bytecode. Called via DELEGATECALL.
-    /// The snapshot carries each context's surplus and balance in its own currency, without price-feed valuation.
+    /// Each record carries its source chain's surplus and balance per context in that context's own currency, without
+    /// price-feed valuation.
     /// @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 ID.
+    /// @param exceptChainId The destination chain, excluded from the gathered peer records.
     /// @param messageVersion The message format version.
-    /// @param sourceTimestamp The monotonic source freshness key for this snapshot.
+    /// @param sourceTimestamp The monotonic source freshness key for the local chain's record.
     /// @return snapshot The constructed accounting snapshot.
     function buildAccountingSnapshot(
         IJBDirectory directory,
+        IJBSuckerRegistry registry,
         uint256 projectId,
+        uint256 exceptChainId,
         uint8 messageVersion,
         uint256 sourceTimestamp
     )
@@ -55,34 +63,39 @@ library JBSuckerLib {
         view
         returns (JBAccountingSnapshot memory snapshot)
     {
-        // Snapshot the project's per-context surplus and balance, un-valued. No price oracle is consulted on send.
-        (uint256 localTotalSupply, JBSourceContext[] memory sourceContexts) =
-            _snapshotAccountsOf({directory: directory, projectId: projectId});
-
         // Construct the accounting-only message without any token-local merkle root.
         snapshot = JBAccountingSnapshot({
             version: messageVersion,
-            sourceTotalSupply: localTotalSupply,
-            sourceContexts: sourceContexts,
-            sourceTimestamp: sourceTimestamp
+            accounts: _buildGossipBundle({
+                directory: directory,
+                registry: registry,
+                projectId: projectId,
+                exceptChainId: exceptChainId,
+                sourceTimestamp: sourceTimestamp
+            })
         });
     }
 
-    /// @notice Build the cross-chain snapshot message (total supply plus per-context surplus and balance).
+    /// @notice Build the cross-chain root message, carrying the accounting gossip bundle alongside the outbox root.
     /// @dev Extracted from `JBSucker._buildSnapshotAndSend` to reduce child contract bytecode. Called via DELEGATECALL.
-    /// The snapshot carries each context's surplus and balance in its own currency, without price-feed valuation.
+    /// Each accounting record carries its source chain's surplus and balance per context in that context's own
+    /// currency, without price-feed valuation.
     /// @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 ID.
+    /// @param exceptChainId The destination chain, excluded from the gathered peer records.
     /// @param remoteToken The remote token bytes32 address.
     /// @param amount The amount of terminal tokens to bridge.
     /// @param nonce The outbox nonce for this send.
     /// @param root The merkle root of the outbox tree.
     /// @param messageVersion The message format version.
-    /// @param sourceTimestamp The monotonic source freshness key for this snapshot.
+    /// @param sourceTimestamp The monotonic source freshness key for the local chain's record.
     /// @return message The constructed JBMessageRoot.
     function buildSnapshotMessage(
         IJBDirectory directory,
+        IJBSuckerRegistry registry,
         uint256 projectId,
+        uint256 exceptChainId,
         bytes32 remoteToken,
         uint256 amount,
         uint64 nonce,
@@ -94,26 +107,22 @@ library JBSuckerLib {
         view
         returns (JBMessageRoot memory message)
     {
-        // Snapshot the project's per-context surplus and balance, un-valued. No price oracle is consulted on send.
-        (uint256 localTotalSupply, JBSourceContext[] memory sourceContexts) =
-            _snapshotAccountsOf({directory: directory, projectId: projectId});
-
-        // Construct the cross-chain message with the per-context snapshot data.
+        // Construct the cross-chain message with the outbox root and the accounting gossip bundle.
         message = JBMessageRoot({
             version: messageVersion,
             token: remoteToken,
             amount: amount,
             remoteRoot: JBInboxTreeRoot({nonce: nonce, root: root}),
-            sourceTotalSupply: localTotalSupply,
-            sourceContexts: sourceContexts,
-            sourceTimestamp: sourceTimestamp
+            accounts: _buildGossipBundle({
+                directory: directory,
+                registry: registry,
+                projectId: projectId,
+                exceptChainId: exceptChainId,
+                sourceTimestamp: sourceTimestamp
+            })
         });
     }
 
-    //*********************************************************************//
-    // ------------------------- external views -------------------------- //
-    //*********************************************************************//
-
     /// @notice Compute a branch root from a leaf, branch, and index. Wraps MerkleLib.branchRoot so its
     /// ~170 lines of unrolled assembly live in the library's bytecode instead of each sucker's.
     /// @param item The leaf hash.
@@ -177,10 +186,130 @@ library JBSuckerLib {
         }
     }
 
+    /// @notice Folds a peer chain's raw source contexts into per-currency surplus and balance, resolving each to a
+    /// local currency.
+    /// @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.
+    /// @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.
+    /// @return contexts The per-currency surplus and balance for the chain.
+    function foldPeerContexts(
+        IJBDirectory directory,
+        uint256 projectId,
+        address[] memory localTokens,
+        JBSourceContext[] memory rawContexts
+    )
+        external
+        view
+        returns (JBPeerChainContext[] memory contexts)
+    {
+        uint256 numRaw = rawContexts.length;
+
+        // The folded set is no larger than the raw set, so allocate to that upper bound and track the populated length.
+        JBPeerChainContext[] memory buf = new JBPeerChainContext[](numRaw);
+        uint256 count;
+
+        for (uint256 i; i < numRaw;) {
+            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]});
+
+            // Fold into an existing entry that matches on BOTH currency AND decimals, or append a new one.
+            bool merged;
+            for (uint256 j; j < count;) {
+                if (buf[j].currency == ctxCurrency && buf[j].decimals == ctxDecimals) {
+                    buf[j].surplus = _saturatingAddU128(buf[j].surplus, ctxSurplus);
+                    buf[j].balance = _saturatingAddU128(buf[j].balance, ctxBalance);
+                    merged = true;
+                    break;
+                }
+                unchecked {
+                    ++j;
+                }
+            }
+            if (!merged) {
+                buf[count++] = JBPeerChainContext({
+                    currency: ctxCurrency, decimals: ctxDecimals, surplus: ctxSurplus, balance: ctxBalance
+                });
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Trim the over-allocated buffer to the folded length.
+        contexts = new JBPeerChainContext[](count);
+        for (uint256 k; k < count;) {
+            contexts[k] = buf[k];
+            unchecked {
+                ++k;
+            }
+        }
+    }
+
     //*********************************************************************//
     // ------------------------- internal views -------------------------- //
     //*********************************************************************//
 
+    /// @notice Assemble a cross-chain accounting gossip bundle: the local chain's own record plus every peer-chain
+    /// record the project's suckers currently hold, excluding the destination chain.
+    /// @dev The local record is taken fresh from `_snapshotAccountsOf` (including any data-hook adjusted accounts). The
+    /// 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.
+    /// @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.
+    /// @param exceptChainId The destination chain, excluded from the gathered peer records.
+    /// @param sourceTimestamp The local record's freshness key.
+    /// @return accounts The assembled gossip bundle, with the local chain's record first.
+    function _buildGossipBundle(
+        IJBDirectory directory,
+        IJBSuckerRegistry registry,
+        uint256 projectId,
+        uint256 exceptChainId,
+        uint256 sourceTimestamp
+    )
+        internal
+        view
+        returns (JBChainAccounting[] memory accounts)
+    {
+        // Snapshot the local chain's own supply and per-context surplus/balance, un-valued. No price oracle is read.
+        (uint256 localTotalSupply, JBSourceContext[] memory localContexts) =
+            _snapshotAccountsOf({directory: directory, projectId: projectId});
+
+        // Gather every other chain's record the project knows, deduped per chain and minus the destination. The
+        // accounting gossip is best-effort, so a reverting registry must never break the essential root/token bridge:
+        // catch the failure and propagate just this chain's own record.
+        JBChainAccounting[] memory peers;
+        try registry.peerChainAccountsOf({projectId: projectId, exceptChainId: exceptChainId}) returns (
+            JBChainAccounting[] memory gathered
+        ) {
+            peers = gathered;
+        } catch {}
+
+        // The local record leads; forwarded peer records follow verbatim, 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
+        });
+        for (uint256 i; i < peers.length;) {
+            accounts[i + 1] = peers[i];
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     /// @notice Builds the project's per-accounting-context surplus and balance, each in the context's own currency,
     /// with no price-feed valuation.
     /// @dev Loops every terminal and accounting context, reading the raw per-token surplus (requested in the token's
@@ -253,6 +382,42 @@ library JBSuckerLib {
         } catch {}
     }
 
+    /// @notice The project's authoritative accounting-context currency for a local token, or a convention fallback.
+    /// @dev Reads the token's accounting context from its primary terminal via length-guarded staticcalls, so a missing
+    /// or non-conforming directory/terminal just yields the fallback. Falls back to `uint32(uint160(token))` when the
+    /// project has no local accounting context for the token yet. The accounting-context currency is immutable.
+    /// @param directory The JB directory to look up the project's primary terminal for the token.
+    /// @param projectId The project whose accounting context to read.
+    /// @param token The local token to resolve the currency of.
+    /// @return currency The project's accounting-context currency for the token.
+    function _currencyOf(
+        IJBDirectory directory,
+        uint256 projectId,
+        address token
+    )
+        internal
+        view
+        returns (uint32 currency)
+    {
+        // Resolve the project's primary terminal for the token. An `address` return needs a full word.
+        (bool terminalOk, bytes memory terminalData) =
+            address(directory).staticcall(abi.encodeCall(IJBDirectory.primaryTerminalOf, (projectId, token)));
+        if (terminalOk && terminalData.length >= 32) {
+            address terminal = abi.decode(terminalData, (address));
+            if (terminal != address(0)) {
+                // Read the token's accounting context. The struct encodes to three words.
+                (bool contextOk, bytes memory contextData) =
+                    terminal.staticcall(abi.encodeCall(IJBTerminal.accountingContextForTokenOf, (projectId, token)));
+                if (contextOk && contextData.length >= 96) {
+                    JBAccountingContext memory accountingContext = abi.decode(contextData, (JBAccountingContext));
+                    if (accountingContext.currency != 0) return accountingContext.currency;
+                }
+            }
+        }
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return uint32(uint160(token));
+    }
+
     /// @notice Optional project-specific adjusted accounts to add to peer-chain snapshots.
     /// @dev Reads the current ruleset's data hook and asks it for extra supply plus per-context surplus/balance, each
     /// in the context's own currency. Non-supporting or broken hooks are ignored so a project's baseline snapshot stays
@@ -339,6 +504,21 @@ library JBSuckerLib {
         });
     }
 
+    /// @notice Adds two `uint128` amounts, saturating at `type(uint128).max` instead of overflowing.
+    /// @dev Saturation keeps a pathological peer record from reverting the read path; the cap can only under-report a
+    /// remote amount, the safe direction.
+    /// @param a The first amount.
+    /// @param b The second amount.
+    /// @return The saturated sum.
+    function _saturatingAddU128(uint128 a, uint128 b) internal pure returns (uint128) {
+        unchecked {
+            uint256 sum = uint256(a) + uint256(b);
+            // The cast only runs when `sum <= type(uint128).max`, so it cannot truncate.
+            // forge-lint: disable-next-line(unsafe-typecast)
+            return sum > type(uint128).max ? type(uint128).max : uint128(sum);
+        }
+    }
+
     /// @notice Builds the local accounting values used in outbound peer-chain snapshots.
     /// @dev Project token supply stays a single currency-agnostic scalar. Surplus and balance are emitted per context
     /// in that context's currency, with no price-feed valuation. The receiving chain folds each context into its
@@ -372,6 +552,15 @@ library JBSuckerLib {
         if (address(controller) != address(0) && address(controller).code.length != 0) {
             (additionalSupply, hookContexts) =
                 _peerChainAdjustedAccountsOf({controller: controller, projectId: projectId});
+            // Fail soft to the baseline snapshot. A malformed hook that returns a `supply` which would overflow the
+            // controller supply contributes no extra supply or contexts — the documented fail-soft model — instead
+            // of
+            // reverting the whole snapshot and bricking every outbound send (`toRemote` / `syncAccountingData`) while
+            // the hook stays active.
+            if (additionalSupply > type(uint256).max - localTotalSupply) {
+                additionalSupply = 0;
+                hookContexts = new JBSourceContext[](0);
+            }
             localTotalSupply += additionalSupply;
         }
 

package/src/structs/JBAccountingSnapshot.sol

@@ -1,19 +1,17 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-import {JBSourceContext} from "./JBSourceContext.sol";
+import {JBChainAccounting} from "./JBChainAccounting.sol";
 
-/// @notice A peer-chain accounting snapshot, without any token-local merkle root or transported value.
+/// @notice A cross-chain accounting gossip bundle, sent without any token-local merkle root or transported value.
+/// @dev Carries the sending chain's own accounting record plus every peer-chain record the sender currently holds,
+/// each stamped with its originating chain's freshness key. The receiving chain stores the freshest record per source
+/// chain, so accounting propagates across a hub-and-spoke sucker mesh without a direct sucker between every pair of
+/// chains.
 /// @custom:member version The message format version. Used to reject incompatible messages.
-/// @custom:member sourceTotalSupply The total token supply (including reserved tokens) on the source chain at the
-/// time the message was sent. Used by the receiving chain to track cross-chain supply for cash out tax calculations.
-/// @custom:member sourceContexts The source chain's surplus and balance per accounting context, each in the context's
-/// own currency and decimals, un-valued.
-/// @custom:member sourceTimestamp A monotonic source-chain freshness key for the snapshot. Used by the receiving
-/// chain to reject stale surplus/balance/supply updates.
+/// @custom:member accounts One accounting record per source chain known to the sender: its own chain plus every peer
+/// chain it has heard about, excluding the destination chain.
 struct JBAccountingSnapshot {
     uint8 version;
-    uint256 sourceTotalSupply;
-    JBSourceContext[] sourceContexts;
-    uint256 sourceTimestamp;
+    JBChainAccounting[] accounts;
 }

package/src/structs/JBChainAccounting.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+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.
+/// @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 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 {
+    uint256 chainId;
+    uint256 totalSupply;
+    JBSourceContext[] contexts;
+    uint256 timestamp;
+}

package/src/structs/JBMessageRoot.sol

@@ -1,31 +1,27 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+import {JBChainAccounting} from "./JBChainAccounting.sol";
 import {JBInboxTreeRoot} from "./JBInboxTreeRoot.sol";
-import {JBSourceContext} from "./JBSourceContext.sol";
 
-/// @notice Information about the remote (inbox) tree's root, passed in a message from the remote chain.
-/// @dev The snapshot carries surplus and balance per accounting context in each context's own currency — the source
-/// chain performs no price-feed valuation. The receiving chain folds each context into its same-asset local context at
-/// par, so no price oracle is consulted in the cross-chain surplus path. Project token supply stays a single
-/// currency-agnostic scalar.
+/// @notice Information about the remote (inbox) tree's root passed in a message from the remote chain, carried
+/// alongside a cross-chain accounting gossip bundle.
+/// @dev The accounting bundle carries the sending chain's own record plus every peer-chain record the sender holds,
+/// each in the originating chain's own currency and decimals, un-valued. The receiving chain folds each context into
+/// its same-asset local context at par and stores the freshest record per source chain, so no price oracle is
+/// consulted in the cross-chain surplus path and accounting propagates across the sucker mesh as roots are relayed.
+/// Project token supply stays a single currency-agnostic scalar per source chain.
 /// @custom:member version The message format version. Used to reject incompatible messages.
 /// @custom:member token The remote token address (bytes32 for cross-VM compatibility with SVM).
 /// @custom:member amount The amount of tokens to send.
 /// @custom:member remoteRoot The root of the merkle tree.
-/// @custom:member sourceTotalSupply The total token supply (including reserved tokens) on the source chain at the
-/// time the message was sent. Used by the receiving chain to track cross-chain supply for cash out tax calculations.
-/// @custom:member sourceContexts The source chain's surplus and balance per accounting context, each in the context's
-/// own currency and decimals, un-valued. The receiving chain resolves each entry to its same-asset local context and
-/// folds it in at par.
-/// @custom:member sourceTimestamp A monotonic source-chain freshness key for the snapshot. Used by the receiving
-/// chain to reject stale surplus/balance/supply updates without blocking token-local inbox root updates.
+/// @custom:member accounts One accounting record per source chain known to the sender: its own chain plus every peer
+/// chain it has heard about, excluding the destination chain. Used by the receiving chain to track cross-chain
+/// supply, surplus, and balance for cash out tax calculations.
 struct JBMessageRoot {
     uint8 version;
     bytes32 token;
     uint256 amount;
     JBInboxTreeRoot remoteRoot;
-    uint256 sourceTotalSupply;
-    JBSourceContext[] sourceContexts;
-    uint256 sourceTimestamp;
+    JBChainAccounting[] accounts;
 }

package/src/structs/PeerAccountScratch.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {JBChainAccounting} from "./JBChainAccounting.sol";
+
+/// @notice Scratch space used while gathering the freshest accounting record per peer chain across a project's suckers.
+/// @dev Sized to the total records across the project's suckers for in-memory de-duplication; `chainCount` tracks
+/// populated entries. Bundled into one struct so the gather helpers stay under the stack-slot limit.
+/// @custom:member chainIds The peer chain IDs that have been observed.
+/// @custom:member records The selected record for each observed peer chain.
+/// @custom:member hasActiveRecord Whether the selected record came from an active sucker instead of a deprecated one.
+/// @custom:member chainCount The number of populated peer-chain entries.
+struct PeerAccountScratch {
+    uint256[] chainIds;
+    JBChainAccounting[] records;
+    bool[] hasActiveRecord;
+    uint256 chainCount;
+}