How It Works
Last updated
Last updated
Content Out of Date
This content is not maintained and refers to an out-of-date version of Perpetual Protocol.
For the latest documentation, see https://docs.perp.com
With this document we aim to go over from a high level the technical details of the protocol and how it currently works.
Before starting we need to go through some basic concepts.
Vault: when we refer to the vault in the future diagrams, we refer to the contract in which all collateral is stored. All funds are commingled in this vault (i.e. it contains all of the margin that is used to open positions).
Clearing House: the clearing house is the contract that handles all the trading, liquidations and leverage.
Virtual AMM: is the V1 design where we utilised the xyk model popularised by Uniswap’s V2 (see https://docs.uniswap.org/protocol/V2/concepts/protocol-overview/how-uniswap-works for more details). It’s best to think of this as a pricing engine where if you put in one token you’ll receive another.
For Perp v2, we utilise the Uniswap V3 implementation. Conceptually things will still work the same as v1, i.e., the clearing house mints virtual tokens and swaps it into our virtual AMM. However, given that we now need to interact with Uni V3, the major update is that we now need to place these virtual tokens on the various ranges.
A virtual token is simply a synthetic token with no intrinsic value and is used for accounting purposes. We prefix it with a v - for the following examples vETH will be virtual ETH and vUSDC will be virtual USDC.
The clearing house does the following when opening a position:
Mint virtual tokens - in our scenario Alice is going long and so we mint vUSDC, if she were to short then we would mint vETH.
Store a cost basis - the cost basis is an important concept for calculating what Alice’s actual profit or loss is. We will illustrate this next.
Swap tokens - the clearing house swaps the tokens with the tokens that currently sit in the active tick and receives the opposite token.
To summarise this step, Alice currently has:
1.96 vETH (managed by the Clearing House).
Cost basis of 200 vUSDC.
100 USDC in the Vault.
Let’s assume that some time has passed since Alice opened her long position and now she wants to close her position. We’ll also assume that the price of ETH has gone up.
The beginning of this scenario is the same as previously, she takes the vETH she holds and deposits it into the AMM and receives vUSDC back. We then derive what PnL that Alice should receive - this is calculated as the vUSDC she now holds less the cost basis that she had in vUSDC. Finally, the vault sends back to Alice her collateral plus her PnL:
PnL = vUSDC - cost basis = 220 - 200 = 20.
Alice receives = collateral + PnL = 100 + 20 = 120.
Let’s assume that some time has passed since Alice opened her long position and now she wants to close her position. We’ll also assume that the price of ETH has gone up.
The beginning of this scenario is the same as previously, she takes the vETH she holds and deposits it into the AMM and receives vUSDC back. We then derive what PnL that Alice should receive - this is calculated as the vUSDC she now holds less the cost basis that she had in vUSDC. Finally, the vault sends back to Alice her collateral plus her PnL:
PnL = vUSDC - cost basis = 220 - 200 = 20.
Alice receives = collateral + PnL = 100 + 20 = 120.
V2 introduces the concept of a maker who will be providing liquidity. Similar to Uniswap V3, a market maker is faced with 3 scenarios:
Place a range order below the current tick: the market maker is willing to buy the token.
Place a range order around the current tick: the market maker in this scenario is willing to both buy and sell the token.
Place a range order above the current price: the market maker is willing to sell the token.
We’ll illustrate these with the following scenarios.
The very first step of this scenario is similar to the previous ones. Let’s take Alice who is looking to provide 100 USDC liquidity with 2x leverage above the range:
The clearing house will mint vETH and place this vETH into the Uni v3 AMM. Let’s assume for simplicity that Alice is the only provider of liquidity and later Bob comes in as a taker and goes long 1.96 vETH. He deposits 200 vUSDC into the pool and receives 1.96 vETH. Alice now only has 0.04 vETH but holds 200 vUSDC.
Assume in the following scenario for simplicity that Alice is the only maker in this active tick. For regular scenarios Alice’s positions would move pro-rata with the other makers.
It’s important to note that at this point Alice has a position of -1.96 ETH (as she owns 0.04 vETH but has a cost basis of 2 vETH). She can continue to provide liquidity and have changing amounts of vETH and vUSDC depending on how traders interact with her pool.
There is also an additional option here for individuals who may not want to market make but simply place a limit order. Let’s say Alice only wanted to place a limit order to sell ETH but didn’t want to market make. The additional step that would occur here is after her order is filled, she would remove her vETH and vUSDC from the Uniswap v3 pool - meaning that she maintains her position but is no longer market making.
Note: This scenario can be used for adding liquidity below the mark price as well.
Adding liquidity around the mark price is the same as Scenario 2 but with a couple of small modifications.
As Alice is willing to both buy and sell in this scenario, the Clearing House mints both vETH and vUSDC. Note that even though Alice still wants to leverage 2x, we don’t mint 200 vETH as in the previous scenario but mint 100 vUSDC and 1vETH so that the numbers add up (assuming ETH = $100, then it will be minting 100 vUSDC and 100 USDC worth of vETH = $200 of USDC equivalent, or 2x the $100 deposit).
