VortexAgent README

Use Case

VortexAgent is an agent-driven liquidity management system built for Uniswap v4, targeting DeFi funds, DAOs, or individual liquidity providers (LPs) managing positions in volatile token pairs like ETH/USDC.

In practice, a DAO treasury could deploy VortexAgent to automate liquidity provision in a Uniswap v4 pool. An offchain keeper (e.g., via Chainlink Automation) monitors the current price through an oracle (e.g., Chainlink Price Feed) and triggers onchain rebalancing when the price drifts outside optimal ranges. This ensures concentrated liquidity around the current tick, maximizing fee earnings while minimizing impermanent loss.

The system emphasizes reliability through atomic operations, transparency via auditable smart contracts, and composability by integrating with other DeFi protocols like oracles and keepers. It meets Uniswap v4 Agentic Finance track requirements by enabling programmatic interaction with pools for liquidity management without relying on speculative AI—using deterministic onchain logic instead.

Problem Solved

In Uniswap v4, LPs face challenges with manual liquidity management: positions in single or static ranges become inefficient in volatile markets, leading to low fee yields and high impermanent loss as prices move. Traditional tools allow multi-range positions but lack automation, requiring constant human intervention.

VortexAgent solves this by introducing agentic rebalancing—autonomous adjustments to liquidity distributions based on real-time onchain state (e.g., current tick from oracles). Technically, this reduces gas costs via batched operations and improves capital efficiency. From a business perspective, it lowers operational overhead for DeFi entities, enabling 24/7 optimization and potentially increasing LP returns by 20–50% in volatile pairs (based on historical backtests of similar strategies), making Uniswap pools more attractive and boosting overall protocol TVL.

How It Works

VortexAgent extends a multi-range position manager with an agentic layer for programmatic liquidity management on Uniswap v4:

• Deployment and Setup — Deploy the VortexAgent contract, which integrates with Uniswap v4's PoolManager for handling positions as ERC721 NFTs. Users mint an NFT representing a multi-range liquidity position by specifying multiple price ranges and liquidity amounts.

• Multi-Range Liquidity Provision — Using a Red-Black Tree (from Solady) for efficient tick tracking, the contract batches additions/removals via _populateActions and executes them atomically through PoolManager.unlock. This allows distributing liquidity across ranges (e.g., 40% near current price, 30% wider) in one transaction.

• Agentic Rebalancing — An external keeper (agent) calls the public rebalance(uint24 currentTick) function, passing the current tick from an oracle. The function calculates new liquidity deltas (e.g., shifting 80% within ±500 ticks of the current price) and atomically adjusts the position. Hooks (optional, via OptionalHook) can trigger dynamic fees or modifications during rebalances for added incentives.

• Integration Points — Relies on Uniswap v4 for core pool interactions (swaps, liquidity mods). Oracles provide onchain state for reliability; no offchain speculation. Composability allows chaining with other agents (e.g., routing trades through rebalanced pools).

• Evidence of Functionality — Testnet transactions (e.g., Sepolia) demonstrate deployment, liquidity addition, and rebalance calls. No UI required—focus on verifiable onchain actions.

Architecture Diagram

Below is an ASCII art diagram illustrating the high-level architecture. Uniswap v4 components are explicitly highlighted in bold for clarity.

+-------------------+       +-------------------+       +-------------------+
|   Offchain Keeper |       |   Chainlink Oracle|       | External User/DAO |
| (e.g., Chainlink  |       | (Provides current |       | (Mints NFT,       |
|  Automation or    |       |  tick/price feed) |       |  Initiates setup) |
|   Gelato Bot)     |       +-------------------+       +-------------------+
+-------------------+                  |                           |
           |                           | (Onchain State)           |
           | (Triggers rebalance)      |                           |
           |                           |                           |
           v                           v                           v
+-------------------+       +-------------------+       +-------------------+
| **Uniswap v4 Hook**| <---> |  VortexAgent      | <---> | **Uniswap v4 Pool**|
| (Optional: Dynamic|       |  Contract         |       | (**PoolManager**:  |
|  fees on modify)  |       | - Multi-Range NFT |       |  Liquidity ops,   |
+-------------------+       | - Rebalance Logic |       |  Swaps, Ticks)    |
                            | - Red-Black Tree  |       +-------------------+
                            +-------------------+                 ^
                                   | (Atomic Batch)               |
                                   |                              |
                                   v                              |
                            +-------------------+                 |
                            | **Uniswap v4 Core**| <---------------+
                            | (Positions, Ticks, |
                            |  State Management) |
                            +-------------------+

Key Flows

• User/DAO interacts with VortexAgent to create/manage positions, leveraging Uniswap v4 Core for state.
• Keeper uses oracle data to call rebalance, which batches changes via PoolManager in Uniswap v4 Pool.
• Optional Hook integrates at modification points for enhanced behavior, all within Uniswap v4's programmable framework.