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 for uint
• SafeMath for uint

---

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:

$$V_s = \rho \ V_c$$

Given that currency is worth its price times its quantity ($V_x = \pi_x \ Q_x$), we have:

$$\pi_s \ Q_s = \rho \ \pi_c \ Q_c$$

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.

$$Q_s = \rho \ \frac{\pi_c}{\pi_s} \ Q_c$$

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

• State(_owner, _associatedContract)
• LimitedSetup(1 weeks)

---

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

• State.onlyAssociatedContract

---

clearIssuanceData

Deletes the issuance data associated with a given account.

Details

Signature

clearIssuanceData(address account) external

Modifiers

• State.onlyAssociatedContract

---

incrementTotalIssuerCount

Increases totalIssuerCount by one. This is called within Oikos._addToDebtRegister whenever an account with no outstanding issuance debt mints new Synths.

Details

Signature

incrementTotalIssuerCount() external

Modifiers

• State.onlyAssociatedContract

---

decrementTotalIssuerCount

Reduces totalIssuerCount by one. This is called within Oikos._removeFromDebtRegister whenever an issuer burns enough Synths to pay down their entire outstanding debt.

Details

Signature

decrementTotalIssuerCount() external

Modifiers

• State.onlyAssociatedContract

---

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.

Details

Signature

appendDebtLedgerValue(uint value) external

Modifiers

• State.onlyAssociatedContract

---

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

• State.onlyAssociatedContract

---

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

• Owned.onlyOwner

Preconditions

• _issuanceRatio cannot exceed MAX_ISSUANCE_RATIO, which is set to 1.0.

Emits

• IssuanceRatioUpdated(_issuanceRatio)

---

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

• Owned.onlyOwner
• LimitedSetup.onlyDuringSetup

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)

---