Pool (v2)

STON.fi v2 Pool smart contract - enhanced AMM pools with vault mechanics and optimization

Off-chain get methods

get_pool_data

Returns the current state of the Pool

_ get_pool_data() method_id;

Arguments

None

Result (common)

Returns PoolData structure containing current state of the pool. Typed pools may return additional arguments if present

PoolData structure

Key	Type	Index	Description
is_locked	bool	0	true if transfer_notification operations are locked (swap, provide_lp)
router_address	address	1	Address of the Router
total_supply	coins	2	Total supply of lp tokens
reserve0	coins	3	Amount of the first token (in basic token units)
reserve1	coins	4	Amount of the second token (in basic token units)
token0_wallet_address	address	5	Address of the first Jetton token
token1_wallet_address	address	6	Address of the second Jetton token
lp_fee	uint16	7	Liquidity pool fee value
protocol_fee	uint16	8	Protocol fee
protocol_fee_address	address	9	Address for receiving protocol fees
collected_token0_protocol_fee	coins	10	Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee	coins	11	Amount of collected protocol fees of the second token (in basic token units)

Notes:

• fee ratio is the value of fee divided by params::fee_divider (10000); so a fee of 1% has a value of 100

Result (stableswap)

Additional data in PoolData structure specific to stableswap pools

PoolData structure additional params

Key	Type	Index	Description
amp	uint32	12	Stableswap amplification parameter

Result (weighted_stableswap)

Additional data in PoolData structure specific to weighted stableswap pools

PoolData structure additional params

Key	Type	Index	Description
amp	uint128	12	Weighted stableswap amplification parameter
rate	uint128	13	Stable token ratio parameter
w0	uint128	14	Token 0 weight parameter
rate_setter	address	15	Address with rights to change rate

Result (weighted_const_product)

Additional data in PoolData structure specific to weighted constant product pools

PoolData structure additional params

Key	Type	Index	Description
w0	uint128	12	Token 0 weight parameter

get_lp_account_address

Get the lp account address of a user

slice get_lp_account_address(slice owner_address) method_id;

Arguments

Key	Type	Description
owner_address	address	Address of a user

Result

Returns the lp account address of a user

get_jetton_data

Standard jetton 'get' methods from TonWeb JettonMinter.

(int, int, slice, cell, cell) get_jetton_data() method_id;

Arguments

None

Result

Returns a structure with Jetton data

JettonData structure

Key	Type	Index	Description
total_supply	coins	0	Total token supply of lp tokens (in basic token units)
mintable	bool	1	always true
admin_address	address	2	Router address
jetton_content_uri	string	3	Offchain uri with Jetton data
jetton_wallet_code	cell	4	Code of the lp Jetton wallet

get_wallet_address

Get lp wallet address of a user.

slice get_wallet_address(slice owner_address) method_id;

Arguments

Name	Type	Description
owner_address	address	Address of a user

Result

Returns a calculated lp wallet address of a user

get_pool_type

Get Pool type, equals to dex_type param in get_router_data

_ get_pool_type() method_id;

Arguments

None

Result

Return pool type of this pool as string:

• constant_product

• stableswap

• weighted_stableswap

• weighted_const_product

On-chain queries

On-chain counterparts of getter methods.

Operations table

Name	Value	Description
getter_pool_data	0x26df39fc	Sends a message with the current state of the pool
getter_lp_account_address	0x15fbca95	Sends a message with the lp account address of a user
provide_wallet_address	0x2c76b973	Sends a message with the lp wallet address of a user

getter_pool_data (0x26df39fc)

Sends a message with the current state of the pool. On-chain equivalent of get_pool_data.

TL-B

getter_pool_data#26df39fc query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends a message with current pool data to the sender_address

Response message body

Name	Type	Description
op	uint32	Operation code is equal to getter_pool_data
query_id	uint64	Query id
is_locked	uint1	If this Pool is locked
reserve0	coins	Amount of the first token (in basic token units)
reserve1	coins	Amount of the second token (in basic token units)
token0_address	address	Address of the first Jetton token
token1_address	address	Address of the second Jetton token
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
lp_fee	uint16	Liquidity pool fee value
protocol_fee	uint16	Protocol fee
router_address	address	Address of the Router
protocol_fee_address	address	Address for receiving protocol fees
total_supply	coins	Total amount of minted lp tokens
collected_token0_protocol_fee	coins	Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee	coins	Amount of collected protocol fees of the second token (in basic token units)

getter_lp_account_address (0x15fbca95)

Sends a message with the lp account address of a user. On-chain equivalent of get_lp_account_address.

TL-B

getter_lp_account_address#15fbca95 query_id:uint64 user_address:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
user_address	address	Address of a user

Outgoing messages

Sends a message with the lp account address of a user to sender_address

Response message body

Name	Type	Description
op	uint32	Operation code is equal to getter_expected_outputs
query_id	uint64	Query id
lp_account_address	address	lp account address of a user

provide_wallet_address (0x2c76b973)

Sends a message with the lp wallet address of a user. On-chain equivalent of get_wallet_address.

TL-B

provide_wallet_address#2c76b973 query_id:uint64 owner_address:MsgAddress include_address?:Bool = InternalMsgBody;

Message body

Name	Type	Description
owner_address	address	Address of a user
include_address?	uint1	Include user address in the response message

Outgoing messages

Sends a message back to sender with the calculated lp wallet address of a user

Response message body

Name	Type	Description
op	uint32	Operation code is equal to take_wallet_address (0xd1735400)
query_id	uint64	Query id
lp_wallet_address	address	Calculated lp wallet address
additional_data	maybe_ref	Cell with data if include_address? evaluates to true

additional_data body

Name	Type	Description
included_address	address	Address of a user

Jetton handlers

Handles operations sent from a Jetton wallet.

Operations table

Name	Value	Description
burn_notification_ext	0x297437cf	Sent by LP wallet after burning LP jettons to release liquidity

burn_notification_ext (0x297437cf)

Sent by LpWallet after burning LP jettons to release liquidity.

TL-B

burn_notification_ext#297437cf query_id:uint64 jetton_amount:Coins from_address:MsgAddress response_address:MsgAddress maybe_custom_payload:(Maybe ^Cell) = InternalMsgBody;

Message body

Name	Type	Description
jetton_amount	coins	Amount of liquidity tokens to burn (in basic token units)
from_address	address	User address
response_address	address	Address for a response message
custom_payloads	maybe_ref	Payloads for token0 and token1

custom_payloads

Name	Type	Description
payload_1	maybe_ref	Payload used for amount0; can be cross_swap
payload_2	maybe_ref	Payload used for amount1; can be cross_swap

Outgoing messages

Sends a message with op excesses (0xd53276db) to response_address

Sends a message with a released amount of both tokens to be received by a user as a result of the burn operation to the router, which initiates pay_to operation to from_address

Router internal message handlers

Handles messages from the router.

Operations table

Name	Value	Description
swap	0x6664de2a	Swap tokens
provide_lp	0x37c096df	Provide liquidity
reset_gas	0x29d22935	Reset gas
set_fees	0x58274069	Set new fee parameters

swap (0x6664de2a)

Swap tokens. This message is received from the router when the user initiates a token swap.

TL-B

swap#6664de2a query_id:uint64 from_user:MsgAddress left_amount:Coins right_amount:Coins dex_payload:^[transferred_op:uint32 token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 swap_body:^[min_out:Coins receiver:MsgAddress fwd_gas:Coins custom_payload:(Maybe ^Cell) refund_fwd_gas:Coins refund_payload:(Maybe ^Cell) ref_fee:uint16 ref_address:MsgAddress]] = InternalMsgBody;

Message body

Name	Type	Description
from_user	address	User address
amount0	coins	Amount of incoming first token
amount1	coins	Amount of incoming second token
payload	cell	Cell with dex payload

payload body

Name	Type	Description
op	uint32	Swap op
other_token_wallet	address	Address of the other Routertoken wallet
refund_address	address	Address where refund will be sent if swap fails
excesses_address	address	Address where TON excesses will be sent
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
min_out	coins	Minimum required amount of tokens to receive
receiver_address	address	Address where tokens will be sent after swap
fwd_gas	coins	Gas used to forward a message in transfer_notification after swap if custom_payload is present
custom_payload	maybe_ref	Payload sent in transfer_notification after swap
refund_fwd_gas	coins	Gas used to forward a message in transfer_notification if swap fails if refund_payload is present
refund_payload	maybe_ref	Payload sent in transfer_notification if swap fails
ref_fee	uint16	Referral fee
referral_address	address	Referral address

Notes:

• swap will fail if a user should receive less than min_out of tokens as a result

• max allowed value of ref_fee is 100 (1%)

Outgoing messages

Sends a message with an amount of the other tokens to be received by a user as a result of the swap to the router, which initiates pay_to operation

Additionally may send a message with referrer fees to the router, which initiates pay_vault operation to Vault of referral_address

provide_lp (0x37c096df)

Provide liquidity for the pool. A user must submit an amount of both tokens to receive lp tokens and add new liquidity to a pool. This message is routed to liquidity pool account with add_liquidity operation code.

TL-B

provide_lp#37c096df query_id:uint64 from_user:MsgAddress left_amount:Coins right_amount:Coins dex_payload:^[transferred_op:uint32 token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 provide_lp_body:^[min_lp_out:Coins to_address:MsgAddress both_positive:uint1 fwd_amount:Coins custom_payload:(Maybe ^Cell)]] = InternalMsgBody;

Message body

Name	Type	Description
from_user	address	User address
amount0	coins	Amount of incoming first token
amount1	coins	Amount of incoming second token
payload	cell	Cell with dex payload

payload body

Name	Type	Description
op	uint32	Provide lp op
other_token_wallet	address	Address of the other Router token wallet
refund_address	address	Address where refund will be sent if swap fails
excesses_address	address	Address where TON excesses will be sent
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
min_lp_out	coins	Minimum required amount of lp tokens to receive
receiver_address	address	Address where lp tokens will be sent
both_positive	uint1	Trigger liquidity deposit only if both token amounts are non-zero
fwd_gas	coins	Gas used to forward a message in transfer_notification after mint if custom_payload is present
custom_payload	maybe_ref	Payload sent in transfer_notification after lp mint

Outgoing messages

Sends a message to liquidity pool account with add_liquidity operation code.

reset_gas (0x29d22935)

Updates the amount of TON (in nanoTons) on the pool to storage_fee::pool (10000000) of the pool. The remaining amount of TON will be sent to excesses_address.

TL-B

reset_gas#29d22935 query_id:uint64 = InternalMsgBody;

Message body

Name	Type	Description
excesses_address	address	Address where excess ton will be sent

Outgoing messages

Sends a message to excesses_address with the remaining TON

internal_set_fees (0x75930d63)

Set new fee values including liquidity pool fees, protocol fees and referral fees as well as an address for receiving collected protocol fees.

TL-B

internal_set_fees#75930d63 query_id:uint64 new_lp_fee:uint16 new_protocol_fee:uint16 new_protocol_fee_address:MsgAddress excesses_address:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
new_lp_fee	uint16	New liquidity pool fee ratio (multiplied by params::fee_divider)
new_protocol_fee	uint16	New protocol fee ratio (multiplied by params::fee_divider)
new_protocol_fee_address	address	Address for receiving protocol fees
excesses_address	address	Address where TON excesses will be sent

Notes:

• fee ratio is the value of fee divided by params::fee_divider (10000); so to set a fee to 1% the value must be 100

• fees must be between params::min_fee (0) and params::max_fee (100)

Outgoing messages

Sends a message to excesses_address with the remaining TON

---

Protocol address internal message handlers

Handles messages from the protocol_fee_address.

Operations table

Name	Value	Description
collect_fees	0x1ee4911e	Collect fees

collect_fees (0x1ee4911e)

Collect protocol fees. The amount of fees in both tokens will be sent to protocol_fee_address address.

TL-B

collect_fees#1ee4911e query_id:uint64 maybe_payload0:(Maybe ^Cell) maybe_payload1:(Maybe ^Cell) = InternalMsgBody;

Message body

Name	Type	Description
payload_0	maybe_ref	Payload used for amount0; can be cross_swap
payload_1	maybe_ref	Payload used for amount1; can be cross_swap

Outgoing messages

Sends a message with collected fees in both tokens to the router, which initiates pay_to operation to protocol_fee_address.

LP Account internal message handlers

Handles messages from an lp account.

Operations table

Name	Value	Description
cb_add_liquidity	0x06ecd527	Sent by user's lp_account after adding liquidity
cb_refund_me	0x0f98e2b8	Sent by user's lp_account after adding liquidity

cb_add_liquidity (0x06ecd527)

Add new liquidity to the pool. Sent by user's lp account after both or one amounts tokens is sent by a user. The resulting added liquidity must be greater than min_lp_out for the operation to be successful.

TL-B

cb_add_liquidity#6ecd527 query_id:uint64 tot_am0:Coins tot_am1:Coins user_address:MsgAddress min_lp_out:Coins fwd_amount:Coins custom_payload_cs:(Maybe ^Cell) additional_fields:^[to_user_address:MsgAddress refund_address:MsgAddress excess_address:MsgAddress] = InternalMsgBody;

Message body

Name	Type	Description
amount0	coins	Amount of the first Jetton tokens added (in basic token units)
amount1	coins	Amount of the second Jetton tokens added (in basic token units)
user_address	address	Owner's address
min_lp_out	coins	Minimum amount of received liquidity tokens (in basic token units)
fwd_amount	coins	Forward amount used to send custom_payload (if present) in transfer_notification
custom_payload	maybe_ref	Payload sent in transfer_notification upon receiving tokens
additional_data	ref	See table below

additional_data

Name	Type	Description
to_address	address	Owner of new liquidity tokens
refund_address	address	Address of the owner of LpAccount where tokens will be refunded if liquidity mint wasn't successful
excess_address	address	Address where all TON excesses will be sent

Notes:

• addition of liquidity will fail if a user should receive less than min_lp_out of lp tokens as a result

• cannot add liquidity if a supply of either tokens becomes greater than MAX_COINS (2^120 - 1)

Outgoing messages

Sends a message with internal_transfer (0x178d4519) op code to the lp wallet of to_address with minted liquidity tokens

cb_refund_me (0x0f98e2b8)

Sent by user's lp account after a user initiates refund_me operation to cancel addition of new liquidity. The amount of previously stored tokens will be sent back to the user.

TL-B

cb_refund_me#f98e2b8 query_id:uint64 tot_am0:Coins tot_am1:Coins user_address:MsgAddress left_maybe_payload:(Maybe ^Cell) right_maybe_payload:(Maybe ^Cell) = InternalMsgBody;

Message body

Name	Type	Description
amount0	coins	Amount of the first Jetton tokens (in basic token units)
amount1	coins	Amount of the second Jetton tokens (in basic token units)
user_address	address	Owner's address
payload_0	maybe_ref	Payload used for amount0; can be cross_swap
payload_1	maybe_ref	Payload used for amount1; can be cross_swap

Outgoing messages

Sends a message with amount0 of the first token and amount1 of the second token to the router, which initiates pay_to operation

---

Constants

Name	Value	Description
storage_fee::pool	10000000	Amount of TON (in nanoTons) to be left on the pool contract as gas
params::required_min_liquidity	1001	Minimum amount of liquidity required
MAX_COINS	2^120 - 1	Maximum amount of tokens (in basic token units) stored as liquidity
gas::pool::provide_wallet_address	20000000	Additional gas (in nanoTons) for providing a wallet
params::fee_divider	10000	Fee values are divided by this value
params::min_fee	0	Minimum fee allowed (0%)
params::max_fee	100	Maximum fee allowed (1%)