Atmos Entry Module

Module Info

• Package Name: AtmosSwap
• Address: atmos_swap=0xa4a4a31116e114bf3c4f4728914e6b43db73279a4421b0768993e07248fe2234
• Module: atmos_swap::atmos_entry
• Description: This module provides high-level entry points for Atmos Swap protocol operations using fungible assets directly. Handles user interactions with pools including creation, liquidity management, and swaps exclusively with the fungible asset standard. Use this module for operations with FAs only, while atmos_entry_coin provides compatibility for both coin types and fungible assets. Manages both stable and weighted pool operations with safety checks and comprehensive validation.

Public Entry Functions

Liquidity Management

Add Liquidity (Stable Pool)

public entry fun add_liquidity_stable_entry(
    user: &signer,
    pool: object::Object<Pool>,
    deposit_amounts: vector<u64>,
    min_lp_amount: u64
)

Adds liquidity to stable pool with safety checks. Handles token collection and LP token distribution.

Function Arguments

Argument	Type	Description
user	&signer	Account adding liquidity
pool	Object<Pool>	Target pool
deposit_amounts	vector<u64>	Amount for each token
min_lp_amount	u64	Minimum acceptable LP tokens

Process Flow

1. Validates input parameters
2. Collects tokens from user
3. Adds liquidity to pool
4. Returns LP tokens

Aborts

• If amounts don't match pool tokens
• If user has insufficient balance
• If LP tokens below minimum

Add Liquidity (Weighted Pool)

public entry fun add_liquidity_weighted_entry(
    user: &signer,
    pool: object::Object<Pool>,
    deposit_amounts: vector<u64>,
    min_lp_amount: u64
)

Adds liquidity to weighted pool with safety checks. Handles token collection, LP token distribution, and refunds.

Function Arguments

Argument	Type	Description
user	&signer	Account adding liquidity
pool	Object<Pool>	Target pool
deposit_amounts	vector<u64>	Amount for each token
min_lp_amount	u64	Minimum acceptable LP tokens

Process Flow

1. Validates inputs
2. Collects tokens
3. Adds liquidity
4. Returns LP tokens
5. Processes refunds

Aborts

• If amounts don't match pool tokens
• If user has insufficient balance
• If LP tokens below minimum

Remove Liquidity

public entry fun remove_liquidity_entry(
    user: &signer,
    pool: object::Object<Pool>,
    lp_token: object::Object<fungible_asset::Metadata>,
    lp_amount: u64,
    min_amounts: vector<u64>
)

Remove liquidity from a pool with comprehensive validation.

Function Arguments

Argument	Type	Description
user	&signer	The signer of the user account removing liquidity
pool	Object<Pool>	The pool object to remove liquidity from
lp_token	Object<Metadata>	LP token metadata object
lp_amount	u64	Amount of LP tokens to burn
min_amounts	vector<u64>	Minimum amounts of tokens to receive

Aborts

• If lp_amount is zero
• If user has insufficient LP tokens
• If received amounts are less than minimum amounts

Pool Creation

Create Stable Pool

public entry fun create_pool_stable_entry(
    user: &signer,
    token_metadata: vector<object::Object<fungible_asset::Metadata>>,
    deposit_amounts: vector<u64>,
    swap_fee_bps: u64,
    amp_factor: u64
)

Creates new stable pool with initial liquidity. Sets up pool parameters and deposits initial tokens.

Function Arguments

Argument	Type	Description
user	&signer	Account creating pool
token_metadata	vector<Object<Metadata>>	Pool token details
deposit_amounts	vector<u64>	Initial liquidity amounts
swap_fee_bps	u64	Trading fee in basis points
amp_factor	u64	Amplification parameter

Process Flow

1. Validates parameters
2. Collects initial tokens
3. Creates pool
4. Returns LP tokens

Aborts

• If amounts don't match tokens
• If user has insufficient balance

Create Weighted Pool

public entry fun create_pool_weighted_entry(
    user: &signer,
    token_metadata: vector<object::Object<fungible_asset::Metadata>>,
    deposit_amounts: vector<u64>,
    pool_weights: vector<u64>,
    swap_fee_bps: u64
)

Creates new weighted pool with initial liquidity. Sets up pool with custom token weights.

Function Arguments

Argument	Type	Description
user	&signer	Account creating pool
token_metadata	vector<Object<Metadata>>	Pool token details
deposit_amounts	vector<u64>	Initial liquidity amounts
pool_weights	vector<u64>	Weight for each token
swap_fee_bps	u64	Trading fee in basis points

Process Flow

1. Validates parameters
2. Collects initial tokens
3. Creates weighted pool
4. Returns LP tokens

Aborts

• If amounts don't match tokens
• If user has insufficient balance

Swap Functions

Exact Input Swaps

Stable Pool Swap (Exact In)

public entry fun swap_exact_in_stable_entry(
    trader: &signer,
    pool: object::Object<Pool>,
    token_in: object::Object<fungible_asset::Metadata>,
    amount_in: u64,
    token_out: object::Object<fungible_asset::Metadata>,
    min_amount_out: u64
)

Performs exact input swap in stable pool with slippage protection.

Function Arguments

Argument	Type	Description
trader	&signer	The signer of the trader account
pool	Object<Pool>	The pool object to swap in
token_in	Object<Metadata>	Input token metadata
amount_in	u64	Amount of input tokens
token_out	Object<Metadata>	Output token metadata
min_amount_out	u64	Minimum amount of output tokens to receive

Aborts

• If amount_in is zero
• If trader has insufficient balance
• If output amount is less than min_amount_out

Weighted Pool Swap (Exact In)

public entry fun swap_exact_in_weighted_entry(
    trader: &signer,
    pool: object::Object<Pool>,
    token_in: object::Object<fungible_asset::Metadata>,
    amount_in: u64,
    token_out: object::Object<fungible_asset::Metadata>,
    min_amount_out: u64
)

Performs exact input swap in weighted pool with slippage protection.

Function Arguments

Argument	Type	Description
trader	&signer	The signer of the trader account
pool	Object<Pool>	The pool object to swap in
token_in	Object<Metadata>	Input token metadata
amount_in	u64	Amount of input tokens
token_out	Object<Metadata>	Output token metadata
min_amount_out	u64	Minimum amount of output tokens to receive

Aborts

• If amount_in is zero
• If trader has insufficient balance
• If output amount is less than min_amount_out

Exact Output Swaps

Stable Pool Swap (Exact Out)

public entry fun swap_exact_out_stable_entry(
    trader: &signer,
    pool: object::Object<Pool>,
    token_in: object::Object<fungible_asset::Metadata>,
    max_amount_in: u64,
    token_out: object::Object<fungible_asset::Metadata>,
    exact_amount_out: u64
)

Performs exact output swap in stable pool with automatic refund handling.

Function Arguments

Argument	Type	Description
trader	&signer	The signer of the trader account
pool	Object<Pool>	The pool object to swap in
token_in	Object<Metadata>	Input token metadata
max_amount_in	u64	Maximum amount of input tokens
token_out	Object<Metadata>	Output token metadata
exact_amount_out	u64	Exact amount of output tokens to receive

Aborts

• If exact_amount_out is zero
• If trader has insufficient balance

Weighted Pool Swap (Exact Out)

public entry fun swap_exact_out_weighted_entry(
    trader: &signer,
    pool: object::Object<Pool>,
    token_in: object::Object<fungible_asset::Metadata>,
    max_amount_in: u64,
    token_out: object::Object<fungible_asset::Metadata>,
    exact_amount_out: u64
)

Performs exact output swap in weighted pool with automatic refund handling.

Function Arguments

Argument	Type	Description
trader	&signer	The signer of the trader account
pool	Object<Pool>	The pool object to swap in
token_in	Object<Metadata>	Input token metadata
max_amount_in	u64	Maximum amount of input tokens
token_out	Object<Metadata>	Output token metadata
exact_amount_out	u64	Exact amount of output tokens to receive

Aborts

• If exact_amount_out is zero
• If trader has insufficient balance

Administrative Functions

Set Amplification Factor

public entry fun set_stable_pool_amp_factor(
    admin: &signer,
    pool: object::Object<Pool>,
    new_amp_factor: u64
)

Updates amplification factor for a stable pool.

Function Arguments

Argument	Type	Description
admin	&signer	The signer of the admin account
pool	Object<Pool>	The pool object to modify
new_amp_factor	u64	New amplification factor value

Aborts

• If caller is not an admin

Set Protocol Fee Allocation

public entry fun set_swap_fee_protocol_allocation_bps(
    admin: &signer,
    new_allocation_bps: u64
)

Updates protocol allocation of swap fees.

Function Arguments

Argument	Type	Description
admin	&signer	The signer of the admin account
new_allocation_bps	u64	New allocation in basis points

Aborts

• If caller is not an admin
• If allocation exceeds maximum allowed

Error Codes

Code	Name	Description
100	EINVALID_AMOUNT	Invalid amount of tokens
101	EBALANCE_TOO_LOW	Insufficient balance
102	EINVALID_VECTOR_LENGTH	Invalid vector length
103	EINSUFFICIENT_OUTPUT_AMOUNT	Insufficient output amount
104	EINVALID_COIN_VERSION	Invalid output coin version
105	EBOTH_TOKENS_MUST_BE_SAME	Both tokens must be the same
106	EINVALID_HOPS	Hops should be between [1,3]