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¶
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
¶
A list of the keys of currencies with a decentralized aggregated pricing network.
Type: bytes32[]
aggregators
¶
For each currency with a decentralized aggregated pricing network, return the Aggregation contract address.
Type: mapping(bytes32 => contract AggregatorV2V3Interface)
currencyKeyDecimals
¶
Type: mapping(bytes32 => uint8)
currentRoundForRate
¶
Type: mapping(bytes32 => uint256)
inversePricing
¶
For each currency with an inverse index, keep the necessary InversePricing
information to maintain the index.
Type: mapping(bytes32 => struct IExchangeRates.InversePricing)
invertedKeys
¶
A list of the keys of currencies with an inverted index.
Type: bytes32[]
oracle
¶
The address which is permitted to push rate updates to the contract.
Type: address
roundFrozen
¶
Type: mapping(bytes32 => uint256)
Constructor¶
constructor
¶
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
Views¶
aggregatorWarningFlags
¶
Details
Signature
aggregatorWarningFlags() returns (address)
Visibility
external
State Mutability
view
anyRateIsInvalid
¶
Details
Signature
anyRateIsInvalid(bytes32[] currencyKeys) returns (bool)
Visibility
external
State Mutability
view
canFreezeRate
¶
Details
Signature
canFreezeRate(bytes32 currencyKey) returns (bool)
Visibility
external
State Mutability
view
currenciesUsingAggregator
¶
Details
Signature
currenciesUsingAggregator(address aggregator) returns (bytes32[])
Visibility
external
State Mutability
view
effectiveValue
¶
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:
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
¶
Details
Signature
effectiveValueAndRates(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256, uint256, uint256)
Visibility
external
State Mutability
view
effectiveValueAtRound
¶
Details
Signature
effectiveValueAtRound(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey, uint256 roundIdForSrc, uint256 roundIdForDest) returns (uint256)
Visibility
external
State Mutability
view
getCurrentRoundId
¶
Details
Signature
getCurrentRoundId(bytes32 currencyKey) returns (uint256)
Visibility
external
State Mutability
view
getLastRoundIdBeforeElapsedSecs
¶
Details
Signature
getLastRoundIdBeforeElapsedSecs(bytes32 currencyKey, uint256 startingRoundId, uint256 startingTimestamp, uint256 timediff) returns (uint256)
Visibility
external
State Mutability
view
lastRateUpdateTimes
¶
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
¶
Maps lastRateUpdateTimes
over an array of keys.
Details
Signature
lastRateUpdateTimesForCurrencies(bytes32[] currencyKeys) returns (uint256[])
Visibility
external
State Mutability
view
rateAndInvalid
¶
Details
Signature
rateAndInvalid(bytes32 currencyKey) returns (uint256, bool)
Visibility
external
State Mutability
view
rateAndTimestampAtRound
¶
Details
Signature
rateAndTimestampAtRound(bytes32 currencyKey, uint256 roundId) returns (uint256, uint256)
Visibility
external
State Mutability
view
rateAndUpdatedTime
¶
Details
Signature
rateAndUpdatedTime(bytes32 currencyKey) returns (uint256, uint256)
Visibility
external
State Mutability
view
rateForCurrency
¶
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
¶
Details
Signature
rateIsFlagged(bytes32 currencyKey) returns (bool)
Visibility
external
State Mutability
view
rateIsFrozen
¶
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
¶
Details
Signature
rateIsInvalid(bytes32 currencyKey) returns (bool)
Visibility
external
State Mutability
view
rateIsStale
¶
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
¶
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
¶
Details
Signature
ratesAndInvalidForCurrencies(bytes32[] currencyKeys) returns (uint256[], bool)
Visibility
external
State Mutability
view
ratesAndUpdatedTimeForCurrencyLastNRounds
¶
Details
Signature
ratesAndUpdatedTimeForCurrencyLastNRounds(bytes32 currencyKey, uint256 numRounds) returns (uint256[], uint256[])
Visibility
external
State Mutability
view
ratesForCurrencies
¶
Maps rateForCurrency
over an array of keys.
Details
Signature
ratesForCurrencies(bytes32[] currencyKeys) returns (uint256[])
Visibility
external
State Mutability
view
resolverAddressesRequired
¶
Details
Signature
resolverAddressesRequired() returns (bytes32[])
Visibility
public
State Mutability
view
Restricted Functions¶
addAggregator
¶
Details
Signature
addAggregator(bytes32 currencyKey, address aggregatorAddress)
Visibility
external
State Mutability
nonpayable
Requires
Modifiers
Emits
deleteRate
¶
Deletes a currency's price and its update time from the ExchangeRates contract.
Details
Signature
deleteRate(bytes32 currencyKey)
Visibility
external
State Mutability
nonpayable
Requires
Modifiers
Emits
removeAggregator
¶
Details
Signature
removeAggregator(bytes32 currencyKey)
Visibility
external
State Mutability
nonpayable
Requires
Modifiers
removeInversePricing
¶
Allows the owner to remove an inverse index for a particular currency.
Details
Signature
removeInversePricing(bytes32 currencyKey)
Visibility
external
State Mutability
nonpayable
Requires
Modifiers
setInversePricing
¶
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
Modifiers
Emits
setOracle
¶
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
Emits
updateRates
¶
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
Internal Functions¶
_effectiveValueAndRates
¶
Details
Signature
_effectiveValueAndRates(bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256, uint256, uint256)
Visibility
internal
State Mutability
view
_formatAggregatorAnswer
¶
Details
Signature
_formatAggregatorAnswer(bytes32 currencyKey, int256 rate) returns (uint256)
Visibility
internal
State Mutability
view
Requires
_getCurrentRoundId
¶
Details
Signature
_getCurrentRoundId(bytes32 currencyKey) returns (uint256)
Visibility
internal
State Mutability
view
_getRate
¶
Details
Signature
_getRate(bytes32 currencyKey) returns (uint256)
Visibility
internal
State Mutability
view
_getRateAndTimestampAtRound
¶
Details
Signature
_getRateAndTimestampAtRound(bytes32 currencyKey, uint256 roundId) returns (uint256, uint256)
Visibility
internal
State Mutability
view
_getRateAndUpdatedTime
¶
Details
Signature
_getRateAndUpdatedTime(bytes32 currencyKey) returns (struct IExchangeRates.RateAndUpdatedTime)
Visibility
internal
State Mutability
view
_getUpdatedTime
¶
Details
Signature
_getUpdatedTime(bytes32 currencyKey) returns (uint256)
Visibility
internal
State Mutability
view
_onlyOracle
¶
Details
Signature
_onlyOracle()
Visibility
internal
State Mutability
view
Requires
_rateIsFlagged
¶
Details
Signature
_rateIsFlagged(bytes32 currencyKey, contract FlagsInterface flags) returns (bool)
Visibility
internal
State Mutability
view
_rateIsFrozen
¶
Details
Signature
_rateIsFrozen(bytes32 currencyKey) returns (bool)
Visibility
internal
State Mutability
view
_rateIsStale
¶
Details
Signature
_rateIsStale(bytes32 currencyKey, uint256 _rateStalePeriod) returns (bool)
Visibility
internal
State Mutability
view
_rateIsStaleWithTime
¶
Details
Signature
_rateIsStaleWithTime(uint256 _rateStalePeriod, uint256 _time) returns (bool)
Visibility
internal
State Mutability
view
_rateOrInverted
¶
Details
Signature
_rateOrInverted(bytes32 currencyKey, uint256 rate, uint256 roundId) returns (uint256)
Visibility
internal
State Mutability
view
_setRate
¶
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
¶
Details
Signature
exchanger() returns (contract IExchanger)
Visibility
internal
State Mutability
view
getFlagsForRates
¶
Details
Signature
getFlagsForRates(bytes32[] currencyKeys) returns (bool[])
Visibility
internal
State Mutability
view
internalUpdateRates
¶
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
Emits
removeFromArray
¶
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
¶
Details
Signature
freezeRate(bytes32 currencyKey)
Visibility
external
State Mutability
nonpayable
Requires
Modifiers¶
onlyOracle
¶
Reverts the transaction if msg.sender
is not the oracle
.
Events¶
AggregatorAdded
¶
Records that an Aggregator pricing network was added
Signature: AggregatorAdded(bytes32 currencyKey, address aggregator)
AggregatorRemoved
¶
Records that an Aggregator pricing network was removed
Signature: AggregatorRemoved(bytes32 currencyKey, address aggregator)
InversePriceConfigured
¶
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
¶
Records that an inverse price breached a limit and was frozen.
Signature: InversePriceFrozen(bytes32 currencyKey, uint256 rate, uint256 roundId, address initiator)
OracleUpdated
¶
Records that the anointed oracle was updated.
Signature: OracleUpdated(address newOracle)
RateDeleted
¶
Signature: RateDeleted(bytes32 currencyKey)
RatesUpdated
¶
Records that a set of currency prices were updated.
Signature: RatesUpdated(bytes32[] currencyKeys, uint256[] newRates)