154 lines
6.6 KiB
Markdown
154 lines
6.6 KiB
Markdown
# 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** (< $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](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.
|