<!-- toc -->

# Architecture

We designed a modular DEX that leverages TON's sharding to distribute load during congestion, ensuring smooth and uninterrupted transactions.

## Preliminary

### Asset

The Asset structure enables the protocol to handle different types of assets with the same logic, including Jetton, TON, XC, and potentially new token standards in the future.

We use a 4-bit prefix to distinguish asset types, which can be checked using `preload_uint(4)`.

Additional token information may be stored after the 4-bit prefix.

- Native (`$0000`), represents TON.
- `begin_cell().store_uint(0, 4).end_cell()`
- Jetton (`$0001`), represents Jetton v1.
- `begin_cell().store_uint(1, 4).store_slice(jetton master address, must not be empty).end_cell()`
- XC (`$0010`), represents extra currency.
- `begin_cell().store_uint(2, 4).store_int(token id, 32).end_cell()`
- Generally, XC is uint32, but we use -1 to indicate the absence of an XC, so int32 is used.

### Factory

The Factory is responsible for deploying all Torch contracts, including Vaults, Pools, and LP Accounts.

In addition to handling contract deployment, the Factory stores admin-related information for Pools and plays a key role in the deposit process. Based on user deposits, the Factory deploys dedicated LP Account contracts for each user.

This design keeps the Torch system running smoothly and everything working together seamlessly.

### Vault

Torch currently supports TON Vault and Jetton Vault (with future plans for Extra-Currency Vault). These Vault contracts manage user assets, storing them directly within the Vault.

#### Key Advantages

1. **Simplified Pool Logic**
- The Pool focuses on mathematics, while Vaults handle asset storage and transfers, reducing complexity and risk.

2. **Optimized for Different Assets**
- Separate Vaults for each asset type allow easy expansion. Future assets, like extra currencies, can integrate smoothly by deploying new Vaults.

3. **Efficient Transactions**
- Dedicated Vaults leverage TON’s sharding to process high volumes during congestion, preventing bottlenecks.

4. **Easy Cross-Pool Operations**
- Vaults simplify cross-pool swaps by managing asset transfers, requiring only the asset type and amount to complete operations.

Torch’s Vault system ensures efficient asset management, scalability, and seamless growth in the evolving DeFi landscape.

### Pool

As mentioned earlier, pool contract handles mathematical logic and does not manage assets. This allows us to expand and implement various Pool types with different formulas (such as Weighted Pools). Currently, Torch has two types of Pools:

1. **Base Pool** – Utilizes Curve’s Stable Swap algorithm, enabling low-slippage swaps (e.g., the triTON Base Pool consisting of TON/tsTON/stTON).
2. **Meta Pool** – Composed of the LP token from a Base Pool and another asset pegged to the Base Pool (e.g., the triTON LP/hTON Meta Pool).

This structure provides flexibility and scalability, supporting diverse liquidity needs across the Torch ecosystem.

### LP Account

The LP Account waits until all assets from the user's deposit have been received. Once the assets are confirmed, the LP Account sends an `op::deposit_all` message to notify the Pool of the liquidity provided by the user.

If the user deposits only one asset, an LP Account contract is not created. Instead, the Vault directly notifies the Pool upon receiving the asset.

## Process of Deposit


To provide liquidity to Torch Finance's N-asset pool, users can choose to deposit between 1 to N assets. Since TON operates as an asynchronous system, the deposit process follows these steps:

1. **Asset Deposit into Vault**
- Users deposit each asset into its corresponding Vault contract.

2. **Vault Notifies Factory**
- After receiving the assets, the Vault sends an `op::deposit_internal` message to the Factory.
- This message contains details of the liquidity provided by the user.

3. **Factory Deploys LP Account**
- Based on the message, the Factory deploys a dedicated LP Account contract for the user.
- The LP Account records the deposit and waits for the remaining assets.

4. **All Assets Deposited**
- Once the LP Account confirms all assets have been deposited, it sends an `op::deposit_all` message to the Pool with deposit details.

5. **Pool Calculates and Notifies Lp Vault**
- After completing the necessary calculations, the Pool sends an `op::payout` to the Pool’s LP Vault, instructing it to transfer LP tokens to the user’s designated recipient.

6. **Cross-Pool Deposits Operations**

- If the deposit involves cross-pool operations, the base pool will include relevant deposit details and send an `op::deposit_between` or `op::swap_between` message to the next pool for further processing.
- A detailed explanation of cross-pool operations will be provided in the [following sections](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Cross-Pool-Operations).

---

### The Role of LP Vault

You might wonder:
**When does the LP Vault come into play, and why does it already hold LP tokens for transfer?**

This is because, during **Pool creation**, Torch automatically performs the following:
- **LP Vault** is deployed alongside the Pool as a dedicated storage for pool assets.
- LP tokens are **preminted** to the LP Vault at the time of deployment (LP Vault is a type of Jetton Vault).

---

### Benefits of This Design

1. **Simplified Pool Logic**
- The Pool does not need to handle LP token minting after deposits.
- Similar to swap operations, the Pool simply instructs the Vault to transfer LP tokens, reducing complexity.

2. **Efficient Cross-Pool Operations**
- When LP tokens are generated through cross-pool operations, the Pool doesn’t need to mint additional LP tokens to the LP Vault.
- This reduces gas costs and enhances overall efficiency.

This design enhances system efficiency, lowers costs during high-frequency trades or cross-pool operations, and streamlines asset management across the Torch ecosystem.

---

### Safety Notice

When depositing to Torch Finance, users are advised to deposit assets in balanced proportions to minimize fees during the deposit process. The more balanced the deposit, the lower the fees, improving the efficiency and cost-effectiveness of liquidity provision.

#### **The Importance of Balanced Deposits**
Depositing assets in highly unbalanced proportions may result in higher fees. While this typically only occurs when depositing large amounts, maintaining balanced deposits can significantly reduce costs and avoid unnecessary fees.

#### **Example – triTON Pool (TON/tsTON/stTON)**
Suppose the price of stTON is **1.0428 TON** and tsTON is **1.036 TON**. Users are encouraged to deposit assets according to the following ratio:
- **TON : stTON : tsTON = 1 : 1 / 1.036 : 1 / 1.0428**

Depositing in this proportion helps minimize fees and ensures optimal asset balance.

#### **Avoiding Unbalanced Deposits**
For example, in the triTON Pool, if a user deposits assets in severely unbalanced amounts:
- **11000 TON / 10 tsTON / 10 stTON**

Such highly disproportionate deposits will result in significant fees and are strongly discouraged.

By maintaining balanced asset ratios, users can optimize deposit costs, enhance the deposit experience, and avoid unnecessary fee expenses.

## Process of Swap


Torch’s Stable Swap mechanism effectively reduces slippage during swaps, providing a more cost-efficient trading experience. Below is a detailed breakdown of the swap process:

1. **Asset Transfer to Vault**
- Users transfer the asset they wish to swap (swap in asset) to the corresponding Vault contract.

2. **Vault Notifies Pool**
- Once the Vault receives the asset, it sends an `op::swap_internal` message to the Pool contract, initiating the swap calculation.

3. **Pool Calculates and Notifies Vault**
- After the calculation, the Pool determines the amount of the swap out asset and sends an `op::payout` message to the Vault responsible for the swap out asset.
- The Vault then transfers the swapped asset to the user’s designated address as instructed.

4. **Cross-Pool Swap Operations**
- If the swap involves cross-pool operations, the Pool includes swap details and sends an `op::swap_between` or `op::withdraw_between` message to the next Pool to continue the swap process.
- A detailed explanation of cross-pool operations will be provided in the [following sections](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Cross-Pool-Operations).

## Process of Withdraw


Torch supports multiple withdrawal methods to meet different liquidity needs. Below is a detailed breakdown of the withdrawal process:

1. **Transfer LP Tokens to LP Vault**
- Users transfer their LP tokens from the pool to the corresponding LP Vault.

2. **LP Vault Notifies Pool**
- After receiving the tokens, the LP Vault sends an `op::withdraw_internal` message to the Pool, notifying it of the withdrawal request and relevant details.

3. **Pool Calculates and Notifies Vault**
- The Pool processes the withdrawal logic, determines the amount of assets to withdraw, and sends an `op::payout` message to the Vault.
- The Vault then transfers the assets to the user’s designated recipient address as instructed.

4. **Cross-Pool Withdrawal Operations**
- If the withdrawal involves cross-pool operations, the first Pool carries the withdrawal details and sends an `op::withdraw_between` message to the next Pool to continue the process.
- A detailed explanation of cross-pool operations will be provided in the [following sections](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Cross-Pool-Operations).

---

### **Withdrawal Methods**
Torch currently supports two types of withdrawals:

1. **Withdraw All**
- Users withdraw all assets proportionally from the pool, receiving liquidity that reflects the asset ratio within the pool. This method does not incur any fees.

2. **Withdraw One**
- Users withdraw a specific asset from the pool. The fees for this method depend on the level of imbalance caused to the pool by the withdrawal.

---

## Cross-Pool Operations

### Deposit and Deposit


Let's assume there are two pools:
1. **Base Pool** – triTON Pool (TON/tsTON/stTON)
2. **Meta Pool** – quaTON Pool (triTON LP / hTON)

#### **Deposit and Deposit Process**
Suppose you currently hold **stTON** and **hTON** and want to maximize your rewards. You can achieve this through a **deposit and deposit** process.

Here’s how it works:
1. **First Deposit** – Deposit **stTON** into the **triTON Pool** to receive **triTON LP tokens**.
2. **Second Deposit** – Take the obtained **triTON LP** along with **hTON** and deposit them into the **quaTON Pool** to receive **quaTON LP tokens**.

---

#### **Detailed Flow**

- The **LP Account contract** will wait until both **stTON** and **hTON** deposits are received.
- Once both assets arrive, the LP Account sends an `op::deposit_all` message to the **triTON Pool** to process the stTON deposit.
- The **triTON Pool** calculates the amount of **triTON LP** the user will receive.
- After calculation, the triTON Pool packages the **triTON LP** and **hTON** deposit information and sends an `op::deposit_between` message to the **quaTON Pool**.
- The **quaTON Pool** then calculates the final amount of **quaTON LP** the user will receive.

For a complete view of the process, please refer to the [diagram](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Process-of-Deposit).

---

#### **Alternative Deposit Scenarios**
This process can also be performed using only the assets within the **triTON Pool**, without the need for hTON. In such cases, users can still achieve the **deposit and deposit** operation by utilizing assets directly from the Base Pool.

---

### Deposit and Swap


In the following example, the scenario typically involves users swapping Token A for Token B, a process that may involve multiple pools.

#### **Deposit and Swap Process**

Continuing from the previous example, suppose you currently hold **stTON** and want to swap it for **hTON**. This can be achieved through a **deposit and swap** process.

Here’s how it works:
1. **First Step** – Deposit **stTON** into the **triTON Pool** to receive **triTON LP tokens**.
2. **Second Step** – Use the obtained **triTON LP** to perform a swap in the **quaTON Pool**, swapping the **triTON LP** for **hTON**.

---

#### **Detailed Flow**

- The **deposit process** for the first step is the same as the one described earlier (refer to [this link](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Process-of-Deposit) for details).
- However, after the triTON Pool completes the deposit, it does not send an `op::payout` to the LP Vault.
- Instead, the triTON Pool sends an `op::swap_between` message to the **quaTON Pool** to initiate the swap.
- Once the swap is completed, the quaTON Pool sends an `op::payout` message to the hTON vault, transferring **hTON** to the user’s designated address.

---

### Swap and Withdraw


Continuing from the previous [Deposit and Swap](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Deposit-and-Swap) example, this time we perform the reverse operation through **Swap and Withdraw** to convert assets from hTON to stTON.

#### **Swap and Withdraw Process**
Suppose you currently hold **hTON** and want to swap it for **stTON**. This can be done through the following steps:
1. **Step 1 – Swap hTON for triTON LP**
- Swap **hTON** for **triTON LP** in the **quaTON Pool**.
2. **Step 2 – Withdraw triTON LP to receive stTON**
- Use the obtained **triTON LP** to perform a withdrawal (Withdraw One mode) in the **triTON Pool** to receive **stTON**.

---

#### **Detailed Flow**
- The **swap process** is the same as the one described earlier (refer to [this link](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Process-of-Swap)).
- However, after the **quaTON Pool** completes the swap, it does not send an `op::payout` to the **stTON Vault** directly.
- Instead, the **quaTON Pool** sends an `op::withdraw_between` message to the **triTON Pool** to initiate the withdrawal process.
- After the **triTON Pool** completes the withdrawal, it sends an `op::payout` message to the **stTON Vault**, transferring the assets to the user’s designated address.

---

### Withdraw and Withdraw


Continuing from the previous **Deposit and Deposit** example, this time we perform the reverse operation through **Withdraw and Withdraw** to convert assets from quaTON LP to stTON in the triTON Pool.

#### **Withdraw and Withdraw Process**
Suppose you currently hold **quaTON LP** and want to convert it to **stTON** in the triTON Pool. This can be achieved through the following steps:
1. **Step 1 – Withdraw quaTON LP for triTON LP**
- Perform a withdrawal in the **quaTON Pool** to receive **triTON LP**.
2. **Step 2 – Withdraw triTON LP for stTON**
- Use the obtained **triTON LP** to perform a withdrawal in the **triTON Pool** to receive **stTON**.

---

#### **Detailed Flow**
- The **withdrawal process** for the first step is the same as the one described earlier (refer to [this link](https://hackmd.io/WUJkKbNOSeujHtjYyB73uA?view#Process-of-Withdraw)).
- However, after the **quaTON Pool** completes the withdrawal, it does not send an `op::payout` to the **triTON LP Vault**.
- Instead, the **quaTON Pool** sends an `op::withdraw_between` message to the **triTON Pool** to initiate the next withdrawal process.
- After the **triTON Pool** completes the withdrawal, it sends an `op::payout` message to the **stTON Vault**, transferring the assets to the user’s designated address.

---

#### **Withdrawal Modes**
Since Torch supports two withdrawal modes – **Withdraw All** and **Withdraw One** – there are four possible combinations during the **Withdraw and Withdraw** process:
- **Withdraw All and Withdraw All**
- **Withdraw One and Withdraw One**
- **Withdraw All and Withdraw One**
- **Withdraw One and Withdraw All**

Users can choose the appropriate combination based on their specific needs and desired outcomes.

---