copper-tone-tech/mev-beta
1
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity

feat: create v2-prep branch with comprehensive planning

Browse Source 
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>
This commit is contained in:
Administrator
2025-11-10 10:14:26 +01:00
parent 1773daffe7
commit 803de231ba
411 changed files with 20390 additions and 8680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
orig/cmd/swap-cli/README.md Normal file
View File

@@ -0,0 +1,233 @@
# 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.