@bananapus/suckers-v6 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bananapus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,422 @@
+# nana-suckers-v5
+
+Cross-chain bridging for Juicebox V5 projects. Suckers let users burn project tokens on one chain and receive the same amount on another, moving the backing funds across via merkle-tree-based claims and chain-specific bridges.
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#what-are-suckers">What are Suckers?</a></li>
+    <li><a href="#architecture">Architecture</a></li>
+    <li><a href="#bridging-flow">Bridging Flow</a></li>
+    <li><a href="#bridging-tokens">Bridging Tokens</a></li>
+    <li><a href="#launching-suckers">Launching Suckers</a></li>
+    <li><a href="#managing-suckers">Managing Suckers</a></li>
+    <li><a href="#using-the-relayer">Using the Relayer</a></li>
+    <li><a href="#resources">Resources</a></li>
+    <li><a href="#repository-layout">Repository Layout</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <ul>
+      <li><a href="#install">Install</a></li>
+      <li><a href="#develop">Develop</a></li>
+      <li><a href="#scripts">Scripts</a></li>
+      <li><a href="#tips">Tips</a></li>
+    </ul>
+  </ol>
+</details>
+
+_If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core-v5) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
+
+## What are Suckers?
+
+`JBSucker` contracts are deployed in pairs, with one on each network being bridged to or from. The [`JBSucker`](src/JBSucker.sol) contract implements core logic, and is extended by network-specific implementations adapted to each bridge:
+
+| Sucker | Networks | Description |
+|--------|----------|-------------|
+| [`JBCCIPSucker`](src/JBCCIPSucker.sol) | Any CCIP-connected chains | Uses [Chainlink CCIP](https://docs.chain.link/ccip) (`ccipSend`/`ccipReceive`). Handles native token wrapping/unwrapping for chains with different native assets. |
+| [`JBOptimismSucker`](src/JBOptimismSucker.sol) | Ethereum and Optimism | Uses the [OP Standard Bridge](https://docs.optimism.io/builders/app-developers/bridging/standard-bridge) and the [OP Messenger](https://docs.optimism.io/builders/app-developers/bridging/messaging). |
+| [`JBBaseSucker`](src/JBBaseSucker.sol) | Ethereum and Base | A thin wrapper around `JBOptimismSucker` with Base chain IDs. |
+| [`JBArbitrumSucker`](src/JBArbitrumSucker.sol) | Ethereum and Arbitrum | Uses the [Arbitrum Inbox](https://docs.arbitrum.io/build-decentralized-apps/cross-chain-messaging) and the [Arbitrum Gateway](https://docs.arbitrum.io/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/get-started). Handles L1<->L2 retryable tickets. |
+
+Suckers use two [merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) to track project token claims associated with each terminal token they support:
+
+- The **outbox tree** tracks tokens on the local chain — the network that the sucker is on.
+- The **inbox tree** tracks tokens which have been bridged from the peer chain — the network that the sucker's peer is on.
+
+For example, a sucker which supports bridging ETH and USDC would have four trees — an inbox and outbox tree for each token. These trees are append-only, and when they're bridged over to the other chain, they aren't deleted — they only update the remote inbox tree with the latest root.
+
+To insert project tokens into the outbox tree, users call `JBSucker.prepare(...)` with the amount of project tokens to bridge and the terminal token to bridge with them. The sucker cashes out those project tokens to reclaim the chosen terminal token from the project's primary terminal. Then it inserts a claim with this information into the outbox tree.
+
+Anyone can bridge an outbox tree to the peer chain by calling `JBSucker.toRemote(token)`. The outbox tree then _becomes_ the peer sucker's inbox tree for that token. Users can claim their tokens on the peer chain by providing a merkle proof which shows that their claim is in the inbox tree.
+
+## Architecture
+
+On each network:
+
+```mermaid
+graph TD;
+    A[JBSuckerRegistry] -->|exposes| B["deploySuckersFor(...)"]
+    B -->|calls| C[IJBSuckerDeployer]
+    C -->|deploys| D[JBSucker]
+    A -->|tracks| D
+```
+
+For an example project deployed on mainnet and Optimism with a `JBOptimismSucker` on each network:
+
+```mermaid
+graph TD;
+    subgraph Mainnet
+    A[Project] -->|cashed-out funds| B[JBOptimismSucker]
+    B -->|burns/mints tokens| A
+    end
+    subgraph Optimism
+    C[Project] -->|cashed-out funds| D[JBOptimismSucker]
+    D -->|burns/mints tokens| C
+    end
+    B <-->|merkle roots/funds| D
+```
+
+### Contracts
+
+| Contract | Description |
+|----------|-------------|
+| `JBSucker` | Abstract base. Manages outbox/inbox merkle trees, `prepare`/`toRemote`/`claim` lifecycle, token mapping, deprecation, and emergency hatch. Deployed as clones via `Initializable`. |
+| `JBCCIPSucker` | Extends `JBSucker`. Bridges via Chainlink CCIP (`ccipSend`/`ccipReceive`). Supports any CCIP-connected chain. Handles native token wrapping/unwrapping. |
+| `JBOptimismSucker` | Extends `JBSucker`. Bridges via OP Standard Bridge + OP Messenger. |
+| `JBBaseSucker` | Thin wrapper around `JBOptimismSucker` with Base chain IDs. |
+| `JBArbitrumSucker` | Extends `JBSucker`. Bridges via Arbitrum Inbox + Gateway Router. Handles L1<->L2 retryable tickets. |
+| `JBSuckerRegistry` | Tracks all suckers per project. Manages deployer allowlist. Entry point for `deploySuckersFor`. |
+| `JBSuckerDeployer` | Abstract base deployer. Clones a singleton sucker via `LibClone.cloneDeterministic` and initializes it. |
+| `JBCCIPSuckerDeployer` | Deployer for `JBCCIPSucker`. Stores CCIP router, remote chain ID, and chain selector. |
+| `JBOptimismSuckerDeployer` | Deployer for `JBOptimismSucker`. Stores OP Messenger and OP Bridge addresses. |
+| `JBBaseSuckerDeployer` | Thin wrapper around `JBOptimismSuckerDeployer` for Base. |
+| `JBArbitrumSuckerDeployer` | Deployer for `JBArbitrumSucker`. Stores Arbitrum Inbox, Gateway Router, and layer (L1/L2). |
+| `MerkleLib` | Incremental merkle tree (depth 32, modeled on eth2 deposit contract). Used for outbox/inbox trees. |
+| `CCIPHelper` | CCIP router addresses, chain selectors, and WETH addresses per chain. |
+| `ARBAddresses` | Arbitrum bridge contract addresses (Inbox, Gateway Router) for mainnet and Sepolia. |
+| `ARBChains` | Arbitrum chain ID constants. |
+
+## Bridging Flow
+
+```
+Chain A                              Chain B
+  |                                    |
+  |  1. prepare(tokenCount, ...)       |
+  |     - transfers project tokens     |
+  |     - cashes out for terminal tkn  |
+  |     - inserts leaf into outbox     |
+  |                                    |
+  |  2. toRemote(token)                |
+  |     - sends merkle root + funds -->|
+  |                                    |
+  |                          3. fromRemote(root)
+  |                             - updates inbox tree
+  |                                    |
+  |                          4. claim(proof)
+  |                             - verifies merkle proof
+  |                             - mints project tokens
+  |                             - adds funds to balance
+```
+
+## Bridging Tokens
+
+Imagine that "OhioDAO" is deployed on Ethereum mainnet and Optimism:
+
+- It has the $OHIO ERC-20 project token and a `JBOptimismSucker` deployed on each network.
+- Its suckers map mainnet ETH to Optimism ETH, and vice versa.
+
+Each sucker has mappings from terminal tokens on the local chain to associated terminal tokens on the remote chain.
+
+_Here's how Jimmy can bridge his $OHIO tokens (and the corresponding ETH) from mainnet to Optimism._
+
+**1. Pay the project.** Jimmy pays OhioDAO 1 ETH on Ethereum mainnet:
+
+```solidity
+JBMultiTerminal.pay{value: 1 ether}({
+    projectId: 12,
+    token: JBConstants.NATIVE_TOKEN,
+    amount: 1 ether,
+    beneficiary: jimmy,
+    minReturnedTokens: 0,
+    memo: "OhioDAO rules",
+    metadata: ""
+});
+```
+
+OhioDAO's ruleset has a `weight` of `1e18`, so Jimmy receives 1 $OHIO (`1e18` tokens).
+
+**2. Approve the sucker.** Before bridging, Jimmy approves the `JBOptimismSucker` to transfer his $OHIO:
+
+```solidity
+JBERC20.approve({
+    spender: address(optimismSucker),
+    value: 1e18
+});
+```
+
+**3. Prepare the bridge.** Jimmy calls `prepare(...)` on the mainnet sucker:
+
+```solidity
+JBOptimismSucker.prepare({
+    projectTokenAmount: 1e18,
+    beneficiary: jimmy,
+    minTokensReclaimed: 0,
+    token: JBConstants.NATIVE_TOKEN
+});
+```
+
+The sucker transfers Jimmy's $OHIO to itself, cashes them out using OhioDAO's primary ETH terminal, and inserts a leaf into the ETH outbox tree. The leaf is a `keccak256` hash of the beneficiary's address, the project token count, and the terminal token amount reclaimed.
+
+**4. Bridge to remote.** Jimmy (or anyone) calls `toRemote(...)`:
+
+```solidity
+JBOptimismSucker.toRemote(JBConstants.NATIVE_TOKEN);
+```
+
+This sends the outbox merkle root and the accumulated ETH to the peer sucker on Optimism. After the bridge completes, the Optimism sucker's ETH inbox tree is updated with the new root containing Jimmy's claim.
+
+**5. Claim on the remote chain.** Jimmy claims his $OHIO on Optimism by calling `claim(...)` with a [`JBClaim`](src/structs/JBClaim.sol):
+
+```solidity
+struct JBClaim {
+    address token;
+    JBLeaf leaf;
+    bytes32[32] proof; // Must be TREE_DEPTH (32) long.
+}
+```
+
+The [`JBLeaf`](src/structs/JBLeaf.sol):
+
+```solidity
+struct JBLeaf {
+    uint256 index;
+    address beneficiary;
+    uint256 projectTokenCount;
+    uint256 terminalTokenAmount;
+}
+```
+
+Building these claims manually requires tracking every insertion and computing merkle proofs. The [`juicerkle`](https://github.com/Bananapus/juicerkle) service simplifies this — `POST` a JSON request to `/claims`:
+
+```json
+{
+    "chainId": 10,
+    "sucker": "0x5678...",
+    "token": "0x000000000000000000000000000000000000EEEe",
+    "beneficiary": "0x1234..."
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chainId` | `int` | Network ID for the sucker being claimed from. |
+| `sucker` | `string` | Address of the sucker being claimed from. |
+| `token` | `string` | Terminal token whose inbox tree is being claimed from. |
+| `beneficiary` | `string` | Address to get available claims for. |
+
+The service looks through the entire inbox tree and returns all available claims as `JBClaim` structs ready to pass to `claim(...)`.
+
+If the sucker's `ADD_TO_BALANCE_MODE` is `ON_CLAIM`, the bridged ETH is immediately added to OhioDAO's Optimism balance. Otherwise, someone calls `addOutstandingAmountToBalance(token)` to add it manually.
+
+## Launching Suckers
+
+Requirements for deploying a sucker pair:
+
+1. **Projects on both chains.** Project IDs don't have to match.
+2. **100% cash out rate.** Both projects must have `cashOutTaxRate` of `JBConstants.MAX_CASH_OUT_TAX_RATE` so suckers can fully cash out project tokens for terminal tokens.
+3. **Owner minting enabled.** Both projects must have `allowOwnerMinting` set to `true` so suckers can mint bridged project tokens.
+4. **ERC-20 project token.** Both projects must have a deployed ERC-20 token (via `JBController.deployERC20For(...)`).
+
+Suckers are deployed through the [`JBSuckerRegistry`](src/JBSuckerRegistry.sol) on each chain. The registry maps local tokens to remote tokens during deployment, so it needs permission:
+
+```solidity
+// Give the registry MAP_SUCKER_TOKEN permission for project 12
+uint256[] memory permissionIds = new uint256[](1);
+permissionIds[0] = JBPermissionIds.MAP_SUCKER_TOKEN; // ID 28
+
+permissions.setPermissionsFor(
+    projectOwner,
+    JBPermissionsData({
+        operator: address(registry),
+        projectId: 12,
+        permissionIds: permissionIds
+    })
+);
+```
+
+Now deploy the suckers with a token mapping:
+
+```solidity
+// Map mainnet ETH to Optimism ETH
+JBTokenMapping[] memory mappings = new JBTokenMapping[](1);
+mappings[0] = JBTokenMapping({
+    localToken: JBConstants.NATIVE_TOKEN,
+    minGas: 200_000,
+    remoteToken: JBConstants.NATIVE_TOKEN,
+    minBridgeAmount: 0.025 ether
+});
+
+JBSuckerDeployerConfig[] memory configs = new JBSuckerDeployerConfig[](1);
+configs[0] = JBSuckerDeployerConfig({
+    deployer: IJBSuckerDeployer(optimismSuckerDeployer),
+    mappings: mappings
+});
+
+// Must use the same salt and caller on both chains
+bytes32 salt = keccak256("my-project-suckers-v1");
+address[] memory suckers = registry.deploySuckersFor(12, salt, configs);
+```
+
+- The [`JBTokenMapping`](src/structs/JBTokenMapping.sol) maps local mainnet ETH to remote Optimism ETH.
+  - `minBridgeAmount` prevents spam — ours blocks attempts to bridge less than 0.025 ETH.
+  - `minGas` requires a gas limit of at least 200,000. If your token has expensive transfer logic, you may need more.
+- The [`JBSuckerDeployerConfig`](src/structs/JBSuckerDeployerConfig.sol) specifies which deployer to use. You can only use approved deployers through the registry — check for `SuckerDeployerAllowed` events or contact the registry's owner.
+- **For the suckers to be peers, the `salt` has to match on both chains and the same address must call `deploySuckersFor(...)`.**
+
+Finally, give the sucker permission to mint bridged project tokens:
+
+```solidity
+uint256[] memory mintPermissionIds = new uint256[](1);
+mintPermissionIds[0] = JBPermissionIds.MINT_TOKENS; // ID 9
+
+permissions.setPermissionsFor(
+    projectOwner,
+    JBPermissionsData({
+        operator: suckers[0],
+        projectId: 12,
+        permissionIds: mintPermissionIds
+    })
+);
+```
+
+Repeat this process on the other chain to deploy the peer sucker, and the project is ready for bridging.
+
+## Managing Suckers
+
+Once configured, suckers manage themselves. Stay up-to-date on changes to the bridge infrastructure used by your sucker of choice. If a change causes suckers to become incompatible with the underlying bridge, there are two options.
+
+**Always perform these actions on BOTH sides of the sucker pair.**
+
+### Disable a token
+
+If a bridge change affects only certain tokens, call `mapToken(...)` with `remoteToken` set to `address(0)` to disable that token. If the bridge won't allow a final transfer with the remaining funds, activate the `EmergencyHatch` for the affected tokens.
+
+The emergency hatch lets depositors withdraw their funds on the chain where they deposited. Only those whose funds have not been sent to the remote chain can withdraw. Once opened for a token, that token can never be bridged by this sucker again — deploy a new sucker instead.
+
+### Deprecate the suckers
+
+If the bridging infrastructure will no longer work, deprecate the sucker to begin shutdown. The deprecation timestamp must be at least `_maxMessagingDelay()` (14 days) in the future to ensure no funds or roots are lost in transit. After this duration, all tokens allow exit through the `EmergencyHatch` and no new messages are accepted. This protects against future fake or malicious bridge messages.
+
+When deprecating, ensure no pending bridge messages need retrying — once deprecation completes, those messages will be rejected.
+
+## Using the Relayer
+
+Bridging from L1 to L2 is straightforward. Bridging from L2 to L1 requires extra steps to finalize the withdrawal. For OP Stack networks like Optimism or Base, this follows the [withdrawal flow](https://docs.optimism.io/stack/protocol/withdrawal-flow):
+
+1. The **withdrawal initiating transaction**, which the user submits on L2.
+2. The **withdrawal proving transaction**, which the user submits on L1 to prove that the withdrawal is legitimate (based on a merkle patricia trie root).
+3. The **withdrawal finalizing transaction**, which the user submits on L1 after the fault challenge period has passed.
+
+Users can do this manually, but it's a hassle. The [`bananapus-sucker-relayer`](https://github.com/Bananapus/bananapus-sucker-relayer) automates proving and finalizing withdrawals using [OpenZeppelin Defender](https://www.openzeppelin.com/defender). Project creators set up a Defender account, configure a relayer through their dashboard, and fund it with ETH for gas.
+
+## Resources
+
+- [`MerkleLib`](src/utils/MerkleLib.sol) — Incremental merkle tree based on [Nomad's implementation](https://github.com/nomad-xyz/nomad-monorepo/blob/main/solidity/nomad-core/libs/Merkle.sol) and the eth2 deposit contract.
+- [`juicerkle`](https://github.com/Bananapus/juicerkle) — Service that returns available claims for a beneficiary (generates merkle proofs). Includes a [Go merkle tree implementation](https://github.com/Bananapus/juicerkle/blob/master/tree/tree.go) for computing roots and building/verifying proofs.
+- [`juicerkle-tester`](https://github.com/Bananapus/juicerkle-tester) — End-to-end bridging test: deploys projects, tokens, and suckers, then bridges between them. Useful as a bridging walkthrough.
+
+## Repository Layout
+
+```
+nana-suckers-v5/
+├── script/
+│   ├── Deploy.s.sol - Deployment script.
+│   └── helpers/
+│       └── SuckerDeploymentLib.sol - Internal helpers for deployment.
+├── src/
+│   ├── JBSucker.sol - Abstract base sucker implementation.
+│   ├── JBCCIPSucker.sol - Chainlink CCIP bridge implementation.
+│   ├── JBOptimismSucker.sol - OP Stack bridge implementation.
+│   ├── JBBaseSucker.sol - Base-specific wrapper around JBOptimismSucker.
+│   ├── JBArbitrumSucker.sol - Arbitrum bridge implementation.
+│   ├── JBSuckerRegistry.sol - Registry tracking suckers per project.
+│   ├── deployers/ - Deployers for each kind of sucker.
+│   ├── enums/ - JBAddToBalanceMode, JBLayer, JBSuckerState.
+│   ├── interfaces/ - Contract interfaces.
+│   ├── libraries/ - ARBAddresses, ARBChains, CCIPHelper.
+│   ├── structs/ - JBClaim, JBLeaf, JBMessageRoot, JBOutboxTree, etc.
+│   └── utils/
+│       └── MerkleLib.sol - Incremental merkle tree (depth 32).
+└── test/
+    ├── Fork.t.sol - Fork tests.
+    ├── SuckerAttacks.t.sol - Security-focused attack tests.
+    ├── SuckerDeepAttacks.t.sol - Deep attack scenario tests.
+    ├── mocks/ - Mock contracts for testing.
+    └── unit/ - Unit tests (merkle, registry, deployer, emergency, arb).
+```
+
+## Usage
+
+### Install
+
+For projects using `npm` to manage dependencies (recommended):
+
+```bash
+npm install @bananapus/suckers-v5
+```
+
+For projects using `forge` to manage dependencies:
+
+```bash
+forge install Bananapus/nana-suckers-v5
+```
+
+If you're using `forge`, add `@bananapus/suckers-v5/=lib/nana-suckers-v5/` to `remappings.txt`. You'll also need to install `nana-suckers-v5`'s dependencies and add similar remappings for them.
+
+### Develop
+
+`nana-suckers-v5` uses [npm](https://www.npmjs.com/) (version >=20.0.0) for package management and the [Foundry](https://github.com/foundry-rs/foundry) development toolchain for builds, tests, and deployments. To get set up, [install Node.js](https://nodejs.org/en/download) and install [Foundry](https://github.com/foundry-rs/foundry):
+
+```bash
+curl -L https://foundry.paradigm.xyz | sh
+```
+
+Download and install dependencies with:
+
+```bash
+npm ci && forge install
+```
+
+If you run into trouble with `forge install`, try using `git submodule update --init --recursive` to ensure that nested submodules have been properly initialized.
+
+| Command | Description |
+|---------|-------------|
+| `forge build` | Compile the contracts and write artifacts to `out`. |
+| `forge test` | Run the tests. |
+| `forge test -vvvv` | Run tests with full traces. |
+| `forge fmt` | Lint. |
+| `forge coverage` | Generate a test coverage report. |
+| `forge build --sizes` | Get contract sizes. |
+| `forge clean` | Remove build artifacts and cache. |
+| `foundryup` | Update Foundry. Run this periodically. |
+
+To learn more, visit the [Foundry Book](https://book.getfoundry.sh/) docs.
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Run local tests. |
+| `npm run coverage` | Generate an LCOV test coverage report. |
+| `npm run artifacts` | Fetch Sphinx artifacts and write them to `deployments/`. |
+
+### Tips
+
+To view test coverage, run `npm run coverage` to generate an LCOV test report. You can use an extension like [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) to view coverage in your editor.
+
+If you're using Nomic Foundation's [Solidity](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity) extension in VSCode, you may run into LSP errors because the extension cannot find dependencies outside of `lib`. You can often fix this by running:
+
+```bash
+forge remappings >> remappings.txt
+```
+
+This makes the extension aware of default remappings.

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security Considerations
+
+## [INTEROP-6] Cross-Chain Accounting Mismatch: NATIVE_TOKEN Semantic Divergence
+
+**Severity:** Medium
+**Status:** Acknowledged — by design, not fixable without oracle dependencies
+
+### Description
+
+`JBConstants.NATIVE_TOKEN` represents different real-world assets on different chains:
+
+| Chain | Native Token | Value |
+|-------|-------------|-------|
+| Ethereum, Optimism, Base, Arbitrum | ETH | ~$X |
+| Celo | CELO | ~$Y |
+| Polygon | MATIC | ~$Z |
+
+When a project deploys suckers that map `NATIVE_TOKEN → NATIVE_TOKEN` across chains where the native token differs, the protocol treats different assets as equivalent. There is no on-chain mechanism that distinguishes ETH from CELO at the sucker level.
+
+### How Suckers Bridge Tokens
+
+1. Source chain: sucker wraps `NATIVE_TOKEN` → WETH (via `CCIPHelper.wethOfChain()`)
+2. CCIP bridges the WETH to the destination chain
+3. Destination chain: sucker unwraps WETH → `NATIVE_TOKEN`
+
+On ETH-native chains (Ethereum, OP, Base, Arbitrum), this works correctly because WETH wraps/unwraps ETH.
+
+On Celo, `NATIVE_TOKEN` is CELO. The sucker would attempt to wrap CELO into WETH, which is a different operation — WETH on Celo (`0xD221812de1BD094f35587EE8E174B07B6167D9Af`) wraps ETH bridged to Celo, not CELO itself.
+
+### Impact
+
+1. **Issuance mispricing** — Payments in CELO through a `NATIVE_TOKEN` terminal are priced as ETH-equivalent without a CELO/ETH price feed.
+2. **Sucker bridging failure** — `NATIVE_TOKEN → NATIVE_TOKEN` mapping causes the CCIP sucker to attempt incompatible token operations.
+3. **Surplus fragmentation** — Cash-out bonding curve on each chain only sees that chain's surplus. Users must bridge project tokens to the chain with more surplus to get fair cash-out values.
+
+### Why the Matching Hash Doesn't Catch This
+
+The REVDeployer matching hash (used to verify both sides of a sucker deployment match) includes economic parameters (baseCurrency, stages, issuance, cash-out tax) but does NOT include terminal configurations, accounting contexts, or token mappings. Two deployments can produce identical hashes with incompatible asset configurations.
+
+### Recommended Mitigation (Operational)
+
+For non-ETH-native chains (Celo, Polygon, Avalanche, BNB Chain):
+
+1. **Use WETH (ERC20) as the accounting context** — not `NATIVE_TOKEN`. This avoids the semantic ambiguity about what "native" means.
+2. **Set sucker token mappings as `WETH → WETH`** (ERC20 to ERC20) — not `NATIVE_TOKEN → NATIVE_TOKEN`.
+3. **Use USDC as a second accounting context** — USDC is the same asset cross-chain, no conversion needed.
+4. **Ensure `JBPrices` has working price feeds** for accepted tokens on each chain.
+
+### Safe Chains (ETH-native)
+
+OP Stack L2s where native token IS ETH are unaffected: Ethereum, Optimism, Base, Arbitrum.
+
+### Affected Chains
+
+Any chain where the native token is not ETH: Celo (CELO), Polygon (MATIC), Avalanche (AVAX), BNB Chain (BNB).

package/SKILLS.md

@@ -0,0 +1,163 @@
+# nana-suckers-v5
+
+## Purpose
+
+Cross-chain token and fund bridging for Juicebox V5 projects, using merkle trees to batch claims and chain-specific bridges (Chainlink CCIP, OP Stack, Arbitrum) to move assets.
+
+## Contracts
+
+| Contract | Role |
+|----------|------|
+| `JBSucker` | Abstract base with full lifecycle: prepare, toRemote, fromRemote, claim, emergency hatch, deprecation. Manages outbox/inbox merkle trees per terminal token. |
+| `JBCCIPSucker` | CCIP bridge implementation. Implements `IAny2EVMMessageReceiver.ccipReceive`. Wraps/unwraps native tokens for CCIP transport. |
+| `JBOptimismSucker` | OP Stack bridge implementation. Uses `IOPMessenger.sendMessage` and `IOPStandardBridge.bridgeERC20To`. |
+| `JBBaseSucker` | Extends `JBOptimismSucker` with Base<->Ethereum chain ID mapping. |
+| `JBArbitrumSucker` | Arbitrum bridge implementation. Uses retryable tickets (`unsafeCreateRetryableTicket`) for L1->L2, `ArbSys.sendTxToL1` for L2->L1. Handles L1/L2 address aliasing. |
+| `JBSuckerRegistry` | Entry point for deploying and tracking suckers. Manages deployer allowlist. Requires `DEPLOY_SUCKERS` permission. |
+| `JBSuckerDeployer` | Abstract deployer base. Uses Solady `LibClone.cloneDeterministic` to deploy suckers as minimal proxies. |
+| `JBCCIPSuckerDeployer` | CCIP-specific deployer. Stores `ccipRouter`, `ccipRemoteChainId`, `ccipRemoteChainSelector`. |
+| `JBOptimismSuckerDeployer` | OP-specific deployer. Stores `opMessenger`, `opBridge`. |
+| `JBBaseSuckerDeployer` | Thin wrapper around `JBOptimismSuckerDeployer` for separate Base artifact. |
+| `JBArbitrumSuckerDeployer` | Arbitrum-specific deployer. Stores `arbInbox`, `arbGatewayRouter`, `arbLayer`. |
+| `MerkleLib` | Incremental merkle tree (depth 32). `insert` appends leaves, `root` computes current root, `branchRoot` verifies proofs. |
+
+## Key Functions
+
+| Function | Contract | What it does |
+|----------|----------|--------------|
+| `prepare(projectTokenCount, beneficiary, minTokensReclaimed, token)` | `JBSucker` | Transfers project tokens from caller, cashes them out for terminal tokens, inserts a leaf into the outbox merkle tree. |
+| `toRemote(token)` | `JBSucker` | Sends the outbox merkle root and accumulated funds for `token` to the peer sucker on the remote chain via the bridge. |
+| `fromRemote(root)` | `JBSucker` | Receives a merkle root from the remote peer. Updates the inbox tree. Only callable by the verified remote peer. |
+| `claim(claimData)` | `JBSucker` | Verifies a merkle proof against the inbox tree, mints project tokens for the beneficiary, and optionally adds terminal tokens to the project's balance. |
+| `claim(claims[])` | `JBSucker` | Batch version of `claim`. |
+| `mapToken(map)` | `JBSucker` | Maps a local terminal token to a remote token. Requires `MAP_SUCKER_TOKEN` permission. Setting `remoteToken` to `address(0)` disables bridging and sends remaining outbox. |
+| `mapTokens(maps[])` | `JBSucker` | Batch version of `mapToken`. |
+| `addOutstandingAmountToBalance(token)` | `JBSucker` | Manually adds received terminal tokens to the project's balance (only when `ADD_TO_BALANCE_MODE == MANUAL`). |
+| `enableEmergencyHatchFor(tokens)` | `JBSucker` | Opens emergency hatch for specified tokens (irreversible). Requires `SUCKER_SAFETY` permission. |
+| `exitThroughEmergencyHatch(claimData)` | `JBSucker` | Lets users reclaim tokens on the chain they deposited, using their outbox proof. Only works when emergency hatch is open or sucker is deprecated. |
+| `setDeprecation(timestamp)` | `JBSucker` | Sets when the sucker becomes fully deprecated. Must be at least `_maxMessagingDelay()` (14 days) in the future. Requires `SUCKER_SAFETY` permission. |
+| `ccipReceive(any2EvmMessage)` | `JBCCIPSucker` | CCIP entry point. Validates router + peer + chain selector, unwraps native tokens if needed, calls `fromRemote`. |
+| `deploySuckersFor(projectId, salt, configurations)` | `JBSuckerRegistry` | Deploys one or more suckers for a project. Requires `DEPLOY_SUCKERS` permission. Salt must match on both chains for peer pairing. |
+| `allowSuckerDeployer(deployer)` | `JBSuckerRegistry` | Adds a deployer to the allowlist. Owner-only. |
+| `removeDeprecatedSucker(projectId, sucker)` | `JBSuckerRegistry` | Removes a deprecated sucker from the registry. Callable by anyone. |
+| `createForSender(localProjectId, salt)` | `JBSuckerDeployer` | Clones the singleton sucker deterministically and initializes it with the project ID. |
+| `setChainSpecificConstants(...)` | Deployers | One-time configuration of bridge-specific addresses. Callable only by `LAYER_SPECIFIC_CONFIGURATOR`. |
+
+## Integration Points
+
+| Dependency | Import | Used For |
+|------------|--------|----------|
+| `@bananapus/core-v5` | `IJBDirectory`, `IJBController`, `IJBTokens`, `IJBTerminal`, `IJBCashOutTerminal`, `IJBPayoutTerminal` | Project lookup, token minting/burning, cash-outs, `addToBalanceOf` |
+| `@bananapus/core-v5` | `JBConstants` | `NATIVE_TOKEN` sentinel address |
+| `@bananapus/permission-ids-v5` | `JBPermissionIds` | `MAP_SUCKER_TOKEN`, `DEPLOY_SUCKERS`, `SUCKER_SAFETY`, `MINT_TOKENS` permission IDs |
+| `@chainlink/contracts-ccip` | `Client`, `IAny2EVMMessageReceiver` | CCIP message encoding/decoding, receiver interface |
+| `@arbitrum/nitro-contracts` | `IInbox`, `IOutbox`, `IBridge`, `ArbSys`, `AddressAliasHelper` | Arbitrum retryable tickets, L2->L1 messages, address aliasing |
+| `@openzeppelin/contracts` | `SafeERC20`, `BitMaps`, `ERC165`, `Initializable`, `Ownable`, `ERC2771Context`, `EnumerableMap` | Token safety, leaf tracking, clone init, registry ownership, meta-transactions |
+| `solady` | `LibClone` | Deterministic minimal proxy deployment |
+| `@prb/math` | `mulDiv` | Safe fixed-point multiplication |
+
+## Key Types
+
+| Struct/Enum | Key Fields | Used In |
+|-------------|------------|---------|
+| `JBClaim` | `token`, `leaf` (`JBLeaf`), `proof` (`bytes32[32]`) | `claim`, `exitThroughEmergencyHatch` |
+| `JBLeaf` | `index`, `beneficiary`, `projectTokenCount`, `terminalTokenAmount` | Merkle tree leaves (outbox/inbox) |
+| `JBOutboxTree` | `nonce` (uint64), `balance`, `tree` (MerkleLib.Tree), `numberOfClaimsSent` | Per-token outbox state in `JBSucker` |
+| `JBInboxTreeRoot` | `nonce` (uint64), `root` (bytes32) | Per-token inbox state in `JBSucker` |
+| `JBMessageRoot` | `token`, `amount`, `remoteRoot` (`JBInboxTreeRoot`) | Cross-chain message payload |
+| `JBRemoteToken` | `enabled`, `emergencyHatch`, `minGas` (uint32), `addr`, `minBridgeAmount` | Token mapping config |
+| `JBTokenMapping` | `localToken`, `minGas` (uint32), `remoteToken`, `minBridgeAmount` | Input for `mapToken`/`mapTokens` |
+| `JBSuckerDeployerConfig` | `deployer` (`IJBSuckerDeployer`), `mappings` (`JBTokenMapping[]`) | Input for `deploySuckersFor` |
+| `JBSuckersPair` | `local`, `remote`, `remoteChainId` | Return type for `suckerPairsOf` |
+| `JBAddToBalanceMode` | `MANUAL`, `ON_CLAIM` | Controls when received funds are added to project balance |
+| `JBSuckerState` | `ENABLED`, `DEPRECATION_PENDING`, `SENDING_DISABLED`, `DEPRECATED` | Deprecation lifecycle |
+| `JBLayer` | `L1`, `L2` | Arbitrum sucker layer identification |
+
+## Gotchas
+
+- `using MerkleLib for MerkleLib.Tree` is NOT inherited by derived contracts -- must redeclare in test harnesses.
+- Suckers are deployed as minimal clones (`LibClone.cloneDeterministic`). The singleton's constructor calls `_disableInitializers()` so it cannot be initialized directly. Only clones can be initialized.
+- For suckers to be peers, the same `salt` AND the same caller address must be used on both chains when calling `deploySuckersFor`. The registry hashes `keccak256(abi.encode(msg.sender, salt))`.
+- `peer()` defaults to `address(this)` -- suckers expect to be deployed at matching addresses on both chains via deterministic deployment.
+- `fromRemote` is `external payable` and does NOT revert on stale nonce or deprecated state -- it silently ignores the update to avoid losing native tokens sent along with the message.
+- `JBCCIPSucker.ccipReceive` calls `this.fromRemote(root)` (external self-call) so that `_isRemotePeer` sees `msg.sender == address(this)` rather than the CCIP router.
+- `_validateTokenMapping` in `JBSucker` enforces that native token (`NATIVE_TOKEN`) can only map to `NATIVE_TOKEN` or `address(0)`. `JBCCIPSucker` overrides this to relax the native token constraint (remote chain may not have native ETH).
+- Emergency hatch is irreversible per-token. Once opened, the token can never be bridged again by that sucker.
+- `setDeprecation` requires the timestamp to be at least `_maxMessagingDelay()` (14 days) in the future. This ensures in-flight messages arrive before the sucker stops accepting them.
+- Deployer `setChainSpecificConstants` and `configureSingleton` are both one-shot functions -- they revert if called twice.
+- `MESSENGER_BASE_GAS_LIMIT` is 300,000. `MESSENGER_ERC20_MIN_GAS_LIMIT` is 200,000. Token mappings must specify `minGas >= 200,000` for ERC-20s.
+- `JBArbitrumSucker` uses `unsafeCreateRetryableTicket` (not `safeCreateRetryableTicket`) to avoid L2 address aliasing of the refund address.
+- The outbox tree tracks `numberOfClaimsSent` separately from `tree.count`. Emergency hatch exit is only available for leaves whose index is `>= numberOfClaimsSent` (not yet sent to remote).
+
+### CRITICAL: NATIVE_TOKEN Mismatch on Non-ETH Chains
+
+`JBConstants.NATIVE_TOKEN` (`0x000...EEEe`) represents whatever is native on the current chain -- ETH on Ethereum/Optimism/Base/Arbitrum, but CELO on Celo, MATIC on Polygon, etc.
+
+**Mapping `NATIVE_TOKEN -> NATIVE_TOKEN` across chains with different native assets is dangerous:**
+
+- The sucker bridges raw amounts without exchange rate conversion
+- 1 CELO bridged as if it were 1 ETH massively overvalues the payment
+- Project issuance (`baseCurrency=1`, i.e. ETH) treats CELO at 1:1 with ETH
+
+**Safe chains** (ETH is native): Ethereum, Optimism, Base, Arbitrum -- `NATIVE_TOKEN -> NATIVE_TOKEN` works correctly.
+
+**Unsafe chains** (non-ETH native): Celo, Polygon, Avalanche, BNB -- use ERC-20 WETH or USDC as the terminal accounting context, NOT `NATIVE_TOKEN`.
+
+**Correct token mapping on Celo:**
+```solidity
+// Map WETH (ERC-20) on Ethereum to WETH (ERC-20) on Celo
+JBTokenMapping({
+    localToken: WETH_ETHEREUM,
+    remoteToken: WETH_CELO,  // 0xD221812de1BD094f35587EE8E174B07B6167D9Af
+    minGas: 200_000,
+    minBridgeAmount: 0.01 ether
+})
+```
+
+**Wrong token mapping on Celo:**
+```solidity
+// NATIVE_TOKEN on Ethereum is ETH, but on Celo it's CELO!
+JBTokenMapping({
+    localToken: JBConstants.NATIVE_TOKEN,
+    remoteToken: JBConstants.NATIVE_TOKEN,  // WRONG on non-ETH chains
+    minGas: 200_000,
+    minBridgeAmount: 0.01 ether
+})
+```
+
+See also: `SECURITY.md` in this repo and INTEROP-6 in `AUDIT_FINDINGS.md`.
+
+## Example Integration
+
+```solidity
+// Deploy suckers for project 12 using CCIP to bridge ETH between Ethereum and Optimism
+JBTokenMapping[] memory mappings = new JBTokenMapping[](1);
+mappings[0] = JBTokenMapping({
+    localToken: JBConstants.NATIVE_TOKEN,
+    minGas: 200_000,
+    remoteToken: JBConstants.NATIVE_TOKEN,
+    minBridgeAmount: 0.025 ether
+});
+
+JBSuckerDeployerConfig[] memory configs = new JBSuckerDeployerConfig[](1);
+configs[0] = JBSuckerDeployerConfig({
+    deployer: IJBSuckerDeployer(ccipSuckerDeployerAddress),
+    mappings: mappings
+});
+
+// Must use the same salt and caller on both chains
+bytes32 salt = keccak256("my-project-suckers-v1");
+address[] memory suckers = registry.deploySuckersFor(12, salt, configs);
+
+// Grant the sucker MINT_TOKENS permission so it can mint on claim
+uint256[] memory permissionIds = new uint256[](1);
+permissionIds[0] = JBPermissionIds.MINT_TOKENS;
+permissions.setPermissionsFor(
+    projectOwner,
+    JBPermissionsData({
+        operator: suckers[0],
+        projectId: 12,
+        permissionIds: permissionIds
+    })
+);
+```