uniswap_auto_clp/doc/UNISWAP_MANAGER_WORKFLOW.md

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