366 lines
11 KiB
Markdown
366 lines
11 KiB
Markdown
# Trustless Bridge Deployment Guide
|
|
|
|
Complete guide for deploying the trustless bridge system with enhanced routing and integration contracts.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Prerequisites](#prerequisites)
|
|
2. [Environment Setup](#environment-setup)
|
|
3. [Deployment Order](#deployment-order)
|
|
4. [Step-by-Step Deployment](#step-by-step-deployment)
|
|
5. [Post-Deployment Configuration](#post-deployment-configuration)
|
|
6. [Verification](#verification)
|
|
7. [Troubleshooting](#troubleshooting)
|
|
|
|
## Prerequisites
|
|
|
|
### Required Accounts
|
|
- **Deployer Account**: Private key with sufficient ETH for gas
|
|
- **Admin Account**: For role management (can be same as deployer)
|
|
- **Liquidity Providers**: Accounts to provide initial liquidity
|
|
|
|
### Required Access
|
|
- Ethereum Mainnet RPC endpoint
|
|
- ChainID 138 RPC endpoint
|
|
- Etherscan API key (for contract verification)
|
|
|
|
### Required Funds
|
|
- **Deployment Gas**: ~5-10 ETH (depending on gas prices)
|
|
- **Initial Liquidity**: 100+ ETH recommended
|
|
- **Reserve Funding**: Based on expected bridge volume
|
|
|
|
## Environment Setup
|
|
|
|
### 1. Create `.env` File
|
|
|
|
```bash
|
|
# Deployment Account
|
|
PRIVATE_KEY=0x... # Your deployer private key
|
|
|
|
# RPC Endpoints
|
|
ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com
|
|
RPC_URL_138=http://chain138.example.com:8545
|
|
|
|
# Etherscan Verification
|
|
ETHERSCAN_API_KEY=your_etherscan_api_key
|
|
|
|
# Bridge Configuration (optional, defaults provided)
|
|
BOND_MULTIPLIER_BPS=11000 # 110%
|
|
MIN_BOND=1000000000000000000 # 1 ETH
|
|
CHALLENGE_WINDOW_SECONDS=1800 # 30 minutes
|
|
LP_FEE_BPS=5 # 0.05%
|
|
MIN_LIQUIDITY_RATIO_BPS=11000 # 110%
|
|
|
|
# Reserve System (if deploying)
|
|
RESERVE_SYSTEM=0x... # ReserveSystem address
|
|
XAU_ADDRESS=0x... # XAU token address (if tokenized)
|
|
|
|
# Peg Configuration
|
|
USD_PEG_THRESHOLD_BPS=50 # 0.5%
|
|
ETH_PEG_THRESHOLD_BPS=10 # 0.1%
|
|
COMMODITY_PEG_THRESHOLD_BPS=100 # 1%
|
|
MIN_RESERVE_RATIO_BPS=11000 # 110%
|
|
```
|
|
|
|
### 2. Source Environment
|
|
|
|
```bash
|
|
source .env
|
|
```
|
|
|
|
## Deployment Order
|
|
|
|
The deployment must follow this order due to dependencies:
|
|
|
|
1. **ReserveSystem** (ChainID 138) - If not already deployed
|
|
2. **Core Bridge Contracts** (ChainID 138 + Ethereum)
|
|
3. **EnhancedSwapRouter** (Ethereum)
|
|
4. **Integration Contracts** (Ethereum)
|
|
5. **System Initialization** (Ethereum)
|
|
6. **Backend Services**
|
|
7. **Frontend Applications**
|
|
|
|
## Step-by-Step Deployment
|
|
|
|
### Step 1: Deploy ReserveSystem (ChainID 138)
|
|
|
|
**Skip if already deployed**
|
|
|
|
```bash
|
|
cd /home/intlc/projects/proxmox/smom-dbis-138
|
|
|
|
forge script script/reserve/DeployReserveSystem.s.sol:DeployReserveSystem \
|
|
--rpc-url $RPC_URL_138 \
|
|
--broadcast \
|
|
--via-ir
|
|
|
|
# Save the deployed address
|
|
export RESERVE_SYSTEM=0x...
|
|
```
|
|
|
|
### Step 2: Deploy Core Bridge Contracts
|
|
|
|
#### 2.1 Deploy on ChainID 138
|
|
|
|
```bash
|
|
forge script script/bridge/trustless/DeployTrustlessBridge.s.sol:DeployTrustlessBridge \
|
|
--rpc-url $RPC_URL_138 \
|
|
--broadcast \
|
|
--via-ir
|
|
|
|
# Save the deployed address
|
|
export LOCKBOX_138=0x...
|
|
```
|
|
|
|
#### 2.2 Deploy on Ethereum Mainnet
|
|
|
|
```bash
|
|
forge script script/bridge/trustless/DeployTrustlessBridge.s.sol:DeployTrustlessBridge \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--broadcast \
|
|
--via-ir \
|
|
--verify \
|
|
--etherscan-api-key $ETHERSCAN_API_KEY
|
|
|
|
# Save deployed addresses
|
|
export BOND_MANAGER=0x...
|
|
export CHALLENGE_MANAGER=0x...
|
|
export LIQUIDITY_POOL=0x...
|
|
export INBOX_ETH=0x...
|
|
export SWAP_ROUTER=0x... # Basic SwapRouter
|
|
export BRIDGE_SWAP_COORDINATOR=0x...
|
|
```
|
|
|
|
### Step 3: Deploy EnhancedSwapRouter
|
|
|
|
```bash
|
|
forge script script/bridge/trustless/DeployEnhancedSwapRouter.s.sol:DeployEnhancedSwapRouter \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--broadcast \
|
|
--via-ir \
|
|
--verify \
|
|
--etherscan-api-key $ETHERSCAN_API_KEY
|
|
|
|
# Save the deployed address
|
|
export ENHANCED_SWAP_ROUTER=0x...
|
|
```
|
|
|
|
**Note**: After deployment, configure Balancer pool IDs:
|
|
```bash
|
|
# Example: Configure WETH-USDT pool
|
|
cast send $ENHANCED_SWAP_ROUTER \
|
|
"setBalancerPoolId(address,address,bytes32)" \
|
|
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
0xdAC17F958D2ee523a2206206994597C13D831ec7 \
|
|
0x... \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
```
|
|
|
|
### Step 4: Deploy Integration Contracts
|
|
|
|
```bash
|
|
# Ensure RESERVE_SYSTEM and BRIDGE_SWAP_COORDINATOR are set
|
|
forge script script/bridge/trustless/DeployIntegrationContracts.s.sol:DeployIntegrationContracts \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--broadcast \
|
|
--via-ir \
|
|
--verify \
|
|
--etherscan-api-key $ETHERSCAN_API_KEY
|
|
|
|
# Save deployed addresses
|
|
export STABLECOIN_PEG_MANAGER=0x...
|
|
export COMMODITY_PEG_MANAGER=0x...
|
|
export ISO_CURRENCY_MANAGER=0x...
|
|
export BRIDGE_RESERVE_COORDINATOR=0x...
|
|
```
|
|
|
|
### Step 5: Initialize System
|
|
|
|
```bash
|
|
forge script script/bridge/trustless/InitializeBridgeSystem.s.sol:InitializeBridgeSystem \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--broadcast \
|
|
--via-ir
|
|
```
|
|
|
|
### Step 6: Provide Initial Liquidity
|
|
|
|
```bash
|
|
# Provide liquidity to LiquidityPoolETH
|
|
cast send $LIQUIDITY_POOL \
|
|
"provideLiquidity(uint8)" \
|
|
0 \
|
|
--value 100ether \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
```
|
|
|
|
### Step 7: Fund ReserveSystem
|
|
|
|
```bash
|
|
# Deposit reserves (example with USDT)
|
|
cast send $USDT \
|
|
"approve(address,uint256)" \
|
|
$RESERVE_SYSTEM \
|
|
100000000000000000000000 \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
|
|
cast send $RESERVE_SYSTEM \
|
|
"depositReserve(address,uint256)" \
|
|
$USDT \
|
|
100000000000000000000000 \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
```
|
|
|
|
## Post-Deployment Configuration
|
|
|
|
### 1. Configure Access Control Roles
|
|
|
|
```bash
|
|
# Grant COORDINATOR_ROLE to BridgeSwapCoordinator
|
|
cast send $ENHANCED_SWAP_ROUTER \
|
|
"grantRole(bytes32,address)" \
|
|
$(cast keccak "COORDINATOR_ROLE") \
|
|
$BRIDGE_SWAP_COORDINATOR \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
```
|
|
|
|
### 2. Configure Routing Logic
|
|
|
|
The EnhancedSwapRouter is pre-configured with default routing, but you can customize:
|
|
|
|
```bash
|
|
# Example: Update small swap routing
|
|
cast send $ENHANCED_SWAP_ROUTER \
|
|
"setRoutingConfig(uint256,uint8[])" \
|
|
0 \
|
|
"[0,2]" \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC \
|
|
--private-key $PRIVATE_KEY
|
|
```
|
|
|
|
### 3. Update BridgeSwapCoordinator
|
|
|
|
If using EnhancedSwapRouter, update the coordinator to use it:
|
|
|
|
```bash
|
|
# This may require redeployment or upgrade
|
|
# Check BridgeSwapCoordinator implementation for update method
|
|
```
|
|
|
|
## Verification
|
|
|
|
### 1. Verify Contracts on Etherscan
|
|
|
|
All contracts should be automatically verified if using `--verify` flag. Manual verification:
|
|
|
|
```bash
|
|
forge verify-contract <CONTRACT_ADDRESS> \
|
|
<CONTRACT_NAME> \
|
|
--chain-id 1 \
|
|
--etherscan-api-key $ETHERSCAN_API_KEY \
|
|
--constructor-args $(cast abi-encode "constructor(...)" <args>)
|
|
```
|
|
|
|
### 2. Test End-to-End Flow
|
|
|
|
```bash
|
|
# 1. Deposit on ChainID 138
|
|
cast send $LOCKBOX_138 \
|
|
"depositNative(address,bytes32)" \
|
|
<recipient> \
|
|
$(cast keccak "test") \
|
|
--value 1ether \
|
|
--rpc-url $RPC_URL_138 \
|
|
--private-key $PRIVATE_KEY
|
|
|
|
# 2. Submit claim on Ethereum
|
|
# (Use relayer service or manual call)
|
|
|
|
# 3. Wait for challenge window
|
|
|
|
# 4. Finalize claim
|
|
|
|
# 5. Verify swap executed
|
|
```
|
|
|
|
### 3. Check System Status
|
|
|
|
```bash
|
|
# Check liquidity pool balance
|
|
cast call $LIQUIDITY_POOL "totalLiquidity()" --rpc-url $ETHEREUM_MAINNET_RPC
|
|
|
|
# Check reserve status
|
|
cast call $BRIDGE_RESERVE_COORDINATOR \
|
|
"getReserveStatus(address,uint256)" \
|
|
$USDT \
|
|
1000000000000000000 \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC
|
|
|
|
# Check peg status
|
|
cast call $STABLECOIN_PEG_MANAGER \
|
|
"checkUSDpeg(address)" \
|
|
$USDT \
|
|
--rpc-url $ETHEREUM_MAINNET_RPC
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Insufficient Gas**: Increase gas limit or gas price
|
|
2. **Contract Verification Fails**: Check constructor arguments
|
|
3. **Role Grant Fails**: Ensure deployer has admin role
|
|
4. **Liquidity Pool Empty**: Provide initial liquidity
|
|
5. **Reserve Insufficient**: Fund ReserveSystem
|
|
|
|
### Live-test cast errors (lock / claim / finalize)
|
|
|
|
- **`-32602: Invalid params`** — Wrong RPC for the tx (e.g. mainnet RPC for a 138 lock), or missing/corrupt env (PRIVATE_KEY, RPC_URL_138, ETHEREUM_MAINNET_RPC). Ensure lock uses `--rpc-url $RPC_URL_138` and claim/finalize use `--rpc-url $ETHEREUM_MAINNET_RPC`. Check `.env` has no typos (e.g. `PRIVATE_KEYIT_ID`).
|
|
- **`invalid string length` (e.g. for `1000000000000000`)** — You passed the **amount** (AMOUNT_WEI) where an **address** or **depositId** is expected. **DEPOSIT_ID** must be the **depositId** from the Lockbox `Deposit` event (a large uint256 from the event), **not** the amount. Get it with:
|
|
```bash
|
|
cast logs <LOCK_TX_HASH> "Deposit(uint256,address,uint256,address,bytes32,address,uint256)" --rpc-url $RPC_URL_138
|
|
```
|
|
Use the first decoded argument as `DEPOSIT_ID`.
|
|
- **`encode length mismatch: expected 1 types, got 0`** — **DEPOSIT_ID** is empty or unset for `claim` or `finalize`. Set it from the lock tx event as above.
|
|
|
|
**Quick DEPOSIT_ID from lock tx:**
|
|
`export DEPOSIT_ID=$(./scripts/deployment/run-e2e-trustless-live-test.sh get-deposit-id <LOCK_TX_HASH>)`
|
|
Then run `AMOUNT_WEI=1000000000000000 ./scripts/deployment/run-e2e-trustless-live-test.sh claim`.
|
|
|
|
### Emergency Procedures
|
|
|
|
1. **Pause System**: Use pause functions if available
|
|
2. **Withdraw Liquidity**: Emergency withdrawal procedures
|
|
3. **Update Configuration**: Use admin functions to update parameters
|
|
|
|
## Next Steps
|
|
|
|
After deployment:
|
|
|
|
1. Deploy backend services
|
|
2. Deploy frontend applications
|
|
3. Set up monitoring
|
|
4. Configure alerting
|
|
5. Train operators
|
|
6. Begin operations
|
|
|
|
See `OPERATIONS_GUIDE.md` for operational procedures.
|
|
|
|
---
|
|
|
|
## Deploy, Configure, and Live Test (single flow)
|
|
|
|
**Deploy:** Run trustless phase: `./scripts/deployment/deploy-all-mainnets-with-mapper-oracle-pmm.sh trustless` (from smom-dbis-138). Set LOCKBOX_138, BOND_MANAGER, LIQUIDITY_POOL, INBOX_ETH, CHALLENGE_MANAGER in .env.
|
|
|
|
**Configure:** (1) Verify Inbox is authorized on LP: `cast call $LIQUIDITY_POOL "authorizedRelease(address)(bool)" $INBOX_ETH --rpc-url $ETHEREUM_MAINNET_RPC`. (2) Initialize if using router: `forge script script/bridge/trustless/InitializeBridgeSystem.s.sol:InitializeBridgeSystem --rpc-url $ETHEREUM_MAINNET_RPC --broadcast --via-ir`. (3) Fund LP: `./scripts/deployment/fund-mainnet-lp.sh --eth 2 --weth 1`.
|
|
|
|
**Verify:** `./scripts/deployment/verify-trustless-deployments.sh`.
|
|
|
|
**Live test with actual tokens (138 to mainnet):** (1) Lock: `cast send $LOCKBOX_138 "depositNative(address,bytes32)" RECIPIENT NONCE --value 0.01ether --rpc-url $RPC_URL_138 --private-key $PRIVATE_KEY --legacy`. (2) Get depositId from Deposit event. (3) Submit claim: `cast send $INBOX_ETH "submitClaim(uint256,address,uint256,address,bytes)" DEPOSIT_ID 0x0 AMOUNT_WEI RECIPIENT 0x --value BOND --rpc-url $ETHEREUM_MAINNET_RPC --private-key $PRIVATE_KEY` (BOND = getRequiredBond(amount)). (4) Wait challenge window. (5) Finalize: `cast send $CHALLENGE_MANAGER "finalizeClaim(uint256)" DEPOSIT_ID ...`. (6) Release bond: `cast send $BOND_MANAGER "releaseBond(uint256)" DEPOSIT_ID ...`. See runbook: `scripts/deployment/live-test-trustless-bridge.sh` (prints commands and optional checks).
|
|
|