ExchangeRates

Description

This contract stores the latest Synth exchange rates. These rates are set by an oracle, which updates this contract every three minutes with any prices that have moved sufficiently. Once set, these prices are available for any contract in the Synthetix system to query. Prices which have not been updated recently enough are considered stale; Synthetix functionality using stale prices does not operate. All rates are denominated in terms of sUSD, so the price of sUSD is always $1.00, and is never stale.

The ExchangeRates contract is also responsible for computing the prices of various derived synths. In particular, the behaviour of inverse synths is defined here. These are derivative synths whose price varies inversely with the price of an underlying asset.

This contract interacts with the oracle's frontrunning protection, which is partially described in SIP-6 and SIP-7.

This does not turn off any functionality in the exchange rate contract, but is used by Synthetix to disable currency exchanges while prices are being updated to protect against oracle front running. The lock is released when rate updates have completed.

Source: contracts/ExchangeRates.sol

Architecture

Libraries

• SafeMath for uint
• SafeDecimalMath for uint

Inheritance Graph

graph TD ExchangeRates[ExchangeRates] --> Owned[Owned] ExchangeRates[ExchangeRates] --> MixinSystemSettings[MixinSystemSettings] MixinSystemSettings[MixinSystemSettings] --> MixinResolver[MixinResolver]

Related Contracts

Details

• oracle: This address is not actually a contract, but it is the source of prices for this contract.
• Aggregators: These are a collection of decentralized pricing networks that collect and aggregate results from a network of oracles.
• PurgeableSynth: exchange rates are used to determine if the total token value is below the purge threshold.
• Synthetix: the value of tokens is used to in order to facilitate exchange between them, and to ensure exchanges cannot occur while price updates and being made or if a particular exchange rate is stale.

Variables

aggregatorKeys

_Source

A list of the keys of currencies with a decentralized aggregated pricing network.

Type: bytes32[]

aggregators

_Source

For each currency with a decentralized aggregated pricing network, return the Aggregation contract address.

Type: mapping(bytes32 => contract AggregatorV2V3Interface)

currencyKeyDecimals

_Source

Type: mapping(bytes32 => uint8)

currentRoundForRate

_Source

Type: mapping(bytes32 => uint256)

inversePricing

_Source

For each currency with an inverse index, keep the necessary InversePricing information to maintain the index.

Type: mapping(bytes32 => struct IExchangeRates.InversePricing)

invertedKeys

_Source

A list of the keys of currencies with an inverted index.

Type: bytes32[]

oracle

_Source

The address which is permitted to push rate updates to the contract.

Type: address

roundFrozen

_Source

Type: mapping(bytes32 => uint256)

Constructor

constructor

_Source

Initialises the oracle address and initial currency prices, along with the inherited SelfDestructible instance.

Details

Signature

(address _owner, address _oracle, address _resolver, bytes32[] _currencyKeys, uint256[] _newRates)

Visibility

public

State Mutability

nonpayable

Requires

• require(..., Currency key length and rate length must match.)

Views

aggregatorWarningFlags

_Source

Details

Signature

aggregatorWarningFlags() returns (address)

Visibility

external

State Mutability

view

anyRateIsInvalid

_Source

Details

Signature

anyRateIsInvalid(bytes32[] currencyKeys) returns (bool)

Visibility

external

State Mutability

view

canFreezeRate

_Source

Details

Signature

canFreezeRate(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

currenciesUsingAggregator

_Source

Details

Signature

currenciesUsingAggregator(address aggregator) returns (bytes32[])

Visibility

external

State Mutability

view

effectiveValue

_Source

Given a quantity of a source currency, returns a quantity of a destination currency that is of equivalent value at current exchange rates, if those rates are fresh.

The effective value is computed as a simple ratio of the prices of the currencies concerned. That is, to convert a quantity $Q_A$ of currency $A$ to currency $B$ at prices $\pi_A$ and $\pi_B$, the quantity $Q_B$ received is:

$$Q_B = Q_A \frac{\pi_A}{\pi_B}$$

This computation is simple because all fractional quantities in the Synthetix system except for the debt ledger are 18 decimal fixed point numbers.

Details

Signature

effectiveValue(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256)

Visibility

external

State Mutability

view

effectiveValueAndRates

_Source

Details

Signature

effectiveValueAndRates(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256, uint256, uint256)

Visibility

external

State Mutability

view

effectiveValueAtRound

_Source

Details

Signature

effectiveValueAtRound(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey, uint256 roundIdForSrc, uint256 roundIdForDest) returns (uint256)

Visibility

external

State Mutability

view

getCurrentRoundId

_Source

Details

Signature

getCurrentRoundId(bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

getLastRoundIdBeforeElapsedSecs

_Source

Details

Signature

getLastRoundIdBeforeElapsedSecs(bytes32 currencyKey, uint256 startingRoundId, uint256 startingTimestamp, uint256 timediff) returns (uint256)

Visibility

external

State Mutability

view

lastRateUpdateTimes

_Source

Retrieves the timestamp the given rate was last updated. Accessed by the same keys as rates is.

Details

Signature

lastRateUpdateTimes(bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

lastRateUpdateTimesForCurrencies

_Source

Maps lastRateUpdateTimes over an array of keys.

Details

Signature

lastRateUpdateTimesForCurrencies(bytes32[] currencyKeys) returns (uint256[])

Visibility

external

State Mutability

view

rateAndInvalid

_Source

Details

Signature

rateAndInvalid(bytes32 currencyKey) returns (uint256, bool)

Visibility

external

State Mutability

view

rateAndTimestampAtRound

_Source

Details

Signature

rateAndTimestampAtRound(bytes32 currencyKey, uint256 roundId) returns (uint256, uint256)

Visibility

external

State Mutability

view

rateAndUpdatedTime

_Source

Details

Signature

rateAndUpdatedTime(bytes32 currencyKey) returns (uint256, uint256)

Visibility

external

State Mutability

view

rateForCurrency

_Source

Returns the last recorded rate for the given currency. This is just an alias to the public mapping rates, so it could probably be eliminated.

Details

Signature

rateForCurrency(bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

rateIsFlagged

_Source

Details

Signature

rateIsFlagged(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

rateIsFrozen

_Source

Returns true if the inverse price for the given currency is frozen. This is simply an alias to inversePricing[currencyKey].frozen. Currencies without an inverse price will naturally return false.

Details

Signature

rateIsFrozen(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

rateIsInvalid

_Source

Details

Signature

rateIsInvalid(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

rateIsStale

_Source

The rate for a given currency is stale if its last update occurred more than rateStalePeriod seconds ago.

sUSD is a special case; since its rate is fixed at $1.0$, it is never stale. The rates of nonexistent currencies are always stale.

Details

Signature

rateIsStale(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

rateStalePeriod

_Source

The duration after which a rate will be considered out of date. Synth exchange and other price-sensitive transactions in the Synthetix contract will not operate if a relevant rate is stale. Initialised to $3$ hours.

Type: uint256

Details

Signature

rateStalePeriod() returns (uint256)

Visibility

external

State Mutability

view

ratesAndInvalidForCurrencies

_Source

Details

Signature

ratesAndInvalidForCurrencies(bytes32[] currencyKeys) returns (uint256[], bool)

Visibility

external

State Mutability

view

ratesAndUpdatedTimeForCurrencyLastNRounds

_Source

Details

Signature

ratesAndUpdatedTimeForCurrencyLastNRounds(bytes32 currencyKey, uint256 numRounds) returns (uint256[], uint256[])

Visibility

external

State Mutability

view

ratesForCurrencies

_Source

Maps rateForCurrency over an array of keys.

Details

Signature

ratesForCurrencies(bytes32[] currencyKeys) returns (uint256[])

Visibility

external

State Mutability

view

resolverAddressesRequired

_Source

Details

Signature

resolverAddressesRequired() returns (bytes32[])

Visibility

public

State Mutability

view

Restricted Functions

addAggregator

_Source

Details

Signature

addAggregator(bytes32 currencyKey, address aggregatorAddress)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., Given Aggregator is invalid)

• require(..., Aggregator decimals should be lower or equal to 18)

Modifiers

• onlyOwner

Emits

• AggregatorAdded

deleteRate

_Source

Deletes a currency's price and its update time from the ExchangeRates contract.

Details

Signature

deleteRate(bytes32 currencyKey)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., Rate is zero)

Modifiers

• onlyOracle

Emits

• RateDeleted

removeAggregator

_Source

Details

Signature

removeAggregator(bytes32 currencyKey)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., No aggregator exists for key)

Modifiers

• onlyOwner

removeInversePricing

_Source

Allows the owner to remove an inverse index for a particular currency.

Details

Signature

removeInversePricing(bytes32 currencyKey)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., No inverted price exists)

Modifiers

• onlyOwner

setInversePricing

_Source

Allows the owner to set up an inverse index for a particular currency. See rateOrInverted for computation details. New inverse indexes begin unfrozen.

Details

Signature

setInversePricing(bytes32 currencyKey, uint256 entryPoint, uint256 upperLimit, uint256 lowerLimit, bool freezeAtUpperLimit, bool freezeAtLowerLimit)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., lowerLimit must be above 0)

• require(..., upperLimit must be above the entryPoint)

• require(..., upperLimit must be less than double entryPoint)

• require(..., lowerLimit must be below the entryPoint)

• require(..., Cannot freeze at both limits)

Modifiers

• onlyOwner

Emits

• InversePriceConfigured

setOracle

_Source

Allows the owner to set the address which is permitted to send prices to this contract.

Details

Signature

setOracle(address _oracle)

Visibility

external

State Mutability

nonpayable

Modifiers

• onlyOwner

Emits

• OracleUpdated

updateRates

_Source

Allows the oracle to update exchange rates in the contract. Otherwise this is just an alias to internalUpdateRates.

Details

Signature

updateRates(bytes32[] currencyKeys, uint256[] newRates, uint256 timeSent) returns (bool)

Visibility

external

State Mutability

nonpayable

Modifiers

• onlyOracle

Internal Functions

_effectiveValueAndRates

_Source

Details

Signature

_effectiveValueAndRates(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256, uint256, uint256)

Visibility

internal

State Mutability

view

_formatAggregatorAnswer

_Source

Details

Signature

_formatAggregatorAnswer(bytes32 currencyKey, int256 rate) returns (uint256)

Visibility

internal

State Mutability

view

Requires

• require(..., Negative rate not supported)

_getCurrentRoundId

_Source

Details

Signature

_getCurrentRoundId(bytes32 currencyKey) returns (uint256)

Visibility

internal

State Mutability

view

_getRate

_Source

Details

Signature

_getRate(bytes32 currencyKey) returns (uint256)

Visibility

internal

State Mutability

view

_getRateAndTimestampAtRound

_Source

Details

Signature

_getRateAndTimestampAtRound(bytes32 currencyKey, uint256 roundId) returns (uint256, uint256)

Visibility

internal

State Mutability

view

_getRateAndUpdatedTime

_Source

Details

Signature

_getRateAndUpdatedTime(bytes32 currencyKey) returns (struct IExchangeRates.RateAndUpdatedTime)

Visibility

internal

State Mutability

view

_getUpdatedTime

_Source

Details

Signature

_getUpdatedTime(bytes32 currencyKey) returns (uint256)

Visibility

internal

State Mutability

view

_onlyOracle

_Source

Details

Signature

_onlyOracle()

Visibility

internal

State Mutability

view

Requires

• require(..., Only the oracle can perform this action)

_rateIsFlagged

_Source

Details

Signature

_rateIsFlagged(bytes32 currencyKey, contract FlagsInterface flags) returns (bool)

Visibility

internal

State Mutability

view

_rateIsFrozen

_Source

Details

Signature

_rateIsFrozen(bytes32 currencyKey) returns (bool)

Visibility

internal

State Mutability

view

_rateIsStale

_Source

Details

Signature

_rateIsStale(bytes32 currencyKey, uint256 _rateStalePeriod) returns (bool)

Visibility

internal

State Mutability

view

_rateIsStaleWithTime

_Source

Details

Signature

_rateIsStaleWithTime(uint256 _rateStalePeriod, uint256 _time) returns (bool)

Visibility

internal

State Mutability

view

_rateOrInverted

_Source

Details

Signature

_rateOrInverted(bytes32 currencyKey, uint256 rate, uint256 roundId) returns (uint256)

Visibility

internal

State Mutability

view

_setRate

_Source

Updates the rate and timestamp for the individual rate using an internal struct.

Details

Signature

_setRate(bytes32 currencyKey, uint256 rate, uint256 time)

Visibility

internal

State Mutability

nonpayable

exchanger

_Source

Details

Signature

exchanger() returns (contract IExchanger)

Visibility

internal

State Mutability

view

getFlagsForRates

_Source

Details

Signature

getFlagsForRates(bytes32[] currencyKeys) returns (bool[])

Visibility

internal

State Mutability

view

internalUpdateRates

_Source

Record the set of provided rates and the timestamp, handling any inverse indexes with rateOrInverted. At this stage inverse indexes which escaped their bounds are frozen. Any rate with a more recent update time is skipped.

Finally, the price update lock is reset, reenabling Synth exchange functionality.

The timeSent argument is useful for maintaining the exact age of the data points even as transactions can take a variable amount of time to confirm. Without this, earlier updates could possibly overwrite later ones.

Returns true if no exception was thrown.

Details

Signature

internalUpdateRates(bytes32[] currencyKeys, uint256[] newRates, uint256 timeSent) returns (bool)

Visibility

internal

State Mutability

nonpayable

Requires

• require(..., Currency key array length must match rates array length.)

• require(..., Time is too far into the future)

Emits

• RatesUpdated

removeFromArray

_Source

Helper function that removes an entry from an existing array in storage. Returns true if found and removed, false otherwise.

Details

Signature

removeFromArray(bytes32 entry, bytes32[] array) returns (bool)

Visibility

internal

State Mutability

nonpayable

External Functions

freezeRate

_Source

Details

Signature

freezeRate(bytes32 currencyKey)

Visibility

external

State Mutability

nonpayable

Requires

• require(..., Cannot freeze non-inverse rate)

• require(..., The rate is already frozen)

Modifiers

onlyOracle

_Source

Reverts the transaction if msg.sender is not the oracle.

Events

AggregatorAdded

_Source

Records that an Aggregator pricing network was added

Signature: AggregatorAdded(bytes32 currencyKey, address aggregator)

AggregatorRemoved

_Source

Records that an Aggregator pricing network was removed

Signature: AggregatorRemoved(bytes32 currencyKey, address aggregator)

InversePriceConfigured

_Source

Records that an inverse price index was set up or deleted. As there is no distinct event for deletion, this is signaled by providing zero values to all arguments barring currencyKey.

Signature: InversePriceConfigured(bytes32 currencyKey, uint256 entryPoint, uint256 upperLimit, uint256 lowerLimit)

InversePriceFrozen

_Source

Records that an inverse price breached a limit and was frozen.

Signature: InversePriceFrozen(bytes32 currencyKey, uint256 rate, uint256 roundId, address initiator)

OracleUpdated

_Source

Records that the anointed oracle was updated.

Signature: OracleUpdated(address newOracle)

RateDeleted

_Source

Signature: RateDeleted(bytes32 currencyKey)

RatesUpdated

_Source

Records that a set of currency prices were updated.

Signature: RatesUpdated(bytes32[] currencyKeys, uint256[] newRates)