Comment on page
Router
This section contains op codes of the router contract as well as corresponding SDK methods
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>
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 |
Returns single slice with the address of liquidity pool for specified pair of Jettons.
TypeScript
async getPool(params: {
jettonAddresses: [AddressType, AddressType];
}): Promise<Pool | null>
Key | Type | Description |
---|---|---|
jettonAddresses | [AddressType, AddressType] | Tuple of Jetton addresses of a pool |
Returns a
Pool
object for a pool with specified Jetton token addresses.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>
None
Returns
RouterData
structure containing current state of the router.RouterData
structureKey | 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 |
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.transfer_notification#7362d09c query_id:uint64 jetton_amount:Grams from_user:MsgAddress ref_msg_data:^DexPayload = InternalMsgBody;
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 |
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
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 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.swap_op#25938561 = SwapOP;
swap$_ transferred_op:SwapOP token_wallet1:MsgAddress min_out:Grams to_address:MsgAddress ref_address:(Either MsgAddress MsgAddress) = DexPayload;
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 |
Sends a message with op
swap
to a liquidity poolBuild
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>
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 |
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 a payload to initiate a
swap
transaction.TypeScript
async createSwapBody(params: {
userWalletAddress: AddressType;
minAskAmount: AmountType;
askJettonWalletAddress: AddressType;
referralAddress?: AddressType;
}): Promise<Cell>
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 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.provide_lp_op#fcf9e58f = ProvideLpOP;
provide_lp$_ transferred_op:ProvideLpOP token_wallet1:MsgAddress min_lp_out:Grams = DexPayload;
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) |
Sends a message with op
provide_lp
to a liquidity poolBuild
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>
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 |
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 a payload to initiate a
provide_lp
transaction.TypeScript
async createProvideLiquidityBody(params: {
routerWalletAddress: AddressType;
minLpOut: AmountType;
}): Promise<Cell>
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 counterparts of getter methods
Name | Value | Description |
---|---|---|
getter_pool_address | 0xd1db969b | Sends a message with a pool address for a requested token pair; counterpart to get_pool_address |
Sends a message with an address of a pool for a specified pair of assets; counterpart to
get_pool_address
getter_pool_address#d1db969b query_id:uint64 token0:MsgAddress token1:MsgAddress = InternalMsgBody;
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 |
Sends a message back to the sender with the pool address
Name | Type | Description |
---|---|---|
op | uint32 | Operation code equal to getter_pool_address |
query_id | uint64 | Query id |
pool_address | address | Address of a pool |
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.
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
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.
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;
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 |
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) andMAX_FEE
(100)
Sends a message with op
set_fees
to a liquidity pool.Collect protocol fees from a pool. The appropriate Jetton wallet addresses must be provided.
collect_fees#1fcb7d3d query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;
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 |
Sends a message to a liquidity pool with
collect_fees
op code.Stops all
transfer_notification
messages from going through. Effectively blocks swap
and provide_lp
transactions through this router.lock#878f9b0e query_id:uint64 = InternalMsgBody;
None.
None.
Allows all
transfer_notification
messages to go through. Enables swap
and provide_lp
transactions through this router.unlock#6ae4b0ef query_id:uint64 = InternalMsgBody;
None
None.
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.init_code_upgrade#df1e233d query_id:uint64 code:^Cell = InternalMsgBody;
Name | Type | Description |
---|---|---|
code | cell | Code of the new router contract |
None
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.init_admin_upgrade#2fb94384 query_id:uint64 admin:MsgAddress = InternalMsgBody;
Name | Type | Description |
---|---|---|
admin | address | New admin address |
None
Cancels an admin change if there's a pending admin change.
cancel_admin_upgrade#a4ed9981 query_id:uint64 = InternalMsgBody;
None
None
Cancels a code upgrade if there's a pending code change.
cancel_code_upgrade#357ccc67 query_id:uint64 = InternalMsgBody;
None
None
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.
finalize_upgrades#6378509f query_id:uint64 = InternalMsgBody;
None
None
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.reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody;
None
Sends an empty message back to admin with the remaining $TON
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.reset_pool_gas#2fb94384 query_id:uint64 jetton_wallet0:MsgAddress jetton_wallet1:MsgAddress = InternalMsgBody;
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 |
Sends a message to a liquidity pool with
reset_gas
op code carrying remaining gasInitiates a Jetton token transfer from wallets belonging to this router, called from pools (on swap, liquidity providing, refund, etc).