> ## Documentation Index
> Fetch the complete documentation index at: https://tech.ramses.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Concentrated Liquidity & Period-Based Accounting

<div>
  <video width="100%" height="100%" playsInline controls loop>
    <source src="https://gateway.pinata.cloud/ipfs/QmTf6EueKk5ZJ2KQwt1ZCHxRaogYVRci2U5uKRo8NeCmoB" />

    Your browser does not support the video tag.
  </video>
</div>

***

<Note title="Key Differences from Uniswap V3">
  Ramses implements concentrated liquidity based on Uniswap V3's core math, but extends it with:

  * **Period-based accounting system** for weekly reward distribution
  * **Governance-adjustable fees** decoupled from tick spacing
  * **Gauge-integrated emission tracking** at the protocol core
  * **Competitive farming** where in-range, active liquidity earns more
</Note>

## Concentrated Liquidity Overview

Ramses V3 uses concentrated liquidity (as introduced in Uniswap V3), where LPs allocate capital within custom price ranges rather than across the full curve. A position is **in-range** when the current tick falls between its `tickLower` and `tickUpper` — only in-range positions earn swap fees and gauge rewards.

## Ticks and Price Discretization

### Tick Basics

**Ticks** partition continuous price space into discrete boundaries:

* Each tick represents a **0.01% price change**
* Formula: `price = 1.0001^tick`
* Example: tick 0 = price 1.0, tick 100 = price 1.01005

### Tick Spacing

**Tick spacing** determines minimum distance between usable ticks:

| Tick Spacing | Min Price Movement | Use Case                       |
| ------------ | ------------------ | ------------------------------ |
| 1            | 0.01%              | Ultra-stable pairs (USDC/USDT) |
| 10           | 0.10%              | Correlated assets (ETH/stETH)  |
| 60           | 0.60%              | Standard pairs (ETH/USDC)      |
| 200          | 2.00%              | High-volatility pairs          |

**Why tick spacing matters**:

* Tighter spacing = more granular positioning
* Wider spacing = fewer active ticks, lower gas costs
* Matched to expected volatility and pool characteristics

### Tick Crossing

When the price crosses a tick boundary:

1. Contract **switches to new tick interval**
2. **Activates/deactivates** liquidity at that tick
3. **Gas cost increases** for the transaction that crosses the tick
4. **Updates tick state** for fee accrual and period tracking

## Period-Based Accounting System

<Info title="Ramses Innovation">
  This is the most significant difference from Uniswap V3. Ramses implements **weekly period-based accounting** to enable fair gauge reward distribution based on time-weighted active liquidity.
</Info>

### The Problem with Snapshot-Based Rewards

Traditional liquidity mining uses snapshots:

* "You have X liquidity at snapshot time = Y% of rewards"
* Incentivizes gaming: Add liquidity before snapshot, remove after
* Ignores actual contribution over time

### The Ramses Solution: periodSecondsInside

Ramses tracks **how long each position was in-range** during each weekly period:

```solidity theme={null}
periodSecondsInside = seconds the position was active (in-range) during the week
```

**Formula**:

```
Position Reward = (position.periodSecondsInside / pool.totalPeriodSecondsInside) × weeklyEmissions
```

### Technical Implementation

Ramses extends Uniswap V3's tick accounting with additional period tracking:

**Standard Uniswap V3** (Tick.sol):

```solidity theme={null}
struct Info {
    uint128 liquidityGross;
    int128 liquidityNet;
    uint256 feeGrowthOutside0X128;
    uint256 feeGrowthOutside1X128;
    int56 tickCumulativeOutside;
    uint160 secondsPerLiquidityOutsideX128;
    uint32 secondsOutside;
}
```

**Ramses V3 Addition** (Tick.sol + Position.sol):

```solidity theme={null}
struct Info {
    // ... standard fields above ...

    // Period-based tracking
    uint256 periodSecondsPerLiquidityOutsideX128;  // SPL for current period
    mapping(uint256 => uint256) periodSecondsPerLiquidityOutsideBeforeX128;  // Historical periods
}
```

### Period Transitions

Every **Thursday 00:00 UTC**, a new period begins:

1. **Snapshot current state**: Record `secondsPerLiquidity` for all active ticks
2. **Initialize new period**: Reset period counters
3. **Calculate rewards**: Previous period's `periodSecondsInside` determines reward share
4. **Distribute emissions**: Gauges distribute to positions based on their period contribution

### Debt Accounting

To prevent reward gaming, Ramses tracks **debt** for positions that modify liquidity mid-period:

```solidity theme={null}
// When adding liquidity mid-period
position.periodSecondsInsideDebt += newLiquidity × secondsElapsedThisPeriod

// When calculating rewards
effectivePeriodSecondsInside = raw - debt
```

This prevents:

* Adding liquidity just before epoch flip for free rewards
* Counting partial-period liquidity as if it existed the entire week

## Competitive Farming Model

Ramses incentivizes **capital efficiency** through competitive rewards:

### Proximity Bonus

Positions closer to current price earn more per unit liquidity:

```
ETH/USDC pool at $3,000

Position A: $2,950 - $3,050 (100 ticks wide, surrounds price)
Position B: $2,500 - $3,500 (1000 ticks wide)

Position A earns MORE rewards per ETH despite same liquidity amount
```

**Why**: Position A provides liquidity where it's most needed (near current price)

### In-Range Requirement

Only **active liquidity** earns rewards:

* Price in range: Accruing `periodSecondsInside` ✓
* Price out of range: `periodSecondsInside` frozen ✗

**Strategy**: LPs must actively manage positions to keep them in-range

## Integration Considerations

### For Integrators

1. **Query position status**:

```solidity theme={null}
(uint256 tokensOwed0, uint256 tokensOwed1) = pool.positions(positionKey);
```

2. **Calculate periodSecondsInside** (complex, see Position.sol):

```solidity theme={null}
// Requires tick data, period boundaries, and position info
// Best practice: Use view functions from GaugeV3 contract
uint256 earned = gauge.earned(tokenId);
```

3. **Monitor tick crossings** via events:

```solidity theme={null}
event Swap(...);
event Mint(...);
event Burn(...);
```

### Gas Considerations

Period-based accounting adds minor gas overhead:

* **Tick crossing**: +\~5,000 gas for period updates
* **Position operations**: +\~10,000 gas for debt accounting
* **Reward claims**: Similar to standard V3

**Optimization**: Batch operations when possible (multi-position management, claim + collect combos)

## Additional Resources

* [Fees](/concepts/protocol/fees)
* [Token Contracts & Tokenomics](/concepts/tokenomics)
* [Uniswap V3 Whitepaper](https://uniswap.org/whitepaper-v3.pdf) - Core math and design
* [ConsenSys Diligence Audit](https://diligence.security/audits/2024/08/ramses-v3/) - Period accounting analysis

***

[^1]: **Tick interval** refers to the area of price space between two nearest active ticks.