Synthetix Docs
V2 User Docs
  • User Docs
  • Synthetix Exchange
  • Leveraged Tokens
  • For Developers
V2 User Docs
  • Synthetix Protocol
    • Welcome to Synthetix
    • The Synthetix Protocol
      • Synthetix Token (SNX)
      • The Role of Stakers
      • Oracles
      • Synthetix Litepaper
    • Synthetic Assets
      • Perpetual Futures
      • Spot Synths
  • Staking
    • Depositing to the 420 Pool
    • Current Protocol Parameters
    • Staking Guide (Nearing Deprecation)
      • Steps for Staking SNX (via Minting)
      • Steps for Unstaking SNX (via Burning)
      • Steps for Claiming Rewards
      • Automating Staking, Claiming, Burning, and Minting
        • Legacy Automated Minting & Claiming
      • Understanding the Collateralization Ratio
      • Understanding Debt, Minting, and Burning
      • Simplified Debt Hedging
      • Escrow and Vesting
      • Liquidations
    • Staking FAQ
    • Bridging sUSD
  • DAO
    • Governance Framework
      • Synthetix Improvement Proposals (SIPs)
      • Synthetix Configuration Change Proposal (SCCPs)
      • Spartan Council
      • Core Contributors
      • Staker
    • Elections and Voting
      • Voting with a Gnosis Safe
    • How to write SIP/SCCPs
  • V3
    • Synthetix v3
    • Build on v3
  • Synthetix Ecosystem
    • Built on Synthetix
      • Kwenta - Spot and Perps
      • Decentrex - Perps
      • Lyra - Options
      • Polynomial - Perps and Option Vaults
      • 1inch/Curve - Atomic Swaps
    • Community Infrastructure
    • Ecosystem Operations
  • integrations
    • Perps Integration Guide
      • Introduction
      • Optimistic Sepolia Testnet Tokens
      • Technical Integration
      • Perps Subgraph
      • General FAQ
      • Tracking Codes
      • Perps Keeper
      • Liquidations
      • Useful Links
      • Migration Guides
        • PerpsV2 Mintaka -> Almach
        • FuturesV1 -> PerpsV2 (Mintaka)
    • Contract Addresses
    • Releases
  • Terms of Use
  • Brand Assets
    • Design Resources
Powered by GitBook
On this page
  • Preamble
  • Contracts
  • Open/Close a Position
  • Funding Rates/Velocity
  • Price Impact & Protection
  • Trade Simulations
  • Miscellaneous
  • Cross-side Maker/Taker Fees
  • Native vs. USD Denomination
  • Tracking Codes
  • Market Keys
  1. integrations
  2. Perps Integration Guide
  3. Migration Guides

FuturesV1 -> PerpsV2 (Mintaka)

This is the migration guide from FuturesV1 to V2

PreviousPerpsV2 Mintaka -> AlmachNextDesign Resources

Preamble

Synthetix FuturesV1 (or Futures as it was also called) from March 2022 is coming to an end (December 2022) and replaced with the long anticipated Perps V2. This document aims to provide a guide on differences between the two versions and how protocols and dApps can migrate their clients to use Perps V2.

Contracts

All existing FuturesV2 haven't changed (except the FuturesMarketManager). All new additions reside in PerpsV2 contracts. You can find them in the same location as all other Synthetix contracts . Take a look at the for more details on the structure.

Open/Close a Position

FuturesV1 had two methods of opening a new position: atomically and next-price. Atomic orders remain the same however next-price has been renamed to delayed orders. For the full details refer to the PRs available below:

Funding Rates/Velocity

Funding has changed. In FuturesV1, they were instantaneous but in PerpsV2, funding rate floats and drifts in one direction or the other based on skew. Lots of internal implications but minimal external visible changes for frontends. You can read through how it all works here:

For more details on funding and velocity, please refer to the full integration guide.

FuturesV1 had funding rate signs inverted. This is no longer the chance in PerpsV2 and the .neg is not necessary. Additionally, due to the floating funding rate, you can calculate the hourly funding rate by just .div(24).

Price Impact & Protection

Orders in PerpsV2 incur price impact. This was previously not the case in Perps v1beta. In short, if the position’s size increases/expands the market skew, they are charged a premium in the form of a higher fill price but if the skew is decreases/contracts, a discount is applied. This happens automatically when a trade is made and it affects both spot and delayed orders.

We provide a fillPrice function to see the impact of size before a trade is executed:

function fillPrice(int size) external view returns (uint price, bool invalid);

It may be beneficial to display the fill price as a result of size impact somewhere in the UI so traders know how their position size will impact their trade.

In short, it’s effectively just:

fill_price = (
  (price * (1 + skew / skew_scale)) + (price * (1 + (skew + pos_size) / skew_scale))
) / 2

Trade Simulations

postTradeDetails still remains but added is a tradePrice argument to specify an allowing a simulation to occur with an arbitrary price.

function postTradeDetails(
  int sizeDelta,
  uint tradePrice,
  address sender
)
  external
  view
  returns (
    uint margin,
    int size,
    uint price,
    uint liqPrice,
    uint fee,
    IPerpsV2MarketBaseTypes.Status status
  );

Miscellaneous

Cross-side Maker/Taker Fees

Traders are charged makerFee if the size of their order reduces the market skew and a takerFee if the order increases the skew. However, in certain situations, an order can decrease and increase the skew. In these scenarios, the proportion of size that decreases the skew should be charged a makerFee and the remaining, a takerFee.

This is a bug in Perps v1beta that has now been fixed to be such that if the position flips the skew then maker/taker fees are charged proportionately. For example:

You can use the same orderFees view to grab the fees associated with an order. There should be no integration impact, just something to be aware of.

function orderFee(int sizeDelta) external view returns (uint fee, bool invalid);

Native vs. USD Denomination

Internally within market contracts, parameters for OI caps and skewScale are denominated in USD. For example:

{
  "maxMarketValueUSD": 4000000,
  "skewScaleUSD": 300000000
}

The above signals that the max OI cap for either side is 4M USD and the skewScale to convert market skew into a fractional is 300M USD. This is no longer the case. Instead, we use the market asset as the denominator. So, if this market was the ETH then:

{
  "maxMarketValue": 20000,
  "skewScale": 1000000
}

So if the price of ETH was $1200 then 20,000 maxMarketValue would be 24M OI cap.

Externally, this may/may not impact integration depending on what data you want to display on the UI. Something to be aware of as traders may hit OI caps for e.g. and wonder why.

Tracking Codes

They remain unchanged. Tracking codes sent in FuturesV1 will still be emitted in events in PerpsV2. Please continue to use the same tracking code unless otherwise specified.

Market Keys

We’ve changed our marketKey for PerpsV2 markets:

// Previous (FuturesV1)
sBTC
sETH
sXXX

// Now (PerpsV2)
sBTCPERP
sETHPERP
sXXXPERP

PerpsV2 also introduces a new method of opening orders via off-chain delayed orders. Please refer to the complete for details.

This is documented in . You can read the full details in the perps integration guide.

perps integration guide
SIP-279
here
Perps Integration Guide
Feature/time based order by davidvuong · Pull Request #1899 · Synthetixio/synthetixGitHub
New delayed orders
SIP-279: Perps v2
Official SIP-279
GitHub - davidvuong/perpsv2-funding: Python impl of Synthetix Perps V2 (SIP-279) funding model simGitHub
Python sample implementation
Feature/cross side order fees by davidvuong · Pull Request #1906 · Synthetixio/synthetixGitHub
PR for cross-side maker/taker fees for details
Logo
Logo
Logo
Logo