@bananapus/suckers-v6 0.0.24 → 0.0.26

package/ADMINISTRATION.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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.