Skip to content

Synthetix

Description

Source: contracts/Synthetix.sol

Architecture

Inheritance Graph

graph TD Synthetix[Synthetix] --> ExternStateToken[ExternStateToken] Synthetix[Synthetix] --> MixinResolver[MixinResolver] ExternStateToken[ExternStateToken] --> SelfDestructible[SelfDestructible] ExternStateToken[ExternStateToken] --> Proxyable[Proxyable] SelfDestructible[SelfDestructible] --> Owned[Owned] Proxyable[Proxyable] --> Owned[Owned] MixinResolver[MixinResolver] --> Owned[Owned]

Synthetix architture graph

Details
  • Depot: The depot trades SNX and therefore knows the Synthetix address.
  • Exchanger The helper contract that performs the heavy lifting for exchange() and settle().
  • ExchangeRates: The Synthetix contract fetches prices from the exchange rates contract to facilitate synth exchange and to determine the value of various quantities of synths.
  • FeePool: The Synthetix contract remits exchange fees as sUSD to the fee pool, and also uses it to keep track of historical issuance records for each issuer.
  • Issuer The helper contract that performs the heavy lifting for issueSynths(), issueMaxSynths() and burnSynths().
  • Proxy: The Synthetix contract, which is Proxyable, exists behind a CALL-style proxy for upgradeability.
  • RewardEscrow: This is similar to the SynthetixEscrow contract, but it is where the SNX inflationary supply is kept before it is released to Synth issuers.
  • RewardsDistribution: This contract works closely with RewardEscrow to release portions of the inflationary supply to different recipients.
  • SupplySchedule: The supply schedule determines the rate at which SNX are released from the inflationary supply.
  • Synth: Synthetix manages the supply of synths. It keeps track of which ones exist, and they are all issued and burnt from the Synthetix contract. The Synthetix contract is also responsible for exchange between different synth flavours.
  • SynthetixEscrow: The escrow contract keeps track of SNX owed to participants in the initial token sale, and releases them according to specified vesting schedules.
  • SynthetixState: This state contract stores the debt ledger and the current issuance information for synth issuers.

Constants

DECIMALS

Source

A constant used to initialise the ERC20 ExternStateToken.decimals field upon construction.

Value: 18

Type: uint8

TOKEN_NAME

Source

A constant used to initialise the ERC20 ExternStateToken.name field upon construction.

Value: "Synthetix Network Token"

Type: string

TOKEN_SYMBOL

Source

A constant used to initialise the ERC20 ExternStateToken.symbol field upon construction.

Value: "SNX"

Type: string

sUSD

Source

Type: bytes32

Constructor

constructor

Source

Details

Signature

(address payable _proxy, contract TokenState _tokenState, address _owner, uint256 _totalSupply, address _resolver)

Visibility

public

State Mutability

nonpayable

Views

anySynthOrSNXRateIsStale

Source

Details

Signature

anySynthOrSNXRateIsStale() returns (bool)

Visibility

external

State Mutability

view

availableCurrencyKeys

Source

Returns the currency key for each synth in availableSynths.

Details

Signature

availableCurrencyKeys() returns (bytes32[])

Visibility

external

State Mutability

view

availableSynthCount

Source

Returns the number of synths in the system, that is availableSynths.length.

Details

Signature

availableSynthCount() returns (uint256)

Visibility

external

State Mutability

view

availableSynths

Source

List of the active Synths. Used to compute the total value of issued synths.

Type: contract ISynth[]

Details

Signature

availableSynths(uint256 index) returns (contract ISynth)

Visibility

external

State Mutability

view

collateral

Source

Returns the total SNX owned by the given account, locked and unlocked, escrowed and unescrowed. This is the quantity of SNX synths can be issued against.

This is computed as the sum of Synthetix.balanceOf(account), SynthetixEscrow.balanceOf(account), and RewardEscrow.balanceOf(account); so an account may issue synths against both its active balance and its unclaimed escrow funds.

Details

Signature

collateral(address account) returns (uint256)

Visibility

external

State Mutability

view

collateralisationRatio

Source

The ratio between value of synths that an account has issued and the value of the collateral they control. That is, this is just debtBalanceOf(issuer, "SNX") / collateral(issuer).

Ideally, issuers should maintain their collateralisation ratio at a level less than the global issuance ratio, and they are incentivised to do this by the fees they can claim if they do so.

Details

Signature

collateralisationRatio(address _issuer) returns (uint256)

Visibility

external

State Mutability

view

debtBalanceOf

Source

Reports the quantity of a given currency required to free up all SNX locked in given account.

If \mathrm{X} is the total value of all issued synths, and \check{\omega} is fraction of that value currently accounted for by this account's locked SNX, then the result is simply:

\check{\omega} \ \mathrm{X}

In order to account for fluctuations in synth prices and supply, the current ownership fraction is computed as the adjusted value:

\check{\omega} = \omega \frac{\Delta_\text{last}}{\Delta_\text{entry}}

Where \omega is the account's debt ownership fraction at the time it last issued or burnt synths, which produced the \Delta_\text{entry} item in the debt ledger. \Delta_\text{last} is the latest value on the ledger. This logic is much the same as that found in FeePool._effectiveDebtRatioForPeriod. The actual value of \omega is set in _addToDebtRegister and _removeFromDebtRegister.

Details

Signature

debtBalanceOf(address account, bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

isWaitingPeriod

Source

Whether or not the waiting period is ongoing for the given synth. If so, no exchanges into this synth will be allowed, nor will that synth be able to be transferred.

Details

Signature

isWaitingPeriod(bytes32 currencyKey) returns (bool)

Visibility

external

State Mutability

view

maxIssuableSynths

Source

The maximum number of a given synth that is issuable against the issuer's collateral. This is simply issuanceRatio * collateral(issuer), priced in the requested currency.

Details

Signature

maxIssuableSynths(address account) returns (uint256)

Visibility

external

State Mutability

view

remainingIssuableSynths

Source

The remaining sUSD synths this account can issue.

If \text{maxIssuable} is maxIssuableSynths(issuer) and \text{debt} is debtBalanceOf(issuer, currencyKey), then the result of this function is max(0, \text{maxIssuable} - \text{debt}).

If prices fluctuate then the account's issued synth debt may exceed its current maximum issuable synths, in which case it may not issue any more synths until more collateral is added.

Details

Signature

remainingIssuableSynths(address account) returns (uint256, uint256, uint256)

Visibility

external

State Mutability

view

synths

Source

A mapping from currency keys (bytes32) to Synth token contract addresses.

Type: mapping(bytes32 => contract ISynth)

Details

Signature

synths(bytes32 currencyKey) returns (contract ISynth)

Visibility

external

State Mutability

view

synthsByAddress

Source

A reverse mapping from a synth's address to its bytes32 currency key

Type: mapping(address => bytes32)

Details

Signature

synthsByAddress(address synthAddress) returns (bytes32)

Visibility

external

State Mutability

view

totalIssuedSynths

Source

Returns the total value of Synths in the system, priced in terms of a given currency.

This value is equivalent to:

\frac{1}{\pi_d}\sum_{s \in \text{synths}}{\sigma_s \pi_s}

Where \sigma_s and \pi_s are the total supply and price of synth s, and \pi_d is the price of the denominating synth flavour.

Details

Signature

totalIssuedSynths(bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

totalIssuedSynthsExcludeEtherCollateral

Source

Details

Signature

totalIssuedSynthsExcludeEtherCollateral(bytes32 currencyKey) returns (uint256)

Visibility

external

State Mutability

view

transferableSynthetix

Source

The quantity of SNX this account can transfer given that a portion of it may be locked due to issuance.

If \text{balance} is balanceOf(account), and \text{lockedSnx} is debtBalanceOf(account, "SNX") / SynthetixState.issuanceRatio, the function returns max(0, \text{balance} - \text{lockedSnx}). Escrowed tokens are not taken into account in this computation, so unescrowed tokens are locked immediately.

A Note on Price Motion

The value of \text{lockedSnx} depends on the current (\pi) and previous (\pi') prices being reported by the oracle, and the issuance ratio (\rho).

If we consider a situation where the synth supply has not changed in the time period under consideration, then ownership fractions do not change even if prices do. Further assuming that there is only a single synth circulating, debt balances correspond to the same number of synths, although perhaps not the same value.

In such a situation, we can think of each user having issued a particular quantity of synths. This quantity depends on the prices of synths and SNX at the time of issuance.

Q_s = \rho \ \frac{\pi'_c}{\pi'_s} \ Q_c

Whose value at the present time priced in terms of SNX, which is what debtBalanceOf(account, "SNX") returns, is:

{V_s}^{c} = \rho \ \frac{\pi'_c}{\pi'_s} \ \pi_c \ Q_c

Note that this computation has a factor of \rho in it, and this must be divided out in order to ascertain the quantity of SNX which are presently locked.

\text{lockedSnx} = \frac{{V_s}^{c}}{\rho} = \frac{\pi'_c}{\pi'_s} \ \pi_c \ Q_c

Which is to say that the quantity of SNX locked in this situation depends on the price.

Extend this to the multicurrency case

Consider a two synth system, one primary synth and a secondary one which represents the price/supply of all other synths. Use the total issued value function to derive the behaviour for multiple currencies, and then examine a single currency as a special case.

Details

Signature

transferableSynthetix(address account) returns (uint256)

Visibility

external

State Mutability

view

Restricted Functions

emitExchangeRebate

Source

Details

Signature

emitExchangeRebate(address account, bytes32 currencyKey, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

emitExchangeReclaim

Source

Details

Signature

emitExchangeReclaim(address account, bytes32 currencyKey, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

emitSynthExchange

Source

Details

Signature

emitSynthExchange(address account, bytes32 fromCurrencyKey, uint256 fromAmount, bytes32 toCurrencyKey, uint256 toAmount, address toAddress)

Visibility

external

State Mutability

nonpayable

Modifiers

Internal Functions

_canTransfer

Source

Details

Signature

_canTransfer(address account, uint256 value) returns (bool)

Visibility

internal

State Mutability

view

emitAccountLiquidated

Source

Details

Signature

emitAccountLiquidated(address account, uint256 snxRedeemed, uint256 amountLiquidated, address liquidator)

Visibility

internal

State Mutability

nonpayable

exchanger

Source

Details

Signature

exchanger() returns (contract IExchanger)

Visibility

internal

State Mutability

view

issuer

Source

Details

Signature

issuer() returns (contract IIssuer)

Visibility

internal

State Mutability

view

rewardsDistribution

Source

Details

Signature

rewardsDistribution() returns (contract IRewardsDistribution)

Visibility

internal

State Mutability

view

supplySchedule

Source

Details

Signature

supplySchedule() returns (contract SupplySchedule)

Visibility

internal

State Mutability

view

synthetixState

Source

Details

Signature

synthetixState() returns (contract ISynthetixState)

Visibility

internal

State Mutability

view

systemStatus

Source

Details

Signature

systemStatus() returns (contract ISystemStatus)

Visibility

internal

State Mutability

view

External Functions

burnSynths

Source

Burns a quantity of sUSD in the calling address, in order to free up its locked SNX supply.

If the caller attempts to burn more synths than their SNX debt is worth, this function will only burn sufficiently many tokens to cover the debt and leave the rest untouched.

The new debt position of the caller is recorded with _appendAccountIssuanceRecord, and the adjustment to global debt recorded with _removeFromDebtRegister.

See Issuer for further details.

Details

Signature

burnSynths(uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

burnSynthsOnBehalf

Source

Details

Signature

burnSynthsOnBehalf(address burnForAddress, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

burnSynthsToTarget

Source

Burns enough sUSD to get the user's collaterisation ratio back to the target issuance ratio.

Details

Signature

burnSynthsToTarget()

Visibility

external

State Mutability

nonpayable

Modifiers

burnSynthsToTargetOnBehalf

Source

Details

Signature

burnSynthsToTargetOnBehalf(address burnForAddress)

Visibility

external

State Mutability

nonpayable

Modifiers

exchange

Source

Exchanges one synth flavour for an equivalent value of another at current exchange rates and transfers the converted quantity to a destination address. An exchange fee is charged on the way.

See Exchanger for further details.

Details

Signature

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

Visibility

external

State Mutability

nonpayable

Modifiers

exchangeOnBehalf

Source

Details

Signature

exchangeOnBehalf(address exchangeForAddress, bytes32 sourceCurrencyKey, uint256 sourceAmount, bytes32 destinationCurrencyKey) returns (uint256)

Visibility

external

State Mutability

nonpayable

Modifiers

issueMaxSynths

Source

Issues the maximum quantity sUSD issuable by the caller of a particular synth flavour. Otherwise, this operates exactly as issueSynths does.

See Issuer for further details.

Details

Signature

issueMaxSynths()

Visibility

external

State Mutability

nonpayable

Modifiers

issueMaxSynthsOnBehalf

Source

Details

Signature

issueMaxSynthsOnBehalf(address issueForAddress)

Visibility

external

State Mutability

nonpayable

Modifiers

issueSynths

Source

Issues a new quantity of sUSD into the calling address. The new debt issuance is recorded with _addToDebtRegister, and the account's issuance records are updated with _appendAccountIssuanceRecord.

See Issuer for further details.

Details

Signature

issueSynths(uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

issueSynthsOnBehalf

Source

Details

Signature

issueSynthsOnBehalf(address issueForAddress, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

liquidateDelinquentAccount

Source

Details

Signature

liquidateDelinquentAccount(address account, uint256 susdAmount) returns (bool)

Visibility

external

State Mutability

nonpayable

Modifiers

mint

Source

This function is responsible for creating the inflationary SNX supply. It is a public function, so any address can ensure new tokens are released on schedule. When a new quantity is minted, the calling address is rewarded with a small incentive of SNX tokens, defined by SupplySchedule.minterReward.

The supply is released according to the schedule defined in SupplySchedule.schedules, being sent to the RewardsDistribution contract for distribution and escrow. The total supply SNX supply is thus increased by the quantity specified by the schedule.

This function always returns true if the transaction did not revert.

Details

Signature

mint() returns (bool)

Visibility

external

State Mutability

nonpayable

Requires

Modifiers

settle

Source

Settles any amounts oustanding for previous exchanges into the given synth.

See Exchanger for further details.

Details

Signature

settle(bytes32 currencyKey) returns (uint256, uint256, uint256)

Visibility

external

State Mutability

nonpayable

Modifiers

transfer

Source

This is a ERC20 transfer functions.

A successful transfer requires the message sender to have sufficient balance, accounting for locked SNX.

Implemented based on ExternStateToken._transfer_byProxy.

Details

Signature

transfer(address to, uint256 value) returns (bool)

Visibility

external

State Mutability

nonpayable

Modifiers

transferFrom

Source

This is a ERC20 transferFrom functions.

A successful transfer requires the token owner to have sufficient balance, accounting for locked SNX.

Implemented based on ExternStateToken._transferFrom_byProxy.

Details

Signature

transferFrom(address from, address to, uint256 value) returns (bool)

Visibility

external

State Mutability

nonpayable

Modifiers

Modifiers

exchangeActive

Source

Signature: exchangeActive(bytes32 src, bytes32 dest)

issuanceActive

Source

onlyExchanger

Source

systemActive

Source

Events

AccountLiquidated

Source

Signature: AccountLiquidated(address account, uint256 snxRedeemed, uint256 amountLiquidated, address liquidator)

ExchangeRebate

Source

Fee Rebates

See SIP-37 on Fee Reclamation & Rebates.

Records that an amount of the synth denoted by currencyKey has been rebated (i.e. issued) by the system to the account.

The amount is the total net amount from all unsettled exchanges into the given synth

Signature: ExchangeRebate(address account, bytes32 currencyKey, uint256 amount)

ExchangeReclaim

Source

Fee Reclaims

See SIP-37 on Fee Reclamation & Rebates.

Records that an amount of the synth denoted by currencyKey has been reclaimed (i.e. burned) from the account to the system.

The amount is the total net amount from all unsettled exchanges into the given synth

Signature: ExchangeReclaim(address account, bytes32 currencyKey, uint256 amount)

SynthExchange

Source

Records that an exchange between two flavours of synths occurred.

This event is emitted from the Synthetix proxy with the emitSynthExchange function.

Signature: SynthExchange(address account, bytes32 fromCurrencyKey, uint256 fromAmount, bytes32 toCurrencyKey, uint256 toAmount, address toAddress)