Skip to content

Synth

Description

This contract is the basis of all Synth flavours. It exposes sufficient functionality for the Synthetix and FeePool contracts to manage its supply. Otherwise Synths are fairly vanilla ERC20 tokens; the PurgeableSynth contract extends this basic functionality to allow the owner to liquidate a Synth if its total value is low enough.

See the main synth notes for more information about how Synths function in practice.

A Historical Note on Conversion Fees

Since transfer conversion is not operating, the following is recorded only to be kept in mind in case it is ever reactivated. At present there is no way for users to set a preferred currency.

The Synthetix system has implements both exchange and transfer fees on Synths. Although they should be distinct, the preferred currency auto conversion on transfer only charges the transfer fee, and not the exchange fee. As a result, it is possible to convert Synths more cheaply whenever the transfer fee is less than the conversion fee.

Given that the transfer fee is currently nil, if a user was able to set a preferred currency for themselves, it would be possible by this means to perform free Synth conversions. This would undercut fee revenue for the system to incentivise participants with. If markets had priced in the conversion fee, but were unaware of the exploit, then there would be a profit cycle available for someone exploiting this.

In particular:

Let \phi_\kappa, \ \phi_\tau \in [0,1] be the conversion and transfer fee rates, respectively. Let \pi_A, \ \pi_B be the prices of synths A and B in terms of some implicit common currency. Q_A will be the starting quantity of synth A.

Then to convert from A to B, quantities

Q^\kappa_B = Q_A\frac{\pi_A}{\pi_B}(1 - \phi_\kappa) \\ Q^\tau_B = Q_A\frac{\pi_A}{\pi_B}(1 - \phi_\tau)

are received if the user performs a standard conversion or a transfer conversion, respectively. The profit of performing a transfer conversion relative to a standard one is then:

Q^\tau_B - Q^\kappa_B = Q_A\frac{\pi_A}{\pi_B}(\phi_\kappa - \phi_\tau)

That is, the relative profit is simply (\phi_\kappa - \phi_\tau). With no transfer fee, this is \phi_\kappa, as expected.

Source: contracts/Synth.sol

Architecture

Inheritance Graph

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

Constants

DECIMALS

Source

The number of decimal places this token uses. Fixed at 18.

Value: 18

Type: uint8

FEE_ADDRESS

Source

Type: address

Variables

currencyKey

Source

The identifier of this Synth within the Synthetix ecosystem. The currency key could in principle be distinct from this token's ERC20 symbol.

Type: bytes32

Constructor

constructor

Source

Initialises the feePool and synthetix addresses, this Synth's currencyKey, and the inherited ExternStateToken instance.

The precision in every Synth's fixed point representation is fixed at 18 so they are all conveniently interconvertible. The total supply of all new Synths is initialised to 0 since they must be created by the Synthetix contract when issuing or converting between Synths, or by the FeePool when users claim fees.

Details

Signature

(address payable _proxy, contract TokenState _tokenState, string _tokenName, string _tokenSymbol, address _owner, bytes32 _currencyKey, uint256 _totalSupply, address _resolver)

Visibility

public

State Mutability

nonpayable

Requires

Views

transferableSynths

Source

Details

Signature

transferableSynths(address account) returns (uint256)

Visibility

public

State Mutability

view

Restricted Functions

burn

Source

Allows the Synthetix contract to burn existing Synths of this flavour. This is used whenever Synths are exchanged or burnt directly. This is also used to burn Synths involved in oracle frontrunning as part of the protection circuit. This is also used by the FeePool to burn sUSD when fees are paid out.

Details

Signature

burn(address account, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

issue

Source

Allows the Synthetix contract to issue new Synths of this flavour. This is used whenever Synths are exchanged or issued directly. This is also used by the FeePool to pay fees out.

Details

Signature

issue(address account, uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

setTotalSupply

Source

This allows the owner to set the total supply directly for upgrades, where the tokenState is retained, but the total supply figure must be migrated.

For example, just such a migration is performed by this script.

Details

Signature

setTotalSupply(uint256 amount)

Visibility

external

State Mutability

nonpayable

Modifiers

Internal Functions

_ensureCanTransfer

Source

Details

Signature

_ensureCanTransfer(address from, uint256 value)

Visibility

internal

State Mutability

view

Requires

_internalBurn

Source

Details

Signature

_internalBurn(address account, uint256 amount) returns (bool)

Visibility

internal

State Mutability

nonpayable

_internalIssue

Source

Details

Signature

_internalIssue(address account, uint256 amount)

Visibility

internal

State Mutability

nonpayable

_internalTransferFrom

Source

Details

Signature

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

Visibility

internal

State Mutability

nonpayable

_transferToFeeAddress

Source

Details

Signature

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

Visibility

internal

State Mutability

nonpayable

emitBurned

Source

Details

Signature

emitBurned(address account, uint256 value)

Visibility

internal

State Mutability

nonpayable

emitIssued

Source

Details

Signature

emitIssued(address account, uint256 value)

Visibility

internal

State Mutability

nonpayable

exchanger

Source

Details

Signature

exchanger() returns (contract IExchanger)

Visibility

internal

State Mutability

view

feePool

Source

The address of the FeePool contract.

Type: FeePool public

Details

Signature

feePool() returns (contract IFeePool)

Visibility

internal

State Mutability

view

issuer

Source

Details

Signature

issuer() returns (contract IIssuer)

Visibility

internal

State Mutability

view

synthetix

Source

The address of the Synthetix contract.

Type: FeePool public

Details

Signature

synthetix() returns (contract ISynthetix)

Visibility

internal

State Mutability

view

systemStatus

Source

Details

Signature

systemStatus() returns (contract ISystemStatus)

Visibility

internal

State Mutability

view

External Functions

transfer

Source

This is a pair of ERC20 transfer function.

Implemented based on ExternStateToken._transfer_byProxy.

Warning

Due to SIP-37 Fee Reclamation, this will always fail if there are any exchanges awaiting settlement for this synth. To prevent failues, please use transferAndSettle() below or invoke Exchanger.settle() prior to transfer().

Details

Signature

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

Visibility

public

State Mutability

nonpayable

Modifiers

transferAndSettle

Source

Settles any outstanding fee reclaims and rebates from SIP-37 and then performs the transfer functionality. If there is insufficient balance to transfer value after any reclaims, the amount will be reduced to the remaining balance of the sender.

Implemented based on ExternStateToken._transfer_byProxy.

Details

Signature

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

Visibility

public

State Mutability

nonpayable

Modifiers

transferFrom

Source

This is a ERC20 transferFrom function.

Implemented based on ExternStateToken._transferFrom_byProxy.

Warning

Due to SIP-37 Fee Reclamation, this will always fail if there are any exchanges awaiting settlement for this synth. To prevent failues, please use transferFromAndSettle() below or invoke Exchanger.settle() prior to transferFrom().

Details

Signature

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

Visibility

public

State Mutability

nonpayable

Modifiers

transferFromAndSettle

Source

Settles any outstanding fee reclaims and rebates from SIP-37 and then performs the transferFrom functionality. If there is insufficient balance to transfer value after any reclaims, the amount will be reduced to the remaining balance of the from address.

Implemented based on ExternStateToken._transferFrom_byProxy.

Warning

Due to SIP-37 Fee Reclamation, this will always fail if there are any exchanges awaiting settlement for this synth. To prevent failues, please use transferFromAndSettle() below or invoke Exchanger.settle() prior to transferFrom().

Details

Signature

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

Visibility

public

State Mutability

nonpayable

Modifiers

Modifiers

onlyInternalContracts

Source

Events

Burned

Source

Records that a quantity of this Synth was burned.

This event is emitted from the Synths's proxy with the emitBurned function.

Signature: Burned(address account, uint256 value)

Issued

Source

Records that a quantity of this Synth was newly issued.

This event is emitted from the Synths's proxy with the emitIssued function.

Signature: Issued(address account, uint256 value)