smom-dbis-138/docs/bridge/trustless/ENHANCED_SWAP_ROUTER_UPGRADE.md

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/:

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:

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

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

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):

# 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 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:

# 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 (< $10k): Uniswap V3, Dodoex
• Medium ($10k–$100k): Dodoex, Balancer, Uniswap V3
• Large (> $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 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.