803de231ba
Restructured project for V2 refactor: **Structure Changes:** - Moved all V1 code to orig/ folder (preserved with git mv) - Created docs/planning/ directory - Added orig/README_V1.md explaining V1 preservation **Planning Documents:** - 00_V2_MASTER_PLAN.md: Complete architecture overview - Executive summary of critical V1 issues - High-level component architecture diagrams - 5-phase implementation roadmap - Success metrics and risk mitigation - 07_TASK_BREAKDOWN.md: Atomic task breakdown - 99+ hours of detailed tasks - Every task < 2 hours (atomic) - Clear dependencies and success criteria - Organized by implementation phase **V2 Key Improvements:** - Per-exchange parsers (factory pattern) - Multi-layer strict validation - Multi-index pool cache - Background validation pipeline - Comprehensive observability **Critical Issues Addressed:** - Zero address tokens (strict validation + cache enrichment) - Parsing accuracy (protocol-specific parsers) - No audit trail (background validation channel) - Inefficient lookups (multi-index cache) - Stats disconnection (event-driven metrics) Next Steps: 1. Review planning documents 2. Begin Phase 1: Foundation (P1-001 through P1-010) 3. Implement parsers in Phase 2 4. Build cache system in Phase 3 5. Add validation pipeline in Phase 4 6. Migrate and test in Phase 5 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
233 lines
6.0 KiB
Markdown
233 lines
6.0 KiB
Markdown
# Swap CLI Tool
|
|
|
|
A standalone command-line interface for executing swaps on Arbitrum using various DEX protocols.
|
|
|
|
## Features
|
|
|
|
- Support for multiple DEX protocols:
|
|
- Uniswap V2 & V3
|
|
- SushiSwap
|
|
- Camelot V3
|
|
- TraderJoe V2
|
|
- KyberSwap Elastic
|
|
- Dry-run simulation mode
|
|
- Gas estimation
|
|
- Token allowance management
|
|
- Configurable slippage and deadlines
|
|
- Comprehensive logging
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Build the CLI tool
|
|
cd cmd/swap-cli
|
|
go build -o swap-cli .
|
|
|
|
# Or build from project root
|
|
make build-swap-cli
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The CLI tool uses environment variables and command-line flags for configuration:
|
|
|
|
### Required Environment Variables
|
|
|
|
```bash
|
|
export ARBITRUM_RPC_ENDPOINT="https://arb1.arbitrum.io/rpc"
|
|
export PRIVATE_KEY="your-private-key-hex" # Optional for dry-run mode
|
|
```
|
|
|
|
### Optional Environment Variables
|
|
|
|
```bash
|
|
export WALLET_ADDRESS="0x..." # If not using private key
|
|
export LOG_LEVEL="info" # debug, info, warn, error
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Swap Commands
|
|
|
|
```bash
|
|
# Dry-run swap simulation (no actual transaction)
|
|
./swap-cli --dry-run uniswap-v3 \
|
|
--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--token-out 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--amount-in 1000000000 \
|
|
--slippage 0.5
|
|
|
|
# Execute actual swap on Uniswap V3
|
|
./swap-cli uniswap-v3 \
|
|
--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--token-out 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--amount-in 1000000000 \
|
|
--slippage 0.5 \
|
|
--deadline 300
|
|
|
|
# Swap on different protocols
|
|
./swap-cli sushiswap --token-in ... --token-out ... --amount-in ...
|
|
./swap-cli camelot-v3 --token-in ... --token-out ... --amount-in ...
|
|
./swap-cli traderjoe-v2 --token-in ... --token-out ... --amount-in ...
|
|
./swap-cli kyber-elastic --token-in ... --token-out ... --amount-in ...
|
|
```
|
|
|
|
### Gas Estimation
|
|
|
|
```bash
|
|
# Estimate gas for a swap
|
|
./swap-cli estimate-gas \
|
|
--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--token-out 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--amount-in 1000000000
|
|
```
|
|
|
|
### Token Management
|
|
|
|
```bash
|
|
# Check token allowance
|
|
./swap-cli check-allowance \
|
|
--token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--spender 0xE592427A0AEce92De3Edee1F18E0157C05861564
|
|
|
|
# Approve token spending
|
|
./swap-cli approve \
|
|
--token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--spender 0xE592427A0AEce92De3Edee1F18E0157C05861564 \
|
|
--amount max
|
|
```
|
|
|
|
## Command-Line Options
|
|
|
|
### Global Flags
|
|
|
|
- `--rpc-endpoint`: Arbitrum RPC endpoint URL
|
|
- `--private-key`: Private key for signing transactions
|
|
- `--wallet-address`: Wallet address (if using external signer)
|
|
- `--dry-run`: Simulate without executing
|
|
- `--log-level`: Logging level (debug, info, warn, error)
|
|
|
|
### Swap Flags
|
|
|
|
- `--token-in`: Input token contract address
|
|
- `--token-out`: Output token contract address
|
|
- `--amount-in`: Amount of input tokens (in smallest unit)
|
|
- `--min-amount-out`: Minimum output tokens (optional)
|
|
- `--recipient`: Recipient address (defaults to sender)
|
|
- `--slippage`: Slippage tolerance percentage (default: 0.5%)
|
|
- `--deadline`: Transaction deadline in seconds (default: 300)
|
|
- `--pool-fee`: V3 pool fee tier (500, 3000, 10000)
|
|
- `--gas-price`: Gas price in gwei
|
|
- `--gas-limit`: Gas limit
|
|
|
|
## Examples
|
|
|
|
### Common Token Addresses on Arbitrum
|
|
|
|
```bash
|
|
# USDC
|
|
USDC="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
|
|
|
|
# WETH
|
|
WETH="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
|
|
|
|
# ARB
|
|
ARB="0x912CE59144191C1204E64559FE8253a0e49E6548"
|
|
|
|
# USDT
|
|
USDT="0xdAC17F958D2ee523a2206206994597C13D831ec7"
|
|
```
|
|
|
|
### Example Swaps
|
|
|
|
```bash
|
|
# Swap 100 USDC for WETH on Uniswap V3
|
|
./swap-cli uniswap-v3 \
|
|
--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--token-out 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--amount-in 100000000 \
|
|
--slippage 0.5
|
|
|
|
# Swap 1 WETH for USDC on SushiSwap
|
|
./swap-cli sushiswap \
|
|
--token-in 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--token-out 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--amount-in 1000000000000000000 \
|
|
--slippage 1.0
|
|
|
|
# High-precision swap with custom gas settings
|
|
./swap-cli uniswap-v3 \
|
|
--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
|
|
--token-out 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
|
|
--amount-in 1000000000 \
|
|
--min-amount-out 995000000000000000 \
|
|
--slippage 0.1 \
|
|
--gas-price 0.1 \
|
|
--gas-limit 200000 \
|
|
--deadline 600
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
1. **Private Key Management**: Never commit private keys to version control
|
|
2. **Dry-Run First**: Always test with `--dry-run` before executing
|
|
3. **Slippage Settings**: Be careful with slippage on volatile tokens
|
|
4. **Gas Price**: Monitor network conditions for optimal gas pricing
|
|
5. **Token Verification**: Always verify token contract addresses
|
|
|
|
## Error Handling
|
|
|
|
The CLI provides detailed error messages for common issues:
|
|
|
|
- Insufficient balance
|
|
- Invalid token addresses
|
|
- Network connectivity issues
|
|
- Gas estimation failures
|
|
- Transaction reverts
|
|
|
|
## Development
|
|
|
|
### Adding New Protocols
|
|
|
|
1. Add the protocol to the router address mapping in `getRouterAddress()`
|
|
2. Implement the protocol-specific swap function
|
|
3. Add any protocol-specific parameters to the CLI flags
|
|
4. Update this README with usage examples
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Test with dry-run mode
|
|
./swap-cli --dry-run uniswap-v3 --token-in ... --token-out ... --amount-in ...
|
|
|
|
# Test gas estimation
|
|
./swap-cli estimate-gas --token-in ... --token-out ... --amount-in ...
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **"Insufficient balance"**: Check token balance and decimals
|
|
2. **"Transaction reverted"**: Check allowances and slippage settings
|
|
3. **"Gas estimation failed"**: Try setting manual gas limits
|
|
4. **"Invalid private key"**: Ensure key is in hex format without 0x prefix
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging for detailed information:
|
|
|
|
```bash
|
|
./swap-cli --log-level debug ...
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Follow the existing code structure
|
|
2. Add comprehensive error handling
|
|
3. Include dry-run simulation support
|
|
4. Update documentation for new features
|
|
|
|
## License
|
|
|
|
This tool is part of the MEV Bot project and follows the same license terms. |