Skip to main content

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.

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

​
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 SpacingMin Price MovementUse Case
10.01%Ultra-stable pairs (USDC/USDT)
100.10%Correlated assets (ETH/stETH)
600.60%Standard pairs (ETH/USDC)
2002.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

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.

​
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: 
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): 
struct Info {
    uint128 liquidityGross;
    int128 liquidityNet;
    uint256 feeGrowthOutside0X128;
    uint256 feeGrowthOutside1X128;
    int56 tickCumulativeOutside;
    uint160 secondsPerLiquidityOutsideX128;
    uint32 secondsOutside;
}
Ramses V3 Addition (Tick.sol + Position.sol): 
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: 
// 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:
(uint256 tokensOwed0, uint256 tokensOwed1) = pool.positions(positionKey);
  1. Calculate periodSecondsInside (complex, see Position.sol):
// Requires tick data, period boundaries, and position info
// Best practice: Use view functions from GaugeV3 contract
uint256 earned = gauge.earned(tokenId);
  1. Monitor tick crossings via events:
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