SIP-299: Minor upgrades to v2x to support V3 Migration

NetworkEthereum & Optimism
ImplementorDaniel Beal (@dbeal-eth), MEB (@barrasso)
ProposalLoading status...

Simple Summary

Grant a few special permissions to the LegacyMarket contract, the facilitator of the migration of collateral and debt to Synthetix V3.


V3 is imminent! To allow for the smoothest transition possible, a special V3 market called the LegacyMarket has been prepared. It allows for users to migrate their collateral and/or redeem their sUSD to their V3 counterparts, while allowing for V2x to continue


See SIP-306 for the motivation behind this migration plan.



The LegacyMarket contract contains a few methods to facilitate transition:

function migrate(uint newAccountId)

Can be called by any staking account to atomically move their position to V3. This consists of the following broad steps:

  • Transfer all SNX (requires special permission) to LegacyMarket
  • Transfer all debt shares in the user's account to the LegacyMarket contract where they will stay
  • Wrap all SNX collected from the user into a newly created user account with ID newAccountId. Invest in the spartan council fund, which invests in the LegacyMarket
  • Associate the specific debt for the user to their account on V3

NOTE: the user still needs to approve() the LegacyMarket for their whole balance of SNX before executing.

function migrateOnBehalf(address target)

Allows for owner to force migrate any. Functions the same as migrate().

function convertUSD(uint amount)

Called by any user who owns amount sUSD to convert (burn) amount sUSD, and mint an equivalent quantity of V3 USD.

This function effectively provides a mechanism of V2x -> v3 debt migration.

NOTE: the user still needs to approve() LegacyMarket to spend their sUSD.

Changes to v2x

In order to support the above functionality, the following changes are required in V2x:

  • allow LegacyMarket to unconditinoally transfer SNX, even if the user has debt in their account (technically not required but would be helpful)
  • prevent any liquidations on V2x once LegacyMarket address is set
    • the idea is users can still be liquidated on V3, and they should be migrated first to allow this to happen.

It is possible and reccomended that these changes be implemented and deployed before V3 is actually deployed. Once V3 is deployed, these special permissions can be granted by simply setting AddressResolver entry for LegacyMarket to the permissioned address.

All of the smart contracts pertaining to synths, perps, wrappers, loans, and shorts can be left as-is. They can be deprecated and/or migrated in the future.

Test Cases

Relevant tests will be developed during implementation.

Configurable Values (Via SCCP)

  • AddressResolver.importAddresses(['LegacyMarket'], ['<insert address>']): initially 0 address, later updated to v3 LegacyMarket contract address with SCCP approval to kick off migration
  • SynthetixDebtShare.setAuthorizedBroker('<insert address>'): should also be updated to authorize the LegacyMarket to transfer debt shares to itself (no code update required, just documenting later need to set this value).

Copyright and related rights waived via CC0.