@bananapus/suckers-v6 0.0.19 → 0.0.21

package/USER_JOURNEYS.md

@@ -1,336 +1,72 @@
-# nana-suckers-v6 -- User Journeys
+# User Journeys
 
-All user paths through the Juicebox V6 sucker bridging system. For each journey: entry point, key parameters, state changes, events, and edge cases.
+## Who This Repo Serves
 
----
+- projects that want canonical cross-chain movement of project-token positions
+- operators deploying and registering sucker pairs on supported bridge families
+- users bridging a project position from one chain to another
+- teams responsible for bridge fees, token mappings, deprecation, and emergency controls
 
-## 1. Deploy Suckers
+## Journey 1: Launch A Cross-Chain Sucker Pair For A Project
 
-**Entry point**: `JBSuckerRegistry.deploySuckersFor(uint256 projectId, bytes32 salt, JBSuckerDeployerConfig[] configurations)`
+**Starting state:** the project exists on multiple chains or plans to, and the team has chosen the bridge family it trusts.
 
-**Who can call**: The project owner, or any address with the project owner's `DEPLOY_SUCKERS` permission.
+**Success:** paired suckers are deployed, registered, and ready to transport claims between the chains they serve.
 
-**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
+**Flow**
+1. Choose the chain-specific sucker implementation and deployer, such as Arbitrum, OP Stack, Celo, or CCIP.
+2. Configure token mappings, bridge counterparties, and per-project registry state in `JBSuckerRegistry`.
+3. Deploy the pair so each side knows its remote peer and expected transport assumptions.
+4. Frontends and operators can now reason about the bridge as a known project surface instead of ad hoc per-transfer logic.
 
-**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.
+## Journey 2: Bridge A Position From One Chain To Another
 
-**Events**: `SuckerDeployedFor(projectId, sucker, configuration, caller)` -- One per deployed sucker
+**Starting state:** a user holds project-token exposure on the source chain and wants the corresponding position on the destination chain.
 
-**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
+**Success:** the source position becomes a claim, the claim is relayed, and the destination position is minted after proof verification.
 
----
+**Flow**
+1. The user calls `prepare` on the source-chain sucker to burn or lock the relevant local position into a claimable leaf.
+2. The source sucker appends that leaf into its Merkle outbox tree.
+3. Someone relays the new root to the remote chain using `toRemote`.
+4. The claimant proves inclusion against the remote inbox tree and receives the recreated project-token position there.
 
-## 2. Map Token
+**Failure cases that matter:** wrong token mappings, transport-layer fee shortages, root ordering mistakes, and assuming the bridge is generic ERC-20 transport when it is really project-position transport.
 
-**Entry point**: `JBSucker.mapToken(JBTokenMapping map)` (payable)
+## Journey 3: Map Treasury Assets And Project Tokens Correctly Across Chains
 
-**Who can call**: The project owner, or any address with the project owner's `MAP_SUCKER_TOKEN` permission.
+**Starting state:** the project supports multiple assets or wrappers across chains and wants users to bridge without silent economic mismatch.
 
-**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
+**Success:** the remote claim recreates the intended exposure instead of a superficially similar but economically different asset.
 
-**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.
+**Flow**
+1. Configure remote token metadata and mapping with the sucker pair.
+2. Make sure the destination chain can mint or settle the project-token representation the bridge expects.
+3. Audit chain-specific native-asset handling, especially on Celo or other non-identical environments.
 
-**Events**: None directly from `mapToken`. If a root flush occurs during disable, emits `RootToRemote(root, token, index, nonce, caller)`.
+## Journey 4: Operate The Bridge Safely Over Time
 
-**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
+**Starting state:** the bridge is live and now needs operational stewardship rather than just deployment.
 
-**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.
+**Success:** fee policy, deprecation, trusted counterparties, and emergency paths remain coherent as conditions change.
 
----
+**Flow**
+1. Use `JBSuckerRegistry` to manage deployer allowlists and shared operational config.
+2. Watch fee fallback paths and transport assumptions because delivery failure is part of the intended threat model.
+3. Use deprecation or emergency surfaces when a bridge family or remote destination should no longer be used.
 
-## 3. Prepare (Bridge Out)
+## Journey 5: Recover Value Through The Emergency Hatch When Normal Delivery Breaks
 
-**Entry point**: `JBSucker.prepare(uint256 projectTokenCount, bytes32 beneficiary, uint256 minTokensReclaimed, address token)`
+**Starting state:** a claim cannot complete through the normal inbox or remote-delivery path.
 
-**Who can call**: Anyone. The caller must have approved the sucker to transfer `projectTokenCount` of their project ERC-20 tokens.
+**Success:** users can recover through the explicit emergency mechanism without double-spending the same claim.
 
-**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)
+**Flow**
+1. Enable or enter the emergency mode the sucker pair exposes for the affected path.
+2. Use `exitThroughEmergencyHatch(...)` with the relevant claim data.
+3. Treat emergency execution slots as distinct state that still must not allow the same economic position to be claimed twice.
 
-**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`.
+## Hand-Offs
 
-**Events**: `InsertToOutboxTree(beneficiary, token, hashed, index, root, projectTokenCount, terminalTokenAmount, caller)`
-
-**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
-
----
-
-## 4. Bridge (toRemote)
-
-**Entry point**: `JBSucker.toRemote(address token)` (payable)
-
-**Who can call**: Anyone. Typically called by a relayer. Requires `msg.value >= REGISTRY.toRemoteFee()` plus any bridge-specific transport payment.
-
-**Parameters**:
-- `token` -- The terminal token whose outbox tree root and backing assets should be sent to the remote chain
-
-**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
-
-**Events**: `RootToRemote(root, token, index, nonce, caller)`
-
-**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
-
----
-
-## 5. Receive Root (fromRemote)
-
-**Entry point**: `JBSucker.fromRemote(JBMessageRoot root)` (payable)
-
-**Who can call**: Only the authenticated bridge messenger representing the remote peer. Validated via `_isRemotePeer(_msgSender())`.
-
-**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)
-
-**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
-
-**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)
-
-**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)
-
----
-
-## 6. Claim (Bridge In)
-
-**Entry point**: `JBSucker.claim(JBClaim claimData)` or `JBSucker.claim(JBClaim[] claims)` for batch
-
-**Who can call**: Anyone. The beneficiary receives the tokens regardless of who calls.
-
-**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`)
-
-**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)
-
-**Events**: `Claimed(beneficiary, token, projectTokenCount, terminalTokenAmount, index, caller)`
-
-**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
-
----
-
-## 7. Deprecate Sucker
-
-**Entry point**: `JBSucker.setDeprecation(uint40 timestamp)`
-
-**Who can call**: The project owner, or any address with the project owner's `SET_SUCKER_DEPRECATION` permission.
-
-**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`.
-
-**State changes**:
-1. `deprecatedAfter = timestamp` -- Sets or clears the deprecation timestamp
-
-**Events**: `DeprecationTimeUpdated(timestamp, caller)`
-
-**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).
-
-**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
-
-**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.
-
----
-
-## 8. Enable Emergency Hatch
-
-**Entry point**: `JBSucker.enableEmergencyHatchFor(address[] tokens)`
-
-**Who can call**: The project owner, or any address with the project owner's `SUCKER_SAFETY` permission.
-
-**Parameters**:
-- `tokens` -- Array of terminal token addresses to enable the emergency hatch for
-
-**State changes**:
-1. For each token:
-   1. `_remoteTokenFor[token].enabled = false` -- Disables bridging for the token
-   2. `_remoteTokenFor[token].emergencyHatch = true` -- Enables emergency exit
-
-**Events**: `EmergencyHatchOpened(tokens, caller)`
-
-**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
-
----
-
-## 9. Exit Through Emergency Hatch
-
-**Entry point**: `JBSucker.exitThroughEmergencyHatch(JBClaim claimData)`
-
-**Who can call**: Anyone. The beneficiary receives the tokens regardless of who calls.
-
-**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)
-
-**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
-
-**Events**: `EmergencyExit(beneficiary, token, terminalTokenAmount, projectTokenCount, caller)`
-
-**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
-
----
-
-## 10. Register Sucker Deployer
-
-**Entry point**: `JBSuckerRegistry.allowSuckerDeployer(address deployer)` or `JBSuckerRegistry.allowSuckerDeployers(address[] deployers)` for batch
-
-**Who can call**: Only the registry `owner` (Ownable). Initially JuiceboxDAO / project #1.
-
-**Parameters**:
-- `deployer` -- The address of the sucker deployer contract to add to the allowlist
-- `deployers` (batch variant) -- Array of deployer addresses
-
-**State changes**:
-1. `suckerDeployerIsAllowed[deployer] = true` -- Adds the deployer to the allowlist
-
-**Events**: `SuckerDeployerAllowed(deployer, caller)` -- One per 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`)
-
-**Removing a deployer**: `JBSuckerRegistry.removeSuckerDeployer(address deployer)` -- Sets `suckerDeployerIsAllowed[deployer] = false`. Emits `SuckerDeployerRemoved(deployer, caller)`. Existing suckers deployed by this deployer continue operating.
-
----
-
-## 11. Set toRemote Fee
-
-**Entry point**: `JBSuckerRegistry.setToRemoteFee(uint256 fee)`
-
-**Who can call**: Only the registry `owner` (Ownable).
-
-**Parameters**:
-- `fee` -- The new ETH fee in wei, paid into the fee project on each `toRemote()` call
-
-**State changes**:
-1. `toRemoteFee = fee` -- Updates the global fee
-
-**Events**: `ToRemoteFeeChanged(oldFee, fee, caller)`
-
-**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
+- Use [nana-omnichain-deployers-v6](../nana-omnichain-deployers-v6/USER_JOURNEYS.md) when a project wants suckers packaged into its launch flow instead of deployed separately.
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) or [revnet-core-v6](../revnet-core-v6/USER_JOURNEYS.md) for the treasury and runtime project behavior that suckers transport across chains.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,9 +19,8 @@
   },
   "dependencies": {
     "@arbitrum/nitro-contracts": "^1.2.1",
-    "@bananapus/address-registry-v6": "^0.0.16",
-    "@bananapus/core-v6": "^0.0.28",
-    "@bananapus/permission-ids-v6": "^0.0.14",
+    "@bananapus/core-v6": "^0.0.31",
+    "@bananapus/permission-ids-v6": "^0.0.15",
     "@chainlink/contracts-ccip": "^1.5.0",
     "@chainlink/local": "github:smartcontractkit/chainlink-local",
     "@openzeppelin/contracts": "^5.6.1",

package/references/operations.md

@@ -0,0 +1,25 @@
+# Suckers Operations
+
+## Configuration Surface
+
+- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) is the first stop for deployer allowlists, shared fees, project inventory, and deprecation helpers.
+- Transport-specific deployers in [`src/deployers/`](../src/deployers/) are where chain-specific constants and bridge addresses live.
+- [`script/`](../script/) is where deployment-time environment wiring belongs.
+
+## Change Checklist
+
+- If you edit base sucker accounting, verify claim flow across at least one chain-specific implementation.
+- If you edit token mapping logic, re-check the registry and deployer assumptions that feed it.
+- If you edit deprecation or emergency paths, verify the intended operator workflow still works end to end.
+- If you touch bridge-specific code, confirm whether the real bug is transport-side or shared accounting-side.
+
+## Common Failure Modes
+
+- Cross-chain issue is blamed on transport when the root or token mapping was wrong before message delivery.
+- Registry configuration drifts from what a deployer or external operator expects.
+- Emergency hatches or deprecation paths are stale because nobody exercises them until stress conditions arrive.
+
+## Useful Proof Points
+
+- [`test/audit/`](../test/audit/) for security-sensitive assumptions.
+- [`script/helpers/`](../script/helpers/) when the problem is deployment wiring rather than runtime logic.

package/references/runtime.md

@@ -0,0 +1,28 @@
+# Suckers Runtime
+
+## Core Roles
+
+- [`src/JBSucker.sol`](../src/JBSucker.sol) owns the shared prepare, relay, claim, token-mapping, and lifecycle logic.
+- [`src/JBSuckerRegistry.sol`](../src/JBSuckerRegistry.sol) owns project-to-sucker inventory, deployer allowlists, and shared remote-fee settings.
+- Chain-specific sucker contracts under [`src/`](../src/) own the transport-specific message delivery and verification path.
+- Matching deployers under [`src/deployers/`](../src/deployers/) own clone and transport configuration.
+
+## Runtime Path
+
+1. Local state is prepared into a claimable Merkle leaf.
+2. A root is relayed to the peer chain through the bridge-specific transport.
+3. The remote side records the root in its inbox state.
+4. Claimants prove inclusion and recreate their position on the destination chain.
+
+## High-Risk Areas
+
+- Token mapping: mapping mistakes break economic equivalence, not just UX.
+- Root ordering and replay protection: message sequencing is part of correctness.
+- Emergency and deprecation paths: these are operational safety surfaces that must remain reliable.
+- Shared accounting vs transport logic: many incidents stem from confusing these layers.
+
+## Tests To Trust First
+
+- [`test/fork/`](../test/fork/) for real transport assumptions.
+- [`test/regression/`](../test/regression/) for pinned cross-chain edge cases.
+- [`test/`](../test/) broadly when the bug could involve base logic, registry behavior, or a specific bridge implementation.

package/script/Deploy.s.sol

@@ -5,8 +5,7 @@ import {IInbox} from "@arbitrum/nitro-contracts/src/bridge/IInbox.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
 import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
-// forge-lint: disable-next-line(unaliased-plain-import)
-import "@bananapus/core-v6/script/helpers/CoreDeploymentLib.sol";
+import {CoreDeployment, CoreDeploymentLib} from "@bananapus/core-v6/script/helpers/CoreDeploymentLib.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {Sphinx} from "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script} from "forge-std/Script.sol";
@@ -132,12 +131,13 @@ contract DeployScript is Script, Sphinx {
         _arbitrumSucker();
         _ccipSucker();
 
-        if (!registryAlreadyDeployed) {
-            // Before transferring ownership to JBDAO we approve the deployers.
-            if (PRE_APPROVED_DEPLOYERS.length != 0) {
-                REGISTRY.allowSuckerDeployers(PRE_APPROVED_DEPLOYERS);
-            }
+        // Synchronize any deployers discovered or resumed during this run into the registry as long as the
+        // current safe still controls it. This keeps partial-deployment recovery idempotent.
+        if (PRE_APPROVED_DEPLOYERS.length != 0 && Ownable(address(REGISTRY)).owner() == safeAddress()) {
+            REGISTRY.allowSuckerDeployers(PRE_APPROVED_DEPLOYERS);
+        }
 
+        if (!registryAlreadyDeployed) {
             // Check what safe this is, if this is the same one as the fee-project owner, then we do not need to
             // transfer. If its not then we transfer to the fee-project safe.
             // NOTE: If this is ran after the configuration of the fee-project, this would transfer it to the

package/src/JBCeloSucker.sol

@@ -87,9 +87,11 @@ contract JBCeloSucker is JBOptimismSucker {
             uint256 _projectId = projectId();
 
             // Unwrap WETH → native ETH.
+            // slither-disable-next-line calls-loop
             WRAPPED_NATIVE.withdraw(amount);
 
             // Get the project's primary terminal for native token.
+            // slither-disable-next-line calls-loop
             IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: _projectId, token: JBConstants.NATIVE_TOKEN});
 
             if (address(terminal) == address(0)) {
@@ -97,7 +99,7 @@ contract JBCeloSucker is JBOptimismSucker {
             }
 
             // Add native ETH to the project's balance.
-            // slither-disable-next-line arbitrary-send-eth
+            // slither-disable-next-line arbitrary-send-eth,calls-loop
             terminal.addToBalanceOf{value: amount}({
                 projectId: _projectId,
                 token: JBConstants.NATIVE_TOKEN,
@@ -140,7 +142,7 @@ contract JBCeloSucker is JBOptimismSucker {
         if (amount != 0) {
             if (token == JBConstants.NATIVE_TOKEN) {
                 // Wrap native ETH → WETH so it can be bridged as ERC-20.
-                // slither-disable-next-line arbitrary-send-eth
+                // slither-disable-next-line arbitrary-send-eth,calls-loop
                 WRAPPED_NATIVE.deposit{value: amount}();
 
                 // Approve the bridge to spend the WETH.

package/src/JBSucker.sol

@@ -712,7 +712,7 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
         // transportPayment.
         IJBTerminal terminal = DIRECTORY.primaryTerminalOf({projectId: FEE_PROJECT_ID, token: JBConstants.NATIVE_TOKEN});
         if (address(terminal) != address(0)) {
-            // slither-disable-next-line unused-return
+            // slither-disable-next-line unused-return,reentrancy-events
             try terminal.pay{value: _toRemoteFee}({
                 projectId: FEE_PROJECT_ID,
                 token: JBConstants.NATIVE_TOKEN,
@@ -726,12 +726,12 @@ abstract contract JBSucker is ERC2771Context, JBPermissioned, Initializable, ERC
             ) {}
                 catch {
                 // Fee payment failed — fee ETH stays in this contract, transportPayment unchanged.
-                // The retained ETH is recoverable: it increases `amountToAddToBalanceOf(NATIVE_TOKEN)`,
-                // so the next `claim(NATIVE_TOKEN)` call will sweep it into the project's terminal balance.
+                // There is no dedicated sweep path for this retained ETH. This is an accepted tradeoff
+                // to avoid DoS on zero-cost bridges that revert on non-zero transport payment.
             }
         }
         // If no terminal exists, fee ETH stays in this contract. transportPayment is already correct.
-        // Same recovery path applies: retained fee ETH flows to the project via `claim`.
+        // This retained ETH is an accepted stuck-funds edge case; later `claim` calls do not sweep it.
 
         // Send the merkle root to the remote chain.
         _sendRoot({transportPayment: transportPayment, token: token, remoteToken: remoteToken});

package/src/JBSuckerRegistry.sol

@@ -187,6 +187,8 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
 
     /// @notice Deploy one or more suckers for the specified project.
     /// @dev The caller must be the project's owner or have `JBPermissionIds.DEPLOY_SUCKERS` from the project's owner.
+    /// Each newly created sucker is immediately configured by calling `mapTokens`, so successful execution also
+    /// depends on this registry being authorized to perform `MAP_SUCKER_TOKEN` for the project.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param salt The salt used to deploy the contract. For the suckers to be peers, this must be the same value on
     /// each chain where suckers are deployed.
@@ -209,7 +211,9 @@ contract JBSuckerRegistry is ERC2771Context, Ownable, JBPermissioned, IJBSuckerR
         suckers = new address[](configurations.length);
 
         // Calculate the salt using the sender's address and the provided `salt`.
-        // This means that for suckers to be peers, the sender has to be the same on each chain.
+        // This is an intentional part of the same-address peer invariant: if projects deploy suckers from
+        // different sender addresses on different chains, the resulting sucker addresses will differ and the
+        // default peer symmetry assumption will not hold.
         salt = keccak256(abi.encode(_msgSender(), salt));
 
         // Iterate through the configurations and deploy the suckers.

package/src/interfaces/IJBSuckerRegistry.sol

@@ -91,6 +91,8 @@ interface IJBSuckerRegistry {
     function allowSuckerDeployers(address[] calldata deployers) external;
 
     /// @notice Deploy one or more suckers for the specified project.
+    /// @dev This call also applies each configuration's token mappings on the deployed suckers. Projects using this
+    /// path need the registry to be able to satisfy the corresponding `MAP_SUCKER_TOKEN` checks.
     /// @param projectId The ID of the project to deploy suckers for.
     /// @param salt The salt used for deterministic deployment.
     /// @param configurations The deployer configs to use.

package/src/libraries/ARBAddresses.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+pragma solidity 0.8.28;
 
 /// @notice Global constants used across Juicebox contracts.
 library ARBAddresses {

package/src/libraries/ARBChains.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
+pragma solidity 0.8.28;
 
 /// @notice Global constants used across Juicebox contracts.
 library ARBChains {