> For the complete documentation index, see [llms.txt](https://docs.flowx.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowx.finance/developer/flowx-clmm-guideline.md).
# FlowX CLMM Guideline
A concentrated liquidity market maker (CLMM) protocol built on the Sui blockchain, inspired by Uniswap v3. FlowX CLMM allows liquidity providers to concentrate their capital within custom price ranges
### ๐ Overview
FlowX CLMM implements a concentrated liquidity model with the following core features:
#### ๐ฏ Key Features
| Feature | Description |
| -------------------------- | ------------------------------------------------ |
| **Concentrated Liquidity** | Capital efficiency through custom price ranges |
| **Multiple Fee Tiers** | Flexible fee structures (0.01%, 0.05%, 0.3%, 1%) |
| **Position Management** | NFT-based position tracking and management |
| **Protocol Rewards** | Built-in reward distribution system |
| **Oracle Integration** | Price feeds and historical data tracking |
| **Modular Architecture** | Clean separation with versioning support |
#### ๐ฐ Benefits
* **For Liquidity Providers**: Higher capital efficiency and customizable risk exposure
* **For Traders**: Lower slippage and better price discovery
* **For Developers**: Modular design for easy integration and extension
#### ๐๏ธ Architecture
**Core Modules**
**๐ฆ Pool Manager (`pool_manager.move`)**
Central registry for all pools in the protocol.
* Pool creation and registration
* Fee tier management
* Administrative functions
* Protocol fee collection
**๐ Pool (`pool.move`)**
Individual pool implementation containing the core AMM logic.
* Liquidity management
* Swap execution
* Tick state management
* Oracle data collection
* Reward distribution
**๐ Position Manager (`position_manager.move`)**
Manages the lifecycle of liquidity positions.
* Position creation and closure
* Liquidity adjustments
* Fee collection
* Reward claiming
**๐ Swap Router (`swap_router.move`)**
Handles swap execution with various input/output specifications.
* Exact input/output swaps
* Price limit enforcement
* Slippage protection
### ๐ง Core Functions
#### ๐ Pool Management
create_pool_v2 - Create a new liquidity pool
Creates a new liquidity pool for token pair X/Y with specified fee rate.
```move
public fun create_pool_v2(
self: &mut PoolRegistry,
fee_rate: u64,
metadata_x: &CoinMetadata,
metadata_y: &CoinMetadata,
versioned: &Versioned,
ctx: &mut TxContext
)
```
**Parameters:**
* `fee_rate`: Fee rate in basis points (e.g., 3000 = 0.3%)
* `metadata_x/y`: Coin metadata for validation
* `versioned`: Package version validation
**Example:**
```move
// Create a new USDC/SUI pool with 0.3% fee
// Note: Fee rate must be enabled first via enable_fee_rate_for_testing in tests
pool_manager::create_pool_v2(
&mut pool_registry,
3000, // 0.3% fee tier
&usdc_metadata,
&sui_metadata,
&versioned,
ctx
);
```
create_and_initialize_pool_v2 - Create and initialize pool with price
Creates and initializes a new pool in a single transaction with an initial price.
```move
public fun create_and_initialize_pool_v2(
self: &mut PoolRegistry,
fee_rate: u64,
sqrt_price: u128,
metadata_x: &CoinMetadata,
metadata_y: &CoinMetadata,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
)
```
**Parameters:**
* `sqrt_price`: Initial square root price as Q64.64 fixed-point number
* Additional parameters same as `create_pool_v2`
**Example:**
```move
// Create and initialize USDC/SUI pool with initial price of 1 USDC = 2 SUI
// sqrt_price = sqrt(0.5) * 2^64 for price of 0.5 USDC per SUI
let initial_sqrt_price = 13043817825332782212; // sqrt(0.5) in Q64.64 format
pool_manager::create_and_initialize_pool_v2(
&mut pool_registry,
3000, // 0.3% fee tier
initial_sqrt_price,
&usdc_metadata,
&sui_metadata,
&versioned,
&clock,
ctx
);
```
#### ๐ Position Management
open_position - Open a new liquidity position
Opens a new liquidity position within specified tick range.
```move
public fun open_position(
self: &mut PositionRegistry,
pool_registry: &PoolRegistry,
fee_rate: u64,
tick_lower_index: I32,
tick_upper_index: I32,
versioned: &Versioned,
ctx: &mut TxContext
): Position
```
**Example:**
```move
let position = position_manager::open_position(
&mut position_registry,
&pool_registry,
3000, // 0.3% fee
tick_lower,
tick_upper,
&versioned,
ctx
);
```
**Complete Liquidity Provider Workflow Example:**
```move
// 1. Calculate tick range for price range $1.80 - $2.20 per SUI
// Assuming USDC has 6 decimals and SUI has 9 decimals
let lower_price = 1_800000; // $1.80 in USDC units (6 decimals)
let upper_price = 2_200000; // $2.20 in USDC units (6 decimals)
// Convert prices to sqrt prices (Q64.64 format)
let lower_sqrt_price = price_to_sqrt_price(lower_price, 6, 9);
let upper_sqrt_price = price_to_sqrt_price(upper_price, 6, 9);
// Convert sqrt prices to ticks
let tick_lower = tick_math::get_tick_at_sqrt_price(lower_sqrt_price);
let tick_upper = tick_math::get_tick_at_sqrt_price(upper_sqrt_price);
// 2. Open position in the calculated range
let position = position_manager::open_position(
&mut position_registry,
&pool_registry,
3000, // 0.3% fee tier
tick_lower,
tick_upper,
&versioned,
ctx
);
```
**Parameters:**
* `self`: Mutable reference to the position registry
* `pool_registry`: Reference to the pool registry for validation
* `fee_rate`: Pool fee rate in basis points (e.g., 3000 = 0.3%)
* `tick_lower_index`: Lower bound of the price range as tick index
* `tick_upper_index`: Upper bound of the price range as tick index
* `versioned`: Reference for package version validation
* `ctx`: Transaction context
**Returns:**
* `Position`: New position NFT for tracking and management
increase_liquidity - Add liquidity to position
Adds liquidity to an existing position with slippage protection.
```move
public fun increase_liquidity(
self: &mut PoolRegistry,
position: &mut Position,
x_in: Coin,
y_in: Coin,
amount_x_min: u64,
amount_y_min: u64,
deadline: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
)
```
**Parameters:**
* `self`: Mutable reference to the pool registry
* `position`: Mutable reference to the position to add liquidity to
* `x_in`: Coin of token X to add as liquidity
* `y_in`: Coin of token Y to add as liquidity
* `amount_x_min`: Minimum amount of X tokens to add (slippage protection)
* `amount_y_min`: Minimum amount of Y tokens to add (slippage protection)
* `deadline`: Transaction deadline timestamp to prevent stale transactions
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* Excess tokens are automatically refunded to the caller
**Example:**
```move
// Add 1000 USDC and 2000 SUI to position with slippage protection
let usdc_coins = coin::mint_for_testing(1000_000000, ctx); // 1000 USDC (6 decimals)
let sui_coins = coin::mint_for_testing(2000_000000000, ctx); // 2000 SUI (9 decimals)
let deadline = clock::timestamp_ms(&clock) + 300_000; // 5 minutes from now
position_manager::increase_liquidity(
&mut pool_registry,
&mut position,
usdc_coins,
sui_coins,
950_000000, // Min 950 USDC (5% slippage tolerance)
1900_000000000, // Min 1900 SUI (5% slippage tolerance)
deadline,
&versioned,
&clock,
ctx
);
```
decrease_liquidity - Remove liquidity from position
Removes liquidity from a position and returns tokens.
```move
public fun decrease_liquidity(
self: &mut PoolRegistry,
position: &mut Position,
liquidity: u128,
amount_x_min: u64,
amount_y_min: u64,
deadline: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
)
```
**Parameters:**
* `self`: Mutable reference to the pool registry
* `position`: Mutable reference to the position to remove liquidity from
* `liquidity`: Amount of liquidity to remove (in liquidity units)
* `amount_x_min`: Minimum amount of X tokens to receive (slippage protection)
* `amount_y_min`: Minimum amount of Y tokens to receive (slippage protection)
* `deadline`: Transaction deadline timestamp to prevent stale transactions
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* Token balances proportional to the liquidity removed
**Example:**
```move
// Remove 50% of position liquidity
let current_liquidity = position::liquidity(&position);
let liquidity_to_remove = current_liquidity / 2;
let deadline = clock::timestamp_ms(&clock) + 300_000; // 5 minutes from now
position_manager::decrease_liquidity(
&mut pool_registry,
&mut position,
liquidity_to_remove,
100_000000, // Min 100 USDC expected
200_000000000, // Min 200 SUI expected
deadline,
&versioned,
&clock,
ctx
);
```
#### ๐ฐ Fee & Reward Collection
collect - Collect accumulated fees
Collects accumulated trading fees from a position.
```move
public fun collect(
self: &mut PoolRegistry,
position: &mut Position,
amount_x_requested: u64,
amount_y_requested: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): (Coin, Coin)
```
**Parameters:**
* `self`: Mutable reference to the pool registry
* `position`: Mutable reference to the position to collect fees from
* `amount_x_requested`: Maximum amount of X token fees to collect
* `amount_y_requested`: Maximum amount of Y token fees to collect
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `(Coin, Coin)`: Tuple of collected fee coins for both tokens
**Example:**
```move
// Collect all accumulated trading fees from position
let (usdc_fees, sui_fees) = position_manager::collect(
&mut pool_registry,
&mut position,
18446744073709551615, // Max u64 to collect all USDC fees
18446744073709551615, // Max u64 to collect all SUI fees
&versioned,
&clock,
ctx
);
// Use collected fees
let usdc_fee_amount = coin::value(&usdc_fees);
let sui_fee_amount = coin::value(&sui_fees);
// Transfer to treasury or reinvest
```
collect_pool_reward - Collect reward tokens
Collects accumulated reward tokens for a position.
```move
public fun collect_pool_reward(
self: &mut PoolRegistry,
position: &mut Position,
amount_requested: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): Coin
```
**Parameters:**
* `self`: Mutable reference to the pool registry
* `position`: Mutable reference to the position to collect rewards from
* `amount_requested`: Maximum amount of reward tokens to collect
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Type Parameters:**
* `X`: First token type of the pool
* `Y`: Second token type of the pool
* `RewardCoinType`: Type of the reward token to collect
**Returns:**
* `Coin`: Collected reward tokens of the specified type
**Example:**
```move
// Collect FLOW reward tokens from USDC/SUI position
let flow_rewards = position_manager::collect_pool_reward(
&mut pool_registry,
&mut position,
18446744073709551615, // Max u64 to collect all available FLOW rewards
&versioned,
&clock,
ctx
);
let reward_amount = coin::value(&flow_rewards);
// Transfer rewards to user wallet
transfer::public_transfer(flow_rewards, tx_context::sender(ctx));
```
#### ๐ Swap Functions
Exact Input Swaps - Swap exact amount in for maximum out
```move
// Swap exact X for maximum Y
public fun swap_exact_x_to_y(
pool: &mut Pool,
coin_in: Coin,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &TxContext
): Balance
// Swap exact Y for maximum X
public fun swap_exact_y_to_x(
pool: &mut Pool,
coin_in: Coin,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &TxContext
): Balance
```
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: Input tokens to swap (entire amount will be consumed)
* `sqrt_price_limit`: Price limit for slippage protection:
* For XโY swaps: Maximum acceptable sqrt price after swap (price decreasing)
* For YโX swaps: Minimum acceptable sqrt price after swap (price increasing)
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance` or `Balance`: Output token balance from the swap
**Use Case:** When you want to swap all of a token
**Example:**
```move
// Swap 1000 USDC for maximum SUI possible
let usdc_in = coin::mint_for_testing(1000_000000, ctx); // 1000 USDC
let current_sqrt_price = pool::sqrt_price_current(&pool);
let min_sqrt_price = (current_sqrt_price * 95) / 100; // 5% slippage tolerance
let sui_out = swap_router::swap_exact_x_to_y(
&mut pool,
usdc_in,
min_sqrt_price,
&versioned,
&clock,
ctx
);
let sui_amount_received = balance::value(&sui_out);
// Convert balance to coin if needed
let sui_coin = coin::from_balance(sui_out, ctx);
```
Exact Output Swaps - Swap minimum in for exact amount out
```move
// Swap minimum X for exact Y
public fun swap_x_to_exact_y(
pool: &mut Pool,
coin_in: Coin,
amount_out: u64,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &TxContext
): Balance
// Swap minimum Y for exact X
public fun swap_y_to_exact_x(
pool: &mut Pool,
coin_in: Coin,
amount_out: u64,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &TxContext
): Balance
```
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: Input tokens to swap (excess will be refunded)
* `amount_out`: Exact amount of output tokens to receive
* `sqrt_price_limit`: Price limit for slippage protection:
* For XโY swaps: Maximum acceptable sqrt price after swap
* For YโX swaps: Minimum acceptable sqrt price after swap
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance` or `Balance`: Exact amount of output tokens requested
**Use Case:** When you need a precise output amount
**Example:**
```move
// Swap minimum USDC needed to get exactly 500 SUI
let usdc_in = coin::mint_for_testing(2000_000000, ctx); // 2000 USDC (excess will be refunded)
let desired_sui_out = 500_000000000; // Exactly 500 SUI (9 decimals)
let current_sqrt_price = pool::sqrt_price_current(&pool);
let max_sqrt_price = (current_sqrt_price * 105) / 100; // 5% slippage tolerance
let sui_out = swap_router::swap_x_to_exact_y(
&mut pool,
usdc_in, // Will be split internally, excess refunded
desired_sui_out,
max_sqrt_price,
&versioned,
&clock,
ctx
);
// Verify exact amount received
assert!(balance::value(&sui_out) == desired_sui_out, 0);
let sui_coin = coin::from_balance(sui_out, ctx);
```
### ๐ API Reference
This section provides detailed parameter descriptions for all core functions.
#### Pool Management Functions
| Function | Purpose | Access Level |
| ------------------------------------- | ------------------------------------------------------------------ | ------------ |
| `create_pool_v2` | Creates a new liquidity pool for token pair X/Y | Public |
| `create_and_initialize_pool_v2` | Creates and initializes pool with initial price in one transaction | Public |
**create\_pool\_v2\**
* **Purpose**: Creates a new liquidity pool for token pair X/Y
* **Fee Rate**: Must be previously enabled (e.g., 3000 for 0.3%)
* **Access**: Public - can be called by any user
**create\_and\_initialize\_pool\_v2\**
* **Purpose**: Creates and initializes pool with initial price in one transaction
* **Initial Price**: Specified as Q64.64 fixed-point sqrt price
* **Access**: Public - can be called by any user
#### Position Management Functions
| Function | Purpose | Returns |
| ---------------------------------------- | -------------------------------------------------------- | ------------------- |
| `open_position` | Opens new liquidity position within specified tick range | Position NFT |
| `close_position` | Closes empty position and destroys NFT | None |
| `increase_liquidity` | Adds liquidity to existing position | Auto-refunds excess |
| `decrease_liquidity` | Removes liquidity from position | Token balances |
| `collect` | Collects accumulated trading fees from position | Fee coins |
| `collect_pool_reward` | Collects reward tokens earned by position | Reward coins |
**open\_position\**
* **Purpose**: Opens new liquidity position within specified tick range
* **Tick Range**: Must respect pool's tick spacing requirements
* **Returns**: Position NFT for tracking and management
**increase\_liquidity\**
* **Purpose**: Adds liquidity to existing position
* **Slippage Protection**: `amount_x_min` and `amount_y_min` parameters
* **Auto-refund**: Excess tokens automatically returned
* **Deadline**: Prevents execution of stale transactions
**decrease\_liquidity\**
* **Purpose**: Removes liquidity from position
* **Returns**: Token balances proportional to liquidity removed
* **Minimum Output**: Slippage protection via `amount_x_min`/`amount_y_min`
**collect\**
* **Purpose**: Collects accumulated trading fees from position
* **Fee Collection**: Specify maximum amounts to collect
* **Returns**: Collected fee balances for both tokens
**collect\_pool\_reward\**
* **Purpose**: Collects reward tokens earned by position
* **Reward Type**: Specify exact reward token type
* **Returns**: Coin of specified reward token type
**close\_position**
* **Purpose**: Closes empty position and destroys NFT
* **Requirements**: Position must have zero liquidity, fees, and rewards
#### Swap Functions
| Function Category | Functions | Use Case |
| --------------------- | ---------------------------------------- | --------------------------------------------- |
| **Exact Input** | `swap_exact_x_to_y`, `swap_exact_y_to_x` | Swap all tokens for maximum output |
| **Exact Output** | `swap_x_to_exact_y`, `swap_y_to_exact_x` | Use minimum input for precise output |
| **High-Level Router** | `swap_exact_input`, `swap_exact_output` | Simplified interface with auto pool selection |
**Exact Input Swaps**
* **swap\_exact\_x\_to\_y**: Swap all X tokens for maximum Y tokens
* **swap\_exact\_y\_to\_x**: Swap all Y tokens for maximum X tokens
* **Use Case**: When you want to sell entire token balance
**Exact Output Swaps**
* **swap\_x\_to\_exact\_y**: Use minimum X tokens to get exact Y amount
* **swap\_y\_to\_exact\_x**: Use minimum Y tokens to get exact X amount
* **Use Case**: When you need precise output amount
**High-Level Router Functions**
* **swap\_exact\_input**: Router function for exact input swaps with deadline validation
* **swap\_exact\_output**: Router function for exact output swaps with deadline validation
* **Use Case**: Simplified interface for common swap operations with automatic pool selection
#### Swap Functions
**`swap_exact_x_to_y(pool, coin_in, sqrt_price_limit, versioned, clock, ctx)`**
Swaps an exact amount of token X for token Y.
```move
public fun swap_exact_x_to_y(
pool: &mut Pool,
coin_in: Coin,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &TxContext
): Balance
```
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: X tokens to swap (entire amount will be consumed)
* `sqrt_price_limit`: Maximum acceptable sqrt price after swap (slippage protection)
* `versioned`: Reference to versioned object for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance`: Resulting Y token balance from the swap
**`swap_exact_y_to_x(pool, coin_in, sqrt_price_limit, versioned, clock, ctx)`**
Swaps an exact amount of token Y for token X.
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: Y tokens to swap (entire amount will be consumed)
* `sqrt_price_limit`: Minimum acceptable sqrt price after swap (slippage protection)
* `versioned`: Reference to versioned object for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance`: Resulting X token balance from the swap
**`swap_x_to_exact_y(pool, coin_in, amount_out, sqrt_price_limit, versioned, clock, ctx)`**
Swaps token X for an exact amount of token Y.
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: X tokens to swap (excess will be refunded)
* `amount_out`: Exact amount of Y tokens to receive
* `sqrt_price_limit`: Maximum acceptable sqrt price after swap
* `versioned`: Reference to versioned object for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance`: Exact amount of Y tokens requested
**`swap_y_to_exact_x(pool, coin_in, amount_out, sqrt_price_limit, versioned, clock, ctx)`**
Swaps token Y for an exact amount of token X.
**Parameters:**
* `pool`: Mutable reference to the pool to execute swap in
* `coin_in`: Y tokens to swap (excess will be refunded)
* `amount_out`: Exact amount of X tokens to receive
* `sqrt_price_limit`: Minimum acceptable sqrt price after swap
* `versioned`: Reference to versioned object for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Balance`: Exact amount of X tokens requested
**`swap_exact_input(pool_registry, fee, coin_in, amount_out_min, sqrt_price_limit, deadline, versioned, clock, ctx)`**
High-level router function for exact input swaps with automatic pool selection and deadline validation.
```move
public fun swap_exact_input(
pool_registry: &mut PoolRegistry,
fee: u64,
coin_in: Coin,
amount_out_min: u64,
sqrt_price_limit: u128,
deadline: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): Coin
```
**Parameters:**
* `pool_registry`: Mutable reference to the pool registry
* `fee`: Pool fee rate to select the correct pool
* `coin_in`: Input tokens to swap (entire amount will be consumed)
* `amount_out_min`: Minimum amount of output tokens expected (slippage protection)
* `sqrt_price_limit`: Price limit for slippage protection
* `deadline`: Transaction deadline timestamp to prevent stale transactions
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Coin`: Output token coin from the swap
**Features:**
* Automatic token ordering (handles both XโY and YโX directions)
* Built-in deadline validation
* Minimum output amount validation
* Simplified interface for common swap operations
**`swap_exact_output(pool_registry, fee, coin_in, amount_out, sqrt_price_limit, deadline, versioned, clock, ctx)`**
High-level router function for exact output swaps with automatic pool selection and deadline validation.
```move
public fun swap_exact_output(
pool_registry: &mut PoolRegistry,
fee: u64,
coin_in: Coin,
amount_out: u64,
sqrt_price_limit: u128,
deadline: u64,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): Coin
```
**Parameters:**
* `pool_registry`: Mutable reference to the pool registry
* `fee`: Pool fee rate to select the correct pool
* `coin_in`: Input tokens to swap (excess will be refunded)
* `amount_out`: Exact amount of output tokens to receive
* `sqrt_price_limit`: Price limit for slippage protection
* `deadline`: Transaction deadline timestamp to prevent stale transactions
* `versioned`: Reference for package version validation
* `clock`: Clock object for timing validation
* `ctx`: Transaction context
**Returns:**
* `Coin`: Exact amount of output tokens requested
**Features:**
* Automatic token ordering (handles both XโY and YโX directions)
* Built-in deadline validation
* Automatic refund of excess input tokens
* Simplified interface for precise output amount swaps
### ๐ก Developer Guide
#### ๐ฏ Complete End-to-End Example
Here's a comprehensive example showing how to create a pool, provide liquidity, perform swaps, and collect fees:
```move
public fun complete_clmm_example(
pool_registry: &mut PoolRegistry,
position_registry: &mut PositionRegistry,
usdc_metadata: &CoinMetadata,
sui_metadata: &CoinMetadata,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
) {
// 1. Create and initialize pool
let initial_sqrt_price = 13043817825332782212; // sqrt(0.5) for 1 USDC = 2 SUI
pool_manager::create_and_initialize_pool_v2(
pool_registry,
3000, // 0.3% fee
initial_sqrt_price,
usdc_metadata,
sui_metadata,
versioned,
clock,
ctx
);
// 2. Open position in price range $1.80 - $2.20 per SUI
let lower_sqrt_price = 11832159566199029792; // sqrt(1/2.20)
let upper_sqrt_price = 14142135623730950624; // sqrt(1/1.80)
let tick_lower = tick_math::get_tick_at_sqrt_price(lower_sqrt_price);
let tick_upper = tick_math::get_tick_at_sqrt_price(upper_sqrt_price);
let position = position_manager::open_position(
position_registry,
pool_registry,
3000,
tick_lower,
tick_upper,
versioned,
ctx
);
// 3. Add liquidity to position
let usdc_coins = coin::mint_for_testing(10000_000000, ctx); // 10,000 USDC
let sui_coins = coin::mint_for_testing(20000_000000000, ctx); // 20,000 SUI
let deadline = clock::timestamp_ms(clock) + 300_000; // 5 minutes
position_manager::increase_liquidity(
pool_registry,
&mut position,
usdc_coins,
sui_coins,
9500_000000, // Min 9,500 USDC (5% slippage)
19000_000000000, // Min 19,000 SUI (5% slippage)
deadline,
versioned,
clock,
ctx
);
// 4. Perform a swap (someone else trades)
let trader_usdc = coin::mint_for_testing(1000_000000, ctx); // 1,000 USDC
let pool = pool_manager::borrow_mut_pool(pool_registry, 3000);
let current_sqrt_price = pool::sqrt_price_current(pool);
let min_sqrt_price = (current_sqrt_price * 95) / 100; // 5% slippage
let sui_out = swap_router::swap_exact_x_to_y(
pool,
trader_usdc,
min_sqrt_price,
versioned,
clock,
ctx
);
// 5. Collect accumulated fees after some trading activity
let (usdc_fees, sui_fees) = position_manager::collect(
pool_registry,
&mut position,
18446744073709551615, // Collect all fees (max u64)
18446744073709551615,
versioned,
clock,
ctx
);
// 6. Collect any reward tokens (if available)
let rewards = position_manager::collect_pool_reward(
pool_registry,
&mut position,
18446744073709551615, // Collect all rewards (max u64)
versioned,
clock,
ctx
);
// 7. Remove liquidity when done
let position_liquidity = position::liquidity(&position);
let remove_deadline = clock::timestamp_ms(clock) + 300_000;
position_manager::decrease_liquidity(
pool_registry,
&mut position,
position_liquidity, // Remove all liquidity
0, // Accept any amount (or set minimums)
0,
remove_deadline,
versioned,
clock,
ctx
);
// 8. Close empty position
position_manager::close_position(position_registry, position, versioned, ctx);
// Transfer collected fees and rewards
transfer::public_transfer(usdc_fees, tx_context::sender(ctx));
transfer::public_transfer(sui_fees, tx_context::sender(ctx));
transfer::public_transfer(rewards, tx_context::sender(ctx));
transfer::public_transfer(coin::from_balance(sui_out, ctx), tx_context::sender(ctx));
}
```
#### ๐ Quick Integration Examples
**Basic Liquidity Provision**
```move
// 1. Open position
let position = position_manager::open_position(
&mut position_registry,
&pool_registry,
3000, // 0.3% fee
tick_lower,
tick_upper,
&versioned,
ctx
);
// 2. Add liquidity
position_manager::increase_liquidity(
&mut pool_registry,
&mut position,
usdc_coins,
sui_coins,
min_usdc_amount,
min_sui_amount,
deadline,
&versioned,
&clock,
ctx
);
```
**Basic Token Swap**
```move
// Swap exact USDC for maximum SUI
let sui_out = swap_router::swap_exact_x_to_y(
&mut pool,
usdc_in,
min_sqrt_price, // Slippage protection
&versioned,
&clock,
ctx
);
```
**Router Function Examples**
```move
// High-level exact input swap with automatic pool selection
let usdc_in = coin::mint_for_testing(1000_000000, ctx); // 1000 USDC
let deadline = clock::timestamp_ms(&clock) + 300_000; // 5 minutes
let current_sqrt_price = pool::sqrt_price_current(&pool);
let min_sqrt_price = (current_sqrt_price * 95) / 100; // 5% slippage
let sui_out = swap_router::swap_exact_input(
&mut pool_registry,
3000, // 0.3% fee pool
usdc_in,
1900_000000000, // Min 1900 SUI output (5% slippage)
min_sqrt_price,
deadline,
&versioned,
&clock,
ctx
);
// High-level exact output swap with automatic pool selection
let usdc_in = coin::mint_for_testing(2000_000000, ctx); // 2000 USDC (excess refunded)
let exact_sui_out = 500_000000000; // Exactly 500 SUI
let max_sqrt_price = (current_sqrt_price * 105) / 100; // 5% slippage
let sui_out = swap_router::swap_exact_output(
&mut pool_registry,
3000, // 0.3% fee pool
usdc_in, // Excess will be refunded
exact_sui_out,
max_sqrt_price,
deadline,
&versioned,
&clock,
ctx
);
// Verify exact amount received
assert!(coin::value(&sui_out) == exact_sui_out, 0);
```
**Swap Best Practices**
**Swap Flow:**
1. **Input Validation**: Checks pool state, price limits, and token amounts
2. **Route Calculation**: Determines optimal path through active liquidity
3. **Tick Traversal**: Executes swap across multiple price ranges if needed
4. **Fee Collection**: Deducts swap fees and protocol fees
5. **Price Update**: Updates pool price and oracle data
6. **Output Delivery**: Transfers resulting tokens to user
**Swap Types:**
**Exact Input Swaps** (`swap_exact_x_to_y`, `swap_exact_y_to_x`):
```move
// Swap all USDC for maximum SUI possible
let sui_out = swap_router::swap_exact_x_to_y(
&mut pool,
usdc_in, // Entire amount consumed
min_sqrt_price, // Price limit (slippage protection)
&versioned,
&clock,
ctx
);
```
**Exact Output Swaps** (`swap_x_to_exact_y`, `swap_y_to_exact_x`):
```move
// Swap minimum USDC needed for exact 1 SUI
let sui_out = swap_router::swap_x_to_exact_y(
&mut pool,
usdc_in, // May have excess refunded
1_000_000_000, // Exactly 1 SUI (9 decimals)
max_sqrt_price, // Price limit
&versioned,
&clock,
ctx
);
```
**Position Management Best Practices**
**Opening Positions:**
```move
// Choose tick range based on strategy
let tick_lower = tick_math::get_tick_at_sqrt_price(lower_price_sqrt);
let tick_upper = tick_math::get_tick_at_sqrt_price(upper_price_sqrt);
// Ensure ticks are valid for the pool's tick spacing
let tick_spacing = pool::tick_spacing(&pool);
let adjusted_lower = (tick_lower / tick_spacing) * tick_spacing;
let adjusted_upper = (tick_upper / tick_spacing) * tick_spacing;
```
**Liquidity Management:**
* **Narrow Ranges**: Higher fees, higher impermanent loss risk
* **Wide Ranges**: Lower fees, lower impermanent loss risk
* **Active Management**: Monitor price movements and adjust ranges
**Fee Collection Strategy:**
```move
// Collect fees regularly to compound returns
let (fee_x, fee_y) = position_manager::collect(
&mut pool_registry,
&mut position,
18446744073709551615, // Max u64 to collect all
18446744073709551615, // Max u64 to collect all
&versioned,
&clock,
ctx
);
// Reinvest fees by adding liquidity
position_manager::increase_liquidity(
&mut pool_registry,
&mut position,
coin::from_balance(fee_x, ctx),
coin::from_balance(fee_y, ctx),
0, // No minimum since we're reinvesting fees
0,
deadline,
&versioned,
&clock,
ctx
);
```
**Defensive Programming Practices**
```move
// Always use deadlines for time-sensitive operations
let deadline = clock::timestamp_ms(clock) + 300_000; // 5 minutes
// Set reasonable slippage tolerance (e.g., 0.5%)
let amount_min = (expected_amount * 995) / 1000;
// Check pool state before operations
assert!(pool::is_initialized(&pool), E_POOL_NOT_INITIALIZED);
// Set appropriate price limits for swaps
let current_sqrt_price = pool::sqrt_price_current(&pool);
// For X to Y swaps (price decreasing), set a lower limit
let min_sqrt_price_limit = (current_sqrt_price * 95) / 100; // 5% slippage
// Ensure it's above the absolute minimum
let safe_min_limit = math::max(min_sqrt_price_limit, tick_math::min_sqrt_price() + 1);
// For Y to X swaps (price increasing), set an upper limit
let max_sqrt_price_limit = (current_sqrt_price * 105) / 100; // 5% slippage
// Ensure it's below the absolute maximum
let safe_max_limit = math::min(max_sqrt_price_limit, tick_math::max_sqrt_price() - 1);
// Check price limits before swap to avoid errors
if (x_for_y) {
assert!(sqrt_price_limit < current_sqrt_price, E_PRICE_LIMIT_ALREADY_EXCEEDED);
assert!(sqrt_price_limit > tick_math::min_sqrt_price(), E_PRICE_LIMIT_OUT_OF_BOUNDS);
} else {
assert!(sqrt_price_limit > current_sqrt_price, E_PRICE_LIMIT_ALREADY_EXCEEDED);
assert!(sqrt_price_limit < tick_math::max_sqrt_price(), E_PRICE_LIMIT_OUT_OF_BOUNDS);
};
```
#### Precision & Safety Features
* **Q64.64 Fixed-Point Arithmetic**: For precise price calculations
* **Overflow-Safe Operations**: Implements overflow-safe arithmetic operations
* **Rounding Controls**: Provides rounding controls for fee calculations
#### Integration Patterns
**Direct Pool Swap Integration**
Best practices for integrating with the core `pool::swap` function for custom swap implementations:
```move
// Complete swap integration pattern
public fun custom_swap_exact_input(
pool: &mut Pool,
input_coin: Coin,
min_output_amount: u64,
max_slippage_bps: u64, // basis points (e.g., 50 = 0.5%)
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): Coin {
let input_amount = coin::value(&input_coin);
let current_sqrt_price = pool::sqrt_price_current(pool);
// Calculate price limit based on slippage tolerance
let price_limit = if (true) { // x_for_y = true
let slippage_factor = 10000 - max_slippage_bps; // e.g., 9950 for 0.5%
(current_sqrt_price * (slippage_factor as u128)) / 10000
} else {
let slippage_factor = 10000 + max_slippage_bps; // e.g., 10050 for 0.5%
(current_sqrt_price * (slippage_factor as u128)) / 10000
};
// Execute swap
let (balance_x_out, balance_y_out, receipt) = pool::swap(
pool,
true, // x_for_y
true, // exact_in
input_amount, // amount_specified
price_limit,
versioned,
clock,
ctx
);
// Pay for the swap
pool::pay(
pool,
receipt,
coin::into_balance(input_coin), // payment_x
balance::zero(), // payment_y
versioned,
ctx
);
// Validate minimum output
let output_amount = balance::value(&balance_y_out);
assert!(output_amount >= min_output_amount, E_INSUFFICIENT_OUTPUT_AMOUNT);
// Return output (balance_x_out should be zero for x_for_y swaps)
balance::destroy_zero(balance_x_out);
coin::from_balance(balance_y_out, ctx)
}
// Precise swap with receipt-based payment amounts
public fun precise_swap_exact_input(
pool: &mut Pool,
input_coin: Coin,
min_output_amount: u64,
sqrt_price_limit: u128,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): (Coin, Coin) { // Returns refunded input and output in (x, y) order
let input_amount = coin::value(&input_coin);
// Execute swap
let (balance_x_out, balance_y_out, receipt) = pool::swap(
pool,
true, // x_for_y
true, // exact_in
input_amount, // amount_specified
sqrt_price_limit,
versioned,
clock,
ctx
);
// Extract exact payment amounts from receipt
let amount_x_needed = swap_receipt::amount_x_needed(&receipt);
let amount_y_needed = swap_receipt::amount_y_needed(&receipt);
// For exact_in swaps, amount_x_needed should equal input_amount
// For x_for_y swaps, amount_y_needed should be zero
assert!(amount_y_needed == 0, E_UNEXPECTED_Y_PAYMENT_REQUIRED); // Should be zero for x_for_y
// Split exact amount needed for payment
let payment_coin = coin::split(&mut input_coin, amount_x_needed, ctx);
let payment_x = coin::into_balance(payment_coin);
// Complete the payment
pool::pay(
pool,
receipt,
payment_x,
balance::zero(),
versioned,
ctx
);
// Validate minimum output
let output_amount = balance::value(&balance_y_out);
assert!(output_amount >= min_output_amount, E_INSUFFICIENT_OUTPUT_AMOUNT);
// Convert output balance to coin
let output_coin = coin::from_balance(balance_y_out, ctx);
balance::destroy_zero(balance_x_out); // Should be zero for x_for_y swaps
// Return refunded input and output in (x, y) order
(input_coin, output_coin)
}
```
**Direct Pool Liquidity Modification Integration**
Best practices for integrating with the core `pool::modify_liquidity` function for custom liquidity management:
```move
// Complete liquidity addition integration pattern
public fun add_liquidity_to_position(
pool: &mut Pool,
position: &mut Position,
desired_amount_x: u64,
desired_amount_y: u64,
min_amount_x: u64,
min_amount_y: u64,
coin_x: Coin,
coin_y: Coin,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): (Coin, Coin) { // Returns refunded coins
// Validate input amounts
assert!(coin::value(&coin_x) >= desired_amount_x, E_INSUFFICIENT_INPUT_AMOUNT);
assert!(coin::value(&coin_y) >= desired_amount_y, E_INSUFFICIENT_INPUT_AMOUNT);
// Get current pool state for calculations
let current_sqrt_price = pool::sqrt_price_current(pool);
let current_liquidity = pool::liquidity(pool);
let tick_lower = position::tick_lower_index(position);
let tick_upper = position::tick_upper_index(position);
// Calculate optimal liquidity amount based on desired token amounts
let target_liquidity = calculate_liquidity_for_amounts(
current_sqrt_price,
tick_lower,
tick_upper,
desired_amount_x,
desired_amount_y
);
// Prepare exact amounts needed (may be less than desired)
// Convert tick boundaries to sqrt prices
let sqrt_price_lower = tick_math::get_sqrt_price_at_tick(tick_lower);
let sqrt_price_upper = tick_math::get_sqrt_price_at_tick(tick_upper);
let (exact_amount_x, exact_amount_y) = liquidity_math::get_amounts_for_liquidity(
current_sqrt_price,
sqrt_price_lower,
sqrt_price_upper,
target_liquidity,
true // add = true for adding liquidity
);
// Validate minimum amounts
assert!(exact_amount_x >= min_amount_x, E_INSUFFICIENT_OUTPUT_AMOUNT);
assert!(exact_amount_y >= min_amount_y, E_INSUFFICIENT_OUTPUT_AMOUNT);
// Split exact amounts from input coins
let balance_x_in = coin::into_balance(coin::split(&mut coin_x, exact_amount_x, ctx));
let balance_y_in = coin::into_balance(coin::split(&mut coin_y, exact_amount_y, ctx));
// Execute liquidity modification
let liquidity_delta = i128::from(target_liquidity);
let (actual_amount_x, actual_amount_y) = pool::modify_liquidity(
pool,
position,
liquidity_delta,
balance_x_in,
balance_y_in,
versioned,
clock,
ctx
);
// Validate actual amounts meet expectations
assert!(actual_amount_x >= min_amount_x, E_INSUFFICIENT_LIQUIDITY_ADDED);
assert!(actual_amount_y >= min_amount_y, E_INSUFFICIENT_LIQUIDITY_ADDED);
// Return any remaining coins as refund
(coin_x, coin_y)
}
// Advanced liquidity removal with precise control
public fun remove_liquidity_from_position(
pool_registry: &mut PoolRegistry,
pool: &mut Pool,
position: &mut Position,
liquidity_to_remove: u128,
min_amount_x_out: u64,
min_amount_y_out: u64,
collect_fees: bool,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): (Balance, Balance) {
// Validate position has enough liquidity
let current_position_liquidity = position::liquidity(position);
assert!(current_position_liquidity >= liquidity_to_remove, E_INSUFFICIENT_LIQUIDITY);
// Get position details for calculations
let tick_lower = position::tick_lower_index(position);
let tick_upper = position::tick_upper_index(position);
let current_sqrt_price = pool::sqrt_price_current(pool);
// Calculate expected amounts to receive
// Convert tick boundaries to sqrt prices
let sqrt_price_lower = tick_math::get_sqrt_price_at_tick(tick_lower);
let sqrt_price_upper = tick_math::get_sqrt_price_at_tick(tick_upper);
let (expected_amount_x, expected_amount_y) = liquidity_math::get_amounts_for_liquidity(
current_sqrt_price,
sqrt_price_lower,
sqrt_price_upper,
liquidity_to_remove,
false // add = false for removing liquidity
);
// Ensure expected amounts meet minimum requirements
assert!(expected_amount_x >= min_amount_x_out, E_INSUFFICIENT_EXPECTED_OUTPUT);
assert!(expected_amount_y >= min_amount_y_out, E_INSUFFICIENT_EXPECTED_OUTPUT);
// Execute liquidity removal
let liquidity_delta = i128::neg_from(liquidity_to_remove);
let (actual_amount_x, actual_amount_y) = pool::modify_liquidity(
pool,
position,
liquidity_delta,
balance::zero(), // No input when removing liquidity
balance::zero(), // No input when removing liquidity
versioned,
clock,
ctx
);
// Validate actual amounts meet minimum requirements
assert!(actual_amount_x >= min_amount_x_out, E_INSUFFICIENT_OUTPUT_AMOUNT);
assert!(actual_amount_y >= min_amount_y_out, E_INSUFFICIENT_OUTPUT_AMOUNT);
// Collect fees if requested
if (collect_fees) {
let (collected_x, collected_y) = position_manager::collect(
pool_registry,
position,
max_u64, // Collect all available fees
max_u64, // Collect all available fees
ctx
);
(collected_x, collected_y)
} else {
(
balance::zero(),
balance::zero()
)
}
}
```
**Position Fees and Rewards Management**
Best practices for collecting fees and rewards from positions:
```move
// Optimized fee collection with threshold checking
public fun collect_fees(
pool_registry: &mut PoolRegistry,
position: &mut Position,
versioned: &Versioned,
ctx: &mut TxContext
): (Balance, Balance) {
let (fee_x, fee_y) = position_manager::collect(
pool_registry,
position,
max_u64, // Collect all available fees
max_u64, // Collect all available fees
versioned,
ctx
);
(fee_x, fee_y)
}
// Collect specific reward token type from position
public fun collect_position_reward(
pool_registry: &mut PoolRegistry,
position: &mut Position,
versioned: &Versioned,
clock: &Clock,
ctx: &mut TxContext
): Coin { // Returns collected reward coin
// Collect the specific reward token type
let collected_reward = position_manager::collect_pool_reward(
pool_registry,
position,
max_u64, // Collect all available rewards
versioned,
clock,
ctx
);
collected_reward
}
```
**Position Monitoring**
Best practices for getting position token amounts:
```move
// Get current token amounts in a position
public fun get_position_amounts(
pool: &Pool,
position: &Position
): (u64, u64) { // Returns (amount_x, amount_y)
let tick_lower = position::tick_lower_index(position);
let tick_upper = position::tick_upper_index(position);
let current_sqrt_price = pool::sqrt_price_current(pool);
let position_liquidity = position::liquidity(position);
// Calculate current token amounts in the position
if (position_liquidity > 0) {
// Convert tick boundaries to sqrt prices
let sqrt_price_lower = tick_math::get_sqrt_price_at_tick(tick_lower);
let sqrt_price_upper = tick_math::get_sqrt_price_at_tick(tick_upper);
liquidity_math::get_amounts_for_liquidity(
current_sqrt_price,
sqrt_price_lower,
sqrt_price_upper,
position_liquidity,
false // add = false for getting amounts
)
} else {
(0, 0)
}
}
```
**Multi-Hop Swaps**
For token pairs without direct pools, implement multi-hop routing:
```move
// USDC -> SUI -> BTC (two-hop swap)
// Step 1: USDC -> SUI
let sui_balance = swap_router::swap_exact_x_to_y(
&mut usdc_sui_pool,
usdc_in,
min_sqrt_price_1,
&versioned,
&clock,
ctx
);
// Step 2: SUI -> BTC
let btc_balance = swap_router::swap_exact_x_to_y(
&mut sui_btc_pool,
coin::from_balance(sui_balance, ctx),
min_sqrt_price_2,
&versioned,
&clock,
ctx
);
```
**Flash Loans Integration**
Leverage flash loans for arbitrage and other strategies:
```move
// Flash loan pattern for arbitrage
public fun arbitrage_opportunity(
pool: &mut Pool,
flash_amount_x: u64,
flash_amount_y: u64,
versioned: &Versioned,
ctx: &mut TxContext
): (Balance, Balance) {
// 1. Flash loan tokens from pool
let (loan_x, loan_y, flash_receipt) = pool::flash(
pool,
flash_amount_x,
flash_amount_y,
versioned,
ctx
);
// 2. Get debt amounts from receipt (includes fees)
let (total_debt_x, total_debt_y) = pool::flash_receipt_debts(&flash_receipt);
// 3. Execute arbitrage logic here
// Example: swap tokens, interact with other protocols, etc.
// ...your arbitrage logic...
// 4. Prepare repayment (must include loan amount + fees)
// Ensure you have enough to repay the debt
let repay_x = loan_x; // Add your tokens if needed: balance::join(&mut loan_x, additional_x);
let repay_y = loan_y; // Add your tokens if needed: balance::join(&mut loan_y, additional_y);
// 5. Repay the flash loan with fees
pool::repay(
pool,
flash_receipt,
repay_x,
repay_y,
versioned,
ctx
);
// 6. Return any profit
(balance::zero(), balance::zero())
}
```
### ๐ฎ Price Oracle System
FlowX CLMM includes a sophisticated time-weighted average price (TWAP) oracle system that provides reliable price feeds and historical data tracking. The oracle automatically records price and liquidity data with each swap, creating a decentralized price feed that follows the Uniswap V3 oracle design.
#### ๐ฏ Oracle Features
| Feature | Description |
| -------------------------- | ------------------------------------------------- |
| **TWAP Calculation** | Time-weighted average prices over any time period |
| **Automated Recording** | Automatic price updates with every transaction |
| **Historical Data** | Up to 1000 observations stored per pool |
| **Manipulation Resistant** | Requires significant capital to manipulate prices |
| **Gas Efficient** | Optimized storage and calculation algorithms |
#### ๐ Oracle Data Structure
Each oracle observation contains:
* **Timestamp (seconds)**: When the observation was recorded (in seconds, not milliseconds)
* **Tick Cumulative (I64)**: Cumulative sum of tick values over time (signed integer)
* **Seconds per Liquidity (u256)**: Time-weighted measure of liquidity depth
* **Initialization Status**: Whether the observation slot is active
#### ๐ง Core Oracle Functions
**Get Historical Price Data**
```move
/// Get TWAP data for specified time periods
public fun observe(
self: &Pool,
seconds_agos: vector,
clock: &Clock
): (vector, vector)
```
**Parameters:**
* `self`: Pool to query oracle data from
* `seconds_agos`: Array of time periods to look back (in seconds)
* `clock`: Clock object for current timestamp
**Returns:**
* `vector`: Tick cumulatives for each time period (signed integers)
* `vector`: Seconds per liquidity cumulatives for each time period
**Increase Oracle Capacity**
```move
/// Increase the maximum number of observations this pool will store
public fun increase_observation_cardinality_next(
self: &mut Pool,
observation_cardinality_next: u64,
versioned: &Versioned,
ctx: &TxContext
)
```
**Parameters:**
* `self`: Pool to increase capacity for
* `observation_cardinality_next`: New maximum number of observations (max 1000)
* `versioned`: Versioned object for package version validation
* `ctx`: Transaction context
#### ๐ก TWAP Calculation Examples
**Basic TWAP Price Calculation**
```move
use flowx_clmm::i64;
use flowx_clmm::i32;
use flowx_clmm::tick_math;
/// Calculate TWAP price over specified time period
public fun calculate_twap_price(
pool: &Pool,
period_seconds: u64,
clock: &Clock
): u128 {
// Get tick cumulatives for current time and period ago
let seconds_agos = vector[0, period_seconds];
let (tick_cumulatives, _) = pool.observe(seconds_agos, clock);
let current_cumulative = *vector::borrow(&tick_cumulatives, 0);
let past_cumulative = *vector::borrow(&tick_cumulatives, 1);
// Calculate time-weighted average tick (handle signed arithmetic)
let tick_delta = i64::sub(current_cumulative, past_cumulative);
let average_tick_i64 = i64::div(tick_delta, i64::from(period_seconds));
// Convert I64 to I32 for tick math
let average_tick = if (i64::is_neg(average_tick_i64)) {
i32::neg_from(i64::abs_u64(average_tick_i64))
} else {
i32::from_u64(i64::abs_u64(average_tick_i64))
};
// Convert tick to sqrt price
tick_math::get_sqrt_price_at_tick(average_tick)
}
/// Get current oracle state information
public fun get_oracle_info(pool: &Pool): (u64, u64, u64) {
(
pool.observation_index(), // Current observation index
pool.observation_cardinality(), // Number of populated observations
pool.observation_cardinality_next() // Maximum observations capacity
)
}
```
#### Data Access Functions
```move
// Pool oracle state getters (read-only)
pool.observation_index(); // Current observation index: u64
pool.observation_cardinality(); // Active observations count: u64
pool.observation_cardinality_next(); // Maximum capacity: u64
pool.borrow_observations(); // Direct access to observations vector
```
#### โ ๏ธ Error Handling
**Common Error Scenarios**
| Error Code | Description | Solution |
| -------------------------------- | ------------------------------------- | ------------------------------------- |
| `E_INSUFFICIENT_OUTPUT_AMOUNT` | Slippage exceeded | Increase tolerance or wait |
| `E_EXCESSIVE_INPUT_AMOUNT` | Price moved unfavorably | Retry with updated limits |
| `E_ZERO_AMOUNT` | Cannot operate with zero amounts | Provide non-zero amounts |
| `E_NOT_EMPTY_POSITION` | Position must be empty before closing | Remove all liquidity and collect fees |
| `E_PRICE_LIMIT_ALREADY_EXCEEDED` | Current price beyond specified limit | Update price limit |
| `E_PRICE_LIMIT_OUT_OF_BOUNDS` | Price limit outside valid range | Use valid price range |
**Error Handling and Edge Cases**
**Common Error Scenarios:**
* `E_INSUFFICIENT_OUTPUT_AMOUNT`: Slippage exceeded, increase tolerance or wait
* `E_EXCESSIVE_INPUT_AMOUNT`: Price moved unfavorably, retry with updated limits
* `E_ZERO_AMOUNT`: Cannot operate with zero amounts
* `E_NOT_EMPTY_POSITION`: Position must be empty before closing (zero liquidity, zero coin owed, and zero reward)
* `E_PRICE_LIMIT_ALREADY_EXCEEDED`: The current price has already moved beyond the specified price limit before swap execution
* `E_PRICE_LIMIT_OUT_OF_BOUNDS`: The specified price limit is outside the valid range (below minimum or above maximum sqrt price)
### ๐งฎ Mathematical Libraries
FlowX CLMM includes optimized mathematical libraries for precise calculations:
#### Core Math Libraries
| Library | Purpose | Key Functions |
| ---------------------- | ------------------------------ | ----------------------------------------------------- |
| `tick_math.move` | Tick โ Price conversions | `get_sqrt_price_at_tick`, `get_tick_at_sqrt_price` |
| `sqrt_price_math.move` | Square root price calculations | `get_next_sqrt_price_from_amount`, `get_amount_delta` |
| `liquidity_math.move` | Liquidity calculations | `add_delta`, `get_amounts_for_liquidity` |
| `full_math_u128.move` | High-precision arithmetic | `mul_div`, `mul_div_round_up` |
| `swap_math.move` | Swap calculations | `compute_swap_step` |
### ๐ ๏ธ Development
#### ๐งช Testing
**Unit Tests**
```bash
# Run all tests
sui move test
# Run with verbose output
sui move test --verbose
# Run with gas profiling
sui move test --gas-limit 1000000000
```
#### ๐ Environment Configuration
**Environment Variables**
```bash
# .env.example
SUI_NETWORK=testnet
JSON_RPC_ENDPOINT=https://fullnode.testnet.sui.io:443 # RPC endpoint for Sui network (testnet/mainnet)
PRIVATE_KEY=your_private_key_here
```
### ๐ฆ Deployment
#### ๐งช Testnet Deployment
```bash
# 2. Build package
sui move build
# 3. Deploy to testnet
sui client publish --gas-budget 100000000
```
#### ๐ Mainnet Deployment
```bash
# 1. Switch to mainnet
sui client switch --env mainnet
# 2. Verify build
sui move build --verification
# 3. Deploy with higher gas budget
sui client publish --gas-budget 200000000
```