@bananapus/suckers-v6 0.0.6 → 0.0.8

package/ADMINISTRATION.md

@@ -0,0 +1,162 @@
+# Administration
+
+Admin privileges and their scope in nana-suckers-v6.
+
+## Roles
+
+### Registry Owner
+
+- **How assigned:** Set at `JBSuckerRegistry` construction via the `initialOwner` parameter. Transferable via OpenZeppelin `Ownable`.
+- **Scope:** Controls which sucker deployer contracts are approved for use by the registry. Initially expected to be JuiceboxDAO (project ID 1).
+- **Permission ID:** None (uses `onlyOwner` modifier from OpenZeppelin `Ownable`).
+
+### Project Owner
+
+- **How assigned:** Owner of the ERC-721 project NFT in `JBProjects`. All project-scoped permissions are checked against `PROJECTS.ownerOf(projectId)` or `DIRECTORY.PROJECTS().ownerOf(projectId)`.
+- **Scope:** Controls sucker deployment, token mapping, deprecation, and emergency hatch for their project. Can delegate any of these permissions to other addresses via `JBPermissions`.
+- **Permission ID:** N/A (is the root authority that grants the permission IDs below).
+
+### Sucker Deployer (delegated role)
+
+- **How assigned:** Granted `DEPLOY_SUCKERS` permission by the project owner via `JBPermissions`.
+- **Scope:** Can deploy new suckers for a specific project through the registry.
+- **Permission ID:** `JBPermissionIds.DEPLOY_SUCKERS`
+
+### Token Mapper (delegated role)
+
+- **How assigned:** Granted `MAP_SUCKER_TOKEN` permission by the project owner via `JBPermissions`. Commonly granted to the `JBSuckerRegistry` address so it can call `mapTokens` during deployment.
+- **Scope:** Can map or disable local-to-remote token pairs on a specific sucker.
+- **Permission ID:** `JBPermissionIds.MAP_SUCKER_TOKEN`
+
+### Safety Admin (delegated role)
+
+- **How assigned:** Granted `SUCKER_SAFETY` permission by the project owner via `JBPermissions`.
+- **Scope:** Can open the emergency hatch for specific tokens on a sucker. This is an irreversible action.
+- **Permission ID:** `JBPermissionIds.SUCKER_SAFETY`
+
+### Deprecation Admin (delegated role)
+
+- **How assigned:** Granted `SET_SUCKER_DEPRECATION` permission by the project owner via `JBPermissions`.
+- **Scope:** Can set or cancel the deprecation timestamp on a sucker.
+- **Permission ID:** `JBPermissionIds.SET_SUCKER_DEPRECATION`
+
+### Layer-Specific Configurator
+
+- **How assigned:** Set at deployer construction via the `configurator` parameter. Stored as the immutable `LAYER_SPECIFIC_CONFIGURATOR` address on each `JBSuckerDeployer`.
+- **Scope:** Can call `setChainSpecificConstants` and `configureSingleton` exactly once each on the deployer. These are one-time setup functions that configure bridge-specific addresses (messenger, bridge, router, inbox) and the singleton implementation used for cloning.
+- **Permission ID:** None (uses direct `_msgSender()` check against `LAYER_SPECIFIC_CONFIGURATOR`).
+
+## Privileged Functions
+
+### JBSuckerRegistry
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|--------------|
+| `allowSuckerDeployer(deployer)` | Registry Owner | N/A (`onlyOwner`) | Global | Adds a deployer contract to the allowlist, enabling it to be used when deploying suckers. |
+| `allowSuckerDeployers(deployers)` | Registry Owner | N/A (`onlyOwner`) | Global | Batch version: adds multiple deployer contracts to the allowlist. |
+| `removeSuckerDeployer(deployer)` | Registry Owner | N/A (`onlyOwner`) | Global | Removes a deployer contract from the allowlist, preventing future sucker deployments through it. |
+| `deploySuckersFor(projectId, salt, configs)` | Project Owner | `DEPLOY_SUCKERS` | Per-project | Deploys one or more suckers for a project using allowlisted deployers. Hashes salt with `msg.sender` for deterministic cross-chain addresses. Also calls `mapTokens` on each newly created sucker. |
+| `removeDeprecatedSucker(projectId, sucker)` | Anyone | None | Per-project | Removes a fully `DEPRECATED` sucker from the registry. Permissionless but only succeeds if the sucker is in the `DEPRECATED` state. |
+
+### JBSucker
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|--------------|
+| `mapToken(map)` | Project Owner | `MAP_SUCKER_TOKEN` | Per-sucker | Maps a local terminal token to a remote token, enabling bridging. Setting `remoteToken` to `bytes32(0)` disables bridging and sends a final root to flush remaining outbox entries. |
+| `mapTokens(maps)` | Project Owner | `MAP_SUCKER_TOKEN` | Per-sucker | Batch version: maps multiple local-to-remote token pairs. Each mapping requires the same permission. |
+| `enableEmergencyHatchFor(tokens)` | Project Owner | `SUCKER_SAFETY` | Per-sucker | Opens the emergency hatch for specified tokens (irreversible). Sets `emergencyHatch = true` and `enabled = false` on each token's remote mapping. Allows users to exit through the outbox on the chain they deposited on. |
+| `setDeprecation(timestamp)` | Project Owner | `SET_SUCKER_DEPRECATION` | Per-sucker | Sets the timestamp after which the sucker becomes fully deprecated. Must be at least `_maxMessagingDelay()` (14 days) in the future. Set to `0` to cancel a pending deprecation. Reverts if already in `SENDING_DISABLED` or `DEPRECATED` state. |
+
+### JBSuckerDeployer (base and all subclasses)
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|--------------|
+| `configureSingleton(singleton)` | Layer-Specific Configurator | N/A (direct address check) | Per-deployer | Sets the singleton implementation contract used to clone suckers via `LibClone`. Can only be called once. |
+| `setChainSpecificConstants(...)` | Layer-Specific Configurator | N/A (direct address check) | Per-deployer | Configures bridge-specific addresses (messenger, bridge, router, inbox, etc.) for the deployer. Can only be called once. Parameters vary by bridge type. |
+
+## Deprecation Lifecycle
+
+The sucker deprecation lifecycle progresses through four states, controlled by `setDeprecation(timestamp)`:
+
+```
+ENABLED --> DEPRECATION_PENDING --> SENDING_DISABLED --> DEPRECATED
+```
+
+| State | Condition | Behavior |
+|-------|-----------|----------|
+| `ENABLED` | `deprecatedAfter == 0` | Fully functional. No deprecation is set. |
+| `DEPRECATION_PENDING` | `block.timestamp < deprecatedAfter - _maxMessagingDelay()` | Fully functional but a warning to users that deprecation is coming. |
+| `SENDING_DISABLED` | `block.timestamp < deprecatedAfter` (but past the messaging delay window) | `prepare()` and `toRemote()` revert. No new outbox entries or root sends. Incoming roots from the remote peer are still accepted. Users can `claim()` incoming tokens and `exitThroughEmergencyHatch()`. |
+| `DEPRECATED` | `block.timestamp >= deprecatedAfter` | Fully shut down. No new inbox roots are accepted (`fromRemote` skips the update). Users can still `claim()` against previously accepted inbox roots and `exitThroughEmergencyHatch()` against outbox entries that were never sent. |
+
+**Who controls transitions:**
+- The project owner (or holder of `SET_SUCKER_DEPRECATION` permission) sets the `deprecatedAfter` timestamp via `setDeprecation(timestamp)`.
+- The timestamp must be at least `_maxMessagingDelay()` (14 days) in the future to allow in-flight messages to arrive.
+- A pending deprecation can be cancelled by calling `setDeprecation(0)`, but only while in `ENABLED` or `DEPRECATION_PENDING` state.
+- Once `SENDING_DISABLED` or `DEPRECATED`, the deprecation cannot be reversed.
+
+**Removing from registry:** Once a sucker reaches `DEPRECATED`, anyone can call `JBSuckerRegistry.removeDeprecatedSucker(projectId, sucker)` to remove it from the project's sucker list.
+
+## Emergency Hatch
+
+The emergency hatch is a per-token escape mechanism for when a bridge becomes non-functional for specific tokens.
+
+**Activation:** The project owner (or holder of `SUCKER_SAFETY` permission) calls `enableEmergencyHatchFor(tokens)` on the sucker. This is irreversible -- once opened for a token, that token can never be bridged by this sucker again.
+
+**Effect:** Sets `emergencyHatch = true` and `enabled = false` on each specified token's `JBRemoteToken` mapping. This:
+- Prevents new `prepare()` calls for the token (the token is no longer mapped/enabled).
+- Prevents `toRemote()` calls for the token (reverts with `JBSucker_TokenHasInvalidEmergencyHatchState`).
+- Prevents `mapToken()` from remapping or re-enabling the token (reverts with `JBSucker_TokenHasInvalidEmergencyHatchState`).
+- Enables `exitThroughEmergencyHatch()` for users whose outbox entries were never sent to the remote peer (entries with `index >= numberOfClaimsSent`).
+
+**Who can exit:** Any user with a valid outbox merkle proof for a leaf that was never sent over the bridge. The exit returns both the project tokens and the terminal tokens that were cashed out during `prepare()`.
+
+**Safety constraint:** Only leaves that were never communicated to the remote peer (i.e., `index >= outbox.numberOfClaimsSent`) can be emergency-exited. Leaves already sent over the bridge (index < `numberOfClaimsSent`) cannot be emergency-exited because they may have already been claimed on the remote chain.
+
+## Immutable Configuration
+
+The following values are set at deploy time and cannot be changed:
+
+| Property | Contract | Set By | Description |
+|----------|----------|--------|-------------|
+| `DIRECTORY` | `JBSucker`, `JBSuckerRegistry`, all deployers | Constructor | The Juicebox directory contract. |
+| `TOKENS` | `JBSucker`, all deployers | Constructor | The Juicebox token management contract. |
+| `PROJECTS` | `JBSuckerRegistry` | Derived from `DIRECTORY.PROJECTS()` | The ERC-721 project ownership contract. |
+| `ADD_TO_BALANCE_MODE` | `JBSucker` | Constructor | Whether balance is added on-claim or manually (`ON_CLAIM` or `MANUAL`). |
+| `OPBRIDGE` | `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker` | Constructor (from deployer callback) | The OP Standard Bridge address. |
+| `OPMESSENGER` | `JBOptimismSucker`, `JBBaseSucker`, `JBCeloSucker` | Constructor (from deployer callback) | The OP Cross-Domain Messenger address. |
+| `ARBINBOX` | `JBArbitrumSucker` | Constructor (from deployer callback) | The Arbitrum Inbox address. |
+| `GATEWAYROUTER` | `JBArbitrumSucker` | Constructor (from deployer callback) | The Arbitrum Gateway Router address. |
+| `LAYER` | `JBArbitrumSucker` | Constructor (from deployer callback) | Whether this is an L1 or L2 sucker. |
+| `CCIP_ROUTER` | `JBCCIPSucker` | Constructor (from deployer callback) | The Chainlink CCIP Router address. |
+| `REMOTE_CHAIN_ID` | `JBCCIPSucker` | Constructor (from deployer callback) | The remote chain's chain ID. |
+| `REMOTE_CHAIN_SELECTOR` | `JBCCIPSucker` | Constructor (from deployer callback) | The CCIP chain selector for the remote chain. |
+| `WRAPPED_NATIVE` | `JBCeloSucker` | Constructor (from deployer callback) | The wrapped native token (WETH) on the local chain. |
+| `LAYER_SPECIFIC_CONFIGURATOR` | All deployers | Constructor | The address authorized to call one-time setup functions. |
+| `peer()` | `JBSucker` | Deterministic (defaults to `address(this)` via CREATE2) | The remote peer sucker address. Assumes identical deployment on both chains. |
+| `deployer` | `JBSucker` | Set once in `initialize()` by `msg.sender` | The address that deployed this sucker clone (the deployer contract). |
+| `projectId()` | `JBSucker` | Set once in `initialize()` | The local project ID this sucker serves. |
+| Bridge/messenger/router addresses | All deployers | `setChainSpecificConstants()` (one-time) | Bridge infrastructure addresses, set once by the configurator. |
+| Singleton implementation | All deployers | `configureSingleton()` (one-time) | The singleton contract used as the clone template. |
+
+## Admin Boundaries
+
+What admins **cannot** do:
+
+- **Cannot remap tokens after outbox activity.** Once a token has outbox tree entries (`_outboxOf[token].tree.count != 0`), it cannot be remapped to a different remote token. It can only be disabled (set to `bytes32(0)`) or re-enabled to the same remote address. This prevents double-spending across two different remote tokens.
+
+- **Cannot reverse an emergency hatch.** Once `enableEmergencyHatchFor` is called for a token, `emergencyHatch` is permanently `true`. The token can never be re-enabled for bridging on this sucker. A new sucker must be deployed if bridging needs to resume.
+
+- **Cannot reverse deprecation past `SENDING_DISABLED`.** Once the sucker enters `SENDING_DISABLED` or `DEPRECATED` state, `setDeprecation()` reverts. The deprecation cannot be cancelled.
+
+- **Cannot bypass bridge security.** Cross-chain message authentication is enforced by each bridge implementation's `_isRemotePeer()` check. The project owner has no way to override this -- only messages from the legitimate remote peer (verified by the OP Messenger, Arbitrum Bridge/Outbox, or CCIP Router) are accepted by `fromRemote()`.
+
+- **Cannot reconfigure deployers.** `setChainSpecificConstants()` and `configureSingleton()` can each only be called once per deployer. Bridge addresses and the singleton implementation are permanent after initial configuration.
+
+- **Cannot steal user funds via emergency hatch.** Emergency exit only returns tokens to the original beneficiary specified in the outbox merkle tree, and only for leaves that were never sent over the bridge (index >= `numberOfClaimsSent`). Leaves already bridged cannot be double-claimed.
+
+- **Cannot claim on behalf of others.** While `claim()` and `exitThroughEmergencyHatch()` are permissionless (anyone can call them), the project tokens are always minted to the beneficiary encoded in the merkle tree leaf, not to the caller.
+
+- **Cannot change the peer address.** The peer is determined by deterministic deployment (CREATE2 with sender-specific salt). There is no admin function to change which remote address is trusted.
+
+- **Cannot change the project ID.** The `projectId` is set once during `initialize()` and is immutable thereafter (enforced by OpenZeppelin `Initializable`).

package/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# nana-suckers-v6 — Architecture
+
+## Purpose
+
+Cross-chain token bridging for Juicebox V6. Allows project tokens and funds to move between EVM chains via Optimism, Arbitrum, and Chainlink CCIP bridges. Uses dual merkle trees (outbox/inbox) for claim verification.
+
+## Contract Map
+
+```
+src/
+├── JBSucker.sol            — Abstract base: merkle tree management, prepare/claim logic
+├── JBBaseSucker.sol        — OP Stack base (Optimism, Base)
+├── JBOptimismSucker.sol    — Optimism/Base bridge implementation
+├── JBArbitrumSucker.sol    — Arbitrum bridge implementation
+├── JBCCIPSucker.sol        — Chainlink CCIP bridge implementation
+├── JBSuckerRegistry.sol    — Registry of suckers per project, deployment permissions
+├── deployers/
+│   ├── JBOptimismSuckerDeployer.sol
+│   ├── JBArbitrumSuckerDeployer.sol
+│   └── JBCCIPSuckerDeployer.sol
+├── enums/
+│   └── JBSuckerState.sol   — ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
+├── libraries/
+│   ├── JBAddressBytes.sol  — Address/bytes32 conversion
+│   └── MerkleLib.sol       — Merkle tree operations
+└── structs/                — Token mappings, sucker pairs, claims
+```
+
+## Key Data Flows
+
+### Outbound (Prepare + Bridge)
+```
+User → JBSucker.prepare()
+  → Cash out project tokens (0% tax via sucker privilege)
+  → Insert {beneficiary, token, amount} into outbox merkle tree
+  → When tree is full or manually triggered:
+    → Bridge tokens via OP/Arb/CCIP messenger
+    → Send merkle root to remote sucker
+```
+
+### Inbound (Claim)
+```
+Remote root arrives → stored in inbox tree
+User → JBSucker.claim(proof)
+  → Verify merkle proof against inbox root
+  → Check leaf not already claimed (bitmap)
+  → Mint project tokens to beneficiary (or transfer bridged tokens)
+  → Mark leaf as executed
+```
+
+### Deprecation Lifecycle
+```
+ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
+  (owner)    (pending period)     (no new outbox)    (fully disabled)
+```
+
+## Extension Points
+
+| Point | Interface | Purpose |
+|-------|-----------|---------|
+| Bridge transport | Chain-specific sucker | OP, Arb, CCIP implementations |
+| Sucker deployer | `IJBSuckerDeployer` | Factory for new suckers |
+| Registry | `IJBSuckerRegistry` | Discovery and access control |
+
+## Dependencies
+- `@bananapus/core-v6` — Terminal, controller, token interfaces
+- `@bananapus/permission-ids-v6` — DEPLOY_SUCKERS, MAP_SUCKER_TOKEN, etc.
+- `@arbitrum/nitro-contracts` — Arbitrum bridge interfaces
+- `@chainlink/contracts-ccip` — CCIP router interfaces
+- `@openzeppelin/contracts` — MerkleProof, SafeERC20
+- `solady` — LibBitmap

package/README.md

@@ -38,6 +38,7 @@ _If you're having trouble understanding this contract, take a look at the [core
 | [`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. Supports Ethereum, Optimism, Base, Arbitrum, Polygon, Avalanche, BNB Chain, and their testnets. |
 | [`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. |
+| [`JBCeloSucker`](src/JBCeloSucker.sol) | Ethereum and Celo | Extends `JBOptimismSucker` for Celo, an OP Stack chain with a custom gas token (CELO, not ETH). Wraps native ETH to WETH before bridging as ERC-20 via the OP Standard Bridge, and unwraps WETH back to native ETH on the receiving end. Allows `NATIVE_TOKEN` to map to ERC-20 addresses. |
 | [`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 and address aliasing. |
 
 Suckers use two [merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) to track project token claims associated with each terminal token they support:
@@ -86,12 +87,14 @@ graph TD;
 | [`JBCCIPSucker`](src/JBCCIPSucker.sol) | Extends `JBSucker`. Bridges via Chainlink CCIP (`ccipSend`/`ccipReceive`). Supports any CCIP-connected chain pair. Wraps native ETH to WETH before bridging (CCIP only transports ERC-20s) and unwraps on the receiving end. Can map `NATIVE_TOKEN` to ERC-20 addresses on the remote chain (unlike OP/Arbitrum suckers). |
 | [`JBOptimismSucker`](src/JBOptimismSucker.sol) | Extends `JBSucker`. Bridges via OP Standard Bridge + OP Messenger. No `msg.value` required for transport. |
 | [`JBBaseSucker`](src/JBBaseSucker.sol) | Thin wrapper around `JBOptimismSucker` with Base chain IDs (Ethereum 1 <-> Base 8453, Sepolia 11155111 <-> Base Sepolia 84532). |
+| [`JBCeloSucker`](src/JBCeloSucker.sol) | Extends `JBOptimismSucker` for Celo (OP Stack, custom gas token CELO). Wraps native ETH → WETH before bridging as ERC-20. Unwraps received WETH → native ETH via `_addToBalance` override. Removes `NATIVE_TOKEN → NATIVE_TOKEN` restriction. Sends messenger messages with `nativeValue = 0` (Celo's native token is CELO, not ETH). |
 | [`JBArbitrumSucker`](src/JBArbitrumSucker.sol) | Extends `JBSucker`. Bridges via Arbitrum Inbox + Gateway Router. Uses `unsafeCreateRetryableTicket` for L1->L2 (to avoid address aliasing of refund address) and `ArbSys.sendTxToL1` for L2->L1. Requires `msg.value` for L1->L2 transport payment. |
 | [`JBSuckerRegistry`](src/JBSuckerRegistry.sol) | Tracks all suckers per project. Manages deployer allowlist (owner-only). Entry point for `deploySuckersFor`. Can remove deprecated suckers via `removeDeprecatedSucker`. |
 | [`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. Gas-optimized with inline assembly for `root()` and `branchRoot()`. |
 | [`CCIPHelper`](src/libraries/CCIPHelper.sol) | CCIP router addresses, chain selectors, and WETH addresses per chain. Covers Ethereum, Optimism, Arbitrum, Base, Polygon, Avalanche, and BNB Chain (mainnet and testnets). |
@@ -232,7 +235,7 @@ Token mappings define which local terminal token corresponds to which remote ter
 - **`remoteToken` is `bytes32`**, not `address` -- this supports cross-VM compatibility (e.g., Solana program addresses). For EVM addresses, left-pad with zeros: `bytes32(uint256(uint160(address)))`.
 - **Immutable once used.** After an outbox tree has entries for a token, the mapping cannot be changed to a different remote token. It can only be disabled (by setting `remoteToken` to `bytes32(0)`), which triggers a final root flush to settle outstanding claims. A disabled mapping can be re-enabled back to the same remote token.
 - **Minimum gas enforcement.** ERC-20 mappings must specify `minGas >= MESSENGER_ERC20_MIN_GAS_LIMIT` (200,000). Native token mappings on the base `JBSucker` do not require minimum gas, but `JBCCIPSucker` requires it for all tokens (because CCIP wraps native to WETH, an ERC-20 transfer).
-- **Native token rules.** On `JBSucker` (OP/Arb), `NATIVE_TOKEN` can only map to `NATIVE_TOKEN` or `bytes32(0)`. `JBCCIPSucker` overrides this to allow `NATIVE_TOKEN` mapping to any remote address (for chains where ETH is an ERC-20).
+- **Native token rules.** On `JBSucker` (OP/Arb), `NATIVE_TOKEN` can only map to `NATIVE_TOKEN` or `bytes32(0)`. `JBCCIPSucker` and `JBCeloSucker` override this to allow `NATIVE_TOKEN` mapping to any remote address (for chains where ETH is an ERC-20).
 - **`minBridgeAmount`** prevents spam by requiring a minimum outbox balance before `toRemote` can be called.
 
 ```solidity
@@ -393,6 +396,7 @@ nana-suckers-v6/
 │   ├── JBCCIPSucker.sol - Chainlink CCIP bridge implementation.
 │   ├── JBOptimismSucker.sol - OP Stack bridge implementation.
 │   ├── JBBaseSucker.sol - Base-specific wrapper around JBOptimismSucker.
+│   ├── JBCeloSucker.sol - Celo-specific wrapper around JBOptimismSucker (custom gas token).
 │   ├── JBArbitrumSucker.sol - Arbitrum bridge implementation.
 │   ├── JBSuckerRegistry.sol - Registry tracking suckers per project.
 │   ├── deployers/ - Deployers for each kind of sucker.

package/RISKS.md

@@ -0,0 +1,48 @@
+# nana-suckers-v6 — Risks
+
+## Trust Assumptions
+
+1. **Bridge Infrastructure** — Trusts OP Stack, Arbitrum, and CCIP bridges to deliver messages and tokens faithfully. Bridge compromise = fund loss.
+2. **Remote Peer** — Each sucker trusts its configured remote peer (the sucker on the other chain). Root messages only accepted from authenticated peer.
+3. **Project Owner** — Can deploy suckers, set token mappings, initiate deprecation, and enable emergency hatch. Full control over cross-chain configuration.
+4. **Core Protocol** — Suckers mint tokens via JBController with special permission (0% cashout tax). Relies on controller to enforce supply rules.
+
+## Known Risks
+
+| Risk | Description | Mitigation |
+|------|-------------|------------|
+| Token mapping immutability | Once outbox tree has entries, token mapping cannot be changed (only disabled) | Verify mappings before first bridge operation |
+| Emergency hatch abuse | Project owner can enable emergency hatch instantly (no timelock) to recover stuck tokens | Trust assumption on project owner |
+| CCIP amount validation skip | Amount validation intentionally skipped (M-28) to prevent token lockup | Accepted risk to avoid permanent fund lock |
+| Bridge liveness | If bridge goes down, tokens in transit are stuck until bridge recovers | Use deprecation lifecycle; emergency hatch for recovery |
+| Surplus fragmentation | Cash-out bonding curve on each chain only sees that chain's surplus | Users must bridge to chain with more surplus for fair cash-out |
+
+## INTEROP-6: Cross-Chain NATIVE_TOKEN Semantic Divergence
+
+**Severity:** Medium
+**Status:** Acknowledged — by design
+
+`JBConstants.NATIVE_TOKEN` represents different real-world assets on different chains (ETH on Ethereum/OP/Base/Arbitrum, CELO on Celo, MATIC on Polygon). When a project maps `NATIVE_TOKEN → NATIVE_TOKEN` across chains where the native token differs, the protocol treats different assets as equivalent.
+
+**Impact:**
+- Issuance mispricing — payments in non-ETH native tokens priced as ETH without a price feed
+- Sucker bridging failure — incompatible token operations on non-ETH chains
+- Surplus fragmentation — bonding curve only sees local chain surplus
+
+**Safe chains:** Ethereum, Optimism, Base, Arbitrum (all ETH-native)
+**Affected chains:** Celo (CELO), Polygon (MATIC), Avalanche (AVAX), BNB Chain (BNB)
+
+**Mitigation:** On non-ETH chains, use WETH ERC20 as accounting context and map `WETH → WETH` instead of `NATIVE_TOKEN → NATIVE_TOKEN`.
+
+## Privileged Roles
+
+| Role | Permission IDs | Scope |
+|------|---------------|-------|
+| Project owner | `DEPLOY_SUCKERS`, `MAP_SUCKER_TOKEN`, `SUCKER_SAFETY`, `SET_SUCKER_DEPRECATION` | Per-project |
+| Remote peer | Sends merkle roots, triggers claims | Per-sucker-pair |
+| Bridge messenger | Delivers cross-chain messages | Infrastructure |
+
+## Deprecation Lifecycle
+- `ENABLED` → `DEPRECATION_PENDING` → `SENDING_DISABLED` → `DEPRECATED`
+- Each state progressively restricts operations
+- No way to re-enable once deprecated (intentional)

package/SKILLS.md

@@ -12,12 +12,14 @@ Cross-chain token and fund bridging for Juicebox V6 projects, using merkle trees
 | `JBCCIPSucker` | CCIP bridge implementation. Implements `IAny2EVMMessageReceiver.ccipReceive`. Wraps native ETH to WETH before bridging (CCIP only transports ERC-20s), unwraps on receive. Overrides `_validateTokenMapping` to allow `NATIVE_TOKEN` mapping to ERC-20 addresses (for chains where ETH is not native). Refunds excess transport payment after `ccipSend` via low-level call (does not revert on refund failure). |
 | `JBOptimismSucker` | OP Stack bridge implementation. Uses `IOPMessenger.sendMessage` for merkle roots and `IOPStandardBridge.bridgeERC20To` for ERC-20s. No transport payment required (`msg.value` must be 0 for ERC-20 bridging). Native tokens are sent as `msg.value` on `sendMessage`. |
 | `JBBaseSucker` | Extends `JBOptimismSucker` with Base<->Ethereum chain ID mapping (1<->8453, 11155111<->84532). |
+| `JBCeloSucker` | 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` | Arbitrum bridge implementation. Uses `unsafeCreateRetryableTicket` for L1->L2 (avoids address aliasing of refund address), `ArbSys.sendTxToL1` for L2->L1. Uses `IArbL1GatewayRouter.outboundTransferCustomRefund` for L1->L2 ERC-20 bridging, `IArbL2GatewayRouter.outboundTransfer` for L2->L1. Requires `msg.value` for L1->L2 transport. Verifies remote peer via Arbitrum bridge outbox on L1, via `AddressAliasHelper` on L2. |
 | `JBSuckerRegistry` | Entry point for deploying and tracking suckers. Manages deployer allowlist (owner-only). Requires `DEPLOY_SUCKERS` permission to deploy. Tracks suckers via `EnumerableMap`. Can remove deprecated suckers via `removeDeprecatedSucker` (callable by anyone). |
 | `JBSuckerDeployer` | Abstract deployer base. Uses Solady `LibClone.cloneDeterministic` to deploy suckers as minimal proxies. Two-phase setup: `setChainSpecificConstants` (bridge addresses) then `configureSingleton` (sucker implementation). Both are one-shot calls restricted to `LAYER_SPECIFIC_CONFIGURATOR`. |
 | `JBCCIPSuckerDeployer` | CCIP-specific deployer. Stores `ccipRouter` (`ICCIPRouter`), `ccipRemoteChainId` (`uint256`), `ccipRemoteChainSelector` (`uint64`). |
 | `JBOptimismSuckerDeployer` | OP-specific deployer. Stores `opMessenger` (`IOPMessenger`), `opBridge` (`IOPStandardBridge`). |
 | `JBBaseSuckerDeployer` | Thin wrapper around `JBOptimismSuckerDeployer` for separate Base artifact. |
+| `JBCeloSuckerDeployer` | Extends `JBOptimismSuckerDeployer` with `wrappedNative` (`IWrappedNativeToken`) for the local chain's WETH. Extended `setChainSpecificConstants` accepts messenger, bridge, and wrapped native token. |
 | `JBArbitrumSuckerDeployer` | Arbitrum-specific deployer. Stores `arbInbox` (`IInbox`), `arbGatewayRouter` (`IArbGatewayRouter`), `arbLayer` (`JBLayer`). |
 | `MerkleLib` | Incremental merkle tree (depth 32, max 2^32 - 1 leaves). `insert` appends leaves, `root` computes current root (gas-optimized assembly), `branchRoot` verifies proofs (assembly). Modeled on eth2 deposit contract. |
 
@@ -105,7 +107,7 @@ Cross-chain token and fund bridging for Juicebox V6 projects, using merkle trees
 - `peer()` defaults to `bytes32(uint256(uint160(address(this))))` -- suckers expect to be deployed at matching addresses on both chains via deterministic deployment. Can be overridden for cross-VM peers (e.g., Solana PDA addresses).
 - `fromRemote` is `external payable` and does NOT revert on stale nonce or deprecated state -- it silently ignores the update and emits `StaleRootRejected` 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 `bytes32(0)`. `JBCCIPSucker` overrides this to only enforce minimum gas (allowing `NATIVE_TOKEN` to map to any remote address since the remote chain may not have native ETH).
+- `_validateTokenMapping` in `JBSucker` enforces that native token (`NATIVE_TOKEN`) can only map to `NATIVE_TOKEN` or `bytes32(0)`. `JBCCIPSucker` and `JBCeloSucker` override this to only enforce minimum gas (allowing `NATIVE_TOKEN` to map to any remote address since the 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. The invariant is: if `emergencyHatch == true` then `enabled == false`.
 - `setDeprecation` requires the timestamp to be at least `_maxMessagingDelay()` (14 days) in the future. Once in `SENDING_DISABLED` or `DEPRECATED` state, deprecation cannot be modified.
 - Deployer `setChainSpecificConstants` and `configureSingleton` are both one-shot functions -- they revert if called twice.