# Optional Upgrade: EnhancedSwapRouter

This runbook describes what you need to do to deploy and use the **EnhancedSwapRouter** (multi-protocol swap: Uniswap V3, Dodoex, Curve, Balancer, 1inch) on Ethereum Mainnet.

---

## 1. Prerequisites

- **Chain**: Ethereum Mainnet (Chain ID 1) only (script enforces this).
- **.env** (in `smom-dbis-138/` or project root) with:
  - `PRIVATE_KEY` — deployer key (has mainnet ETH for gas).
  - `ETHEREUM_MAINNET_RPC` — mainnet RPC (Infura/Alchemy recommended).
  - `ETHERSCAN_API_KEY` — for contract verification (optional but recommended).

---

## 2. Deploy EnhancedSwapRouter

From repo root `smom-dbis-138/`:

```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
set -a && [ -f .env ] && source .env && set +a

forge script script/bridge/trustless/DeployEnhancedSwapRouter.s.sol:DeployEnhancedSwapRouter \
  --rpc-url "$ETHEREUM_MAINNET_RPC" \
  --broadcast \
  --via-ir \
  --verify \
  --etherscan-api-key "$ETHERSCAN_API_KEY"
```

Or use the phase-3 script:

```bash
./scripts/deployment/phase3-deploy-router.sh
```

**Save the deployed address** from the script output and add to `.env`:

```bash
ENHANCED_SWAP_ROUTER=0x...
```

---

## 3. Configure Balancer pool IDs (optional)

EnhancedSwapRouter uses Balancer for medium/large swaps. If you use those tiers, set pool IDs for the pairs you need (e.g. WETH–USDC, WETH–USDT):

```bash
# Example: WETH–USDT Balancer pool ID (replace <poolId> with actual bytes32)
cast send $ENHANCED_SWAP_ROUTER \
  "setBalancerPoolId(address,address,bytes32)" \
  0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
  0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  <poolId> \
  --rpc-url "$ETHEREUM_MAINNET_RPC" \
  --private-key "$PRIVATE_KEY"
```

Find pool IDs from [Balancer](https://app.balancer.fi/) or their subgraph for mainnet.

---

## 4. Grant COORDINATOR_ROLE (for future coordinator use)

If you later deploy a coordinator that uses EnhancedSwapRouter (see §6), that coordinator must have `COORDINATOR_ROLE` on EnhancedSwapRouter. You can grant it to the **existing** BridgeSwapCoordinator so it’s ready if you switch to a coordinator that calls EnhancedSwapRouter:

```bash
# Role hash (COORDINATOR_ROLE)
cast keccak "COORDINATOR_ROLE"

# Grant to BridgeSwapCoordinator (replace with your BRIDGE_SWAP_COORDINATOR address)
cast send $ENHANCED_SWAP_ROUTER \
  "grantRole(bytes32,address)" \
  $(cast keccak "COORDINATOR_ROLE") \
  "$BRIDGE_SWAP_COORDINATOR" \
  --rpc-url "$ETHEREUM_MAINNET_RPC" \
  --private-key "$PRIVATE_KEY"
```

---

## 5. Customize routing (optional)

Default routing is:

- **Small** (&lt; $10k): Uniswap V3, Dodoex  
- **Medium** ($10k–$100k): Dodoex, Balancer, Uniswap V3  
- **Large** (&gt; $100k): Dodoex, Curve, Balancer  

To change providers per size category (e.g. `setRoutingConfig`), use the contract’s `setRoutingConfig(sizeCategory, providers[])` with the provider enum values (see `EnhancedSwapRouter.SwapProvider`).

---

## 6. Important: BridgeSwapCoordinator and EnhancedSwapRouter

The **current** **BridgeSwapCoordinator** (trustless bridge payout) is wired to the **basic SwapRouter** in code:

- It calls `swapRouter.swapToStablecoin(..., bytes calldata routeData)` and expects a single `uint256` return.
- **EnhancedSwapRouter** exposes `swapToStablecoin(..., SwapProvider preferredProvider)` and returns `(uint256, SwapProvider)`.

So the existing coordinator **cannot** call EnhancedSwapRouter without a contract change. Today:

- **bridgeAndSwap** (Lockbox → claim → release → swap to USDT/USDC) still uses the **basic SwapRouter** only.
- Deploying EnhancedSwapRouter gives you:
  - Multi-protocol routing for **other** callers (e.g. quote services, liquidity engine, or direct `EnhancedSwapRouter.swapToStablecoin` calls).
  - A path ready for a **future** coordinator (or upgraded coordinator) that uses EnhancedSwapRouter once one is implemented and deployed.

To actually use EnhancedSwapRouter for the trustless payout flow you would need to:

- Implement and deploy a new coordinator (or upgrade) that takes an EnhancedSwapRouter-compatible interface and calls `swapToStablecoin(..., preferredProvider)` with the right parameters and return handling, and
- Point the LP’s authorized releaser (or users) at that new coordinator instead of the current BridgeSwapCoordinator.

---

## 7. Summary checklist

| Step | Action |
|------|--------|
| 1 | Set `PRIVATE_KEY`, `ETHEREUM_MAINNET_RPC`, `ETHERSCAN_API_KEY` in `.env`. |
| 2 | Run `DeployEnhancedSwapRouter.s.sol` (or `phase3-deploy-router.sh`) on mainnet. |
| 3 | Add `ENHANCED_SWAP_ROUTER=<address>` to `.env`. |
| 4 | (Optional) Configure Balancer pool IDs for WETH–stable pairs. |
| 5 | (Optional) Grant `COORDINATOR_ROLE` on EnhancedSwapRouter to BridgeSwapCoordinator for future use. |
| 6 | (Optional) Adjust routing via `setRoutingConfig` if needed. |

**References:** `DEPLOYMENT_GUIDE.md`, `DEPLOYMENT_SUMMARY.md`, `script/bridge/trustless/DeployEnhancedSwapRouter.s.sol`, `scripts/deployment/phase3-deploy-router.sh`.

---

## 8. Completed deployment (2026-02-20)

- **EnhancedSwapRouter** deployed at `0xc99f13275a3a85f556570767f1Fc3e58788f777d` (Ethereum Mainnet).
- Default routing configured (small: Uniswap V3 + Dodoex; medium: Dodoex + Balancer + Uniswap V3; large: Dodoex + Curve + Balancer).
- **COORDINATOR_ROLE** granted to BridgeSwapCoordinator (`0xF51581eee46f5A7Ef2A035C5B3Ac4a89bF6FbaAa`).
- **Balancer pool IDs**: optional; set via `setBalancerPoolId(tokenA, tokenB, poolId)` when you have pool IDs from [Balancer](https://app.balancer.fi/) or the Balancer subgraph.

---

## 9. DualRouterBridgeSwapCoordinator (bridgeAndSwap with basic or enhanced router)

A **DualRouterBridgeSwapCoordinator** contract is deployed so that one coordinator can perform `bridgeAndSwap` using either the basic SwapRouter or the EnhancedSwapRouter.

- **Contract**: `contracts/bridge/trustless/DualRouterBridgeSwapCoordinator.sol`
- **Deployed at (Ethereum Mainnet)**: `0x5BB7e48DA5f571344E08BDB4f0d3CE2198963EcD`
- **Signature**: `bridgeAndSwap(depositId, recipient, outputAsset, stablecoinToken, amountOutMin, routeData, useEnhancedRouter)`
  - `useEnhancedRouter == false`: uses basic SwapRouter (same as existing BridgeSwapCoordinator).
  - `useEnhancedRouter == true`: uses EnhancedSwapRouter (multi-protocol routing).
- **Deploy script**: `script/bridge/trustless/DeployDualRouterBridgeSwapCoordinator.s.sol` (env: INBOX_ETH_MAINNET, LIQUIDITY_POOL_ETH_MAINNET, SWAP_ROUTER_MAINNET, ENHANCED_SWAP_ROUTER, CHALLENGE_MANAGER_MAINNET).
- **Wiring**: After deploy, the script calls `LiquidityPoolETH.authorizeRelease(coordinator)` and `EnhancedSwapRouter.grantRole(COORDINATOR_ROLE, coordinator)`.
- **.env**: Set `DUAL_ROUTER_BRIDGE_SWAP_COORDINATOR` to the deployed address.