@bananapus/suckers-v6 0.0.70 → 0.0.72

package/README.md

@@ -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.70",
+  "version": "0.0.72",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "3.2.0",
-    "@bananapus/core-v6": "^0.0.78",
+    "@bananapus/core-v6": "^0.0.81",
     "@bananapus/permission-ids-v6": "^0.0.28",
     "@chainlink/contracts-ccip": "1.6.4",
     "@chainlink/local": "0.2.7",

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;
 
@@ -401,7 +460,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 {
@@ -683,7 +742,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 +770,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();
 
@@ -930,14 +989,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;
     }
 
@@ -1027,7 +1086,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 +1184,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.
@@ -1167,7 +1226,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
     /// 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
@@ -1299,9 +1358,8 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // Record the balance before the cash out for the sanity check.
         uint256 balanceBefore = _balanceOf({token: token, addr: address(this)});
 
-        // Cash out the project tokens for terminal tokens. Suckers are a transparent value-mover (the bridge
-        // accounting is the entirety of their function) — they're not a fee-paying entry point for any referrer,
-        // so `referralProjectId: 0` is correct.
+        // Cash out the project tokens for terminal tokens. Suckers are a transparent value-mover; the bridge
+        // accounting is the entirety of their function.
         reclaimedAmount = terminal.cashOutTokensOf({
             holder: address(this),
             projectId: cachedProjectId,
@@ -1309,8 +1367,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             tokenToReclaim: token,
             minTokensReclaimed: minTokensReclaimed,
             beneficiary: payable(address(this)),
-            metadata: bytes(""),
-            referralProjectId: 0
+            metadata: bytes("")
         });
 
         // Sanity check to make sure we received the expected amount.
@@ -1326,7 +1383,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.
@@ -1466,7 +1523,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.
@@ -1491,8 +1548,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
@@ -1515,7 +1572,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(
@@ -1542,10 +1599,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});
@@ -1553,8 +1610,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))));
 
@@ -1834,7 +1891,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 ---------------------------- //
@@ -654,9 +664,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();

package/src/archive/JBSwapCCIPSucker.sol

@@ -87,16 +87,37 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when no received batch covers the claim's leaf index, so no conversion rate can be applied.
     error JBSwapCCIPSucker_BatchNotReceived(uint64 nonce);
+
+    /// @notice Thrown when the Uniswap V4 unlock callback is invoked by an address other than the pool manager.
     error JBSwapCCIPSucker_CallerNotPoolManager(address caller);
+
+    /// @notice Thrown when an incoming batch reuses a nonce that has already been received.
     error JBSwapCCIPSucker_DuplicateBatch(uint64 nonce);
+
+    /// @notice Thrown when the bridge token is the zero address or matches the wrapped native token.
     error JBSwapCCIPSucker_InvalidBridgeToken(address bridgeToken, address wrappedNativeToken);
+
+    /// @notice Thrown when a swap retry is attempted for a token and nonce that has no pending failed swap.
     error JBSwapCCIPSucker_NoPendingSwap(address localToken, uint64 nonce, bool retrySwapLocked);
+
+    /// @notice Thrown when the self-only swap entry point is called by an address other than this contract.
     error JBSwapCCIPSucker_OnlySelf(address caller, address expected);
+
+    /// @notice Thrown when an incoming root claims a positive amount but no bridge tokens were delivered with it.
     error JBSwapCCIPSucker_PositiveRootWithoutDelivery(uint256 rootAmount);
+
+    /// @notice Thrown when a swap produces no output tokens.
     error JBSwapCCIPSucker_SwapFailed(address tokenIn, address tokenOut, uint256 amountIn);
+
+    /// @notice Thrown when a claim or swap is attempted while another swap is already in progress.
     error JBSwapCCIPSucker_SwapPending(uint64 nonce);
+
+    /// @notice Thrown when an incoming message delivers an unexpected number of token transfers.
     error JBSwapCCIPSucker_UnexpectedDeliveredTokens(uint256 count);
+
+    /// @notice Thrown when the token delivered with an incoming message does not match the expected token.
     error JBSwapCCIPSucker_WrongDeliveredToken(address delivered, address expected);
 
     //*********************************************************************//

package/src/archive/JBSwapCCIPSuckerDeployer.sol

@@ -22,7 +22,10 @@ contract JBSwapCCIPSuckerDeployer is JBCCIPSuckerDeployer, IJBSwapCCIPSuckerDepl
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when the swap configuration is set with a zero-address bridge token.
     error JBSwapCCIPSuckerDeployer_InvalidSwapConfig(address bridgeToken);
+
+    /// @notice Thrown when the swap configuration is set after it has already been configured.
     error JBSwapCCIPSuckerDeployer_SwapAlreadyConfigured(address bridgeToken);
 
     //*********************************************************************//

package/src/archive/JBSwapPoolLib.sol

@@ -46,12 +46,25 @@ library JBSwapPoolLib {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when a swap amount exceeds the `uint128` range required by the pool interface.
     error JBSwapPoolLib_AmountOverflow(uint256 amount);
+
+    /// @notice Thrown when a swap callback is invoked by an address other than the expected pool.
     error JBSwapPoolLib_CallerNotPool(address caller);
+
+    /// @notice Thrown when a pool's oracle history is too short to serve the required TWAP window.
     error JBSwapPoolLib_InsufficientTwapHistory(address pool, uint256 availableWindow, uint256 requiredWindow);
+
+    /// @notice Thrown when the selected pool has no liquidity to swap against.
     error JBSwapPoolLib_NoLiquidity(address pool, PoolId poolId);
+
+    /// @notice Thrown when no eligible V3 or V4 pool can be found for the given token pair.
     error JBSwapPoolLib_NoPool(address tokenIn, address tokenOut);
+
+    /// @notice Thrown when a swap consumes less than the full requested input amount.
     error JBSwapPoolLib_PartialFill(uint256 consumed, uint256 requested);
+
+    /// @notice Thrown when a swap's output is below the minimum acceptable amount after slippage.
     error JBSwapPoolLib_SlippageExceeded(uint256 amountOut, uint256 minAmountOut);
 
     //*********************************************************************//

package/src/archive/README.md

@@ -0,0 +1,5 @@
+# Archived suckers (non-canonical)
+
+The contracts in this directory are retained for reference only. They are not part of the canonical
+runtime surface and are out of scope for audits, the house-style sweep, and deployment. Treat any
+inline language here as historical and do not depend on these implementations.

package/src/deployers/JBSuckerDeployer.sol

@@ -26,11 +26,23 @@ abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerD
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when configuration is attempted but the deployer (singleton or layer-specific config) has already
+    /// been configured.
     error JBSuckerDeployer_AlreadyConfigured(address singleton, bool layerSpecificConfigurationIsSet);
+
+    /// @notice Thrown when a sucker is deployed before the deployer's singleton implementation has been set.
     error JBSuckerDeployer_DeployerIsNotConfigured(address singleton);
+
+    /// @notice Thrown when the layer-specific configuration is not properly set after configuration.
     error JBSuckerDeployer_InvalidLayerSpecificConfiguration(address configurator);
+
+    /// @notice Thrown when a sucker is deployed before the layer-specific configuration has been set.
     error JBSuckerDeployer_LayerSpecificNotConfigured(address configurator);
+
+    /// @notice Thrown when the caller is not the address authorized to configure this deployer.
     error JBSuckerDeployer_Unauthorized(address caller, address expected);
+
+    /// @notice Thrown when the configurator address provided is the zero address.
     error JBSuckerDeployer_ZeroConfiguratorAddress(address configurator);
 
     //*********************************************************************//
@@ -51,9 +63,11 @@ abstract contract JBSuckerDeployer is ERC2771Context, JBPermissioned, IJBSuckerD
     //*********************************************************************//
 
     /// @notice Whether a given address was deployed by this deployer.
-    mapping(address => bool) public override isSucker;
+    /// @custom:param sucker The address to check.
+    mapping(address sucker => bool) public override isSucker;
 
     /// @notice The singleton used to clone suckers.
+    /// @dev Write-once via `configureSingleton`; the clone implementation for every sucker this deployer produces.
     JBSucker public singleton;
 
     //*********************************************************************//

package/src/interfaces/IJBSucker.sol

@@ -24,6 +24,7 @@ interface IJBSucker is IERC165 {
     /// @param projectTokenCount The number of project tokens claimed.
     /// @param terminalTokenAmount The amount of terminal tokens involved.
     /// @param index The leaf index in the inbox tree.
+    /// @param metadata The opaque, caller-defined payload carried by the claimed leaf.
     /// @param caller The address that performed the claim.
     event Claimed(
         bytes32 beneficiary,
@@ -52,6 +53,7 @@ interface IJBSucker is IERC165 {
     /// @param root The new outbox tree root after insertion.
     /// @param projectTokenCount The number of project tokens cashed out.
     /// @param terminalTokenAmount The amount of terminal tokens reclaimed.
+    /// @param metadata The opaque, caller-defined payload carried by the outbox leaf.
     /// @param caller The address that performed the insertion.
     event InsertToOutboxTree(
         bytes32 indexed beneficiary,

package/src/libraries/CCIPHelper.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 /// @notice CCIP chain-specific constants used across Juicebox sucker contracts.
 library CCIPHelper {
+    /// @notice Thrown when a lookup is requested for a chain ID that has no configured CCIP constants.
     error CCIPHelper_UnsupportedChain(uint256 chainId);
     /// @notice The CCIP router address for Ethereum mainnet.
     address public constant ETH_ROUTER = 0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D;

package/src/structs/JBLeaf.sol

@@ -6,11 +6,9 @@ pragma solidity ^0.8.0;
 /// @custom:member beneficiary The beneficiary of the leaf.
 /// @custom:member projectTokenCount The number of project tokens to claim.
 /// @custom:member terminalTokenAmount The amount of terminal tokens to claim.
-/// @custom:member metadata Opaque, caller-defined attribution payload that travels with the leaf inside the merkle
-/// root. Use cases include cross-chain referral split hooks tagging a leaf with `(originChainId, referralProjectId)`
-/// so the destination contract can settle the bridged value atomically. The sucker protocol itself never inspects
-/// this field — it's covered by the leaf hash, so receivers can trust the value once the merkle proof verifies.
-/// Pass `bytes32(0)` when no attribution context is needed.
+/// @custom:member metadata Opaque, caller-defined payload that travels with the leaf inside the merkle root. The
+/// sucker protocol itself never inspects this field — it's covered by the leaf hash, so receivers can trust the value
+/// once the merkle proof verifies. Pass `bytes32(0)` when no extra claim context is needed.
 struct JBLeaf {
     uint256 index;
     bytes32 beneficiary;

package/src/utils/MerkleLib.sol

@@ -5,6 +5,7 @@ pragma solidity 0.8.28;
  * @title MerkleLib
  * @author Illusory Systems Inc.
  * @notice An incremental merkle tree modeled on the eth2 deposit contract.
+ * @dev Vendored upstream library; its Doxygen-style NatSpec deviates from the repo's `///` house style.
  *
  */
 library MerkleLib {
@@ -12,6 +13,7 @@ library MerkleLib {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when a leaf is inserted into a merkle tree that has already reached its maximum number of leaves.
     error MerkleLib_InsertTreeIsFull(uint256 size, uint256 maxLeaves);
 
     //*********************************************************************//
@@ -82,7 +84,7 @@ library MerkleLib {
     /**
      * @notice Inserts a given node (leaf) into the merkle tree in storage.
      * @dev Operates directly on storage, writing only the single branch entry that changes (plus count).
-     * This avoids the 33-slot memory round-trip of the previous memory-based approach.
+     * This writes only the changed branch slot instead of round-tripping all 33 slots through memory.
      * @dev Reverts if the tree is already full.
      * @param tree The storage reference to the tree.
      * @param node Element to insert into tree.