@bananapus/suckers-v6 0.0.13 → 0.0.15

package/ADMINISTRATION.md

@@ -56,7 +56,7 @@ Admin privileges and their scope in nana-suckers-v6.
 | `allowSuckerDeployers(deployers)` | Registry Owner | N/A (`onlyOwner`) | Global | Batch version: adds multiple deployer contracts to the allowlist. |
 | `removeSuckerDeployer(deployer)` | Registry Owner | N/A (`onlyOwner`) | Global | Removes a deployer contract from the allowlist, preventing future sucker deployments through it. |
 | `setToRemoteFee(fee)` | Registry Owner | N/A (`onlyOwner`) | Global | Sets the `toRemoteFee` applied to all suckers. The fee must be <= `MAX_TO_REMOTE_FEE` (0.001 ether). Emits `ToRemoteFeeChanged`. |
-| `deploySuckersFor(projectId, salt, configs)` | Project Owner | `DEPLOY_SUCKERS` | Per-project | Deploys one or more suckers for a project using allowlisted deployers. Hashes salt with `msg.sender` for deterministic cross-chain addresses. Also calls `mapTokens` on each newly created sucker. |
+| `deploySuckersFor(projectId, salt, configs)` | Project Owner | `DEPLOY_SUCKERS` | Per-project | Deploys one or more suckers for a project using allowlisted deployers. Hashes salt with `_msgSender()` (which equals `msg.sender` for direct calls, or the relayed sender for ERC-2771 meta-transactions) for deterministic cross-chain addresses. Also calls `mapTokens` on each newly created sucker. |
 | `removeDeprecatedSucker(projectId, sucker)` | Anyone | None | Per-project | Removes a fully `DEPRECATED` sucker from the registry. Permissionless but only succeeds if the sucker is in the `DEPRECATED` state. |
 
 ### JBSucker
@@ -110,7 +110,7 @@ The emergency hatch is a per-token escape mechanism for when a bridge becomes no
 - Prevents `mapToken()` from remapping or re-enabling the token (reverts with `JBSucker_TokenHasInvalidEmergencyHatchState`).
 - Enables `exitThroughEmergencyHatch()` for users whose outbox entries were never sent to the remote peer (entries with `index >= numberOfClaimsSent`).
 
-**Who can exit:** Any user with a valid outbox merkle proof for a leaf that was never sent over the bridge. The exit returns both the project tokens and the terminal tokens that were cashed out during `prepare()`.
+**Who can exit:** Any user with a valid outbox merkle proof for a leaf that was never sent over the bridge. The exit mints project tokens to the beneficiary and returns the terminal tokens to the project's terminal balance. The beneficiary can then cash out the minted project tokens through the normal Juicebox mechanism if desired.
 
 **Safety constraint:** Only leaves that were never communicated to the remote peer (i.e., `index >= outbox.numberOfClaimsSent`) can be emergency-exited. Leaves already sent over the bridge (index < `numberOfClaimsSent`) cannot be emergency-exited because they may have already been claimed on the remote chain.
 
@@ -136,7 +136,7 @@ The following values are set at deploy time and cannot be changed:
 | `REMOTE_CHAIN_SELECTOR` | `JBCCIPSucker` | Constructor (from deployer callback) | The CCIP chain selector for the remote chain. |
 | `WRAPPED_NATIVE` | `JBCeloSucker` | Constructor (from deployer callback) | The wrapped native token (WETH) on the local chain. |
 | `LAYER_SPECIFIC_CONFIGURATOR` | All deployers | Constructor | The address authorized to call one-time setup functions. |
-| `peer()` | `JBSucker` | Deterministic (defaults to `address(this)` via CREATE2) | The remote peer sucker address. Assumes identical deployment on both chains. |
+| `peer()` | `JBSucker` | Deterministic (returns `bytes32` via `_toBytes32(address(this))`) | The remote peer sucker address as `bytes32`. Defaults to the local address, relying on CREATE2 giving the same address on both chains. |
 | `deployer` | `JBSucker` | Set once in `initialize()` by `msg.sender` | The address that deployed this sucker clone (the deployer contract). |
 | `projectId()` | `JBSucker` | Set once in `initialize()` | The local project ID this sucker serves. |
 | Bridge/messenger/router addresses | All deployers | `setChainSpecificConstants()` (one-time) | Bridge infrastructure addresses, set once by the configurator. |
@@ -167,3 +167,14 @@ What admins **cannot** do:
 - **Cannot change the fee project.** `FEE_PROJECT_ID` is set at construction and is immutable. If the fee project's terminal changes or is removed, fee payments silently stop (best-effort design), but `toRemote()` still works.
 
 - **Can adjust the fee amount, within bounds.** The registry owner can call `setToRemoteFee()` on `JBSuckerRegistry` to adjust the fee globally for all suckers, but it is capped at `MAX_TO_REMOTE_FEE` (0.001 ether).
+
+## Bridge Infrastructure Risks
+
+Sucker security ultimately depends on the underlying bridge infrastructure (OP Cross-Domain Messenger, Arbitrum Inbox/Outbox, CCIP Router). Each sucker's `_isRemotePeer()` check trusts these bridges to faithfully report the sender of cross-chain messages. If a bridge itself is compromised, an attacker could forge messages that pass the peer check, potentially minting unbacked project tokens on the destination chain.
+
+**Mitigations available to project owners:**
+
+- **Emergency hatch.** If a bridge is suspected to be compromised for a specific token, the project owner (or `SUCKER_SAFETY` delegate) can call `enableEmergencyHatchFor()` to immediately disable bridging for that token and allow users to exit with their outbox entries locally.
+- **Deprecation.** If the bridge is broadly compromised, the project owner (or `SET_SUCKER_DEPRECATION` delegate) can deprecate the entire sucker via `setDeprecation()`, shutting down all new outbound and eventually inbound activity.
+
+**Fee delivery is best-effort.** The `toRemoteFee` is collected by calling `terminal.pay()` to the fee project during `toRemote()`. If this call reverts (e.g., the fee project has no native token terminal or its terminal is misconfigured), the fee is silently skipped and `toRemote()` proceeds normally. This ensures bridging availability is never blocked by fee infrastructure issues, but it also means fee revenue can be lost without any on-chain signal.

package/ARCHITECTURE.md

@@ -2,28 +2,37 @@
 
 ## Purpose
 
-Cross-chain token bridging for Juicebox V6. Allows project tokens and funds to move between EVM chains via Optimism, Arbitrum, and Chainlink CCIP bridges. Uses dual merkle trees (outbox/inbox) for claim verification.
+Cross-chain token bridging for Juicebox V6. Allows project tokens and funds to move between EVM chains via Optimism, Base, Celo (OP Stack), Arbitrum, and Chainlink CCIP bridges. Uses dual merkle trees (outbox/inbox) for claim verification.
 
 ## Contract Map
 
 ```
 src/
 ├── JBSucker.sol            — Abstract base: merkle tree management, prepare/claim logic, FEE_PROJECT_ID, reads toRemoteFee from REGISTRY (immutable IJBSuckerRegistry)
-├── JBBaseSucker.sol        — OP Stack base (Optimism, Base)
-├── JBOptimismSucker.sol    — Optimism/Base bridge implementation
+├── JBOptimismSucker.sol    — OP Stack bridge implementation (Optimism, Base, Celo)
+├── JBBaseSucker.sol        — Base chain sucker (extends JBOptimismSucker, overrides peerChainId for Base ↔ Ethereum)
+├── JBCeloSucker.sol        — Celo sucker (extends JBOptimismSucker, wraps ETH → WETH for bridging, custom gas token handling)
 ├── JBArbitrumSucker.sol    — Arbitrum bridge implementation
 ├── JBCCIPSucker.sol        — Chainlink CCIP bridge implementation
 ├── JBSuckerRegistry.sol    — Registry of suckers per project, deployment permissions, centralized toRemoteFee (owner-controlled, applies to all suckers)
 ├── deployers/
+│   ├── JBSuckerDeployer.sol        — Abstract base deployer (LibClone, singleton pattern)
 │   ├── JBOptimismSuckerDeployer.sol
+│   ├── JBBaseSuckerDeployer.sol
+│   ├── JBCeloSuckerDeployer.sol
 │   ├── JBArbitrumSuckerDeployer.sol
 │   └── JBCCIPSuckerDeployer.sol
 ├── enums/
-│   └── JBSuckerState.sol   — ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
+│   ├── JBSuckerState.sol   — ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
+│   └── JBLayer.sol         — L1 / L2 indicator (used by JBArbitrumSucker)
+├── interfaces/             — IJBSucker, IJBSuckerRegistry, IJBSuckerDeployer, bridge-specific interfaces (OP, Arb, CCIP)
 ├── libraries/
-│   ├── JBAddressBytes.sol  — Address/bytes32 conversion
-│   └── MerkleLib.sol       — Merkle tree operations
-└── structs/                — Token mappings, sucker pairs, claims
+│   ├── ARBAddresses.sol    — Arbitrum precompile/contract addresses
+│   ├── ARBChains.sol       — Arbitrum chain ID constants
+│   └── CCIPHelper.sol      — CCIP chain selector lookups
+├── structs/                — JBClaim, JBLeaf, JBTokenMapping, JBRemoteToken, JBOutboxTree, JBMessageRoot, etc.
+└── utils/
+    └── MerkleLib.sol       — Append-only merkle tree operations
 ```
 
 ## Key Data Flows
@@ -33,19 +42,23 @@ src/
 User → JBSucker.prepare()
   → Cash out project tokens (0% tax via sucker privilege)
   → Insert {beneficiary, token, amount} into outbox merkle tree
-  → When tree is full or manually triggered:
-    → Bridge tokens via OP/Arb/CCIP messenger
-    → Send merkle root to remote sucker
+
+User → JBSucker.toRemote{value}(token)
+  → Pay toRemoteFee (ETH) to fee project via terminal.pay() — caller gets fee project tokens
+  → Remaining msg.value forwarded as transport payment to the bridge
+  → Send merkle root + bridged tokens to remote sucker via OP/Arb/CCIP messenger
 ```
 
+The `toRemoteFee` is a global ETH fee (max 0.001 ETH) set by the registry owner via `setToRemoteFee()`. The caller must send at least `toRemoteFee` as `msg.value` (reverts otherwise). The fee is paid into `FEE_PROJECT_ID` (typically project 1) through the project's primary native-token terminal. If the `pay()` call reverts or no terminal exists, the fee is silently added to the transport payment instead (best-effort).
+
 ### Inbound (Claim)
 ```
 Remote root arrives → stored in inbox tree
 User → JBSucker.claim(proof)
+  → Check leaf not already claimed (bitmap), mark as executed
   → Verify merkle proof against inbox root
-  → Check leaf not already claimed (bitmap)
-  → Mint project tokens to beneficiary (or transfer bridged tokens)
-  → Mark leaf as executed
+  → Add bridged terminal tokens to project balance (via terminal.addToBalanceOf)
+  → Mint project tokens to beneficiary (via controller.mintTokensOf)
 ```
 
 ### Deprecation Lifecycle
@@ -54,6 +67,31 @@ ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
   (owner)    (pending period)     (no new outbox)    (fully disabled)
 ```
 
+## Token Mapping
+
+Token mappings link a local terminal token to a remote token address, enabling bridging for that pair. Mappings are managed via `mapToken()` / `mapTokens()` (requires `MAP_SUCKER_TOKEN` permission).
+
+**Immutability constraint:** 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)`. This prevents double-spending: if remapping were allowed after outbox activity, the same local funds could be claimed against two different remote tokens on the remote chain.
+
+A disabled mapping can be re-enabled to the *same* remote token. A misconfigured mapping requires deploying a new sucker.
+
+When a mapping is disabled (set to `address(0)`) and unsent leaves remain in the outbox, the sucker automatically flushes the remaining root to the remote chain to settle outstanding claims.
+
+## Emergency Hatch
+
+The emergency hatch allows users to reclaim their tokens on the chain they deposited on when the bridge is no longer functional.
+
+**Who can enable it:** The project owner (or an address with the `SUCKER_SAFETY` permission) calls `enableEmergencyHatchFor(address[] tokens)`.
+
+**What it does:** Sets `emergencyHatch = true` and `enabled = false` for each token's remote mapping. This is irreversible — once the emergency hatch is enabled for a token, it cannot be disabled or remapped.
+
+**How users exit:** Users call `exitThroughEmergencyHatch(JBClaim claimData)` with a merkle proof against the *outbox* tree. The sucker validates:
+1. The emergency hatch is enabled for that token (or the sucker is in `DEPRECATED` / `SENDING_DISABLED` state).
+2. The leaf has not already been sent to the remote chain (`index >= numberOfClaimsSent`). Leaves whose roots were already bridged cannot be emergency-exited, since they could also be claimed remotely.
+3. The leaf has not already been claimed (bitmap check).
+
+The sucker then adds the terminal tokens back to the project's balance (via `terminal.addToBalanceOf`) and mints project tokens to the beneficiary on the local chain.
+
 ## Extension Points
 
 | Point | Interface | Purpose |
@@ -62,10 +100,22 @@ ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
 | Sucker deployer | `IJBSuckerDeployer` | Factory for new suckers |
 | Registry | `IJBSuckerRegistry` | Discovery and access control |
 
+## Design Decisions
+
+**Dual merkle trees instead of direct bridging.** Each sucker maintains separate outbox and inbox merkle trees per token. Outbound transfers are batched into the outbox tree via `prepare()`, and a single `toRemote()` call bridges the root and accumulated funds together. This amortizes bridge costs across many users — only one cross-chain message per batch rather than one per transfer. The inbox tree on the receiving side lets users self-serve claims with merkle proofs at their own pace.
+
+**Bitmap for claim tracking.** Each leaf index is tracked in an OpenZeppelin `BitMaps.BitMap` (`_executedFor`), which packs 256 booleans per storage slot. This is far cheaper than a `mapping(uint256 => bool)` for dense sequential indices, and the merkle tree's sequential leaf indices are a natural fit.
+
+**Immutable token mappings once outbox has entries.** After a token mapping has been used (outbox tree count > 0), remapping to a different remote token is blocked. Without this, an attacker could prepare tokens mapped to token A, then remap to token B before `toRemote()` is called, allowing the same local funds to be claimed against both tokens on the remote chain. Disabling (mapping to `address(0)`) is still allowed since it flushes remaining outbox entries and stops new ones.
+
+**`uint128` amount cap for SVM compatibility.** Both `terminalTokenAmount` and `projectTokenCount` are capped at `type(uint128).max` in `_insertIntoTree()`. This ensures the leaf data is compatible with Solana's SVM, where token amounts are `u64`/`u128`. The `bytes32` beneficiary field similarly accommodates 32-byte Solana public keys alongside 20-byte EVM addresses.
+
+**Best-effort fee payment.** The `toRemoteFee` payment to the fee project is wrapped in a try-catch. If the fee project's terminal doesn't exist or the `pay()` call reverts, the bridge proceeds without the fee. This prevents a misconfigured or paused fee project from blocking all cross-chain transfers.
+
 ## Dependencies
 - `@bananapus/core-v6` — Terminal, controller, token interfaces
 - `@bananapus/permission-ids-v6` — DEPLOY_SUCKERS, MAP_SUCKER_TOKEN, etc.
-- `@arbitrum/nitro-contracts` — Arbitrum bridge interfaces
-- `@chainlink/contracts-ccip` — CCIP router interfaces
-- `@openzeppelin/contracts` — MerkleProof, SafeERC20
-- `solady` — LibBitmap
+- `@arbitrum/nitro-contracts` — Arbitrum bridge interfaces (IInbox, IOutbox, IBridge, ArbSys, AddressAliasHelper)
+- `@chainlink/contracts-ccip` — CCIP router and message interfaces
+- `@openzeppelin/contracts` — BitMaps, SafeERC20, ERC165, Initializable, ERC2771Context, Ownable, EnumerableMap
+- `solady` — LibClone (deterministic clone deployment for sucker deployers)

package/AUDIT_INSTRUCTIONS.md

@@ -14,7 +14,7 @@ src/JBBaseSucker.sol                    # Base (OP Stack variant) (~48 lines)
 src/JBCeloSucker.sol                    # Celo (OP Stack + WETH wrapping) (~196 lines)
 src/JBArbitrumSucker.sol                # Arbitrum bridge implementation (~322 lines)
 src/JBCCIPSucker.sol                    # Chainlink CCIP implementation (~306 lines)
-src/JBSuckerRegistry.sol                # Deployer registry and tracking (~260 lines)
+src/JBSuckerRegistry.sol                # Deployer registry and tracking (~282 lines)
 src/deployers/                          # JBSuckerDeployer, JB{Optimism,Base,Celo,Arbitrum,CCIP}SuckerDeployer
 src/utils/MerkleLib.sol                 # Incremental merkle tree (eth2-style) (~1,030 lines)
 src/structs/                            # JBMessageRoot, JBLeaf, JBClaim, JBOutboxTree, etc.
@@ -300,3 +300,99 @@ forge test --match-contract ForkMainnet --fork-url $ETH_RPC_URL
 # Gas analysis
 forge test --gas-report
 ```
+
+## Error Reference
+
+35 custom errors across source files:
+
+| Error | Contract | Trigger |
+|-------|----------|---------|
+| `JBSucker_AmountExceedsUint128` | JBSucker | `projectTokenCount` or `terminalTokenAmount` exceeds `uint128` during `_insertIntoTree` |
+| `JBSucker_BelowMinGas` | JBSucker | Token mapping `minGas` is below `MESSENGER_ERC20_MIN_GAS_LIMIT` |
+| `JBSucker_Deprecated` | JBSucker | `prepare`, `toRemote`, or `_sendRoot` called when sucker is `SENDING_DISABLED` or `DEPRECATED` |
+| `JBSucker_DeprecationTimestampTooSoon` | JBSucker | `setDeprecation` timestamp is earlier than `block.timestamp + _maxMessagingDelay()` |
+| `JBSucker_ExpectedMsgValue` | JBArbitrumSucker, JBCCIPSucker | Transport payment is 0 when bridge requires msg.value (Arbitrum L1, CCIP) |
+| `JBSucker_InsufficientBalance` | JBSucker | `_addToBalance` amount exceeds `amountToAddToBalanceOf` (actual token balance minus outbox balance) |
+| `JBSucker_InsufficientMsgValue` | JBSucker | `msg.value` is less than the `toRemoteFee` in `toRemote` |
+| `JBSucker_InvalidMessageVersion` | JBSucker | `fromRemote` receives a root with mismatched `MESSAGE_VERSION` |
+| `JBSucker_InvalidNativeRemoteAddress` | JBSucker | Native token mapped to non-native, non-zero remote address (base class restriction) |
+| `JBSucker_InvalidProof` | JBSucker | Merkle proof does not reconstruct the stored inbox root during `_validate` |
+| `JBSucker_LeafAlreadyExecuted` | JBSucker | Leaf index already claimed in bitmap during `_validate` or `_validateForEmergencyExit` |
+| `JBSucker_NoTerminalForToken` | JBSucker | No primary terminal registered for the token when pulling backing assets or adding to balance |
+| `JBSucker_NotPeer` | JBSucker | `fromRemote` caller fails `_isRemotePeer` authentication |
+| `JBSucker_NothingToSend` | JBSucker | `toRemote` called when emergency hatch is enabled or outbox has no unsent entries |
+| `JBSucker_TokenAlreadyMapped` | JBSucker | Attempt to remap a token after outbox tree has entries (immutability enforcement) |
+| `JBSucker_TokenHasInvalidEmergencyHatchState` | JBSucker | Emergency hatch state conflict during `toRemote`, `_mapToken`, or `_validateForEmergencyExit` |
+| `JBSucker_TokenNotMapped` | JBSucker | `prepare` or `_sendRoot` called for an unmapped token |
+| `JBSucker_UnexpectedMsgValue` | JBArbitrumSucker, JBOptimismSucker, JBCeloSucker | Non-zero transport payment on bridges that don't accept it (Arbitrum L2, OP Stack, Celo) |
+| `JBSucker_ZeroBeneficiary` | JBSucker | `prepare` called with zero-address beneficiary |
+| `JBSucker_ZeroERC20Token` | JBSucker | `prepare` called when project has no ERC-20 token |
+| `JBArbitrumSucker_NotEnoughGas` | JBArbitrumSucker | Transport payment insufficient for retryable ticket gas cost |
+| `JBCCIPSucker_InvalidRouter` | JBCCIPSucker | Constructor reverts when `CCIP_ROUTER == address(0)` |
+| `JBSuckerRegistry_FeeExceedsMax` | JBSuckerRegistry | `setToRemoteFee` exceeds `MAX_TO_REMOTE_FEE` |
+| `JBSuckerRegistry_InvalidDeployer` | JBSuckerRegistry | Deployer not in allowlist during `deploySuckersFor` |
+| `JBSuckerRegistry_SuckerDoesNotBelongToProject` | JBSuckerRegistry | `removeDeprecatedSucker` called for sucker not belonging to the project |
+| `JBSuckerRegistry_SuckerIsNotDeprecated` | JBSuckerRegistry | `removeDeprecatedSucker` called for a non-deprecated sucker |
+| `JBCCIPSuckerDeployer_InvalidCCIPRouter` | JBCCIPSuckerDeployer | Zero-address CCIP router in constructor |
+| `JBSuckerDeployer_AlreadyConfigured` | JBSuckerDeployer | `configureSucker` called on an already-configured sucker |
+| `JBSuckerDeployer_DeployerIsNotConfigured` | JBSuckerDeployer | `createFor` called before deployer is configured |
+| `JBSuckerDeployer_InvalidLayerSpecificConfiguration` | JBSuckerDeployer | Layer-specific configuration validation fails |
+| `JBSuckerDeployer_LayerSpecificNotConfigured` | JBSuckerDeployer | Layer-specific configuration not set when required |
+| `JBSuckerDeployer_Unauthorized` | JBSuckerDeployer | Caller is not the expected configurator |
+| `JBSuckerDeployer_ZeroConfiguratorAddress` | JBSuckerDeployer | Zero-address configurator in constructor |
+| `CCIPHelper_UnsupportedChain` | CCIPHelper | Chain ID has no CCIP chain selector mapping |
+| `MerkleLib_InsertTreeIsFull` | MerkleLib | Merkle tree reached max capacity (`2^32 - 1` leaves) |
+
+## Previous Audit Findings
+
+No prior formal audit with finding IDs has been conducted on this codebase. All risk analysis is internal. See [RISKS.md](./RISKS.md) for known risks and trust assumptions.
+
+## Anti-Patterns to Hunt
+
+| Pattern | Where to Look | Why It's Dangerous |
+|---------|--------------|-------------------|
+| Non-atomic bridging (Arbitrum L1→L2) | `JBArbitrumSucker._sendRootOverAMB()` | Two independent retryable tickets: tokens and merkle root arrive separately. If message arrives before tokens, `_handleClaim` could mint unbacked tokens. Mitigated by `amountToAddToBalanceOf()` check -- verify this is sufficient. |
+| Self-call pattern (CCIP) | `JBCCIPSucker.ccipReceive()` calls `this.fromRemote()` | The self-call bypasses the `_isRemotePeer` check since `msg.sender == address(this)`. All authentication happens in `ccipReceive`. Verify no path can call `fromRemote()` directly. |
+| Emergency hatch with no timelock | `enableEmergencyHatchFor()` | Project owner can enable emergency exit instantly. No delay, no multisig requirement. If the owner's key is compromised, they can emergency-exit tokens that are legitimately in transit. |
+| uint128 truncation | `_insertIntoTree()` | Amounts are cast to uint128 for SVM compatibility. If a project token amount exceeds uint128, it silently truncates. Verify the cast reverts on overflow. |
+| Bitmap slot collision | `_executedFor[token]` vs emergency exit bitmap | Emergency exit uses `address(bytes20(keccak256(abi.encode(terminalToken))))` as a separate bitmap key. Verify this cannot collide with any legitimate token address. |
+| Root flush on disable | `_mapToken()` with `bytes32(0)` | Disabling a token calls `_sendRoot()` to flush unsent entries. If the bridge is down, this flush reverts and the token cannot be disabled. |
+| CCIP amount validation skip | `JBCCIPSucker._sendRootOverAMB()` | Amount validation is intentionally skipped (reverting would lock tokens). If CCIP delivers fewer tokens than expected, claims are underfunded. |
+| Nonce gap acceptance | `fromRemote()` | Inbox nonce only requires `> current`, not `== current + 1`. For CCIP where messages can arrive out of order, intermediate roots are lost. |
+
+## Coverage Gaps
+
+The test suite covers core flows but these areas have limited or no coverage:
+
+- **CCIP amount mismatch handling**: CCIP intentionally skips amount validation (reverting would lock tokens). No tests verify behavior when the delivered token amount differs from the amount encoded in the merkle root.
+- **Arbitrum retryable ticket redemption ordering**: L1->L2 creates two independent retryable tickets (one for tokens, one for merkle root). No tests simulate the message arriving before tokens, verifying that `_addToBalance` correctly checks `amountToAddToBalanceOf` to prevent unbacked minting.
+- **Multi-hop Celo WETH wrapping**: Celo wraps native ETH to WETH before bridging and unwraps on the other side. No tests cover edge cases like partial WETH unwrap failures or WETH contract balance manipulation.
+- **Emergency exit under active bridging**: No tests for the scenario where a user calls `prepare()`, tokens are in the outbox, `toRemote()` is called (sending the root), and then emergency hatch is enabled -- verifying that `numberOfClaimsSent` correctly prevents double-spend across both chains.
+- **Concurrent deprecation and bridging**: No tests for the timing window between `SENDING_DISABLED` and `DEPRECATED` states where `fromRemote()` can still accept roots but `prepare()`/`toRemote()` are blocked.
+- **Token mapping flush under reentrancy**: `_mapToken` calls `_sendRoot()` when disabling a token with unsent outbox entries. No tests verify this flush is safe under reentrancy from the bridge callback.
+
+## Compiler and Version Info
+
+- **Solidity**: 0.8.28
+- **EVM target**: Cancun
+- **Optimizer**: 200 runs (via-IR is NOT enabled)
+- **Dependencies**: OpenZeppelin 5.x, Arbitrum SDK, Chainlink CCIP, nana-core-v6
+- **Build**: `forge build` (Foundry)
+
+## How to Report Findings
+
+For each finding:
+
+1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
+2. **Affected contract(s)** -- exact file path and line numbers
+3. **Description** -- what is wrong, in plain language
+4. **Trigger sequence** -- step-by-step, minimal steps to reproduce (include which chain each step happens on)
+5. **Impact** -- what an attacker gains, what a user loses (with numbers if possible)
+6. **Proof** -- code trace showing the exact execution path, or a Foundry test
+7. **Fix** -- minimal code change that resolves the issue
+
+**Severity guide:**
+- **CRITICAL**: Double-claim, unbacked minting, bridge fund loss. Exploitable with no preconditions.
+- **HIGH**: Conditional fund loss, authentication bypass, or broken cross-chain invariant.
+- **MEDIUM**: Value leakage, griefing, stuck tokens (recoverable via emergency hatch).
+- **LOW**: Informational, edge-case-only with no material impact.

package/CHANGE_LOG.md

@@ -1,6 +1,16 @@
 # nana-suckers-v6 Changelog (v5 -> v6)
 
-This document describes all changes between `nana-suckers` (v5, Solidity 0.8.23) and `nana-suckers-v6` (v6, Solidity 0.8.26).
+This document describes all changes between `nana-suckers` (v5, Solidity 0.8.23) and `nana-suckers-v6` (v6, Solidity 0.8.28).
+
+## Summary
+
+The dominant theme of this release is **cross-VM preparation for Solana/SVM** — addresses throughout the sucker architecture are widened from `address` (20 bytes) to `bytes32` (32 bytes) to support non-EVM chains.
+
+- **`address` → `bytes32` throughout**: All cross-chain identifiers (peer addresses, beneficiaries, remote tokens) widened to `bytes32` for Solana/SVM compatibility. `uint128` amount caps added for SVM compatibility.
+- **Message versioning**: New `version` field in `JBMessageRoot` prevents v5/v6 message incompatibility. v6 messages use `MESSAGE_VERSION = 1`.
+- **Anti-spam redesigned**: Per-token `minBridgeAmount` replaced by a global `toRemoteFee` (max 0.001 ETH) paid to the fee project on every `toRemote()` call.
+- **`MANUAL` add-to-balance mode removed**: Balance is always added atomically during `claim()`, simplifying the sucker lifecycle.
+- **New Celo support**: `JBCeloSucker` handles Celo's non-ETH native gas token via WETH wrapping.
 
 ---
 
@@ -22,6 +32,8 @@ The most pervasive breaking change in v6 is the systematic replacement of `addre
 
 All callers of `peer()` and `prepare()` must update to use `bytes32`. For EVM-to-EVM usage, addresses are left-padded to 32 bytes via `_toBytes32(address)`.
 
+> **Cross-repo impact**: `nana-omnichain-deployers-v6` and `nana-fee-project-deployer-v6` both updated `JBTokenMapping.remoteToken` from `address` to `bytes32`. `nana-permission-ids-v6` split `SUCKER_SAFETY` into two permissions (`SUCKER_SAFETY` + `SET_SUCKER_DEPRECATION`) to match the v6 separation.
+
 ### 1.2 Struct Field Type Changes
 
 | Struct | Field | v5 Type | v6 Type |
@@ -354,7 +366,7 @@ See section 2.4 above.
 
 ### 7.9 Solidity Version
 
-All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.26`.
+All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.28`.
 
 ### 7.10 Named Arguments
 

package/README.md

@@ -2,31 +2,6 @@
 
 Cross-chain bridging for Juicebox V6 projects. Suckers let users cash out project tokens on one chain, move the backing funds across a bridge, and mint the same number of project tokens on another chain -- all via merkle-tree-based claims and chain-specific bridges.
 
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li><a href="#what-are-suckers">What are Suckers?</a></li>
-    <li><a href="#architecture">Architecture</a></li>
-    <li><a href="#bridging-flow">Bridging Flow</a></li>
-    <li><a href="#bridging-tokens">Bridging Tokens</a></li>
-    <li><a href="#token-mapping">Token Mapping</a></li>
-    <li><a href="#deprecation-lifecycle">Deprecation Lifecycle</a></li>
-    <li><a href="#emergency-hatch">Emergency Hatch</a></li>
-    <li><a href="#launching-suckers">Launching Suckers</a></li>
-    <li><a href="#managing-suckers">Managing Suckers</a></li>
-    <li><a href="#using-the-relayer">Using the Relayer</a></li>
-    <li><a href="#resources">Resources</a></li>
-    <li><a href="#repository-layout">Repository Layout</a></li>
-    <li><a href="#usage">Usage</a></li>
-    <ul>
-      <li><a href="#install">Install</a></li>
-      <li><a href="#develop">Develop</a></li>
-      <li><a href="#scripts">Scripts</a></li>
-      <li><a href="#tips">Tips</a></li>
-    </ul>
-  </ol>
-</details>
-
 _If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core-v6) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
 
 ## What are Suckers?
@@ -381,6 +356,14 @@ Users can do this manually, but it's a hassle. The [`bananapus-sucker-relayer`](
 - [`juicerkle`](https://github.com/Bananapus/juicerkle) -- Service that returns available claims for a beneficiary (generates merkle proofs). Includes a [Go merkle tree implementation](https://github.com/Bananapus/juicerkle/blob/master/tree/tree.go) for computing roots and building/verifying proofs.
 - [`juicerkle-tester`](https://github.com/Bananapus/juicerkle-tester) -- End-to-end bridging test: deploys projects, tokens, and suckers, then bridges between them. Useful as a bridging walkthrough.
 
+## Risks
+
+- **Out-of-order nonce delivery (CCIP).** `fromRemote` only accepts roots with a nonce strictly greater than the current inbox nonce. If CCIP delivers messages out of order, earlier nonces are silently skipped and every claim in those skipped roots becomes permanently unclaimable on the destination chain. Affected users must use the emergency hatch on the source chain to recover their funds.
+- **Emergency hatch is irreversible per-token.** Calling `enableEmergencyHatchFor` permanently disables bridging for that token on that sucker. Once opened, the token can never be bridged by this sucker again -- a new sucker must be deployed to restore bridging for that token.
+- **`msg.value` required for Arbitrum L1-to-L2 transport.** `JBArbitrumSucker` uses `unsafeCreateRetryableTicket` for L1-to-L2 messages, which requires `msg.value` to cover the retryable ticket cost. OP Stack suckers (`JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker`) do not require `msg.value` for transport. Callers must know which sucker type they are interacting with, or the `toRemote` call will revert.
+- **Merkle tree depth is fixed at 32.** The outbox tree supports approximately 4 billion leaves, which is practically unlimited, but the tree is append-only and never pruned. Every leaf persists for the lifetime of the sucker, and proofs always require exactly 32 siblings regardless of tree size.
+- **Token mapping immutability.** Once an outbox tree has any entries for a given token, the mapping between local and remote token is locked forever. The mapping can be disabled (set `remoteToken` to `bytes32(0)`) and later re-enabled, but only to the same remote token. Mapping to a different remote token requires deploying a new sucker.
+
 ## Repository Layout
 
 ```
@@ -406,11 +389,19 @@ nana-suckers-v6/
 │       └── MerkleLib.sol - Incremental merkle tree (depth 32).
 └── test/
     ├── Fork.t.sol - Fork tests.
+    ├── ForkArbitrum.t.sol - Arbitrum fork tests.
+    ├── ForkCelo.t.sol - Celo fork tests.
+    ├── ForkClaim.t.sol - Fork claim tests.
+    ├── ForkMainnet.t.sol - Mainnet fork tests.
+    ├── ForkOPStack.t.sol - OP Stack fork tests.
     ├── InteropCompat.t.sol - Cross-VM compatibility tests.
     ├── SuckerAttacks.t.sol - Security-focused attack tests.
     ├── SuckerDeepAttacks.t.sol - Deep attack scenario tests.
+    ├── SuckerRegressions.t.sol - Regression tests.
+    ├── TestAuditGaps.sol - Audit gap coverage tests.
     ├── mocks/ - Mock contracts for testing.
-    └── unit/ - Unit tests (merkle, registry, deployer, emergency, arb).
+    ├── regression/ - Regression-specific tests.
+    └── unit/ - Unit tests (merkle, registry, deployer, emergency, arb, ccip, invariants).
 ```
 
 ## Usage

package/RISKS.md

@@ -42,26 +42,25 @@ Forward-looking risk catalog for the JBSucker cross-chain bridging system.
   - Wrong native mapping can cause permanent loss: e.g., bridging ETH to a non-WETH ERC-20 address on the remote chain.
 - **`fromRemote` accepts roots for unmapped tokens.** By design, to avoid permanent loss of already-bridged tokens. Claims against those roots fail at the mapping lookup. This means stale token data can accumulate in inbox storage indefinitely.
 - **minGas too low = permanent fund loss.** If `minGas` is below the actual gas needed for the remote call, the bridge message will fail on the remote chain. The OP/CCIP implementations enforce `MESSENGER_ERC20_MIN_GAS_LIMIT` (200k), but the actual gas needed could be higher depending on the remote token implementation.
+- **Cross-reference: omnichain deployer token mapping.** When suckers are deployed through `JBOmnichainDeployer`, the `MAP_SUCKER_TOKEN` permission is granted to the sucker registry with `projectId=0` (wildcard). This means the registry can map tokens for ALL projects, not just the one being deployed. See [nana-omnichain-deployers-v6 RISKS.md](../nana-omnichain-deployers-v6/RISKS.md) section 3 for the permission escalation analysis.
 
 ## 5. Fee Collection Risks
 
 - **Best-effort fee collection.** `toRemoteFee` is a centralized storage variable on `JBSuckerRegistry` (ETH, in wei) — uniform across all suckers and all tokens, non-bypassable by integrators. It is paid into `FEE_PROJECT_ID` (typically project ID 1) via `terminal.pay()`. If the fee project has no primary terminal for `NATIVE_TOKEN`, or if `terminal.pay()` reverts for any reason, `toRemote()` silently proceeds without collecting the fee. This means fee collection is best-effort — it can fail if the fee project's terminal is misconfigured, paused, or removed — but the fee amount cannot be set to 0 by users calling `toRemote()`.
-- **Registry-controlled fee.** The registry owner can adjust `toRemoteFee` via `JBSuckerRegistry.setToRemoteFee()`, up to the hard cap of `MAX_TO_REMOTE_FEE` (0.001 ether). A single call applies to all suckers globally. This mitigates ETH price risk: if ETH price changes significantly, the registry owner can adjust the fee without deploying new suckers. Because fee control is centralized, individual sucker clones have no per-clone ownership (`Ownable` has been removed from `JBSucker`) and no `transferOwnership()` or `renounceOwnership()`.
 - **Renounced registry ownership risk.** If the registry owner calls `renounceOwnership()`, `setToRemoteFee()` becomes permanently uncallable and the fee is frozen at its current value across all suckers. This is a deliberate trade-off: it allows the registry owner to credibly commit to a fee level, but eliminates the ability to respond to future ETH price changes. The fee is still capped at `MAX_TO_REMOTE_FEE`, so the maximum downside is bounded.
 - **Immutable fee project.** `FEE_PROJECT_ID` is set at construction and cannot be changed. If the fee project is abandoned or its terminal removed, there is no way to redirect fees without deploying new suckers.
-- **Fee does not protect the sucker's own project.** The fee is paid to `FEE_PROJECT_ID` (the protocol project), not to the sucker's own `projectId()`. This is by design — the protocol project always has a native token terminal — but means the sucker's project does not directly benefit from the anti-spam fee.
-- **ETH price risk (mitigated).** `toRemoteFee` is denominated in wei but is adjustable by the registry owner (up to `MAX_TO_REMOTE_FEE`). A significant ETH price increase can be mitigated by lowering the fee; a significant decrease can be mitigated by raising it. If registry ownership has been renounced, the fee is frozen across all suckers and the only recourse is deploying a new registry and new suckers.
+- **Cross-reference: sucker registration path.** Suckers are deployed via `JBSuckerRegistry.deploySuckersFor`, which requires `DEPLOY_SUCKERS` permission from the project owner. The registry's `deploy` function uses `CREATE2` with a deployer-specific salt. The sucker's `peer()` address is deterministic — a misconfigured peer means the sucker accepts messages from the wrong remote address. See [nana-omnichain-deployers-v6 RISKS.md](../nana-omnichain-deployers-v6/RISKS.md) for deployer-level risks.
 
 ## 6. Deprecation Lifecycle
 
 - **State machine: ENABLED -> DEPRECATION_PENDING -> SENDING_DISABLED -> DEPRECATED.**
   - `DEPRECATION_PENDING`: fully functional, warning only. `block.timestamp < deprecatedAfter - _maxMessagingDelay()`.
   - `SENDING_DISABLED`: no new `prepare()` or `toRemote()`. `block.timestamp >= deprecatedAfter - _maxMessagingDelay()` but `< deprecatedAfter`.
-  - `DEPRECATED`: fully shut down. No new inbox roots accepted. Emergency exits allowed.
+  - `DEPRECATED`: outbound sends blocked. Incoming roots are still accepted to prevent stranding already-sent tokens. Emergency exits allowed.
 - **Irrecoverability once SENDING_DISABLED.** `setDeprecation` reverts in SENDING_DISABLED and DEPRECATED states. Once the sucker enters SENDING_DISABLED, there is no way to cancel or extend the deprecation.
 - **Messaging delay = 14 days.** `_maxMessagingDelay()` returns 14 days for all implementations. The deprecation timestamp must be at least `block.timestamp + 14 days` in the future. This is generous for OP/Arb (minutes to hours) but may be insufficient if a bridge has an extended outage.
 - **Stuck tokens during deprecation.** Tokens that were `prepare()`d but not yet `toRemote()`d before SENDING_DISABLED cannot be sent to the remote chain. They can only be recovered via emergency exit after the sucker reaches DEPRECATED state.
-- **Both sides must deprecate.** The deprecation must be called on both the local and remote sucker with matching timestamps. If only one side deprecates, the other side continues accepting roots while the deprecated side blocks sends -- tokens become unreachable on the non-deprecated side.
+- **Both sides must deprecate.** The deprecation must be called on both the local and remote sucker with matching timestamps. If only one side deprecates, the other side continues accepting roots while the deprecated side blocks outbound sends. The deprecated side still accepts incoming roots, so tokens sent before deprecation can be claimed.
 
 ## 7. Emergency Hatch
 
@@ -69,7 +68,7 @@ Forward-looking risk catalog for the JBSucker cross-chain bridging system.
   1. Per-token: `enableEmergencyHatchFor(tokens)` -- requires `SUCKER_SAFETY` permission from project owner. Allows emergency exit for specific tokens while the sucker is still ENABLED.
   2. Global: deprecation reaching SENDING_DISABLED or DEPRECATED state. Allows emergency exit for all tokens.
 - **Claim vs emergency exit use separate bitmap slots.** Emergency exit uses `_executedFor[keccak256(abi.encode(terminalToken))]` while regular claims use `_executedFor[terminalToken]`. This means a leaf that was emergency-exited locally could theoretically also be claimed remotely if the root was already sent -- double-spend is prevented only by the `numberOfClaimsSent` check.
-- **`numberOfClaimsSent` is the critical guard.** Emergency exit reverts if `outbox.numberOfClaimsSent - 1 >= index`. This means leaves at indices below `numberOfClaimsSent` cannot be emergency-exited (they may have been sent to the remote peer). If `_sendRootOverAMB` silently fails, these leaves are permanently locked.
+- **`numberOfClaimsSent` is the critical guard.** Emergency exit reverts if `outbox.numberOfClaimsSent != 0 && outbox.numberOfClaimsSent - 1 >= index`. The `numberOfClaimsSent != 0` precondition prevents underflow when no root has ever been sent — in that case, all leaves are available for emergency exit. This means leaves at indices below `numberOfClaimsSent` cannot be emergency-exited (they may have been sent to the remote peer). If `_sendRootOverAMB` silently fails, these leaves are permanently locked.
 - **Emergency exit decrements `outbox.balance`.** If emergency exits drain the outbox balance below the amount that was already sent to the bridge, the accounting becomes inconsistent. The contract guards against this by only allowing exit for unsent leaves.
 - **Emergency hatch + minting.** Emergency exit calls `_handleClaim`, which mints project tokens via the controller. If the controller or token contract is broken/missing, emergency exits also revert -- there is no "raw withdrawal" of terminal tokens without minting.
 
@@ -96,3 +95,21 @@ Forward-looking risk catalog for the JBSucker cross-chain bridging system.
 - **Claim and emergency exit slot independence.** A regular claim (inbox path) and an emergency exit (outbox path) for the same index on the same token use different bitmap keys and do not interfere. Tested in `test_merkleTree_claimAndEmergencyExitSlotIndependence`.
 - **Tree count monotonically increases.** `MerkleLib.Tree.count` only increments (append-only). No operation decreases the count. Tested in `invariant_treeCountMonotonicallyIncreases`.
 - **Message version gate.** `fromRemote` rejects any message where `root.version != MESSAGE_VERSION`. Tested in `test_merkleTree_messageVersionValidation`.
+
+## 10. Accepted Behaviors
+
+### 10.1 Stale nonce messages silently ignored (not reverted)
+
+`fromRemote` does not revert when receiving a message with a nonce <= the current inbox nonce. Instead, it emits `StaleRootRejected` and returns silently. This is intentional for native ETH bridges: reverting a message that carries native ETH (e.g., OP bridge `relayMessage` with value) would lose the ETH. Silent acceptance preserves bridge funds while discarding the stale root. Monitoring systems should watch for `StaleRootRejected` events as indicators of bridge message ordering issues.
+
+### 10.2 Emergency hatch is irreversible
+
+Once `enableEmergencyHatchFor(token)` is called, the token mapping is permanently disabled (`enabled = false`, `emergencyHatch = true`). There is no mechanism to re-enable the mapping or close the hatch. This is a conscious trade-off: reversibility would require additional access control and state transitions that could be exploited to trap tokens. The irreversibility forces a clean deployment of a new sucker when recovery is complete.
+
+### 10.3 Registry-controlled fee with ETH price adjustability
+
+The registry owner can adjust `toRemoteFee` via `JBSuckerRegistry.setToRemoteFee()`, up to the hard cap of `MAX_TO_REMOTE_FEE` (0.001 ether). A single call applies to all suckers globally. This mitigates ETH price risk: if ETH price changes significantly, the registry owner can adjust the fee without deploying new suckers. Because fee control is centralized, individual sucker clones have no per-clone ownership (`Ownable` has been removed from `JBSucker`) and no `transferOwnership()` or `renounceOwnership()`. If registry ownership is renounced, the fee is frozen and the only recourse is deploying a new registry and new suckers.
+
+### 10.4 Fee is paid to the protocol project, not the sucker's project
+
+The fee is paid to `FEE_PROJECT_ID` (the protocol project), not to the sucker's own `projectId()`. The protocol project always has a native token terminal, ensuring reliable fee collection. The sucker's project does not directly benefit from the anti-spam fee.

package/SKILLS.md

@@ -28,9 +28,9 @@ Cross-chain token and fund bridging for Juicebox V6 projects, using merkle trees
 | Function | Contract | What it does |
 |----------|----------|--------------|
 | `prepare(projectTokenCount, beneficiary, minTokensReclaimed, token)` | `JBSucker` | Transfers project tokens (ERC-20) from caller via `safeTransferFrom`, cashes them out at the project's primary terminal for the specified terminal token, inserts a leaf into the outbox merkle tree. `beneficiary` is `bytes32` for cross-VM compatibility. Amounts are capped at `uint128` for SVM compatibility. Reverts if token not mapped, sucker deprecated/sending-disabled, beneficiary is zero, or project has no ERC-20 token. |
-| `toRemote(token)` | `JBSucker` | Sends the outbox merkle root and accumulated funds for `token` to the peer sucker on the remote chain via the bridge. Reverts with `NothingToSend` if outbox is empty (balance==0 and count==numberOfClaimsSent). Reads the fee via `REGISTRY.toRemoteFee()`. If the fee != 0, deducts it from `msg.value` and pays it into the fee project (`FEE_PROJECT_ID`, typically project ID 1) via `terminal.pay()` (caller gets project tokens). Best-effort: if the fee project has no native token terminal or `terminal.pay()` reverts, proceeds without fee. Remainder is passed as `transportPayment` to the bridge. Increments outbox nonce. Updates `numberOfClaimsSent` to current tree count. Reverts if emergency hatch is open for the token. |
+| `toRemote(token)` | `JBSucker` | Sends the outbox merkle root and accumulated funds for `token` to the peer sucker via the bridge. Deducts `toRemoteFee` from `msg.value` (paid into fee project), passes remainder as transport payment. Increments outbox nonce and updates `numberOfClaimsSent`. Reverts if outbox is empty or emergency hatch is open. |
 | `setToRemoteFee(fee)` | `JBSuckerRegistry` | Sets the global `toRemoteFee` for all suckers. Restricted to the registry owner via OpenZeppelin `Ownable` (`onlyOwner`). The fee must be <= `MAX_TO_REMOTE_FEE` (0.001 ether). Emits `ToRemoteFeeChanged`. |
-| `fromRemote(root)` | `JBSucker` | Receives a merkle root from the remote peer. Validates `MESSAGE_VERSION` (reverts on mismatch). Updates inbox tree only if received nonce > current inbox nonce AND sucker is not `DEPRECATED`. Does NOT revert on stale nonce -- emits `StaleRootRejected` instead (to avoid losing native tokens sent with the message). |
+| `fromRemote(root)` | `JBSucker` | Receives a merkle root from the remote peer. Validates `MESSAGE_VERSION` (reverts on mismatch). Updates inbox tree only if received nonce > current inbox nonce. Accepts roots in all states including `DEPRECATED` to prevent stranding already-sent tokens. Does NOT revert on stale nonce -- emits `StaleRootRejected` instead (to avoid losing native tokens sent with the message). |
 | `claim(claimData)` | `JBSucker` | Verifies a merkle proof against the inbox tree, marks the leaf as executed (prevents double-spend), mints project tokens for the beneficiary via `IJBController.mintTokensOf` (with `useReservedPercent: false`), and adds terminal tokens to the project's balance. |
 | `claim(claims[])` | `JBSucker` | Batch version -- iterates and calls `claim(JBClaim)` for each. |
 | `mapToken(map)` | `JBSucker` | Maps a local terminal token to a remote token. Requires `MAP_SUCKER_TOKEN` permission. Setting `remoteToken` to `bytes32(0)` disables bridging and sends a final root to flush remaining outbox. Cannot remap to a different remote token once outbox has entries (prevents double-spend). Can re-enable a previously disabled token to the same remote address. Reverts if emergency hatch is active for the token. |
@@ -100,6 +100,46 @@ Cross-chain token and fund bridging for Juicebox V6 projects, using merkle trees
 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Setting the deprecation timestamp |
 | `MINT_TOKENS` | Needed on the sucker address | Sucker must have this to mint project tokens on claim |
 
+## Errors
+
+| Error | Contract | When |
+|-------|----------|------|
+| `JBSucker_AmountExceedsUint128` | `JBSucker` | `projectTokenCount` or `terminalTokenAmount` exceeds `uint128` (SVM cap) |
+| `JBSucker_BelowMinGas` | `JBSucker` | Token mapping `minGas` is below `MESSENGER_ERC20_MIN_GAS_LIMIT` |
+| `JBSucker_Deprecated` | `JBSucker` | `prepare` or `toRemote` called when sucker is `SENDING_DISABLED` or `DEPRECATED` |
+| `JBSucker_DeprecationTimestampTooSoon` | `JBSucker` | `setDeprecation` timestamp is less than `_maxMessagingDelay()` in the future |
+| `JBSucker_ExpectedMsgValue` | `JBSucker` | `toRemote` called without required `msg.value` for transport payment |
+| `JBSucker_InsufficientBalance` | `JBSucker` | Emergency hatch exit amount exceeds outbox balance |
+| `JBSucker_InsufficientMsgValue` | `JBSucker` | `msg.value` is less than the `toRemoteFee` |
+| `JBSucker_InvalidMessageVersion` | `JBSucker` | `fromRemote` receives a message with wrong `MESSAGE_VERSION` |
+| `JBSucker_InvalidNativeRemoteAddress` | `JBSucker` | `NATIVE_TOKEN` mapped to a non-native, non-zero remote address (base validation) |
+| `JBSucker_InvalidProof` | `JBSucker` | Merkle proof does not match the inbox root |
+| `JBSucker_LeafAlreadyExecuted` | `JBSucker` | `claim` or emergency exit for a leaf that was already processed |
+| `JBSucker_NoTerminalForToken` | `JBSucker` | Project has no terminal for the specified token |
+| `JBSucker_NotPeer` | `JBSucker` | `fromRemote` called by an address that is not the recognized peer |
+| `JBSucker_NothingToSend` | `JBSucker` | `toRemote` called when outbox has no pending entries |
+| `JBSucker_TokenAlreadyMapped` | `JBSucker` | Attempting to remap a token to a different remote address when outbox has entries |
+| `JBSucker_TokenHasInvalidEmergencyHatchState` | `JBSucker` | Operation incompatible with the token's emergency hatch state |
+| `JBSucker_TokenNotMapped` | `JBSucker` | `prepare` called for a token that has no mapping |
+| `JBSucker_UnexpectedMsgValue` | `JBSucker` | `msg.value` sent when not expected |
+| `JBSucker_ZeroBeneficiary` | `JBSucker` | `prepare` called with `bytes32(0)` beneficiary |
+| `JBSucker_ZeroERC20Token` | `JBSucker` | `prepare` called but project has no ERC-20 token deployed |
+| `JBCCIPSucker_InvalidRouter` | `JBCCIPSucker` | Zero address passed as `CCIP_ROUTER` at construction time |
+| `JBArbitrumSucker_NotEnoughGas` | `JBArbitrumSucker` | `msg.value` insufficient for Arbitrum retryable ticket cost |
+| `JBSuckerRegistry_FeeExceedsMax` | `JBSuckerRegistry` | `setToRemoteFee` called with fee > `MAX_TO_REMOTE_FEE` |
+| `JBSuckerRegistry_InvalidDeployer` | `JBSuckerRegistry` | Deployer not on the allowlist |
+| `JBSuckerRegistry_SuckerDoesNotBelongToProject` | `JBSuckerRegistry` | Sucker is not registered for the given project |
+| `JBSuckerRegistry_SuckerIsNotDeprecated` | `JBSuckerRegistry` | `removeDeprecatedSucker` called on a non-deprecated sucker |
+| `JBSuckerDeployer_AlreadyConfigured` | `JBSuckerDeployer` | `configureSingleton` or `setChainSpecificConstants` called a second time |
+| `JBSuckerDeployer_DeployerIsNotConfigured` | `JBSuckerDeployer` | `createForSender` called before singleton is configured |
+| `JBSuckerDeployer_InvalidLayerSpecificConfiguration` | `JBSuckerDeployer` | Invalid bridge addresses passed to `setChainSpecificConstants` |
+| `JBSuckerDeployer_LayerSpecificNotConfigured` | `JBSuckerDeployer` | `configureSingleton` called before `setChainSpecificConstants` |
+| `JBSuckerDeployer_Unauthorized` | `JBSuckerDeployer` | Caller is not `LAYER_SPECIFIC_CONFIGURATOR` |
+| `JBSuckerDeployer_ZeroConfiguratorAddress` | `JBSuckerDeployer` | Constructor passed `address(0)` for configurator |
+| `JBCCIPSuckerDeployer_InvalidCCIPRouter` | `JBCCIPSuckerDeployer` | Zero address passed as CCIP router |
+| `CCIPHelper_UnsupportedChain` | `CCIPHelper` | Chain ID has no known CCIP chain selector mapping |
+| `MerkleLib_InsertTreeIsFull` | `MerkleLib` | Tree has reached max capacity (2^32 - 1 leaves) |
+
 ## Gotchas
 
 - **`remoteToken` is `bytes32`, not `address`.** All remote token addresses in `JBTokenMapping`, `JBRemoteToken`, and `JBMessageRoot` are `bytes32` for cross-VM compatibility (e.g., Solana). Convert EVM addresses with `bytes32(uint256(uint160(addr)))`.
@@ -108,17 +148,14 @@ Cross-chain token and fund bridging for Juicebox V6 projects, using merkle trees
 - Suckers are deployed as minimal clones (`LibClone.cloneDeterministic`). The singleton's constructor calls `_disableInitializers()` so it cannot be initialized directly. Only clones can be initialized.
 - For suckers to be peers, the same `salt` AND the same caller address must be used on both chains when calling `deploySuckersFor`. The registry hashes `keccak256(abi.encode(msg.sender, salt))`, and the deployer hashes `keccak256(abi.encodePacked(msg.sender, salt))` again.
 - `peer()` defaults to `bytes32(uint256(uint160(address(this))))` -- suckers expect to be deployed at matching addresses on both chains via deterministic deployment. Can be overridden for cross-VM peers (e.g., Solana PDA addresses).
-- `fromRemote` is `external payable` and does NOT revert on stale nonce or deprecated state -- it silently ignores the update and emits `StaleRootRejected` to avoid losing native tokens sent along with the message.
-- `JBCCIPSucker.ccipReceive` calls `this.fromRemote(root)` (external self-call) so that `_isRemotePeer` sees `msg.sender == address(this)` rather than the CCIP router.
-- `_validateTokenMapping` in `JBSucker` enforces that native token (`NATIVE_TOKEN`) can only map to `NATIVE_TOKEN` or `bytes32(0)`. `JBCCIPSucker` and `JBCeloSucker` override this to only enforce minimum gas (allowing `NATIVE_TOKEN` to map to any remote address since the remote chain may not have native ETH).
-- Emergency hatch is irreversible per-token. Once opened, the token can never be bridged again by that sucker. The invariant is: if `emergencyHatch == true` then `enabled == false`.
-- `setDeprecation` requires the timestamp to be at least `_maxMessagingDelay()` (14 days) in the future. Once in `SENDING_DISABLED` or `DEPRECATED` state, deprecation cannot be modified.
-- Deployer `setChainSpecificConstants` and `configureSingleton` are both one-shot functions -- they revert if called twice.
+- `JBCCIPSucker` and `JBCeloSucker` override `_validateTokenMapping` to only enforce minimum gas, allowing `NATIVE_TOKEN` to map to any remote address (the remote chain may not have native ETH). Base `JBSucker` restricts `NATIVE_TOKEN` to mapping only to `NATIVE_TOKEN` or `bytes32(0)`.
+- Emergency hatch is irreversible per-token. Once opened, the token can never be bridged again by that sucker. Invariant: `emergencyHatch == true` implies `enabled == false`.
 - `MESSENGER_BASE_GAS_LIMIT` is 300,000. `MESSENGER_ERC20_MIN_GAS_LIMIT` is 200,000. Token mappings must specify `minGas >= 200,000` for ERC-20s. `JBCCIPSucker` requires `minGas >= 200,000` for ALL tokens (including native) because CCIP wraps native to WETH.
 - `JBArbitrumSucker` uses `unsafeCreateRetryableTicket` (not `safeCreateRetryableTicket`) to avoid L2 address aliasing of the refund address.
 - The outbox tree tracks `numberOfClaimsSent` separately from `tree.count`. Emergency hatch exit is only available for leaves whose index >= `numberOfClaimsSent` (not yet sent to remote). A `numberOfClaimsSent` of 0 means no root has ever been sent, so all leaves can be emergency-exited.
 - Both `projectTokenCount` and `terminalTokenAmount` are capped at `uint128` in `_insertIntoTree` for SVM (Solana) compatibility.
 - Nonce ordering is non-sequential: `fromRemote` accepts any nonce strictly greater than the current inbox nonce. Out-of-order nonces (from CCIP) cause earlier nonces to be silently skipped, making their claims permanently unclaimable on that chain. The sender must use the emergency hatch on the source chain to recover.
+- `toRemote` fee payment is best-effort: if the fee project has no native token terminal or `terminal.pay()` reverts, `toRemote` proceeds without collecting the fee. The caller still receives project tokens from the fee payment when it succeeds.
 - `JBCCIPSucker` transport payment refund uses a low-level `call` that does NOT revert on failure. If the refund fails (e.g., caller is a non-payable contract), the excess ETH is permanently stuck. The `TransportPaymentRefundFailed` event provides observability.
 - The sucker has an unrestricted `receive()` function -- it must accept ETH from bridges, WETH unwrapping, and terminal cash-outs. Excess ETH increases `amountToAddToBalanceOf` for the project (not a double-spend risk).
 
@@ -169,7 +206,7 @@ ENABLED --> DEPRECATION_PENDING --> SENDING_DISABLED --> DEPRECATED
 | `ENABLED` | `deprecatedAfter == 0` | yes | yes | yes | yes | per-token only |
 | `DEPRECATION_PENDING` | `now < deprecatedAfter - 14 days` | yes | yes | yes | yes | per-token only |
 | `SENDING_DISABLED` | `now < deprecatedAfter` | no | no | yes | yes | all tokens |
-| `DEPRECATED` | `now >= deprecatedAfter` | no | no | no (silently ignored) | yes | all tokens |
+| `DEPRECATED` | `now >= deprecatedAfter` | no | no | yes | yes | all tokens |
 
 ## Example Integration
 

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;
@@ -328,7 +328,7 @@ Standard config across all repos:
 
 ```toml
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]