GyroscopePool

class GyroscopePool

Bases: AbstractPool

Elliptical Concentrated Liquidity Pool (ECLP) implementation.

The ECLP is an automated market maker (AMM) design that uses elliptical geometry to define the trading curve. It provides concentrated liquidity within a specified price range while maintaining smooth price discovery.

Key Features: - Price bounds (alpha, beta) define valid trading range - Rotation angle (phi) and scaling factor (lambda) control curve shape - Supports fee-based and zero-fee trading - Optimizes parameters to achieve target weights - Compatible with LVR (Liquidity Value at Risk) hooks

The pool is defined by: - Elliptical trading curve rotated by phi - Price range [alpha, beta] for valid trades - Lambda parameter controlling curve eccentricity - Optional trading fees and arbitrage thresholds

The implementation follows the E-CLP paper, using JAX for efficient computation of reserves and weights. The pool maintains both public interfaces for normal operation and protected implementations for use by hooks and internal calculations.

Parameters:

• params (Dict[str, Any]) – Pool parameters including alpha, beta, lambda, and phi

• run_fingerprint (Dict[str, Any]) – Configuration settings for the simulation run

• prices (jnp.ndarray) – Asset prices over time

• start_index (jnp.ndarray) – Starting indices for price windows

• additional_oracle_input (Optional[jnp.ndarray]) – Additional input data from oracles

Notes

• Only supports exactly 2 assets

• Uses JAX for efficient computation

• Implements equations from “The Elliptic Concentrated Liquidity Pool” paper

• Maintains original implementation access for hooks via protected methods

• Weights are derived empirically from zero-fee reserve calculations

__init__()

calculate_reserves_with_fees(params, run_fingerprint, prices, start_index, additional_oracle_input=None)

Calculate reserves for ECLP pool including trading fees.

This method computes pool reserves over time considering trading fees and arbitrage thresholds. It follows Appendix A of the E-CLP paper, applying the calculations at each timestep.

Parameters:

• params (Dict[str, Any]) –

  Pool parameters including:

  • alphafloat

    Lower price bound

  • betafloat

    Upper price bound

  • phifloat

    Rotation angle

  • lamfloat

    Scaling factor

• run_fingerprint (Dict[str, Any]) –

  Run configuration including:

  • feesfloat

    Trading fee percentage

  • gas_costfloat

    Arbitrage threshold

  • arb_feesfloat

    Additional arbitrage fees

• prices (jnp.ndarray) – Asset prices over time, shape (T, 2)

• start_index (jnp.ndarray) – Starting indices for price windows

• additional_oracle_input (Optional[jnp.ndarray], optional) – Additional oracle data if needed

Returns:

Calculated reserves over time, shape (T, 2)

Return type:

jnp.ndarray

Notes

The implementation handles numeraire ordering internally and restores the original order before returning.

calculate_reserves_zero_fees(params, run_fingerprint, prices, start_index, additional_oracle_input=None)

Public interface for zero-fee reserve calculation.

This method can be safely overridden by hooks (e.g., LVR) while still allowing access to the original implementation through the protected _calculate_reserves_zero_fees method.

Parameters:

• params (Dict[str, Any])

• run_fingerprint (Dict[str, Any])

• prices (Array)

• start_index (Array)

• additional_oracle_input (Array | None)

Return type:

Array

calculate_reserves_with_dynamic_inputs(params, run_fingerprint, prices, start_index, fees_array, arb_thresh_array, arb_fees_array, trade_array, lp_supply_array=None, additional_oracle_input=None)

Parameters:

• params (Dict[str, Any])

• run_fingerprint (Dict[str, Any])

• prices (Array)

• start_index (Array)

• fees_array (Array)

• arb_thresh_array (Array)

• arb_fees_array (Array)

• trade_array (Array)

• lp_supply_array (Array)

• additional_oracle_input (Array | None)

Return type:

Array

init_base_parameters(initial_values_dict, run_fingerprint, n_assets, n_parameter_sets=1, noise='gaussian')

Initialize parameters for an ECLP pool.

ECLP pools have four base parameters: - rotation angle Phi: Controls the rotation of the ellipse - scaling factor Lambda: Controls the eccentricity of the ellipse - Lower price bound alpha: Minimum price ratio between assets - Upper price bound beta: Maximum price ratio between assets

Parameters:

• initial_values_dict (Dict[str, Any]) – Dictionary containing initial values for the parameters

• run_fingerprint (Dict[str, Any]) – Dictionary containing run configuration settings

• n_assets (int) – Number of assets in the pool (must be 2 for ECLP)

• n_parameter_sets (int, optional) – Number of parameter sets to initialize, by default 1

• noise (str, optional) – Type of noise to apply during initialization, by default “gaussian”

Returns:

Dictionary containing initialized parameters: - phi: Rotation angle - lambda: Scaling factor - alpha: Lower price bound - beta: Upper price bound

Return type:

Dict[str, Any]

Raises:

ValueError – If n_assets is not 2 or if required initial values are missing

is_trainable()

weights_needs_original_methods()

ECLP pools need original methods for weight calculation.

Returns:

True - ECLP weight calculation requires original pool methods.

Return type:

bool

Notes

This is because the weights are calculated based on the reserves that the pool has when run in the zero-fees case, and the empirical weights are derived from the empirical division of value between reserve over time. This also means that we need to preserve the original reserve calculation method in the original pool class as a classmethod.

calculate_weights(params, run_fingerprint, prices, start_index, additional_oracle_input=None)

Calculate empirical weights for ECLP pool.

ECLP pools do not have weights in the same way as other pools, such as G3M pools or FM-AMM pools. Therefore, the weights are calculated based on the reserves that the pool has when run in the zero-fees case, and the empirical weights are derived from the empirical division of value between reserve over time. This method: 1. Calculates zero-fee reserves 2. Computes value distribution using prices 3. Returns normalized weights

Parameters:

• params (Dict[str, Any]) – The parameters for the pool.

• run_fingerprint (Dict[str, Any]) – The fingerprint of the current run.

• prices (jnp.ndarray) – The prices of the assets.

• start_index (jnp.ndarray) – The starting index for the prices.

• additional_oracle_input (Optional[jnp.ndarray]) – Additional input from the oracle, if any.

Returns:

The calculated weights for the ECLP pool.

Return type:

jnp.ndarray

Notes

This method uses the protected _calculate_reserves_zero_fees implementation to ensure consistent weight calculation even when hooks override the public interface. It is only called in the ‘versus rebalancing’ hooks.

classmethod process_parameters(update_rule_parameters, run_fingerprint)

Process gyroscope pool parameters from web interface input.