Pool

This section contains api reference of the pool contract

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

Referral 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 referral 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

Referral 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 referral 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 referral 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. The amount of fees in both tokens will be sent to protocol_fee_address address.

TL-B

collect_fees#1fcb7d3d query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

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

set_fees (0x355423e5)

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

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 referral 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

PreviousRouterNextLpAccount

Last updated