@bananapus/suckers-v6 0.0.20 → 0.0.22

package/ADMINISTRATION.md

@@ -2,6 +2,35 @@
 
 Admin privileges and their scope in nana-suckers-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Cross-chain bridge deployment, token mapping, deprecation, emergency hatch controls, and layer-specific bridge configurator setup. |
+| Operators | Registry owner, project owners and delegates, sucker deployers, token mappers, safety admins, deprecation admins, and one-time bridge configurators. |
+| Highest-risk actions | Mapping the wrong remote token, enabling an emergency hatch, setting deprecation, or misconfiguring bridge singletons and chain constants. |
+| Recovery posture | The normal recovery path is to deploy or registry-enable a new sucker/deployer and migrate traffic; several safety actions are intentionally irreversible. |
+
+## Routine Operations
+
+- Allow only the sucker deployer implementations you are prepared to support operationally on the registry side.
+- Map remote tokens carefully and early, before outbox activity makes mistakes harder to unwind.
+- Use deprecation timestamps to create a safe runway for shutdown rather than trying to disable a bridge abruptly.
+- Treat emergency hatch activation as a last-resort safety action when the normal bridge path is no longer trustworthy.
+- Verify one-time deployer configuration (`configureSingleton`, `setChainSpecificConstants`) before using a deployer in production.
+
+## One-Way Or High-Risk Actions
+
+- `enableEmergencyHatchFor` is irreversible for the affected token mapping.
+- Once a sucker reaches `SENDING_DISABLED` or `DEPRECATED`, the lifecycle cannot be reversed.
+- Deployer singleton and chain-specific constant configuration are one-time setup operations.
+- A bad token mapping can strand users or route liquidity to the wrong remote asset.
+
+## Recovery Notes
+
+- If a bridge path is unhealthy, prefer deprecating the affected sucker and standing up a replacement rather than forcing traffic through a degraded route.
+- If a token is emergency-hatched, users recover through the documented exit flow; you cannot simply re-enable the old path afterward.
+
 ## Roles
 
 ### Registry Owner
@@ -28,6 +57,8 @@ Admin privileges and their scope in nana-suckers-v6.
 - **Scope:** Can map or disable local-to-remote token pairs on a specific sucker.
 - **Permission ID:** `JBPermissionIds.MAP_SUCKER_TOKEN`
 
+For existing-project deployments, this permission is part of the same operational path as `DEPLOY_SUCKERS`: the registry deploys the sucker and then immediately calls `mapTokens` on it. If the project delegates deployment without arranging mapping authority for the registry, the single deployment transaction will revert during configuration.
+
 ### Safety Admin (delegated role)
 
 - **How assigned:** Granted `SUCKER_SAFETY` permission by the project owner via `JBPermissions`.
@@ -56,17 +87,17 @@ Admin privileges and their scope in nana-suckers-v6.
 | `allowSuckerDeployers(deployers)` | Registry Owner | N/A (`onlyOwner`) | Global | Batch version: adds multiple deployer contracts to the allowlist. |
 | `removeSuckerDeployer(deployer)` | Registry Owner | N/A (`onlyOwner`) | Global | Removes a deployer contract from the allowlist, preventing future sucker deployments through it. |
 | `setToRemoteFee(fee)` | Registry Owner | N/A (`onlyOwner`) | Global | Sets the `toRemoteFee` applied to all suckers. The fee must be <= `MAX_TO_REMOTE_FEE` (0.001 ether). Emits `ToRemoteFeeChanged`. |
-| `deploySuckersFor(projectId, salt, configs)` | Project Owner | `DEPLOY_SUCKERS` | Per-project | Deploys one or more suckers for a project using allowlisted deployers. Hashes salt with `_msgSender()` (which equals `msg.sender` for direct calls, or the relayed sender for ERC-2771 meta-transactions) for deterministic cross-chain addresses. Also calls `mapTokens` on each newly created sucker. |
+| `deploySuckersFor(projectId, salt, configs)` | Project owner or delegate | `DEPLOY_SUCKERS` | Per-project | Deploys one or more suckers for a project using allowlisted deployers. Hashes salt with `_msgSender()` (which equals `msg.sender` for direct calls, or the relayed sender for ERC-2771 meta-transactions) for deterministic cross-chain addresses. Also calls `mapTokens` on each newly created sucker, so the registry must be able to satisfy the corresponding `MAP_SUCKER_TOKEN` checks for the project. |
 | `removeDeprecatedSucker(projectId, sucker)` | Anyone | None | Per-project | Removes a fully `DEPRECATED` sucker from the registry. Permissionless but only succeeds if the sucker is in the `DEPRECATED` state. |
 
 ### JBSucker
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|--------------|
-| `mapToken(map)` | Project Owner | `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. |
+| `mapToken(map)` | Project owner or delegate | `MAP_SUCKER_TOKEN` | Per-sucker | Maps a local terminal token to a remote token, enabling bridging. Setting `remoteToken` to `bytes32(0)` disables bridging and sends a final root to flush remaining outbox entries. |
+| `mapTokens(maps)` | Project owner or delegate | `MAP_SUCKER_TOKEN` | Per-sucker | Batch version: maps multiple local-to-remote token pairs. Each mapping requires the same permission. |
+| `enableEmergencyHatchFor(tokens)` | Project owner or delegate | `SUCKER_SAFETY` | Per-sucker | Opens the emergency hatch for specified tokens (irreversible). Sets `emergencyHatch = true` and `enabled = false` on each token's remote mapping. Allows users to exit through the outbox on the chain they deposited on. |
+| `setDeprecation(timestamp)` | Project owner or delegate | `SET_SUCKER_DEPRECATION` | Per-sucker | Sets the timestamp after which the sucker becomes fully deprecated. Must be at least `_maxMessagingDelay()` (14 days) in the future. Set to `0` to cancel a pending deprecation. Reverts if already in `SENDING_DISABLED` or `DEPRECATED` state. |
 
 ### JBSuckerDeployer (base and all subclasses)
 

package/ARCHITECTURE.md

@@ -1,121 +1,60 @@
-# nana-suckers-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Cross-chain token bridging for Juicebox V6. Allows project tokens and funds to move between EVM chains via Optimism, Base, Celo (OP Stack), Arbitrum, and Chainlink CCIP bridges. Uses dual merkle trees (outbox/inbox) for claim verification.
+`nana-suckers-v6` moves Juicebox project token value across chains. A sucker pair lets a holder burn or cash out locally, bridge the resulting terminal token plus the latest merkle root, and then claim equivalent project-token value on the remote chain.
 
-## Contract Map
+## Boundaries
 
-```
-src/
-├── JBSucker.sol            — Abstract base: merkle tree management, prepare/claim logic, FEE_PROJECT_ID, reads toRemoteFee from REGISTRY (immutable IJBSuckerRegistry)
-├── JBOptimismSucker.sol    — OP Stack bridge implementation (Optimism, Base, Celo)
-├── JBBaseSucker.sol        — Base chain sucker (extends JBOptimismSucker, overrides peerChainId for Base ↔ Ethereum)
-├── JBCeloSucker.sol        — Celo sucker (extends JBOptimismSucker, wraps ETH → WETH for bridging, custom gas token handling)
-├── JBArbitrumSucker.sol    — Arbitrum bridge implementation
-├── JBCCIPSucker.sol        — Chainlink CCIP bridge implementation
-├── JBSuckerRegistry.sol    — Registry of suckers per project, deployment permissions, centralized toRemoteFee (owner-controlled, applies to all suckers)
-├── deployers/
-│   ├── JBSuckerDeployer.sol        — Abstract base deployer (LibClone, singleton pattern)
-│   ├── JBOptimismSuckerDeployer.sol
-│   ├── JBBaseSuckerDeployer.sol
-│   ├── JBCeloSuckerDeployer.sol
-│   ├── JBArbitrumSuckerDeployer.sol
-│   └── JBCCIPSuckerDeployer.sol
-├── enums/
-│   ├── JBSuckerState.sol   — ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
-│   └── JBLayer.sol         — L1 / L2 indicator (used by JBArbitrumSucker)
-├── interfaces/             — IJBSucker, IJBSuckerRegistry, IJBSuckerDeployer, bridge-specific interfaces (OP, Arb, CCIP)
-├── libraries/
-│   ├── ARBAddresses.sol    — Arbitrum precompile/contract addresses
-│   ├── ARBChains.sol       — Arbitrum chain ID constants
-│   └── CCIPHelper.sol      — CCIP chain selector lookups
-├── structs/                — JBClaim, JBLeaf, JBTokenMapping, JBRemoteToken, JBOutboxTree, JBMessageRoot, etc.
-└── utils/
-    └── MerkleLib.sol       — Append-only merkle tree operations
-```
+- `JBSucker` owns the chain-agnostic lifecycle.
+- Chain-specific subclasses own transport details for OP Stack, Arbitrum, CCIP, and Celo variants.
+- The registry and deployers own pair creation and global policy.
+- Core protocol accounting still happens through project terminals on each chain.
 
-## Key Data Flows
+## Main Components
 
-### Outbound (Prepare + Bridge)
-```
-User → JBSucker.prepare()
-  → Cash out project tokens (0% tax via sucker privilege)
-  → Insert {beneficiary, token, amount} into outbox merkle tree
-
-User → JBSucker.toRemote{value}(token)
-  → Pay toRemoteFee (ETH) to fee project via terminal.pay() — caller gets fee project tokens
-  → Remaining msg.value forwarded as transport payment to the bridge
-  → Send merkle root + bridged tokens to remote sucker via OP/Arb/CCIP messenger
-```
+| Component | Responsibility |
+| --- | --- |
+| `JBSucker` | Prepare, root management, claim verification, token mapping, and deprecation controls |
+| chain-specific suckers | Bridge transport and token-wrapping details for each supported network family |
+| `JBSuckerRegistry` | Tracks deployed suckers, allowlists deployers, and stores global bridge-fee policy |
+| deployers | Clone and initialize deterministic sucker instances |
+| `MerkleLib` and helper libraries | Incremental tree logic plus chain-specific constants |
 
-The `toRemoteFee` is a global ETH fee (max 0.001 ETH) set by the registry owner via `setToRemoteFee()`. The caller must send at least `toRemoteFee` as `msg.value` (reverts otherwise). The fee is paid into `FEE_PROJECT_ID` (typically project 1) through the project's primary native-token terminal. If the `pay()` call reverts or no terminal exists, the fee is silently added to the transport payment instead (best-effort).
+## Runtime Model
 
-### Inbound (Claim)
-```
-Remote root arrives → stored in inbox tree
-User → JBSucker.claim(proof)
-  → Check leaf not already claimed (bitmap), mark as executed
-  → Verify merkle proof against inbox root
-  → Add bridged terminal tokens to project balance (via terminal.addToBalanceOf)
-  → Mint project tokens to beneficiary (via controller.mintTokensOf)
+```text
+holder prepares a bridge
+  -> sucker cashes out or consumes the local project-token position
+  -> sucker inserts a merkle leaf into the outbox tree
+  -> someone bridges funds and the latest root to the remote sucker
+  -> claimant proves inclusion against the remote inbox tree
+  -> remote sucker releases or remints the destination-side value
 ```
 
-### Deprecation Lifecycle
-```
-ENABLED → DEPRECATION_PENDING → SENDING_DISABLED → DEPRECATED
-  (owner)    (pending period)     (no new outbox)    (fully disabled)
-```
-
-## Token Mapping
-
-Token mappings link a local terminal token to a remote token address, enabling bridging for that pair. Mappings are managed via `mapToken()` / `mapTokens()` (requires `MAP_SUCKER_TOKEN` permission).
-
-**Immutability constraint:** 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 by mapping to `address(0)`. This prevents double-spending: if remapping were allowed after outbox activity, the same local funds could be claimed against two different remote tokens on the remote chain.
-
-A disabled mapping can be re-enabled to the *same* remote token. A misconfigured mapping requires deploying a new sucker.
+## Critical Invariants
 
-When a mapping is disabled (set to `address(0)`) and unsent leaves remain in the outbox, the sucker automatically flushes the remaining root to the remote chain to settle outstanding claims.
+- Inbox and outbox tree updates must remain append-only and proof-compatible across chains.
+- Token mapping is part of bridge correctness; a wrong remote token mapping is a value-loss bug.
+- Deprecation and emergency controls must not compromise already-bridged claims.
+- The chain-specific transport layers may differ, but they must preserve the same logical prepare-to-claim lifecycle.
 
-## Emergency Hatch
+## Where Complexity Lives
 
-The emergency hatch allows users to reclaim their tokens on the chain they deposited on when the bridge is no longer functional.
+- The abstract lifecycle is simple, but every transport backend has its own failure modes and native-token quirks.
+- Tree state, token mapping, and claim replay protection all carry cross-chain blast radius.
+- Registry policy matters because deployment mistakes are hard to repair after pairs exist on multiple chains.
 
-**Who can enable it:** The project owner (or an address with the `SUCKER_SAFETY` permission) calls `enableEmergencyHatchFor(address[] tokens)`.
-
-**What it does:** Sets `emergencyHatch = true` and `enabled = false` for each token's remote mapping. This is irreversible — once the emergency hatch is enabled for a token, it cannot be disabled or remapped.
-
-**How users exit:** Users call `exitThroughEmergencyHatch(JBClaim claimData)` with a merkle proof against the *outbox* tree. The sucker validates:
-1. The emergency hatch is enabled for that token (or the sucker is in `DEPRECATED` / `SENDING_DISABLED` state).
-2. The leaf has not already been sent to the remote chain (`index >= numberOfClaimsSent`). Leaves whose roots were already bridged cannot be emergency-exited, since they could also be claimed remotely.
-3. The leaf has not already been claimed (bitmap check).
-
-The sucker then adds the terminal tokens back to the project's balance (via `terminal.addToBalanceOf`) and mints project tokens to the beneficiary on the local chain.
-
-## 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 |
-
-## Design Decisions
-
-**Dual merkle trees instead of direct bridging.** Each sucker maintains separate outbox and inbox merkle trees per token. Outbound transfers are batched into the outbox tree via `prepare()`, and a single `toRemote()` call bridges the root and accumulated funds together. This amortizes bridge costs across many users — only one cross-chain message per batch rather than one per transfer. The inbox tree on the receiving side lets users self-serve claims with merkle proofs at their own pace.
-
-**Bitmap for claim tracking.** Each leaf index is tracked in an OpenZeppelin `BitMaps.BitMap` (`_executedFor`), which packs 256 booleans per storage slot. This is far cheaper than a `mapping(uint256 => bool)` for dense sequential indices, and the merkle tree's sequential leaf indices are a natural fit.
-
-**Immutable token mappings once outbox has entries.** After a token mapping has been used (outbox tree count > 0), remapping to a different remote token is blocked. Without this, an attacker could prepare tokens mapped to token A, then remap to token B before `toRemote()` is called, allowing the same local funds to be claimed against both tokens on the remote chain. Disabling (mapping to `address(0)`) is still allowed since it flushes remaining outbox entries and stops new ones.
+## Dependencies
 
-**`uint128` amount cap for SVM compatibility.** Both `terminalTokenAmount` and `projectTokenCount` are capped at `type(uint128).max` in `_insertIntoTree()`. This ensures the leaf data is compatible with Solana's SVM, where token amounts are `u64`/`u128`. The `bytes32` beneficiary field similarly accommodates 32-byte Solana public keys alongside 20-byte EVM addresses.
+- `nana-core-v6` terminals and project-token semantics
+- Native bridge infrastructure for OP Stack, Arbitrum, CCIP, and supported variants
+- `nana-permission-ids-v6` for deploy, map, safety, and deprecation permissions
 
-**Best-effort fee payment.** The `toRemoteFee` payment to the fee project is wrapped in a try-catch. If the fee project's terminal doesn't exist or the `pay()` call reverts, the bridge proceeds without the fee. This prevents a misconfigured or paused fee project from blocking all cross-chain transfers.
+## Safe Change Guide
 
-## Dependencies
-- `@bananapus/core-v6` — Terminal, controller, token interfaces
-- `@bananapus/permission-ids-v6` — DEPLOY_SUCKERS, MAP_SUCKER_TOKEN, etc.
-- `@arbitrum/nitro-contracts` — Arbitrum bridge interfaces (IInbox, IOutbox, IBridge, ArbSys, AddressAliasHelper)
-- `@chainlink/contracts-ccip` — CCIP router and message interfaces
-- `@openzeppelin/contracts` — BitMaps, SafeERC20, ERC165, Initializable, ERC2771Context, Ownable, EnumerableMap
-- `solady` — LibClone (deterministic clone deployment for sucker deployers)
+- Review every cross-chain change from both sides of the pair.
+- Do not change merkle leaf encoding casually; proofs and remote compatibility depend on it.
+- Keep registry policy, deployer configuration, and singleton logic aligned.
+- Test chain-specific native-token wrapping paths separately from the abstract lifecycle.
+- Assume bridge-edge behavior is the primary review target, not the happy path.