Router

This section contains op codes of the router contract as well as corresponding SDK methods

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.

FunC

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

TypeScript

async getPoolAddress(params: {
    token0: AddressType
    token1: AddressType
}): Promise<Address | null>

Arguments

Key	Type	Index	Description
token0	AddressType	0	The address of the router's wallet of first Jetton
token1	AddressType	1	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.

Additional functions

TypeScript

async getPool(params: {
    jettonAddresses: [AddressType, AddressType];
}): Promise<Pool | null>

Arguments

Key	Type	Description
jettonAddresses	[AddressType, AddressType]	Tuple of Jetton addresses of a pool

Result

Returns a Pool object for a pool with specified Jetton token addresses.

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.

FunC

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

TypeScript

async getData(): Promise<RouterData>

Arguments

None

Result

Returns RouterData structure containing current state of the router.

RouterData structure

Key	Type	Index	Description
isLocked	boolean	0	true if transfer_notification operations are locked (swap, provide_lp)
adminAddress	Address	1	Address of contract's admin account
tempUpgrade	Cell	2	A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
poolCode	Cell	3	Code of the router's liquidity pool contract
jettonLpWalletCode	Cell	4	Code of lp wallet contract
lpAccountCode	Cell	5	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:(Either MsgAddress 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	Referral address; present only if has_ref is 1

Outgoing messages

Sends a message with op swap to a liquidity pool

Build transaction

Build swap transaction.

TypeScript

async buildSwapJettonTxParams(params: {
    userWalletAddress: AddressType;
    offerJettonAddress: AddressType;
    askJettonAddress: AddressType;
    offerAmount: AmountType;
    minAskAmount: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
    referralAddress?: AddressType;
  }): Promise<MessageData>

async buildSwapProxyTonTxParams(params: {
    userWalletAddress: AddressType;
    proxyTonAddress: AddressType;
    askJettonAddress: AddressType;
    offerAmount: AmountType;
    minAskAmount: AmountType;
    forwardGasAmount?: AmountType;
    referralAddress?: AddressType;
    queryId?: QueryIdType;
  }): Promise<MessageData>

params structure

Key	Type	Description
userWalletAddress	AddressType	User's address
offerJettonAddress | proxyTonAddress	AddressType	Jetton address of a token to be swapped or proxy ton contract address
askJettonAddress	AddressType	Jetton address of a token to be received
offerAmount	AmountType	Amount of tokens to be swapped (in basic token units)
minAskAmount	AmountType	Minimum amount of tokens to be received (in basic token units)
forwardGasAmount	AmountType | undefined	Optional; forward amount of gas for the next transaction (in nanoTons)
referralAddress	AddressType | undefined	Optional; referral address
queryId	QueryIdType | undefined	Optional; query id

MessageData structure

Name	Type	Description
to	Address	Address of the router's Jetton wallet for the swapped token
payload	Cell	Payload created by createSwapBody
gasAmount	BN	Recommended amount of $TON (in nanoTons) sent as gas

Notes:

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

• if forwardGasAmount is not specified the default value is 0.265 $TON

• the default value for gasAmount is equal to 0.3 $TON

Create payload

Create a payload to initiate a swap transaction.

TypeScript

async createSwapBody(params: {
    userWalletAddress: AddressType;
    minAskAmount: AmountType;
    askJettonWalletAddress: AddressType;
    referralAddress?: AddressType;
}): Promise<Cell>

params structure

Key	Type	Description
userWalletAddress	AddressType	User's address
minAskAmount	AmountType	Minimum amount of tokens received (in basic token units)
askJettonWalletAddress	AddressType	Jetton router's wallet address of tokens to be received
referralAddress	AddressType	Optional; referral address

Notes:

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

• if forwardGasAmount is not specified the default value is 0.265 $TON

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

Build transaction

Build provide_lp transactions for the first and the second Jetton token of the pair or TON-Jetton pair.

TypeScript

async buildProvideLiquidityJettonTxParams(params: {
    userWalletAddress: AddressType;
    sendTokenAddress: AddressType;
    otherTokenAddress: AddressType;
    sendAmount: AmountType;
    minLpOut: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
  }): Promise<MessageData>

public async buildProvideLiquidityProxyTonTxParams(params: {
    userWalletAddress: AddressType;
    proxyTonAddress: AddressType;
    otherTokenAddress: AddressType;
    sendAmount: AmountType;
    minLpOut: AmountType;
    forwardGasAmount?: AmountType;
    queryId?: QueryIdType;
  }): Promise<MessageData>

params structure

Key	Type	Description
userWalletAddress	AddressType	User's address
sendTokenAddress | proxyTonAddress	AddressType	Address of the first Jetton token or a proxy ton contract
otherTokenAddress	AddressType	Address of the second Jetton token
sendAmount	AmountType	Amount of the first/second tokens deposited as liquidity (in basic token units)
minLpOut	AmountType	Minimum amount of created liquidity tokens (in basic token units)
forwardGasAmount	AmountType | undefined	Optional; forward amount of gas for the next transaction (in nanoTons)
queryId	QueryIdType | undefined	Optional; query id

MessageData structure

Name	Type	Description
to	Address	Address of the router's Jetton wallet
payload	Cell	Payload created by createProvideLiquidityBody
gasAmount	BN	Recommended amount of $TON (in nanoTons) sent as gas

Notes:

• the provide liquidity operation will fail if a user should receive less than minLpOut of lp tokens as a result

• if forwardGasAmount is not specified the default value is 0.265 $TON

• the default value for gasAmount is equal to 0.3 $TON

Create payload

Create a payload to initiate a provide_lp transaction.

TypeScript

async createProvideLiquidityBody(params: {
    routerWalletAddress: AddressType;
    minLpOut: AmountType;
}): Promise<Cell>

params structure

Key	Type	Description
routerWalletAddress	AddressType	Address of the router's Jetton token wallet
minLpOut	AmountType	Minimum amount of created liquidity tokens (in basic token units)

Notes:

• the provide liquidity operation will fail if a user should receive less than minLpOut of lp tokens as a result

• if forwardGasAmount is not specified the default value is 0.265 $TON

---

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	New admin address

Outgoing messages

None

cancel_admin_upgrade (0xa4ed9981)

Cancels an admin change if there's a pending admin change.

TL-B

cancel_admin_upgrade#a4ed9981 query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

None

cancel_code_upgrade (0x357ccc67)

Cancels a code upgrade if there's a pending code change.

TL-B

cancel_code_upgrade#357ccc67 query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

None

finalize_upgrades (0x6378509f)

Finalizes upgrades of the router code and admin change. In order for the changes to take effect an appropriate amount of time must pass since initializing and upgrade. For code upgrade the delay is seven days, for an admin change the delay is two days.

TL-B

finalize_upgrades#6378509f query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

None

reset_gas (0x42a0fb43)

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

TL-B

reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

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

reset_pool_gas (0xf6aa9737)

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