@bananapus/suckers-v6 0.0.26 → 0.0.27

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

package/USER_JOURNEYS.md

@@ -2,141 +2,49 @@
 
 ## Repo Purpose
 
-This repo bridges Juicebox project-token positions and their treasury-backed claim semantics across chains.
-It is not a generic proxy terminal and not a generic ERC-20 bridge. The important unit is the project position and the
-explicit bridge lifecycle around `prepare`, `toRemote`, and claim.
+This repo lets a Juicebox project move a claimable position from one chain to another.
 
 ## Primary Actors
 
-- projects that want canonical cross-chain movement of project-token positions
-- operators deploying and registering sucker pairs on supported bridge families
-- users bridging a project position from one chain to another
-- teams responsible for bridge fees, token mappings, deprecation, and emergency controls
+- users bridging project positions
+- operators relaying roots and managing emergency or deprecation flows
+- auditors checking Merkle progression and token mapping correctness
 
-## Key Surfaces
+## Journey 1: Prepare And Relay A Claim
 
-- `JBSucker`: shared base lifecycle for preparing, relaying, and claiming bridge leaves
-- `JBSuckerRegistry`: registry for sucker deployments, deployer allowlists, and shared fee settings
-- `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker`, `JBArbitrumSucker`, `JBCCIPSucker`, `JBSwapCCIPSucker`: bridge-family implementations
+**Actor:** user or relayer.
 
-## Journey 1: Launch A Cross-Chain Sucker Pair For A Project
-
-**Actor:** operator or deployer.
-
-**Intent:** deploy and register the paired bridge surfaces a project will rely on across chains.
-
-**Preconditions**
-- the project exists on multiple chains or plans to
-- the team has chosen the bridge family it trusts
-
-**Main Flow**
-1. Choose the chain-specific sucker implementation and deployer, such as Arbitrum, OP Stack, Celo, or CCIP.
-2. Configure token mappings, bridge counterparties, and per-project registry state in `JBSuckerRegistry`.
-3. Deploy the pair so each side knows its remote peer and expected transport assumptions.
-4. Frontends and operators can now reason about the bridge as a known project surface instead of ad hoc per-transfer logic.
-
-**Failure Modes**
-- paired deployments disagree about counterparties or token mappings
-- teams deploy the right contracts but never register the resulting pair coherently
-
-**Postconditions**
-- paired suckers are deployed, registered, and ready to transport claims between the chains they serve
-
-## Journey 2: Bridge A Position From One Chain To Another
-
-**Actor:** user bridging a position.
-
-**Intent:** move project-token exposure from the source chain to the destination chain.
-
-**Preconditions**
-- a user holds project-token exposure on the source chain
-- the project has a supported destination-side sucker path
-
-**Main Flow**
-1. The user calls `prepare` on the source-chain sucker to burn or lock the relevant local position into a claimable leaf.
-2. The source sucker appends that leaf into its Merkle outbox tree.
-3. Someone relays the new root to the remote chain using `toRemote`.
-4. The claimant proves inclusion against the remote inbox tree and receives the recreated project-token position there.
-
-**Failure Modes**
-- token mappings are wrong for the project or chain pair
-- transport-layer fees are missing and roots never arrive
-- operators assume the bridge is generic ERC-20 transport rather than project-position transport
-
-**Postconditions**
-- the source position becomes a claim, the claim is relayed, and the destination position is minted after proof verification
-
-## Journey 3: Map Treasury Assets And Project Tokens Correctly Across Chains
-
-**Actor:** operator mapping assets and wrappers.
-
-**Intent:** preserve economic meaning across chains instead of bridging into the wrong wrapped exposure.
-
-**Preconditions**
-- the project supports multiple assets or wrappers across chains
-- users should be able to bridge without silent economic mismatch
+**Intent:** burn locally and make the position claimable remotely.
 
 **Main Flow**
-1. Configure remote token metadata and mapping with the sucker pair.
-2. Make sure the destination chain can mint or settle the project-token representation the bridge expects.
-3. Audit chain-specific native-asset handling, especially on Celo or other non-identical environments.
-
-**Failure Modes**
-- local and remote wrappers look similar but settle into different economics
-- chain-specific native-asset assumptions are copied across environments where they do not hold
-
-**Postconditions**
-- the remote claim recreates the intended exposure instead of a superficially similar but economically different asset
+1. A user calls `prepare`.
+2. The claim enters the local outbox tree.
+3. A relayer sends the current root to the peer chain with `toRemote`.
 
-## Journey 4: Operate The Bridge Safely Over Time
+## Journey 2: Claim Remotely
 
-**Actor:** bridge operator.
+**Actor:** claimant.
 
-**Intent:** keep registry config, fees, deprecation, and bridge-family assumptions coherent after launch.
-
-**Preconditions**
-- the bridge is live and now needs operational stewardship rather than just deployment
+**Intent:** prove inclusion on the remote chain and mint the corresponding position.
 
 **Main Flow**
-1. Use `JBSuckerRegistry` to manage deployer allowlists and shared operational config.
-2. Watch fee fallback paths and transport assumptions because delivery failure is part of the intended threat model.
-3. Use deprecation or emergency surfaces when a bridge family or remote destination should no longer be used.
-
-**Failure Modes**
-- fee policy drifts from actual transport costs and claims stop delivering
-- bridge-family deprecation is delayed even after counterparties or fees become unsafe
-
-**Postconditions**
-- fee policy, deprecation, trusted counterparties, and emergency paths remain coherent as conditions change
-
-## Journey 5: Recover Value Through The Emergency Hatch When Normal Delivery Breaks
+1. Fetch a proof against the current inbox root.
+2. Call the remote claim path.
+3. The remote side verifies the proof and recreates the intended position.
 
-**Actor:** user or responder handling a broken delivery path.
+## Journey 3: Use Emergency Or Deprecation Paths
 
-**Intent:** recover value when the normal bridge delivery path is unavailable.
+**Actor:** operator or project authority.
 
-**Preconditions**
-- a claim cannot complete through the normal inbox or remote-delivery path
+**Intent:** recover from broken or deprecated bridge conditions.
 
 **Main Flow**
-1. Enable or enter the emergency mode the sucker pair exposes for the affected path.
-2. Use `exitThroughEmergencyHatch(...)` with the relevant claim data.
-3. Treat emergency execution slots as distinct state that still must not allow the same economic position to be claimed twice.
-
-**Failure Modes**
-- teams use the emergency path prematurely instead of as a documented recovery mode
-- claim state is not checked carefully and responders risk inconsistent double-claim assumptions
-
-**Postconditions**
-- users can recover through the explicit emergency mechanism without double-spending the same claim
+1. Enable the relevant emergency or deprecation path.
+2. Stop relying on the broken route.
+3. Recover only through the allowed recovery surface.
 
 ## Trust Boundaries
 
-- this repo trusts both the shared sucker accounting logic and the selected bridge-family transport
-- token mapping and registry governance are part of the economic safety model
-- emergency and deprecation controls are operationally important, not just last-resort tooling
-
-## Hand-Offs
+- shared claim logic and transport behavior are separate concerns
+- non-atomic cross-chain flows are normal, not exceptional
 
-- Use [nana-omnichain-deployers-v6](../nana-omnichain-deployers-v6/USER_JOURNEYS.md) when a project wants suckers packaged into its launch flow instead of deployed separately.
-- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) or [revnet-core-v6](../revnet-core-v6/USER_JOURNEYS.md) for the treasury and runtime project behavior that suckers transport across chains.

package/package.json

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

package/src/libraries/JBSwapPoolLib.sol

@@ -327,13 +327,11 @@ library JBSwapPoolLib {
                 config: config, normalizedTokenIn: normalizedTokenIn, normalizedTokenOut: normalizedTokenOut
             });
 
-            // Prefer V4 if it has more liquidity, but only if V4 has a hook or V3 had no liquidity.
+            // Select the V4 pool if it has strictly more liquidity than the best V3 pool.
             if (v4Liquidity > bestLiquidity) {
-                if (address(v4Candidate.hooks) != address(0) || bestLiquidity == 0) {
-                    isV4 = true;
-                    v3Pool = IUniswapV3Pool(address(0));
-                    v4Key = v4Candidate;
-                }
+                isV4 = true;
+                v3Pool = IUniswapV3Pool(address(0));
+                v4Key = v4Candidate;
             }
         }
     }

package/test/unit/pool_discovery.t.sol

@@ -0,0 +1,366 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+// forge-lint: disable-next-line(unaliased-plain-import)
+import "forge-std/Test.sol";
+
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IUniswapV3Pool} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol";
+import {IUniswapV3PoolState} from "@uniswap/v3-core/contracts/interfaces/pool/IUniswapV3PoolState.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
+import {PoolId, PoolIdLibrary} from "@uniswap/v4-core/src/types/PoolId.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {StateLibrary} from "@uniswap/v4-core/src/libraries/StateLibrary.sol";
+
+import {JBSwapPoolLib} from "../../src/libraries/JBSwapPoolLib.sol";
+
+/// @notice Mock V4 PoolManager that stores slot data for pool state queries via extsload.
+contract MockPoolManager {
+    using PoolIdLibrary for PoolKey;
+
+    /// @dev Storage slot for pools mapping (matches StateLibrary.POOLS_SLOT).
+    bytes32 private constant POOLS_SLOT = bytes32(uint256(6));
+    /// @dev Offset for liquidity within Pool.State (matches StateLibrary.LIQUIDITY_OFFSET).
+    uint256 private constant LIQUIDITY_OFFSET = 3;
+
+    /// @dev Arbitrary storage mapping: slot => value.
+    mapping(bytes32 => bytes32) private _slots;
+
+    /// @notice Configure a pool's slot0 (sqrtPriceX96, tick, protocolFee, lpFee) and liquidity.
+    /// @param key The pool key to configure.
+    /// @param sqrtPriceX96 The sqrt price (non-zero means initialized).
+    /// @param liquidity The in-range liquidity.
+    function setPool(PoolKey memory key, uint160 sqrtPriceX96, uint128 liquidity) external {
+        PoolId id = key.toId();
+        bytes32 stateSlot = keccak256(abi.encodePacked(PoolId.unwrap(id), POOLS_SLOT));
+
+        // Pack slot0: sqrtPriceX96 in bottom 160 bits, tick=0 in next 24, fees=0 in upper.
+        _slots[stateSlot] = bytes32(uint256(sqrtPriceX96));
+
+        // Pack liquidity at offset 3.
+        bytes32 liquiditySlot = bytes32(uint256(stateSlot) + LIQUIDITY_OFFSET);
+        _slots[liquiditySlot] = bytes32(uint256(liquidity));
+    }
+
+    /// @notice Implements IExtsload.extsload for StateLibrary compatibility.
+    function extsload(bytes32 slot) external view returns (bytes32) {
+        return _slots[slot];
+    }
+
+    /// @notice Multi-slot extsload (not used in pool discovery but required by interface).
+    function extsload(bytes32 startSlot, uint256 nSlots) external view returns (bytes32[] memory values) {
+        values = new bytes32[](nSlots);
+        for (uint256 i; i < nSlots; i++) {
+            values[i] = _slots[bytes32(uint256(startSlot) + i)];
+        }
+    }
+
+    /// @notice Array extsload (not used in pool discovery but required by interface).
+    function extsload(bytes32[] calldata slots) external view returns (bytes32[] memory values) {
+        values = new bytes32[](slots.length);
+        for (uint256 i; i < slots.length; i++) {
+            values[i] = _slots[slots[i]];
+        }
+    }
+}
+
+/// @notice Harness contract that exposes JBSwapPoolLib.discoverPool for unit testing.
+contract PoolDiscoveryHarness {
+    function discoverPool(
+        JBSwapPoolLib.SwapConfig memory config,
+        address normalizedTokenIn,
+        address normalizedTokenOut
+    )
+        external
+        view
+        returns (bool isV4, IUniswapV3Pool v3Pool, PoolKey memory v4Key)
+    {
+        return JBSwapPoolLib.discoverPool(config, normalizedTokenIn, normalizedTokenOut);
+    }
+}
+
+/// @title JBSwapPoolLib_PoolDiscoveryTest
+/// @notice Unit tests for the M-1 audit fix: V3/V4 pool preference logic in _discoverPool.
+/// @dev The fix removed the V3 preference guard that blocked hookless V4 pools from being selected
+/// even when they had deeper liquidity than any V3 pool.
+contract JBSwapPoolLib_PoolDiscoveryTest is Test {
+    using PoolIdLibrary for PoolKey;
+
+    // Test addresses.
+    address constant TOKEN_A = address(0xA);
+    address constant TOKEN_B = address(0xB);
+    address constant WETH = address(0xC);
+    address constant HOOK_ADDR = address(0xD);
+
+    // Mock contracts.
+    address v3Factory;
+    MockPoolManager poolManager;
+    PoolDiscoveryHarness harness;
+
+    // Precomputed V3 pool addresses (one per fee tier).
+    address v3Pool3000;
+    address v3Pool500;
+    address v3Pool10000;
+    address v3Pool100;
+
+    function setUp() public {
+        v3Factory = makeAddr("v3Factory");
+        poolManager = new MockPoolManager();
+        harness = new PoolDiscoveryHarness();
+
+        // Create V3 pool addresses.
+        v3Pool3000 = makeAddr("v3Pool3000");
+        v3Pool500 = makeAddr("v3Pool500");
+        v3Pool10000 = makeAddr("v3Pool10000");
+        v3Pool100 = makeAddr("v3Pool100");
+
+        // Default: all V3 factory getPool calls return address(0) (no pool).
+        vm.mockCall(v3Factory, abi.encodeWithSelector(IUniswapV3Factory.getPool.selector), abi.encode(address(0)));
+    }
+
+    // =========================================================================
+    // Helpers
+    // =========================================================================
+
+    /// @dev Configure a V3 pool at a specific fee tier with given liquidity.
+    function _setupV3Pool(address pool, uint24 fee, uint128 liquidity) internal {
+        // Mock the factory to return this pool for the given fee tier.
+        vm.mockCall(
+            v3Factory,
+            abi.encodeWithSelector(IUniswapV3Factory.getPool.selector, TOKEN_A, TOKEN_B, fee),
+            abi.encode(pool)
+        );
+        // Also mock the reverse token ordering (factory is commutative).
+        vm.mockCall(
+            v3Factory,
+            abi.encodeWithSelector(IUniswapV3Factory.getPool.selector, TOKEN_B, TOKEN_A, fee),
+            abi.encode(pool)
+        );
+        // Mock the pool's liquidity.
+        vm.mockCall(pool, abi.encodeWithSelector(IUniswapV3PoolState.liquidity.selector), abi.encode(liquidity));
+    }
+
+    /// @dev Configure a V4 pool (hookless) with given liquidity.
+    function _setupV4HooklessPool(uint24 fee, int24 tickSpacing, uint128 liquidity) internal {
+        // Sort tokens for V4 convention (no WETH conversion needed here since neither is WETH).
+        (address sorted0, address sorted1) = TOKEN_A < TOKEN_B ? (TOKEN_A, TOKEN_B) : (TOKEN_B, TOKEN_A);
+
+        PoolKey memory key = PoolKey({
+            currency0: Currency.wrap(sorted0),
+            currency1: Currency.wrap(sorted1),
+            fee: fee,
+            tickSpacing: tickSpacing,
+            hooks: IHooks(address(0))
+        });
+
+        // Set a non-zero sqrtPriceX96 to indicate the pool is initialized, and set liquidity.
+        poolManager.setPool(key, 1 << 96, liquidity); // sqrtPriceX96 = 2^96 (price = 1)
+    }
+
+    /// @dev Configure a V4 pool with a hook and given liquidity.
+    function _setupV4HookedPool(address hook, uint24 fee, int24 tickSpacing, uint128 liquidity) internal {
+        (address sorted0, address sorted1) = TOKEN_A < TOKEN_B ? (TOKEN_A, TOKEN_B) : (TOKEN_B, TOKEN_A);
+
+        PoolKey memory key = PoolKey({
+            currency0: Currency.wrap(sorted0),
+            currency1: Currency.wrap(sorted1),
+            fee: fee,
+            tickSpacing: tickSpacing,
+            hooks: IHooks(hook)
+        });
+
+        poolManager.setPool(key, 1 << 96, liquidity);
+    }
+
+    /// @dev Build a SwapConfig pointing at our mocks.
+    function _config() internal view returns (JBSwapPoolLib.SwapConfig memory) {
+        return JBSwapPoolLib.SwapConfig({
+            v3Factory: IUniswapV3Factory(v3Factory),
+            poolManager: IPoolManager(address(poolManager)),
+            univ4Hook: HOOK_ADDR,
+            weth: WETH
+        });
+    }
+
+    // =========================================================================
+    // Test 1: V3 dust liquidity, V4 deep liquidity => V4 selected
+    // (This was the broken case before the M-1 fix)
+    // =========================================================================
+
+    /// @notice When V3 has dust liquidity (1 wei) and hookless V4 has deep liquidity,
+    /// V4 should be selected. Before the fix, V3 would win because hookless V4 was blocked.
+    function test_poolDiscovery_v4HooklessBeatsV3Dust() public {
+        // V3 has dust liquidity at 0.3% fee tier.
+        _setupV3Pool(v3Pool3000, 3000, 1);
+
+        // Hookless V4 has deep liquidity at 0.3% fee tier (fee=3000, tickSpacing=60).
+        _setupV4HooklessPool(3000, 60, 1_000_000e18);
+
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "V4 hookless pool with deep liquidity should be selected over V3 dust");
+        assertEq(address(v3Pool), address(0), "V3 pool should be cleared when V4 wins");
+    }
+
+    // =========================================================================
+    // Test 2: V3 deeper liquidity than V4 => V3 still selected
+    // =========================================================================
+
+    /// @notice When V3 has deeper liquidity than V4, V3 should still be selected.
+    function test_poolDiscovery_v3DeeperThanV4() public {
+        // V3 has deep liquidity.
+        _setupV3Pool(v3Pool3000, 3000, 1_000_000e18);
+
+        // Hookless V4 has less liquidity.
+        _setupV4HooklessPool(3000, 60, 500_000e18);
+
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertFalse(isV4, "V3 should be selected when it has deeper liquidity");
+        assertEq(address(v3Pool), v3Pool3000, "Best V3 pool should be returned");
+    }
+
+    // =========================================================================
+    // Test 3: Equal liquidity => V3 wins (tie-break behavior)
+    // =========================================================================
+
+    /// @notice When V3 and V4 have equal liquidity, V3 wins because V4 requires
+    /// strictly greater liquidity (> not >=).
+    function test_poolDiscovery_equalLiquidity_v3Wins() public {
+        uint128 sameLiquidity = 500_000e18;
+
+        // V3 and V4 both at same liquidity.
+        _setupV3Pool(v3Pool3000, 3000, sameLiquidity);
+        _setupV4HooklessPool(3000, 60, sameLiquidity);
+
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertFalse(isV4, "V3 should win on equal liquidity (V4 needs strictly more)");
+        assertEq(address(v3Pool), v3Pool3000, "V3 pool should be returned on tie");
+    }
+
+    // =========================================================================
+    // Test 4: V3 zero liquidity, V4 has liquidity => V4 selected
+    // (Was already working before the fix, regression check)
+    // =========================================================================
+
+    /// @notice When V3 has zero liquidity and V4 has liquidity, V4 is selected.
+    function test_poolDiscovery_v3ZeroLiquidity_v4Selected() public {
+        // V3 pool exists but has zero liquidity.
+        _setupV3Pool(v3Pool3000, 3000, 0);
+
+        // V4 hookless has some liquidity.
+        _setupV4HooklessPool(3000, 60, 100e18);
+
+        (bool isV4,,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "V4 should be selected when V3 has zero liquidity");
+    }
+
+    // =========================================================================
+    // Test 5: Hookless V4 with more liquidity than V3 (the broken case)
+    // =========================================================================
+
+    /// @notice Edge case: hookless V4 pool with strictly more liquidity than V3 should
+    /// be selected. This was the exact scenario broken before the M-1 fix — the old
+    /// code required V4 to have a hook OR V3 to have zero liquidity.
+    function test_poolDiscovery_hooklessV4MoreLiquidityThanV3() public {
+        // V3 has moderate liquidity.
+        _setupV3Pool(v3Pool500, 500, 100_000e18);
+
+        // Hookless V4 at 0.05% tier has more liquidity.
+        _setupV4HooklessPool(500, 10, 200_000e18);
+
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "Hookless V4 with more liquidity must beat V3 (M-1 fix)");
+        assertEq(address(v3Pool), address(0), "V3 pool should be zeroed when V4 wins");
+    }
+
+    // =========================================================================
+    // Additional coverage: hooked V4 pool with more liquidity
+    // =========================================================================
+
+    /// @notice A hooked V4 pool with more liquidity than V3 should also be selected
+    /// (this already worked before the fix, but verify it still works).
+    function test_poolDiscovery_hookedV4BeatsV3() public {
+        // V3 has some liquidity.
+        _setupV3Pool(v3Pool3000, 3000, 50_000e18);
+
+        // Hooked V4 has much more liquidity.
+        _setupV4HookedPool(HOOK_ADDR, 3000, 60, 500_000e18);
+
+        (bool isV4,,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "Hooked V4 with more liquidity should beat V3");
+    }
+
+    // =========================================================================
+    // No V4 pool manager configured => V3 always wins
+    // =========================================================================
+
+    /// @notice When no V4 pool manager is configured, V3 is always selected.
+    function test_poolDiscovery_noPoolManager_v3Only() public {
+        _setupV3Pool(v3Pool3000, 3000, 100e18);
+
+        JBSwapPoolLib.SwapConfig memory config = JBSwapPoolLib.SwapConfig({
+            v3Factory: IUniswapV3Factory(v3Factory),
+            poolManager: IPoolManager(address(0)), // No V4.
+            univ4Hook: HOOK_ADDR,
+            weth: WETH
+        });
+
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(config, TOKEN_A, TOKEN_B);
+
+        assertFalse(isV4, "Without pool manager, V3 should always be selected");
+        assertEq(address(v3Pool), v3Pool3000, "V3 pool should be returned");
+    }
+
+    // =========================================================================
+    // No pools at all => reverts with NoPool in executeSwap (but discoverPool returns zeros)
+    // =========================================================================
+
+    /// @notice When neither V3 nor V4 has any pools, discoverPool returns zeros.
+    function test_poolDiscovery_noPools_returnsZeros() public {
+        // No pools configured (default setUp has all V3 returning address(0)).
+        (bool isV4, IUniswapV3Pool v3Pool,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertFalse(isV4, "Should not select V4 when no pools exist");
+        assertEq(address(v3Pool), address(0), "No V3 pool should be found");
+    }
+
+    // =========================================================================
+    // Multi-tier: V4 wins on a different tier than V3's best
+    // =========================================================================
+
+    /// @notice V3 best pool is on 0.3% tier, but hookless V4 on 0.05% tier has more liquidity.
+    function test_poolDiscovery_v4WinsOnDifferentTier() public {
+        // V3 at 0.3% has moderate liquidity.
+        _setupV3Pool(v3Pool3000, 3000, 100_000e18);
+
+        // Hookless V4 at 0.05% tier (fee=500, tickSpacing=10) has more.
+        _setupV4HooklessPool(500, 10, 200_000e18);
+
+        (bool isV4,,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "V4 should win even on a different fee tier");
+    }
+
+    // =========================================================================
+    // V4 barely beats V3 (boundary: V4 has 1 more liquidity)
+    // =========================================================================
+
+    /// @notice V4 with exactly 1 more unit of liquidity than V3 should win.
+    function test_poolDiscovery_v4BeatsV3ByOne() public {
+        uint128 v3Liq = 1_000_000;
+
+        _setupV3Pool(v3Pool3000, 3000, v3Liq);
+        _setupV4HooklessPool(3000, 60, v3Liq + 1);
+
+        (bool isV4,,) = harness.discoverPool(_config(), TOKEN_A, TOKEN_B);
+
+        assertTrue(isV4, "V4 should win with strictly more liquidity (by 1 wei)");
+    }
+}