flowx

name	flowx
description	This skill should be used when the user asks about FlowX Finance, FlowX DEX, FlowX AMM, FlowX CLMM, FlowX swap, FlowX liquidity, or wants to integrate with FlowX on Sui. Covers AMM V1 constant-product swaps, CLMM concentrated liquidity swaps, multi-hop routing, liquidity provision, LP tokens, flash loans, position management, and pool queries.

FlowX Finance on Sui

FlowX Finance is a DEX on Sui with two AMM models: a classic constant-product AMM (V1) and a Uniswap V3-style concentrated liquidity market maker (CLMM). The V1 AMM uses PairMetadata<X, Y> pools stored in a shared Container, while the CLMM uses tick-based Pool<X, Y> objects stored in a shared PoolRegistry.

Package IDs

Package	Original ID	Description
AMM V1 (Core)	0xba153169476e8c3114962261d1edc70de5ad9781b83cc617ecc8c1923191cae0	Factory, Pair, Router, swap_utils for constant-product AMM
CLMM (Core)	0x25929e7f29e0a30eb4e692952ba1b5b65a3a4d65ab5f2a32e1ba3edcb587f26d	Pool, PoolManager, SwapRouter, PositionManager for concentrated liquidity

Source Files

Decompiled Move source:

• AMM V1: packages/mainnet_most_used/0xba/153169476e8c3114962261d1edc70de5ad9781b83cc617ecc8c1923191cae0/decompiled_modules/
• CLMM (latest v7): packages/mainnet_most_used/0xde/2c47eb0da8c74e4d0f6a220c41619681221b9c2590518095f0f0c2d3f3c772/decompiled_modules/

Architecture

AMM V1

• Container (shared object): Holds all pairs in a Bag, keyed by LP name string. Created at init, one global instance.
• PairMetadata<X, Y>: Constant-product pool with reserve_x, reserve_y, lp_supply, fee_rate. Stored inside Container.pairs.
• LP<X, Y>: Fungible LP token type with Supply managed by the pair. Minimum 1000 locked on first mint.
• Treasury: Holds the fee recipient address for protocol fees.
• Token ordering: Pairs are always stored in canonical order determined by swap_utils::is_ordered<T0, T1>() (lexicographic comparison of type names).
• Default fee rate: 30 basis points (0.3%) set on pair creation. Fee denominator is 10000.

CLMM

• PoolRegistry (shared object): Manages all CLMM pools as dynamic object fields. Pools are keyed by (coin_type_x, coin_type_y, fee_rate).
• Pool<X, Y>: Concentrated liquidity pool with sqrt_price, tick_index, liquidity, tick bitmap, observations (TWAP), reward infos, reserves. Uses SwapReceipt pattern for payment.
• Position (owned NFT): Represents a concentrated liquidity range with tick_lower_index, tick_upper_index, liquidity, accrued fees and rewards. Display name: "FlowX CLMM Liquidity Positions".
• PositionRegistry (shared object): Tracks total number of open positions.
• Versioned: Version gating object for upgradeable contracts.
• Fee rate denominator: 1_000_000. Pre-configured tiers: 100 (0.01%, tick spacing 2), 500 (0.05%, tick spacing 10), 3000 (0.3%, tick spacing 60), 10000 (1%, tick spacing 200).
• Flash loans via pool::flash / pool::repay with FlashReceipt.

Key Modules

AMM V1

Module	Purpose
factory	Container creation, pair management, fee rate admin
pair	PairMetadata struct, swap, mint (add liquidity), burn (remove liquidity), LP token management
router	Entry points: swap_exact_input, swap_exact_output, add_liquidity, remove_liquidity, multi-hop swaps
swap_utils	get_amount_out, get_amount_in, quote, is_ordered
treasury	Protocol fee recipient management
math	sqrt, min/max, pow helpers
comparator	Byte-level comparison for type ordering
type_helper	Type name string conversion

CLMM

Module	Purpose
pool	Pool struct, swap, flash loan, modify_liquidity, collect fees/rewards, state queries
pool_manager	PoolRegistry, pool creation, pool borrowing, admin operations
swap_router	swap_exact_input, swap_exact_output (handles token ordering)
position_manager	open_position, increase_liquidity, decrease_liquidity, collect, close_position
position	Position NFT struct, field accessors
tick_math	Tick-to-sqrt-price conversions, min/max bounds
liquidity_math	Liquidity calculations from amounts and price ranges
sqrt_price_math	Price-based amount calculations
oracle	TWAP observation management
tick, tick_bitmap	Tick state and initialized tick traversal

Common Integration Patterns

AMM V1: Swap Exact Input (entry point)

// Single-hop swap with exact input amount
// Container is the shared FlowX AMM object
router::swap_exact_input<TokenIn, TokenOut>(
    clock,          // &Clock
    container,      // &mut Container
    coin_in,        // Coin<TokenIn>
    min_amount_out, // u64
    recipient,      // address
    deadline,       // u64 (timestamp_ms)
    ctx,            // &mut TxContext
);

// Programmable: returns Coin<TokenOut> directly
let coin_out = router::swap_exact_input_direct<TokenIn, TokenOut>(
    container, coin_in, ctx
);

// Multi-hop (2 hops): TokenIn -> Mid -> TokenOut
router::swap_exact_input_doublehop<TokenIn, Mid, TokenOut>(
    clock, container, coin_in, min_amount_out, recipient, deadline, ctx
);

// Multi-hop (3 hops)
router::swap_exact_input_triplehop<T0, T1, T2, T3>(
    clock, container, coin_in, min_amount_out, recipient, deadline, ctx
);

AMM V1: Add / Remove Liquidity

// Add liquidity (auto-creates pair if needed)
router::add_liquidity<TokenX, TokenY>(
    clock, container, coin_x, coin_y,
    amount_x_min,  // u64
    amount_y_min,  // u64
    recipient,     // address -- receives LP tokens
    deadline, ctx,
);

// Remove liquidity
router::remove_liquidity<TokenX, TokenY>(
    clock, container,
    lp_coin,         // Coin<pair::LP<TokenX, TokenY>>
    amount_x_min,    // u64
    amount_y_min,    // u64
    recipient, deadline, ctx,
);

CLMM: Swap

// Exact input swap via swap_router (handles ordering automatically)
let coin_out = swap_router::swap_exact_input<TokenIn, TokenOut>(
    pool_registry,    // &mut PoolRegistry
    fee_rate,         // u64 (e.g., 3000 for 0.3%)
    coin_in,          // Coin<TokenIn>
    min_amount_out,   // u64
    sqrt_price_limit, // u128 (0 for no limit)
    deadline,         // u64 (seconds)
    versioned,        // &Versioned
    clock, ctx,
);

// Exact output swap
let coin_out = swap_router::swap_exact_output<TokenIn, TokenOut>(
    pool_registry, fee_rate, coin_in,
    exact_amount_out, sqrt_price_limit, deadline,
    versioned, clock, ctx,
);

CLMM: Open Position + Add Liquidity

// 1. Open position with tick range
let position = position_manager::open_position<TokenX, TokenY>(
    position_registry, pool_registry,
    fee_rate,          // u64
    tick_lower,        // i32::I32
    tick_upper,        // i32::I32
    versioned, ctx,
);

// 2. Add liquidity to the position
position_manager::increase_liquidity<TokenX, TokenY>(
    pool_registry, &mut position,
    coin_x, coin_y,
    amount_x_min, amount_y_min,
    deadline, versioned, clock, ctx,
);

// 3. Transfer position to user
transfer::public_transfer(position, sender);

CLMM: Flash Loan

let (balance_x, balance_y, receipt) = pool::flash<T0, T1>(
    pool, amount_x, amount_y, versioned, ctx
);
// ... use balances ...
// Must repay with fee
pool::repay<T0, T1>(pool, receipt, repay_balance_x, repay_balance_y, versioned, ctx);

Pool Queries

// AMM V1
let (reserve_x, reserve_y) = pair::get_reserves<X, Y>(pair_metadata);
let fee = pair::fee_rate<X, Y>(pair_metadata);
let lp_supply = pair::total_lp_supply<X, Y>(pair_metadata);

// CLMM
let (reserve_x, reserve_y) = pool::reserves<X, Y>(pool);
let sqrt_price = pool::sqrt_price_current<X, Y>(pool);
let tick = pool::tick_index_current<X, Y>(pool);
let liquidity = pool::liquidity<X, Y>(pool);
let fee_rate = pool::swap_fee_rate<X, Y>(pool);

Related Skills

• sui-framework -- Core Sui types (Coin, Balance, Clock, TxContext)
• cetus -- Alternative CLMM DEX on Sui (similar CLMM architecture)
• turbos -- Alternative CLMM DEX
• kriya -- Alternative AMM/PMM DEX
• deepbook -- CLOB DEX on Sui