Skip to content

Integrations Overview

Who this guide is for

This is a series of guides for developers looking into integrate with Synthetix protocol. Please read the below thoroughly and ask for help in the #dev-portal channel of our Discord.

If you're looking to integrate Synthetix into your dApps and scripts, please reference the libraries section in addition to the data guide.

Synthetix provides the following integration guides:

  1. Trading
  2. Staking
  3. Data
  4. Delegating
  5. Depot: ETH/sUSD
  6. Testnets
  7. ENS Support

The additional contextual information below is also helpful as a companion reference to the guides provided.

Address Resolver

In our Achernar release, we introduced a new feature called the AddressResolver contract.

In short, the AddressResolver allows any referencing contract to have access to a number of key contract - in particular the underlying Synthetix, FeePool, SynthsUSD and SynthsETH contracts. There are plans in the near future to add our proxies as well.

The ReadProxyAddressResolver is our readable AddressResolver behind a proxy that won't change, so it's safe to use in your code (it only allows calls that do not mutate state). We have one for each testnet and mainnet up on the addresses page.

For guides on how to use the AddressResolver in Solidity, see our trading section.

Proxies

Synthetix makes extensive use of the proxy pattern. This allows users and integrated systems to refer to immutable proxy addresses while the underlying functionality is passed through to the target or underlying contracts which can be updated by an owner function. This allows for fast iteration of the Synthetix ecosystem at the cost of trust in the protocol.

The transaction's to parameter can be to either the proxy or the underlying, however two things are worth noting: the underlying is subject to change (and does most releases); and the events will always be emitted on the proxy, regardless of the to parameter in the transaction.

For best results, always interact with the proxy using the ABI of the underlying.

Decentralize All the Things

In order for Synthetix to become a fully decentralized protocol, these upgradable proxy contracts need more oversight and constraint. Please read our blogpost for the path towards full decentralization and how the Proxy architecture is impacted: https://blog.synthetix.io/transition-to-decentralised-governance/ (see Protocol Changes)

As of this moment, the following contracts are behind proxies:

  • FeePool is behind ProxyFeePool
  • Synthetix is behind both ProxyERC20 and ProxySynthetix (deprecated, see notice below).
  • SynthsUSD is behind both ProxyERC20sUSD and ProxysUSD (deprecated)
  • All remaining synths are also behind a Proxy, all of which are the newer ProxyERC20 pattern. e.g. ProxysETH, ProxyiBTC, etc.

Proxy Deprecation

Why are we deprecating proxies?

The current proxies have been marked deprecated:

  • Synthetix (aka ProxySynthetix at 0xC011A72400E58ecD99Ee497CF89E3775d4bd732F) and
  • sUSD (aka ProxysUSD at 0x57Ab1E02fEE23774580C119740129eAC7081e9D3)

The Synthetix proxies use the CALL pattern and set messageSender on the target for any request (see here). This mutation inside functions that are marked view - such as balanceOf, break ERC20 interface conventions, and thus fail.

In their stead we have new integration proxies in place, used by both Uniswap and Kyber. The new integration proxies are fully ERC20 compliant and explictly call through to the target for all ERC20 functions (see ProxyERC20.sol).

If you are planning any integration with Synthetix, it is recommended that you use the newer proxies:

  • Synthetix (aka ProxyERC20 at 0xC011a73ee8576Fb46F5E1c5751cA3B9Fe0af2a6F) and
  • sUSD (aka ProxyERC20sUSD at 0x57Ab1ec28D129707052df4dF418D58a2D46d5f51)

That said however, both are functioning side by side while we transition over.

One note of caution: the events from the underlying contracts - Synthetix and Synth are still emitted on the currently deprecated proxy contracts. Indeed, SynthetixJs still use the deprecated proxies for this reason (see Synthetix.js). Once we migrate to the new proxies, the events will be emitted on the integration proxies and the deprecated ones will be removed entirely.

  1. Phase 1

    Prior to May 10, 2020, both proxies for Synthetix and SynthsUSD will function. Our dApps and integrations will call and transact using the deprecated proxies, and all events emitted will be on the deprecated proxy.

  2. Phase 2

    Time converter at worldtimebuddy.com

    On May 10, 2020 11pm UTC, we will switch the proxy and integrationProxy properties of Synthetix and our SynthsUSD contracts. We will then update our dApps and integrations (including synthetix-js) to use the addresses of the new proxies for all calls and transactions. All events emitted will now be on the new ERC20 proxies. However, the deprecated proxies will continue to work until Phase 3.

  3. Phase 3 (Current)

    Updated timeline to July 31

    Due to some third party project requirements, we've decided to push back Phase 3 to the end of July, 2020. Please reach out to us in Discord channel #dev-portal if you need more time.

    Time converter at worldtimebuddy.com

    On July 31, 2020 11pm UTC, we will set the integrationProxy property from Synthetix and SynthsUSD to 0x0, meaning that no more incoming transactions on 0xC011A72400E58ecD99Ee497CF89E3775d4bd732F (ProxySynthetix) or 0x57Ab1E02fEE23774580C119740129eAC7081e9D3 (ProxysUSD) will work. These will fail as the target contracts they use will no longer accept incoming requests from them. We will update our ProxySynthetix and ProxysUSD labels to point to the new ERC20 proxies (in our docs and in our contract-linker utility).

  4. Phase 4: We will rename our proxy labels to all be ProxyERC20<name> where <name> is either Synthetix or the name of the synth (eg. sUSD, iETH, etc). We will also remove the integrationProxy property from Proxyable.sol.

Example Scenarios:

Exchanging via Synthetix

Let's say you want to exchange 100 sUSD for sETH:

  1. Phase 1 (prior to May 10, 2020):

    • You can invoke exchange(sUSD, 100e18, sETH) on either ProxySynthetix (0xC011a72) or ProxyERC20 (0xC011a73).
    • On success, SynthExchange will be emitted on ProxySynthetix (0xC011a72) regardless of which proxy you used to transact.

  2. Phase 2 (between May 10 - May 30, 2020):

    • You can still invoke exchange(sUSD, 100e18, sETH) on either ProxySynthetix (0xC011a72) or ProxyERC20 (0xC011a73), however you are strongly recommended to migrate to using ProxyERC20.
    • On success, SynthExchange will be emitted on ProxyERC20 (0xC011a73) regardless of which proxy you used to transact.

  3. Phase 3 (From May 30, 2020):

    • You can only invoke exchange(sUSD, 100e18, sETH) on ProxyERC20 (0xC011a73), the old proxy address will fail.
    • On success, SynthExchange will be emitted on ProxyERC20 (0xC011a73).

Transferring sUSD

Or say you want to transfer 5 sUSD to user

  1. Phase 1 (prior to May 10, 2020):

    • You can invoke transfer(user, 5e18) on either ProxysUSD (0x57Ab1E0) or ProxyERC20sUSD (0x57Ab1ec).
    • On success, Transfer will be emitted on ProxysUSD (0x57Ab1E0) regardless of which proxy you used to transact.

  2. Phase 2 (between May 10 - May 30, 2020):

    • You can still invoke transfer(user, 5e18) on either ProxysUSD (0x57Ab1E0) or ProxyERC20sUSD (0x57Ab1ec), however you are strongly recommended to migrate to using ProxyERC20sUSD.
    • On success, Transfer will be emitted on ProxysUSD (0x57Ab1E0) regardless of which proxy you used to transact.

  3. Phase 3 (From May 30, 2020):

    • You can only invoke transfer(user, 5e18) on ProxyERC20sUSD (0x57Ab1ec), the old proxy will fail.
    • On success, Transfer will be emitted on ProxyERC20sUSD (0x57Ab1ec).

Fee Reclamation and Atomicity of Exchanges

In our Achernar release, we introduced Fee Reclamation (SIP-37). The major implication here is that if you invoke exchange(src, amount, dest) in your smart contracts, you cannot atomically invoke dest.transfer() or exchange(dest, ..., ...) - both will fail until a waiting period expires.

You can use Exchanger.maxSecsLeftInWaitingPeriod() to check how many seconds are left in the waiting period for that dest synth. Once it's 0, exchanges of the dest synth will automatically settle any rebates or reclaims. However after the waiting period expires, dest.transfer() will fail regardless if there are any exchanges awaiting settlement. To circumvent this, integrators are encouraged to use transferAndSettle or transferFromAndSettle. Alternatively, Exchanger.settle() can be invoked directly prior to a transfer or transferFrom.