STON.fi
Search
⌃K
Comment on page

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
TypeScript
(slice) get_pool_address(slice token0, slice token1) method_id;
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
TypeScript
(int, slice, cell, cell, cell, cell) get_router_data() method_id;
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).