Pool Module

The Pool module is the core component of the DAMM protocol, defining trading pairs and handling all operations related to trading, liquidity management, and advanced fee mechanisms.

Overview

The Pool module provides:

• Core swap functionality with dynamic and scheduled fees

• Concentrated liquidity management

• Flash swap and flash loan capabilities

• Position and fee management

• Reward distribution integration

• Whitelist and activation controls

Data Structures

Pool Struct

struct Pool<phantom CoinTypeA, phantom CoinTypeB> has key, store {
    id: UID,
    creator: address,
    parameters: PairParameters,
    coin_a: Balance<CoinTypeA>,
    coin_b: Balance<CoinTypeB>,
    liquidity: u128,
    whitelisted: VecSet<address>,
    collect_fee_mode: u8,
    is_quote_y: bool,
    fee_growth_global_a: u128,
    fee_growth_global_b: u128,
    fee_protocol_coin_a: u64,
    fee_protocol_coin_b: u64,
    tick_manager: TickManager,
    rewarder_manager: RewarderManager,
    position_manager: PositionManager,
    is_pause: bool,
    index: u64,
    url: String,
}

Key Fields:

Field	Type	Description
creator	address	Pool creator address
parameters	PairParameters	Fee scheduler and dynamic fee configuration
coin_a, coin_b	Balance	Token balances in the pool
liquidity	u128	Current active liquidity
whitelisted	VecSet<address>	Pre-activation whitelist
collect_fee_mode	u8	Fee collection mode
is_quote_y	bool	Whether token Y is quote
fee_growth_global_a/b	u128	Global fee growth trackers
fee_protocol_coin_a/b	u64	Accumulated protocol fees

Receipt Structs

FlashSwapReceipt

struct FlashSwapReceipt<phantom CoinTypeA, phantom CoinTypeB> {
    pool_id: ID,
    a2b: bool,
    pay_amount: u64,
}

AddLiquidityReceipt

struct AddLiquidityReceipt<phantom CoinTypeA, phantom CoinTypeB> {
    pool_id: ID,
    amount_a: u64,
    amount_b: u64,
}

FlashLoanReceipt

struct FlashLoanReceipt {
    pool_id: ID,
    loan_a: bool,
    amount: u64,
    fee_amount: u64,
}

CalculatedSwapResult

struct CalculatedSwapResult has copy, drop, store {
    amount_in: u64,
    amount_out: u64,
    atob: bool,
    collect_fee_on_input: bool,
    fee_amount: u64,
    base_fee: u64,
    dynamic_fee: u64,
    before_sqrt_price: u128,
    after_sqrt_price: u128,
    is_exceed: bool,
    step_results: vector<SwapStepResult>,
}

Core Functions

1. Position Management

Open Position

public fun open_position<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    tick_lower_idx: u32,
    tick_upper_idx: u32,
    ctx: &mut TxContext
): Position

Creates a new liquidity position within the specified tick range.

Parameters:

Parameter	Description
tick_lower_idx	Lower tick index (as u32, converted to I32 internally)
tick_upper_idx	Upper tick index

Close Position

public fun close_position<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: Position
)

Closes an empty position and removes it from the registry.

Lock Position

public fun lock_position<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &mut Position,
    lock_until: u64,
    clock: &Clock,
)

Locks a position until a specified timestamp, preventing liquidity removal.

2. Liquidity Management

Add Liquidity

public fun add_liquidity<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &mut Position,
    delta_liquidity: u128,
    clock: &Clock,
): AddLiquidityReceipt<CoinTypeA, CoinTypeB>

Adds liquidity to an existing position by specifying liquidity amount.

Add Liquidity with Fixed Amount

public fun add_liquidity_fix_coin<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &mut Position,
    amount: u64,
    is_fixed_a: bool,
    clock: &Clock,
): AddLiquidityReceipt<CoinTypeA, CoinTypeB>

Adds liquidity by fixing one token amount.

Repay Add Liquidity

public fun repay_add_liquidity<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    coin_a: Balance<CoinTypeA>,
    coin_b: Balance<CoinTypeB>,
    receipt: AddLiquidityReceipt<CoinTypeA, CoinTypeB>,
)

Completes liquidity addition by providing required tokens.

Remove Liquidity

public fun remove_liquidity<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &mut Position,
    liquidity_amount: u128,
    clock: &Clock,
): (Balance<CoinTypeA>, Balance<CoinTypeB>)

Removes liquidity from a position and returns token balances.

3. Trading

Flash Swap

public fun flash_swap<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    a2b: bool,
    by_amount_in: bool,
    amount: u64,
    sqrt_price_limit: u128,
    clock: &Clock,
    ctx: &TxContext,
): (Balance<CoinTypeA>, Balance<CoinTypeB>, FlashSwapReceipt<CoinTypeA, CoinTypeB>)

Executes a flash swap operation.

Parameters:

Parameter	Description
a2b	true if swapping from CoinA to CoinB
by_amount_in	true if specifying input amount
amount	Token amount to swap
sqrt_price_limit	Price limit for slippage protection

Repay Flash Swap

public fun repay_flash_swap<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    coin_a: Balance<CoinTypeA>,
    coin_b: Balance<CoinTypeB>,
    receipt: FlashSwapReceipt<CoinTypeA, CoinTypeB>,
)

Completes flash swap by providing input tokens.

Calculate Swap Result

public fun calculate_swap_result<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    a2b: bool,
    by_amount_in: bool,
    amount: u64,
    clock: &Clock
): CalculatedSwapResult

Simulates a swap without executing, useful for quotes.

4. Flash Loans

Create Flash Loan

public fun flash_loan<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    is_coin_a: bool,
    amount: u64,
    clock: &Clock
): (Balance<CoinTypeA>, Balance<CoinTypeB>, FlashLoanReceipt)

Borrows tokens for atomic operations.

Repay Flash Loan

public fun repay_flash_loan<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    coin_a: Balance<CoinTypeA>,
    coin_b: Balance<CoinTypeB>,
    receipt: FlashLoanReceipt,
)

Repays flash loan with fee.

5. Fee and Reward Collection

Collect Position Fees

public fun collect_fee<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &Position,
    recalculate: bool,
): (Balance<CoinTypeA>, Balance<CoinTypeB>)

Collects accumulated trading fees for a position.

Collect Rewards

public fun collect_reward<CoinTypeA, CoinTypeB, RewardCoin>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position: &Position,
    rewarder_vault: &mut RewarderGlobalVault,
    recalculate: bool,
    clock: &Clock,
): Balance<RewardCoin>

Collects accumulated rewards for a position.

Collect Protocol Fees

public fun collect_protocol_fee<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    ctx: &mut TxContext
)

Collects protocol fees (admin only).

6. Fee Configuration

Update Fee Rate

public fun update_fee_rate<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    new_fee_rate: u64,
    ctx: &TxContext,
)

Updates the base fee rate (admin only).

Enable/Disable Fee Scheduler

public fun enable_fee_scheduler<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    ctx: &TxContext,
)

public fun disable_fee_scheduler<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    ctx: &TxContext,
)

Enable/Disable Dynamic Fee

public fun enable_dynamic_fee<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    ctx: &TxContext,
)

public fun disable_dynamic_fee<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    ctx: &TxContext,
)

7. Whitelist Management

Add Whitelist

public fun add_whitelist<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    users: vector<address>,
    ctx: &mut TxContext,
)

Adds addresses to pre-activation whitelist.

Remove Whitelist

public fun remove_whitelist<X, Y>(
    config: &GlobalConfig,
    pool: &mut Pool<X, Y>,
    users: vector<address>,
    ctx: &mut TxContext,
)

Removes addresses from whitelist.

8. Pool Management

Pause/Unpause Pool

public fun pause<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    ctx: &TxContext,
)

public fun unpause<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    ctx: &TxContext,
)

Query Functions

Pool Information

// Get current liquidity
public fun liquidity<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): u128

// Get current sqrt price
public fun current_sqrt_price<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): u128

// Get current tick index
public fun current_tick_index<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): I32

// Get total fee rate at current time
public fun get_total_fee_rate<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    current_timestamp: u64
): u64

// Get pool balances
public fun balances<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>
): (&Balance<CoinTypeA>, &Balance<CoinTypeB>)

// Check if pool is paused
public fun is_pause<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): bool

// Get protocol fees
public fun protocol_fee<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): (u64, u64)

// Get fee growth globals
public fun fees_growth_global<CoinTypeA, CoinTypeB>(pool: &Pool<CoinTypeA, CoinTypeB>): (u128, u128)

Position Information

// Check if position exists
public fun is_position_exist<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    position_id: ID
): bool

// Get position token amounts
public fun get_position_amounts<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
): (u64, u64)

// Get position fees
public fun get_position_fee<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
): (u64, u64)

// Get position points
public fun get_position_points<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
): u128

// Get position rewards
public fun get_position_rewards<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
): vector<u64>

// Fetch multiple positions
public fun fetch_positions<CoinTypeA, CoinTypeB>(
    pool: &Pool<CoinTypeA, CoinTypeB>,
    start: vector<ID>,
    limit: u64
): vector<PositionInfo>

Calculate and Update Functions

// Calculate and update position fee
public fun calculate_and_update_fee<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position_id: ID
): (u64, u64)

// Calculate and update position points
public fun calculate_and_update_points<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
    clock: &Clock
): u128

// Calculate and update position rewards
public fun calculate_and_update_rewards<CoinTypeA, CoinTypeB>(
    config: &GlobalConfig,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    position_id: ID,
    clock: &Clock
): vector<u64>

Events

SwapEvent

struct SwapEvent has copy, drop, store {
    atob: bool,
    pool: ID,
    amount_in: u64,
    amount_out: u64,
    fee_a: u64,
    fee_b: u64,
    base_fee: u64,
    dynamic_fee: u64,
    collect_fee_on_input: bool,
    vault_a_amount: u64,
    vault_b_amount: u64,
    before_sqrt_price: u128,
    after_sqrt_price: u128,
    steps: u64,
}

AddLiquidityEvent

struct AddLiquidityEvent has copy, drop, store {
    pool: ID,
    position: ID,
    tick_lower: I32,
    tick_upper: I32,
    liquidity: u128,
    after_liquidity: u128,
    amount_a: u64,
    amount_b: u64,
}

RemoveLiquidityEvent

struct RemoveLiquidityEvent has copy, drop, store {
    pool: ID,
    position: ID,
    tick_lower: I32,
    tick_upper: I32,
    liquidity: u128,
    after_liquidity: u128,
    amount_a: u64,
    amount_b: u64,
}

OpenPositionEvent

struct OpenPositionEvent has copy, drop, store {
    pool: ID,
    tick_lower: I32,
    tick_upper: I32,
    position: ID,
}

LockPositionEvent

struct LockPositionEvent has copy, drop, store {
    pool: ID,
    position: ID,
    lock_until: u64,
}

FlashLoanEvent

struct FlashLoanEvent has copy, drop, store {
    pool: ID,
    loan_a: bool,
    amount: u64,
    fee_amount: u64,
    vault_a_amount: u64,
    vault_b_amount: u64,
}

Error Codes

Code	Constant	Description
400	E_INVALID_AMOUNT	Invalid token amount
401	E_LIQUIDITY_OVERFLOW	Liquidity calculation overflow
403	E_LIQUIDITY_ZERO	Zero liquidity provided
405	E_INSUFFICIENT_AMOUNT	Insufficient token amount
406	E_SWAP_AMOUNT_IN_OVERFLOW	Swap input amount overflow
407	E_SWAP_AMOUNT_OUT_OVERFLOW	Swap output amount overflow
408	E_SWAP_FEE_AMOUNT_OVERFLOW	Fee amount overflow
410	E_POOL_TICK_OUT_OF_RANGE	Tick outside valid range
412	E_POOL_ID_MISMATCH	Pool ID mismatch
413	E_POOL_PAUSED	Pool is paused
417	E_REWARDER_NOT_FOUND	Rewarder not initialized
418	E_SWAP_ZERO_OUTPUT	Swap resulted in zero output
419	E_POSITION_POOL_MISMATCH	Position doesn't belong to pool
423	E_INVALID_LOCK_TIME	Invalid lock duration
424	E_POSITION_LOCKED	Position is currently locked
430	E_FLASH_LOAN_PAUSED	Flash loans are disabled
431	E_PENDING_ADD_LIQUIDITY	Pending liquidity operation
432	E_NOT_WHITELISTED	Address not whitelisted for pre-activation
433	E_MAX_TOTAL_FEE_EXCEEDED	Total fee exceeds maximum
434	E_NO_PERMISSION	Insufficient permissions
435	E_CLIFF_FEE_BELOW_BASE_FEE	Cliff fee must be >= base fee

Fee Collection Modes

COLLECT_FEE_ON_BOTH (0)

Fees are always collected from the input token.

COLLECT_FEE_ON_QUOTE (1)

Fees are collected from the quote token:

• If is_quote_y = true and swapping A→B: fee from output (B)

• If is_quote_y = true and swapping B→A: fee from input (B)

• If is_quote_y = false and swapping A→B: fee from input (A)

• If is_quote_y = false and swapping B→A: fee from output (A)

Usage Examples

Complete Swap Flow

// 1. Calculate expected output
let result = pool::calculate_swap_result<USDC, TOKEN>(
    &pool,
    true,           // a2b
    true,           // by_amount_in
    1000000,        // 1 USDC
    &clock
);

// 2. Execute flash swap
let (coin_a, coin_b, receipt) = pool::flash_swap<USDC, TOKEN>(
    &config,
    &mut pool,
    true,           // a2b
    true,           // by_amount_in
    1000000,        // amount
    min_sqrt_price, // slippage protection
    &clock,
    ctx
);

// 3. Repay with input token
pool::repay_flash_swap<USDC, TOKEN>(
    &config,
    &mut pool,
    coin::into_balance(payment_coin),
    balance::zero(),
    receipt
);

Adding Liquidity

// 1. Open position
let position = pool::open_position<USDC, TOKEN>(
    &config,
    &mut pool,
    tick_lower,
    tick_upper,
    ctx
);

// 2. Add liquidity with fixed amount
let receipt = pool::add_liquidity_fix_coin<USDC, TOKEN>(
    &config,
    &mut pool,
    &mut position,
    1000000,    // fix 1 USDC
    true,       // is_fixed_a
    &clock
);

// 3. Get required amounts
let (amount_a, amount_b) = pool::add_liquidity_pay_amount(&receipt);

// 4. Repay
pool::repay_add_liquidity<USDC, TOKEN>(
    &config,
    &mut pool,
    coin::into_balance(coin_a),
    coin::into_balance(coin_b),
    receipt
);

Security Considerations

1. Slippage Protection: Always use sqrt_price_limit when swapping

2. Receipt Validation: Carefully validate receipts before repaying

3. Permission Checks: Only admins can pause/unpause pools

4. Lock Period: Positions can be locked to prevent premature withdrawal

5. Whitelist Check: Pre-activation swaps require whitelist membership