# v10.2 Update

## Changelog

### Summary

The depth bands feature replaces the simple "1% depth" price impact model with a 30-band system that provides granular control over price impact curves. This enhancement allows for more realistic market depth modeling.

### Added

#### New Features

* 30 configurable bands (0-29) representing different liquidity depths
* Piecewise calculation using trapezoidal rule for smooth price impact curves
* Linear extrapolation beyond 100% depth for very large trades
* Separate depth configurations for longs (above) and shorts (below)
* Efficient storage packing: all band data in 2 slots per direction
* Non-decreasing validation for band liquidity/offset values

#### New Data Structures

* `IPriceImpact.PairDepthBands` - Stores depth band liquidity configuration for each pair (4 slots: above/below × slot1/slot2)
* `IPriceImpact.DepthBandsMapping` - Global mapping of band indices to band percentage offsets from mid price (2 slots)
* `IPriceImpact.DepthBandParameters` - Working struct for depth band calculations

#### New Functions

* `initializeDepthBandsMapping(uint256 slot1, uint256 slot2)` - Initialize global bands offset mapping (reinitializer(25))
* `setPairDepthBands(uint256[] indices, PairDepthBands[] depthBands)` - Set depth bands liquidity for multiple pairs
* `setDepthBandsMapping(uint256 slot1, uint256 slot2)` - Configure global bands offset values
* `getPairDepthBands(uint256 pairIndex)` - Get single pair's encoded depth bands
* `getPairDepthBands(uint256[] indices)` - Get multiple pairs' encoded depth bands (array version)
* `getPairDepthBandsDecoded(uint256 pairIndex)` - Get single pair's decoded depth bands
* `getPairDepthBandsDecoded(uint256[] indices)` - Get multiple pairs' decoded depth bands (array version)
* `getDepthBandsMapping()` - Get global bands encoded mapping
* `getDepthBandsMappingDecoded()` - Get global bands decoded mapping

#### New Internal Functions

* `_getDepthBandsPriceImpactP()` - New price impact getter using depth bands
* `_getTotalDepthUsd()` - Extract total depth usd from encoded slot
* `_getBandValue()` - Extract band value from encoded slots (returns ppm for mappings, bps for depths)
* `_calculateDepthBandsPriceImpact()` - Core calculation using trapezoidal rule for average fill price

#### New Constants

* `DEPTH_BANDS_COUNT = 30` - Total number of depth bands
* `DEPTH_BANDS_PER_SLOT1 = 14` - Number of bands stored in slot1
* `HUNDRED_P_BPS = 1e4` - 100% in bps

### Changed

#### Libraries

* `PriceImpactUtils` is now external and has been adjusted for the new bands feature

#### Modified Functions

* `getTradeCumulVolPriceImpactP()` - Now forwards to `_getDepthBandsPriceImpactP` implementation using depth bands

#### Storage Updates

* `IPriceImpact.PriceImpactStorage` struct updated:
  * Added `mapping(uint256 => PairDepthBands) pairDepthBands`
  * Added `DepthBandsMapping depthBandsMapping`
  * Reduced `__gap` array to \[36] to accommodate new storage

### Deprecated

#### Storage

* `pairDepths` - Replaced by `pairDepthBands`

### Removed

#### Functions

* `setPairDepths()` - Replaced by `setPairDepthBands()`
* `getPairDepth()` - Replaced by `getPairDepthBands()`
* `getPairDepths()` - Replaced by array version of `getPairDepthBands()`

### Technical Details

#### Band Structure

**PairDepthBands** (per-pair liquidity configuration):

* Defines the actual liquidity distribution for each trading pair
* 30 bands representing cumulative percentages of total depth (0-100%)
* Each band liquidity percentage stored as basis points (bps), e.g., 2500 = 25% of total depth
* Separate configurations for above/below market price
* Storage encoding per direction:
  * Slot1: totalDepthUsd (32 bits) + bands 0-13 (16 bits each)
  * Slot2: bands 14-29 (16 bits each)

**DepthBandsMapping** (global offset configuration):

* Defines the cumulative offset from mid price at each band boundary
* Values stored as parts per million (ppm), e.g., 130 = 0.013% offset from mid price
* Storage encoding:
  * Slot1: bands 0-13 offsets (16 bits each, first 32 bits unused)
  * Slot2: bands 14-29 offsets (16 bits each)

#### Calculation Method

1. Iterate through bands until trade size is consumed
2. Use trapezoidal rule for average impact within each band
3. Weight each band's contribution by depth consumed
4. Support linear extrapolation beyond 100% for large trades

#### Variable Naming Conventions

* Variables ending in `Usd` represent USD-denominated values (1e18)
* Variables ending in `Ppm` represent parts per million (1e6) => percentage with 4 decimals
* Variables ending in `Bps` represent basis points (1e4) => percentage with 2 decimals
* `priceImpactP` represents price impact percentage in 1e10 precision

#### Migration Path

1. Initialize global depth bands mapping using `initializeDepthBandsMapping()`
2. Migrate existing pairs from old depth model to depth bands
3. New pairs should use `setPairDepthBands()` directly
4. Between deployment and setting bands, dynamic price impact will be 0
5. Monitor and adjust band configurations as needed

### Key Specifications

#### Backwards Compatibility

* **Fully backwards compatible**: The new depth bands system produces identical results to the previous linear formula when configured with linear bands and the same depth values

#### Validation Requirements

* **Pair depth bands**: Must include the value 100% (10,000 bps) as one of the band values and it must be the maximum value
* **Pair depth bands**: Must be non-decreasing across bands since they are cumulative (each band value ≥ previous band value)
* **Global depth offsets**: Must be non-decreasing across bands since they are cumulative (each offset ≥ previous offset)

#### Trade Splitting Protection

* **Cumulative volume price impact**: Has 2x weight in the calculation to ensure trade splitting remains unprofitable
* This design choice prevents traders from gaming the system by splitting large trades into smaller ones

### Gas Optimization

* Efficient storage packing reduces reads to 2 slots per direction + 2 slots for global offsets => 4 slots total
* Early exit from loop when trade size has been consumed