# 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*