FeePoolState¶
Description¶
This contract composes persistent state storage for the issuance percentage and index for each address interacting with the fee pool. These details are stored for the last six fee periods.
As a persistent state contract, FeePoolState is not intended to be easily upgraded, as opposed to the FeePool itself, which is so intended.
See FeePool.feesByPeriod and FeePool.effectiveDebtRatioForPeriod for discussion of the meaning of this information held in this contract and how it is used.
Caution: The Number of Stored Fee Periods
Note that this contract contains storage for up to six fee periods, while the FeePool contract limits it to only three. This is a consequence of the implementation of SIP 4, which reduced the fee window in the main FeePool contract in order to encourage faster responses to alterations of system incentives. As part of this process, this storage contract was, of course, not upgraded.
See also: Design_Decisions.md.
Source: contracts/FeePoolState.sol
Architecture¶
Related Contracts¶
- <>FeePool
Structs¶
IssuanceData¶
Holds the issuance state and index of users interacting with the FeePool for the last several fee periods.
For more information on these fields and their meaning, see the main Synthetix contract functions _addToDebtRegister and _removeFromDebtRegister, along with the corresponding struct in SynthetixState.
Relationship with SynthetixState
This is the same struct as SynthetixState.issuanceData, modulo naming, but in the case of SynthetixState, only one entry is kept, corresponding to only the most recent issuance event associated with an address.
This induces a slightly awkward structure where the current and historical issuance information is stored over two separate contracts. In a future version this information could potentially be stored in a unified structure for dividends in efficiency and clarity.
| Field | Type | Description |
|---|---|---|
debtPercentage |
uint256 |
The percentage of the total system debt owned by the address associated with this entry at the time of issuance. These are 27-decimal fixed point numbers, closely related to the values in SynthetixState.debtLedger. |
debtEntryIndex |
uint256 |
The debt ledger index when this user issued or destroyed tokens. That is, the length of the ledger at the time of issuance. |
Variables¶
FEE_PERIOD_LENGTH¶
The number of fee periods (6) worth of issuance data to keep. Note the inconsistency with the corresponding constant in FeePool, which is set to 3.
Value: 6
Type: uint8
accountIssuanceLedger¶
A list of up to 6 issuance data entries for each address, for the most recent changes to their issuance level. The fee periods do not have to be consecutive, but they are ordered from newest to oldest (decreasing debt ledger indexes).
Note that the entry accountIssuanceLedger[account][0] only corresponds to the current fee period if appendAccountIssuanceRecord(account, *, *, *) has been called during the current fee period. That is, if the account has issued or burnt synths this period.
Type: mapping(address => struct FeePoolState.IssuanceData[6])
feePool¶
The address of the main FeePool contract.
Type: address
Constructor¶
constructor¶
Initialises the fee pool address, as well as the inherited SelfDestructible and LimitedSetup instances. The setup period is initialised to six weeks.
Details
Signature
constructor(address _owner, contract IFeePool _feePool)
Visibility
public
State Mutability
``
Views¶
applicableIssuanceData¶
From a given account's issuance data, retrieve the most recent entry which closed before the provided index. If there is no such entry, (0,0) is returned.
This function is used in FeePool.feesByPeriod and FeePool.effectiveDebtRatioForPeriod to compute the fees owed to a user for specific past periods.
The returned values are as per getAccountsDebtEntry, hence the first return value is a 27-decimal fixed point number.
Details
Signature
applicableIssuanceData(address account, uint256 closingDebtIndex) view returns (uint256, uint256)
Visibility
external
State Mutability
view
getAccountsDebtEntry¶
Accesses accountIssuanceLedger.
The first return value is a 27-decimal fixed point number.
Details
Signature
getAccountsDebtEntry(address account, uint256 index) view returns (uint256 debtPercentage, uint256 debtEntryIndex)
Visibility
public
State Mutability
view
Requires
Restricted Functions¶
appendAccountIssuanceRecord¶
Allows the Synthetix contract, through FeePool.appendAccountIssuanceRecord, to record current fee period issuance information for a given account in the issuance ledger. This is used when synths are issued or burnt.
If the latest entry in this account's issuance ledger was from the current fee period, it is overwritten. Otherwise, the existing entries are shifted down one spot, dropping the last one (using a call to issuanceDataIndexOrder), and a new entry is added at the head of the list.
The debtRatio argument is a 27-decimal fixed point number.
Details
Signature
appendAccountIssuanceRecord(address account, uint256 debtRatio, uint256 debtEntryIndex, uint256 currentPeriodStartDebtIndex)
Visibility
external
State Mutability
``
Modifiers
importIssuerData¶
This function was used during the initial six week setup period to initialise the issuance ledger from the previous Synthetix version.
Details
Signature
importIssuerData(address[] accounts, uint256[] ratios, uint256 periodToInsert, uint256 feePeriodCloseIndex)
Visibility
external
State Mutability
``
Requires
Modifiers
setFeePool¶
Changes the fee pool address.
Details
Signature
setFeePool(contract IFeePool _feePool)
Visibility
external
State Mutability
``
Modifiers
Modifiers¶
onlyFeePool¶
Reverts the transaction if msg.sender is not the fee pool address.
Events¶
IssuanceDebtRatioEntry¶
Record that an entry was updated in the issuance ledger by the importIssuerData function during the setup period.
Signature: IssuanceDebtRatioEntry(address account, uint256 debtRatio, uint256 feePeriodCloseIndex)