npm - @bananapus/suckers-v6 - Versions diffs - 0.0.25 → 0.0.26 - Mend

@bananapus/suckers-v6 0.0.25 → 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/ADMINISTRATION.md +58 -184
package/ARCHITECTURE.md +66 -36
package/AUDIT_INSTRUCTIONS.md +26 -41
package/README.md +23 -4
package/RISKS.md +7 -2
package/SKILLS.md +11 -3
package/USER_JOURNEYS.md +83 -26
package/foundry.toml +1 -0
package/package.json +1 -1
package/references/operations.md +7 -4
package/references/runtime.md +7 -5
package/src/JBCCIPSucker.sol +0 -1
package/src/JBSwapCCIPSucker.sol +0 -1
package/src/structs/JBClaim.sol +0 -1
package/src/structs/JBDenominatedAmount.sol +0 -1
package/src/structs/JBInboxTreeRoot.sol +0 -1
package/src/structs/JBLeaf.sol +0 -1
package/src/structs/JBMessageRoot.sol +0 -1
package/src/structs/JBOutboxTree.sol +0 -1
package/src/structs/JBRemoteToken.sol +0 -1
package/src/structs/JBSuckerDeployerConfig.sol +0 -1
package/src/structs/JBSuckersPair.sol +0 -1
package/src/structs/JBTokenMapping.sol +0 -1

package/ADMINISTRATION.md CHANGED Viewed

@@ -1,211 +1,85 @@
 # Administration
-Admin privileges and their scope in nana-suckers-v6.
 ## At A Glance
 | Item | Details |
-|------|---------|
-| Scope | Cross-chain bridge deployment, token mapping, deprecation, emergency hatch controls, and layer-specific bridge configurator setup. |
-| Operators | Registry owner, project owners and delegates, sucker deployers, token mappers, safety admins, deprecation admins, and one-time bridge configurators. |
-| Highest-risk actions | Mapping the wrong remote token, enabling an emergency hatch, setting deprecation, or misconfiguring bridge singletons and chain constants. |
-| Recovery posture | The normal recovery path is to deploy or registry-enable a new sucker/deployer and migrate traffic; several safety actions are intentionally irreversible. |
-## Routine Operations
-- Allow only the sucker deployer implementations you are prepared to support operationally on the registry side.
-- Map remote tokens carefully and early, before outbox activity makes mistakes harder to unwind.
-- Use deprecation timestamps to create a safe runway for shutdown rather than trying to disable a bridge abruptly.
-- Treat emergency hatch activation as a last-resort safety action when the normal bridge path is no longer trustworthy.
-- Verify one-time deployer configuration (`configureSingleton`, `setChainSpecificConstants`) before using a deployer in production.
+| --- | --- |
+| Scope | Registry-managed sucker deployment plus project-local bridge mapping, deprecation, and safety control |
+| Control posture | Mixed registry-owner, project-owner, and one-time deployer-configurator control |
+| Highest-risk actions | Wrong token mapping, emergency hatch activation, unsafe deprecation handling, and misconfigured bridge constants |
+| Recovery posture | Recovery usually means replacement sucker paths or deployers rather than in-place reversal |
-## One-Way Or High-Risk Actions
+## Purpose
-- `enableEmergencyHatchFor` is irreversible for the affected token mapping.
-- Once a sucker reaches `SENDING_DISABLED` or `DEPRECATED`, the lifecycle cannot be reversed.
-- Deployer singleton and chain-specific constant configuration are one-time setup operations.
-- A bad token mapping can strand users or route liquidity to the wrong remote asset.
+`nana-suckers-v6` has a layered control plane: registry ownership, project-local permissioned actions, and one-time deployer configuration for each bridge family. The most dangerous admin actions are token mapping, deprecation, emergency hatch activation, and deployer bridge-constant setup.
-## Recovery Notes
+## Control Model
-- If a bridge path is unhealthy, prefer deprecating the affected sucker and standing up a replacement rather than forcing traffic through a degraded route.
-- If a token is emergency-hatched, users recover through the documented exit flow; you cannot simply re-enable the old path afterward.
+- `JBSuckerRegistry` is globally `Ownable`.
+- Project-local authority flows through `JBPermissions`.
+- `MAP_SUCKER_TOKEN`, `DEPLOY_SUCKERS`, `SUCKER_SAFETY`, and `SET_SUCKER_DEPRECATION` are the critical project-level permissions.
+- Bridge deployers have a one-time configurator role for singleton and chain constants.
 ## Roles
-### Registry Owner
-- **How assigned:** Set at `JBSuckerRegistry` construction via the `initialOwner` parameter. Transferable via OpenZeppelin `Ownable`.
-- **Scope:** Controls which sucker deployer contracts are approved for use by the registry, and sets the global `toRemoteFee` applied to all suckers. Initially expected to be JuiceboxDAO (project ID 1).
-- **Permission ID:** None (uses `onlyOwner` modifier from OpenZeppelin `Ownable`).
-### Project Owner
-- **How assigned:** Owner of the ERC-721 project NFT in `JBProjects`. All project-scoped permissions are checked against `PROJECTS.ownerOf(projectId)` or `DIRECTORY.PROJECTS().ownerOf(projectId)`.
-- **Scope:** Controls sucker deployment, token mapping, deprecation, and emergency hatch for their project. Can delegate any of these permissions to other addresses via `JBPermissions`.
-- **Permission ID:** N/A (is the root authority that grants the permission IDs below).
-### Sucker Deployer (delegated role)
-- **How assigned:** Granted `DEPLOY_SUCKERS` permission by the project owner via `JBPermissions`.
-- **Scope:** Can deploy new suckers for a specific project through the registry.
-- **Permission ID:** `JBPermissionIds.DEPLOY_SUCKERS`
-### Token Mapper (delegated role)
-- **How assigned:** Granted `MAP_SUCKER_TOKEN` permission by the project owner via `JBPermissions`. Commonly granted to the `JBSuckerRegistry` address so it can call `mapTokens` during deployment.
-- **Scope:** Can map or disable local-to-remote token pairs on a specific sucker.
-- **Permission ID:** `JBPermissionIds.MAP_SUCKER_TOKEN`
-For existing-project deployments, this permission is part of the same operational path as `DEPLOY_SUCKERS`: the registry deploys the sucker and then immediately calls `mapTokens` on it. If the project delegates deployment without arranging mapping authority for the registry, the single deployment transaction will revert during configuration.
-### Safety Admin (delegated role)
-- **How assigned:** Granted `SUCKER_SAFETY` permission by the project owner via `JBPermissions`.
-- **Scope:** Can open the emergency hatch for specific tokens on a sucker. This is an irreversible action.
-- **Permission ID:** `JBPermissionIds.SUCKER_SAFETY`
-### Deprecation Admin (delegated role)
-- **How assigned:** Granted `SET_SUCKER_DEPRECATION` permission by the project owner via `JBPermissions`.
-- **Scope:** Can set or cancel the deprecation timestamp on a sucker.
-- **Permission ID:** `JBPermissionIds.SET_SUCKER_DEPRECATION`
-### Layer-Specific Configurator
-- **How assigned:** Set at deployer construction via the `configurator` parameter. Stored as the immutable `LAYER_SPECIFIC_CONFIGURATOR` address on each `JBSuckerDeployer`.
-- **Scope:** Can call `setChainSpecificConstants` and `configureSingleton` exactly once each on the deployer. These are one-time setup functions that configure bridge-specific addresses (messenger, bridge, router, inbox) and the singleton implementation used for cloning.
-- **Permission ID:** None (uses direct `_msgSender()` check against `LAYER_SPECIFIC_CONFIGURATOR`).
-## Privileged Functions
-### JBSuckerRegistry
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `allowSuckerDeployer(deployer)` | Registry Owner | N/A (`onlyOwner`) | Global | Adds a deployer contract to the allowlist, enabling it to be used when deploying suckers. |
-| `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 or delegate | `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, so the registry must be able to satisfy the corresponding `MAP_SUCKER_TOKEN` checks for the project. |
-| `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
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `mapToken(map)` | Project owner or delegate | `MAP_SUCKER_TOKEN` | Per-sucker | Maps a local terminal token to a remote token, enabling bridging. Setting `remoteToken` to `bytes32(0)` disables bridging and sends a final root to flush remaining outbox entries. |
-| `mapTokens(maps)` | Project owner or delegate | `MAP_SUCKER_TOKEN` | Per-sucker | Batch version: maps multiple local-to-remote token pairs. Each mapping requires the same permission. |
-| `enableEmergencyHatchFor(tokens)` | Project owner or delegate | `SUCKER_SAFETY` | Per-sucker | Opens the emergency hatch for specified tokens (irreversible). Sets `emergencyHatch = true` and `enabled = false` on each token's remote mapping. Allows users to exit through the outbox on the chain they deposited on. |
-| `setDeprecation(timestamp)` | Project owner or delegate | `SET_SUCKER_DEPRECATION` | Per-sucker | Sets the timestamp after which the sucker becomes fully deprecated. Must be at least `_maxMessagingDelay()` (14 days) in the future. Set to `0` to cancel a pending deprecation. Reverts if already in `SENDING_DISABLED` or `DEPRECATED` state. |
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Registry owner | `Ownable(initialOwner)` | Global | Controls approved deployers and global `toRemoteFee` |
+| Project owner | `JBProjects.ownerOf(projectId)` | Per project | May delegate project-local sucker permissions |
+| Project operator | `JBPermissions` grant | Per project | Typically `DEPLOY_SUCKERS`, `MAP_SUCKER_TOKEN`, `SUCKER_SAFETY`, `SET_SUCKER_DEPRECATION` |
+| Deployer configurator | Constructor `configurator` | Per deployer | One-time setup role for chain constants and singleton |
-### JBSuckerDeployer (base and all subclasses)
+## Privileged Surfaces
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `configureSingleton(singleton)` | Layer-Specific Configurator | N/A (direct address check) | Per-deployer | Sets the singleton implementation contract used to clone suckers via `LibClone`. Can only be called once. |
-| `setChainSpecificConstants(...)` | Layer-Specific Configurator | N/A (direct address check) | Per-deployer | Configures bridge-specific addresses (messenger, bridge, router, inbox, etc.) for the deployer. Can only be called once. Parameters vary by bridge type. |
+| Contract | Function | Who Can Call | Effect |
+| --- | --- | --- | --- |
+| `JBSuckerRegistry` | `allowSuckerDeployer(...)`, `removeSuckerDeployer(...)`, `setToRemoteFee(...)` | Registry owner | Controls global deployer allowlist and fee |
+| `JBSuckerRegistry` | `deploySuckersFor(...)` | Project owner or `DEPLOY_SUCKERS` delegate | Deploys sucker pairs for a project |
+| `JBSucker` | `mapToken(...)`, `mapTokens(...)` | Project owner or `MAP_SUCKER_TOKEN` delegate | Sets or disables token mappings |
+| `JBSucker` | `enableEmergencyHatchFor(...)` | Project owner or `SUCKER_SAFETY` delegate | Irreversibly opens emergency exit for tokens |
+| `JBSucker` | `setDeprecation(...)` | Project owner or `SET_SUCKER_DEPRECATION` delegate | Starts or cancels deprecation while allowed |
+| `JBSuckerDeployer` variants | `configureSingleton(...)`, `setChainSpecificConstants(...)` | Configurator | One-time deployer setup |
-## Deprecation Lifecycle
+## Immutable And One-Way
-The sucker deprecation lifecycle progresses through four states, controlled by `setDeprecation(timestamp)`:
+- Emergency hatch is irreversible for the affected token mapping.
+- Deployer singleton and chain-constant setup are one-time.
+- Deprecation becomes irreversible once the sucker reaches the disabled phase.
+- Token mapping is constrained once outbox activity exists for that token.
-```
-ENABLED --> DEPRECATION_PENDING --> SENDING_DISABLED --> DEPRECATED
-```
+## Operational Notes
-| State | Condition | Behavior |
-|-------|-----------|----------|
-| `ENABLED` | `deprecatedAfter == 0` | Fully functional. No deprecation is set. |
-| `DEPRECATION_PENDING` | `block.timestamp < deprecatedAfter - _maxMessagingDelay()` | Fully functional but a warning to users that deprecation is coming. |
-| `SENDING_DISABLED` | `block.timestamp < deprecatedAfter` (but past the messaging delay window) | `prepare()` and `toRemote()` revert. No new outbox entries or root sends. Incoming roots from the remote peer are still accepted. Users can `claim()` incoming tokens and `exitThroughEmergencyHatch()`. |
-| `DEPRECATED` | `block.timestamp >= deprecatedAfter` | Fully shut down. No new inbox roots are accepted (`fromRemote` skips the update). Users can still `claim()` against previously accepted inbox roots and `exitThroughEmergencyHatch()` against outbox entries that were never sent. |
+- Map remote tokens carefully before meaningful bridge traffic accumulates.
+- Use deprecation to create a controlled shutdown window instead of abrupt disablement.
+- Treat emergency hatch as a last resort.
+- Verify deployer singleton and chain constants before approving or using a deployer operationally.
+- Treat fee-payment and bridge-send paths as best-effort in some variants; certain failures degrade into retained funds or local fallback claims rather than clean global rollback.
-**Who controls transitions:**
-- The project owner (or holder of `SET_SUCKER_DEPRECATION` permission) sets the `deprecatedAfter` timestamp via `setDeprecation(timestamp)`.
-- The timestamp must be at least `_maxMessagingDelay()` (14 days) in the future to allow in-flight messages to arrive.
-- A pending deprecation can be cancelled by calling `setDeprecation(0)`, but only while in `ENABLED` or `DEPRECATION_PENDING` state.
-- Once `SENDING_DISABLED` or `DEPRECATED`, the deprecation cannot be reversed.
+## Machine Notes
-**Removing from registry:** Once a sucker reaches `DEPRECATED`, anyone can call `JBSuckerRegistry.removeDeprecatedSucker(projectId, sucker)` to remove it from the project's sucker list.
+- Do not assume registry ownership implies control over project-local mapping or emergency actions.
+- Treat `src/JBSucker.sol`, `src/JBSuckerRegistry.sol`, and `src/deployers/` as the minimum admin source set.
+- If live leaves, token mappings, or deprecation phase disagree with the planned action, stop and re-evaluate the recovery path.
+- If a sucker variant uses try/catch around fee payment or inbound swaps, inspect the variant-specific recovery behavior before assuming failed bridge-side actions fully reverted.
-## Emergency Hatch
+## Recovery
-The emergency hatch is a per-token escape mechanism for when a bridge becomes non-functional for specific tokens.
-**Activation:** The project owner (or holder of `SUCKER_SAFETY` permission) calls `enableEmergencyHatchFor(tokens)` on the sucker. This is irreversible -- once opened for a token, that token can never be bridged by this sucker again.
-**Effect:** Sets `emergencyHatch = true` and `enabled = false` on each specified token's `JBRemoteToken` mapping. This:
-- Prevents new `prepare()` calls for the token (the token is no longer mapped/enabled).
-- Prevents `toRemote()` calls for the token (reverts with `JBSucker_TokenHasInvalidEmergencyHatchState`).
-- 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 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.
-## Immutable Configuration
-The following values are set at deploy time and cannot be changed:
-| Property | Contract | Set By | Description |
-|----------|----------|--------|-------------|
-| `DIRECTORY` | `JBSucker`, `JBSuckerRegistry`, all deployers | Constructor | The Juicebox directory contract. |
-| `FEE_PROJECT_ID` | `JBSucker` | Constructor | The project that receives `toRemoteFee` payments via `terminal.pay()` on each `toRemote()` call. Typically project ID 1 (the protocol project). Best-effort: fee is silently skipped if the fee project has no native token terminal or if `terminal.pay()` reverts. |
-| `REGISTRY` | `JBSucker` | Constructor | The `JBSuckerRegistry` that this sucker reads the `toRemoteFee` from. |
-| `MAX_TO_REMOTE_FEE` | `JBSuckerRegistry` | Constant | Hard cap on what `toRemoteFee` can be set to (0.001 ether). Prevents the registry owner from setting an excessively high fee. |
-| `TOKENS` | `JBSucker`, all deployers | Constructor | The Juicebox token management contract. |
-| `PROJECTS` | `JBSuckerRegistry` | Derived from `DIRECTORY.PROJECTS()` | The ERC-721 project ownership contract. |
-| `OPBRIDGE` | `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker` | Constructor (from deployer callback) | The OP Standard Bridge address. |
-| `OPMESSENGER` | `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker` | Constructor (from deployer callback) | The OP Cross-Domain Messenger address. |
-| `ARBINBOX` | `JBArbitrumSucker` | Constructor (from deployer callback) | The Arbitrum Inbox address. |
-| `GATEWAYROUTER` | `JBArbitrumSucker` | Constructor (from deployer callback) | The Arbitrum Gateway Router address. |
-| `LAYER` | `JBArbitrumSucker` | Constructor (from deployer callback) | Whether this is an L1 or L2 sucker. |
-| `CCIP_ROUTER` | `JBCCIPSucker` | Constructor (from deployer callback) | The Chainlink CCIP Router address. |
-| `REMOTE_CHAIN_ID` | `JBCCIPSucker` | Constructor (from deployer callback) | The remote chain's chain ID. |
-| `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 (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. |
-| Singleton implementation | All deployers | `configureSingleton()` (one-time) | The singleton contract used as the clone template. |
+- The normal recovery path is a new sucker path or a new deployer, not trying to re-enable an unsafe one.
+- Emergency-hatched tokens recover through the defined local exit flow.
+- Bad bridge-constant configuration generally means replacement deployers or replacement sucker instances.
+- Some failure modes intentionally preserve liveness over strict rollback, so recovery may mean reconciling retained funds or retryable local claims rather than undoing the original send.
 ## Admin Boundaries
-What admins **cannot** do:
-- **Cannot remap tokens after outbox activity.** 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 (set to `bytes32(0)`) or re-enabled to the same remote address. This prevents double-spending across two different remote tokens.
-- **Cannot reverse an emergency hatch.** Once `enableEmergencyHatchFor` is called for a token, `emergencyHatch` is permanently `true`. The token can never be re-enabled for bridging on this sucker. A new sucker must be deployed if bridging needs to resume.
-- **Cannot reverse deprecation past `SENDING_DISABLED`.** Once the sucker enters `SENDING_DISABLED` or `DEPRECATED` state, `setDeprecation()` reverts. The deprecation cannot be cancelled.
-- **Cannot bypass bridge security.** Cross-chain message authentication is enforced by each bridge implementation's `_isRemotePeer()` check. The project owner has no way to override this -- only messages from the legitimate remote peer (verified by the OP Messenger, Arbitrum Bridge/Outbox, or CCIP Router) are accepted by `fromRemote()`.
-- **Cannot reconfigure deployers.** `setChainSpecificConstants()` and `configureSingleton()` can each only be called once per deployer. Bridge addresses and the singleton implementation are permanent after initial configuration.
-- **Cannot steal user funds via emergency hatch.** Emergency exit only returns tokens to the original beneficiary specified in the outbox merkle tree, and only for leaves that were never sent over the bridge (index >= `numberOfClaimsSent`). Leaves already bridged cannot be double-claimed.
-- **Cannot claim on behalf of others.** While `claim()` and `exitThroughEmergencyHatch()` are permissionless (anyone can call them), the project tokens are always minted to the beneficiary encoded in the merkle tree leaf, not to the caller.
-- **Cannot change the peer address.** The peer is determined by deterministic deployment (CREATE2 with sender-specific salt). There is no admin function to change which remote address is trusted.
-- **Cannot change the project ID.** The `projectId` is set once during `initialize()` and is immutable thereafter (enforced by OpenZeppelin `Initializable`).
-- **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:**
+- Registry owners cannot override project-local mapping or safety decisions directly.
+- Project operators cannot reverse an emergency hatch.
+- Project operators cannot force already sent leaves through the emergency hatch path.
+- Nobody can mutate constructor immutables on live suckers or deployers.
-- **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.
+## Source Map
-**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.
+- `src/JBSucker.sol`
+- `src/JBSuckerRegistry.sol`
+- `src/deployers/`
+- `src/utils/MerkleLib.sol`
+- `test/`

package/ARCHITECTURE.md CHANGED Viewed

@@ -2,59 +2,89 @@
 ## Purpose
-`nana-suckers-v6` moves Juicebox project token value across chains. A sucker pair lets a holder burn or cash out locally, bridge the resulting terminal token plus the latest merkle root, and then claim equivalent project-token value on the remote chain.
+`nana-suckers-v6` moves Juicebox project-token value across chains. A sucker pair lets a holder destroy or consume a local project-token position, bridge the corresponding terminal-side value plus a Merkle root, and later claim equivalent value on the remote chain.
-## Boundaries
+## System Overview
-- `JBSucker` owns the chain-agnostic lifecycle.
-- Chain-specific subclasses own transport details for OP Stack, Arbitrum, CCIP, and Celo variants.
-- The registry and deployers own pair creation and global policy.
-- Core protocol accounting still happens through project terminals on each chain.
+`JBSucker` defines the chain-agnostic prepare, relay, and claim lifecycle. Chain-specific implementations such as `JBOptimismSucker`, `JBArbitrumSucker`, `JBCCIPSucker`, `JBSwapCCIPSucker`, `JBBaseSucker`, and `JBCeloSucker` handle transport-specific details. `JBSuckerRegistry` governs deployment inventory and shared policy, while deployers create deterministic clones for each supported transport family.
-## Main Components
+## Core Invariants
-| Component | Responsibility |
-| --- | --- |
-| `JBSucker` | Prepare, root management, claim verification, token mapping, and deprecation controls |
-| chain-specific suckers | Bridge transport and token-wrapping details for each supported network family |
-| `JBSuckerRegistry` | Tracks deployed suckers, allowlists deployers, and stores global bridge-fee policy |
-| deployers | Clone and initialize deterministic sucker instances |
-| `MerkleLib` and helper libraries | Incremental tree logic plus chain-specific constants |
+- Inbox and outbox trees must remain append-only and proof-compatible across chains.
+- Token mapping is part of economic correctness; a wrong mapping is a value-loss bug.
+- Deprecation or emergency controls must not break already-bridged claims.
+- Roots may arrive out of order. Newer nonces replace older inbox roots, so claims must stay provable against the latest append-only tree.
+- Root reception and token mapping are intentionally decoupled. Accepting a root for an unmapped token is valid if later mapping is what makes the claim redeemable.
+- Transport-specific implementations may differ operationally, but they must preserve the same logical prepare-to-claim lifecycle.
-## Runtime Model
+## Modules
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JBSucker` | Prepare, root management, claim verification, token mapping, deprecation | Chain-agnostic base |
+| chain-specific suckers | Transport details for OP Stack, Arbitrum, CCIP, Base, and Celo | Bridge-specific subclasses |
+| `JBSuckerRegistry` | Deployer allowlist, inventory, and global bridge-fee policy | Shared policy surface |
+| deployers | Deterministic clone deployment and initialization | One per transport family |
+| `MerkleLib` and helper libraries | Incremental tree logic and chain constants | Proof-critical |
+## Trust Boundaries
+- Project-token semantics and local terminal accounting remain rooted in `nana-core-v6`.
+- Transport assumptions come from native bridge infrastructure for each chain family.
+- Permission IDs come from `nana-permission-ids-v6`.
+## Critical Flows
+### Prepare, Relay, Claim
 ```text
 holder prepares a bridge
   -> sucker cashes out or consumes the local project-token position
-  -> sucker inserts a merkle leaf into the outbox tree
-  -> someone bridges funds and the latest root to the remote sucker
+  -> sucker inserts a Merkle leaf into the outbox tree
+  -> someone relays funds and the latest root to the remote sucker
+  -> remote sucker may accept a later nonce before an earlier one, updating shared cross-chain snapshots to the freshest project-wide message
   -> claimant proves inclusion against the remote inbox tree
-  -> remote sucker releases or remints the destination-side value
+  -> remote sucker releases or remints destination-side value
 ```
-## Critical Invariants
-- Inbox and outbox tree updates must remain append-only and proof-compatible across chains.
-- Token mapping is part of bridge correctness; a wrong remote token mapping is a value-loss bug.
-- Deprecation and emergency controls must not compromise already-bridged claims.
-- The chain-specific transport layers may differ, but they must preserve the same logical prepare-to-claim lifecycle.
+## Accounting Model
-## Where Complexity Lives
+The repo does not replace local treasury accounting. It owns bridge-specific claim accounting: outbox leaves, inbox roots, token mappings, replay protection, and the transition from local destruction to remote claimability.
-- The abstract lifecycle is simple, but every transport backend has its own failure modes and native-token quirks.
-- Tree state, token mapping, and claim replay protection all carry cross-chain blast radius.
-- Registry policy matters because deployment mistakes are hard to repair after pairs exist on multiple chains.
+`JBSwapCCIPSucker` adds another accounting layer on top of the base lifecycle: nonce-indexed conversion rates. A claim can be temporarily blocked while a failed swap is pending retry, and successful claims are scaled against the conversion rate recorded for that batch's nonce.
-## Dependencies
+## Security Model
-- `nana-core-v6` terminals and project-token semantics
-- Native bridge infrastructure for OP Stack, Arbitrum, CCIP, and supported variants
-- `nana-permission-ids-v6` for deploy, map, safety, and deprecation permissions
+- Tree state, token mapping, and replay protection have cross-chain blast radius.
+- Each transport backend has distinct failure modes and native-token quirks.
+- Out-of-order message delivery is part of the trust model, not an exception path. Proof generation and monitoring must tolerate stale-root rejection and regenerated proofs against the newest root.
+- Emergency hatch and deprecation flows are designed to preserve already-bridged exits. Post-deprecation root acceptance is intentional so in-flight messages do not strand users.
+- Registry policy matters because bad deployments are hard to repair once pairs exist on multiple chains.
 ## Safe Change Guide
 - Review every cross-chain change from both sides of the pair.
-- Do not change merkle leaf encoding casually; proofs and remote compatibility depend on it.
-- Keep registry policy, deployer configuration, and singleton logic aligned.
-- Test chain-specific native-token wrapping paths separately from the abstract lifecycle.
-- Assume bridge-edge behavior is the primary review target, not the happy path.
+- Do not change Merkle leaf encoding casually.
+- Keep registry policy, deployer configuration, and singleton initialization aligned.
+- If you change root or snapshot nonce handling, re-check out-of-order delivery behavior and whether older claims remain provable against the newest root.
+- If you change CCIP swap handling, re-check pending-swap claim blocking and per-batch conversion-rate lookups together.
+- Test chain-specific wrapping and native-token handling separately from the abstract lifecycle.
+## Canonical Checks
+- peer snapshot and remote-state synchronization:
+  `test/audit/codex-PeerSnapshotDesync.t.sol`
+- deprecation and stranded-destination handling:
+  `test/audit/DeprecatedSuckerDestination.t.sol`
+- peer-chain state accounting:
+  `test/unit/peer_chain_state.t.sol`
+## Source Map
+- `src/JBSucker.sol`
+- `src/JBSuckerRegistry.sol`
+- `src/deployers/`
+- `src/utils/MerkleLib.sol`
+- `test/audit/codex-PeerSnapshotDesync.t.sol`
+- `test/audit/DeprecatedSuckerDestination.t.sol`
+- `test/unit/peer_chain_state.t.sol`

package/AUDIT_INSTRUCTIONS.md CHANGED Viewed

@@ -2,7 +2,7 @@
 This repo bridges Juicebox project tokens and associated terminal assets across chains. Audit it as a conservation and replay-prevention system.
-## Objective
+## Audit Objective
 Find issues that:
 - allow double claim, replay, or claim on the wrong destination
@@ -32,7 +32,7 @@ Read in this order:
 That order gets you from the shared conservation model to the transport-specific deviations.
-## System Model
+## Security Model
 The bridge flow is:
 - burn or prepare project-token value on source chain
@@ -52,6 +52,21 @@ One non-obvious property to audit explicitly:
 - the system is intentionally designed to survive some transport mismatch without deadlocking
 - those recovery choices are exactly where conservation bugs tend to hide
+## Roles And Privileges
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Source-side caller | Prepare and bridge value to a remote chain | Must not create more claimable value than was prepared |
+| Remote peer and messenger | Install new roots and deliver assets | Must be authenticated per transport |
+| Emergency authority | Deprecate paths or enable recovery exits | Must not be able to steal in-flight funds |
+## Integration Assumptions
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| Bridge transport | Delivers only authenticated peer messages | Anyone can spoof remote state |
+| Token mapping and registry state | Remote asset identity stays stable | Users claim the wrong asset or wrong meaning |
 ## Critical Invariants
 1. Cross-chain conservation
@@ -72,22 +87,7 @@ Remote token mappings must be immutable or mutable only exactly where the design
 6. Nonce progression is monotonic in the way each transport expects
 Later roots must not silently invalidate earlier user claims unless the protocol explicitly intends that recovery path.
-## Threat Model
-Prioritize:
-- out-of-order nonce arrival
-- cross-sucker replay
-- trusted-forwarder or messenger spoofing
-- emergency-exit races
-- fee fallback and bridge-payment edge cases
-- deterministic deployer assumptions for peer pairing
-The strongest attacker models here are:
-- a caller trying to claim from the wrong root with a structurally valid proof
-- a privileged actor abusing token mapping or emergency controls after users already prepared transfers
-- a transport delivering messages out of order and exposing assumptions hidden in the happy path
-## Hotspots
+## Attack Surfaces
 - `prepare`, `toRemote`, `fromRemote`, and `claim`
 - bitmap execution tracking
@@ -96,33 +96,18 @@ The strongest attacker models here are:
 - chain-specific messenger authentication
 - deployer address derivation and clone setup
-## Sequences Worth Replaying
-1. Prepare multiple leaves -> send multiple roots -> receive them out of order -> attempt claims for each.
-2. Prepare -> deprecate or enable emergency hatch -> claim and exit attempts racing each other.
-3. Map token -> prepare transfer -> attempt remap or peer mismatch after value is already in flight.
-4. Same logical transfer across different sucker implementations to check for replay or identity confusion.
+Replay these sequences:
+1. prepare multiple leaves, send multiple roots, receive them out of order, and attempt each claim
+2. prepare, deprecate or enable emergency hatch, then race claim and exit paths
+3. map a token, prepare a transfer, then attempt remap or peer mismatch after value is in flight
+4. replay the same logical transfer across different sucker implementations
-## Finding Bar
+## Accepted Risks Or Behaviors
-The strongest findings here usually show one of these:
-- a user can claim against value that was never actually prepared
-- a valid prepare becomes permanently unclaimable without the recovery path the protocol expects
-- transport-specific authentication is weaker than the shared model assumes
-- a privileged mapping or safety control can rewrite the meaning of already in-flight value
+- Out-of-order arrival is part of the intended model, not an edge case.
-## Build And Verification
+## Verification
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-The current tests already target:
-- deep attack and regression scenarios
-- trusted-forwarder spoofing
-- fee fallback behavior
-- deterministic deployment
-- chain-specific fork flows
-High-value findings here show a break in conservation, replay resistance, or trusted-peer boundaries.

package/README.md CHANGED Viewed

@@ -3,7 +3,12 @@
 `@bananapus/suckers-v6` provides cross-chain bridging for Juicebox project tokens and the terminal assets that back them. A pair of suckers lets users burn on one chain, move value across a bridge, and mint the same project token representation on another chain.
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)
+Skills: [SKILLS.md](./SKILLS.md)
+Risks: [RISKS.md](./RISKS.md)
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 The codebase includes multiple bridge variants, but the canonical deployment and discovery tooling in this repo is narrower than the full runtime surface. Treat the deployment scripts and helper libraries as the source of truth for what is operationally supported today.
@@ -50,7 +55,7 @@ The shortest useful reading order is:
 | Contract | Description |
 |----------|-------------|
 | [`JBSucker`](src/JBSucker.sol) | Abstract base. Manages outbox/inbox merkle trees, `prepare`/`toRemote`/`claim` lifecycle, token mapping, deprecation, and emergency hatch. Deployed as clones via `Initializable`. Uses `ERC2771Context` for meta-transactions. Has immutable `FEE_PROJECT_ID` (typically project ID 1) and immutable `REGISTRY` reference. Reads the `toRemoteFee` from the registry via `REGISTRY.toRemoteFee()` on each `toRemote()` call. |
-| [`JBCCIPSucker`](src/JBCCIPSucker.sol) | Extends `JBSucker`. Bridges via Chainlink CCIP (`ccipSend`/`ccipReceive`). Supports any CCIP-connected chain pair. Wraps native ETH to WETH before bridging (CCIP only transports ERC-20s) and unwraps on the receiving end. Can map `NATIVE_TOKEN` to ERC-20 addresses on the remote chain (unlike OP/Arbitrum suckers). |
+| [`JBCCIPSucker`](src/JBCCIPSucker.sol) | Extends `JBSucker`. Bridges via Chainlink CCIP (`ccipSend`/`ccipReceive`) for chain pairs whose router, selector, and token mapping are configured. Wraps native ETH to WETH before bridging (CCIP only transports ERC-20s) and unwraps on the receiving end. Can map `NATIVE_TOKEN` to ERC-20 addresses on the remote chain (unlike OP/Arbitrum suckers). |
 | [`JBOptimismSucker`](src/JBOptimismSucker.sol) | Extends `JBSucker`. Bridges via OP Standard Bridge + OP Messenger. No `msg.value` required for transport. |
 | [`JBBaseSucker`](src/JBBaseSucker.sol) | Thin wrapper around `JBOptimismSucker` with Base chain IDs (Ethereum 1 <-> Base 8453, Sepolia 11155111 <-> Base Sepolia 84532). |
 | [`JBCeloSucker`](src/JBCeloSucker.sol) | Extends `JBOptimismSucker` for Celo (OP Stack, custom gas token CELO). Wraps native ETH → WETH before bridging as ERC-20. Unwraps received WETH → native ETH via `_addToBalance` override. Removes `NATIVE_TOKEN → NATIVE_TOKEN` restriction. Sends messenger messages with `nativeValue = 0` (Celo's native token is CELO, not ETH). |
@@ -63,7 +68,7 @@ The shortest useful reading order is:
 | [`JBCeloSuckerDeployer`](src/deployers/JBCeloSuckerDeployer.sol) | Deployer for `JBCeloSucker`. Extends `JBOptimismSuckerDeployer` with `wrappedNative` (`IWrappedNativeToken`) storage for the local chain's WETH address. |
 | [`JBArbitrumSuckerDeployer`](src/deployers/JBArbitrumSuckerDeployer.sol) | Deployer for `JBArbitrumSucker`. Stores Arbitrum Inbox, Gateway Router, and layer (`JBLayer.L1` or `JBLayer.L2`). |
 | [`MerkleLib`](src/utils/MerkleLib.sol) | Incremental merkle tree (depth 32, max ~4 billion leaves, modeled on eth2 deposit contract). Used for outbox/inbox trees. `insert` and `root` operate directly on `Tree storage` (not memory copies) to avoid redundant SLOAD/SSTORE round-trips. Gas-optimized with inline assembly for `root()` and `branchRoot()`. |
-| [`CCIPHelper`](src/libraries/CCIPHelper.sol) | CCIP router addresses, chain selectors, and WETH addresses per chain. Covers Ethereum, Optimism, Arbitrum, Base, Polygon, Avalanche, and BNB Chain (mainnet and testnets). |
+| [`CCIPHelper`](src/libraries/CCIPHelper.sol) | CCIP router addresses, chain selectors, and WETH addresses for the chain set currently encoded in this repo. |
 | [`ARBAddresses`](src/libraries/ARBAddresses.sol) | Arbitrum bridge contract addresses (Inbox, Gateway Router) for mainnet and Sepolia. |
 | [`ARBChains`](src/libraries/ARBChains.sol) | Arbitrum chain ID constants. |
@@ -90,6 +95,14 @@ The shortest useful reading order is:
 When reviewing a bridge incident, check local state transition correctness before blaming the transport layer.
+## High-Signal Tests
+1. `test/unit/registry.t.sol`
+2. `test/unit/multi_chain_evolution.t.sol`
+3. `test/ForkClaimMainnet.t.sol`
+4. `test/audit/codex-PeerSnapshotDesync.t.sol`
+5. `test/audit/codex-ToRemoteFeeIrrecoverable.t.sol`
 ## Install
 ```bash
@@ -112,7 +125,7 @@ Useful scripts:
 ## Deployment Notes
-This package supports multiple bridge families and is intentionally split into bridge-specific deployers. It is commonly used directly and through the Omnichain and Revnet deployer packages.
+This package supports multiple bridge families and is intentionally split into bridge-specific deployers. Operational support is narrower than "all theoretically bridgeable chains" and should be taken from the configured deployers, helper libraries, and deployment scripts in this repo.
 ## Repository Layout
@@ -142,3 +155,9 @@ script/
 - a bridge that stays live operationally still may not be economically safe for every asset or chain pair
 When debugging a bad cross-chain outcome, first decide whether the failure is in claim construction, message transport, inbox/outbox root progression, or remote settlement. Those are different bug classes.
+## For AI Agents
+- Do not summarize this repo as a generic token bridge; it bridges Juicebox project positions plus transported value.
+- Always separate shared sucker logic from bridge-specific transport behavior in your explanation.
+- Use the chain-specific implementation and the matching deployer together when answering operational questions.

package/RISKS.md CHANGED Viewed

@@ -62,6 +62,7 @@ This file focuses on the bridge-like risks in the sucker system: merkle-root pro
 - **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.
 - **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.
+- **Registry aggregate views fail open.** `JBSuckerRegistry.remoteBalanceOf`, `remoteSurplusOf`, and `remoteTotalSupplyOf` sum values across active suckers but silently skip any sucker that reverts. This preserves liveness for dashboards and cross-chain estimates, but it means the returned aggregate can understate remote state whenever one peer is broken, censored, deprecated incorrectly, or simply expensive to query.
 ## 6. Deprecation Lifecycle
@@ -127,10 +128,14 @@ The registry owner can adjust `toRemoteFee` via `JBSuckerRegistry.setToRemoteFee
 The fee is paid to `FEE_PROJECT_ID` (the protocol project), not to the sucker's own `projectId()`. This centralizes fee collection, but it is still only best-effort: if the fee project's native terminal is missing or its `pay` call reverts, the fee ETH stays in the sucker contract and is later recoverable through the normal claim path. The sucker's project does not directly benefit from the anti-spam fee.
-### 10.5 Hookless V4 spot pricing is sandwich-vulnerable by design
+### 10.5 Registry aggregate views prioritize liveness over completeness
+`JBSuckerRegistry.remoteBalanceOf`, `remoteSurplusOf`, and `remoteTotalSupplyOf` intentionally use `try/catch` around each sucker and silently ignore peers that revert. This is accepted because a single bad peer should not brick every cross-chain dashboard or estimator. The trade-off is that these read surfaces are best-effort only: consumers must treat them as lower bounds, not exact reconciled totals, unless they independently verify that every active sucker responded successfully.
+### 10.6 Hookless V4 spot pricing is sandwich-vulnerable by design
 When the only available Uniswap pool for a cross-denomination swap is a hookless V4 pool (no V3 pool exists), `_getV4Quote` falls back to the instantaneous spot tick from `POOL_MANAGER.getSlot0()` instead of a TWAP oracle. This tick is manipulable via sandwich attacks, allowing an attacker to skew the `minAmountOut` and extract value from the swap. The sigmoid slippage model limits the damage but operates on a corrupted baseline. This is an accepted tradeoff: reverting when no TWAP is available would cause the CCIP message to fail, leaving bridged tokens stuck in the CCIP router until manual retry. Getting some value (even at a worse rate) is preferred over a stuck bridge message, especially since this path only triggers when no V3 pool with built-in TWAP exists at all. The hooked V4 path also falls back to spot if the hook's `observe()` reverts, with the same tradeoff.
-### 10.6 `mapTokens` refunds ETH on enable-only batches
+### 10.7 `mapTokens` refunds ETH on enable-only batches
 `mapTokens()` only uses `msg.value` when one or more mappings are being disabled and need transport payment for the final root flush. If every mapping in the batch is enable-only (`numberToDisable == 0`), the full `msg.value` is refunded to `_msgSender()`. If the refund transfer fails (e.g., the caller is a non-payable contract), the call reverts with `JBSucker_RefundFailed`. When disables are present, any dust remainder from integer division (`msg.value % numberToDisable`) is also refunded on a best-effort basis.

package/SKILLS.md CHANGED Viewed

@@ -3,7 +3,7 @@
 ## Use This File For
 - Use this file when the task involves cross-chain project-token bridging, token mapping, Merkle claim flow, bridge-specific transport logic, or sucker registry behavior.
-- Start here, then open the base sucker, registry, chain-specific implementation, or deployer depending on which leg of the bridge path is under review.
+- Start here, then decide whether the issue is in shared accounting, message authentication, token mapping, or operator/deprecation controls. Those concerns live in different layers.
 ## Read This Next
@@ -11,9 +11,11 @@
 |---|---|
 | Repo overview and bridge model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Shared bridge logic | [`src/JBSucker.sol`](./src/JBSucker.sol), [`src/JBSuckerRegistry.sol`](./src/JBSuckerRegistry.sol) |
-| Chain-specific transport behavior | [`src/`](./src/), [`src/deployers/`](./src/deployers/) |
+| Chain-specific transport behavior | [`src/JBArbitrumSucker.sol`](./src/JBArbitrumSucker.sol), [`src/JBOptimismSucker.sol`](./src/JBOptimismSucker.sol), [`src/JBCCIPSucker.sol`](./src/JBCCIPSucker.sol), [`src/JBCeloSucker.sol`](./src/JBCeloSucker.sol) |
+| Deployer and transport setup | [`src/deployers/`](./src/deployers/) |
 | Merkle and helper logic | [`src/utils/`](./src/utils/), [`src/libraries/`](./src/libraries/) |
-| Attack, interoperability, or regression coverage | [`test/`](./test/), [`test/regression/`](./test/regression/), [`test/fork/`](./test/fork/) |
+| Interop and chain-specific fork coverage | [`test/ForkMainnet.t.sol`](./test/ForkMainnet.t.sol), [`test/ForkArbitrum.t.sol`](./test/ForkArbitrum.t.sol), [`test/ForkCelo.t.sol`](./test/ForkCelo.t.sol), [`test/ForkOPStack.t.sol`](./test/ForkOPStack.t.sol), [`test/InteropCompat.t.sol`](./test/InteropCompat.t.sol) |
+| Swap, claim, attack, and regression coverage | [`test/ForkSwap.t.sol`](./test/ForkSwap.t.sol), [`test/ForkClaimMainnet.t.sol`](./test/ForkClaimMainnet.t.sol), [`test/SuckerAttacks.t.sol`](./test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](./test/SuckerDeepAttacks.t.sol), [`test/SuckerRegressions.t.sol`](./test/SuckerRegressions.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
 ## Repo Map
@@ -37,6 +39,12 @@ Cross-chain bridge layer for Juicebox project tokens and the terminal assets tha
 ## Working Rules
 - Start in [`src/JBSucker.sol`](./src/JBSucker.sol) for shared accounting and claim flow, then move to the chain-specific implementation only after you know the base path is correct.
+- `JBSucker` explicitly does not support fee-on-transfer or rebasing tokens. If a bug report involves those assets, treat it as an unsupported-path question first.
+- Root progression, peer supply, and peer surplus snapshots are part of economic correctness, not just bridge bookkeeping.
+- Token mapping is intentionally one-way after real activity starts. Disabling a mapping is allowed; remapping to a different remote asset is not.
+- Peer symmetry depends on deployer and salt assumptions as well as runtime code. A bridge bug can start in deployment shape before it appears in message flow.
 - Treat token mapping, root progression, and emergency/deprecation controls as first-class runtime behavior, not admin-only side tooling.
 - When debugging a bridge incident, separate accounting correctness from transport correctness before patching.
+- Message authentication is delegated to bridge-specific subclasses. When reviewing a new transport, `_isRemotePeer` is one of the first things to inspect.
+- Emergency exit and deprecation behavior are intentionally conservative. Some failure modes lock funds rather than risking double-spend.
 - If a task touches project deployment shape, check whether the real source is `nana-omnichain-deployers-v6` or `revnet-core-v6` instead of the sucker implementation itself.

package/USER_JOURNEYS.md CHANGED Viewed

@@ -1,83 +1,140 @@
 # User Journeys
-## Who This Repo Serves
+## Repo Purpose
+This repo bridges Juicebox project-token positions and their treasury-backed claim semantics across chains.
+It is not a generic proxy terminal and not a generic ERC-20 bridge. The important unit is the project position and the
+explicit bridge lifecycle around `prepare`, `toRemote`, and claim.
+## Primary Actors
 - 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
+## Key Surfaces
+- `JBSucker`: shared base lifecycle for preparing, relaying, and claiming bridge leaves
+- `JBSuckerRegistry`: registry for sucker deployments, deployer allowlists, and shared fee settings
+- `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker`, `JBArbitrumSucker`, `JBCCIPSucker`, `JBSwapCCIPSucker`: bridge-family implementations
 ## Journey 1: Launch A Cross-Chain Sucker Pair For A Project
-**Starting state:** the project exists on multiple chains or plans to, and the team has chosen the bridge family it trusts.
+**Actor:** operator or deployer.
+**Intent:** deploy and register the paired bridge surfaces a project will rely on across chains.
-**Success:** paired suckers are deployed, registered, and ready to transport claims between the chains they serve.
+**Preconditions**
+- the project exists on multiple chains or plans to
+- the team has chosen the bridge family it trusts
-**Flow**
+**Main 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.
+**Failure Modes**
+- paired deployments disagree about counterparties or token mappings
+- teams deploy the right contracts but never register the resulting pair coherently
+**Postconditions**
+- paired suckers are deployed, registered, and ready to transport claims between the chains they serve
 ## Journey 2: Bridge A Position From One Chain To Another
-**Starting state:** a user holds project-token exposure on the source chain and wants the corresponding position on the destination chain.
+**Actor:** user bridging a position.
-**Success:** the source position becomes a claim, the claim is relayed, and the destination position is minted after proof verification.
+**Intent:** move project-token exposure from the source chain to the destination chain.
-**Flow**
+**Preconditions**
+- a user holds project-token exposure on the source chain
+- the project has a supported destination-side sucker path
+**Main 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.
-**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.
+**Failure Modes**
+- token mappings are wrong for the project or chain pair
+- transport-layer fees are missing and roots never arrive
+- operators assume the bridge is generic ERC-20 transport rather than project-position transport
+**Postconditions**
+- the source position becomes a claim, the claim is relayed, and the destination position is minted after proof verification
 ## Journey 3: Map Treasury Assets And Project Tokens Correctly Across Chains
-**Starting state:** the project supports multiple assets or wrappers across chains and wants users to bridge without silent economic mismatch.
+**Actor:** operator mapping assets and wrappers.
-**Success:** the remote claim recreates the intended exposure instead of a superficially similar but economically different asset.
+**Intent:** preserve economic meaning across chains instead of bridging into the wrong wrapped exposure.
-**Flow**
+**Preconditions**
+- the project supports multiple assets or wrappers across chains
+- users should be able to bridge without silent economic mismatch
+**Main 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.
+**Failure Modes**
+- local and remote wrappers look similar but settle into different economics
+- chain-specific native-asset assumptions are copied across environments where they do not hold
+**Postconditions**
+- the remote claim recreates the intended exposure instead of a superficially similar but economically different asset
 ## Journey 4: Operate The Bridge Safely Over Time
-**Starting state:** the bridge is live and now needs operational stewardship rather than just deployment.
+**Actor:** bridge operator.
+**Intent:** keep registry config, fees, deprecation, and bridge-family assumptions coherent after launch.
-**Success:** fee policy, deprecation, trusted counterparties, and emergency paths remain coherent as conditions change.
+**Preconditions**
+- the bridge is live and now needs operational stewardship rather than just deployment
-**Flow**
+**Main 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.
+**Failure Modes**
+- fee policy drifts from actual transport costs and claims stop delivering
+- bridge-family deprecation is delayed even after counterparties or fees become unsafe
+**Postconditions**
+- fee policy, deprecation, trusted counterparties, and emergency paths remain coherent as conditions change
 ## Journey 5: Recover Value Through The Emergency Hatch When Normal Delivery Breaks
-**Starting state:** a claim cannot complete through the normal inbox or remote-delivery path.
+**Actor:** user or responder handling a broken delivery path.
-**Success:** users can recover through the explicit emergency mechanism without double-spending the same claim.
+**Intent:** recover value when the normal bridge delivery path is unavailable.
-**Flow**
+**Preconditions**
+- a claim cannot complete through the normal inbox or remote-delivery path
+**Main 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.
-## Journey 6: Create A Proxy Project And Route Payments Through It
-**Starting state:** a project exists on the home chain with an ERC-20 token deployed, and wants to let users on other chains acquire proxy tokens backed by real project tokens.
+**Failure Modes**
+- teams use the emergency path prematurely instead of as a documented recovery mode
+- claim state is not checked carefully and responders risk inconsistent double-claim assumptions
-**Success:** a proxy project is created once, and payments routed through it mint proxy tokens 1:1 with the real tokens deposited.
+**Postconditions**
+- users can recover through the explicit emergency mechanism without double-spending the same claim
-**Flow**
-1. Call `JBSuckerTerminal.createProxy(realProjectId, name, symbol, salt)` to launch a locked proxy project with a permanent 1:1 ruleset, backed by the real project's ERC-20 token.
-2. Anyone can then call `JBSuckerTerminal.pay(proxyProjectId, token, amount, beneficiary, ...)` to pay the real project and automatically receive proxy tokens.
-3. Suckers registered for the proxy project get mint permission through `JBSuckerTerminal`'s data hook, enabling cross-chain bridging of proxy token positions.
+## Trust Boundaries
-**Failure cases that matter:** calling `createProxy` on a project without an ERC-20 deployed, attempting to create a second proxy for the same project, and paying with a token that has no primary terminal on the real project.
+- this repo trusts both the shared sucker accounting logic and the selected bridge-family transport
+- token mapping and registry governance are part of the economic safety model
+- emergency and deprecation controls are operationally important, not just last-resort tooling
 ## Hand-Offs

package/foundry.toml CHANGED Viewed

@@ -14,6 +14,7 @@ depth = 100
 fail_on_revert = false
 [lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 lint_on_build = false
 [fmt]

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/suckers-v6",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md CHANGED Viewed

@@ -3,14 +3,16 @@
 ## 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.
+- Transport-specific deployers in `src/deployers/` are where chain-specific constants and bridge addresses live.
+- [`script/Deploy.s.sol`](../script/Deploy.s.sol) is where deployment-time environment wiring belongs.
 ## Change Checklist
 - 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 token mapping semantics, verify that remapping is still impossible once outbox activity has made economic equivalence depend on permanence.
 - If you edit deprecation or emergency paths, verify the intended operator workflow still works end to end.
+- If you edit snapshot or claim-boundary logic, verify `numberOfClaimsSent`, peer snapshots, and emergency exit behavior together.
 - If you touch bridge-specific code, confirm whether the real bug is transport-side or shared accounting-side.
 ## Common Failure Modes
@@ -21,5 +23,6 @@
 ## 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.
+- [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for security-sensitive assumptions.
+- [`test/InteropCompat.t.sol`](../test/InteropCompat.t.sol) when the problem is deployment wiring rather than runtime logic.
+- [`test/unit/invariants.t.sol`](../test/unit/invariants.t.sol), [`test/unit/peer_chain_state.t.sol`](../test/unit/peer_chain_state.t.sol), and [`test/audit/codex-PeerSnapshotDesync.t.sol`](../test/audit/codex-PeerSnapshotDesync.t.sol) when shared accounting or snapshot boundaries are in doubt.

package/references/runtime.md CHANGED Viewed

@@ -4,8 +4,8 @@
 - [`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.
+- Chain-specific sucker contracts such as [`src/JBArbitrumSucker.sol`](../src/JBArbitrumSucker.sol), [`src/JBOptimismSucker.sol`](../src/JBOptimismSucker.sol), [`src/JBCCIPSucker.sol`](../src/JBCCIPSucker.sol), and [`src/JBCeloSucker.sol`](../src/JBCeloSucker.sol) own transport-specific delivery and verification.
+- Matching deployers under `src/deployers/` own clone and transport configuration.
 ## Runtime Path
@@ -20,9 +20,11 @@
 - 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.
+- Peer snapshots and `numberOfClaimsSent`: these guard against double-spend at the cost of conservative locking when timing goes wrong.
 ## 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.
+- [`test/ForkMainnet.t.sol`](../test/ForkMainnet.t.sol), [`test/ForkArbitrum.t.sol`](../test/ForkArbitrum.t.sol), [`test/ForkCelo.t.sol`](../test/ForkCelo.t.sol), and [`test/ForkOPStack.t.sol`](../test/ForkOPStack.t.sol) for real transport assumptions.
+- [`test/ForkSwap.t.sol`](../test/ForkSwap.t.sol), [`test/ForkClaimMainnet.t.sol`](../test/ForkClaimMainnet.t.sol), and [`test/SuckerRegressions.t.sol`](../test/SuckerRegressions.t.sol) for pinned cross-chain edge cases.
+- [`test/unit/invariants.t.sol`](../test/unit/invariants.t.sol), [`test/unit/peer_chain_state.t.sol`](../test/unit/peer_chain_state.t.sol), and [`test/unit/registry.t.sol`](../test/unit/registry.t.sol) for shared-accounting invariants.
+- [`test/SuckerAttacks.t.sol`](../test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](../test/SuckerDeepAttacks.t.sol), [`test/audit/codex-PeerSnapshotDesync.t.sol`](../test/audit/codex-PeerSnapshotDesync.t.sol), and [`test/audit/codex-PeerDeterminism.t.sol`](../test/audit/codex-PeerDeterminism.t.sol) when the bug could involve base logic, registry behavior, or a specific bridge implementation.

package/src/JBCCIPSucker.sol CHANGED Viewed

@@ -205,7 +205,6 @@ contract JBCCIPSucker is JBSucker, IAny2EVMMessageReceiver {
         address token,
         uint256 amount,
         JBRemoteToken memory remoteToken,
-        // forge-lint: disable-next-line(mixed-case-variable)
         JBMessageRoot memory sucker_message
     )
         internal

package/src/JBSwapCCIPSucker.sol CHANGED Viewed

@@ -512,7 +512,6 @@ contract JBSwapCCIPSucker is JBCCIPSucker, IUnlockCallback, IUniswapV3SwapCallba
         address token,
         uint256 amount,
         JBRemoteToken memory remoteToken,
-        // forge-lint: disable-next-line(mixed-case-variable)
         JBMessageRoot memory sucker_message
     )
         internal

package/src/structs/JBClaim.sol CHANGED Viewed

@@ -6,7 +6,6 @@ import {JBLeaf} from "./JBLeaf.sol";
 /// @custom:member token The token to claim.
 /// @custom:member leaf The leaf to claim from.
 /// @custom:member proof The proof to claim with. Must be of length `JBSucker._TREE_DEPTH`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBClaim {
     address token;
     JBLeaf leaf;

package/src/structs/JBDenominatedAmount.sol CHANGED Viewed

@@ -5,7 +5,6 @@ pragma solidity ^0.8.0;
 /// @custom:member value The amount.
 /// @custom:member currency The currency identifier (e.g. `JBCurrencyIds.ETH`).
 /// @custom:member decimals The decimal precision of `value`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBDenominatedAmount {
     uint256 value;
     uint32 currency;

package/src/structs/JBInboxTreeRoot.sol CHANGED Viewed

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// inbox tree.
 /// @custom:member nonce Tracks the nonce of the tree. The nonce cannot decrease.
 /// @custom:member root The root of the tree.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBInboxTreeRoot {
     uint64 nonce;
     bytes32 root;

package/src/structs/JBLeaf.sol CHANGED Viewed

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// @custom:member beneficiary The beneficiary of the leaf.
 /// @custom:member projectTokenCount The number of project tokens to claim.
 /// @custom:member terminalTokenAmount The amount of terminal tokens to claim.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBLeaf {
     uint256 index;
     bytes32 beneficiary;

package/src/structs/JBMessageRoot.sol CHANGED Viewed

@@ -20,7 +20,6 @@ import {JBInboxTreeRoot} from "./JBInboxTreeRoot.sol";
 /// @custom:member snapshotNonce A project-wide counter that orders shared-state snapshots independently of per-token
 /// outbox nonces. Used by the receiving chain to reject stale surplus/balance/supply updates without blocking
 /// token-local inbox root updates.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBMessageRoot {
     uint8 version;
     bytes32 token;

package/src/structs/JBOutboxTree.sol CHANGED Viewed

@@ -10,7 +10,6 @@ import {MerkleLib} from "../utils/MerkleLib.sol";
 /// claims have been sent. Packed with `nonce` into one storage slot.
 /// @custom:member balance The balance of the outbox.
 /// @custom:member tree The merkle tree.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBOutboxTree {
     uint64 nonce;
     uint192 numberOfClaimsSent;

package/src/structs/JBRemoteToken.sol CHANGED Viewed

@@ -7,7 +7,6 @@ pragma solidity ^0.8.0;
 /// @custom:member emergencyHatchOpened Whether the emergency hatch is opened.
 /// @custom:member minGas The minimum gas to use when bridging.
 /// @custom:member addr The address of the token on the remote chain.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRemoteToken {
     bool enabled;
     bool emergencyHatch;

package/src/structs/JBSuckerDeployerConfig.sol CHANGED Viewed

@@ -6,7 +6,6 @@ import {JBTokenMapping} from "./JBTokenMapping.sol";
 /// @custom:member deployer The deployer to use.
 /// @custom:member mappings The token mappings to use.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSuckerDeployerConfig {
     IJBSuckerDeployer deployer;
     JBTokenMapping[] mappings;

package/src/structs/JBSuckersPair.sol CHANGED Viewed

@@ -4,7 +4,6 @@ pragma solidity ^0.8.0;
 /// @custom:member local The local address.
 /// @custom:member remote The remote address.
 /// @custom:member remoteChainId The chain ID of the remote address.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSuckersPair {
     address local;
     bytes32 remote;

package/src/structs/JBTokenMapping.sol CHANGED Viewed

@@ -4,7 +4,6 @@ pragma solidity ^0.8.0;
 /// @custom:member localToken The local token address.
 /// @custom:member minGas The minimum gas amount to bridge.
 /// @custom:member remoteToken The remote token address.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBTokenMapping {
     address localToken;
     uint32 minGas;