@bananapus/suckers-v6 0.0.26 → 0.0.28

package/ADMINISTRATION.md

@@ -4,82 +4,23 @@
 
 | Item | Details |
 | --- | --- |
-| 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 |
+| 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 |
 
 ## Purpose
 
-`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.
+This repo controls the shared lifecycle around bridging project positions, not just the transport call itself.
 
 ## Control Model
 
-- `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
-
-| 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 |
-
-## Privileged Surfaces
-
-| 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 |
-
-## Immutable And One-Way
-
-- 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.
-
-## Operational Notes
-
-- 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.
-
-## Machine Notes
-
-- 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.
+- 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
 
 ## Recovery
 
-- 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
-
-- 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.
-
-## Source Map
+- emergency hatch and deprecation are the main recovery tools
+- both are intentionally conservative and often one-way
 
-- `src/JBSucker.sol`
-- `src/JBSuckerRegistry.sol`
-- `src/deployers/`
-- `src/utils/MerkleLib.sol`
-- `test/`

package/ARCHITECTURE.md

@@ -2,89 +2,33 @@
 
 ## Purpose
 
-`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.
+`nana-suckers-v6` bridges Juicebox project positions across chains by turning local burns into claimable remote mints.
 
 ## System Overview
 
-`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.
+`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.
 
 ## Core Invariants
 
-- 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.
-
-## 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 |
+- 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
 
 ## 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 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 destination-side value
-```
-
-## Accounting Model
-
-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.
-
-`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.
+- 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
 
 ## Security Model
 
-- 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.
-- 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`
+- 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
 
 ## 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

@@ -1,110 +1,30 @@
 # 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.
 
 ## 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.
-
-## Security 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
-
-## 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
-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.
-
-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.
-
-## Attack Surfaces
-
-- `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
-
-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
-
-## Accepted Risks Or Behaviors
-
-- Out-of-order arrival is part of the intended model, not an edge case.
+1. `src/JBSucker.sol`
+2. `src/JBSuckerRegistry.sol`
+3. the relevant bridge-specific implementation
 
 ## Verification
 

package/README.md

@@ -24,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
 
@@ -32,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
 
@@ -50,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`) 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). |
-| [`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 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. |
-
 ## Read These Files First
 
 1. `src/JBSucker.sol`
@@ -82,18 +56,16 @@ 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
-
-When reviewing a bridge incident, check local state transition correctness before blaming the transport layer.
+- 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
 
@@ -149,15 +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; 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.
+- 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

@@ -24,6 +24,7 @@ This file focuses on the bridge-like risks in the sucker system: merkle-root pro
 - **CCIP:** trusts `CCIP_ROUTER` identity plus `any2EvmMessage.sender` and `sourceChainSelector`. The router address is immutable at deploy time -- if Chainlink rotates routers, the sucker is bricked (no upgrade path).
 - **CREATE2 peer assumption.** `peer()` defaults to `address(this)`, assuming deterministic cross-chain deployment. Breaks if deployer address, init code, or factory nonce differs across chains. Incorrect peer = permanent fund loss (messages accepted from nobody, or routed to wrong address).
 - **Controller/terminal must exist on destination chain.** `_handleClaim` calls `controllerOf(projectId).mintTokensOf()`. If the project does not exist or has no controller on the remote chain, all claims permanently revert -- funds are stuck.
+- **Registry allowlisting does not verify deployer singleton provenance.** `JBSuckerRegistry.deploySuckersFor()` only checks the deployer allowlist, not the singleton implementation behind the deployer. `configureSingleton()` can point an approved deployer at any JBSucker singleton. This is a privileged-only concern (both deployer configuration and registry allowlisting require governance). Defense: validate deployer configuration during registry allowlist reviews.
 - **No reentrancy guard.** The contract relies on state ordering (mark-executed-before-external-call) rather than explicit ReentrancyGuard. Correct today, but fragile to future refactors.
 
 ## 2. Merkle Tree Risks
@@ -41,6 +42,7 @@ This file focuses on the bridge-like risks in the sucker system: merkle-root pro
 - **CCIP: no guaranteed delivery order.** CCIP does not guarantee in-order delivery. The contract handles this by accepting any nonce > current, but concurrent `toRemote` calls for the same token could result in a later root arriving first, skipping an intermediate root.
 - **OP Stack: generally ordered** but the L1-to-L2 message must be relayed by an off-chain actor. A delayed or dropped relay permanently blocks claims until someone retries the relay.
 - **Message loss.** If an AMB silently fails (accepts the message on L1 but never delivers to L2), `numberOfClaimsSent` is incremented but the remote peer never receives the root. Those leaves are blocked from both remote claim and local emergency exit (conservative: locked, not double-spent). Recovery requires enabling the emergency hatch.
+- **Aggregate balance accounting.** `amountToAddToBalanceOf(token)` computes `balanceOf(this) - outbox.balance`, making all contract-held tokens fungible claim backing. This is intentional: all funds serve the same project, so refunded ETH (from failed Arbitrum retryable tickets) and stale native deliveries correctly become project-claimable. The tradeoff is that later roots can consume liquidity from earlier failed batches, but the project is the ultimate beneficiary in all cases.
 - **`fromRemote` does not revert on stale nonce.** By design, stale/duplicate messages are silently ignored (emitting `StaleRootRejected`). This prevents fund loss on native token transfers where reverting would lose the ETH, but means monitoring must watch for this event to detect bridge issues.
 
 ## 4. Token Mapping Risks
@@ -62,7 +64,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.
+- **Registry aggregate views fail open.** `JBSuckerRegistry.remoteBalanceOf`, `remoteSurplusOf`, and `remoteTotalSupplyOf` include both active and deprecated suckers with per-chain deduplication (max per chain, not sum). When multiple suckers target the same peer chain (e.g., during migration), the highest reported value is used. The views 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, or simply expensive to query.
 
 ## 6. Deprecation Lifecycle
 
@@ -83,6 +85,8 @@ This file focuses on the bridge-like risks in the sucker system: merkle-root pro
 - **Claim vs emergency exit use separate bitmap slots.** Emergency exit uses `_executedFor[keccak256(abi.encode(terminalToken))]` while regular claims use `_executedFor[terminalToken]`. This means a leaf that was emergency-exited locally could theoretically also be claimed remotely if the root was already sent -- double-spend is prevented only by the `numberOfClaimsSent` check.
 - **`numberOfClaimsSent` is the critical guard.** Emergency exit reverts if `outbox.numberOfClaimsSent != 0 && outbox.numberOfClaimsSent - 1 >= index`. The `numberOfClaimsSent != 0` precondition prevents underflow when no root has ever been sent — in that case, all leaves are available for emergency exit. This means leaves at indices below `numberOfClaimsSent` cannot be emergency-exited (they may have been sent to the remote peer). If `_sendRootOverAMB` silently fails, these leaves are permanently locked.
 - **Emergency exit decrements `outbox.balance`.** If emergency exits drain the outbox balance below the amount that was already sent to the bridge, the accounting becomes inconsistent. The contract guards against this by only allowing exit for unsent leaves.
+- **Emergency exit recipient is the leaf beneficiary.** `exitThroughEmergencyHatch()` refunds to `claimData.leaf.beneficiary`, not the original `prepare()` caller. The depositor chose this beneficiary when preparing the bridge; the leaf structure does not store the depositor address. If Alice prepares for Bob and the bridge fails, Bob gets the emergency refund, not Alice. This is the intended behavior: the depositor delegated their claim to the beneficiary.
+- **`numberOfClaimsSent` advancement timing.** `_sendRoot()` sets `numberOfClaimsSent` before `_sendRootOverAMB()` completes. If the L1 transaction succeeds but L2 delivery fails, those leaves are blocked from emergency exit. Mitigations: Arbitrum retryable tickets can be manually re-executed on L2; Optimism messages can be re-relayed by anyone. If delivery permanently fails, `enableEmergencyHatchFor()` combined with project owner intervention can recover. Adding a rollback mechanism would introduce double-spend risk (leaf claimable on both chains). Current design is conservative: locked funds are preferable to double-spent funds.
 - **Emergency hatch + minting.** Emergency exit calls `_handleClaim`, which mints project tokens via the controller. If the controller or token contract is broken/missing, emergency exits also revert -- there is no "raw withdrawal" of terminal tokens without minting.
 
 ## 8. DoS Vectors
@@ -130,7 +134,11 @@ The fee is paid to `FEE_PROJECT_ID` (the protocol project), not to the sucker's
 
 ### 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.
+`JBSuckerRegistry.remoteBalanceOf`, `remoteSurplusOf`, and `remoteTotalSupplyOf` intentionally use `try/catch` around each sucker and silently ignore peers that revert. Both active and deprecated suckers are included, with per-chain deduplication: when multiple suckers target the same peer chain (e.g., during a migration window), the highest reported value is used to avoid double-counting. 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.8 Zero-output swap batches route to pendingSwapOf
+
+When `JBSwapCCIPSucker.ccipReceive` receives bridge tokens and the swap succeeds but returns zero local tokens (e.g., due to extreme price impact or dust amounts), the batch is routed to `pendingSwapOf` for later retry via `retrySwap`. Without this, claims would proceed with zero terminal backing, minting unbacked project tokens. The trade-off is that these batches require a manual `retrySwap` call once pool conditions improve. Anyone can call `retrySwap` — it is permissionless.
 
 ### 10.6 Hookless V4 spot pricing is sandwich-vulnerable by design
 
@@ -139,3 +147,7 @@ When the only available Uniswap pool for a cross-denomination swap is a hookless
 ### 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.
+
+### 10.9 Zero-value `prepare()` is allowed
+
+`prepare()` does not reject `projectTokenCount == 0`. A zero-value check would be trivially bypassed by passing `1` instead, so it provides no real protection against remap-window consumption. The cost to create a leaf with `projectTokenCount = 1` is negligible (1 wei of project tokens). The one-time remap window is protected by the token mapping's `enabled` flag and the outbox tree count, not by minimum deposit requirements.

package/SKILLS.md

@@ -2,49 +2,24 @@
 
 ## Use This File For
 
-- Use this file when the task involves cross-chain project-token bridging, token mapping, Merkle claim flow, bridge-specific transport logic, or sucker registry behavior.
-- Start here, then decide whether the issue is in shared accounting, message authentication, token mapping, or operator/deprecation controls. Those concerns live in different layers.
+- Use this file when the task involves cross-chain project-token movement, Merkle-root progression, token mapping, or emergency and deprecation flows.
+- Start here, then decide whether the issue is in shared sucker logic or in a bridge-specific transport implementation.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and bridge model | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Repo overview and architecture | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Shared bridge logic | [`src/JBSucker.sol`](./src/JBSucker.sol), [`src/JBSuckerRegistry.sol`](./src/JBSuckerRegistry.sol) |
-| Chain-specific transport behavior | [`src/JBArbitrumSucker.sol`](./src/JBArbitrumSucker.sol), [`src/JBOptimismSucker.sol`](./src/JBOptimismSucker.sol), [`src/JBCCIPSucker.sol`](./src/JBCCIPSucker.sol), [`src/JBCeloSucker.sol`](./src/JBCeloSucker.sol) |
-| Deployer and transport setup | [`src/deployers/`](./src/deployers/) |
-| Merkle and helper logic | [`src/utils/`](./src/utils/), [`src/libraries/`](./src/libraries/) |
-| Interop and chain-specific fork coverage | [`test/ForkMainnet.t.sol`](./test/ForkMainnet.t.sol), [`test/ForkArbitrum.t.sol`](./test/ForkArbitrum.t.sol), [`test/ForkCelo.t.sol`](./test/ForkCelo.t.sol), [`test/ForkOPStack.t.sol`](./test/ForkOPStack.t.sol), [`test/InteropCompat.t.sol`](./test/InteropCompat.t.sol) |
-| Swap, claim, attack, and regression coverage | [`test/ForkSwap.t.sol`](./test/ForkSwap.t.sol), [`test/ForkClaimMainnet.t.sol`](./test/ForkClaimMainnet.t.sol), [`test/SuckerAttacks.t.sol`](./test/SuckerAttacks.t.sol), [`test/SuckerDeepAttacks.t.sol`](./test/SuckerDeepAttacks.t.sol), [`test/SuckerRegressions.t.sol`](./test/SuckerRegressions.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Base contracts | [`src/JBSucker.sol`](./src/JBSucker.sol), [`src/JBSuckerRegistry.sol`](./src/JBSuckerRegistry.sol) |
-| Chain-specific implementations and deployers | [`src/`](./src/), [`src/deployers/`](./src/deployers/) |
-| Libraries, utils, and types | [`src/libraries/`](./src/libraries/), [`src/utils/`](./src/utils/), [`src/interfaces/`](./src/interfaces/), [`src/structs/`](./src/structs/), [`src/enums/`](./src/enums/) |
-| Scripts | [`script/`](./script/) |
-| Tests | [`test/`](./test/) |
+| Merkle logic | [`src/utils/MerkleLib.sol`](./src/utils/MerkleLib.sol) |
+| Bridge-specific behavior | the matching implementation and deployer under [`src/`](./src/) and [`src/deployers/`](./src/deployers/) |
 
 ## Purpose
 
-Cross-chain bridge layer for Juicebox project tokens and the terminal assets that back them. Suckers package local burn or claim state into Merkle roots, relay those roots across bridge transports, and let users recreate the position on the remote chain.
-
-## Reference Files
-
-- Open [`references/runtime.md`](./references/runtime.md) when you need the base claim flow, registry role, token mapping model, or the main bridge invariants.
-- Open [`references/operations.md`](./references/operations.md) when you need deployer and transport-selection guidance, deprecation and emergency behavior, or the common stale-data traps around bridge configuration.
+Canonical cross-chain movement layer for Juicebox project positions.
 
 ## Working Rules
 
-- Start in [`src/JBSucker.sol`](./src/JBSucker.sol) for shared accounting and claim flow, then move to the chain-specific implementation only after you know the base path is correct.
-- `JBSucker` explicitly does not support fee-on-transfer or rebasing tokens. If a bug report involves those assets, treat it as an unsupported-path question first.
-- Root progression, peer supply, and peer surplus snapshots are part of economic correctness, not just bridge bookkeeping.
-- Token mapping is intentionally one-way after real activity starts. Disabling a mapping is allowed; remapping to a different remote asset is not.
-- Peer symmetry depends on deployer and salt assumptions as well as runtime code. A bridge bug can start in deployment shape before it appears in message flow.
-- Treat token mapping, root progression, and emergency/deprecation controls as first-class runtime behavior, not admin-only side tooling.
-- When debugging a bridge incident, separate accounting correctness from transport correctness before patching.
-- Message authentication is delegated to bridge-specific subclasses. When reviewing a new transport, `_isRemotePeer` is one of the first things to inspect.
-- Emergency exit and deprecation behavior are intentionally conservative. Some failure modes lock funds rather than risking double-spend.
-- If a task touches project deployment shape, check whether the real source is `nana-omnichain-deployers-v6` or `revnet-core-v6` instead of the sucker implementation itself.
+- Start in `JBSucker` for shared lifecycle logic.
+- Separate Merkle bookkeeping from bridge-specific transport assumptions.
+- Treat token mapping, deprecation, and emergency hatch behavior as core safety surfaces.