@bananapus/suckers-v6 0.0.25 → 0.0.27

package/ADMINISTRATION.md

@@ -1,211 +1,26 @@
 # 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.
-
-## One-Way Or High-Risk Actions
-
-- `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.
-
-## Recovery Notes
-
-- 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.
-
-## 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. |
-
-### JBSuckerDeployer (base and all subclasses)
-
-| 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. |
-
-## Deprecation Lifecycle
-
-The sucker deprecation lifecycle progresses through four states, controlled by `setDeprecation(timestamp)`:
-
-```
-ENABLED --> DEPRECATION_PENDING --> SENDING_DISABLED --> DEPRECATED
-```
-
-| 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. |
-
-**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.
-
-**Removing from registry:** Once a sucker reaches `DEPRECATED`, anyone can call `JBSuckerRegistry.removeDeprecatedSucker(projectId, sucker)` to remove it from the project's sucker list.
-
-## Emergency Hatch
-
-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. |
-
-## 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`).
+| --- | --- |
+| Scope | Cross-chain claim movement, token mapping, fees, and deprecation controls |
+| Control posture | Mixed registry-owner, project-permission, and bridge-specific trust |
+| Highest-risk actions | Wrong token mapping, wrong peer assumptions, and bad emergency or deprecation handling |
+| Recovery posture | Often one-way; many recovery paths are intentionally irreversible |
 
-- **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.
+## Purpose
 
-- **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).
+This repo controls the shared lifecycle around bridging project positions, not just the transport call itself.
 
-## Bridge Infrastructure Risks
+## Control Model
 
-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.
+- registry owner controls shared fee settings and deployer allowlists
+- project-level permissions control token mapping and safety paths
+- bridge-specific implementations inherit external trust assumptions
 
-**Mitigations available to project owners:**
+## Recovery
 
-- **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.
+- emergency hatch and deprecation are the main recovery tools
+- both are intentionally conservative and often one-way
 
-**Fee delivery is best-effort.** The `toRemoteFee` is collected by calling `terminal.pay()` to the fee project during `toRemote()`. If this call reverts (e.g., the fee project has no native token terminal or its terminal is misconfigured), the fee is silently skipped and `toRemote()` proceeds normally. This ensures bridging availability is never blocked by fee infrastructure issues, but it also means fee revenue can be lost without any on-chain signal.

package/ARCHITECTURE.md

@@ -2,59 +2,33 @@
 
 ## 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` bridges Juicebox project positions across chains by turning local burns into claimable remote mints.
 
-## 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` handles prepare, relay, claim, token mapping, deprecation, and emergency exits. `JBSuckerRegistry` tracks deployments, deployer allowlists, and shared fee settings. Bridge-specific implementations handle transport details.
 
-## 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 |
+- Merkle trees stay append-only
+- nonce progression stays monotonic
+- token mapping stays coherent across peers
+- claims and emergency exits do not double-spend
+- outbox balance accounting stays consistent through send and recovery flows
 
-## Runtime Model
+## Trust Boundaries
 
-```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
-  -> claimant proves inclusion against the remote inbox tree
-  -> remote sucker releases or remints the destination-side value
-```
+- shared logic lives in `JBSucker`
+- transport security lives in the bridge-specific implementation and external bridge counterparties
+- registry decisions can widen or constrain the allowed deployment surface
 
-## Critical Invariants
+## Security Model
 
-- 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.
+- the biggest risks are non-atomic cross-chain state, bad token mapping, and broken peer assumptions
+- bridge liveness and correct peer identity are real trust assumptions
 
-## Where Complexity Lives
+## Source Map
 
-- 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.
-
-## Dependencies
-
-- `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
-
-## 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.
+- `src/JBSucker.sol`
+- `src/JBSuckerRegistry.sol`
+- `src/utils/MerkleLib.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,128 +1,33 @@
 # Audit Instructions
 
-This repo bridges Juicebox project tokens and associated terminal assets across chains. Audit it as a conservation and replay-prevention system.
+Audit this repo as cross-chain claim and recovery logic, not as a generic ERC-20 bridge.
 
-## Objective
+## Audit Objective
 
 Find issues that:
-- allow double claim, replay, or claim on the wrong destination
-- lose or strand bridged backing assets
-- let deprecated or emergency paths violate intended safety rules
-- mis-handle root ordering, especially across asynchronous bridge transports
-- grant mapping or safety privileges more broadly than intended
+
+- break Merkle-root or nonce progression
+- allow bad token mapping or peer assumptions
+- permit double-claim or bad emergency exit behavior
+- make non-atomic bridge semantics unsafe
 
 ## Scope
 
 In scope:
-- all Solidity under `src/`
-- deployer contracts under `src/deployers/`
+
+- `src/JBSucker.sol`
+- `src/JBSuckerRegistry.sol`
+- bridge-specific implementations and deployers
 - `src/utils/MerkleLib.sol`
-- libraries, enums, interfaces, and structs under `src/`
-- deployment scripts in `script/`
 
 ## Start Here
 
-Read in this order:
-- the shared flow in `JBSucker`
-- claim validation and execution tracking
-- token mapping and emergency-hatch logic
-- one native bridge implementation
-- `JBCCIPSucker`
-- deployers and registry assumptions
-
-That order gets you from the shared conservation model to the transport-specific deviations.
-
-## System Model
-
-The bridge flow is:
-- burn or prepare project-token value on source chain
-- record a leaf into an outbox tree
-- send a merkle root and backing assets over a chain-specific transport
-- receive the root on the remote chain
-- claim by proving inclusion against the current inbox root
-
-This repo supports multiple transport implementations:
-- OP Stack variants
-- Arbitrum
-- CCIP
-- related deployers and registries
-
-One non-obvious property to audit explicitly:
-- roots and assets do not always arrive in a perfectly ordered, synchronous way
-- the system is intentionally designed to survive some transport mismatch without deadlocking
-- those recovery choices are exactly where conservation bugs tend to hide
-
-## Critical Invariants
-
-1. Cross-chain conservation
-For any prepared transfer, destination claimable value must not exceed what the source side actually prepared and backed.
-
-2. Single execution
-Each bridged leaf must be claimable at most once on the destination and at most once via emergency exit.
-
-3. Peer authenticity
-Only the intended remote peer and messenger path may update inbox roots.
-
-4. Deprecation safety
-Deprecation and emergency-hatch controls must not let callers bypass intended restrictions or steal in-flight funds.
-
-5. Token mapping integrity
-Remote token mappings must be immutable or mutable only exactly where the design allows.
+1. `src/JBSucker.sol`
+2. `src/JBSuckerRegistry.sol`
+3. the relevant bridge-specific implementation
 
-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.
+## Verification
 
-## 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
-
-- `prepare`, `toRemote`, `fromRemote`, and `claim`
-- bitmap execution tracking
-- root and nonce handling
-- token mapping and registry trust
-- 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.
-
-## Finding Bar
-
-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
-
-## Build And 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.
 
@@ -19,7 +24,7 @@ The base implementation is extended for multiple bridge families so the same pro
 
 Use this repo when the requirement is canonical project-token movement across chains. Do not use it if the project is single-chain or if the bridge assumptions for the target networks are unacceptable.
 
-The main idea is not "bridge the token contract." The main idea is "bridge a Juicebox cash-out claim plus enough information to recreate the project-token position on the remote chain."
+The main idea is not "bridge the token contract." The main idea is "bridge a Juicebox claim plus enough information to recreate the project-token position on the remote chain."
 
 ## Key Contracts
 
@@ -27,11 +32,7 @@ The main idea is not "bridge the token contract." The main idea is "bridge a Jui
 | --- | --- |
 | `JBSucker` | Base bridge logic for prepare, relay, claim, token mapping, and lifecycle controls. |
 | `JBSuckerRegistry` | Registry for per-project sucker deployments, deployer allowlists, and shared bridge fee settings. |
-| `JBOptimismSucker` | OP Stack bridge implementation. |
-| `JBBaseSucker` | Base-flavored OP Stack implementation. |
-| `JBCeloSucker` | OP Stack implementation adapted for Celo's native asset behavior. |
-| `JBArbitrumSucker` | Arbitrum bridge implementation. |
-| `JBCCIPSucker` | Chainlink CCIP-based implementation for CCIP-connected chains. |
+| Chain-specific suckers | Transport-specific implementations for OP Stack, Arbitrum, CCIP, and related environments. |
 
 ## Mental Model
 
@@ -45,28 +46,6 @@ That means every bridge path has two trust surfaces:
 - the shared sucker accounting and Merkle logic
 - the bridge-specific transport implementation
 
-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). |
-| [`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). |
-| [`JBArbitrumSucker`](src/JBArbitrumSucker.sol) | Extends `JBSucker`. Bridges via Arbitrum Inbox + Gateway Router. Uses `unsafeCreateRetryableTicket` for L1->L2 (to avoid address aliasing of refund address) and `ArbSys.sendTxToL1` for L2->L1. Requires `msg.value` for L1->L2 transport payment. |
-| [`JBSuckerRegistry`](src/JBSuckerRegistry.sol) | Tracks all suckers per project. Manages deployer allowlist (owner-only). Entry point for `deploySuckersFor`. Can remove deprecated suckers via `removeDeprecatedSucker`. Owns the global `toRemoteFee` (ETH fee in wei, capped at `MAX_TO_REMOTE_FEE` = 0.001 ether), adjustable by the registry owner via `setToRemoteFee()`. All sucker clones read this fee from the registry. Existing-project deployments are deploy-and-map operations, so the registry also needs to be arranged as an authorized `MAP_SUCKER_TOKEN` operator for those projects. |
-| [`JBSuckerDeployer`](src/JBSuckerDeployer.sol) | Abstract base deployer. Clones a singleton sucker via `LibClone.cloneDeterministic` and initializes it. Two-phase setup: `setChainSpecificConstants` then `configureSingleton`. |
-| [`JBCCIPSuckerDeployer`](src/deployers/JBCCIPSuckerDeployer.sol) | Deployer for `JBCCIPSucker`. Stores CCIP router, remote chain ID, and CCIP chain selector. |
-| [`JBOptimismSuckerDeployer`](src/deployers/JBOptimismSuckerDeployer.sol) | Deployer for `JBOptimismSucker`. Stores OP Messenger and OP Bridge addresses. |
-| [`JBBaseSuckerDeployer`](src/deployers/JBBaseSuckerDeployer.sol) | Thin wrapper around `JBOptimismSuckerDeployer` for Base. |
-| [`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). |
-| [`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. |
-
 ## Read These Files First
 
 1. `src/JBSucker.sol`
@@ -77,18 +56,24 @@ The shortest useful reading order is:
 
 ## Integration Traps
 
-- do not reason about suckers as if they were generic ERC-20 bridges; they are project-token plus treasury-state bridges
-- root ordering and message delivery semantics matter as much as the claim proof format
-- token mapping is part of the economic invariant, not just a convenience config
-- emergency and deprecation paths are not edge tooling; they are part of normal operational safety
+- do not reason about suckers as if they were generic ERC-20 bridges
+- root ordering and message delivery semantics matter as much as proof format
+- token mapping is part of the economic invariant
+- emergency and deprecation paths are part of normal operational safety
 
 ## Where State Lives
 
-- per-claim and tree progression state live in the sucker pair itself
-- deployment inventory and shared operational config live in `JBSuckerRegistry`
-- bridge transport assumptions live in the chain-specific implementation and its external counterparties
+- per-claim and tree progression state: the sucker pair
+- deployment inventory and shared operational config: `JBSuckerRegistry`
+- bridge transport assumptions: the chain-specific implementation and its external counterparties
+
+## High-Signal Tests
 
-When reviewing a bridge incident, check local state transition correctness before blaming the transport layer.
+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
 
@@ -112,7 +97,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
 
@@ -136,9 +121,13 @@ script/
 
 ## Risks And Notes
 
-- out-of-order root delivery can make some claims unclaimable until an operator uses an emergency path
+- out-of-order root delivery can make some claims unavailable until an operator uses an emergency path
 - bridge-specific transport assumptions matter as much as the shared sucker logic
 - token mapping and deprecation controls are governance-sensitive surfaces
 - 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.
+- Always separate shared sucker logic from bridge-specific transport behavior.
+- Use the chain-specific implementation and 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.