# SIP-267: Direct Integration

Author Implemented Governance Ethereum & Optimism meb (@barrasso) TBD Loading status... 2022-07-28

## Simple Summary

This SIP proposes to implement a direct integration contract that allows integrators to tap into Synthetix's exchange functionalities with a customized set parameters.

## Abstract

The direct integration contract allows the Synthetix protocol to create a unique environment for integrators, allowing access to Synthetix's exchange functionalities with custom parameters that fit individual use cases. Although this sip is built on top of v2x, it fits in the spirit of what we should expect with Synthetix v3, where different markets can be created and tailored for specific offerings and use cases.

## Motivation

There are a number of benefits to the Synthetix protocol from having a direct integration path with partners:

• Lyra's uses Synthetix's exchange functionalities in to offer it's users options trading venue with an integrated amm model which embeds slippage.
• Curve also provides Synthetix with pools that allow for cross-asset swaps with built-in slippage.

Both these protocols have a significantly reduced chance of latency attacks, due to their protocol's incorporation of slippage constraining toxic flow to a certain extent. Providing these special DirectIntegrationManager routes into Synthetix's exchange functionalities isolates the trade flow to a certain extent and allows us to offer more competitive offerings via lower fees.

## Direct Integration Workflow

The workflow of adding a directing integration external contract (or EOA) to interact with Synthetix exchange functions is as follows:

• The entity submits a SIP specifying the motivation behind the integration, the benefits to and risks undertaken by SNX stakers. The SIP should include the following:
• The address of the contract (or EOA). In case the address is yet to be available, the SIP needs to be amended at later date, and the amendment approved by the Spartan Council.
• The list of currency keys on which to incorporate overrides
• The parameter overrides involved. If the default parameters are to be used, then no override needs to be specified in the SIP.
• The custodian of the integration (the person/entity responsible for seen the process through) needs to find the necessary resource to create a designated contract that would interact with synthetix at the over-ridden environment. The contract is submitted to Synthetix's auditors and Core-Contributors for review and if no objection from auditors/Core-Contributors and all the previous requirements are met (in terms of gathering the necessary vote), the contract is incorporated into the DirectIntegrationManager contract with the specified parameter overrides.

Alternatively, the SC can designate an EOA which can directly interact with synthetix at the over-ridden parameters, this still requires the normal SIP governance submission and approval. Obviously, there are more risks to the protocol involved when undertaking this expedited approach.

## Specification

### Technical Specification

The DirectIntegrationManager contract allows the Spartan Council to approve an address (contract or EOA), to interact with the Synthetix's core exchange functionalities at specified parameters. If parameters specified under setExchangeParameters are set to 0 or the 0x address, then the default parameters configuration would be used. Below are the functionalities configurable within the DirectIntegrationManager contract:

#### Set Exchange Parameters

setExchangeParameters allows the protocol to specify the parameters of the exchange functionalities that go through the DirectIntegrationManager contract. It takes in the following structure:

• The address of the msg.sender which is allowed to interact with synthetix contracts with specialized parameters
• The currencyKey on which parameter overrides are implemented
• The list of override values that governs the environment under which a specified address is able to interact with synthetix contracts:
• dexPriceAggregator
• atomicEquivalentForDexPricing
• atomicExchangeFeeRate
• atomicTwapWindow
• atomicMaxVolumePerBlock
• atomicVolatilityConsiderationWindow
• atomicVolatilityUpdateThreshold
• exchangeFeeRate
• exchangeMaxDynamicFee
• exchangeDynamicFeeRounds
• exchangeDynamicFeeThreshold
• exchangeDynamicFeeWeightDecay

Few things worth noting:

• The parameters are applicable on the sourceCurrencyKey of a trade, for example setting atomicMaxVolumePerBlock to 10m$on sUSD and 20m$ on sETH and someone does a trade from sUSD to sETH, then the maxVolumePerBlock applicable on this trade would be that of sUSD.
• The parameters are applicable on both the source and destination currency keys, for cases involving dynamic fees and fees for exchange, since the fee levied is basically the sum of the fees assigned to the source and destination legs of the transaction.
• The view functions effectiveAtomicValueAndRates, getAmountForAtomicExchange and getAmountsForExchange behave based on the address calling them. Hence the returned values reflect the environment assigned to an integration address.

#### Get Exchange Parameters

This function return the set of settings configured for a given address and currencyKey combination. If an address / currencyKey combination is not configured with any overrides, this would just return the global parameters from system settings. Any overrides would be applied if applicable. Below is what can be expected when getExchangeParameters is called with the 0x address and sUSD as the integration currencyKey:

{'currencyKey': 'sUSD',
'dexPriceAggregator': '0xf120F029Ac143633d1942e48aE2Dfa2036C5786c',
'atomicEquivalentForDexPricing': '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
'atomicExchangeFeeRate': 0,
'atomicTwapWindow': 1800,
'atomicMaxVolumePerBlock': 100000000000000000000000,
'atomicVolatilityConsiderationWindow': 0,
'atomicVolatilityUpdateThreshold': 0,
'exchangeFeeRate': 0,
'exchangeMaxDynamicFee': 50000000000000000,
'exchangeDynamicFeeRounds': 0,
'exchangeDynamicFeeThreshold': 4000000000000000,
'exchangeDynamicFeeWeightDecay': 900000000000000000}


#### Resume / Pause Integration

The SystemStatus would include resumeDirectIntegration and suspendDirectIntegration functions, that take in the external contract address and allows pdao to suspend and resume interaction with external contracts.

### Other Important Considerations:

In future SIP's, such as SIP-272, the direct integration universe would need to be updated as to incorporate new parameters and functions configured into synthetix's systems.

### Test Cases

• Setting a Direct Integration (DI) account to have 40 bp sETH atomic exchange fees and 10 bp sUSD fees, while standard fees being 10 bp sETH and 5 bp on sUSD
• When the DI account attempts to trade atomically 100 sUSD to sETH
• ✅ Then it succeeds and the following take place:
• 50 bp fees are levied on the trade
• When the a non-DI account attempts the same trade atomically 100 sUSD to sETH
• ✅ Then it succeeds and the following take place:
• 15 bp fees are levied on the trade
• Setting a Direct Integration (DI) account to have 0 bp sEUR atomic exchange fees and 30 bp sUSD fees, while standard fees being 15 bp sEUR and 5 bp on sUSD
• When the DI account attempts to trade atomically 100 sUSD to sETH
• ✅ Then it succeeds and the following take place:
• 45 bp fees are levied on the trade, being the DI fees on sUSD and standard fees on EUR
• Setting a Direct Integration (DI) maxAtomicVolumePerBlock to 2000$per block on sUSD and 1000$ on sETH while the standard parameters being 100$• When a non DI account attempts to trade 101 sUSD to sETH • ❌ Then transaction reverts, due to exceeding max volume per block • When an DI account attempts to trade 50 sUSD to sETH and subsequently in the same block a non-DI account trades 50 sUSD to sETH • ✅ Then both transactions succeed • When an DI account attempts to trade 2000 sUSD to sETH and subsequently in the same block a non-DI account trades 100 sUSD to sETH • ✅ Then the DI account transaction succeeds • ❌ Then the non-DI account transaction reverts • When an DI account attempts to trade 2000 sUSD to sETH and subsequently in the same block a DI account trades 1 sETH to sUSD • ✅ Then the DI sUSD to sETH trades succeeds • ❌ Then the DI sETH to sUSD trade reverts • Setting the DI account to route through 30 bp uni pools while the non-DI accounts routes through 5 bp pools • When the DI account trades atomically • ✅ Then the tx succeeds and the trade is routed through 30 bp uni pool • When a non-DI account trades atomically • ✅ Then the tx succeeds and the trade is routed through the 5 bp uni pool • Setting the base exchange fee on a DI account to 50 bp on sETH and 10 bp on sUSD, while the standard fees are 20 bp and 5 bp • Setting the DI and standard setExchangeDynamicFeeRounds to 0 • When the DI account trades with the standard exchange functionality 100 sUSD to sETH • ✅ Then the tx succeeds and 60 bp fees are levied • When a non-DI account trades with the standard exchange functionality 100 sUSD to sETH • ✅ Then the tx succeeds and 25 bp fees are levied • Setting the base exchange fee 0 bp on sETH and 0 bp on sUSD • Setting the DI dynamic fee parameters as follows a) setExchangeDynamicFeeWeightDecay to 0.8 b) setExchangeDynamicFeeThreshold to 0.1% c) setExchangeDynamicFeeRounds to 5 d) setExchangeMaxDynamicFee to 10% e) update the ETH price print to 1200$ / 1220$/ 1250$ / 1240$/ 1230$

• While the standard non DI setExchangeDynamicFeeRounds is 0.

• When the DI account trades with the standard exchange functionality 100 sUSD to sETH
• ✅ Then the tx succeeds and 3.58% fees are levied
• When the non-Di accounts trades with the standard exchange function 100 sUSD to sETH
• ✅ Then the tx succeeds and no fees are levied
• Setting the standard dynamic fee parameters as follows

a) setExchangeDynamicFeeWeightDecay to 0.5

b) setExchangeDynamicFeeThreshold to 0.2%

c) setExchangeDynamicFeeRounds to 4

d) setExchangeMaxDynamicFee to 10%

e) update the ETH price print to 1200$/ 1220$ / 1250$/ 1240$ / 1230\$

• While the DI setExchangeDynamicFeeRounds is 1.

• When the non-DI account trades with the standard exchange functionality 100 sUSD to sETH
• ✅ Then the tx succeeds and 1.65% fees are levied
• When the Di accounts trades with the standard exchange function 100 sUSD to sETH
• ✅ Then the tx succeeds and no fees are levied
• Setting a Direct Integration (DI) with a atomicVolatilityUpdateThreshold of 10 updates on sETH and atomicConsiderationWindow being set to 60 seconds. The standard parameters being 15 updates and 60 seconds.
• When 10 oracle updates are pushed in the span of few seconds and DI and an nonDI account attempts to trade 1 sUSD to sETH
• ✅ Then the non-DI account transaction succeeds

• ❌ Then the DI account transaction reverts

### Configurable Values (Via SCCP)

Below is a list of values configurable:

• setExchangeParameters: This will allow the protocol to configure integrations, requires a SIP presentation.
• suspendDirectIntegration and resumeDirectIntegration can be called by pDAO to cease and resume interaction on the DirectIntegrationManager contract. Note that suspendDirectIntegration can be called by pdao in case of emergencies, but resumeDirectIntegration requires a SCCP.

Copyright and related rights waived via CC0.