Exchange

Implements the majority of the exchange functionality, including balance tracking and AMM pool reserve tracking

Key functions

Deposit

Users must fund their account in the IDEX contracts before they can trade. The deposit acts as escrow which enables the exchange to separate order creation and execution from final settlement. Trading happens in real-time, at the speed of a centralized exchange, with settlement occurring shortly thereafter.

Depositing ETH requires calling depositEtheron the Exchange contract; depositing tokens requires an approve call on the token itself before calling depositTokenByAddress on the Exchange contract.

While depositEther and depositTokenByAddress are functions on the Exchange contract, the funds are ultimately held in the Custodian contract. During a deposit tokens are transferred from the funding wallet to the Custodian, while the Exchange contract's storage tracks wallet asset balances. This separation allows for upgrades without requiring users to migrate funds.

Order

The order function includes all of the data necessary to match and construct a trade. This data includes:

  • Originating wallet

  • Nonce

  • Traded assets

  • Buy or sell

  • Order-type

  • Quantity

  • Price

The constructed order is signed by the private key of the originating wallet. This ensures that only the owner of the funds can authorize their movement. Orders are stored in the off chain order book and, in the event of a matched trade, are executed by IDEX and included in a trade settlement transaction using the trade function.

Order-types

The order function contains additional parameters that enable users to create an array of order-types. Order-types include:

  • Market: Buy/sell funds into existing limit orders on the book

  • Limit: Place a buy/sell order at a specific price

  • Limit maker: Limit order that only executes if you are the maker of the order

  • Stop loss: Taker sell triggered when a specific price level is reached

  • Stop loss limit: Limit sell triggered when a specific price level is reached

  • Take profit: Taker buy triggered when a specific price level is reached

  • Take profit limit: Limit buy triggered when a specific price level is reached

IDEX also supports Time-In-Force constraints that specify the behavior of limit orders upon execution.

  • Good-Til-Canceled (GTC): Limit order stays on the books until matched or cancelled

  • Immediate-Or-Cancel (IOC): Limit order that only takes liquidity from order book and never becomes a resting order

  • Fill-Or-Kill (FOK): Similar to IOC in that FOK only takes liquidity, however the entire quantity must be matched immediately or the order is rejected

The complete details of the order function can be found in the the IDEX github repo. More detailed explanations of the order-types and Time-In-Force settings are available in the IDEX API documentation.

Trade

Order management and trade matching occur off-chain, while trades are ultimately settled on-chain. The primary responsibility of the trade functions is order and trade validation. In the case that IDEX off-chain infrastructure is compromised, the validations ensure that funds can only move in accordance with orders signed by the depositing wallet.

Unlike deposits, trade settlement can only be initiated via a whitelisted Dispatch wallet controlled by IDEX. Because IDEX alone controls dispatch, IDEX’s off-chain components can guarantee the eventual on-chain trade settlement order and thus allow users to trade in real-time without waiting for dispatch or mining. A trade is considered settled when the Exchange contract’s wallet asset balances reflect the new values agreed to in the trade.

There are three different trade settlement functions:

Order book trade: A trade settled between two order book orders with matching terms. This is the traditional type of trade supported by central limit order book exchanges. Order book trades are settled by Exchange’s executeOrderBookTradefunction.

Pool trade: A trade involving an AMM pool and a single taker order. This is similar to a “swap” in standard AMM pools. The taking order adds one reserve to the pool and receives the other reserve in accordance with the terms of the order and constant product formula. Pool trades are settled by Exchange’s executePoolTrade function.

Hybrid trade: A trade involving an AMM pool and two order book orders. In hybrid trades, the pool and one order supply liquidity and one order takes liquidity. Conceptually, the pool fills in liquidity between standing maker orders on the order book. Hybrid trades are settled by Exchange’s executeHybridTradefunction.

More information on the trade functionality can be found in the github repo.

Withdraw

Similar to trade settlement, withdrawals are initiated by users via IDEX’s off-chain components. Calls to the Exchange contract's withdraw function are restricted to the same whitelisted Dispatch wallet. This restriction guarantees that users cannot move their funds before all pending trades have settled and thus supports trading ahead of settlement.

More information on the withdraw functionality can be found in the github repo.

Wallet Exit

The Exchange contract includes a wallet exit mechanism which allows users to withdraw funds in the event IDEX is offline or maliciously censoring withdrawals.

Wallet exits are a two step process to allow the off-chain infrastructure time to register the on-chain activity. Calling exitWallet initiates the exit process, which prevents the wallet from making subsequent deposits, trades, or normal withdrawals. After the chain propagation period expires (~1 hour) the user can initiate the withdrawal on-chain.

More information can be found in the github repo.

Automated Market Maker (AMM)

Add liquidity

IDEX provides two options for users to add liquidity to hybrid liquidity pools.

Deposit Additions: draws funds from a wallet’s Exchange-tracked balances to add to a liquidity pool’s reserves.

Wallet Additions: uses a multi-step process to draw funds directly from wallet balances to add to a hybrid liquidity pool’s reserves.

Remove liquidity

IDEX provides two options for users to remove liquidity from hybrid liquidity pools

Deposit Removals: LP tokens are held in the user's wallet outside of IDEX and removes funds from the pool via Exchange’s executeRemoveLiquidity.

Wallet Removals: LP tokens are held in the user's IDEX balance and removes funds from the pool via Exchange’s removeLiquidity.

Structurally, both approaches work similarly to Deposit Additions and Wallet Additions. There is also a provision in the wallet exit mechanism to prevent liquidity removal censorship by IDEX.

LP tokens

Creating or migrating a new hybrid liquidity pool deploys a new ERC-20 contract representing Liquidity Provider ownership. Similar to the Uniswap Pair LP token, the LiquidityProviderToken is a simple and standard token contract that allows hybrid liquidity pool ownership to be integrated elsewhere in the DeFi ecosystem.

New additions to a hybrid liquidity pool mint new LiquidityProviderTokens representing ownership shares, and burning LiquidityProviderTokens redeems pool ownership shares for the underlying reserve tokens.

Last updated