@bananapus/suckers-v6 0.0.29 → 0.0.31

package/RISKS.md

@@ -151,3 +151,11 @@ When the only available Uniswap pool for a cross-denomination swap is a hookless
 ### 10.9 Zero-value `prepare()` is allowed
 
 `prepare()` does not reject `projectTokenCount == 0`. A zero-value check would be trivially bypassed by passing `1` instead, so it provides no real protection against remap-window consumption. The cost to create a leaf with `projectTokenCount = 1` is negligible (1 wei of project tokens). The one-time remap window is protected by the token mapping's `enabled` flag and the outbox tree count, not by minimum deposit requirements.
+
+### 10.10 Cross-chain currency uses standardized `JBCurrencyIds.ETH` (1), not local token addresses
+
+Snapshot messages encode surplus and balance values using `JBCurrencyIds.ETH` (currency ID `1`) as the cross-chain currency identifier, not `uint32(uint160(JBConstants.NATIVE_TOKEN))` (currency ID `61166`). This is intentional: `NATIVE_TOKEN` (`0x000...EEEe`) is a local sentinel meaning "the native token on this chain," which may represent different assets on different networks (e.g., ETH on mainnet, MATIC on Polygon). A standardized semantic currency ID is required for cross-chain values to be comparable.
+
+On the consuming side, contracts like `REVOwner` and `REVLoans` query sucker-reported values using `uint32(uint160(NATIVE_TOKEN))` — the local terminal convention. The `JBPrices` oracle in `JBSuckerLib.convertPeerValue` resolves the conversion between currency ID `1` (ETH) and currency ID `61166` (native token) when a price feed is registered for the pair. If no feed exists, `convertPeerValue` returns `0`, which is acceptable: it means the project has not configured cross-chain pricing for that token pair, and remote values are simply not factored into local calculations.
+
+Projects that need accurate cross-chain surplus and supply accounting should register a price feed for the `1 ↔ 61166` pair via `JBPrices`. On chains where the native token is ETH, this is a 1:1 identity feed. On chains where the native token is not ETH, the feed should reflect the actual exchange rate.

package/package.json

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

package/src/JBArbitrumSucker.sol

@@ -206,8 +206,8 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
             // slither-disable-next-line calls-loop,unused-return
             IArbL2GatewayRouter(address(GATEWAYROUTER))
                 .outboundTransfer({
-                    l1Token: _toAddress(remoteToken.addr), to: peerAddress, amount: amount, data: bytes("")
-                });
+                l1Token: _toAddress(remoteToken.addr), to: peerAddress, amount: amount, data: bytes("")
+            });
         } else {
             // Otherwise, the token is the native token, and the amount will be sent as `msg.value`.
             nativeValue = amount;
@@ -269,8 +269,7 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
                     IL1ArbitrumGateway(gateway)
                 .getOutboundCalldata({
                     _token: token, _from: address(this), _to: _peerAddress(), _amount: amount, _data: bytes("")
-                })
-                .length;
+                }).length;
                 // slither-disable-next-line calls-loop
                 maxSubmissionCostERC20 = ARBINBOX.calculateRetryableSubmissionFee({
                     dataLength: outboundCalldataLength, baseFee: maxFeePerGas

package/src/JBSucker.sol

@@ -178,11 +178,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @dev The `currency` and `decimals` fields describe the denomination; `value` is the balance amount.
     JBDenominatedAmount private _peerChainBalance;
 
-    /// @notice Outbound project-wide snapshot counter. Incremented each time `_sendRoot` is called.
-    uint64 private _snapshotNonce;
-
-    /// @notice The highest snapshot nonce received from the peer chain. Used to reject stale shared-state updates.
-    uint64 private _peerSnapshotNonce;
+    /// @notice The `block.timestamp` from the source chain when the most recent accepted peer snapshot was taken.
+    /// @dev Only snapshots with a strictly newer source timestamp are accepted, preventing stale rollbacks.
+    /// Returns 0 if no snapshot has been received yet.
+    uint256 public snapshotTimestamp;
 
     //*********************************************************************//
     // ---------------------------- constructor -------------------------- //
@@ -400,12 +399,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             emit StaleRootRejected({token: localToken, receivedNonce: root.remoteRoot.nonce, currentNonce: inbox.nonce});
         }
 
-        // --- Project-wide shared state update (gated by snapshot nonce) ---
-        // The snapshot nonce is a project-wide counter independent of per-token outbox nonces.
+        // --- Project-wide shared state update (gated by source timestamp) ---
+        // Only accept snapshots whose source timestamp is strictly newer than the last accepted one.
         // This prevents a staler per-token message from rolling back shared state (surplus, balance, supply)
         // that was already updated by a fresher message for a different token.
-        if (root.snapshotNonce > _peerSnapshotNonce) {
-            _peerSnapshotNonce = root.snapshotNonce;
+        if (root.sourceTimestamp > snapshotTimestamp) {
+            snapshotTimestamp = root.sourceTimestamp;
 
             // Update unconditionally — a legitimate zero supply must clear phantom cached supply.
             peerChainTotalSupply = root.sourceTotalSupply;
@@ -875,12 +874,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // slither-disable-next-line calls-loop,unused-return
         IJBController(address(DIRECTORY.controllerOf(cachedProjectId)))
             .mintTokensOf({
-                projectId: cachedProjectId,
-                tokenCount: projectTokenAmount,
-                beneficiary: _toAddress(beneficiary),
-                memo: "",
-                useReservedPercent: false
-            });
+            projectId: cachedProjectId,
+            tokenCount: projectTokenAmount,
+            beneficiary: _toAddress(beneficiary),
+            memo: "",
+            useReservedPercent: false
+        });
     }
 
     /// @notice Inserts a new leaf into the outbox merkle tree for the specified `token`.
@@ -1489,7 +1488,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             nonce: nonce,
             root: root,
             messageVersion: MESSAGE_VERSION,
-            snapshotNonce: ++_snapshotNonce
+            sourceTimestamp: block.timestamp
         });
 
         // Send the root over the AMB (positional args — slither IR parser crashes on named args here).

package/src/JBSwapCCIPSucker.sol

@@ -273,6 +273,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
 
             address localToken = _toAddress(root.token);
             uint256 localAmount;
+            bool swapFailed;
 
             if (any2EvmMessage.destTokenAmounts.length == 1) {
                 Client.EVMTokenAmount memory tokenAmount = any2EvmMessage.destTokenAmounts[0];
@@ -284,7 +285,7 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
                     // Swap bridge token -> local token via best V3/V4 pool.
                     // Wrapped in try-catch so a swap failure doesn't revert the entire CCIP message
                     // (which would leave tokens stuck in the OffRamp). On failure, bridge tokens are
-                    // stored for later retry via `retrySwap`.
+                    // stored for later retry via `retrySwap` (written below, after nonce validation).
                     // slither-disable-next-line reentrancy-benign,reentrancy-events
                     try this.executeSwapExternal({
                         tokenIn: tokenAmount.token, tokenOut: localToken, amount: tokenAmount.amount
@@ -293,59 +294,78 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
                     ) {
                         localAmount = swapped;
                     } catch {
-                        // Store for later retry. Merkle root and batch range still get stored below.
-                        pendingSwapOf[localToken][root.remoteRoot.nonce] = PendingSwap({
-                            bridgeToken: tokenAmount.token, bridgeAmount: tokenAmount.amount, leafTotal: root.amount
-                        });
-                        // localAmount stays 0 — the conversion rate code below will set
-                        // localTotal: 0, gating claims until retrySwap succeeds.
+                        swapFailed = true;
+                        // localAmount stays 0 — pendingSwapOf and conversion rate are written
+                        // below, after fromRemote validates the nonce.
                     }
                 }
             }
 
-            // Record the batch range so _findNonceForLeafIndex can resolve leaf ownership
-            // independently of nonce ordering. Each nonce is self-describing: [start, end).
-            if (batchEnd > 0) {
-                _batchStartOf[localToken][root.remoteRoot.nonce] = batchStart;
-                _batchEndOf[localToken][root.remoteRoot.nonce] = batchEnd;
-                if (root.remoteRoot.nonce > _highestReceivedNonce[localToken]) {
-                    _highestReceivedNonce[localToken] = root.remoteRoot.nonce;
+            // Capture the inbox nonce before fromRemote to detect whether the root was accepted.
+            uint64 inboxNonceBefore = _inboxOf[localToken].nonce;
+
+            // Store the inbox merkle root for later claims.
+            // Must be called BEFORE writing batch metadata and conversion rates so that stale
+            // (duplicate/replayed) roots that fromRemote silently rejects do not overwrite
+            // metadata from the original accepted delivery.
+            this.fromRemote(root);
+
+            // Only write batch metadata and conversion rates if fromRemote accepted this root.
+            // fromRemote updates _inboxOf[localToken].nonce when the root's nonce is strictly
+            // greater than the current inbox nonce; stale roots are silently rejected.
+            // We detect acceptance by checking if the nonce actually changed.
+            if (_inboxOf[localToken].nonce > inboxNonceBefore) {
+                // Record the batch range so _findNonceForLeafIndex can resolve leaf ownership
+                // independently of nonce ordering. Each nonce is self-describing: [start, end).
+                if (batchEnd > 0) {
+                    _batchStartOf[localToken][root.remoteRoot.nonce] = batchStart;
+                    _batchEndOf[localToken][root.remoteRoot.nonce] = batchEnd;
+                    if (root.remoteRoot.nonce > _highestReceivedNonce[localToken]) {
+                        _highestReceivedNonce[localToken] = root.remoteRoot.nonce;
+                    }
+                }
+
+                // Store pendingSwapOf for failed swaps now that nonce is validated.
+                if (swapFailed) {
+                    Client.EVMTokenAmount memory failedTokenAmount = any2EvmMessage.destTokenAmounts[0];
+                    pendingSwapOf[localToken][root.remoteRoot.nonce] = PendingSwap({
+                        bridgeToken: failedTokenAmount.token,
+                        bridgeAmount: failedTokenAmount.amount,
+                        leafTotal: root.amount
+                    });
                 }
-            }
 
-            // Zero-output swap guard: When a swap succeeds but returns zero local tokens, the
-            // batch must NOT be marked claimable. Without this guard, `_addToBalance` would see
-            // `pendingSwapOf.bridgeAmount == 0` (no pending swap stored) and allow claims to
-            // proceed — minting the full bridged project-token amount while adding zero terminal
-            // backing, breaking cross-chain solvency.
-            //
-            // Route zero-output swaps into `pendingSwapOf` so the swap can be retried via
-            // `retrySwap` once pool conditions improve. Only store the conversion rate when
-            // the swap produced a positive local amount.
-            if (root.amount > 0) {
-                if (localAmount == 0 && any2EvmMessage.destTokenAmounts.length == 1) {
-                    Client.EVMTokenAmount memory zeroSwapTokenAmount = any2EvmMessage.destTokenAmounts[0];
-                    // Only route to pending if there were actual bridge tokens delivered.
-                    // If bridgeAmount is also 0 (zero-value batch), store the conversion rate
-                    // normally — there is nothing to retry.
-                    if (zeroSwapTokenAmount.amount > 0) {
-                        pendingSwapOf[localToken][root.remoteRoot.nonce] = PendingSwap({
-                            bridgeToken: zeroSwapTokenAmount.token,
-                            bridgeAmount: zeroSwapTokenAmount.amount,
-                            leafTotal: root.amount
-                        });
+                // Zero-output swap guard: When a swap succeeds but returns zero local tokens, the
+                // batch must NOT be marked claimable. Without this guard, `_addToBalance` would see
+                // `pendingSwapOf.bridgeAmount == 0` (no pending swap stored) and allow claims to
+                // proceed — minting the full bridged project-token amount while adding zero terminal
+                // backing, breaking cross-chain solvency.
+                //
+                // Route zero-output swaps into `pendingSwapOf` so the swap can be retried via
+                // `retrySwap` once pool conditions improve. Only store the conversion rate when
+                // the swap produced a positive local amount.
+                if (root.amount > 0 && !swapFailed) {
+                    if (localAmount == 0 && any2EvmMessage.destTokenAmounts.length == 1) {
+                        Client.EVMTokenAmount memory zeroSwapTokenAmount = any2EvmMessage.destTokenAmounts[0];
+                        // Only route to pending if there were actual bridge tokens delivered.
+                        // If bridgeAmount is also 0 (zero-value batch), store the conversion rate
+                        // normally — there is nothing to retry.
+                        if (zeroSwapTokenAmount.amount > 0) {
+                            pendingSwapOf[localToken][root.remoteRoot.nonce] = PendingSwap({
+                                bridgeToken: zeroSwapTokenAmount.token,
+                                bridgeAmount: zeroSwapTokenAmount.amount,
+                                leafTotal: root.amount
+                            });
+                        } else {
+                            _conversionRateOf[localToken][root.remoteRoot.nonce] =
+                                ConversionRate({leafTotal: root.amount, localTotal: 0});
+                        }
                     } else {
                         _conversionRateOf[localToken][root.remoteRoot.nonce] =
-                            ConversionRate({leafTotal: root.amount, localTotal: 0});
+                            ConversionRate({leafTotal: root.amount, localTotal: localAmount});
                     }
-                } else {
-                    _conversionRateOf[localToken][root.remoteRoot.nonce] =
-                        ConversionRate({leafTotal: root.amount, localTotal: localAmount});
                 }
             }
-
-            // Store the inbox merkle root for later claims.
-            this.fromRemote(root);
         } else {
             revert JBCCIPSucker_UnknownMessageType(messageType);
         }
@@ -405,10 +425,13 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         PendingSwap memory pending = pendingSwapOf[localToken][nonce];
         if (pending.bridgeAmount == 0) revert JBSwapCCIPSucker_NoPendingSwap();
 
-        // slither-disable-next-line reentrancy-no-eth,reentrancy-benign,reentrancy-events
+        // slither-disable-next-line reentrancy-no-eth,reentrancy-benign,reentrancy-events,reentrancy-eth
         uint256 localAmount =
             _executeSwap({tokenIn: pending.bridgeToken, tokenOut: localToken, amount: pending.bridgeAmount});
 
+        // Revert on zero output — matches outbound guard at toRemote.
+        if (localAmount == 0) revert JBSwapCCIPSucker_SwapFailed();
+
         // Update the conversion rate so claims can proceed, then clear the pending swap.
         _conversionRateOf[localToken][nonce] = ConversionRate({leafTotal: pending.leafTotal, localTotal: localAmount});
         delete pendingSwapOf[localToken][nonce];
@@ -430,7 +453,10 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         if (_retrySwapLocked) revert JBSwapCCIPSucker_SwapPending(0);
         // slither-disable-next-line events-maths
         _currentClaimLeafIndex = claimData.leaf.index + 1;
+        // slither-disable-next-line reentrancy-eth
         super.claim(claimData);
+        // Clear stale transient context to prevent leaking into same-tx emergency exits.
+        _currentClaimLeafIndex = 0;
     }
 
     //*********************************************************************//
@@ -453,14 +479,14 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         if (_currentClaimLeafIndex != 0) {
             uint64 nonce = _findNonceForLeafIndex({token: token, leafIndex: _currentClaimLeafIndex - 1});
             if (nonce != 0) {
+                // Gate on pending swaps — if a swap failed and hasn't been retried yet,
+                // claims must wait. This check must come BEFORE the leafTotal gate so that
+                // failed swaps (where _conversionRateOf was never written) still block claims.
+                if (pendingSwapOf[token][nonce].bridgeAmount > 0) {
+                    revert JBSwapCCIPSucker_SwapPending(nonce);
+                }
                 ConversionRate storage rate = _conversionRateOf[token][nonce];
                 if (rate.leafTotal > 0) {
-                    // Gate on pending swaps — if a swap failed and hasn't been retried yet,
-                    // claims must wait. Check pendingSwapOf rather than localTotal == 0 to
-                    // distinguish a pending swap from a legitimately zero-output swap.
-                    if (pendingSwapOf[token][nonce].bridgeAmount > 0) {
-                        revert JBSwapCCIPSucker_SwapPending(nonce);
-                    }
                     amount = amount * rate.localTotal / rate.leafTotal;
                 }
             }

package/src/libraries/JBSuckerLib.sol

@@ -219,7 +219,7 @@ library JBSuckerLib {
     /// @param nonce The outbox nonce for this send.
     /// @param root The merkle root of the outbox tree.
     /// @param messageVersion The message format version.
-    /// @param snapshotNonce The snapshot nonce (caller should pre-increment).
+    /// @param sourceTimestamp The `block.timestamp` on the source chain when the snapshot is taken.
     /// @return message The constructed JBMessageRoot.
     function buildSnapshotMessage(
         IJBDirectory directory,
@@ -229,7 +229,7 @@ library JBSuckerLib {
         uint64 nonce,
         bytes32 root,
         uint8 messageVersion,
-        uint64 snapshotNonce
+        uint256 sourceTimestamp
     )
         external
         view
@@ -268,7 +268,7 @@ library JBSuckerLib {
             sourceDecimals: _ETH_DECIMALS,
             sourceSurplus: ethSurplus,
             sourceBalance: ethBalance,
-            snapshotNonce: snapshotNonce
+            sourceTimestamp: sourceTimestamp
         });
     }
 

package/src/libraries/JBSwapPoolLib.sol

@@ -167,6 +167,12 @@ library JBSwapPoolLib {
                 IWrappedNativeToken(config.weth).withdraw(amountOut);
             }
         }
+
+        // V4 outputs native ETH for WETH-paired pools. If the caller requested WETH (not NATIVE_TOKEN),
+        // wrap the received ETH so the caller gets the token they expect.
+        if (isV4 && tokenOut != JBConstants.NATIVE_TOKEN && normalizedOut == config.weth) {
+            IWrappedNativeToken(config.weth).deposit{value: amountOut}();
+        }
     }
 
     /// @notice Execute the body of a V4 unlock callback. Called via DELEGATECALL from the sucker's
@@ -177,40 +183,50 @@ library JBSwapPoolLib {
     /// @return Encoded output amount.
     function executeV4UnlockCallback(IPoolManager poolManager, bytes calldata data) external returns (bytes memory) {
         // Decode the swap parameters packed during _executeV4Swap.
-        (PoolKey memory key, bool zeroForOne, int256 amountSpecified, uint160 sqrtPriceLimitX96, uint256 minAmountOut) =
-            abi.decode(data, (PoolKey, bool, int256, uint160, uint256));
-
-        // Execute the swap through the V4 PoolManager.
-        BalanceDelta delta = poolManager.swap({
-            key: key,
-            params: SwapParams({
-                zeroForOne: zeroForOne, amountSpecified: amountSpecified, sqrtPriceLimitX96: sqrtPriceLimitX96
-            }),
-            hookData: ""
-        });
+        (
+            PoolKey memory key,
+            bool zeroForOne,
+            int256 amountSpecified,
+            uint160 sqrtPriceLimitX96,
+            uint256 minAmountOut,
+            address weth
+        ) = abi.decode(data, (PoolKey, bool, int256, uint160, uint256, address));
 
-        // V4 sign convention: negative = we owe (input), positive = we're owed (output).
-        int128 delta0 = delta.amount0();
-        int128 delta1 = delta.amount1();
         uint256 amountIn;
         uint256 amountOut;
 
-        // Extract input and output amounts based on swap direction.
-        if (zeroForOne) {
-            amountIn = uint256(uint128(-delta0));
-            amountOut = uint256(uint128(delta1));
-        } else {
-            amountIn = uint256(uint128(-delta1));
-            amountOut = uint256(uint128(delta0));
-        }
+        {
+            // Execute the swap through the V4 PoolManager.
+            BalanceDelta delta = poolManager.swap({
+                key: key,
+                params: SwapParams({
+                    zeroForOne: zeroForOne, amountSpecified: amountSpecified, sqrtPriceLimitX96: sqrtPriceLimitX96
+                }),
+                hookData: ""
+            });
 
-        // Enforce the minimum output from the TWAP quote.
-        if (amountOut < minAmountOut) revert JBSwapPoolLib_SlippageExceeded(amountOut, minAmountOut);
+            // V4 sign convention: negative = we owe (input), positive = we're owed (output).
+            int128 delta0 = delta.amount0();
+            int128 delta1 = delta.amount1();
+
+            // Extract input and output amounts based on swap direction.
+            if (zeroForOne) {
+                amountIn = uint256(uint128(-delta0));
+                amountOut = uint256(uint128(delta1));
+            } else {
+                amountIn = uint256(uint128(-delta1));
+                amountOut = uint256(uint128(delta0));
+            }
+
+            // Enforce the minimum output from the TWAP quote.
+            if (amountOut < minAmountOut) revert JBSwapPoolLib_SlippageExceeded(amountOut, minAmountOut);
+        }
 
         // Settle input (pay what we owe to the PoolManager).
         Currency inputCurrency = zeroForOne ? key.currency0 : key.currency1;
         if (Currency.unwrap(inputCurrency) == address(0)) {
-            // Native ETH: settle by sending ETH value directly.
+            // Native ETH: unwrap WETH if needed, then settle by sending ETH value directly.
+            if (weth != address(0)) IWrappedNativeToken(weth).withdraw(amountIn);
             // slither-disable-next-line unused-return,arbitrary-send-eth
             poolManager.settle{value: amountIn}();
         } else {
@@ -826,17 +842,22 @@ library JBSwapPoolLib {
         // Determine swap direction based on currency ordering in the pool key.
         bool zeroForOne = Currency.unwrap(key.currency0) == v4In;
 
-        // Compute the sqrt price limit from the expected amounts.
-        uint160 sqrtPriceLimitX96 = JBSwapLib.sqrtPriceLimitFromAmounts({
-            amountIn: amount, minimumAmountOut: minAmountOut, zeroForOne: zeroForOne
-        });
+        // Build the encoded unlock data in a scoped block to avoid stack-too-deep.
+        bytes memory unlockData;
+        {
+            // Compute the sqrt price limit from the expected amounts.
+            uint160 sqrtPriceLimitX96 = JBSwapLib.sqrtPriceLimitFromAmounts({
+                amountIn: amount, minimumAmountOut: minAmountOut, zeroForOne: zeroForOne
+            });
+
+            // V4 uses negative amounts for exact-input swaps.
+            int256 exactInputAmount = -int256(amount);
 
-        // V4 uses negative amounts for exact-input swaps.
-        int256 exactInputAmount = -int256(amount);
+            unlockData = abi.encode(key, zeroForOne, exactInputAmount, sqrtPriceLimitX96, minAmountOut, config.weth);
+        }
 
         // Unlock the PoolManager and encode the swap parameters for the callback.
-        bytes memory result =
-            config.poolManager.unlock(abi.encode(key, zeroForOne, exactInputAmount, sqrtPriceLimitX96, minAmountOut));
+        bytes memory result = config.poolManager.unlock(unlockData);
 
         // Decode the output amount returned by the unlock callback.
         amountOut = abi.decode(result, (uint256));

package/src/structs/JBMessageRoot.sol

@@ -17,9 +17,8 @@ import {JBInboxTreeRoot} from "./JBInboxTreeRoot.sol";
 /// `sourceDecimals` precision.
 /// @custom:member sourceBalance The total recorded balance on the source chain, denominated in `sourceCurrency` at
 /// `sourceDecimals` precision.
-/// @custom:member snapshotNonce A project-wide counter that orders shared-state snapshots independently of per-token
-/// outbox nonces. Used by the receiving chain to reject stale surplus/balance/supply updates without blocking
-/// token-local inbox root updates.
+/// @custom:member sourceTimestamp The `block.timestamp` on the source chain when the snapshot was taken. Used by the
+/// receiving chain to reject stale surplus/balance/supply updates without blocking token-local inbox root updates.
 struct JBMessageRoot {
     uint8 version;
     bytes32 token;
@@ -30,5 +29,5 @@ struct JBMessageRoot {
     uint8 sourceDecimals;
     uint256 sourceSurplus;
     uint256 sourceBalance;
-    uint64 snapshotNonce;
+    uint256 sourceTimestamp;
 }