@bananapus/suckers-v6 0.0.71 → 0.0.73

package/README.md

@@ -13,7 +13,7 @@
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — scope, entrypoints, and reading order for security review.
 - [SKILLS.md](./SKILLS.md) — reusable patterns and gotchas distilled from this codebase.
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity conventions used across this repo.
-- [CHANGELOG.md](./CHANGELOG.md) — versioned change history.
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 migration changelog.
 
 The codebase includes multiple bridge variants, but the canonical deployment and discovery tooling in this repo is narrower than the full runtime surface. Treat the deployment scripts and helper libraries as the source of truth for what is operationally supported today.
 
@@ -31,7 +31,7 @@ Use this repo when the requirement is canonical project-token movement across ch
 
 The main idea is not "bridge the token contract." The main idea is "bridge a Juicebox claim plus enough information to recreate the project-token position on the remote chain."
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -39,7 +39,7 @@ The main idea is not "bridge the token contract." The main idea is "bridge a Jui
 | `JBSuckerRegistry` | Registry for per-project sucker deployments, deployer allowlists, and shared bridge fee settings. |
 | Chain-specific suckers | Transport-specific implementations for OP Stack, Arbitrum, CCIP, and related environments. |
 
-## Mental Model
+## Mental model
 
 Each sucker pair has two jobs:
 
@@ -51,7 +51,7 @@ That means every bridge path has two trust surfaces:
 - the shared sucker accounting and Merkle logic
 - the bridge-specific transport implementation
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBSucker.sol`
 2. `src/JBSuckerRegistry.sol`
@@ -59,7 +59,7 @@ That means every bridge path has two trust surfaces:
 4. the matching deployer under `src/deployers/`
 5. `src/utils/MerkleLib.sol`
 
-## Integration Traps
+## Integration traps
 
 - do not reason about suckers as if they were generic ERC-20 bridges
 - root ordering and message delivery semantics matter as much as proof format
@@ -67,13 +67,13 @@ That means every bridge path has two trust surfaces:
 - peer contexts are merged only when they share both currency and decimals; same-currency contexts with different decimals are kept separate and valued independently at read time, never summed across precisions
 - emergency and deprecation paths are part of normal operational safety
 
-## Where State Lives
+## Where state lives
 
 - per-claim and tree progression state: the sucker pair
 - deployment inventory and shared operational config: `JBSuckerRegistry`
 - bridge transport assumptions: the chain-specific implementation and its external counterparties
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/unit/registry.t.sol`
 2. `test/unit/multi_chain_evolution.t.sol`
@@ -101,11 +101,11 @@ Useful scripts:
 - `npm run deploy:testnets`
 - `npm run analyze`
 
-## Deployment Notes
+## Deployment notes
 
 This package supports multiple bridge families and is intentionally split into bridge-specific deployers. Operational support is narrower than "all theoretically bridgeable chains" and should be taken from the configured deployers, helper libraries, and deployment scripts in this repo.
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -125,14 +125,14 @@ script/
   helpers/
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - out-of-order root delivery can make some claims unavailable until an operator uses an emergency path
 - bridge-specific transport assumptions matter as much as the shared sucker logic
 - token mapping and deprecation controls are governance-sensitive surfaces
 - a bridge that stays live operationally still may not be economically safe for every asset or chain pair
 
-## For AI Agents
+## For AI agents
 
 - Do not summarize this repo as a generic token bridge.
 - Always separate shared sucker logic from bridge-specific transport behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.71",
+  "version": "0.0.73",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,7 +11,8 @@
     "references/",
     "remappings.txt",
     "script/",
-    "src/"
+    "src/",
+    "!src/archive/"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -26,18 +27,18 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.81",
-    "@bananapus/permission-ids-v6": "^0.0.28",
+    "@bananapus/core-v6": "^0.0.82",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@chainlink/contracts-ccip": "1.6.4",
-    "@chainlink/local": "0.2.7",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1",
-    "@uniswap/v3-core": "github:Uniswap/v3-core#6562c52e8f75f0c10f9deaf44861847585fc8129",
-    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#b325bb0905d922ae61fcc7df85ee802e8df5e96c",
+    "@prb/math": "4.1.2",
     "@uniswap/v4-core": "1.0.2",
     "solady": "0.1.26"
   },
   "devDependencies": {
+    "@chainlink/local": "0.2.9",
+    "@uniswap/v3-core": "1.0.1",
+    "@uniswap/v3-periphery": "1.4.4",
     "@sphinx-labs/plugins": "0.33.3"
   }
 }

package/references/operations.md

@@ -1,12 +1,12 @@
-# Suckers Operations
+# Suckers operations
 
-## Configuration Surface
+## Configuration surface
 
 - [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) is the first stop for deployer allowlists, shared fees, project inventory, and deprecation helpers.
 - Transport-specific deployers in `src/deployers/` are where chain-specific constants and bridge addresses live.
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) is where deployment-time environment wiring belongs.
 
-## Change Checklist
+## Change checklist
 
 - If you edit base sucker accounting, verify claim flow across at least one chain-specific implementation.
 - If you edit token mapping logic, re-check the registry and deployer assumptions that feed it.
@@ -15,13 +15,13 @@
 - If you edit snapshot or claim-boundary logic, verify `numberOfClaimsSent`, peer snapshots, and emergency exit behavior together.
 - If you touch bridge-specific code, confirm whether the real bug is transport-side or shared accounting-side.
 
-## Common Failure Modes
+## Common failure modes
 
 - Cross-chain issue is blamed on transport when the root or token mapping was wrong before message delivery.
 - Registry configuration drifts from what a deployer or external operator expects.
 - Emergency hatches or deprecation paths are stale because nobody exercises them until stress conditions arrive.
 
-## Useful Proof Points
+## Useful proof points
 
 - [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), and [`test/TestRegressionGaps.sol`](../test/TestRegressionGaps.sol) for security-sensitive assumptions.
 - [`test/InteropCompat.t.sol`](../test/InteropCompat.t.sol) when the problem is deployment wiring rather than runtime logic.

package/references/runtime.md

@@ -1,20 +1,20 @@
-# Suckers Runtime
+# Suckers runtime
 
-## Core Roles
+## Core roles
 
 - [`src/JBSucker.sol`](../src/JBSucker.sol) owns the shared prepare, relay, claim, token-mapping, and lifecycle logic.
 - [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) owns project-to-sucker inventory, deployer allowlists, and shared remote-fee settings.
 - Chain-specific sucker contracts such as [`src/JBArbitrumSucker.sol`](../src/JBArbitrumSucker.sol), [`src/JBOptimismSucker.sol`](../src/JBOptimismSucker.sol), [`src/JBCCIPSucker.sol`](../src/JBCCIPSucker.sol), and [`src/JBCeloSucker.sol`](../src/JBCeloSucker.sol) own transport-specific delivery and verification.
 - Matching deployers under `src/deployers/` own clone and transport configuration.
 
-## Runtime Path
+## Runtime path
 
 1. Local state is prepared into a claimable Merkle leaf.
 2. A root is relayed to the peer chain through the bridge-specific transport.
 3. The remote side records the root in its inbox state.
 4. Claimants prove inclusion and recreate their position on the destination chain.
 
-## High-Risk Areas
+## High-risk areas
 
 - Token mapping: mapping mistakes break economic equivalence, not just UX.
 - Root ordering and replay protection: message sequencing is part of correctness.
@@ -22,7 +22,7 @@
 - Shared accounting vs transport logic: many incidents stem from confusing these layers.
 - Peer snapshots and `numberOfClaimsSent`: these guard against double-spend at the cost of conservative locking when timing goes wrong.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`test/ForkMainnet.t.sol`](../test/ForkMainnet.t.sol), [`test/ForkArbitrum.t.sol`](../test/ForkArbitrum.t.sol), [`test/ForkCelo.t.sol`](../test/ForkCelo.t.sol), and [`test/ForkOPStack.t.sol`](../test/ForkOPStack.t.sol) for real transport assumptions.
 - [`test/ForkSwap.t.sol`](../test/ForkSwap.t.sol), [`test/ForkClaimMainnet.t.sol`](../test/ForkClaimMainnet.t.sol), and [`test/SuckerRegressions.t.sol`](../test/SuckerRegressions.t.sol) for pinned cross-chain edge cases.

package/src/JBArbitrumSucker.sol

@@ -34,6 +34,8 @@ contract JBArbitrumSucker is JBSucker, IJBArbitrumSucker {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the provided transport payment is insufficient to cover the cost of the Arbitrum retryable
+    /// ticket.
     error JBArbitrumSucker_NotEnoughGas(uint256 payment, uint256 cost);
 
     //*********************************************************************//

package/src/JBCCIPSucker.sol

@@ -36,11 +36,22 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the configured CCIP router address is the zero address.
     error JBCCIPSucker_InvalidRouter(address router);
+
+    /// @notice Thrown when an incoming root message claims a positive amount but no tokens were delivered with it.
     error JBCCIPSucker_PositiveRootWithoutDelivery(uint256 rootAmount);
+
+    /// @notice Thrown when the amount of tokens delivered is less than the amount declared in the root message.
     error JBCCIPSucker_UnderDeliveredAmount(uint256 delivered, uint256 rootAmount);
+
+    /// @notice Thrown when an incoming message delivers an unexpected number of token transfers.
     error JBCCIPSucker_UnexpectedDeliveredTokens(uint256 count);
+
+    /// @notice Thrown when an incoming message has an unrecognized message type prefix.
     error JBCCIPSucker_UnknownMessageType(uint8 messageType);
+
+    /// @notice Thrown when the token delivered with an incoming message does not match the expected token.
     error JBCCIPSucker_WrongDeliveredToken(address delivered, address expected);
 
     //*********************************************************************//

package/src/JBOptimismSucker.sol

@@ -76,6 +76,7 @@ contract JBOptimismSucker is JBSucker, IJBOptimismSucker {
 
     /// @notice Checks if the `sender` (`_msgSender()`) is a valid representative of the remote peer.
     /// @param sender The message's sender.
+    /// @return valid A flag if the sender is a valid representative of the remote peer.
     function _isRemotePeer(address sender) internal override returns (bool valid) {
         return sender == address(OPMESSENGER) && _toBytes32(OPMESSENGER.xDomainMessageSender()) == peer();
     }

package/src/JBSucker.sol

@@ -68,31 +68,88 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when a terminal-token or project-token amount being bridged exceeds the `uint128` cap enforced
+    /// for cross-VM compatibility.
     error JBSucker_AmountExceedsUint128(uint256 amount);
+
+    /// @notice Thrown when a token mapping specifies a bridging gas limit below the minimum required to safely deliver
+    /// an ERC-20 on the remote chain.
     error JBSucker_BelowMinGas(uint256 minGas, uint256 minGasLimit);
+
+    /// @notice Thrown when an outbound action is attempted while the sucker is deprecated (or no longer accepting
+    /// sends).
     error JBSucker_Deprecated(JBSuckerState state);
+
+    /// @notice Thrown when a deprecation is scheduled for a time sooner than the minimum allowed delay.
     error JBSucker_DeprecationTimestampTooSoon(uint256 givenTime, uint256 minimumTime);
+
+    /// @notice Thrown when a native token transport payment is required but no `msg.value` was sent.
     error JBSucker_ExpectedMsgValue(uint256 msgValue);
+
+    /// @notice Thrown when a merkle leaf index is greater than or equal to the maximum number of leaves the tree can
+    /// hold.
     error JBSucker_IndexOutOfRange(uint256 index);
+
+    /// @notice Thrown when the amount to add to the project's balance exceeds the funds available to the sucker.
     error JBSucker_InsufficientBalance(uint256 amount, uint256 balance);
+
+    /// @notice Thrown when the `msg.value` sent is less than the required `toRemoteFee`.
     error JBSucker_InsufficientMsgValue(uint256 received, uint256 expected);
+
+    /// @notice Thrown when an incoming bridge message has a format version that does not match the expected version.
     error JBSucker_InvalidMessageVersion(uint8 received, uint8 expected);
+
+    /// @notice Thrown when the native token is mapped to a remote token that is neither the native token nor the zero
+    /// address.
     error JBSucker_InvalidNativeRemoteAddress(bytes32 remoteToken);
+
+    /// @notice Thrown when a claim's merkle proof does not validate against the stored inbox root.
     error JBSucker_InvalidProof(bytes32 root, bytes32 inboxRoot);
+
+    /// @notice Thrown when a leaf at the given index has already been executed for the given token.
     error JBSucker_LeafAlreadyExecuted(address token, uint256 index);
+
+    /// @notice Thrown when no terminal can be found for the given project and token.
     error JBSucker_NoTerminalForToken(uint256 projectId, address token);
+
+    /// @notice Thrown when the caller is not a valid representative of the remote peer sucker.
     error JBSucker_NotPeer(bytes32 caller);
+
+    /// @notice Thrown when a send is attempted but there is nothing new in the outbox to bridge.
     error JBSucker_NothingToSend(address token, uint256 outboxBalance, uint256 treeCount, uint256 numberOfClaimsSent);
+
+    /// @notice Thrown when an account attempts to claim a retained failed-fee refund but is owed nothing.
     error JBSucker_NoRetainedToRemoteFee(address account);
+
+    /// @notice Thrown when an account attempts to claim a retained failed transport-payment refund but is owed nothing.
     error JBSucker_NoRetainedTransportPaymentRefund(address account);
+
+    /// @notice Thrown when a native token refund transfer to the beneficiary fails.
     error JBSucker_RefundFailed(address beneficiary, uint256 amount);
+
+    /// @notice Thrown when a token mapping targets a remote token that another local token has already reserved.
     error JBSucker_RemoteTokenAlreadyMapped(bytes32 remoteToken, address localToken);
+
+    /// @notice Thrown when remapping a local token whose outbox tree already has entries, which is no longer permitted.
     error JBSucker_TokenAlreadyMapped(address localToken, bytes32 mappedTo);
+
+    /// @notice Thrown when an emergency-hatch action is attempted for a token whose emergency hatch state does not
+    /// allow it.
     error JBSucker_TokenHasInvalidEmergencyHatchState(address token);
+
+    /// @notice Thrown when an action references a token that has not been mapped to a remote token.
     error JBSucker_TokenNotMapped(address token);
+
+    /// @notice Thrown when `msg.value` is sent for an action that expects none.
     error JBSucker_UnexpectedMsgValue(uint256 value);
+
+    /// @notice Thrown when a required beneficiary address is the zero address.
     error JBSucker_ZeroBeneficiary(bytes32 beneficiary);
+
+    /// @notice Thrown when bridging is attempted for a project that has no ERC-20 token deployed.
     error JBSucker_ZeroERC20Token(uint256 projectId);
+
+    /// @notice Thrown when a bridge is queued with zero project tokens.
     error JBSucker_ZeroProjectTokenCount();
 
     //*********************************************************************//
@@ -171,14 +228,16 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     uint256 public retainedTransportPaymentRefundBalance;
 
     /// @notice The retained failed-fee ETH owed to each original `toRemote` caller.
+    /// @custom:param account The address owed the retained ETH.
     mapping(address account => uint256 amount) public retainedToRemoteFeeOf;
 
     /// @notice The retained failed transport-payment refund ETH owed to each original bridge caller.
+    /// @custom:param account The address owed the retained ETH.
     mapping(address account => uint256 amount) public retainedTransportPaymentRefundOf;
 
     /// @notice The source chain freshness key for the most recent accepted peer snapshot.
     /// @dev Only snapshots with a strictly newer source freshness key are accepted, preventing stale rollbacks.
-    /// The historical name is retained for ABI compatibility with the `JBMessageRoot.sourceTimestamp` field.
+    /// Named to align with the `JBMessageRoot.sourceTimestamp` field it tracks.
     /// Returns 0 if no snapshot has been received yet.
     uint256 public snapshotTimestamp;
 
@@ -252,10 +311,9 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @dev A zero value preserves the default same-address deterministic peer.
     bytes32 private _peer;
 
-    /// @notice The peer chain's per-currency surplus and balance from the latest snapshot. Rebuilt in full each time a
-    /// fresher snapshot is received, so a context that dropped out of the new snapshot is simply absent — no
-    /// per-entry
-    /// versioning or clearing is needed. A read sums these and values them into the requested currency.
+    /// @notice The peer chain's per-currency surplus and balance from the latest snapshot.
+    /// @dev Rebuilt from each fresher snapshot; dropped contexts are absent without per-entry versioning or clearing.
+    /// A read sums these and values them into the requested currency.
     JBPeerChainContext[] private _peerContexts;
 
     //*********************************************************************//
@@ -401,7 +459,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     }
 
     /// @notice Emergency escape hatch: lets a user reclaim their project tokens and terminal tokens on the chain they
-    /// originally deposited from, when the bridge has become permanently non-functional. Must be enabled by the project
+    /// deposited from, when the bridge has become permanently non-functional. Must be enabled by the project
     /// owner via `enableEmergencyHatchFor`.
     /// @param claimData The terminal token, merkle tree leaf, and proof for the claim.
     function exitThroughEmergencyHatch(JBClaim calldata claimData) external override {
@@ -586,8 +644,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
     /// @notice Configure which remote-chain tokens each local terminal token maps to, enabling (or disabling) those
     /// tokens for cross-chain bridging. Setting a remote token to `bytes32(0)` disables bridging and flushes any
-    /// pending outbox entries. Requires `MAP_SUCKER_TOKEN` permission from the project owner (or called by the
-    /// registry during deployment).
+    /// pending outbox entries. Requires `MAP_SUCKER_TOKEN` permission from the project owner or deployment registry.
     /// @param maps A list of local and remote terminal token addresses to map, and minimum amount/gas limits for
     /// bridging them.
     function mapTokens(JBTokenMapping[] calldata maps) external payable override {
@@ -646,8 +703,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     ///   For EVM peers: the EVM address left-padded to 32 bytes via `_toBytes32`.
     ///   For SVM peers: the full 32-byte Solana public key.
     /// @param minTokensReclaimed The minimum amount of terminal tokens to cash out for. If the amount cashed out is
-    /// less
-    /// than this, the transaction will revert.
+    /// less than this, the transaction will revert.
     /// @param token The address of the terminal token to cash out for.
     function prepare(
         uint256 projectTokenCount,
@@ -683,7 +739,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             revert JBSucker_TokenNotMapped({token: token});
         }
 
-        // Make sure that the sucker still allows sending new messaged.
+        // Make sure that the sucker still allows sending new messages.
         _requireSendingEnabled();
 
         // Transfer the tokens to this contract.
@@ -711,7 +767,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// 14-day buffer ensures in-flight messages have time to arrive before the sucker fully shuts down.
     /// @param timestamp The time after which the sucker will be deprecated. Or `0` to remove the upcoming deprecation.
     function setDeprecation(uint40 timestamp) external override {
-        // As long as the sucker has not started letting users withdrawal, its deprecation time can be
+        // As long as the sucker has not started letting users withdraw, its deprecation time can be
         // extended/shortened.
         _requireSendingEnabled();
 
@@ -845,9 +901,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     }
 
     /// @notice The peer chain total supply bundled with the peer chain ID and snapshot freshness key.
-    /// @dev Lets aggregators (e.g. `JBSuckerRegistry`) read the value, the peer chain it belongs to, and its
-    /// freshness in one call instead of three separate staticcalls. The `value` is identical to
-    /// `peerChainTotalSupply`.
+    /// @dev Lets aggregators (e.g. `JBSuckerRegistry`) read the value, peer chain, and freshness in one call instead
+    /// of three separate staticcalls. The `value` is identical to `peerChainTotalSupply`.
     /// @return A `JBPeerChainValue` with the total supply, peer chain ID, and snapshot freshness key.
     function peerChainTotalSupplyValue() external view returns (JBPeerChainValue memory) {
         return JBPeerChainValue({
@@ -930,14 +985,14 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             return JBSuckerState.DEPRECATION_PENDING;
         }
 
-        // The sucker will no longer send new roots to the pair, but it will accept new incoming roots.
-        // Additionally it will let users exit here now that we can no longer send roots/tokens.
+        // The sucker no longer sends new roots to the pair, but it accepts new incoming roots.
+        // Additionally it lets users exit here, since the sucker can no longer send roots/tokens.
         // forge-lint: disable-next-line(block-timestamp)
         if (block.timestamp < _deprecatedAfter) {
             return JBSuckerState.SENDING_DISABLED;
         }
 
-        // The sucker is now in the final state of deprecation. It will no longer allow new roots.
+        // The sucker is in the final state of deprecation. It does not allow new roots.
         return JBSuckerState.DEPRECATED;
     }
 
@@ -1015,8 +1070,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         deployer = _msgSender();
     }
 
-    /// @notice Map an ERC-20 token on the local chain to an ERC-20 token on the remote chain, allowing that token to be
-    /// bridged.
+    /// @notice Map an ERC-20 token on the local chain to a remote-chain ERC-20 token for bridging.
     /// @param map The local and remote terminal token addresses to map, and minimum amount/gas limits for bridging
     /// them.
     function mapToken(JBTokenMapping calldata map) public payable override {
@@ -1027,7 +1081,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     // --------------------- internal transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Adds funds to the projects balance.
+    /// @notice Adds funds to the project's balance.
     /// @param token The terminal token to add to the project's balance.
     /// @param amount The amount of terminal tokens to add to the project's balance.
     /// @param cachedProjectId The cached project ID to avoid redundant storage reads.
@@ -1125,7 +1179,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     )
         internal
     {
-        // Guard against amounts that would overflow uint128 on SVM (INTEROP-5).
+        // Guard against amounts that would overflow uint128 on SVM, which caps bridged amounts at uint128.
         if (terminalTokenAmount > type(uint128).max) revert JBSucker_AmountExceedsUint128(terminalTokenAmount);
         if (projectTokenCount > type(uint128).max) revert JBSucker_AmountExceedsUint128(projectTokenCount);
         // Build a hash based on the token amounts, the beneficiary, and the attribution metadata.
@@ -1161,13 +1215,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @return valid Whether the sender is the remote peer.
     function _isRemotePeer(address sender) internal virtual returns (bool valid);
 
-    /// @notice Map an ERC-20 token on the local chain to an ERC-20 token on the remote chain, allowing that token to be
-    /// bridged or disabled.
+    /// @notice Map an ERC-20 token on the local chain to a remote-chain ERC-20 token, or disable bridging.
     /// @dev Once a token has outbox tree entries (`_outboxOf[token].tree.count != 0`), it cannot be remapped to a
     /// different remote token -- it can only be disabled by mapping to `address(0)`, which triggers a final root
     /// flush to settle outstanding claims. This permanence prevents double-spending: if a remapping were allowed
     /// after outbox activity, the same local funds could be claimed against two different remote tokens. A
-    /// misconfigured mapping therefore requires deploying a new sucker. Re-enabling a previously disabled mapping
+    /// misconfigured mapping therefore requires deploying a new sucker. Re-enabling a disabled mapping
     /// (back to the same remote token) is supported.
     /// @dev Remote tokens are also unique per local token within this sucker. The source side keeps separate
     /// outboxes/nonces per local token, but the destination side stores roots under the remote token address. Sharing
@@ -1324,7 +1377,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Ensure the token is mapped to an address on the remote chain.
         if (remoteToken.addr == bytes32(0)) revert JBSucker_TokenNotMapped(token);
 
-        // Make sure that the sucker still allows sending new messaged.
+        // Make sure that the sucker still allows sending new messages.
         _requireSendingEnabled();
 
         // Drain the outbox: read balance/nonce/root, clear balance, advance nonce and numberOfClaimsSent.
@@ -1464,7 +1517,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     }
 
     /// @notice Validates a branch root against the expected root.
-    /// @dev This is a virtual function to allow a tests to override the behavior, it should never be overwritten
+    /// @dev This is a virtual function to allow tests to override the behavior; it should never be overridden
     /// otherwise.
     /// @param expectedRoot The expected merkle root to validate against.
     /// @param leafHash The precomputed leaf hash (`_buildTreeHash` output) for the leaf being validated.
@@ -1489,8 +1542,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         }
     }
 
-    /// @notice Validates a leaf as being in the outbox merkle tree and not being send over the amb, and registers the
-    /// leaf as executed (to prevent double-spending).
+    /// @notice Validates a leaf as being in the outbox merkle tree and not having been sent over the amb, and registers
+    /// the leaf as executed (to prevent double-spending).
     /// @dev Reverts if the leaf is invalid.
     /// @dev IMPORTANT: Emergency exit safety depends on `numberOfClaimsSent` being accurately tracked.
     /// `numberOfClaimsSent` is updated in `_sendRoot` to equal `outbox.tree.count` at the time the root is sent
@@ -1513,7 +1566,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// @param terminalToken The terminal token that the project tokens were cashed out for.
     /// @param terminalTokenAmount The amount of terminal tokens reclaimed by the cash out.
     /// @param beneficiary The beneficiary of the project tokens (bytes32 for cross-VM compatibility).
-    /// @param index The index of the leaf to prove in the terminal token's inbox tree.
+    /// @param index The index of the leaf to prove in the terminal token's outbox tree.
     /// @param leaves The leaves that prove that the leaf at the `index` is in the tree (i.e. the merkle branch that the
     /// leaf is on).
     function _validateForEmergencyExit(
@@ -1540,10 +1593,10 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         }
 
         // Check that this claim is within the bounds of who can claim.
-        // If the root that this leaf is in was already send then we can not let the user claim here.
+        // If the root that this leaf is in was already sent then we can not let the user claim here.
         // As it could have also been received by the peer sucker, which would then let the user claim on each side.
         // NOTE: We are comparing the *count* and the *index*, so `count - 1` is the last index that was sent.
-        // A count of 0 means that no root has ever been send for this token, so everyone can claim.
+        // A count of 0 means that no root has ever been sent for this token, so everyone can claim.
         JBOutboxTree storage outboxOfToken = _outboxOf[terminalToken];
         if (outboxOfToken.numberOfClaimsSent != 0 && outboxOfToken.numberOfClaimsSent - 1 >= index) {
             revert JBSucker_LeafAlreadyExecuted({token: terminalToken, index: index});
@@ -1551,8 +1604,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
 
         {
             // We re-use the same `_executedFor` mapping but we use a different slot.
-            // We can not use the regular mapping, since this claim is done for tokens being send from here to the pair.
-            // where the regular mapping is for tokens that were send on the pair to here. Even though these may seem
+            // We can not use the regular mapping, since this claim is done for tokens being sent from here to the pair.
+            // where the regular mapping is for tokens that were sent on the pair to here. Even though these may seem
             // similar they are actually completely unrelated.
             address emergencyExitAddress = address(bytes20(keccak256(abi.encode(terminalToken))));
 
@@ -1832,7 +1885,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         return bytes32(uint256(uint160(addr)));
     }
 
-    /// @notice Allow sucker implementations to add/override mapping rules to suite their specific needs.
+    /// @notice Allow sucker implementations to add/override mapping rules to suit their specific needs.
     /// @param map The token mapping to validate.
     function _validateTokenMapping(JBTokenMapping calldata map) internal pure virtual {
         bool isNative = map.localToken == JBConstants.NATIVE_TOKEN;

package/src/JBSuckerRegistry.sol

@@ -35,10 +35,19 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the owner attempts to set a `toRemoteFee` greater than the maximum allowed fee.
     error JBSuckerRegistry_FeeExceedsMax(uint256 fee, uint256 max);
+
+    /// @notice Thrown when a sucker deployment references a deployer that is not approved by this registry.
     error JBSuckerRegistry_InvalidDeployer(IJBSuckerDeployer deployer);
+
+    /// @notice Thrown when an action references a sucker that is not registered to the given project.
     error JBSuckerRegistry_SuckerDoesNotBelongToProject(uint256 projectId, address sucker);
+
+    /// @notice Thrown when a sucker is being removed from active listings but is not deprecated.
     error JBSuckerRegistry_SuckerIsNotDeprecated(address sucker, JBSuckerState suckerState);
+
+    /// @notice Thrown when a sucker reports a zero peer chain ID and cannot identify a real peer chain.
     error JBSuckerRegistry_ZeroPeerChainId(address sucker);
 
     //*********************************************************************//
@@ -82,7 +91,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     //*********************************************************************//
 
     /// @notice Tracks whether the specified sucker deployer is approved by this registry.
-    /// @custom:member deployer The address of the deployer to check.
+    /// @custom:param deployer The address of the deployer to check.
     mapping(address deployer => bool) public override suckerDeployerIsAllowed;
 
     /// @notice The ETH fee (in wei) paid into the fee project via terminal.pay() on each toRemote() call.
@@ -93,7 +102,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
     //*********************************************************************//
 
     /// @notice Tracks the suckers for the specified project.
-    mapping(uint256 => EnumerableMap.AddressToUintMap) internal _suckersOf;
+    /// @custom:param projectId The ID of the project whose suckers are tracked.
+    mapping(uint256 projectId => EnumerableMap.AddressToUintMap) internal _suckersOf;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -146,8 +156,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         return exists && (val == _SUCKER_EXISTS || val == _SUCKER_DEPRECATED);
     }
 
-    /// @notice Values one sucker's raw peer-chain balance into a currency, bundled with the peer chain ID and
-    /// freshness.
+    /// @notice Values one sucker's raw peer-chain balance into a currency with peer chain ID and freshness.
     /// @dev Exposed as an external self-call boundary so `totalRemoteBalanceOf` can `try` it and drop a single sucker
     /// whose price feed is missing. A context whose currency already matches `currency` folds in at par (no feed read);
     /// a missing cross-currency feed reverts, and the aggregator catches it and skips just this sucker.
@@ -196,8 +205,7 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         return JBPeerChainValue({value: value, peerChainId: chainId, snapshotTimestamp: snapshot});
     }
 
-    /// @notice Values one sucker's raw peer-chain surplus into a currency, bundled with the peer chain ID and
-    /// freshness.
+    /// @notice Values one sucker's raw peer-chain surplus into a currency with peer chain ID and freshness.
     /// @dev Exposed as an external self-call boundary so `totalRemoteSurplusOf` can `try` it and drop a single sucker
     /// whose price feed is missing. A context whose currency already matches `currency` folds in at par (no feed read);
     /// a missing cross-currency feed reverts, and the aggregator catches it and skips just this sucker.
@@ -654,9 +662,9 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         emit SuckerDeployerAllowed({deployer: deployer, caller: _msgSender()});
     }
 
-    /// @notice Adds multiple suckers deployer to the allowlist.
+    /// @notice Adds multiple sucker deployers to the allowlist.
     /// @dev Can only be called by this contract's owner (initially project ID 1, or JuiceboxDAO).
-    /// @param deployers The address of the deployer to add.
+    /// @param deployers The addresses of the deployers to add.
     function allowSuckerDeployers(address[] calldata deployers) public override onlyOwner {
         // Cache _msgSender() to avoid redundant calls in the loop.
         address sender = _msgSender();