OikosState¶
This is a state contract associated with the main Oikos
contract, which is the only address permitted to invoke most of its functionality.
This contract is responsible for recording issuance and debt information for the system and users within it, as well as the global issuance ratio.
Upon system updates, this contract will continue to exist, while the Oikos logic itself is swapped out.
Disabled: Preferred Currency Transfer Conversion
This contract also contains functionality enabling automatic preferred currency conversion on Synth transfers, but it is currently disabled.
Source: OikosState.sol
Architecture¶
Inheritance Graph¶
Related Contracts¶
- Oikos as this contract's
State.associatedContract
Libraries¶
SafeDecimalMath
foruint
SafeMath
foruint
Structs¶
IssuanceData¶
Individual wallets have an issuance data object associated with their address. This holds the issuance state and preferred currency of users in the Oikos system, which is used to compute user's exit price and collateralisation ratio.
Field | Type | Description |
---|---|---|
initialDebtOwnership | uint |
The percentage of the total system debt owned by the address associated with this entry at the time of issuance. |
debtEntryIndex | uint |
The debt ledger index when this user last issued or destroyed tokens. That is, the length of the ledger at the time of issuance. |
This struct is replicated in the FeePoolState
contract.
Variables¶
issuanceData
¶
The most recent issuance data for each address.
Type: mapping(address => IssuanceData) public
totalIssuerCount
¶
The number of people with outstanding synths.
Type: uint public
debtLedger
¶
A list of factors indicating, for each debt-modifying event, what effect it had on the percentage of debt of all other holders. Later debt ledger entries correspond to more recent issuance events.
Type: uint[] public
importedXDRAmount
¶
The XDR-equivalent debt of oUSD
imported which was outstanding immediately before the multicurrency transition.
Type: uint public
issuanceRatio
¶
The current global issuance ratio, which is the conversion factor between a value of OKS and the value of synths issued against them. As a result this determines the maximum ratio between the total value of Synths and OKS in the system.
It is also the target ratio for OKS stakers. As per the logic in FeePool.feesClaimable
, stakers can only claim any fee rewards if they are within ten percent of the issuance ratio. Therefore altering it will also alter the maximum total supply of Synths, as suppliers of Synths are strongly incentivised to track the issuance ratio closely.
If the issuance ratio is \rho, then the maximum value V_s of a synth s issuable against a value V_c of OKS collateral is just:
Given that currency is worth its price times its quantity (V_x = \pi_x \ Q_x), we have:
This implies that the quantity of synths received upon issuance is the quantity of collateral staked, multiplied by the issuance ratio and the ratio between the collateral and synth prices.
As a result of this calculation, the number of synths that can be issued increases as the OKS price increases, but decreases as the synth price increases. Since neither market prices nor synth supply can be controlled directly, the remaining parameter, the issuance ratio, is an important way of affecting these quantities.
The Issuance Ratio as a Macro-Economic Lever
Tweaking the issuance ratio is an effective means of altering the total synth supply, and therefore its price.
In cases where Synths are oversupplied, there is downward price pressure and decreased stability. Decreasing the issuance ratio both constrains the total supply of Synths circulating in the system, and transiently increases aggregate demand for Synths as every staker must rebuy a quantity of Synths and burn them.
For precisely these reasons the issuance ratio was altered by SCCP-2 from its initial value of \frac{1}{5} to \frac{2}{15}.
The related case of increasing the issuance ratio is similar.
Type: uint public
MAX_ISSUANCE_RATIO
¶
Constraining the value of issuanceRatio
to be less than 1.0 ensures that Oikos does not become a fractional reserve system.
Type: uint constant
Value: UNIT
preferredCurrency
¶
Disabled
This feature is currently dormant. It can still operate, but the Oikos
contract does not expose any means for an account's preferred currency to actually be set, so it never operates.
If users nominate a preferred currency, all synths they receive will be converted to this currency. This mapping stores the nominated preferred currency for each account, if any. A null preferred currency means no conversion will be performed.
This is used within Synth._internalTransfer
.
Type: mapping(address => bytes4) public
Short Currency Keys
Note that as of SIP-17 currency keys in other contracts are of the bytes32
type. This means that if this preferred currency component is ever reused, it will only be able to support short-named synths unless new storage is provided.
Functions¶
constructor
¶
Initialises the inherited State
and LimitedSetup
instances.
Details
Signature
constructor(address _owner, address _associatedContract) public
Superconstructors
setCurrentIssuanceData
¶
Allows the Oikos
contract to update the debt ownership entry for this account and sets their debt entry index to the current length of the debtLedger
.
The debt ledger itself is not modified.
Details
Signature
setCurrentIssuanceData(address account, uint initialDebtOwnership) external
Modifiers
clearIssuanceData
¶
Deletes the issuance data associated with a given account.
incrementTotalIssuerCount
¶
Increases totalIssuerCount
by one. This is called within Oikos._addToDebtRegister
whenever an account with no outstanding issuance debt mints new Synths.
decrementTotalIssuerCount
¶
Reduces totalIssuerCount
by one. This is called within Oikos._removeFromDebtRegister
whenever an issuer burns enough Synths to pay down their entire outstanding debt.
appendDebtLedgerValue
¶
Pushes a new value to the end of the debtLedger
.
This is used by Oikos._addToDebtRegister
contract whenever Synths are issued or burnt, which modifies the total outstanding system debt.
setPreferredCurrency
¶
Disabled
This function is not used anywhere within the Oikos
contract, which is the only address with the privileges to call it. As a result the preferred currency feature is not operational.
Sets the preferred currency for a particular account. Pass in null to unset this value.
Details
Signature
setPreferredCurrency(address account, bytes4 currencyKey) external
Modifiers
setIssuanceRatio
¶
Allows the owner to set the Synth issuance ratio, but disallows setting it higher than 1.0, which prevents more than one dollar worth of Synths being issued against each dollar of OKS backing them.
Details
Signature
setIssuanceRatio(uint _issuanceRatio) external`
Modifiers
Preconditions
_issuanceRatio
cannot exceedMAX_ISSUANCE_RATIO
, which is set to1.0
.
Emits
importIssuerData
¶
Disabled
This function only operated during the one week setup period.
This function allowed the owner to migrate oUSD issuance data during the launch of multiple Synth flavours. It simply calls _addToDebtRegister
in a loop.
Details
Signature
importIssuerData(address[] accounts, uint[] oUSDAmounts) external
Modifiers
Preconditions
- The
XDR
price must not be stale.
_addToDebtRegister(address account, uint amount)
¶
Disabled
This function is only called from importIssuerData
, which only operated during the one week setup period.
This utility function allows adds a new entry to the debt register to set up staker debt holdings when migrating from the previous Oikos version.
It duplicates the logic of Oikos._addToDebtRegister
with some minor modifications to keep track of how much debt has been imported.
Details
Signature
_addToDebtRegister(address account, uint amount) internal
debtLedgerLength
¶
Returns the number of entries currently in debtLedger
.
Primarily used in FeePool
for fee period computations.
Details
Signature
debtLedgerLength() external view returns (uint)
lastDebtLedgerEntry
¶
Returns the most recent debtLedger
entry.
Primarily used in the Oikos
for debt computations.
Details
Signature
lastDebtLedgerEntry() external view returns (uint)
hasIssued
¶
Returns true if a given account has any outstanding issuance debt resulting from Synth minting.
Used in Oikos._addToDebtRegister
to determine whether an minting event requires incrementing the total issuer count.
Details
Signature
hasIssued(address account) external view returns (uint)
Events¶
IssuanceRatioUpdated
¶
Records that the issuance ratio was modified.
Signature: IssuanceRatioUpdated(uint newRatio)