What causes "Liquidity addition overflow: x={current}, y={y}, delta={delta}" in nautechsystems/nautilus_trader?

Use try_liquidity_math_add to handle the Overflow error gracefully

Liquidity addition overflow: x={current}, y={y}, delta={delt

Error message

Liquidity addition overflow: x={current}, y={y}, delta={delta}

What it means

liquidity_math_add() converts the fallible try_liquidity_math_add result into a panic when adding a positive delta would overflow u128 liquidity. The checked version exists (try_liquidity_math_add / LiquidityMathError::Overflow) so callers needing graceful handling should use that instead.

Source

Thrown at crates/model/src/defi/tick_map/liquidity_math.rs:64

/// with surrounding context is preferred. This panic-style variant is kept for
/// in-pool invariants where overflow is treated as a contract bug rather than an
/// expected runtime error.
///
/// # Returns
///
/// The resulting liquidity after applying the delta.
///
/// # Panics
///
/// This function panics if:
/// - Adding positive delta causes overflow.
/// - Subtracting causes underflow.
#[must_use]
pub fn liquidity_math_add(x: u128, y: i128) -> u128 {
    match try_liquidity_math_add(x, y) {
        Ok(value) => value,
        Err(LiquidityMathError::Overflow { current, delta }) => {
            panic!("Liquidity addition overflow: x={current}, y={y}, delta={delta}")
        }
        Err(LiquidityMathError::Underflow { current, delta }) => {
            panic!("Liquidity subtraction underflow: x={current}, y={y}, delta={delta}")
        }
    }
}

/// Derives max liquidity per tick from a given tick spacing.
///
/// # Panics
///
/// Panics if `tick_spacing` is zero.
#[must_use]
pub fn tick_spacing_to_max_liquidity_per_tick(tick_spacing: i32) -> u128 {
    assert!(tick_spacing != 0, "Tick spacing must be non-zero");

    // Calculate min and max tick aligned to tick spacing
    let min_tick = (PoolTick::MIN_TICK / tick_spacing) * tick_spacing;

View on GitHub (pinned to 18893faf8b)

Solutions

Use try_liquidity_math_add to handle the Overflow error gracefully
Clamp or validate liquidity values before repeated additions
Audit the accumulation loop for double-added deltas (e.g. same tick applied twice)

Example fix

// before
let liquidity = liquidity_math_add(current, delta); // panics on overflow
// after
match try_liquidity_math_add(current, delta) {
    Ok(liquidity) => /* use it */,
    Err(e) => /* handle overflow/underflow */,
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check the addition
fn add_will_not_overflow(x: u128, y: i128) -> bool {
    y <= 0 || x.checked_add(y as u128).is_some()
}

Try / catch

let liquidity = try_liquidity_math_add(x, y)
    .map_err(|e| format!("liquidity math failed: {e:?}"))?;

Prevention

Prefer try_liquidity_math_add in non-test code
Clamp liquidity inputs to plausible on-chain ranges
Audit accumulation loops for repeated/double additions

When it happens

Trigger: Calling liquidity_math_add(x, y) where x + y as positive delta exceeds u128::MAX; triggered transitively by apply_swap_quote or update_liquidity on corrupt/absurd liquidity values.

Common situations: Aggregating liquidity across many positions with unit mismatches (double-counting); feeding raw unclamped on-chain values; bugs in tick-crossing loops that add the same liquidity repeatedly.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/cdbb859482ae3a5e. Report an issue: GitHub.