# Router (v1)

## 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` | 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 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`    | 0     | if operations are locked (`swap`, `provide_lp`)                                                                  |
| `admin_address`         | `address` | 1     | Address of contract's admin account                                                                              |
| `temp_upgrade`          | `cell`    | 2     | A structure describing state of contract's code & admin upgrade; zero values indicate that no upgrade is pending |
| `pool_code`             | `cell`    | 3     | Code of the router's liquidity pool contract                                                                     |
| `jetton_lp_wallet_code` | `cell`    | 4     | Code of lp wallet contract                                                                                       |
| `lp_account_code`       | `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:(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` | 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                                                 |