DiTus
5ca16ec33f
Core Components: - uniswap_manager.py: V3 concentrated liquidity position manager - clp_hedger.py: Hyperliquid perpetuals hedging bot - requirements.txt: Python dependencies - .gitignore: Security exclusions for sensitive data - doc/: Project documentation - tools/: Utility scripts and Git agent Features: - Automated liquidity provision on Uniswap V3 (WETH/USDC) - Delta-neutral hedging using Hyperliquid perpetuals - Position lifecycle management (open/close/rebalance) - Automated backup and version control system Security: - Private keys and tokens excluded from version control - Environment variables properly handled - Automated security validation for backups Git Agent: - Hourly automated backups to separate branches - Keep last 100 backups (~4 days coverage) - Detailed change tracking and parameter monitoring - Push to Gitea server automatically - Manual main branch control preserved - No performance tracking for privacy - No notifications for simplicity Files Added: - git_agent.py: Main automation script - agent_config.json: Configuration with Gitea settings - git_utils.py: Git operations wrapper - backup_manager.py: Backup branch management - change_detector.py: File change analysis - cleanup_manager.py: 100-backup rotation - commit_formatter.py: Detailed commit messages - README_GIT_AGENT.md: Complete usage documentation
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# Uniswap Manager Workflow Documentation
|
|
|
|
This document describes the operational logic of the `uniswap_manager_refactored.py` script, specifically focusing on how it handles position lifecycle events.
|
|
|
|
## 1. Out of Range Workflow (Position Closing)
|
|
|
|
When the script detects that an active Concentrated Liquidity Position (CLP) has moved out of its defined tick range, the following sequence occurs:
|
|
|
|
1. **Detection (Monitoring Loop):**
|
|
* The `main` loop runs every `MONITOR_INTERVAL_SECONDS` (default: 60s).
|
|
* It retrieves the active position's `tickLower` and `tickUpper` from on-chain data.
|
|
* It fetches the current pool `tick`.
|
|
* It determines if the position is out of range (`current_tick < tickLower` or `current_tick >= tickUpper`).
|
|
|
|
2. **Logging:**
|
|
* A warning is logged to both console and file: `🛑 Closing Position {token_id} (Out of Range)`.
|
|
|
|
3. **Status Update -> "CLOSING":**
|
|
* The `hedge_status.json` file is updated to mark the position status as `"CLOSING"`.
|
|
* **Purpose:** This signals external Hedger bots (watching this file) to halt hedging operations or close their hedges immediately.
|
|
|
|
4. **Liquidity Removal:**
|
|
* The script executes a `decreaseLiquidity` transaction on the `NonfungiblePositionManager` contract.
|
|
* It removes 100% of the liquidity, converting the position back into the underlying tokens (WETH and USDC) in the wallet.
|
|
|
|
5. **Fee Collection:**
|
|
* Immediately following liquidity removal, a `collect` transaction is sent to claim all accrued trading fees.
|
|
|
|
6. **Status Update -> "CLOSED":**
|
|
* Upon successful confirmation of the transactions, `hedge_status.json` is updated to status `"CLOSED"`.
|
|
* A `timestamp_close` is recorded.
|
|
|
|
7. **Rebalancing (Optional/Configuration Dependent):**
|
|
* The script checks the `REBALANCE_ON_CLOSE_BELOW_RANGE` flag.
|
|
* **Scenario:** If the price fell **BELOW** the range, the position is 100% WETH.
|
|
* **Action:** If implemented, the script may perform a swap (e.g., selling 50% of the WETH for USDC) to rebalance the portfolio before opening a new position.
|
|
* *Current State:* The logic identifies this condition but requires the specific swap logic implementation (currently a `pass` placeholder in the refactored script).
|
|
|
|
8. **Cycle Reset:**
|
|
* The script returns to the monitoring loop.
|
|
* In the next cycle, detecting no "OPEN" position, it will evaluate `OPEN_POSITION_ENABLED` to potentially calculate and mint a **new** position centered on the current market price.
|
|
|
|
## 2. New Position Creation (Opening)
|
|
|
|
When no active position exists and `OPEN_POSITION_ENABLED` is `True`:
|
|
|
|
1. **Market Analysis:**
|
|
* Fetches current pool price and tick.
|
|
* Calculates a new range (default: +/- 2.5%) centered on the current tick.
|
|
|
|
2. **Investment Calculation:**
|
|
* Uses `TARGET_INVESTMENT_VALUE_USDC` (default: $200).
|
|
* If set to `"MAX"`, it calculates the maximum affordable position based on wallet balances minus a safety buffer.
|
|
* Calculates the precise amount of Token0 and Token1 required for the target value at the current price and range.
|
|
|
|
3. **Preparation (Swap & Approve):**
|
|
* Checks wallet balances.
|
|
* **Auto-Wrap:** Wraps ETH to WETH if necessary.
|
|
* **Auto-Swap:** Swaps surplus tokens (e.g., excess USDC for WETH) to match the required ratio for the new position.
|
|
* **Approvals:** Checks and sends `approve` transactions for the Position Manager if allowances are insufficient.
|
|
|
|
4. **Minting:**
|
|
* Sends the `mint` transaction to create the new NFT position.
|
|
* Applies a slippage tolerance (default: 0.5%) to `amountMin` parameters.
|
|
|
|
5. **Status Recording:**
|
|
* On success, updates `hedge_status.json` with the new position details (Token ID, Range, Entry Price, Initial Amounts).
|
|
* Sets status to `"OPEN"`.
|
|
|
|
---
|
|
*Last Updated: December 19, 2025*
|