Liquidity Pool Module

Module Info

• Package Name: AtmosSwap
• Address: atmos_swap=0xa4a4a31116e114bf3c4f4728914e6b43db73279a4421b0768993e07248fe2234
• Module: atmos_swap::liquidity_pool
• Description: Core module for managing liquidity pools in the Atmos Swap Hyper Amm. Supports both Weighted and Stable pool types with various pool operations including swaps, liquidity provision, and fee management. This module handles the core pool logic and mathematical calculations for AMM operations.

Constants

Constant	Value	Description
MAX_STABLE_TOKENS	4	Maximum allowed tokens in a stable pool
MAX_WEIGHTED_TOKENS	4	Maximum allowed tokens in a weighted pool
POOL_TYPE_STABLE	100	Stable pool type identifier
POOL_TYPE_WEIGHTED	101	Weighted pool type identifier
BPS_BASE	10000	Base points denominator (100%)
MIN_AMP_FACTOR	0	Minimum AMP factor for stable pools
MAX_AMP_FACTOR	10000	Maximum AMP factor for stable pools
MAX_SWAP_FEE	1000	Maximum swap fee in basis points

---

Public Functions

Pool Creation

Create Stable Pool

public fun create_pool_stable(
    initial_assets: vector<FungibleAsset>,
    swap_fee_bps: u64,
    amp_factor: u64
) : (Object<Pool>, FungibleAsset)

Creates a new stable pool with specified parameters and initial liquidity.

Function Arguments

Argument	Type	Description
initial_assets	vector<FungibleAsset>	Initial assets to deposit
swap_fee_bps	u64	Swap fee in basis points
amp_factor	u64	Amplification coefficient

Returns

Type	Description
Object<Pool>	Pool object
FungibleAsset	LP tokens

Aborts

• If swap fee is invalid
• If assets validation fails
• If pool already exists
• If amp factor is out of valid range
• If any initial amount is zero

Create Weighted Pool

public fun create_pool_weighted(
    initial_assets: vector<FungibleAsset>,
    pool_weights: vector<u64>,
    swap_fee_bps: u64
) : (Object<Pool>, FungibleAsset)

Creates a new weighted pool with specified parameters and initial liquidity.

Function Arguments

Argument	Type	Description
initial_assets	vector<FungibleAsset>	Initial assets to deposit
pool_weights	vector<u64>	Token weights (must sum to 100)
swap_fee_bps	u64	Swap fee in basis points

Returns

Type	Description
Object<Pool>	Pool object
FungibleAsset	LP tokens

Aborts

• If swap fee is invalid
• If assets validation fails
• If pool already exists
• If any weight is zero
• If weights don’t sum to 100
• If any initial amount is zero

Liquidity Management

Add Liquidity (Stable)

public fun add_liquidity_stable(
    pool: Object<Pool>,
    assets_to_add: vector<FungibleAsset>
) : FungibleAsset

Adds liquidity to a stable pool.

Function Arguments

Argument	Type	Description
pool	Object<Pool>	Pool to add liquidity to
assets_to_add	vector<FungibleAsset>	Assets to add as liquidity

Returns

Type	Description
FungibleAsset	Minted LP tokens

Aborts

• If number of assets doesn’t match pool metadata
• If validation checks fail

Add Liquidity (Weighted)

public fun add_liquidity_weighted(
    pool: Object<Pool>,
    assets_to_add: vector<FungibleAsset>
) : (FungibleAsset, vector<FungibleAsset>)

Adds liquidity to a weighted pool with automatic refund handling.

Function Arguments

Argument	Type	Description
pool	Object<Pool>	Pool to add liquidity to
assets_to_add	vector<FungibleAsset>	Assets to add as liquidity

Returns

Type	Description
FungibleAsset	Minted LP tokens
vector<FungibleAsset>	Refunded assets

Aborts

• If number of assets doesn’t match pool metadata
• If validation checks fail

Remove Liquidity

public fun remove_liquidity(
    pool: Object<Pool>,
    lp_tokens: FungibleAsset
) : vector<FungibleAsset>

Removes liquidity from a pool by burning LP tokens.

Function Arguments

Argument	Type	Description
pool	Object<Pool>	Pool object
lp_tokens	FungibleAsset	LP tokens to burn

Returns

Type	Description
vector<FungibleAsset>	Withdrawn assets

Aborts

• If validation fails
• If vector lengths don’t match

Swap Functions

Exact Input Swaps

Stable Pool Swap (Exact In)

public fun swap_exact_in_stable(
    trader: &signer,
    pool: Object<Pool>,
    tokens_in: FungibleAsset,
    token_out: Object<Metadata>
) : FungibleAsset

Performs exact input swap in a stable pool.

Function Arguments

Argument	Type	Description
trader	&signer	Trader account
pool	Object<Pool>	Pool to swap in
tokens_in	FungibleAsset	Input tokens
token_out	Object<Metadata>	Output token metadata

Returns

Type	Description
FungibleAsset	Output tokens

Aborts

• If input amount is zero
• If simulate validation fails

Weighted Pool Swap (Exact In)

public fun swap_exact_in_weighted(
    trader: &signer,
    pool: Object<Pool>,
    input_tokens: FungibleAsset,
    token_out: Object<Metadata>
) : FungibleAsset

Performs exact input swap in a weighted pool.

Function Arguments

Argument	Type	Description
trader	&signer	Trader account
pool	Object<Pool>	Pool to swap in
input_tokens	FungibleAsset	Input tokens
token_out	Object<Metadata>	Output token metadata

Returns

Type	Description
FungibleAsset	Output tokens

Aborts

• If input amount is zero
• If simulate validation fails

Exact Output Swaps

Stable Pool Swap (Exact Out)

public fun swap_exact_out_stable(
    trader: &signer,
    pool: Object<Pool>,
    input_tokens: FungibleAsset,
    token_out: Object<Metadata>,
    exact_amount_out: u64
) : (FungibleAsset, FungibleAsset)

Performs exact output swap in a stable pool.

Function Arguments

Argument	Type	Description
trader	&signer	Trader account
pool	Object<Pool>	Pool to swap in
input_tokens	FungibleAsset	Input tokens
token_out	Object<Metadata>	Output token metadata
exact_amount_out	u64	Exact amount of output tokens

Returns

Type	Description
FungibleAsset	Refund tokens
FungibleAsset	Output tokens

Aborts

• If exact_amount_out is zero
• If input amount is insufficient

Weighted Pool Swap (Exact Out)

public fun swap_exact_out_weighted(
    trader: &signer,
    pool: Object<Pool>,
    input_tokens: FungibleAsset,
    token_out: Object<Metadata>,
    exact_amount_out: u64
) : (FungibleAsset, FungibleAsset)

Performs exact output swap in a weighted pool.

Function Arguments

Argument	Type	Description
trader	&signer	Trader account
pool	Object<Pool>	Pool to swap in
input_tokens	FungibleAsset	Input tokens
token_out	Object<Metadata>	Output token metadata
exact_amount_out	u64	Exact amount of output tokens

Returns

Type	Description
FungibleAsset	Refund tokens
FungibleAsset	Output tokens

Aborts

• If exact_amount_out is zero
• If input amount is insufficient

View Functions

Pool Information

Pool Assets Metadata

#[view]
public fun pool_assets_metadata(pool: Object<Pool>) : vector<Object<Metadata>>

Returns metadata of pool assets.

Pool Balances

#[view]
public fun pool_balances(pool: Object<Pool>) : vector<u64>

Returns current balances of pool assets.

Pool Size

#[view]
public fun pool_size(pool: Object<Pool>) : u64

Returns number of assets in a pool.

Pool Type

#[view]
public fun pool_type(pool: Object<Pool>) : u8

Returns pool type (100 for stable, 101 for weighted).

Pool Locked Status

#[view]
public fun pool_locked(pool: Object<Pool>) : bool

Returns if pool is locked.

Pool Swap Fee

#[view]
public fun pool_swap_fee_bps(pool: Object<Pool>) : u64

Returns swap fee in basis points.

Stable Pool Specific

Pool Amplification Factor

#[view]
public fun pool_amp_factor(pool: Object<Pool>) : u64

Returns amplification factor of a stable pool.

Pool Precision Multipliers

#[view]
public fun pool_precision_multipliers(pool: Object<Pool>) : vector<u64>

Returns precision multipliers for stable pool tokens.

Pool Invariant

public fun pool_invariant(pool: Object<Pool>) : u256

Returns current pool invariant for a stable pool.

Weighted Pool Specific

Pool Weights

#[view]
public fun pool_weights(pool: Object<Pool>) : vector<u64>

Returns weights for weighted pool tokens.

LP Token Information

LP Token Metadata

#[view]
public fun pool_lp_token_metadata(pool: Object<Pool>) : Object<Metadata>

Returns LP token metadata of a pool.

LP Token Supply

#[view]
public fun pool_lp_token_supply(pool: Object<Pool>) : u64

Returns LP token supply of a pool.

Pool Existence Checks

Stable Pool Exists

#[view]
public fun stable_pool_exists(
    token_metadata: vector<Object<Metadata>>,
    swap_fee_bps: u64
) : bool

Checks if a stable pool exists with given parameters.

Weighted Pool Exists

#[view]
public fun weighted_pool_exists(
    token_metadata: vector<Object<Metadata>>,
    weights: vector<u64>,
    swap_fee_bps: u64
) : bool

Checks if a weighted pool exists with given parameters.

Simulation Functions

Response Structs

SwapSimulate

struct SwapSimulate has drop {
    amount_in: u64,
    amount_in_post_fee: u64,
    amount_out: u64,
    amount_normalized_in: u128,
    amount_normalized_out: u128,
    total_fee_amount: u64,
    protocol_fee_amount: u64,
    idx_in: u64,
    idx_out: u64,
    swap_fee_bps: u64,
}

Simulate data for swap operations including fees and normalized amounts.

AddLiquiditySimulate

struct AddLiquiditySimulate has drop {
    minted_lp_token_amount: u64,
    refund_amounts: vector<u64>,
}

Simulate data for liquidity addition including LP tokens to mint and refund amounts.

RemoveLiquiditySimulate

struct RemoveLiquiditySimulate has drop {
    withdrawn_amounts: vector<u64>,
}

Simulate data for liquidity removal showing withdrawn token amounts.

Simulate Add Liquidity (Stable)

#[view]
public fun simulate_add_liquidity_stable_pool(
    pool: Object<Pool>,
    token_metadata_addr: vector<address>,
    deposit_amounts: vector<u64>
) : AddLiquiditySimulate

Simulates adding liquidity to a stable pool.

Simulate Add Liquidity (Weighted)

#[view]
public fun simulate_add_liquidity_weighted_pool(
    pool: Object<Pool>,
    token_metadata_addr: vector<address>,
    deposit_amounts: vector<u64>
) : AddLiquiditySimulate

Simulates adding liquidity to a weighted pool.

Simulate Remove Liquidity

#[view]
public fun simulate_remove_liquidity(
    pool: Object<Pool>,
    lp_token_metadata: Object<Metadata>,
    lp_tokens_to_burn: u64
) : RemoveLiquiditySimulate

Simulates removing liquidity from a pool.

Simulate Swap Functions

Stable Pool Swaps

#[view]
public fun simulate_swap_exact_in_stable(
    pool: Object<Pool>,
    token_in: Object<Metadata>,
    token_out: Object<Metadata>,
    amount_in: u64,
    trader: option::Option<address>
) : SwapSimulate

Simulates exact input swap in stable pool.

#[view]
public fun simulate_swap_exact_out_stable(
    pool: Object<Pool>,
    token_in: Object<Metadata>,
    token_out: Object<Metadata>,
    amount_out: u64,
    trader: option::Option<address>
) : SwapSimulate

Simulates exact output swap in stable pool.

Weighted Pool Swaps

#[view]
public fun simulate_swap_exact_in_weighted(
    pool: Object<Pool>,
    token_in: Object<Metadata>,
    token_out: Object<Metadata>,
    amount_in: u64,
    trader: option::Option<address>
) : SwapSimulate

Simulates exact input swap in weighted pool.

#[view]
public fun simulate_swap_exact_out_weighted(
    pool: Object<Pool>,
    token_in: Object<Metadata>,
    token_out: Object<Metadata>,
    amount_out: u64,
    trader: option::Option<address>
) : SwapSimulate

Simulates exact output swap in weighted pool.

Error Codes

Code	Name	Description
400	EINSUFFICIENT_PERMISSIONS	Caller has insufficient permissions
401	EPOOL_NOT_FOUND	Pool not found
402	EPOOL_ALREADY_EXISTS	Pool already exists
403	EPOOL_IS_LOCKED	Pool is locked
404	EINCORRECT_POOL_TYPE	Incorrect pool type
405	EVEC_LENGTH_MISMATCH	Vector length should match
406	EMULTIPLIERS_OUT_OF_BOUND	Multipliers should be less than or equal to 10000
407	ETOKEN_AMOUNT_SHOULD_BE_GREATER_THAN_ZERO	Token amount should be greater than zero
408	EPOOL_BALANCE_EXCEEDED	Pool output amount exceeds balance
409	ENEW_INVARIANT_MUST_BE_GREATER	New invariant must be greater than old invariant
410	ETOKEN_METADATA_DOES_NOT_MATCH	Token metadata does not match
411	EINVALID_TOKEN_METADATA	Token metadata not found in pool
412	ELP_TOKEN_AMOUNT_ZERO	LP token amount to mint is zero
413	ELP_AMOUNT_TOO_LOW	Initial LP amount too low
414	EINVALID_SWAP_FEE	Invalid swap fee
415	EINVALID_ASSETS_METADATA	Invalid assets metadata
416	EAMOUNT_SHOULD_BE_GREATER_THAN_ZERO	Amount should be greater than zero
417	EWEIGHTS_SHOULD_BE_GREATER_THAN_ZERO	Weights should be greater than zero
418	EWEIGHTS_SUM_TO_100	Weights should sum to 100%
419	EASSET_LENGTH_MISMATCH	Vector lengths do not match for asset operations
420	EBPS_DENOMINATOR_ZERO	BPS denominator is zero
421	ELP_SUPPLY_ZERO	Total LP supply is zero
422	EAMP_FACTOR_OUT_OF_RANGE	Amp factor out of range
423	ELAUNCHPAD_TOKEN_NOT_BONDED	Launchpad token that is not bonded, pool creation blocked
424	ELOCKED_STATUS_SAME	New locked status is same as old
425	EGLOBAL_POOL_OPS_PAUSED	Global pool operations are stopped
426	ERR_UNAUTHORIZED	Thrown when caller lacks required permissions
427	ERR_INITIALIZED	Thrown when initializing already initialized config
428	ERR_UNINITIALIZED	Thrown when accessing uninitialized config
429	ERR_BPS_GT_10000	Thrown when BPS value exceeds 10000 (100%)
430	ERR_ROLE_ALREADY_ASSIGNED	Role already assigned
431	ERR_TOKEN_STATUS_NOT_LAUNCHED	Token not launched
432	ERR_TOKEN_STATUS_NOT_VALID	Token status invalid