@bananapus/suckers-v6 0.0.9 → 0.0.11

package/ADMINISTRATION.md

@@ -7,7 +7,7 @@ Admin privileges and their scope in nana-suckers-v6.
 ### 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).
+- **Scope:** Controls which sucker deployer contracts are approved for use by the registry, and sets the global `toRemoteFee` applied to all suckers. Initially expected to be JuiceboxDAO (project ID 1).
 - **Permission ID:** None (uses `onlyOwner` modifier from OpenZeppelin `Ownable`).
 
 ### Project Owner
@@ -55,6 +55,7 @@ Admin privileges and their scope in nana-suckers-v6.
 | `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. |
+| `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 `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. |
 
@@ -120,9 +121,11 @@ 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. |
+| `FEE_PROJECT_ID` | `JBSucker` | Constructor | The project that receives `toRemoteFee` payments via `terminal.pay()` on each `toRemote()` call. Typically project ID 1 (the protocol project). Best-effort: fee is silently skipped if the fee project has no native token terminal or if `terminal.pay()` reverts. |
+| `REGISTRY` | `JBSucker` | Constructor | The `JBSuckerRegistry` that this sucker reads the `toRemoteFee` from. |
+| `MAX_TO_REMOTE_FEE` | `JBSuckerRegistry` | Constant | Hard cap on what `toRemoteFee` can be set to (0.001 ether). Prevents the registry owner from setting an excessively high fee. |
 | `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. |
@@ -160,3 +163,7 @@ What admins **cannot** do:
 - **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`).
+
+- **Cannot change the fee project.** `FEE_PROJECT_ID` is set at construction and is immutable. If the fee project's terminal changes or is removed, fee payments silently stop (best-effort design), but `toRemote()` still works.
+
+- **Can adjust the fee amount, within bounds.** The registry owner can call `setToRemoteFee()` on `JBSuckerRegistry` to adjust the fee globally for all suckers, but it is capped at `MAX_TO_REMOTE_FEE` (0.001 ether).

package/ARCHITECTURE.md

@@ -8,12 +8,12 @@ Cross-chain token bridging for Juicebox V6. Allows project tokens and funds to m
 
 ```
 src/
-├── JBSucker.sol            — Abstract base: merkle tree management, prepare/claim logic
+├── JBSucker.sol            — Abstract base: merkle tree management, prepare/claim logic, FEE_PROJECT_ID, reads toRemoteFee from REGISTRY (immutable IJBSuckerRegistry)
 ├── 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
+├── JBSuckerRegistry.sol    — Registry of suckers per project, deployment permissions, centralized toRemoteFee (owner-controlled, applies to all suckers)
 ├── deployers/
 │   ├── JBOptimismSuckerDeployer.sol
 │   ├── JBArbitrumSuckerDeployer.sol

package/AUDIT_INSTRUCTIONS.md

@@ -0,0 +1,302 @@
+# Audit Instructions
+
+You are auditing the Juicebox V6 suckers -- a cross-chain bridging system that lets project token holders move their tokens between chains by cashing out on one chain and minting on another. Dual incremental merkle trees (outbox on source, inbox on destination) track token movements, with chain-specific bridges (OP Stack, Arbitrum, CCIP) transporting the merkle roots and backing assets. Your goal is to find bugs that enable double-claiming, lose bridged funds, or bypass the deprecation lifecycle.
+
+Read [RISKS.md](./RISKS.md) for known risks and trust assumptions. Then come back here.
+
+## Scope
+
+**In scope -- all Solidity in `src/`:**
+```
+src/JBSucker.sol                        # Abstract base (~1,196 lines)
+src/JBOptimismSucker.sol                # OP Stack bridge implementation (~141 lines)
+src/JBBaseSucker.sol                    # Base (OP Stack variant) (~48 lines)
+src/JBCeloSucker.sol                    # Celo (OP Stack + WETH wrapping) (~196 lines)
+src/JBArbitrumSucker.sol                # Arbitrum bridge implementation (~322 lines)
+src/JBCCIPSucker.sol                    # Chainlink CCIP implementation (~306 lines)
+src/JBSuckerRegistry.sol                # Deployer registry and tracking (~260 lines)
+src/deployers/                          # JBSuckerDeployer, JB{Optimism,Base,Celo,Arbitrum,CCIP}SuckerDeployer
+src/utils/MerkleLib.sol                 # Incremental merkle tree (eth2-style) (~1,030 lines)
+src/structs/                            # JBMessageRoot, JBLeaf, JBClaim, JBOutboxTree, etc.
+src/enums/                              # JBSuckerState, JBLayer
+src/libraries/                          # ARBChains, ARBAddresses, CCIPHelper
+```
+
+**Out of scope:** Test files (`test/`), OpenZeppelin/Arbitrum/CCIP dependencies (assume correct), forge-std.
+
+## Architecture
+
+### JBSucker (src/JBSucker.sol) -- Abstract Base
+
+The core bridging logic. Each sucker instance is associated with one project and deployed as a clone via `Initializable`. Suckers are deployed in pairs (one per chain) with matching CREATE2 addresses so `peer()` returns `_toBytes32(address(this))` by default.
+
+**Immutables:** `DIRECTORY`, `TOKENS`.
+
+**Key state:**
+- `_outboxOf[token]` -- `JBOutboxTree`: merkle tree, balance, nonce, numberOfClaimsSent per token
+- `_inboxOf[token]` -- `JBInboxTreeRoot`: root hash and nonce per token
+- `_remoteTokenFor[token]` -- `JBRemoteToken`: remote address, enabled flag, emergency hatch, min gas, min bridge amount
+- `_executedFor[token]` -- `BitMap`: tracks which leaf indices have been claimed (prevents double-spend)
+- `deprecatedAfter` -- timestamp for deprecation lifecycle
+
+**Key functions:**
+- `initialize(projectId)` -- One-time initialization of the clone with the project ID.
+- `prepare(projectTokenCount, beneficiary, minTokensReclaimed, token)` -- Cash out project tokens, insert a leaf into the outbox merkle tree.
+- `toRemote(token)` -- Send the outbox root and backing assets to the remote chain via the bridge.
+- `fromRemote(JBMessageRoot)` -- Receive a merkle root from the remote peer. Only callable by the authenticated bridge messenger.
+- `claim(JBClaim)` / `claim(JBClaim[])` -- Verify a merkle proof against the inbox root and mint project tokens for the beneficiary.
+- `mapToken(JBTokenMapping)` / `mapTokens(JBTokenMapping[])` -- Map local tokens to remote tokens. Requires `MAP_SUCKER_TOKEN` permission.
+- `exitThroughEmergencyHatch(JBClaim)` -- Reclaim tokens locally when the bridge is broken. Validates against the outbox tree (not inbox).
+- `enableEmergencyHatchFor(address[])` -- Project owner enables emergency exit for specific tokens. Requires `SUCKER_SAFETY` permission.
+- `setDeprecation(uint40 timestamp)` -- Set or clear the deprecation timestamp. Requires `SET_SUCKER_DEPRECATION` permission.
+
+**Key internal functions:**
+- `_insertIntoTree(projectTokenCount, token, terminalTokenAmount, beneficiary)` -- Builds leaf hash, inserts into outbox merkle tree, updates balance.
+- `_validate(projectTokenCount, terminalToken, terminalTokenAmount, beneficiary, index, leaves)` -- Verifies merkle proof against inbox root, marks leaf as executed in bitmap.
+- `_validateForEmergencyExit(...)` -- Validates against outbox root, checks `numberOfClaimsSent` bounds, uses separate bitmap slot.
+- `_validateBranchRoot(expectedRoot, ...)` -- Computes `MerkleLib.branchRoot()` and compares to expected root.
+- `_sendRoot(transportPayment, token, remoteToken)` -- Builds `JBMessageRoot`, clears outbox balance, increments nonce, delegates to `_sendRootOverAMB()`.
+- `_pullBackingAssets(projectToken, count, token, minTokensReclaimed)` -- Cashes out project tokens via the primary terminal.
+- `_handleClaim(terminalToken, terminalTokenAmount, projectTokenAmount, beneficiary)` -- Adds terminal tokens to balance and mints project tokens for beneficiary.
+- `_mapToken(map, transportPaymentValue)` -- Token mapping with immutability enforcement (cannot remap once outbox has entries).
+- `_addToBalance(token, amount)` -- Adds terminal tokens to the project's balance via the primary terminal.
+- `_isRemotePeer(sender)` -- Abstract. Verifies the caller is the authenticated bridge messenger representing the remote peer.
+- `_sendRootOverAMB(...)` -- Abstract. Chain-specific bridge logic.
+
+### JBOptimismSucker (src/JBOptimismSucker.sol)
+
+OP Stack implementation. Uses `IOPMessenger` for messages and `IOPStandardBridge` for token bridging.
+
+- `_isRemotePeer(sender)`: Checks `sender == OPMESSENGER && OPMESSENGER.xDomainMessageSender() == peer()`.
+- `_sendRootOverAMB(...)`: Bridges ERC-20 via `OPBRIDGE.bridgeERC20To()`, sends message via `OPMESSENGER.sendMessage()`. Native ETH sent as `msg.value` on the messenger call. Transport payment must be 0 (OP bridge is free).
+
+### JBBaseSucker (src/JBBaseSucker.sol)
+
+Extends `JBOptimismSucker` with Base chain ID mappings. Same bridge logic.
+
+### JBCeloSucker (src/JBCeloSucker.sol)
+
+Extends `JBOptimismSucker` for Celo (OP Stack chain with CELO as native gas token, not ETH).
+
+- Wraps native ETH to WETH before bridging as ERC-20.
+- Removes the `NATIVE_TOKEN -> NATIVE_TOKEN` restriction so native ETH can map to a remote ERC-20.
+- `_addToBalance()` override: unwraps WETH -> native ETH before adding to project balance.
+- Messenger message sent with `nativeValue = 0` (no ETH attached on Celo).
+
+### JBArbitrumSucker (src/JBArbitrumSucker.sol)
+
+Arbitrum implementation. Uses `IInbox` for retryable tickets and `IArbGatewayRouter` for token bridging.
+
+- `_isRemotePeer(sender)`:
+  - **L1 side**: Checks `sender == ARBINBOX.bridge() && IOutbox(bridge.activeOutbox()).l2ToL1Sender() == peer()`.
+  - **L2 side**: Checks `sender == AddressAliasHelper.applyL1ToL2Alias(peer())`.
+- `_sendRootOverAMB(...)`:
+  - **L1 -> L2**: Creates two independent retryable tickets (one for ERC-20 bridge, one for merkle root message). Non-atomic: tickets are redeemed independently on L2 with no guaranteed ordering. `_addToBalance` checks actual token balance to prevent unbacked minting when message arrives before tokens.
+  - **L2 -> L1**: Uses `ArbSys.sendTxToL1()` for message, `IArbL2GatewayRouter.outboundTransfer()` for tokens.
+- Transport payment required from L1 (covers retryable ticket gas).
+
+### JBCCIPSucker (src/JBCCIPSucker.sol)
+
+Chainlink CCIP implementation. Uses `ICCIPRouter` for cross-chain messaging with token transfer.
+
+- `_isRemotePeer(sender)`: Checks `sender == address(this)` (CCIP calls `ccipReceive` which then calls `this.fromRemote()`).
+- `ccipReceive(Client.Any2EVMMessage)`: Entry point from CCIP router. Validates `msg.sender == CCIP_ROUTER`, `origin == peer()`, `sourceChainSelector == REMOTE_CHAIN_SELECTOR`. Unwraps WETH to ETH when `root.token == NATIVE_TOKEN`. Calls `this.fromRemote(root)`.
+- `_sendRootOverAMB(...)`: Wraps native ETH to WETH (CCIP only transports ERC-20s). Builds `Client.EVM2AnyMessage`, gets fee quote, calls `CCIP_ROUTER.ccipSend{value: fees}()`. Refunds excess transport payment (best-effort, does not revert on failure).
+- Amount validation intentionally skipped (CCIP guarantees delivery). Reverting on mismatch would lock tokens.
+
+### JBSuckerRegistry (src/JBSuckerRegistry.sol)
+
+Manages sucker deployment and tracking.
+
+**Key functions:**
+- `deploySuckersFor(projectId, salt, configurations[])` -- Deploys suckers via allowed deployers. Requires `DEPLOY_SUCKERS` permission. Salt includes sender address for deterministic cross-chain deployment.
+- `allowSuckerDeployer(deployer)` / `removeSuckerDeployer(deployer)` -- Owner-only allowlist management.
+- `removeDeprecatedSucker(projectId, sucker)` -- Anyone can remove a fully deprecated sucker from the registry.
+- `isSuckerOf(projectId, addr)` -- Check if a sucker belongs to a project.
+- `suckersOf(projectId)` / `suckerPairsOf(projectId)` -- List project suckers with remote peer info.
+
+### MerkleLib (src/utils/MerkleLib.sol)
+
+Incremental merkle tree modeled on the eth2 deposit contract. Depth-32, max `2^32 - 1` leaves.
+
+**Key functions:**
+- `insert(Tree, node)` -- Insert a leaf. Returns updated tree. Reverts if full.
+- `root(Tree storage)` -- Compute the current root from storage (assembly-optimized).
+- `branchRoot(item, branch, index)` -- Compute root from a leaf, proof branch, and index (assembly-optimized). Used for claim verification.
+
+## Key Flows
+
+### Prepare (Bridge Out -- Source Chain)
+
+```
+User calls prepare(projectTokenCount, beneficiary, minTokensReclaimed, token)
+  |
+  +--> Validate: beneficiary != 0, project has ERC-20, token is mapped and enabled, sucker not deprecated
+  +--> Transfer project tokens from user to sucker
+  +--> _pullBackingAssets():
+  |      Cash out project tokens via terminal.cashOutTokensOf()
+  |      Sucker gets 0% cashOutTaxRate (special permission from JBOmnichainDeployer)
+  |      Assert: balance delta matches returned reclaimedAmount
+  |
+  +--> _insertIntoTree():
+  |      Guard: amounts fit in uint128 (SVM compatibility)
+  |      Build leaf hash: keccak256(abi.encode(projectTokenCount, terminalTokenAmount, beneficiary))
+  |      Insert into outbox merkle tree
+  |      Update outbox balance
+  |
+  +--> Emit InsertToOutboxTree(beneficiary, token, hash, index, root, counts)
+```
+
+### Bridge (Transport -- Source Chain)
+
+```
+Anyone calls toRemote(token)
+  |
+  +--> Validate: emergency hatch not enabled, nothing-to-send guard, deduct toRemoteFee (if set, read from JBSuckerRegistry via REGISTRY.toRemoteFee(), set globally by registry owner via setToRemoteFee(), capped at MAX_TO_REMOTE_FEE = 0.001 ether), sucker not deprecated
+  +--> _sendRoot():
+  |      Read outbox tree count and balance
+  |      Clear outbox balance (set to 0)
+  |      Increment nonce
+  |      Compute outbox tree root
+  |      Update numberOfClaimsSent = tree.count
+  |      Build JBMessageRoot(version, remoteToken.addr, amount, JBInboxTreeRoot(nonce, root))
+  |
+  +--> _sendRootOverAMB() [chain-specific]:
+         OP:  bridgeERC20To() + OPMESSENGER.sendMessage()
+         ARB: IArbGatewayRouter.outboundTransfer() + ARBINBOX.createRetryableTicket()
+         CCIP: CCIP_ROUTER.ccipSend() with token amounts
+```
+
+### Claim (Bridge In -- Destination Chain)
+
+```
+Bridge delivers message -> fromRemote(JBMessageRoot) is called
+  |
+  +--> Validate: caller is authenticated remote peer, message version matches
+  +--> If root.remoteRoot.nonce > inbox.nonce && state != DEPRECATED:
+  |      Update inbox root and nonce
+  |
+
+Later, anyone calls claim(JBClaim) for a beneficiary:
+  |
+  +--> _validate():
+  |      Check _executedFor[token].get(index) is false (not already claimed)
+  |      Set _executedFor[token].set(index)
+  |      Build leaf hash from claim data
+  |      Compute root via MerkleLib.branchRoot(hash, proof, index)
+  |      Compare to _inboxOf[token].root -- revert if mismatch
+  |
+  +--> _handleClaim():
+  |      _addToBalance(terminalToken, terminalTokenAmount)
+  |      Mint project tokens for beneficiary via controller.mintTokensOf()
+  |        (useReservedPercent = false -- sucker mints bypass reserved percent)
+```
+
+### Deprecation Lifecycle
+
+```
+ENABLED (normal operation)
+  |  setDeprecation(timestamp) where timestamp > block.timestamp + _maxMessagingDelay()
+  v
+DEPRECATION_PENDING (warning, all operations still work)
+  |  block.timestamp reaches (deprecatedAfter - _maxMessagingDelay)
+  v
+SENDING_DISABLED (prepare and toRemote blocked, claims still work)
+  |  block.timestamp reaches deprecatedAfter
+  v
+DEPRECATED (fromRemote rejects new roots, claims still work, emergency exit works)
+```
+
+## Merkle Tree Proof System
+
+### Outbox Tree Construction
+
+Each `prepare()` call inserts a leaf into the outbox tree:
+
+```
+leaf = keccak256(abi.encode(projectTokenCount, terminalTokenAmount, beneficiary))
+```
+
+The tree is an incremental merkle tree (eth2 deposit contract pattern) with depth 32 and max `2^32 - 1` leaves. Leaves are inserted in order; the tree is append-only.
+
+### Inbox Root Verification
+
+When `fromRemote()` receives a `JBMessageRoot`, it stores the merkle root in `_inboxOf[token].root`. The nonce must be strictly greater than the current inbox nonce (non-sequential ordering is accepted for CCIP compatibility).
+
+### Claim Verification
+
+To claim, a user provides:
+- `JBLeaf`: `(index, beneficiary, projectTokenCount, terminalTokenAmount)`
+- `bytes32[32] proof`: the 32-element merkle proof branch
+
+`_validate()` rebuilds the leaf hash, computes the root via `MerkleLib.branchRoot()`, and compares it to the stored inbox root. The leaf index is marked in a bitmap to prevent double-claiming.
+
+### Emergency Exit Verification
+
+`_validateForEmergencyExit()` validates against the **outbox** tree (not inbox). It additionally checks:
+- Emergency hatch is enabled for the token, OR the sucker is deprecated/sending-disabled.
+- `index >= numberOfClaimsSent` (the leaf was NOT part of a root already sent to the remote peer). This prevents double-spending where a leaf could be claimed on both chains.
+- Uses a separate bitmap slot: `address(bytes20(keccak256(abi.encode(terminalToken))))` to avoid collision with the regular claim bitmap.
+
+## Token Mapping
+
+- **Immutable once outbox has entries**: If `_outboxOf[token].tree.count != 0`, the token can only be disabled (mapped to `bytes32(0)`), not remapped to a different remote token. This prevents double-spending.
+- **Re-enabling supported**: A disabled token (remote = 0) can be re-enabled back to its original remote token.
+- **Disabling triggers root flush**: When mapping to `bytes32(0)` with unsent outbox entries (`numberOfClaimsSent != tree.count`), `_sendRoot()` is called to flush remaining entries before disabling.
+- **Validation**: Base class requires native token to map only to native token or zero. `JBCCIPSucker` and `JBCeloSucker` override this to allow native-to-ERC20 mapping. All implementations enforce `minGas >= MESSENGER_ERC20_MIN_GAS_LIMIT` for ERC-20 tokens.
+
+## Priority Audit Areas
+
+| Priority | Target | Why |
+|----------|--------|-----|
+| 1 | **Merkle proof verification** (`_validate`, `_validateForEmergencyExit`, `MerkleLib.branchRoot`) | Double-claim or invalid-claim is the highest-impact bug. Verify: leaf hash construction matches insertion, bitmap prevents replay, proof verification is correct, emergency exit uses separate bitmap and checks numberOfClaimsSent bounds. |
+| 2 | **fromRemote authentication** (`_isRemotePeer` in each implementation) | If an attacker can call `fromRemote()` with a crafted root, they can mint arbitrary tokens. Verify each bridge's authentication: OP (xDomainMessageSender), Arbitrum (L1 outbox / L2 alias), CCIP (router + origin + chain selector). |
+| 3 | **Token conservation across bridge** | Verify: outbox balance cleared in `_sendRoot()` matches what the bridge transfers, inbox `_handleClaim()` only distributes `terminalTokenAmount` that was actually received. For CCIP: amount validation is intentionally skipped. For Arbitrum L1->L2: two independent retryable tickets create a non-atomic window. |
+| 4 | **Emergency exit safety** | `numberOfClaimsSent` determines which leaves are safe to emergency-exit. Verify: it's updated only in `_sendRoot()`, accurately tracks what was sent, and the `>= index` comparison is correct (count vs 0-based index). |
+| 5 | **Deprecation lifecycle** | State transitions are timestamp-based. Verify: `_maxMessagingDelay()` provides enough time for in-flight messages, `SENDING_DISABLED` blocks `prepare()` and `toRemote()` but allows `claim()` and `fromRemote()`, `DEPRECATED` blocks `fromRemote()` new roots. |
+| 6 | **Token mapping immutability** | Verify: once `_outboxOf[token].tree.count != 0`, remapping to a different remote token reverts. Disabling triggers root flush. Re-enabling back to the same address works. |
+| 7 | **Arbitrum non-atomic bridging** | L1->L2 creates two independent retryable tickets. Verify: `_addToBalance()` checks `amountToAddToBalanceOf()` which depends on actual token balance, preventing unbacked minting when message arrives before tokens. |
+| 8 | **CCIP-specific: ccipReceive** | Must never revert after CCIP delivers tokens. Verify: WETH unwrap safety, `this.fromRemote()` self-call pattern, transport payment refund (best-effort, stuck ETH accepted). |
+| 9 | **Reentrancy surfaces** | `_pullBackingAssets()` calls `terminal.cashOutTokensOf()` which triggers hooks. `_handleClaim()` calls `terminal.addToBalanceOf()` and `controller.mintTokensOf()`. No ReentrancyGuard. Verify: state is updated before external calls, bitmap prevents re-entry exploits. |
+
+## Invariants to Verify
+
+1. **No double-claim**: Each leaf index can only be claimed once per token (bitmap enforcement).
+2. **No cross-chain double-spend**: Emergency exit only allows leaves with `index >= numberOfClaimsSent` (not already sent to remote).
+3. **Token conservation**: `outbox.balance` (before `_sendRoot()`) == amount bridged to remote peer == amount available for claims on remote.
+4. **Nonce monotonicity**: Inbox nonce only increases. A stale nonce is rejected.
+5. **Mapping immutability**: After first outbox insertion, token cannot be remapped (only disabled).
+6. **Deprecation irreversibility**: Once `SENDING_DISABLED` or `DEPRECATED`, the sucker cannot return to `ENABLED`.
+7. **Balance accounting**: `amountToAddToBalanceOf(token) = contract.balance(token) - outboxOf[token].balance` is always non-negative.
+8. **Peer symmetry**: `peer()` returns the same address on both chains (CREATE2 determinism).
+
+## How to Run Tests
+
+```bash
+cd nana-suckers-v6
+npm install
+forge build
+forge test
+
+# Run with high verbosity for debugging
+forge test -vvvv --match-test testExploitName
+
+# Write a PoC
+forge test --match-path test/audit/ExploitPoC.t.sol -vvv
+
+# Specific test suites
+forge test --match-contract SuckerAttacks       # Attack scenarios
+forge test --match-contract SuckerDeepAttacks    # Deep attack vectors
+forge test --match-contract SuckerRegressions    # Regression tests
+forge test --match-contract InteropCompat        # Cross-chain compatibility
+forge test --match-path test/unit/               # Unit tests
+forge test --match-path test/regression/         # Regression tests
+
+# Fork tests (require RPC URLs)
+forge test --match-contract Fork --fork-url $ETH_RPC_URL
+forge test --match-contract ForkCelo --fork-url $CELO_RPC_URL
+forge test --match-contract ForkMainnet --fork-url $ETH_RPC_URL
+
+# Gas analysis
+forge test --gas-report
+```