Pool (v1)

STON.fi v1 Pool smart contract - AMM pool implementation with constant product formula

Off-chain get methods

get_pool_data

Returns the current state of the pool: Jetton token reserves, Jetton wallet addresses and fee parameters.

(int, int, slice, slice, int, int, int, slice, int, int) get_pool_data() method_id;

Arguments

None

Result

Returns current state of the Pool

Result structure

Key	Type	Index	Description
reserve0	coins	0	Amount of the first token (in basic token units)
reserve1	coins	1	Amount of the second token (in basic token units)
token0_wallet_address	address	2	Address of the first Jetton token
token1_wallet_address	address	3	Address of the second Jetton token
lp_fee	uint8	4	Liquidity pool fee value
protocol_fee	uint8	5	Protocol fee
ref_fee	uint8	6	Referrer fee
protocol_fee_address	address	7	Address for receiving protocol fees
collected_token0_protocol_fee	coins	8	Amount of collected protocol fees of the first token (in basic token units)
collected_token1_protocol_fee	coins	9	Amount of collected protocol fees of the second token (in basic token units)

Notes:

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

get_expected_outputs

Estimate expected result of the amount of jettonWallet tokens swapped to the other type of tokens of the pool.

(int, int, int) get_expected_outputs(int amount, slice token_wallet) method_id;

Arguments

Name	Type	Description
amount	coins	Amount of tokens to swap (in basic token units)
token_wallet	address	Token Jetton address (must be equal to one of the Jetton addresses of the pool)

Result

Returns expected result of a token swap

Result structure

Key	Type	Index	Description
jetton_to_receive	coins	0	Amount of tokens received (in basic token units)
protocol_fee_paid	coins	1	Amount tokens paid for protocol fees (in basic token units)
ref_fee_paid	coins	2	Amount tokens paid for referrer fees (in basic token units)

get_expected_tokens

Estimate an expected amount of lp tokens minted when providing liquidity.

(int) get_expected_tokens(int amount0, int amount1) method_id;

Arguments

Key	Type	Description
amount0	coins	Amount of tokens for the first Jetton (in basic token units)
amount1	coins	Amount of tokens for the second Jetton (in basic token units)

Result

Returns an estimated amount of liquidity tokens to be minted

get_expected_liquidity

Estimate expected liquidity freed upon burning liquidity tokens.

(int, int) get_expected_liquidity(int jetton_amount) method_id;

Arguments

Key	Type	Description
jetton_amount	coins	Amount of liquidity tokens (in basic token units)

Result

Returns expected freed liquidity

Return structure

Key	Type	Index	Description
amount0	coins	0	Amount of tokens for the first Jetton (in basic token units)
amount1	coins	1	Amount of tokens for the second Jetton (in basic token units)

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

Function 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

Return structure

Key	Type	Index	Description
total_supply	coins	0	Total token supply (in basic token units)
is_mintable	bool	1	If new tokens can be minted
admin_address	address	2	Admin 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 calculated lp wallet address of a user

On-chain queries

On-chain counterparts of getter methods.

Operations table

Name	Value	Description
getter_pool_data	0x43c034e6	Sends a message with the current state of the pool
getter_expected_outputs	0xed4d8b67	Sends a message with an estimated result of the token swap
getter_lp_account_address	0x9163a98a	Sends a message with the lp account address of a user
getter_expected_tokens	0x9ce632c5	Sends a message with an estimated amount of lp tokens minted when providing liquidity
getter_expected_liquidity	0x8751801f	Sends a message with estimated liquidity freed upon burning of liquidity tokens
provide_wallet_address	0x2c76b973	Sends a message with the lp wallet address of a user

getter_pool_data (0x43c034e6)

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

TL-B

getter_pool_data#43c034e6 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
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
ref_fee_data	cell	Cell with fee data

ref_fee_data body

Name	Type	Description
lp_fee	uint8	Liquidity pool fee value
protocol_fee	uint8	Protocol fee
ref_fee	uint8	Referrer fee
protocol_fee_address	address	Address for receiving protocol fees
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_expected_outputs (0xed4d8b67)

Sends a message with an estimated result of the token swap. On-chain equivalent of get_expected_outputs.

TL-B

getter_expected_outputs#ed4d8b67 query_id:uint64 amount:Grams token_wallet:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
amount	coins	Amount of tokens (in basic token units)
token_wallet	address	Token Jetton address

Outgoing messages

Sends a message with an estimated result of the token swap to sender_address

Response message body

Name	Type	Description
op	uint32	Operation code is equal to getter_expected_outputs
query_id	uint64	Query id
out	coins	Amount of tokens to be received (in basic token units)
protocol_fee_out	coins	Amount tokens paid for protocol fees (in basic token units)
ref_fee_out	coins	Amount tokens paid for referrer fees (in basic token units)

getter_lp_account_address (0x9163a98a)

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#9163a98a 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

Notes:

• the current version of the contract returns a message with getter_expected_outputs op code instead of getter_lp_account_address so the user must differentiate those messages with some other means

getter_expected_tokens (0x9ce632c5)

Sends a message with an estimated amount of lp tokens minted when providing liquidity. On-chain equivalent of get_expected_tokens

TL-B

getter_expected_tokens#9ce632c5 query_id:uint64 user_address:MsgAddress amount0:Grams amount1:Grams = InternalMsgBody;

Message body

Name	Type	Description
user_address	address	User address (unused)
amount0	coins	Amount of tokens for the first Jetton (in basic token units)
amount1	coins	Amount of tokens for the second Jetton (in basic token units)

Outgoing messages

Sends a message with an estimated amount of liquidity tokens to be minted to sender_address

Response message body

Name	Type	Description
op	uint32	Operation code is equal to getter_expected_tokens
query_id	uint64	Query id
liquidity	coins	Expected amount of liquidity tokens (in basic token units)

getter_expected_liquidity (0x8751801f)

Sends a message with estimated liquidity freed upon burning liquidity tokens. On-chain equivalent of get_expected_liquidity.

TL-B

getter_expected_liquidity#8751801f query_id:uint64 jetton_amount:Grams = InternalMsgBody;

Message body

Name	Type	Description
jetton_amount	coins	Amount of liquidity tokens to burn (in basic token units)

Outgoing messages

Sends a message with estimated liquidity to sender_address

Response message body

Name	Type	Description
op	uint32	Operation code is equal to getter_expected_tokens
query_id	uint64	Query id
amount0_out	coins	Amount of tokens for the first Jetton (in basic token units)
amount1_out	coins	Amount of tokens for the second Jetton (in basic token units)

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
ref_address	cell | null	Cell with data if include_address? evaluates to true

ref_address 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	0x7bdd97de	Sent by LP wallet after burning LP jettons to release liquidity

burn_notification (0x7bdd97de)

Sent by LP wallet after burning LP jettons to release liquidity.

TL-B

burn_notification#7bdd97de query_id:uint64 jetton_amount:Grams from_address:MsgAddress response_address:MsgAddress = 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

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	0x25938561	Swap tokens
provide_lp	0xfcf9e58f	Provide liquidity
reset_gas	0x42a0fb43	Reset gas
collect_fees	0x1fcb7d3d	Collect fees
set_fees	0x355423e5	Set new fee parameters

swap (0x25938561)

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

TL-B

ref_bodycell$_ from_real_user:MsgAddress ref_address:MsgAddress = RefBodyCell;
swap#25938561 query_id:uint64 from_user:MsgAddress token_wallet:MsgAddress amount:Grams min_out:Grams ref_bodycell:(Either RefBodyCell ^RefBodyCell) = InternalMsgBody;

Message body

Name	Type	Description
from_user_address	address	User address
token_wallet	address	Incoming Jetton wallet address
amount	coins	Amount of incoming tokens (in basic token units)
min_out	coins	Minimum amount of received tokens (in basic token units)
has_ref	uint1	If referral is present
ref_bodycell	cell	Cell with data

Notes:

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

ref_bodycell body

Name	Type	Description
from_real_user	address	Who initialized the swap
ref_address	address	Referral address; present only if has_ref is 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_to operation to ref_address

provide_lp (0xfcf9e58f)

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#fcf9e58f query_id:uint64 owner_addr:MsgAddress min_lp_out:Grams amount0:Grams amount1:Grams = InternalMsgBody;

Message body

Name	Type	Description
owner_addr	address	User address
min_lp_out	coins	Minimum amount of received liquidity tokens (in basic token units)
amount0	coins	Amount of the first Jetton token (in basic token units)
amount1	coins	Amount of the second Jetton token (in basic token units)

Outgoing messages

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

reset_gas (0x42a0fb43)

Updates the amount of $TON (in nanoTons) on the pool to REQUIRED_TON_RESERVE (10000000) of the pool. The remaining amount of $TON will be sent back to the router.

TL-B

reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends an empty message back to the router with the remaining $TON

collect_fees (0x1fcb7d3d)

Collect protocol fees which will be sent to protocol_fee_address. A user which initiates this operation receives a bounty equal to 1/1000 of collected amount of both tokens.

TL-B

collect_fees#1fcb7d3d query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends a message with collected fees (minus the bounty) to protocol_fee_address

Sends a message with an amount of tokens to be received by a user as a bounty (equal to collected fees divided by 1000) to the router, which initiates pay_to operation

set_fees (0x355423e5)

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

TL-B

set_fees#355423e5 query_id:uint64 new_lp_fee:uint8 new_protocol_fee:uint8 new_ref_fee:uint8 new_protocol_fee_address:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
new_lp_fee	uint8	New liquidity pool fee ratio (multiplied by FEE_DIVIDER)
new_protocol_fee	uint8	New protocol fee ratio (multiplied by FEE_DIVIDER)
new_ref_fee	uint8	New referrer fee ratio (multiplied by FEE_DIVIDER)
new_protocol_fee_address	address	Address for receiving protocol fees

Notes:

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

• fees must be between MIN_FEE (0) and MAX_FEE (100)

Outgoing messages

None

---

LP Account internal message handlers

Handles messages from an lp account.

Operations table

Name	Value	Description
cb_add_liquidity	0x56dfeb8a	Sent by user's lp_account after adding liquidity
cb_refund_me	0x89446a42	Sent by user's lp_account after adding liquidity

cb_add_liquidity (0x56dfeb8a)

Add new liquidity to the pool. Sent by user's lp account after an appropriate amount (greater than 1000) of both Jetton 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#56dfeb8a query_id:uint64 tot_am0:Grams tot_am1:Grams user_address:MsgAddress min_lp_out:Grams = InternalMsgBody;

Message body

Name	Type	Description
tot_am0	coins	Amount of the first Jetton token (in basic token units)
tot_am1	coins	Amount of the second Jetton token (in basic token units)
user_address	address	User address
min_lp_out	coins	Minimum amount of received liquidity tokens (in basic token units)

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 user_address with minted liquidity tokens; on initial liquidity addition tokens are minted to addr_none

cb_refund_me (0x89446a42)

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#89446a42 query_id:uint64 tot_am0:Grams tot_am1:Grams user_address:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
tot_am0	coins	Amount of the first Jetton token (in basic token units)
tot_am1	coins	Amount of the second Jetton token (in basic token units)
user_address	address	User address

Outgoing messages

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

---

User message handlers

Handles direct messages from a user.

Operations table

Name	Value	Description
collect_fees	0x1fcb7d3d	Called by anyone; collect fees; the caller receives a bounty

collect_fees (0x1fcb7d3d)

Collect protocol fees which will be sent to protocol_fee_address. A user which initiates this operation receives a bounty equal to 1/1000 of collected amount of both tokens.

TL-B

collect_fees#1fcb7d3d query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends a message with collected fees (minus the bounty) to protocol_fee_address

Sends a message with an amount of tokens to be received by a user as a bounty (equal to collected fees divided by 1000) to the router, which initiates pay_to operation

---

Constants

Name	Value	Description
WORKCHAIN	0	Workchain id
REQUIRED_TON_RESERVE	10000000	Amount of $TON (in nanoTons) to be left on the pool contract as gas
REQUIRED_MIN_LIQUIDITY	1000	Minimum amount of liquidity required
REQUIRED_MIN_COLLECT_FEES	1000000	Minimum amount of tokens (in basic token units) collected as fees
MAX_COINS	2^120 - 1	Maximum amount of tokens (in basic token units) stored as liquidity
PROVIDE_ADD_GAS_CONSUMPTION	10000000	Additional gas (in nanoTons) for providing a wallet
FEE_DIVIDER	10000	Fee values are divided by this value
MIN_FEE	0	Minimum fee allowed
MAX_FEE	100	Maximum fee allowed

---