# 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¶

• Oikos as this contract's State.associatedContract

## 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

### 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.

Details

Signature

clearIssuanceData(address account) external

Modifiers

### 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

### 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

### 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

### 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

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

### _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)`