1 of 5

API reference v1

This section describes different op codes of AMM smart contracts

Overview

The section contains separate documents for each smart contract used in AMM:

Pool
Router
LpAccount
LpWallet

Source code of all smart contracts can be found in this Github repo

Definitions of terminology used can be found in Glossary

Router

This section contains api reference of the router contract

Off-chain get methods

`get_pool_address`

Returns an address of a pool for a specified pair of assets.

It's necessary to specify addresses of Jetton wallets of the router as the arguments of this method. These addresses can be retrieved with get_wallet_address of the Jetton minter.

(slice) get_pool_address(slice token0, slice token1) method_id;

Arguments

Key

Type

Index

Description

token0

address

The address of the router's wallet of first Jetton

token1

address

The address of the router's wallet of second Jetton

Result

Returns single slice with the address of liquidity pool for specified pair of Jettons.

`get_router_data`

Returns the current state of the router: is the router locked, admin address, pending code or admin upgrades, pool contract code, lp wallet code, lp account code.

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

Arguments

None

Result

Returns current state of the Router

Result structure

Key

Type

Index

Description

is_locked

bool

if operations are locked (swap, provide_lp)

admin_address

address

Address of contract's admin account

temp_upgrade

cell

A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending

pool_code

cell

Code of the router's liquidity pool contract

jetton_lp_wallet_code

cell

Code of lp wallet contract

lp_account_code

cell

Code of lp account contract

transfer_notification operations

`transfer_notification` (0x7362d09c)

Messages received from Jetton wallets belonging to the router upon getting a token transfer from a user. The user must include a custom payload with additional op code (either swap or provide_lp) and appropriate data in order for those messages to be processed correctly.

TL-B

transfer_notification#7362d09c query_id:uint64 jetton_amount:Grams from_user:MsgAddress ref_msg_data:^DexPayload = InternalMsgBody;

Message body

Name

Type

Description

op

uint32

Operation code; equal to transfer_notification

query_id

uint64

Query id

jetton_amount

coins

Jetton amount (in basic token units)

from_user

address

User address

ref_msg_data

cell

Cell with data

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code

token_wallet1

address

The address of the router's wallet of second Jetton

Notes:

ref_msg_data contains other fields depending on which op code is called

Transfer operations table

Name

Value

Description

swap

0x25938561

Swap one type of Jetton tokens for another

provide_lp

0xfcf9e58f

Provide liquidity; route call to the correct pool

`swap` (0x25938561)

Swap tokens. This message is received when the Router's Jetton token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The router then sends a swap message to the appropriate pool contract address.

TL-B

swap_op#25938561 = SwapOP;
swap$_ transferred_op:SwapOP token_wallet1:MsgAddress min_out:Grams to_address:MsgAddress ref_address:(Maybe MsgAddress) = DexPayload;

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code; equal to swap

token_wallet1

address

The address of the router's wallet of second Jetton

min_out

coins

Minimum amount out (in basic token units)

to_address

address

User address

has_ref

uint1

If referral is present

ref_address

address

Referrer address; present only if has_ref is 1

Outgoing messages

Sends a message with op swap to a liquidity pool

`provide_lp` (0xfcf9e58f)

Provide liquidity for a pool. This message is received when Router's token wallet sends a message upon confirmation of token transfer from a user with a custom payload. The router then sends a provide_lp message to the appropriate pool contract address.

TL-B

provide_lp_op#fcf9e58f = ProvideLpOP;
provide_lp$_ transferred_op:ProvideLpOP token_wallet1:MsgAddress min_lp_out:Grams = DexPayload;

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code; equal to provide_lp

token_wallet1

address

The address of the router's wallet of second Jetton

min_lp_out

coins

Minimum amount of created liquidity tokens (in basic token units)

Outgoing messages

Sends a message with op provide_lp to a liquidity pool

On-chain queries

On-chain counterparts of getter methods

Operations table

Name

Value

Description

getter_pool_address

0xd1db969b

Sends a message with a pool address for a requested token pair; counterpart to get_pool_address

`getter_pool_address` (0xd1db969b)

Sends a message with an address of a pool for a specified pair of assets; counterpart to get_pool_address

TL-B

getter_pool_address#d1db969b query_id:uint64 token0:MsgAddress token1:MsgAddress = InternalMsgBody;

Message Body

Name

Type

Description

token0

address

The address of the router's wallet of first Jetton

token1

address

The address of the router's wallet of second Jetton

Outgoing messages

Sends a message back to the sender with the pool address

Response message body

Name

Type

Description

op

uint32

Operation code equal to getter_pool_address

query_id

uint64

Query id

pool_address

address

Address of a pool

On-chain admin operations

Handles governance message from admin to change pool parameters.

The admin can lock/unlock trading on all pools, change fees on a certain pool, upgrade the router code, etc.

Operations table

Name

Value

Description

set_fees

0x355423e5

Change fee parameters of a pool

collect_fees

0x1fcb7d3d

Collect protocol fees from a pool

lock

0x878f9b0e

Lock the router (locks all swaps and liquidity providing)

unlock

0x6ae4b0ef

Unlock the router

init_code_upgrade

0xdf1e233d

Initiate code upgrade for the router

init_admin_upgrade

0x2fb94384

Initiate admin change for the router

cancel_admin_upgrade

0xa4ed9981

Cancel an admin change

cancel_code_upgrade

0x357ccc67

Cancel a code upgrade

finalize_upgrades

0x6378509f

Finalize upgrades of the router code and admin change

reset_gas

0x42a0fb43

Update the amount of $TON (in nanoTons) on the router to REQUIRED_TON_RESERVE of the router

reset_pool_gas

0xf6aa9737

Update the amount of $TON (in nanoTons) on a pool to REQUIRED_TON_RESERVE of a pool

Notes:

REQUIRED_TON_RESERVE for the router is 100000

`set_fees` (0x355423e5)

Change fees of a pool including liquidity pool fees, protocol fees and referral fees. It's necessary to provide correct Jetton token addresses for a target liquidity pool.

TL-B

ref_wallets$_ jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = RefWallets;
set_fees#355423e5 query_id:uint64 new_lp_fee:uint8 new_protocol_fee:uint8 new_ref_fee:uint8 new_protocol_fee_address:MsgAddress ref_wallets:^RefWallets = InternalMsgBody;

Arguments

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

ref_wallets

cell

Cell with wallet addresses

`ref_wallets` body

Name

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

The address of the router's wallet of second Jetton

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

Sends a message with op set_fees to a liquidity pool.

`collect_fees` (0x1fcb7d3d)

Collect protocol fees from a pool. The appropriate Jetton wallet addresses must be provided.

TL-B

collect_fees#1fcb7d3d query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;

Arguments

Name

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

The address of the router's wallet of second Jetton

Outgoing messages

Sends a message to a liquidity pool with collect_fees op code.

`lock` (0x878f9b0e)

Stops all transfer_notification messages from going through. Effectively blocks swap and provide_lp transactions through this router.

TL-B

lock#878f9b0e query_id:uint64 = InternalMsgBody;

Arguments

None.

Outgoing messages

None.

`unlock` (0x6ae4b0ef)

Allows all transfer_notification messages to go through. Enables swap and provide_lp transactions through this router.

TL-B

unlock#6ae4b0ef query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

None.

`init_code_upgrade` (0xdf1e233d)

Initiates code upgrade for the router. An appropriate data with the new router code must be provided. The changes won't take effect until finalize_upgrades is received by the router. The minimum delay between initiating code upgrade and finalizing the changes in seven days.

TL-B

init_code_upgrade#df1e233d query_id:uint64 code:^Cell = InternalMsgBody;

Arguments

Name

Type

Description

code

cell

Code of the new router contract

Outgoing messages

None

`init_admin_upgrade` (0x2fb94384)

Initiates admin change for the router. An appropriate address for a new router admin must be provided. The changes won't take effect until finalize_upgrades is received by the router. The minimum delay between initiating admin change and finalizing the changes in two days.

TL-B

init_admin_upgrade#2fb94384 query_id:uint64 admin:MsgAddress = InternalMsgBody;

Arguments

Name

Type

Description

admin

address

Updates the amount of $TON (in nanoTons) on a pool to REQUIRED_TON_RESERVE of a pool. Forwards this message to a pool contract for provided pair of Jetton tokens.

TL-B

reset_pool_gas#2fb94384 query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;

Arguments

Name

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

The address of the router's wallet of second Jetton

Outgoing messages

Sends a message to a liquidity pool with reset_gas op code carrying remaining gas

Internal message handlers

`pay_to` (0xf93bb43f)

Initiates a Jetton token transfer from wallets belonging to this router, called from pools (on swap, liquidity providing, refund, etc).

TL-B

ref_coins_data$_ amount0_out:Grams token0_address:MsgAddress amount1_out:Grams token1_address:MsgAddress = RefCoinsData;
pay_to#f93bb43f query_id:uint64 owner:MsgAddress exit_code:uint32 ref_coins_data:^RefCoinsData = InternalMsgBody;

Message body

Name

Type

Description

op

uint32

Operation code; equal to pay_to

query_id

uint64

Query id

owner

address

Address of a receiver

exit_code

uint32

Exit code

ref_coins_data

cell

Cell with Jetton wallet addresses and token amounts

`ref_coins_data` body

Name

Type

Description

amount0_out

coins

Amount of the first Jetton token (in basic token units)

token0_address

address

The address of the router's wallet of the first Jetton

amount1_out

coins

Amount of the second Jetton token (in basic token units)

token1_address

address

The address of the router's wallet of the second Jetton

Outgoing messages

Sends transfer of amount0_out tokens to owner message to token0_address wallet if amount0_out > 0

Sends transfer of amount1_out tokens to owner message to token1_address wallet if amount1_out > 0

Constants

Name

Value

Description

WORKCHAIN

Workchain id

REQUIRED_TON_RESERVE

100000

Amount of $TON (in nanoTons) to be left on the router contract as gas

TWODAYS

172800

Two days is seconds

SEVENDAYS

604800

Seven days in seconds

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

Amount of the first token (in basic token units)

reserve1

coins

Amount of the second token (in basic token units)

token0_wallet_address

address

Address of the first Jetton token

token1_wallet_address

address

Address of the second Jetton token

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)

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

Amount of tokens received (in basic token units)

protocol_fee_paid

coins

Amount tokens paid for protocol fees (in basic token units)

ref_fee_paid

coins

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

Amount of tokens for the first Jetton (in basic token units)

amount1

coins

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

Total token supply (in basic token units)

is_mintable

bool

If new tokens can be minted

admin_address

address

Admin address

jetton_content_uri

string

Offchain uri with Jetton data

jetton_wallet_code

cell

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;

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

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

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

Minimum fee allowed

MAX_FEE

100

Maximum fee allowed

LpAccount

This section contains api reference of the lp account contract

Off-chain get methods

`get_lp_account_data`

Returns current state of the lp account: owner address, pool address and amount of both Jetton tokens.

(slice, slice, int, int) get_lp_account_data() method_id;

Arguments

None

Result

Returns the current state of the lp account.

Return structure

Key

Type

Index

Description

user_address

address

Owner's address

pool_address

address

Pool's address

amount0

coins

Balance of th e first Jetton token (in basic token units)

amount1

coins

Balance of the second Jetton token (in basic token units)

On-chain queries

On-chain counterparts of getter methods.

Operations table

Name

Value

Description

getter_lp_account_data

0x1d439ae0

Sends a message with the current state of the pool

`getter_lp_account_data` (0x1d439ae0)

Sends a message with current state of the lp account. On-chain equivalent of get_lp_account_data.

TL-B

getter_lp_account_data#1d439ae0 query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends a message with current state of the lp account to sender_address

Response message body

Name

Type

Description

op

uint32

Operation code equal to getter_lp_account_data

query_id

uint64

Query id

user_address

address

Owner's address

pool_address

address

Pool's address

amount0

coins

Balance of the first Jetton token (in basic token units)

amount1

coins

Balance of the second Jetton token (in basic token units)

Pool message handlers

Handles incoming messages from a pool

Operations table

Name

Value

Description

add_liquidity

0x3ebe5431

Add liquidity

`add_liquidity` (0x3ebe5431)

Stores the sent amount of tokens by the user to be added as new liquidity. Upon receiving an appropriate amount of both tokens sends a message with those amounts to a pool to be added as new liquidity. The automatic liquidity addition happens only if the amount of both tokens if greater than 1000 and non-zero min_lp_out was specified, otherwise the user can keep increasing the amount of stored tokens.

TL-B

add_liquidity#3ebe5431 query_id:uint64 new_amount0:Grams new_amount1:Grams min_lp_out:Grams = InternalMsgBody;

Message body

Name

Type

Description

new_amount0

coins

Amount of the first Jetton tokens added (in basic token units)

new_amount1

coins

Amount of the second Jetton tokens added (in basic token units)

min_lp_out

coins

Minimum required amount of received new 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

Outgoing messages

Sends a message to the pool with cb_add_liquidity op

Response message body

Name

Type

Description

op

uint32

Operation code, equal to cb_add_liquidity

query_id

uint64

Query id

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)

Notes:

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

User message handlers

Handles incoming messages from a user

Operations table

Name

Value

Description

refund_me

0xbf3f447

Return previously sent tokens back to the user

direct_add_liquidity

0x4cf82803

Directly add liquidity with specified amount of tokens and a minimum amount of received liquidity tokens

reset_gas

0x42a0fb43

Reset gas

`refund_me` (0xbf3f447)

Initiates a refund of stored tokens by add_liquidity if the user decides to cancel the addition of new liquidity. The amount of stored tokens will be sent to the pool which will initiate a transfer back to the user.

TL-B

refund_me#bf3f447 query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

Sends a message with cb_refund_me op code and amount of stored tokens to a pool. The pool will send a message to refund those tokens back to the user.

Response message body

Name

Type

Description

op

uint32

Operation code

query_id

uint64

Query id

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

`direct_add_liquidity` (0x4cf82803)

Initiates an addition of new liquidity to a pool with a specified amount of both tokens and a minimum amount of received liquidity. The operation is successful only if there's an equal or greater amount of both tokens stored in the account (the amount of both tokens must be greater than 1000). This method is useful if an automatic liquidity addition has not been triggered upon deposition of tokens.

TL-B

direct_add_liquidity#4cf82803 query_id:uint64 amount0:Grams amount1:Grams min_lp_out:Grams = 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)

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
min_lp_out value must be greater than zero for this operation to proceed

Outgoing messages

Sends a message with cb_add_liquidity op code and amount of both tokens to be added as new liquidity.

Response message body

Name

Type

Description

op

uint32

Operation code

query_id

uint64

Query id

am0

coins

Amount of the first Jetton tokens (in basic token units)

am1

coins

Amount of the second Jetton tokens (in basic token units)

user_address

address

Owner's 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

`reset_gas` (0x42a0fb43)

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

TL-B

reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody;

Message body

None

Outgoing messages

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

Constants

Name

Value

Description

WORKCHAIN

Workchain id

REQUIRED_TON_RESERVE

10000000

Amount of $TON (in nanoTons) to be left on the lp account contract as gas

LpWallet

This section contains api reference of the lp wallet contract

This is a standard Jetton token wallet for holding liquidity tokens. Only specific modifications for this implementation will be described.

User message handlers

`burn` (0x595f07bc)

Burn an amount of liquidity tokens.

TL-B

burn#595f07bc query_id:uint64 amount:Grams response_destination:MsgAddress custom_payload:Maybe ^Cell = InternalMsgBody;

Message body

Name

Type

Description

op

uint32

Operation code is equal to burn

query_id

uint64

Query id

amount

coins

Amount of coins to burn (in basic token units)

response_destination

address

Address of a user

Outgoing messages

Sends a message with burn_notification op code to the router contract with the amount of token burnt.

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

Amount of the first token (in basic token units)

reserve1

coins

Amount of the second token (in basic token units)

token0_wallet_address

address

Address of the first Jetton token

token1_wallet_address

address

Address of the second Jetton token

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)

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

Amount of tokens received (in basic token units)

protocol_fee_paid

coins

Amount tokens paid for protocol fees (in basic token units)

ref_fee_paid

coins

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

Amount of tokens for the first Jetton (in basic token units)

amount1

coins

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

Total token supply (in basic token units)

is_mintable

bool

If new tokens can be minted

admin_address

address

Admin address

jetton_content_uri

string

Offchain uri with Jetton data

jetton_wallet_code

cell

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;

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)

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

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)

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

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

Minimum fee allowed

MAX_FEE

100

Maximum fee allowed

Router

This section contains api reference of the router contract

Off-chain get methods

`get_pool_address`

Returns an address of a pool for a specified pair of assets.

It's necessary to specify addresses of Jetton wallets of the router as the arguments of this method. These addresses can be retrieved with get_wallet_address of the Jetton minter.

(slice) get_pool_address(slice token0, slice token1) method_id;

Arguments

Key

Type

Index

Description

token0

address

The address of the router's wallet of first Jetton

token1

address

The address of the router's wallet of second Jetton

Result

Returns single slice with the address of liquidity pool for specified pair of Jettons.

`get_router_data`

Returns the current state of the router: is the router locked, admin address, pending code or admin upgrades, pool contract code, lp wallet code, lp account code.

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

Arguments

None

Result

Returns current state of the Router

Result structure

Key

Type

Index

Description

is_locked

bool

if operations are locked (swap, provide_lp)

admin_address

address

Address of contract's admin account

temp_upgrade

cell

A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending

pool_code

cell

Code of the router's liquidity pool contract

jetton_lp_wallet_code

cell

Code of lp wallet contract

lp_account_code

cell

Code of lp account contract

transfer_notification operations

`transfer_notification` (0x7362d09c)

TL-B

transfer_notification#7362d09c query_id:uint64 jetton_amount:Grams from_user:MsgAddress ref_msg_data:^DexPayload = InternalMsgBody;

Message body

Name

Type

Description

op

uint32

Operation code; equal to transfer_notification

query_id

uint64

Query id

jetton_amount

coins

Jetton amount (in basic token units)

from_user

address

User address

ref_msg_data

cell

Cell with data

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code

token_wallet1

address

The address of the router's wallet of second Jetton

Notes:

ref_msg_data contains other fields depending on which op code is called

Transfer operations table

Name

Value

Description

swap

0x25938561

Swap one type of Jetton tokens for another

provide_lp

0xfcf9e58f

Provide liquidity; route call to the correct pool

`swap` (0x25938561)

TL-B

swap_op#25938561 = SwapOP;
swap$_ transferred_op:SwapOP token_wallet1:MsgAddress min_out:Grams to_address:MsgAddress ref_address:(Maybe MsgAddress) = DexPayload;

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code; equal to swap

token_wallet1

address

The address of the router's wallet of second Jetton

min_out

coins

Minimum amount out (in basic token units)

to_address

address

User address

has_ref

uint1

If referral is present

ref_address

address

Referrer address; present only if has_ref is 1

Outgoing messages

Sends a message with op swap to a liquidity pool

`provide_lp` (0xfcf9e58f)

TL-B

provide_lp_op#fcf9e58f = ProvideLpOP;
provide_lp$_ transferred_op:ProvideLpOP token_wallet1:MsgAddress min_lp_out:Grams = DexPayload;

`ref_msg_data` body

Name

Type

Description

transferred_op

uint32

Additional operation code; equal to provide_lp

token_wallet1

address

The address of the router's wallet of second Jetton

min_lp_out

coins

Minimum amount of created liquidity tokens (in basic token units)

Outgoing messages

Sends a message with op provide_lp to a liquidity pool

On-chain queries

On-chain counterparts of getter methods

Operations table

Name

Value

Description

getter_pool_address

0xd1db969b

Sends a message with a pool address for a requested token pair; counterpart to get_pool_address

`getter_pool_address` (0xd1db969b)

Sends a message with an address of a pool for a specified pair of assets; counterpart to get_pool_address

TL-B

getter_pool_address#d1db969b query_id:uint64 token0:MsgAddress token1:MsgAddress = InternalMsgBody;

Message Body

Name

Type

Description

token0

address

The address of the router's wallet of first Jetton

token1

address

The address of the router's wallet of second Jetton

Outgoing messages

Sends a message back to the sender with the pool address

Response message body

Name

Type

Description

op

uint32

Operation code equal to getter_pool_address

query_id

uint64

Query id

pool_address

address

Address of a pool

On-chain admin operations

Handles governance message from admin to change pool parameters.

The admin can lock/unlock trading on all pools, change fees on a certain pool, upgrade the router code, etc.

Operations table

Name

Value

Description

set_fees

0x355423e5

Change fee parameters of a pool

collect_fees

0x1fcb7d3d

Collect protocol fees from a pool

lock

0x878f9b0e

Lock the router (locks all swaps and liquidity providing)

unlock

0x6ae4b0ef

Unlock the router

init_code_upgrade

0xdf1e233d

Initiate code upgrade for the router

init_admin_upgrade

0x2fb94384

Initiate admin change for the router

cancel_admin_upgrade

0xa4ed9981

Cancel an admin change

cancel_code_upgrade

0x357ccc67

Cancel a code upgrade

finalize_upgrades

0x6378509f

Finalize upgrades of the router code and admin change

reset_gas

0x42a0fb43

Update the amount of $TON (in nanoTons) on the router to REQUIRED_TON_RESERVE of the router

reset_pool_gas

0xf6aa9737

Update the amount of $TON (in nanoTons) on a pool to REQUIRED_TON_RESERVE of a pool

Notes:

REQUIRED_TON_RESERVE for the router is 100000

`set_fees` (0x355423e5)

Change fees of a pool including liquidity pool fees, protocol fees and referral fees. It's necessary to provide correct Jetton token addresses for a target liquidity pool.

TL-B

ref_wallets$_ jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = RefWallets;
set_fees#355423e5 query_id:uint64 new_lp_fee:uint8 new_protocol_fee:uint8 new_ref_fee:uint8 new_protocol_fee_address:MsgAddress ref_wallets:^RefWallets = InternalMsgBody;

Arguments

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

ref_wallets

cell

Cell with wallet addresses

`ref_wallets` body

Name

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

The address of the router's wallet of second Jetton

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

Sends a message with op set_fees to a liquidity pool.

`collect_fees` (0x1fcb7d3d)

Collect protocol fees from a pool. The appropriate Jetton wallet addresses must be provided.

TL-B

collect_fees#1fcb7d3d query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;

Arguments

Name

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

None.

`init_code_upgrade` (0xdf1e233d)

TL-B

init_code_upgrade#df1e233d query_id:uint64 code:^Cell = InternalMsgBody;

Arguments

Name

Type

Description

code

cell

Code of the new router contract

Outgoing messages

None

`init_admin_upgrade` (0x2fb94384)

TL-B

init_admin_upgrade#2fb94384 query_id:uint64 admin:MsgAddress = InternalMsgBody;

Arguments

Name

Type

Description

admin

address

TL-B

finalize_upgrades#6378509f query_id:uint64 = InternalMsgBody;

Type

Description

jetton_wallet0

address

The address of the router's wallet of first Jetton

jetton_wallet1

address

The address of the router's wallet of second Jetton

Outgoing messages

Sends a message to a liquidity pool with reset_gas op code carrying remaining gas

Internal message handlers

`pay_to` (0xf93bb43f)

Initiates a Jetton token transfer from wallets belonging to this router, called from pools (on swap, liquidity providing, refund, etc).

TL-B

ref_coins_data$_ amount0_out:Grams token0_address:MsgAddress amount1_out:Grams token1_address:MsgAddress = RefCoinsData;
pay_to#f93bb43f query_id:uint64 owner:MsgAddress exit_code:uint32 ref_coins_data:^RefCoinsData = InternalMsgBody;

Message body

Name

Type

Description

op

uint32

Operation code; equal to pay_to

query_id

uint64

Query id

owner

address

Address of a receiver

exit_code

uint32

Exit code

ref_coins_data

cell

Cell with Jetton wallet addresses and token amounts

`ref_coins_data` body

Name

Type

Description

amount0_out

coins

Amount of the first Jetton token (in basic token units)

token0_address

address

The address of the router's wallet of the first Jetton

amount1_out

coins

Amount of the second Jetton token (in basic token units)

token1_address

address

The address of the router's wallet of the second Jetton

Outgoing messages

Sends transfer of amount0_out tokens to owner message to token0_address wallet if amount0_out > 0

Sends transfer of amount1_out tokens to owner message to token1_address wallet if amount1_out > 0

Constants

Name

Value

Description

WORKCHAIN

Workchain id

REQUIRED_TON_RESERVE

100000

Amount of $TON (in nanoTons) to be left on the router contract as gas

TWODAYS

172800

Two days is seconds

SEVENDAYS

604800

Seven days in seconds

API reference v1

Overview

Router

Off-chain get methods

get_pool_address

Arguments

Result

get_router_data

Arguments

Result

transfer_notification operations

transfer_notification (0x7362d09c)

TL-B

Message body

ref_msg_data body

Transfer operations table

swap (0x25938561)

TL-B

ref_msg_data body

Outgoing messages

provide_lp (0xfcf9e58f)

TL-B

ref_msg_data body

Outgoing messages

On-chain queries

Operations table

getter_pool_address (0xd1db969b)

TL-B

Message Body

Outgoing messages

Response message body

On-chain admin operations

Operations table

set_fees (0x355423e5)

TL-B

Arguments

ref_wallets body

Outgoing messages

collect_fees (0x1fcb7d3d)

TL-B

Arguments

Outgoing messages

lock (0x878f9b0e)

TL-B

Arguments

Outgoing messages

unlock (0x6ae4b0ef)

TL-B

Arguments

Outgoing messages

init_code_upgrade (0xdf1e233d)

TL-B

Arguments

Outgoing messages

init_admin_upgrade (0x2fb94384)

TL-B

Arguments

Outgoing messages

cancel_admin_upgrade (0xa4ed9981)

TL-B

Arguments

Outgoing messages

cancel_code_upgrade (0x357ccc67)

TL-B

Arguments

Outgoing messages

finalize_upgrades (0x6378509f)

TL-B

Arguments

Outgoing messages

reset_gas (0x42a0fb43)

TL-B

Arguments

Outgoing messages

reset_pool_gas (0xf6aa9737)

TL-B

Arguments

Outgoing messages

Internal message handlers

pay_to (0xf93bb43f)

`get_pool_address`

`get_router_data`

`transfer_notification` (0x7362d09c)

`ref_msg_data` body

`swap` (0x25938561)

`ref_msg_data` body

`provide_lp` (0xfcf9e58f)

`ref_msg_data` body

`getter_pool_address` (0xd1db969b)

`set_fees` (0x355423e5)

`ref_wallets` body

`collect_fees` (0x1fcb7d3d)

`lock` (0x878f9b0e)

`unlock` (0x6ae4b0ef)

`init_code_upgrade` (0xdf1e233d)

`init_admin_upgrade` (0x2fb94384)

`cancel_admin_upgrade` (0xa4ed9981)

`cancel_code_upgrade` (0x357ccc67)

`finalize_upgrades` (0x6378509f)

`reset_gas` (0x42a0fb43)

`reset_pool_gas` (0xf6aa9737)

`pay_to` (0xf93bb43f)

`ref_coins_data` body

`get_pool_data`

`get_expected_outputs`

`get_expected_tokens`

`get_expected_liquidity`

`get_lp_account_address`

`get_jetton_data`

`get_wallet_address`

`getter_pool_data` (0x43c034e6)

`ref_fee_data` body

`getter_expected_outputs` (0xed4d8b67)

`getter_lp_account_address` (0x9163a98a)

`getter_expected_tokens` (0x9ce632c5)

`getter_expected_liquidity` (0x8751801f)

`provide_wallet_address` (0x2c76b973)

`ref_address` body

`burn_notification` (0x7bdd97de)