> For the complete documentation index, see [llms.txt](https://avitus.gitbook.io/avitus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://avitus.gitbook.io/avitus-docs/technical-overview.md).

# Technical Overview

## Act 1 : Depositing LP

<figure><img src="/files/CrjsVrxpSQem8rYRR7RS" alt=""><figcaption></figcaption></figure>

## Depositing LP in Avitus

Avitus employs a **two‐step flow** to facilitate secure and efficient liquidity provisioning:

1. **`createDeposit`**
   * Gathers deposit parameters from the user
   * Validates those parameters
   * Prepares a deposit record
   * Returns a **unique deposit key**
2. **`executeDeposit`**
   * Uses the deposit key to fetch the prepared deposit
   * Validates current market conditions and user parameters
   * Executes token swaps, calculates fees/price impact
   * Mints “market tokens” to the user based on the final deposit value

In the sections below, each **step** and **function** are explained in detail.

***

### 1. `createDeposit` Flow

#### a. User Supplies Deposit Details

* The user initiates the deposit by calling `createDeposit` with:
  * **Deposit details** — information such as token addresses, desired deposit amounts, market where they want to invest and any additional parameters (like minimum acceptable tokens to receive).
  * **User account address** — the address that will eventually receive the minted “market tokens.”

#### b. Validate Account and Market

* **Box**: *validate Account and Market*
* **Purpose**: Verifies that:
  * The **caller’s address** is valid (e.g., not the zero address).
  * The **market** into which the user is depositing is recognized and active in Avitus.
* **Outcome**: If either validation fails, the transaction reverts immediately, preventing invalid deposits.

#### c. Get Initial Long and Short Token

* **Box**: *get Intial Long and short token*
* **Purpose**: Determines how many of each token (long token, short token) were sent by the user into the Avitus deposit vault.
* **Special Case**:
  * If the deposited token is the **wrapped native token** (e.g., WETH), the protocol notes that execution fees may be deducted in that token.

#### d. Deduct Execution Fees from the User’s Deposit

* **Box**: *Deduct execution fees from the user’s deposit*
* **Purpose**:
  * Confirms the user has provided enough tokens to cover the deposit **and** the **execution fee**.
  * If insufficient, the deposit is reverted.

#### e. Validate Receiver

* **Box**: *validateReceiver*
* **Purpose**: Ensures the user‐specified **receiver** address (the address that will receive the minted market tokens) is valid (non‐zero, properly formatted).

#### f. Construct Deposit Object

* **Box**: *Construct Deposit Object*
* **Purpose**:
  * Packages all the user’s deposit parameters (validated amounts, addresses, fees) into a cohesive data structure.
  * This object will be stored on‐chain and referenced in the second step.

#### g. Generate a Unique Key

* **Box**: *Generate a Unique Key*
* **Purpose**:
  * Produces a **unique identifier** (often a `bytes32` hash) for the deposit.
  * This key references the specific deposit record and is essential for the subsequent `executeDeposit` call.

#### h. Validate Execution Fee

* **Box**: *Validate Execution Fee*
* **Purpose**:
  * Compares the user’s provided fee amount with the **estimated cost** of executing the deposit.
  * If it falls short, the deposit creation is rejected.

#### i. Estimate Gas

* **Box**: *Estimate Gas*
* **Purpose**:
  * Predicts how much gas the eventual `executeDeposit` call might consume, based on factors like how many tokens are being processed, and what swaps might be needed.

#### j. Validate Callback Gas Limit

* **Box**: *Validate Callback Gas Limit*
* **Purpose**:
  * Ensures any “callback” function (if Avitus is set up to do a callback to a user’s contract) has a safe, allowable gas limit.

#### k. Store Deposit Details

* **Box**: *Store Deposit Details*
* **Purpose**:
  * Persists the constructed deposit data and the unique deposit key to Avitus’s internal data store (e.g., a mapping in a smart contract).

#### l. Emit Event

* **Box**: *Emit Event*
* **Purpose**:
  * Fires a blockchain event indicating that a deposit record was created.
  * Off‐chain services (like UIs or indexers) can track deposits by listening to this event.

#### m. Return the Key

* **Box**: *Return the Key*
* **Purpose**:
  * Returns the **unique key** to the caller, typically as a function return value.
  * The user (or front‐end) must keep this key to proceed with the `executeDeposit` step.

***

### 2. `executeDeposit` Flow

Once the deposit has been created, someone must call `executeDeposit` (usually the same user, but it could be a keeper or another authorized entity). They will provide the **deposit key** generated earlier.

#### a. Gas Calculation

* **Box**: *Gas Calculation*
* **Purpose**:
  * Adjusts the starting gas in compliance with Ethereum’s “63/64 rule” or other chain‐specific nuances to ensure that subsequent internal calls have enough gas.

#### b. Remove Deposit Entry

* **Box**: *Remove Deposit Entry*
* **Purpose**:
  * Retrieves the deposit data (by the key) from Avitus’s store.
  * Removes that record to avoid potential replay or duplication.
  * If the deposit key is invalid or doesn’t exist, the transaction reverts.

#### c. Fetch Market Data

* **Box**: *Fetch Market Data*
* **Purpose**:
  * Retrieves important info about the target market where the user is depositing.
  * Data may include the current liquidity, existing market token supply, price feeds, and any special rules or limits.

#### d. Validate Initial Deposit

* **Box**: *Validate Initial Deposit*
* **Purpose**:
  * If this is the first deposit into a brand‐new market, enforces any extra constraints for “initial deposits” (e.g., minimum liquidity thresholds).

#### e. Get Market Prices

* **Box**: *Get Market Prices*
* **Purpose**:
  * Retrieves the latest token prices from oracles or internal price feeds.
  * Used for calculating how many market tokens to mint in return for the user’s deposit.

#### f. Distribute Position Impact Pool

* **Box**: *Distribute Position Impact Pool*
* **Purpose**:
  * Adjusts the deposit’s effect on the overall liquidity pool by distributing any existing “price impact” from prior trades or deposits.
  * Helps maintain fair pricing as liquidity changes.

#### g. Validate Max PnL Factor

* **Box**: *Validate Max PnL Factor*
* **Purpose**:
  * Ensures the protocol’s **risk parameters** are respected (e.g., you can’t deposit if you’d exceed a certain profit‐and‐loss exposure).

#### h. Perform Swaps

* **Box**: *Perform Swaps*
* **Purpose**:
  * Executes any necessary token swaps to obtain the correct balance of “long” vs. “short” tokens for this deposit.
  * For instance, if a user deposits ETH but the market requires both ETH and a stablecoin for the position, it will swap as needed.

#### i. Calculate USD Values

* **Box**: *Calculate USD Values*
* **Purpose**:
  * Converts the user’s final token amounts (post‐swap) into an equivalent USD value, based on the mid‐market price.

#### j. Calculate Price Impact USD

* **Box**: *Calculate Price Impact USD*
* **Purpose**:
  * Determines how much the user’s deposit changes the market price (e.g., if a large deposit pushes the token price up or down).
  * This is reflected as **positive** or **negative** price impact.

#### k. Process Long and Short Token Deposits

* **Box**: *Process Long and Short Token Deposits*
* **Purpose**:
  * If the deposit includes both “long” and “short” positions, handles them in separate branches.
  * Ensures each side is credited correctly according to the deposit amounts.

#### l. Calculate Swap Fees

* **Box**: *Calculate Swap Fees*
* **Purpose**:
  * Determines the total fees owed to the protocol for performing these swaps, typically a percentage of the swapped amounts.

#### m. Increment Claimable Fees

* **Box**: *Increment Claimable Fees*
* **Purpose**:
  * Adds the newly calculated swap fees to the protocol’s **claimable‐fee pool**, which may be collected by governance or stakers.

#### n. Retrieve Pool Value Info

* **Box**: *Retrieve Pool Value Info*
* **Purpose**:
  * Fetches the **total liquidity** in the market.
  * This is crucial for deciding how many new “market tokens” the depositor should receive, based on the deposit’s share of the pool.

#### o. Retrieve Market Token Supply

* **Box**: *Retrieve Market Token Supply*
* **Purpose**:
  * Checks the total supply of existing market tokens.
  * Used to calculate the depositor’s ownership stake in the pool.

#### p. Handle Positive Price Impact

* **Box**: *Handle Positive Price Impact*
* **Purpose**:
  * If the deposit contributes beneficially to the pool (e.g., balancing liquidity or covering an under‐collateralized side), the depositor might receive **extra** market tokens (an incentive to add liquidity).

#### q. Mint Market Tokens

* **Box**: *Mint Market Tokens*
* **Purpose**:
  * Mints new tokens in proportion to the user’s deposit value relative to the total pool value and existing token supply.

#### r. Validate Minimum Tokens

* **Box**: *Validate Minimum Tokens*
* **Purpose**:
  * Ensures the user receives **at least** the minimum number of tokens they specified in their deposit parameters.
  * If the actual amount is too low (due to price movement or slippage), the deposit may revert to protect the user.

#### s. Handle Negative Price Impact

* **Box**: *Handle Negative Price Impact*
* **Purpose**:
  * If the deposit causes a **negative** price impact, fewer tokens get minted.
  * Some of the tokens may remain in the “impact pool” instead of going to the user.

#### t. Final Validations

* **Box**: *Final Validations*
* **Purpose**:
  * Double‐checks that internal balances, minted amounts, and fees all align with Avitus’s rules.
  * Confirms no deposit constraints are violated at the last minute (e.g., user deposit didn’t exceed some cap).

#### u. Pay Execution Fees

* **Box**: *Pay Execution Fees*
* **Purpose**:
  * Distributes the **execution fee** (collected earlier) to the entity that executed the deposit, such as a keeper or the protocol itself.

#### v. Final Minting

* **Box**: *Final Minting*
* **Purpose**:
  * Officially transfers the newly minted market tokens into the user’s (receiver’s) address.
  * Concludes the deposit process, marking it as complete.

## Act 2 : Opening Trade&#x20;

<figure><img src="/files/0CTBeGGPsBPGyUQZcPGd" alt=""><figcaption></figcaption></figure>

## Opening a Trade Position in Avitus

In Avitus, **opening a trade** (e.g., going long or short on an asset, or swapping tokens) is separated into two steps:

1. **`createOrder`**
   * The user supplies initial parameters for the order (collateral, fees, target market, etc.).
   * The protocol validates these parameters, estimates fees, and stores the order in Avitus’s data store.
   * A **unique key** is generated to track this specific order.
2. **`executeOrder`**
   * The protocol checks real‐time conditions (e.g., price feeds, trigger prices).
   * If everything is valid, Avitus processes the order (swaps, opens a position, etc.).
   * Finally, it deducts fees, executes callbacks if needed, and completes the order.

Each section below covers these **two functions** and their internal steps in detail.

***

### 1. `createOrder` Flow

#### a. User Calls `createOrder`

* The user triggers the `createOrder` function, passing:
  * **`orderVault`** — the contract or module that manages collateral and token transfers.
  * **`params`** — order‐specific parameters such as:
    * **Order type** (e.g. increase position, decrease position, swap).
    * **Collateral** (which token the user is depositing).
    * **Fees** (execution fee, possible referral discounts, etc.).
    * **Market details** (which market(s) the user wants to trade).
    * Other data like leverage and position size

#### b. Validate Trader’s Account

* **Box**: *Validate Trader’s Account*
* **Purpose**: Ensures the trader’s account (caller) meets protocol requirements.
  * For example: verifying the trader’s address isn’t banned, restricted or does not meet the margin requirements.
* **Outcome**: If the account fails these checks, the function reverts.

#### c. Set Trader Referral Code

* **Box**: *Set Trader Referral Code* (Referral Storage)
* **Purpose**:
  * If the user (trader) provided a referral code, associate that code with the user’s account in the referral tracking system.
  * Helps the protocol track which referrals led to new orders and potentially distribute referral rewards.

#### d. Process Order Based on Type

* **Box**: *Process Order Based on Type*
* **Purpose**:
  * Determines the **initial** handling of collateral and execution fees, depending on whether the user is:
    1. **Decreasing a position**
       * Uses the `params` amount to reduce the trader’s open position.
       * Collateral adjustments might be performed directly.
    2. **Swapping tokens** or **Increasing a position**
       * If the collateral token is the wrapped native token (e.g., WNT), ensure the user deposited enough for the entire collateral **plus** the execution fee.
       * Deduct the execution fee from the collateral if needed.

#### e. Record Execution Fee

* **Box**: *Record Execution Fee*
* **Purpose**:
  * If using the wrapped native token (e.g., WNT) for fees, Avitus transfers the required amount of tokens into an internal fee pool (or dedicated fee address).
  * Ensures that the protocol has the necessary gas to later execute the order.

#### f. Validate Order Conditions

* **Box**: *Validate Order Conditions*
* **Purpose**:
  * For **Position Orders** (long/short trades): verifies the user’s target market is valid and open for trading.
  * For **Swap Orders**: checks the entire swap path (e.g., token A → token B → token C) to ensure each “hop” is recognized and the pair/market is valid.
* **Outcome**: If the market or path is invalid, the order is rejected.

#### g. Validate Receiver and Callback

* **Box**: *Validate Receiver and Callback*
* **Purpose**:
  * Ensures the order’s “receiver” address (where any output tokens or position credit goes) is valid.
  * If the user specified a “callback,” Avitus checks the gas limit or other conditions to ensure that callback execution is allowed.

#### h. Estimate and Validate Gas Fees

* **Box**: *Estimate and Validate Gas Fees*
* **Purpose**:
  * Estimates the on‐chain gas needed to execute this order in the future.
  * Validates that the **execution fee** the user provided is sufficient to cover this estimated cost (otherwise reverts).

#### i. Generate Unique Key and Save Order

* **Box**: *Generate Unique Key and Save Order*
* **Purpose**:
  * Creates a unique identifier (Key) for the new order.
  * Validates that the order object is not empty.
  * Saves the order’s data in Avitus’s **Data Store** under that key, enabling later retrieval during `executeOrder`.

***

### 2. `executeOrder` Flow

When market conditions are right—such as the order’s trigger price being met or the user initiating the final step—someone (the user, a keeper, or another designated executor) calls `executeOrder` with the **order key**.

#### a. Validate the Order

* **Box**: *Validate the Order*
* **Purpose**:
  * Ensures the order object is present in the data store, not expired, not malformed, etc.
  * Confirms that the order is indeed eligible for execution.

#### b. Validate Order’s Trigger Price

* **Box**: *Validate Order’s Trigger Price*
* **Purpose**:
  * For limit orders or stop orders, checks if the **trigger price** set by the user has been reached in the marketplace.
  * If the trigger price condition isn’t met, the order can’t be executed.

#### c. Remove the Order from Storage

* **Box**: *Remove the Order from Storage*
* **Purpose**:
  * Once confirmed valid, Avitus removes the order record from its data store so it **cannot** be executed again (prevents double‐execution or replay).

#### d. Adjust Gas Accounting

* **Box**: *Adjust Gas Accounting*
* **Purpose**:
  * Accounts for Ethereum’s “63/64 rule” on internal calls or any other which is specific to chain.
  * Ensures that subsequent internal operations have enough gas.
  * If the gas is insufficient, it reverts here rather than mid‐execution.

#### e. Process the Order

* **Box**: *Process the Order*
* **Purpose**:
  * Executes the core logic of the trade (opening or closing a position, swapping tokens, etc.).
  * For a **position increase**: uses the user’s collateral to open a bigger position.
  * For a **position decrease**: closes or partially closes the user’s position, returning any freed collateral.
  * For a **swap**: executes the swap route from token A → token B → ... → token X.

#### f. Validate Internal State Changes

* **Box**: *Validate Internal State Changes*
* **Purpose**:
  * After the core logic runs, Avitus checks that internal balances (collateral, user position sizes, etc.) are consistent.
  * Ensures the user’s new position size, collateral usage, or token holdings are reflected correctly.

#### g. Execute Callback Logic

* **Box**: *Execute Callback Logic*
* **Purpose**:
  * If the user specified a “callback” in the order, Avitus calls the user’s contract here.
  * For example, a user might want to do something automatically after the trade is filled.
  * This step is only performed if the callback was validated earlier.

#### h. Pay Execution Fee

* **Box**: *Pay Execution Fee*
* **Purpose**:
  * Avitus uses the fees collected in the “Record Execution Fee” step (from `createOrder`) to compensate the **executor** or the protocol.
  * This covers the gas cost and any additional execution overhead.

#### i. Deposit Collateral into the Clearinghouse & Acquire Leveraged Exposure

* **New Final Step**
* **Purpose**:
  1. **Deposit Collateral**: Once the order is validated and all conditions are met, Avitus **deposits the user’s collateral** into the clearinghouse.
  2. **Leveraged Exposure**: From there, the user gets **leveraged exposure** via the **self‐hedging automated market‐making pool**. In practice, the user is borrowing exposure from the pool which houses the assets provided by liquidity providers (LPs) without owning the underlying asset directly.
  3. **Active Management**:
     * The clearinghouse actively **manages** the position, tracking mark‐to‐market valuations in near‐real‐time.
  4. **Next Section**: Further technical details on how the **clearinghouse** handles collateral, margin requirements can be found in the upcoming “Clearinghouse” section.