TECHNICAL ATMOS SWAP

Atmos Pump Module

Module Info

• Name: atmos_swap::atmos_pump
• Description: This module implements the Atmos pump mechanism for token launches. Manages bonding curve-based token sales with dynamic pricing, handles pool creation, token swaps, and automatic liquidity provision.

Public Entry Functions

Token Creation

Create

public entry fun create_fa(
    creator: &signer,
    name: String,
    symbol: String,
    uri: String,
    description: String,
    twitter: String,
    telegram: String,
    website: String,
    supra_amount: u64,
    min_tokens: u64,
    config_idx: u64
)

Creates a new token with bonding curve launch mechanism.

Function Arguments

Argument	Type	Description
creator	&signer	Account creating the token
name	String	Token name (≤ 300 chars)
symbol	String	Token symbol
uri	String	Token metadata URI (≤ 300 chars)
description	String	Project description (≤ 1000 chars)
twitter	String	Twitter handle (≤ 500 chars)
telegram	String	Telegram group (≤ 500 chars)
website	String	Project website (≤ 500 chars)
supra_amount	u64	Initial SUPRA to spend
min_tokens	u64	Minimum tokens to receive
config_idx	u64	Configuration index to use , this decides start and end mcap of the token , config_idx : 0 is the default value , to use any other config permissioned access will be needed

Process Flow

1. Validates string lengths and pump status
2. Creates dispatchable fungible asset
3. Sets up bonding curve pool
4. Executes initial buy if requested
5. Emits creation event

Aborts

• If global pump operations are paused
• If string lengths exceed limits
• If invalid configuration index

Trading Functions

Buy Tokens

public entry fun buy<TokenType>(
    buyer: &signer,
    pool_address: address,
    supra_in_with_fee: u64,
    min_tokens_out: u64,
    to_coin: bool,
    _integrator_address: address,
)

Executes token purchase from pump pool using bonding curve pricing.

Function Arguments

Argument	Type	Description
buyer	&signer	Account purchasing tokens
pool_address	address	Target pool address
supra_in_with_fee	u64	Maximum SUPRA willing to spend
min_tokens_out	u64	Minimum tokens to receive
to_coin	bool	Whether to receive as coin type -
for all fungiable coin this will be false
_integrator_address	address	Integrator for fee sharing ,
for integrator registeration contact us on discord , if integrator address is not registered with us this address will be ignored

Process Flow

1. Validates pool existence and completion status
2. Calculates fee and net SUPRA input
3. Determines available tokens and purchase amount
4. Executes swap using bonding curve
5. Handles token distribution and fee collection
6. Updates pool metrics and triggers events
7. Checks for graduation or milestone achievements

Aborts

• If pool not found or completed
• If insufficient SUPRA provided
• If slippage exceeds limits

Sell Tokens

public entry fun sell<TokenType>(
    seller: &signer,
    pool_address: address,
    token_amount: u64,
    min_supra_out: u64,
    to_coin: bool,
    _integrator_address: address,
)

Executes token sale back to pump pool using bonding curve pricing.

Function Arguments

Argument	Type	Description
seller	&signer	Account selling tokens
pool_address	address	Target pool address
token_amount	u64	Amount of tokens to sell
min_supra_out	u64	Minimum SUPRA to receive
to_coin	bool	Whether selling coin type
_integrator_address	address	for integrator registeration contact us on discord , if integrator address is not registered with us this address will be ignored

Process Flow

1. Validates pool and token amount
2. Calculates SUPRA output using bonding curve
3. Executes swap and handles fees
4. Updates pool volume and emits events
5. Records trading activity

Aborts

• If pool completed or invalid amount
• If insufficient token balance
• If slippage exceeds limits

Boost System

Boost Token

public entry fun boost_token(
    user: &signer,
    token_curve_address: address,
    boost_value: u64
)

Applies boost to a token using boost tickets.

Function Arguments

Argument	Type	Description
user	&signer	User applying boost
token_curve_address	address	Target token pool
boost_value	u64	Boost amount to apply

Process Flow

1. Consumes user's boost tickets
2. Adds boost value to pool
3. Sets expiration time (24 hours)
4. Emits boost mutation event

Aborts

• If pool not found or completed
• If insufficient boost tickets

View Functions

Pool Information

Get Pool Address

#[view]
public fun get_pool_address_fa(token: object::Object<Metadata>): address

Returns the pool address for a given token.

Get Configuration

#[view]
public fun get_configuration(pool_address: address): (u8, u64, u64, u64, u64, u8)

Retrieves current configuration for a pool.

Token Details

Get Token Details

struct TokenDetailsResponse has key {
    token_address: String,
    name: String,
    symbol: String,
    boost: u64,
    price: u64,
    is_completed: bool,
    is_crowned: bool,
    volume_supra: u64,
    current_mcap: u64,
    graduation_mcap: u64,
    king_of_space_mcap: u64,
    holders: u64
}

#[view]
public fun get_token_details(pool_address: address): TokenDetailsResponse

Returns comprehensive token information including market metrics.

Get Token Details (Multiple)

#[view]
public fun get_token_details_multi(pool_addresses: vector<address>): vector<TokenDetailsResponse>

Returns token details for multiple pools efficiently.

Get King of Space

#[view]
public fun get_king_of_space(): String

Returns the current "King of Space" token address.

Simulation Functions

Simulate Buy

#[view]
public fun simulate_buy(
    pool_address: address,
    supra_in_with_fee: u64
): (u64, u64, u64)

Simulates a buy operation without executing it.

Returns

• Expected token output
• SUPRA amount used (net of fee)
• Fee amount

Simulate Initial Buy

#[view]
public fun simulate_initial_buy(
    config_idx: u64,
    supra_in_with_fee: u64
): (u64, u64, u64)

Simulates initial buy for new token creation.

Simulate Sell

#[view]
public fun simulate_sell(
    pool_address: address,
    token_amount: u64
): (u64, u64, u64)

Simulates a sell operation without executing it.

Returns

• Expected SUPRA output
• Platform fee amount
• Net SUPRA amount (after fee)

Balance and Distribution

Get Holder Distribution

#[view]
public fun get_holder_distribution(token: address): simple_map::SimpleMap<address, u64>

Returns the distribution of token holders and their balances.

Get User Balances

#[view]
public fun get_user_balances(user_address: address): simple_map::SimpleMap<address, u64>

Returns all token balances for a specific user.

Get User Balance

#[view]
public fun get_user_balance(user_address: address, token_address: address): u64

Returns user's balance for a specific token.

Error Codes

Code	Name	Description
101	EINVALID_STRING_LENGTH	Invalid string length provided
102	EINVALID_DESCRIPTION_LENGTH	Invalid description length provided
103	EINVALID_TWITTER_LENGTH	Invalid Twitter handle length provided
104	EINVALID_TELEGRAM_LENGTH	Invalid Telegram handle length provided
105	EINVALID_WEBSITE_LENGTH	Invalid website URL length provided
106	EPOOL_NOT_FOUND	Pool not found
107	EPOOL_COMPLETED	Pool has already completed
108	EINVALID_MIN_TOKENS	Invalid minimum tokens amount provided
109	EINSUFFICIENT_SUPRA	Insufficient SUPRA tokens for operation
110	EINVALID_TOKEN_AMOUNT	Invalid token amount provided
111	EINSUFFICIENT_MIN_OUT	Insufficient minimum output amount
112	ENO_INPUT_AMOUNT	No input amount provided
113	EPOOL_VALUE_DECREASED	Pool value has decreased below threshold
114	ENOT_ADMIN	Caller is not an admin
115	EPOOL_ADDRESS_NOT_FOUND	Pool address not found
116	EINVALID_PLATFORM_FEE	Invalid platform fee provided
117	EINVALID_GRADUATED_FEE	Invalid graduated fee provided
118	EINVALID_VIRTUAL_RESERVES	Invalid virtual reserves provided
119	EINVALID_REMAIN_TOKENS	Invalid remaining tokens amount
120	EINVALID_TOKEN_DECIMALS	Invalid token decimals provided
121	EPAUSED	Contract is paused
122	EGLOBAL_PUMP_OPS_PAUSED	Global pump operations are paused
123	EDISPATCHABLE_FA_NOT_INITIALIZED	Dispatchable fungible asset not initialized
124	ESUPRA_METADATA_NOT_FOUND	SUPRA coin metadata not found
125	EPOOL_NOT_FOUND_BOOST	Pool not found for boost operation
126	EINSUFFICIENT_BOOST_VALUE	Insufficient boost value for operation
127	EINVALID_STRING_OPERATION	Invalid string manipulation operation
128	EDIVISION_BY_ZERO	Division by zero error
129	EARITHMETIC_OVERFLOW	Arithmetic overflow error
130	EINVALID_MARKET_CAP	Invalid market cap calculation

Boost System Architecture

Boost Mechanics

• Duration: 24-hour boost periods
• Ticket System: Users consume boost tickets
• Visibility: Boosted tokens get enhanced exposure
• Expiration: Automatic boost removal after expiry
• Batch Processing: Efficient expiration handling

Expiration Process

1. Batch Processing: Processes multiple expired boosts
2. Pool Updates: Removes boost values from pools
3. Event Emission: Tracks boost state changes
4. Index Management: Maintains processing efficiency

Integration Points

GameFi Integration

• Daily Activity: Marks users active for missions
• Trading Missions: Records buy/sell activities
• Creator Missions: Rewards for successful launches
• Milestone Rewards: Achievements for reaching thresholds

Fee Sharing

• Protocol Fees: Distributed through fee sharing system
• Integrator Fees: Support for partner platforms
• Treasury Management: Automatic fee collection

Liquidity Pool Integration

• Launchpad Registry: Tracks launched tokens
• Pool Creation: Seamless transition to permanent pools
• Bond Status: Controls when pools can be created

Economic Security

• Invariant Protection: Bonding curve K value preservation
• Fee Validation: Prevents excessive fees
• Reserve Minimums: Ensures sufficient liquidity
• Slippage Protection: User-defined minimum outputs

Technical Security

• Overflow Prevention: Safe arithmetic operations
• State Validation: Comprehensive input checking
• Event Integrity: Complete audit trail
• Resource Management: Efficient storage and cleanup