> For the complete documentation index, see [llms.txt](https://docs.bean.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bean.exchange/lite-turbo-vault.md).

# Lite Turbo Vault

### Introduction

Automated liquidity management vault for DLMM pools.

**Goals:**

1. Simplify DLMM liquidity provision
2. Automate liquidity rebalancing across price ranges
3. Optimize capital efficiency through multi-strategy deployment
4. Aggregate fees and rewards for vault shareholders

### Architecture

```
                    ┌──────────┐
                    │  Keeper  │
                    └─────┬────┘
                          │
                          ▼
        ┌─────────────────────────────────┐
        │     Lite Turbo Vault            │
        │  ┌────────┐ ┌────────┐ ┌─────┐ │
        │  │  DLMM  │ │ Buffer │ │ Inv │ │
        │  └────────┘ └────────┘ └─────┘ │
        └──────────────┬──────────────────┘
                       │ 1:1
                       ▼
                ┌─────────────┐
                │   LBPair    │
                └─────────────┘
```

**Components:**

1. DLMM Liquidity - Active positions in price bins
2. Buffer - Idle tokens (deposits, fees, rewards)
3. Investment Handlers - Optional yield strategies
4. Keeper - Owner managing vault operations
5. LBPair - Underlying DLMM pool

### Parameters

| Parameter                     | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| `protocolFeeRate`             | Protocol fee on trading fees (basis points, max 5000)        |
| `feeRecipient`                | Protocol fee recipient address                               |
| `depositXMax` / `depositYMax` | Maximum single deposit per token                             |
| `maxTotalSupply`              | Vault share supply cap                                       |
| `binThreshold`                | Maximum allowed bin crosses                                  |
| `twapInterval`                | TWAP validation period (seconds)                             |
| `whitelistedAddress`          | Optional exclusive depositor                                 |
| `currentRange`                | Distribution config (deltaIds, distributionX, distributionY) |

### Use Cases

#### Deposit

1. User transfers tokenX and/or tokenY to vault
2. Vault calculates shares based on total assets
3. Mint shares proportional to deposit value
4. Tokens remain in buffer

#### Withdraw

1. User burns vault shares
2. Calculate proportional X/Y amounts
3. Transfer tokens from available liquidity
4. Distribute reward tokens proportionally

#### Rebalance

**Trigger:** Owner only

**Steps:**

1. Remove all DLMM liquidity
2. Collect pending fees and rewards
3. Withdraw from investment handlers (optional)
4. Redeploy with new distribution parameters
5. Invest to handlers (optional)

**Input:** RebalanceParams (amounts, deltaIds, distributions, handler indexes)

#### Compound

**Trigger:** Anyone

**Steps:**

1. Collect pending fees and rewards
2. Redeploy buffer using current distribution
3. No liquidity removal required

#### Force Add/Remove LP

**Owner Functions:**

1. `addLiquidity` - Deploy buffer to DLMM with current distribution
2. `removeLiquidity` - Remove all DLMM liquidity to buffer
3. `removeLiquidityPartially` - Remove percentage of liquidity to buffer

#### Force Invest/Divest

**Owner Functions:**

1. `invest` - Deploy buffer to handler by index
2. `divest` - Withdraw from handler by index
3. `addInvestmentHandler` - Register new handler
4. `removeInvestmentHandler` - Remove handler (must be empty)

#### Admin Functions

1. `setFeeRecipient` - Update fee recipient
2. `setProtocolFeeRate` - Update protocol fee rate
3. `setWhitelist` - Set whitelisted depositor
4. `setDepositMax` - Set deposit limits
5. `setMaxTotalSupply` - Set share cap
6. `setBinThreshold` - Set bin cross threshold
7. `setTwapInterval` - Set TWAP period
8. `setDistribution` - Update default distribution
9. `setPaused` - Pause/unpause deposits and withdrawals

#### Prevent TWAP Price Manipulation

**Protection Mechanism:**

1. Check bin crosses during `twapInterval` period
2. Compare against `binThreshold` limit
3. Revert if crosses exceed threshold
4. Applied on every deposit

### Rebalancing Method

#### Distribution System

**Delta-Based Parameters:**

1. `deltaIds` - Bin offsets from active bin

```
   Example: [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5]
```

2. `distributionX` - X token weights (sum = 1e18)
3. `distributionY` - Y token weights (sum = 1e18)

#### Rebalancing Process

1. **Remove Positions**
   * Burn LP tokens from all tracked bins
   * Receive tokens to buffer
2. **Settle Claims**
   * Collect trading fees
   * Collect farming rewards
   * Transfer protocol fee to recipient
3. **Withdraw Investments** (optional)
   * Withdraw all from handlers if enabled
4. **Calculate Range**
   * Get current active bin ID
   * Apply deltaIds to determine target bins
   * Validate range bounds
5. **Deploy Distribution**
   * Build liquidityConfigs from parameters
   * Transfer tokens to LBPair
   * Mint LP tokens
   * Track deployed bin IDs
6. **Deploy to Handlers** (optional)
   * Invest specified amounts by handler index

#### Features

1. TWAP price manipulation protection
2. Asymmetric distribution support
3. Single-transaction rebalancing
4. Multi-strategy deployment

### Keeper Rebalancing Strategy

#### Metrics to Monitor

1. **APY Comparison**
   * DLMM pool trading fees APY
   * Lending protocol APY
   * LSD staking APY
   * Calculate optimal allocation
2. **Effective Liquidity**
   * Current liquidity depth in active bins
   * Liquidity utilization rate
   * Buffer vs deployed ratio
3. **Trading Behavior**
   * Volume distribution across bins
   * Active bin movement patterns
   * Fee generation per bin
   * Optimal LP shape for current market

#### Rebalancing Triggers

1. **Time-Based**
   * Daily scheduled rebalance
   * Check all metrics at fixed intervals
2. **Demand-Driven**
   * Spike in trading volume (LP utilization high)
   * Active bin moved significantly from range center
   * Large deposits in buffer waiting deployment
3. **Yield-Driven**
   * Lending rewards increase significantly
   * LSD APY spikes above DLMM fees
   * New farming incentives available

#### Decision Process

1. Evaluate current allocation performance
2. Compare yields across strategies
3. Assess liquidity needs vs yield opportunity
4. Calculate optimal distribution and amounts
5. Execute rebalance with new parameters

### External Protocol Monitoring

#### Health Monitoring

1. **Lending Protocol Safety**
   * Monitor utilization rates
   * Track bad debt accumulation
   * Check collateral health ratios
   * Verify oracle price feeds
2. **LSD Protocol Safety**
   * Monitor validator performance
   * Track slashing events
   * Verify withdrawal queue depth
   * Check redemption rate stability
3. **Risk Indicators**
   * TVL sudden drops
   * Unusual withdraw patterns
   * Smart contract upgrades
   * Security incidents reported

#### Emergency Response

1. **Monitoring Alerts**
   * Set threshold alerts for each metric
   * Multi-channel notification system
   * Priority levels for different risks
2. **Emergency Withdrawal**
   * Keeper triggers emergency divest
   * Withdraw all funds from affected handler
   * Move assets to vault buffer
   * Pause new investments to handler
3. **Post-Emergency Actions**
   * Remove compromised handler
   * Redistribute assets to safe strategies
   * Notify vault users
   * Update risk parameters