ifalabs::hetero_swap_periphery) — the intended entry point for integrators — and the core module (ifalabs::hetero_swap_core), which contains the actual logic, error codes, and admin functions.
For the underlying price feed this contract consumes, see Sui Function Reference.
Package Structure
Every periphery function is a thin wrapper that delegates directly to the matching core function. There is no safety difference between calling periphery vs. core — but periphery is the documented, stable interface.
Data Types
Pool
The central shared object coordinating the swap contract.
&mut Pool for state-changing operations and &Pool for read-only quotes and summaries.
AssetConfig
Per-asset configuration stored inside the Pool. Returned as part of get_asset_summary.
AssetVault<T>
A generic shared object holding token reserves and cached valuation for asset type T.
ProtocolFeeVault<T>
A generic shared object accumulating the protocol’s fee share for asset type T.
swap_exact_input and sweep — not for deposits or withdrawals.
Error Codes
These are the actual error constants fromhetero_swap_core. Every abort in the swap contract maps to one of these.
Liquidity Functions
deposit_liquidity
Deposits a supported asset into the pool and mints HLP tokens proportional to the deposit’s USD value.
Verified abort sequence:
E_POOL_PAUSEDif the pool is pausedE_ASSET_NOT_WHITELISTED/E_ASSET_DISABLEDifTisn’t whitelisted or is disabledE_ZERO_AMOUNTif the deposited coin has zero valueE_ORACLE_PRICE_MISSING/E_ORACLE_PRICE_STALEif the oracle price forTis missing or staleE_ZERO_AMOUNTif the computed USD value of the deposit is zeroE_LP_SUPPLY_ZEROif this is not the first deposit andaccounted_value_usdis somehow zero (an invariant guard, not a normal user-facing case)E_ZERO_AMOUNTif the resulting HLP mint amount rounds to zeroE_SLIPPAGEif the resulting HLP mint amount is less thanmin_lp_out
- The first-ever deposit into the pool mints HLP at a fixed ratio (USD value scaled from 30 decimals down to 9 LP decimals) — there is no existing supply to price against.
- Every subsequent deposit mints HLP proportional to
deposit_value_usd / accounted_value_usd × total_lp_supply. - HLP is minted directly to
ctx.sender()— you cannot deposit on behalf of another address.
withdraw_liquidity
Burns HLP tokens to redeem a proportional share of a specific asset from the pool.
Verified abort sequence:
E_POOL_PAUSEDif the pool is pausedE_ASSET_NOT_WHITELISTED/E_ASSET_DISABLEDifTisn’t whitelisted or is disabledE_ZERO_AMOUNTiflp_coinhas zero valueE_LP_SUPPLY_ZEROiftotal_lp_supplyis zero (should never happen if you hold valid HLP)E_ORACLE_PRICE_MISSING/E_ORACLE_PRICE_STALEfor assetTE_ZERO_AMOUNTif the computed output amount rounds to zeroE_SLIPPAGEif the output is less thanmin_amount_outE_INSUFFICIENT_LIQUIDITYifvaultdoesn’t physically hold enough of assetTE_WITHDRAW_TOO_LARGEif the withdrawal exceedsmax_withdraw_bpsof the vault’s current balanceE_MIN_LIQUIDITYif the withdrawal would drop the vault below its configured floor
Swap Functions
swap_exact_input
Swaps an exact amount of one asset for another, priced via the oracle’s derived pair calculation.
Verified abort sequence:
E_POOL_PAUSEDif the pool is pausedE_SAME_ASSETifTInandTOutare the same typeE_ASSET_NOT_WHITELISTED/E_ASSET_DISABLEDfor eitherTInorTOutE_ZERO_AMOUNTifcoin_inhas zero valueE_ORACLE_PRICE_STALEif the derived pair’s combined timestamp is stale (checked first, viaquote_exact_input_internal)E_SLIPPAGEif the net output (after both fees) is less thanmin_amount_outE_INSUFFICIENT_LIQUIDITYifvault_outdoesn’t hold enough foramount_out + protocol_feeE_TRADE_TOO_LARGEif the raw output exceedsmax_trade_bpsofvault_out’s balanceE_MIN_LIQUIDITYif the trade would dropvault_outbelow its floorE_ORACLE_PRICE_MISSING/E_ORACLE_PRICE_STALEagain — re-fetched individually per-asset for USD accounting (in addition to the derived-pair check above)
raw_amount_out from the oracle-derived exchange rate, then deducts two fees from it:
lp_fee portion stays in vault_out (implicitly benefiting all LPs by not being paid out). The protocol_fee portion is physically moved into protocol_fee_vault_out.
Example:
sweep
Converts a dust balance of one asset directly into a target asset. This is exposed only in the periphery module — hetero_swap_core has no separate sweep function. It calls swap_exact_input internally with renamed type parameters.
swap_exact_input in every respect — same abort sequence, same fee mechanics. There is no relaxed validation path for sweep transactions; it is swap_exact_input under a different name.
To sweep multiple dust tokens into one target asset, compose multiple
sweep calls — one per dust token — within a single Sui Programmable Transaction Block (PTB). Each call independently enforces every check listed for swap_exact_input.Quote Functions (Read-Only)
These simulate the result of an operation without executing it. None mutate state. All still perform the same oracle freshness checks as their state-changing counterparts — a quote can abort withE_ORACLE_PRICE_STALE exactly like a real swap would.
quote_exact_input
Example:
quote_sweep
Identical signature, identical internal logic to quote_exact_input — provided as a semantically named alias for previewing a sweep operation.
quote_exact_input.
preview_deposit
u64 — the expected HLP token amount to be minted. Uses the exact same math as deposit_liquidity, so this value should match what you actually receive (assuming no price change between the quote and the real transaction).
preview_withdraw
u64 — the expected amount of asset T you’d receive for burning lp_amount of HLP.
Pool and Asset Inspection
get_pool_summary
total_lp_supply and accounted_value_usd come before the fee fields, not after.
get_asset_summary
Other Read-Only Functions
These are simpler getters also exposed byhetero_swap_core, useful for building dashboards without needing the full summary structs.
Admin-Only Functions
These all require theAdminCap — held by the IFÁ Labs team. Listed for transparency and so you understand what configuration changes are possible, not because integrators call them.
Notice
pause is a true global switch — there is no per-asset pause. If you need to react to a paused pool in your own integration, check get_pool_summary().0 (the first return value) before attempting any operation.Function Quick Reference
Next Steps
Sui Swap Contract Overview
Architecture, core concepts, and what’s deployed on testnet.
Swap Contract Addresses
Package ID, Pool ID, AdminCap, and every asset vault on Sui Testnet.
Sui Function Reference
The underlying oracle functions this contract consumes.
Testnet Faucet
Claim testnet tokens to try deposits and swaps yourself.

