Router (v1)

STON.fi v1 Router smart contract - entry point for swaps and liquidity operations on-chain

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

Previousv1 Smart Contracts NextPool (v1)

Last updated 4 months ago

hashtagOff-chain get methods

hashtagget_pool_address

hashtagArguments

hashtagResult

hashtagget_router_data

hashtagArguments

hashtagResult

hashtagtransfer_notification operations

hashtagtransfer_notification (0x7362d09c)

hashtagTL-B

hashtagMessage body

hashtagref_msg_data body

hashtagTransfer operations table

hashtagswap (0x25938561)

hashtagTL-B

hashtagref_msg_data body

hashtagOutgoing messages

hashtagprovide_lp (0xfcf9e58f)

hashtagTL-B

hashtagref_msg_data body

hashtagOutgoing messages

hashtagOn-chain queries

hashtagOperations table

hashtaggetter_pool_address (0xd1db969b)

hashtagTL-B

hashtagMessage Body

hashtagOutgoing messages

hashtagResponse message body

hashtagOn-chain admin operations

hashtagOperations table

hashtagset_fees (0x355423e5)

hashtagTL-B

hashtagArguments

hashtagref_wallets body

hashtagOutgoing messages

hashtagcollect_fees (0x1fcb7d3d)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtaglock (0x878f9b0e)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagunlock (0x6ae4b0ef)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtaginit_code_upgrade (0xdf1e233d)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtaginit_admin_upgrade (0x2fb94384)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagcancel_admin_upgrade (0xa4ed9981)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagcancel_code_upgrade (0x357ccc67)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagfinalize_upgrades (0x6378509f)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagreset_gas (0x42a0fb43)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagreset_pool_gas (0xf6aa9737)

hashtagTL-B

hashtagArguments

hashtagOutgoing messages

hashtagInternal message handlers

hashtagpay_to (0xf93bb43f)

hashtagTL-B

hashtagMessage body

hashtagref_coins_data body

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)

TL-B

Message body

`ref_coins_data` body