@bananapus/suckers-v6 0.0.13 → 0.0.15

package/USER_JOURNEYS.md

@@ -1,247 +1,336 @@
-# User Journeys
+# nana-suckers-v6 -- User Journeys
 
-Step-by-step flows for every major user interaction with the sucker bridging system.
+All user paths through the Juicebox V6 sucker bridging system. For each journey: entry point, key parameters, state changes, events, and edge cases.
+
+---
 
 ## 1. Deploy Suckers
 
-A project owner deploys a pair of suckers to bridge tokens between Ethereum and Optimism.
+**Entry point**: `JBSuckerRegistry.deploySuckersFor(uint256 projectId, bytes32 salt, JBSuckerDeployerConfig[] configurations)`
 
-**Actors:** Project owner, JBSuckerRegistry, JBOptimismSuckerDeployer
+**Who can call**: The project owner, or any address with the project owner's `DEPLOY_SUCKERS` permission.
 
-**Steps:**
+**Parameters**:
+- `projectId` -- The ID of the project to deploy suckers for
+- `salt` -- A salt for CREATE2 deterministic deployment. Must be the same value on both chains for the suckers to be peers
+- `configurations` -- Array of `JBSuckerDeployerConfig` structs, each containing:
+  - `deployer` -- An `IJBSuckerDeployer` address that must be on the registry's allowlist
+  - `mappings` -- Array of `JBTokenMapping` structs for initial token mappings
 
-1. Registry owner has previously called `JBSuckerRegistry.allowSuckerDeployer(optimismDeployerAddress)`.
+**State changes**:
+1. Registry enforces `DEPLOY_SUCKERS` permission from the project owner.
+2. Computes `salt = keccak256(abi.encode(_msgSender(), salt))` (sender-specific determinism). Note: the deployer also hashes the salt again with its own `_msgSender()` via `keccak256(abi.encodePacked(_msgSender(), salt))`, so the final CREATE2 salt is double-hashed (registry + deployer).
+3. For each configuration:
+   - Validates the deployer is in the allowlist; reverts with `JBSuckerRegistry_InvalidDeployer` if not.
+   - Calls `deployer.createForSender(projectId, salt)` which deploys a clone via CREATE2 and internally calls `initialize(projectId)` on the clone (setting `_localProjectId` and `deployer`). There is no separate `initialize()` call -- it happens inside `createForSender`.
+   - Stores the sucker address in `_suckersOf[projectId]`.
+   - Calls `sucker.mapTokens(configuration.mappings)` to set initial token mappings.
+4. Project owner repeats on the remote chain with the **same salt and same sender address** to deploy the matching peer sucker.
 
-2. Project owner calls `JBSuckerRegistry.deploySuckersFor(projectId, salt, configurations)` on Ethereum.
-   - `salt` must be the same value on both chains for CREATE2 address matching.
-   - `configurations` contains one entry: `JBSuckerDeployerConfig{deployer: optimismDeployer, mappings: [...]}`.
+**Events**: `SuckerDeployedFor(projectId, sucker, configuration, caller)` -- One per deployed sucker
 
-3. Registry enforces `DEPLOY_SUCKERS` permission from the project owner.
+**Edge cases**:
+- Reverts with `JBSuckerRegistry_InvalidDeployer` if any deployer is not on the allowlist
+- The sender must be the same address on both chains for CREATE2 addresses to match (peer recognition)
+- Project owner repeats the call on the remote chain with the **same salt and same sender** to deploy the matching peer
 
-4. Registry computes `salt = keccak256(abi.encode(_msgSender(), salt))` (sender-specific determinism).
+---
 
-5. For each configuration:
-   - Validates the deployer is in the allowlist.
-   - Calls `deployer.createForSender(projectId, salt)` which deploys a clone of `JBOptimismSucker` via CREATE2.
-   - The clone's `initialize(projectId)` is called, setting `_localProjectId` and `deployer`.
-   - Registry stores the sucker address in `_suckersOf[projectId]`.
-   - Calls `sucker.mapTokens(configuration.mappings)` to set initial token mappings.
+## 2. Map Token
 
-6. Project owner repeats step 2 on Optimism with the **same salt and same sender address** to deploy the matching peer sucker.
+**Entry point**: `JBSucker.mapToken(JBTokenMapping map)` (payable)
 
-**Result:** Two suckers exist at matching CREATE2 addresses. Each recognizes the other as its `peer()`. Token mappings are configured for bridging.
+**Who can call**: The project owner, or any address with the project owner's `MAP_SUCKER_TOKEN` permission.
 
-## 2. Map Token
+**Parameters**:
+- `map` -- A `JBTokenMapping` struct containing:
+  - `localToken` -- The local terminal token address (e.g., `NATIVE_TOKEN` or an ERC-20)
+  - `minGas` -- Minimum gas for bridging; must be >= `MESSENGER_ERC20_MIN_GAS_LIMIT` (200,000) for non-native tokens
+  - `remoteToken` -- The remote token address as `bytes32`. Set to `bytes32(0)` to disable bridging
 
-A project owner maps a local terminal token to its remote counterpart.
+**State changes**:
+1. Validates the emergency hatch is not enabled for the token; reverts with `JBSucker_TokenHasInvalidEmergencyHatchState` if so.
+2. `_validateTokenMapping()` checks native-token and min-gas rules.
+3. Enforces `MAP_SUCKER_TOKEN` permission from the project owner.
+4. Immutability check: if `_remoteTokenFor[token].addr != bytes32(0)` AND the new `remoteToken` differs from the current mapping AND `remoteToken != bytes32(0)` AND `_outboxOf[token].tree.count != 0`, reverts with `JBSucker_TokenAlreadyMapped`. All four conditions must be true for the revert -- notably, the mapping is only considered immutable when both the current remote address is set and the outbox has entries.
+5. If disabling a mapping (`remoteToken == bytes32(0)`) and the outbox has unsent entries, `_sendRoot()` is called first to flush them.
+6. Stores the mapping: `_remoteTokenFor[token] = JBRemoteToken{enabled: true/false, emergencyHatch: false, minGas, addr: remoteToken}`. When disabling, `addr` retains the original remote address for re-enabling.
 
-**Actors:** Project owner, JBSucker
+**Events**: None directly from `mapToken`. If a root flush occurs during disable, emits `RootToRemote(root, token, index, nonce, caller)`.
 
-**Steps:**
+**Edge cases**:
+- Reverts with `JBSucker_TokenAlreadyMapped` if the outbox has entries and remapping to a different remote token
+- Reverts with `JBSucker_TokenHasInvalidEmergencyHatchState` if the emergency hatch is already enabled for the token
+- Reverts with `JBSucker_InvalidNativeRemoteAddress` if mapping native token to a non-native, non-zero remote
+- Reverts with `JBSucker_BelowMinGas` if `minGas < MESSENGER_ERC20_MIN_GAS_LIMIT` for non-native tokens
+- Re-enabling a previously disabled mapping (to the same remote token) is supported
+- CCIP and Celo suckers override `_validateTokenMapping` to allow native-to-ERC20 mapping
+- `msg.value` is used as `transportPayment` when flushing the outbox during disable
 
-1. Project owner calls `JBSucker.mapToken(JBTokenMapping{localToken: USDC, minGas: 200_000, remoteToken: bytes32(remoteUSDC)})`.
+**Bulk variant**: `JBSucker.mapTokens(JBTokenMapping[] maps)` -- Maps multiple tokens. Splits `msg.value` evenly across mappings that require a root flush. Refunds remainder from integer division.
 
-2. The sucker enforces `MAP_SUCKER_TOKEN` permission from the project owner.
+---
 
-3. `_validateTokenMapping()` checks:
-   - For non-native tokens: `minGas >= MESSENGER_ERC20_MIN_GAS_LIMIT` (200,000).
-   - For native tokens (base class): remote must be `NATIVE_TOKEN` or `bytes32(0)`.
-   - CCIP/Celo suckers override to allow native-to-ERC20 mapping.
+## 3. Prepare (Bridge Out)
 
-4. Immutability check: if `_outboxOf[USDC].tree.count != 0` (outbox has entries) AND the current mapping exists AND the new remote differs, reverts with `TokenAlreadyMapped`.
+**Entry point**: `JBSucker.prepare(uint256 projectTokenCount, bytes32 beneficiary, uint256 minTokensReclaimed, address token)`
 
-5. Stores the mapping: `_remoteTokenFor[USDC] = JBRemoteToken{enabled: true, emergencyHatch: false, minGas: 200_000, addr: bytes32(remoteUSDC)}`.
+**Who can call**: Anyone. The caller must have approved the sucker to transfer `projectTokenCount` of their project ERC-20 tokens.
 
-**Result:** USDC is now bridgeable. Users can call `prepare()` with USDC as the terminal token.
+**Parameters**:
+- `projectTokenCount` -- Number of project tokens to cash out and bridge
+- `beneficiary` -- Recipient on the remote chain (`bytes32` for cross-VM compatibility; EVM addresses are left-padded to 32 bytes, Solana uses full 32-byte public keys)
+- `minTokensReclaimed` -- Minimum terminal tokens to receive from the cash out (slippage protection)
+- `token` -- The terminal token to cash out into (e.g., `NATIVE_TOKEN` or an ERC-20)
 
-**Disabling a mapping:** Call `mapToken(JBTokenMapping{localToken: USDC, ..., remoteToken: bytes32(0), ...})`. If the outbox has unsent entries, `_sendRoot()` is called first to flush them. The mapping is disabled (`enabled = false`) but `addr` retains the original remote address (for re-enabling later).
+**State changes**:
+1. Validates `beneficiary != bytes32(0)`; reverts with `JBSucker_ZeroBeneficiary` if zero.
+2. Validates the project has a deployed ERC-20 token; reverts with `JBSucker_ZeroERC20Token` if not.
+3. Validates `_remoteTokenFor[token].enabled == true`; reverts with `JBSucker_TokenNotMapped` if disabled.
+4. Validates sucker state is `ENABLED` or `DEPRECATION_PENDING`; reverts with `JBSucker_Deprecated` otherwise.
+5. Transfers `projectTokenCount` project tokens from caller to the sucker via `safeTransferFrom`.
+6. `_pullBackingAssets()`: calls `terminal.cashOutTokensOf()` with `beneficiary: payable(address(this))` (the sucker itself receives the reclaimed tokens) at 0% cashOutTaxRate (set by JBOmnichainDeployer as data hook). Records the reclaimed amount and asserts the balance delta matches.
+7. `_insertIntoTree()`: builds a leaf hash, inserts into `_outboxOf[token].tree`, and increments `_outboxOf[token].balance`.
 
-## 3. Prepare (Bridge Out)
+**Events**: `InsertToOutboxTree(beneficiary, token, hashed, index, root, projectTokenCount, terminalTokenAmount, caller)`
 
-A user prepares project tokens to be bridged to the remote chain.
+**Edge cases**:
+- Reverts with `JBSucker_ZeroBeneficiary` if `beneficiary == bytes32(0)`
+- Reverts with `JBSucker_ZeroERC20Token` if the project has no deployed ERC-20 token
+- Reverts with `JBSucker_TokenNotMapped` if the token mapping is not enabled
+- Reverts with `JBSucker_Deprecated` if sucker state is `SENDING_DISABLED` or `DEPRECATED`
+- Reverts with `JBSucker_AmountExceedsUint128` if `terminalTokenAmount` or `projectTokenCount` exceeds `uint128` (SVM compatibility)
+- The project tokens are burned via the cash out, and the backing assets are held by the sucker until `toRemote()` is called
 
-**Actors:** Token holder, JBSucker, JBMultiTerminal, JBController
+---
 
-**Steps:**
+## 4. Bridge (toRemote)
 
-1. User approves the sucker to spend their project tokens.
+**Entry point**: `JBSucker.toRemote(address token)` (payable)
 
-2. User calls `JBSucker.prepare(projectTokenCount: 1000, beneficiary: bytes32(userAddressOnRemote), minTokensReclaimed: 950, token: NATIVE_TOKEN)`.
+**Who can call**: Anyone. Typically called by a relayer. Requires `msg.value >= REGISTRY.toRemoteFee()` plus any bridge-specific transport payment.
 
-3. Validation:
-   - `beneficiary != bytes32(0)` (would revert on remote mint).
-   - Project has a deployed ERC-20 token.
-   - `_remoteTokenFor[NATIVE_TOKEN].enabled == true`.
-   - Sucker state is `ENABLED` or `DEPRECATION_PENDING` (not `SENDING_DISABLED` or `DEPRECATED`).
+**Parameters**:
+- `token` -- The terminal token whose outbox tree root and backing assets should be sent to the remote chain
 
-4. Transfers 1000 project tokens from user to the sucker.
+**State changes**:
+1. Validates emergency hatch is not enabled for the token; reverts with `JBSucker_TokenHasInvalidEmergencyHatchState`.
+2. Validates the outbox has something to send; reverts with `JBSucker_NothingToSend` if `outbox.balance == 0 && outbox.tree.count == outbox.numberOfClaimsSent`.
+3. Validates `msg.value >= REGISTRY.toRemoteFee()`; reverts with `JBSucker_InsufficientMsgValue` if insufficient. This check is a hard revert -- it happens before any best-effort logic.
+4. Fee deduction: deducts `toRemoteFee` from `msg.value` to compute `transportPayment = msg.value - toRemoteFee`. Then attempts to pay the fee into the fee project (ID 1) via `terminal.pay()`. The fee payment itself is best-effort: if the fee project has no native-token terminal or `pay()` reverts (via try-catch), the fee is returned to `transportPayment` and the call proceeds. Only the bridge transport cost uses the remaining `transportPayment`.
+5. `_sendRoot()`:
+   - Reads `outbox.tree.count` and `outbox.balance`.
+   - Clears `outbox.balance = 0`.
+   - Increments `outbox.nonce`.
+   - Computes `outbox.tree.root()`.
+   - Sets `outbox.numberOfClaimsSent = tree.count`.
+6. `_sendRootOverAMB()` (chain-specific): bridges assets and merkle root message to the remote peer.
+   - **OP Stack**: `OPMESSENGER.sendMessage{value: amount}()` bridges ETH and encodes `JBSucker.fromRemote(messageRoot)`
+   - **Arbitrum**: Two retryable tickets -- one for ERC-20 via gateway router, one for the merkle root message via inbox
+   - **CCIP**: Wraps native ETH to WETH, calls `CCIP_ROUTER.ccipSend()` with token amounts and message data
 
-5. `_pullBackingAssets()`:
-   - Gets the project's primary terminal for `NATIVE_TOKEN`.
-   - Calls `terminal.cashOutTokensOf(address(this), projectId, 1000, NATIVE_TOKEN, 950, payable(address(this)), "")`.
-   - The sucker cashes out with 0% cashOutTaxRate (configured by JBOmnichainDeployer as data hook).
-   - Records `balanceBefore`, asserts `reclaimedAmount == balanceAfter - balanceBefore`.
-   - Returns `reclaimedAmount` (e.g., 0.5 ETH).
+**Events**: `RootToRemote(root, token, index, nonce, caller)`
 
-6. `_insertIntoTree()`:
-   - Guards: `terminalTokenAmount` and `projectTokenCount` fit in `uint128`.
-   - Builds leaf hash: `keccak256(abi.encode(1000, 500000000000000000, beneficiary))`.
-   - Inserts into `_outboxOf[NATIVE_TOKEN].tree` via `MerkleLib.insert()`.
-   - Updates `_outboxOf[NATIVE_TOKEN].balance += 0.5 ETH`.
+**Edge cases**:
+- Reverts with `JBSucker_TokenHasInvalidEmergencyHatchState` if the emergency hatch is enabled for this token
+- Reverts with `JBSucker_NothingToSend` if `outbox.balance == 0 && outbox.tree.count == outbox.numberOfClaimsSent`
+- Reverts with `JBSucker_InsufficientMsgValue` if `msg.value < REGISTRY.toRemoteFee()`
+- Reverts with `JBSucker_Deprecated` if sucker state is `SENDING_DISABLED` or `DEPRECATED`
+- If the outbox tree is empty (`count == 0`), `_sendRoot` returns early without sending
+- The `toRemoteFee` is global across all suckers, set by the registry owner via `setToRemoteFee()`, capped at `MAX_TO_REMOTE_FEE` (0.001 ether)
+- Transport payment (0 for OP bridges, non-zero for Arbitrum L1->L2 and CCIP) is the remainder after fee deduction
 
-7. Emits `InsertToOutboxTree` with the leaf details and updated root.
+---
 
-**Result:** The user's project tokens are burned (via cash out), the backing ETH is held by the sucker, and a leaf is recorded in the outbox merkle tree. The user waits for someone to call `toRemote()`.
+## 5. Receive Root (fromRemote)
 
-## 4. Bridge (toRemote)
+**Entry point**: `JBSucker.fromRemote(JBMessageRoot root)` (payable)
 
-Anyone triggers the bridge to send the outbox root and backing assets to the remote chain.
+**Who can call**: Only the authenticated bridge messenger representing the remote peer. Validated via `_isRemotePeer(_msgSender())`.
 
-**Actors:** Relayer (anyone), JBSucker, Bridge infrastructure
+**Parameters**:
+- `root` -- A `JBMessageRoot` struct containing:
+  - `version` -- Message format version (must equal `MESSAGE_VERSION`, currently 1)
+  - `token` -- The remote token address as `bytes32` (converted to local address for inbox lookup)
+  - `amount` -- The amount of terminal tokens being delivered
+  - `remoteRoot` -- A `JBInboxTreeRoot` with `nonce` and `root` (the merkle root)
 
-**Steps:**
+**State changes**:
+1. If `root.remoteRoot.nonce > inbox.nonce` AND state is not `DEPRECATED`:
+   1. `_inboxOf[localToken].nonce = root.remoteRoot.nonce` -- Updates the inbox nonce
+   2. `_inboxOf[localToken].root = root.remoteRoot.root` -- Updates the inbox merkle root
 
-1. Relayer calls `JBSucker.toRemote{value: transportPayment}(NATIVE_TOKEN)`.
-   - `transportPayment` is 0 for OP bridges, non-zero for Arbitrum L1->L2 and CCIP.
+**Events**:
+- On success: `NewInboxTreeRoot(token, nonce, root, caller)`
+- On rejection: `StaleRootRejected(token, receivedNonce, currentNonce)` -- emitted if the nonce is not newer OR if the sucker is `DEPRECATED` (even with a valid newer nonce, deprecated suckers reject new roots to prevent double-spend with emergency hatch withdrawals)
 
-2. Validation:
-   - Emergency hatch not enabled for this token.
-   - "Nothing to send" guard: reverts if `outbox.balance == 0 && outbox.tree.count == outbox.numberOfClaimsSent`.
-   - If `REGISTRY.toRemoteFee() != 0`: deducts the fee from `msg.value` and pays it into the fee project (`FEE_PROJECT_ID`, typically project ID 1) via `terminal.pay()`. The caller (relayer) receives project tokens. Best-effort: if the fee project has no native token terminal or `terminal.pay()` reverts, proceeds without collecting the fee. Remainder is passed as `transportPayment`. The fee is global across all suckers, set by the registry owner via `JBSuckerRegistry.setToRemoteFee()`, capped at `MAX_TO_REMOTE_FEE` (0.001 ether).
-   - Sucker not deprecated/sending-disabled.
+**Edge cases**:
+- Reverts with `JBSucker_NotPeer` if the sender is not the authenticated remote peer
+- Reverts with `JBSucker_InvalidMessageVersion` if `root.version != MESSAGE_VERSION`
+- Does NOT revert for stale nonces -- emits `StaleRootRejected` instead (because reverting could lose native tokens delivered with the message)
+- Accepts roots for unmapped tokens (rejecting would permanently lose bridged tokens; future mapping enables claims)
+- Nonce gaps are expected -- some bridges (e.g., CCIP) do not guarantee in-order delivery
+- Deprecated suckers reject new roots to prevent double-spend (project owner may have enabled emergency hatch for local withdrawals)
 
-3. `_sendRoot()`:
-   - Reads `outbox.tree.count` and `outbox.balance` (e.g., 2.5 ETH across multiple prepares).
-   - Clears `outbox.balance = 0`.
-   - Increments `outbox.nonce`.
-   - Computes `outbox.tree.root()`.
-   - Sets `outbox.numberOfClaimsSent = tree.count` (used for emergency exit bounds).
-   - Builds `JBMessageRoot{version: 1, token: remoteTokenAddr, amount: 2.5 ETH, remoteRoot: {nonce, root}}`.
+---
+
+## 6. Claim (Bridge In)
+
+**Entry point**: `JBSucker.claim(JBClaim claimData)` or `JBSucker.claim(JBClaim[] claims)` for batch
 
-4. `_sendRootOverAMB()` (chain-specific):
-   - **OP Stack**: Bridges ETH via `OPMESSENGER.sendMessage{value: 2.5 ETH}()` to `peer()`. Message encodes `JBSucker.fromRemote(messageRoot)`.
-   - **Arbitrum L1->L2**: Bridges ERC-20 via gateway router (retryable ticket 1), sends merkle root message via inbox (retryable ticket 2). Two independent tickets.
-   - **CCIP**: Wraps native ETH to WETH, calls `CCIP_ROUTER.ccipSend()` with token amounts and message data.
+**Who can call**: Anyone. The beneficiary receives the tokens regardless of who calls.
 
-**Result:** The merkle root and backing assets are in transit to the remote chain. The bridge delivers them according to its own timeline (minutes to hours depending on the bridge).
+**Parameters**:
+- `claimData` -- A `JBClaim` struct containing:
+  - `token` -- The local terminal token address
+  - `leaf` -- A `JBLeaf` struct with `index`, `beneficiary` (bytes32), `projectTokenCount`, `terminalTokenAmount`
+  - `proof` -- A `bytes32[32]` merkle proof (32 = `_TREE_DEPTH`)
 
-## 5. Claim (Bridge In)
+**State changes**:
+1. `_validate()`:
+   1. `_executedFor[token].get(index)` -- Checks leaf not already claimed
+   2. `_executedFor[token].set(index)` -- Marks leaf as claimed
+   3. Computes `MerkleLib.branchRoot(leafHash, proof, index)` and compares to `_inboxOf[token].root`
+2. `_handleClaim()`:
+   1. If `terminalTokenAmount > 0`: calls `terminal.addToBalanceOf{value: amount}(projectId, token, amount, false, "", "")` -- Adds backing assets to the project's terminal balance
+   2. `controller.mintTokensOf(projectId, projectTokenCount, beneficiary, "", false)` -- Mints project tokens for the beneficiary with `useReservedPercent = false` (suckers bypass reserved percent)
 
-A beneficiary claims their bridged tokens on the destination chain.
+**Events**: `Claimed(beneficiary, token, projectTokenCount, terminalTokenAmount, index, caller)`
 
-**Actors:** Beneficiary (or anyone on their behalf), JBSucker (destination), JBController
+**Edge cases**:
+- Reverts with `JBSucker_LeafAlreadyExecuted` if the leaf at `index` was already claimed
+- Reverts with `JBSucker_InvalidProof` if the merkle proof does not match the inbox root
+- Reverts if the project's controller is misconfigured or the project doesn't exist on the destination chain (permanently blocks claims -- a deployment concern)
+- Off-chain: a relayer must compute the merkle proof from `InsertToOutboxTree` events on the source chain
+- If nonces arrive out of order, users need regenerated proofs against the current root (the merkle tree is append-only, so all leaves remain provable)
+- Batch `claim(JBClaim[])` simply loops over each claim
 
-**Steps:**
+---
 
-1. Bridge delivers the message. The bridge messenger calls `JBSucker.fromRemote(JBMessageRoot)`.
+## 7. Deprecate Sucker
 
-2. `fromRemote()` validates:
-   - `_isRemotePeer(_msgSender())` -- verifies the bridge messenger represents the authenticated peer.
-   - `root.version == MESSAGE_VERSION` (1).
-   - `root.remoteRoot.nonce > inbox.nonce` -- only accepts newer roots.
-   - Sucker state is not `DEPRECATED`.
+**Entry point**: `JBSucker.setDeprecation(uint40 timestamp)`
 
-3. Updates `_inboxOf[localToken].root = root.remoteRoot.root` and `_inboxOf[localToken].nonce = root.remoteRoot.nonce`.
+**Who can call**: The project owner, or any address with the project owner's `SET_SUCKER_DEPRECATION` permission.
 
-4. Off-chain: a relayer computes the merkle proof for the beneficiary's leaf against the inbox root. This requires knowing all leaves in the tree (from `InsertToOutboxTree` events on the source chain).
+**Parameters**:
+- `timestamp` -- The time after which the sucker is deprecated. Must be `0` (cancel deprecation) or `>= block.timestamp + _maxMessagingDelay()` (14 days minimum). Type is `uint40`.
 
-5. Beneficiary (or anyone) calls `JBSucker.claim(JBClaim{token: ETH, leaf: {index: 3, beneficiary: userAddr, projectTokenCount: 1000, terminalTokenAmount: 0.5 ETH}, proof: [...]})`.
+**State changes**:
+1. `deprecatedAfter = timestamp` -- Sets or clears the deprecation timestamp
 
-6. `_validate()`:
-   - Checks `_executedFor[ETH].get(3)` is false (not already claimed).
-   - Sets `_executedFor[ETH].set(3)` (marks as claimed).
-   - Builds leaf hash: `keccak256(abi.encode(1000, 500000000000000000, beneficiary))`.
-   - Computes root via `MerkleLib.branchRoot(hash, proof, 3)`.
-   - Compares to `_inboxOf[ETH].root` -- reverts with `InvalidProof` if mismatch.
+**Events**: `DeprecationTimeUpdated(timestamp, caller)`
 
-7. `_handleClaim()`:
-   - If `terminalTokenAmount > 0`:
-     - Calls `_addToBalance(ETH, 0.5 ETH)` which forwards to `terminal.addToBalanceOf{value: 0.5 ETH}(projectId, ...)`.
-   - Mints 1000 project tokens for the beneficiary via `controller.mintTokensOf(projectId, 1000, beneficiary, "", false)`.
-     - `useReservedPercent = false` -- sucker mints bypass the reserved percent.
+**State progression over time**:
+- **Now -> timestamp - 14 days**: `DEPRECATION_PENDING`. All operations work normally. Users are warned.
+- **timestamp - 14 days -> timestamp**: `SENDING_DISABLED`. `prepare()` and `toRemote()` revert. `fromRemote()` still accepts roots. `claim()` still works. `exitThroughEmergencyHatch()` works (even without enabling the emergency hatch per-token).
+- **After timestamp**: `DEPRECATED`. `fromRemote()` rejects new roots. `claim()` still works for existing inbox roots. `exitThroughEmergencyHatch()` works (even without enabling the emergency hatch per-token).
 
-**Result:** The beneficiary receives 1000 project tokens on the destination chain. The 0.5 ETH backing is added to the project's terminal balance.
+**Edge cases**:
+- Reverts with `JBSucker_Deprecated` if state is already `SENDING_DISABLED` or `DEPRECATED`
+- Reverts with `JBSucker_DeprecationTimestampTooSoon` if `timestamp != 0` and `timestamp < block.timestamp + _maxMessagingDelay()`
+- Cancellation: call `setDeprecation(0)` before reaching `SENDING_DISABLED` state
 
-## 6. Deprecate Sucker
+**Registry cleanup**: Anyone calls `JBSuckerRegistry.removeDeprecatedSucker(uint256 projectId, address sucker)` after the sucker reaches `DEPRECATED` state. This removes the sucker from `_suckersOf[projectId]` and emits `SuckerDeprecated(projectId, sucker, caller)`. Reverts with `JBSuckerRegistry_SuckerDoesNotBelongToProject` if the sucker is not registered, or `JBSuckerRegistry_SuckerIsNotDeprecated` if not yet deprecated.
 
-A project owner deprecates a sucker pair, progressively disabling operations.
+---
 
-**Actors:** Project owner, JBSucker
+## 8. Enable Emergency Hatch
 
-**Steps:**
+**Entry point**: `JBSucker.enableEmergencyHatchFor(address[] tokens)`
 
-1. Project owner calls `JBSucker.setDeprecation(timestamp)` on both chains, ideally with matching timestamps.
+**Who can call**: The project owner, or any address with the project owner's `SUCKER_SAFETY` permission.
 
-2. Validation:
-   - Sucker state is `ENABLED` or `DEPRECATION_PENDING` (cannot change if already `SENDING_DISABLED` or `DEPRECATED`).
-   - `SET_SUCKER_DEPRECATION` permission from project owner.
-   - `timestamp == 0` (cancel) OR `timestamp >= block.timestamp + _maxMessagingDelay()` (14 days minimum).
+**Parameters**:
+- `tokens` -- Array of terminal token addresses to enable the emergency hatch for
 
-3. Sets `deprecatedAfter = timestamp`.
+**State changes**:
+1. For each token:
+   1. `_remoteTokenFor[token].enabled = false` -- Disables bridging for the token
+   2. `_remoteTokenFor[token].emergencyHatch = true` -- Enables emergency exit
 
-4. State progression over time:
-   - **Now -> timestamp - 14 days**: `DEPRECATION_PENDING`. All operations work normally. Users are warned.
-   - **timestamp - 14 days -> timestamp**: `SENDING_DISABLED`. `prepare()` and `toRemote()` revert. `fromRemote()` still accepts roots. `claim()` still works.
-   - **After timestamp**: `DEPRECATED`. `fromRemote()` rejects new roots. `claim()` still works for existing inbox roots. `exitThroughEmergencyHatch()` works.
+**Events**: `EmergencyHatchOpened(tokens, caller)`
 
-5. **Cancellation**: Project owner calls `setDeprecation(0)` before reaching `SENDING_DISABLED` state.
+**Edge cases**:
+- **Irreversible**: Once the emergency hatch is enabled for a token, it cannot be disabled
+- No explicit revert for empty array (no-op)
+- Does not require the sucker to be in any particular state
 
-6. **Registry cleanup**: Anyone calls `JBSuckerRegistry.removeDeprecatedSucker(projectId, suckerAddress)` after the sucker reaches `DEPRECATED` state.
+---
 
-**Result:** The sucker is gracefully wound down. Users have 14+ days to claim pending bridges. No new bridges can be initiated.
+## 9. Exit Through Emergency Hatch
 
-## 7. Enable Emergency Hatch
+**Entry point**: `JBSucker.exitThroughEmergencyHatch(JBClaim claimData)`
 
-A project owner enables the emergency exit for tokens stuck in a broken bridge.
+**Who can call**: Anyone. The beneficiary receives the tokens regardless of who calls.
 
-**Actors:** Project owner, JBSucker, affected token holders
+**Parameters**:
+- `claimData` -- A `JBClaim` struct containing:
+  - `token` -- The local terminal token address
+  - `leaf` -- A `JBLeaf` struct with `index`, `beneficiary` (bytes32), `projectTokenCount`, `terminalTokenAmount`
+  - `proof` -- A `bytes32[32]` merkle proof against the **outbox** tree root (not inbox)
 
-**Steps:**
+**State changes**:
+1. `_validateForEmergencyExit()`:
+   1. Checks emergency hatch is enabled for the token (or sucker is `DEPRECATED`/`SENDING_DISABLED`)
+   2. Checks `index >= numberOfClaimsSent` or `numberOfClaimsSent == 0` (the leaf was NOT sent to the remote peer)
+   3. Uses a separate bitmap slot (`address(bytes20(keccak256(abi.encode(token))))`) to prevent collision with regular claims
+   4. Marks the leaf as executed in the emergency exit bitmap
+   5. Validates the merkle proof against `_outboxOf[token].tree.root()`
+2. `_outboxOf[token].balance -= terminalTokenAmount` -- Decreases the outbox balance
+3. `_handleClaim()`:
+   1. If `terminalTokenAmount > 0`: `terminal.addToBalanceOf(projectId, token, amount, ...)` -- Adds tokens back to project balance
+   2. `controller.mintTokensOf(projectId, projectTokenCount, beneficiary, "", false)` -- Mints project tokens for the beneficiary
 
-1. A bridge becomes non-functional (e.g., OP Stack bridge bug, token incompatibility). Tokens are stuck in the sucker's outbox.
+**Events**: `EmergencyExit(beneficiary, token, terminalTokenAmount, projectTokenCount, caller)`
 
-2. Project owner calls `JBSucker.enableEmergencyHatchFor([NATIVE_TOKEN, USDC])`.
+**Edge cases**:
+- Reverts with `JBSucker_TokenHasInvalidEmergencyHatchState` if emergency hatch is not enabled AND sucker is not `DEPRECATED`/`SENDING_DISABLED`
+- Reverts with `JBSucker_LeafAlreadyExecuted` if `index < numberOfClaimsSent` (leaf was already sent to remote peer) or if already emergency-exited
+- Reverts with `JBSucker_InvalidProof` if the merkle proof does not match the outbox root
+- **Important limitation**: If `_sendRoot()` was called (incrementing `numberOfClaimsSent`) but the bridge message was never delivered, leaves with `index < numberOfClaimsSent` are blocked from emergency exit even though they cannot be claimed remotely. This is a conservative failure mode (funds locked, not double-spent). The deprecation flow provides an alternative exit path.
+- Only leaves NOT already sent to the remote peer can be emergency-exited
 
-3. Validation:
-   - `SUCKER_SAFETY` permission from project owner.
-   - For each token: sets `_remoteTokenFor[token].enabled = false` and `_remoteTokenFor[token].emergencyHatch = true`.
-   - **Irreversible**: Once the emergency hatch is enabled for a token, it cannot be disabled.
+---
 
-4. Affected users call `JBSucker.exitThroughEmergencyHatch(JBClaim{...})` with their prepare data.
+## 10. Register Sucker Deployer
 
-5. `_validateForEmergencyExit()`:
-   - Confirms emergency hatch is enabled for the token (or sucker is deprecated/sending-disabled).
-   - Checks `index >= numberOfClaimsSent` or `numberOfClaimsSent == 0` (the leaf was NOT sent to the remote peer).
-   - Uses a separate bitmap slot (derived from `keccak256(abi.encode(terminalToken))`) to prevent collision with regular claims.
-   - Validates the merkle proof against the **outbox** tree root (not inbox).
+**Entry point**: `JBSuckerRegistry.allowSuckerDeployer(address deployer)` or `JBSuckerRegistry.allowSuckerDeployers(address[] deployers)` for batch
 
-6. Decreases `_outboxOf[token].balance -= terminalTokenAmount`.
+**Who can call**: Only the registry `owner` (Ownable). Initially JuiceboxDAO / project #1.
 
-7. `_handleClaim()`:
-   - Adds terminal tokens back to the project's balance.
-   - Mints project tokens for the beneficiary.
+**Parameters**:
+- `deployer` -- The address of the sucker deployer contract to add to the allowlist
+- `deployers` (batch variant) -- Array of deployer addresses
 
-**Result:** Users recover their tokens locally without the bridge. Only leaves that were NOT already sent to the remote peer can be emergency-exited (leaves that were sent must be claimed on the remote chain).
+**State changes**:
+1. `suckerDeployerIsAllowed[deployer] = true` -- Adds the deployer to the allowlist
 
-**Important limitation:** If `_sendRoot()` was called (incrementing `numberOfClaimsSent`) but the bridge message was never delivered, leaves with `index < numberOfClaimsSent` are blocked from emergency exit even though they cannot be claimed remotely. This is a conservative failure mode (funds locked, not double-spent). The deprecation flow provides an alternative exit path.
+**Events**: `SuckerDeployerAllowed(deployer, caller)` -- One per deployer
 
-## 8. Register Sucker Deployer
+**Edge cases**:
+- Reverts with `OwnableUnauthorizedAccount` if caller is not the owner
+- Idempotent: calling again on an already-allowed deployer is a no-op (re-sets to `true`)
 
-The registry owner adds a new sucker deployer implementation.
+**Removing a deployer**: `JBSuckerRegistry.removeSuckerDeployer(address deployer)` -- Sets `suckerDeployerIsAllowed[deployer] = false`. Emits `SuckerDeployerRemoved(deployer, caller)`. Existing suckers deployed by this deployer continue operating.
 
-**Actors:** Registry owner (initially JuiceboxDAO / project #1), JBSuckerRegistry
+---
 
-**Steps:**
+## 11. Set toRemote Fee
 
-1. A new sucker deployer contract is deployed (e.g., `JBCCIPSuckerDeployer` for a new chain).
+**Entry point**: `JBSuckerRegistry.setToRemoteFee(uint256 fee)`
 
-2. Registry owner calls `JBSuckerRegistry.allowSuckerDeployer(deployerAddress)`.
-   - Only the registry `owner` (Ownable) can call this.
+**Who can call**: Only the registry `owner` (Ownable).
 
-3. Sets `suckerDeployerIsAllowed[deployerAddress] = true`.
+**Parameters**:
+- `fee` -- The new ETH fee in wei, paid into the fee project on each `toRemote()` call
 
-4. Projects can now use this deployer in `deploySuckersFor()` configurations.
+**State changes**:
+1. `toRemoteFee = fee` -- Updates the global fee
 
-**Removing a deployer:** Registry owner calls `removeSuckerDeployer(deployerAddress)`. Sets `suckerDeployerIsAllowed[deployerAddress] = false`. Existing suckers deployed by this deployer are unaffected -- they continue operating.
+**Events**: `ToRemoteFeeChanged(oldFee, fee, caller)`
 
-**Result:** A new bridge implementation is available for projects to deploy suckers with.
+**Edge cases**:
+- Reverts with `JBSuckerRegistry_FeeExceedsMax` if `fee > MAX_TO_REMOTE_FEE` (0.001 ether)
+- The fee is initialized to `MAX_TO_REMOTE_FEE` in the constructor
+- Setting to 0 effectively disables the fee

package/foundry.toml

@@ -1,5 +1,5 @@
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,8 +19,8 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "^1.2.1",
-    "@bananapus/core-v6": "^0.0.23",
-    "@bananapus/permission-ids-v6": "^0.0.10",
+    "@bananapus/core-v6": "^0.0.25",
+    "@bananapus/permission-ids-v6": "^0.0.11",
     "@chainlink/contracts-ccip": "^1.5.0",
     "@chainlink/local": "github:smartcontractkit/chainlink-local",
     "@openzeppelin/contracts": "^5.6.1",

package/script/Deploy.s.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 import {IInbox} from "@arbitrum/nitro-contracts/src/bridge/IInbox.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
@@ -52,7 +52,7 @@ contract DeployScript is Script, Sphinx {
 
     function configureSphinx() public override {
         // TODO: Update to contain JB Emergency Developers
-        sphinxConfig.projectName = "nana-suckers-v5";
+        sphinxConfig.projectName = "nana-suckers-v6";
         sphinxConfig.mainnets = ["ethereum", "optimism", "base", "arbitrum"];
         sphinxConfig.testnets = ["ethereum_sepolia", "optimism_sepolia", "base_sepolia", "arbitrum_sepolia"];
     }
@@ -71,6 +71,14 @@ contract DeployScript is Script, Sphinx {
         deploy();
     }
 
+    /// @dev Ownership transfer ordering: This function deploys multiple contracts and performs configuration in a
+    /// specific sequence. If the deployment is interrupted (e.g., by an out-of-gas error or a revert in one of the
+    /// deployer steps), intermediate states are possible where some deployers are created but not yet approved in the
+    /// registry, or the registry's ownership has not yet been transferred. When using Sphinx for deployment, the
+    /// entire `deploy()` function executes atomically within a single Gnosis Safe transaction, so partial deployment
+    /// states are not possible on-chain. However, if this script is used outside of Sphinx (e.g., via `forge script`
+    /// with `--broadcast`), each internal call would be a separate transaction, and an interruption could leave the
+    /// system in a partially configured state requiring manual intervention.
     function deploy() public sphinx {
         // Deploy the registry first — singletons need its address as an immutable.
         // If the registry is already deployed we don't have to deploy it
@@ -550,6 +558,27 @@ contract DeployScript is Script, Sphinx {
         internal
         returns (JBCCIPSuckerDeployer deployer)
     {
+        // Check if this CCIP deployer is already deployed on this chain,
+        // if that is the case we return the existing address and skip redeployment.
+        if (_isDeployed({
+                salt: salt,
+                creationCode: type(JBCCIPSuckerDeployer).creationCode,
+                arguments: abi.encode(directory, permissions, tokens, configurator, trustedForwarder)
+            })) {
+            return JBCCIPSuckerDeployer(
+                vm.computeCreate2Address({
+                    salt: salt,
+                    initCodeHash: keccak256(
+                        abi.encodePacked(
+                            type(JBCCIPSuckerDeployer).creationCode,
+                            abi.encode(directory, permissions, tokens, configurator, trustedForwarder)
+                        )
+                    ),
+                    deployer: address(0x4e59b44847b379578588920cA78FbF26c0B4956C)
+                })
+            );
+        }
+
         deployer = new JBCCIPSuckerDeployer{salt: salt}({
             directory: directory,
             permissions: permissions,