Router (v2)

STON.fi v2 Router smart contract - advanced routing with vault integration for swaps

Off-chain get methods

get_vault_address

Returns an address of a vault for a specified asset and user.

(slice) get_vault_address(slice user, slice token_wallet) method_id;

Arguments

Key	Type	Index	Description
user	address	0	The address of the Vault's owner
token	address	1	The address of the Router's jetton wallet

Result

Returns VaultV2 object for Vault's' address.

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 token_wallet0, slice token_wallet1) method_id;

Arguments

Key	Type	Index	Description
token0	address	0	The address of the Router's wallet of first Jetton
token1	address	1	The address of the Router's wallet of second Jetton

Result

Returns Pool address.

get_router_data

Returns the current state of the Router

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

Arguments

None

Result

Returns RouterData structure containing current state of the Router.

RouterData structure

Key	Type	Index	Description
id	uint32	0	Router id
dex_type	string	1	Router type
is_locked	bool	2	true if transfer_notification operations are locked (swap, provide_lp)
admin_address	address	3	Address of contract's admin account
temp_upgrade	cell	4	A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending
pool_code	cell	5	Code of the Router's liquidity pool contract
jetton_lp_wallet_code	cell	6	Code of lp wallet contract
lp_account_code	cell	7	Code of lp account contract
vault_code	cell	8	Code of lp account contract

Notes:

• possible dex_type values:

  • constant_product

  • stableswap

  • weighted_stableswap

  • weighted_const_product

get_router_version

Returns the current Router version

(int, int, slice) get_router_version() method_id;

Arguments

None

Result

Returns VersionData structure containing Router version.

RouterData structure

Key	Type	Index	Description
major	uint	0	Major version
minor	uint	1	Minor version
development	string	2	Contains additional version info

---

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 forward_payload:^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
payload	cell	Cell with data

payload body

Name	Type	Description
transferred_op	uint32	Additional operation code
token_wallet1	address	The address of the Router's wallet of second Jetton

Notes:

• payload contains other fields depending on which op code is called

Transfer operations table

Name	Value	Description
swap	0x6664de2a	Swap one type of Jetton tokens for another
provide_lp	0x37c096df	Provide liquidity; route call to the correct pool

swap (0x6664de2a)

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.

Check examples for in-depth message flow.

TL-B

swap#6664de2a token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 cross_swap_body:^[min_out:Coins receiver:MsgAddress fwd_gas:Coins custom_payload:(Maybe ^Cell) refund_fwd_gas:Coins refund_payload:(Maybe ^Cell) ref_fee:uint16 ref_address:MsgAddress] = DexPayload;

payload body

Name	Type	Description
op	uint32	Swap op
other_token_wallet	address	Address of the other Router token wallet
refund_address	address	Address where refund will be sent if swap fails
excesses_address	address	Address where TON excesses will be sent
deadline	uint64	Timestamp of execution deadline for this tx
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
min_out	coins	Minimum required amount of tokens to receive
receiver_address	address	Address where tokens will be sent after swap
fwd_gas	coins	Gas used to forward a message in transfer_notification after swap if custom_payload is present
custom_payload	maybe_ref	Payload sent in transfer_notification after swap
refund_fwd_gas	coins	Gas used to forward a message in transfer_notification if swap fails if refund_payload is present
refund_payload	maybe_ref	Payload sent in transfer_notification if swap fails
ref_fee	uint16	Referrer fee
referral_address	address	Referrer address

Notes:

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

• max allowed value of ref_fee is 100 (1%)

Outgoing messages

Sends a message with op swap to Pool

provide_lp (0x37c096df)

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.

Check examples for in-depth message flow.

TL-B

provide_lp#37c096df token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 cross_provide_lp_body:^[min_lp_out:Coins to_address:MsgAddress both_positive:uint1 fwd_amount:Coins custom_payload:(Maybe ^Cell)] = DexPayload;

payload body

Name	Type	Description
op	uint32	Provide lp op
other_token_wallet	address	Address of the other Router token wallet
refund_address	address	Address where refund will be sent if swap fails
excesses_address	address	Address where TON excesses will be sent
deadline	uint64	Timestamp of execution deadline for this tx
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
min_lp_out	coins	Minimum required amount of lp tokens to receive
receiver_address	address	Address where lp tokens will be sent
both_positive	uint1	Trigger liquidity deposit only if both token amounts are non-zero
fwd_gas	coins	Gas used to forward a message in transfer_notification after mint if custom_payload is present
custom_payload	maybe_ref	Payload sent in transfer_notification after lp mint

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	0x2993ade0	Sends a message with a pool address for a requested token pair; counterpart to get_pool_address

getter_pool_address (0x2993ade0)

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#2993ade0 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.

Common operations table

Name	Value	Description
set_fees	0x58274069	Change fee parameters of a pool
reset_pool_gas	0x66d0dff2	Update the amount of TON (in nanoTons) on a pool to storage_fee::router of a pool
update_pool_status	0x2af4607c	Change Pool status
update_status	0x38a6022f	Change Router status
init_code_upgrade	0x03601fc8	Initiate code upgrade for the Router
init_admin_upgrade	0x0b02fd5b	Initiate admin change for the Router
cancel_admin_upgrade	0x72d6b3b4	Cancel an admin change
cancel_code_upgrade	0x1f72111a	Cancel a code upgrade
finalize_upgrades	0x4e6707b7	Finalize upgrades of the Router code and admin change
reset_gas	0x29d22935	Update the amount of TON (in nanoTons) on the Router to storage_fee::router of the Router
set_params	0x2b8b3b62	Change pool-specific parameters

set_fees (0x58274069)

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

set_fees#58274069 query_id:uint64 new_lp_fee:uint16 new_protocol_fee:uint16 new_protocol_fee_address:MsgAddress jetton_info:^[jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress excesses_recipient:MsgAddress] = InternalMsgBody;

Arguments

Name	Type	Description
new_lp_fee	uint16	New liquidity pool fee ratio
new_protocol_fee	uint16	New protocol fee ratio
new_protocol_fee_address	address	Address for receiving protocol fees
additional_data	cell	Cell with wallet addresses

additional_data 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
excesses_address	address	The address where TON excesses will be sent

Notes:

• fee ratio is the value of fee divided by params::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.

update_status (0x38a6022f)

Changes Router is_locked var to the opposite value. If is_locked == 1 blocks transfer_notification messages from going through. Effectively blocks swap and provide_lp transactions through this Router.

TL-B

update_status#38a6022f query_id:uint64 = InternalMsgBody;

Arguments

None.

Outgoing messages

None.

init_code_upgrade (0x03601fc8)

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#3601fc8 query_id:uint64 new_code:^Cell = InternalMsgBody;

Arguments

Name	Type	Description
new_code	cell	Code of the new Router contract

Outgoing messages

Excesses will be sent to admin_address

init_admin_upgrade (0x0b02fd5b)

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#b02fd5b query_id:uint64 new_admin_address:MsgAddress = InternalMsgBody;

Arguments

Name	Type	Description
new_admin	address	New admin address

Outgoing messages

Excesses will be sent to admin_address

cancel_admin_upgrade (0x72d6b3b4)

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

TL-B

cancel_admin_upgrade#72d6b3b4 query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

Excesses will be sent to admin_address

cancel_code_upgrade (0x1f72111a)

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

TL-B

cancel_code_upgrade#1f72111a query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

Excesses will be sent to admin_address

finalize_upgrades (0x4e6707b7)

Finalizes upgrades of the Router code and admin changes. 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#4e6707b7 query_id:uint64 = InternalMsgBody;

Arguments

None

Outgoing messages

None

reset_gas (0x29d22935)

Updates the amount of TON (in nanoTons) on the Router to storage_fee::router (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

Excesses will be sent to admin_address

reset_pool_gas (0x66d0dff2)

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

TL-B

reset_pool_gas#66d0dff2 query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress excesses_recipient: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
excesses_address	address	The address where TON excesses will be sent

Outgoing messages

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

update_pool_status (0x2af4607c)

Changes Pool is_locked var to the opposite value. If is_locked == 1 blocks swaps and liquidity withdraws from this Pool

TL-B

update_pool_status#2af4607c query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress excesses_recipient: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
excesses_address	address	The address where TON excesses will be sent

Outgoing messages

Excesses will be sent to excesses_address

---

Internal message handlers

pay_to (0x657b54f5)

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

TL-B

pay_to#657b54f5 query_id:uint64 to_address:MsgAddress excesses_address:MsgAddress original_caller:MsgAddress exit_code:uint32 custom_payload:(Maybe ^Cell) additional_info:^[fwd_ton_amount:Coins amount0_out:Coins token0_address:MsgAddress amount1_out:Coins token1_address:MsgAddress] = InternalMsgBody;

Message body

Name	Type	Description
op	uint32	Operation code; equal to pay_to
query_id	uint64	Query id
to_address	address	Address of a receiver
excesses_address	address	Address where TON excesses will be sent
original_caller	address	Address of the original tx sender
exit_code	uint32	Exit code
custom_payload	maybe_ref	Payload sent in transfer_notification
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
fwd_gas	coins	Gas used to forward custom_payload if present
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

or

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

or

Sends swap to some Pool if custom_payload is cross_swap

pay_vault (0x63381632)

Deposit a token amount into a Vault contract; used if swap was done with referral

TL-B

pay_vault#63381632 query_id:uint64 owner:MsgAddress excesses_address:MsgAddress additional_info:^[amount0_out:Coins token0_address:MsgAddress amount1_out:Coins token1_address:MsgAddress] = InternalMsgBody;

Message body

Name	Type	Description
op	uint32	Operation code; equal to pay_vault
query_id	uint64	Query id
to_address	address	Address of a receiver
excesses_address	address	The address where TON excesses will be sent
additional_data	cell	Cell with additional data

additional_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 deposit_ref_fee to a corresponding token Vault of to_address

vault_pay_to (0x2100c922)

Initiates a Jetton token transfer from wallets belonging to this Router, called from a Vault when an owner withdraws their collected referral fees.

TL-B

vault_pay_to#2100c922 query_id:uint64 amount_out:Coins token_address:MsgAddress to_address:MsgAddress = InternalMsgBody;

Message body

Name	Type	Description
op	uint32	Operation code; equal to vault_pay_to
query_id	uint64	Query id
amount_out	coins	Amount of the Jetton token (in basic token units)
token_address	address	The address of the Router's wallet of the Jetton
to_address	address	Address of a receiver

Outgoing messages

Sends transfer of amount_out tokens to to_address message to token_address wallet

---

Custom swap payloads

Forward swap to another router

Use a normal swap payload as custom_payload in the initial swap with the other Router address as the receiver_address. The value of fwd_gas must be non-zero and enough to perform the next swap.

Cross-swap payload

This payload allows chaining of swap operations on the same Router; fwd_gas is ignored.

TL-B

cross_swap#69cf1a5b token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 cross_swap_body:^[min_out:Coins receiver:MsgAddress fwd_gas:Coins custom_payload:(Maybe ^Cell) refund_fwd_gas:Coins refund_payload:(Maybe ^Cell) ref_fee:uint16 ref_address:MsgAddress] = DexPayload;

custom_payload body

Name	Type	Description
op	uint32	Cross-swap op (0x69cf1a5b)
other_token_wallet	address	Address of the other Router token wallet
refund_address	address	Address where refund will be sent if swap fails
excesses_address	address	Address where TON excesses will be sent
deadline	uint64	Timestamp of execution deadline for this tx
additional_data	cell	Cell with additional data

additional_data body

Name	Type	Description
min_out	coins	Minimum required amount of tokens to receive
receiver_address	address	Address where tokens will be sent after swap
fwd_gas	coins	Gas used to forward a message in transfer_notification after swap if custom_payload is present
custom_payload	maybe_ref	Payload sent in transfer_notification after swap
refund_fwd_gas	coins	Gas used to forward a message in transfer_notification if swap fails if refund_payload is present
refund_payload	maybe_ref	Payload sent in transfer_notification if swap fails
ref_fee	uint16	Referrer fee
referral_address	address	Referrer address

---

Constants

Name	Value	Description
storage_fee::router	10000000	Amount of TON (in nanoTons) to be left on the Router contract as gas
params::twodays	172800	Two days is seconds
params::sevendays	604800	Seven days in seconds