Skip to content

IIFtso#

Source | Inherits from IFtso, IFtsoGenesis

Internal interface for each of the FTSO contracts that handles an asset. Read the FTSO documentation page for general information about the FTSO system.

Functions#

activateFtso#

Defined in IIFtso (Docs, Source).

function activateFtso(
    uint256 _firstEpochStartTs,
    uint256 _submitPeriodSeconds,
    uint256 _revealPeriodSeconds
) external;

Initializes FTSO immutable settings and activates the contract.

Parameters Type Description
_firstEpochStartTs uint256 Timestamp of the first epoch in seconds from UNIX epoch.
_submitPeriodSeconds uint256 Duration of epoch submission window in seconds.
_revealPeriodSeconds uint256 Duration of epoch reveal window in seconds.

active#

Defined in IFtso (Docs, Source).

function active(
) external view returns (
    bool);

Returns whether FTSO is active or not.

configureEpochs#

Defined in IIFtso (Docs, Source).

function configureEpochs(
    uint256 _maxVotePowerNatThresholdFraction,
    uint256 _maxVotePowerAssetThresholdFraction,
    uint256 _lowAssetUSDThreshold,
    uint256 _highAssetUSDThreshold,
    uint256 _highAssetTurnoutThresholdBIPS,
    uint256 _lowNatTurnoutThresholdBIPS,
    uint256 _elasticBandRewardBIPS,
    uint256 _elasticBandWidthPPM,
    address[] _trustedAddresses
) external;

Sets configurable settings related to epochs.

Parameters Type Description
_maxVotePowerNatThresholdFraction uint256 High threshold for native token vote power per voter.
_maxVotePowerAssetThresholdFraction uint256 High threshold for asset vote power per voter.
_lowAssetUSDThreshold uint256 Threshold for low asset vote power (in scaled USD).
_highAssetUSDThreshold uint256 Threshold for high asset vote power (in scaled USD).
_highAssetTurnoutThresholdBIPS uint256 Threshold for high asset turnout (in BIPS).
_lowNatTurnoutThresholdBIPS uint256 Threshold for low nat turnout (in BIPS).
_elasticBandRewardBIPS uint256 Percentage of the rewards (in BIPS) that go to the secondary reward band. The rest go to the primary reward band.
_elasticBandWidthPPM uint256 Width of the secondary reward band, in parts-per-milion of the median.
_trustedAddresses address[] Trusted voters that will be used if low voter turnout is detected.

deactivateFtso#

Defined in IIFtso (Docs, Source).

function deactivateFtso(
) external;

Deactivates the contract.

epochsConfiguration#

Defined in IIFtso (Docs, Source).

function epochsConfiguration(
) external view returns (
    uint256 _maxVotePowerNatThresholdFraction,
    uint256 _maxVotePowerAssetThresholdFraction,
    uint256 _lowAssetUSDThreshold,
    uint256 _highAssetUSDThreshold,
    uint256 _highAssetTurnoutThresholdBIPS,
    uint256 _lowNatTurnoutThresholdBIPS,
    uint256 _elasticBandRewardBIPS,
    uint256 _elasticBandWidthPPM,
    address[] _trustedAddresses);

Returns current configuration of epoch state.

Returns Type Description
_maxVotePowerNatThresholdFraction uint256 High threshold for native token vote power per voter.
_maxVotePowerAssetThresholdFraction uint256 High threshold for asset vote power per voter.
_lowAssetUSDThreshold uint256 Threshold for low asset vote power (in scaled USD).
_highAssetUSDThreshold uint256 Threshold for high asset vote power (in scaled USD).
_highAssetTurnoutThresholdBIPS uint256 Threshold for high asset turnout (in BIPS).
_lowNatTurnoutThresholdBIPS uint256 Threshold for low nat turnout (in BIPS).
_elasticBandRewardBIPS uint256 Percentage of the rewards (in BIPS) that go to the secondary reward band. The rest go to the primary reward band.
_elasticBandWidthPPM uint256 Width of the secondary reward band, in parts-per-milion of the median.
_trustedAddresses address[] Trusted voters that will be used if low voter turnout is detected.

fallbackFinalizePriceEpoch#

Defined in IIFtso (Docs, Source).

function fallbackFinalizePriceEpoch(
    uint256 _epochId
) external;

Forces finalization of a price epoch, calculating the median price from trusted addresses only.

Used as a fallback method, for example, due to an unexpected error during normal epoch finalization or because the ftsoManager enabled the fallback mode.

Parameters Type Description
_epochId uint256 ID of the epoch to finalize.

finalizePriceEpoch#

Defined in IIFtso (Docs, Source).

function finalizePriceEpoch(
    uint256 _epochId,
    bool _returnRewardData
) external returns (
    address[] _eligibleAddresses,
    uint256[] _natWeights,
    uint256 _totalNatWeight);

Computes epoch price based on gathered votes.

  • If the price reveal window for the epoch has ended, finalize the epoch.
  • Iterate list of price submissions.
  • Find weighted median.
  • Find adjacent 50% of price submissions.
  • Allocate rewards for price submissions.
Parameters Type Description
_epochId uint256 ID of the epoch to finalize.
_returnRewardData bool Parameter that determines if the reward data is returned.
Returns Type Description
_eligibleAddresses address[] List of addresses eligible for reward.
_natWeights uint256[] List of native token weights corresponding to the eligible addresses.
_totalNatWeight uint256 Sum of weights in _natWeights.

forceFinalizePriceEpoch#

Defined in IIFtso (Docs, Source).

function forceFinalizePriceEpoch(
    uint256 _epochId
) external;

Forces finalization of a price epoch by copying the price from the previous epoch.

Used as a fallback method if fallbackFinalizePriceEpoch fails due to an exception.

Parameters Type Description
_epochId uint256 ID of the epoch to finalize.

ftsoManager#

Defined in IIFtso (Docs, Source).

function ftsoManager(
) external view returns (
    address);

Returns the FTSO manager's address.

Returns Type Description
[0] address Address of the FTSO manager contract.

getAsset#

Defined in IIFtso (Docs, Source).

function getAsset(
) external view returns (
    contract IIVPToken);

Returns the FTSO asset.

Returns Type Description
[0] contract IIVPToken Address of the IIVPToken tracked by this FTSO. null in case of multi-asset FTSO.

getAssetFtsos#

Defined in IIFtso (Docs, Source).

function getAssetFtsos(
) external view returns (
    contract IIFtso[]);

Returns the asset FTSOs.

Returns Type Description
[0] contract IIFtso[] Array of IIFtso contract addresses. null in case of single-asset FTSO.

getCurrentEpochId#

Defined in IFtso (Docs, Source).

function getCurrentEpochId(
) external view returns (
    uint256);

Returns the current epoch ID.

Returns Type Description
[0] uint256 Currently running epoch ID. IDs are consecutive numbers starting from zero.

getCurrentPrice#

Defined in IFtso (Docs, Source).

function getCurrentPrice(
) external view returns (
    uint256 _price,
    uint256 _timestamp);

Returns the current asset price.

Returns Type Description
_price uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.
_timestamp uint256 Time when price was updated for the last time, in seconds from UNIX epoch.

getCurrentPriceDetails#

Defined in IFtso (Docs, Source).

function getCurrentPriceDetails(
) external view returns (
    uint256 _price,
    uint256 _priceTimestamp,
    enum IFtso.PriceFinalizationType _priceFinalizationType,
    uint256 _lastPriceEpochFinalizationTimestamp,
    enum IFtso.PriceFinalizationType _lastPriceEpochFinalizationType);

Returns asset's current price details. All timestamps are in seconds from UNIX epoch.

Returns Type Description
_price uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.
_priceTimestamp uint256 Time when price was updated for the last time.
_priceFinalizationType enum IFtso.PriceFinalizationType Finalization type when price was updated for the last time.
_lastPriceEpochFinalizationTimestamp uint256 Time when last price epoch was finalized.
_lastPriceEpochFinalizationType enum IFtso.PriceFinalizationType Finalization type of last finalized price epoch.

getCurrentPriceFromTrustedProviders#

Defined in IFtso (Docs, Source).

function getCurrentPriceFromTrustedProviders(
) external view returns (
    uint256 _price,
    uint256 _timestamp);

Returns current asset price calculated only using input from trusted providers.

Returns Type Description
_price uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.
_timestamp uint256 Time when price was updated for the last time, in seconds from UNIX epoch.

getCurrentPriceWithDecimals#

Defined in IFtso (Docs, Source).

function getCurrentPriceWithDecimals(
) external view returns (
    uint256 _price,
    uint256 _timestamp,
    uint256 _assetPriceUsdDecimals);

Returns current asset price and number of decimals.

Returns Type Description
_price uint256 Price in USD multiplied by 10^_assetPriceUsdDecimals.
_timestamp uint256 Time when price was updated for the last time, in seconds from UNIX epoch.
_assetPriceUsdDecimals uint256 Number of decimals used to return the USD price.

getCurrentPriceWithDecimalsFromTrustedProviders#

Defined in IFtso (Docs, Source).

function getCurrentPriceWithDecimalsFromTrustedProviders(
) external view returns (
    uint256 _price,
    uint256 _timestamp,
    uint256 _assetPriceUsdDecimals);

Returns current asset price calculated only using input from trusted providers and number of decimals.

Returns Type Description
_price uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.
_timestamp uint256 Time when price was updated for the last time, in seconds from UNIX epoch.
_assetPriceUsdDecimals uint256 Number of decimals used to return the USD price.

getCurrentRandom#

Defined in IFtso (Docs, Source).

function getCurrentRandom(
) external view returns (
    uint256);

Returns the random number for the previous price epoch, obtained from the random numbers provided by all data providers along with their data submissions.

getEpochId#

Defined in IFtso (Docs, Source).

function getEpochId(
    uint256 _timestamp
) external view returns (
    uint256);

Returns the ID of the epoch that was opened for price submission at the specified timestamp.

Parameters Type Description
_timestamp uint256 Queried timestamp in seconds from UNIX epoch.
Returns Type Description
[0] uint256 Epoch ID corresponding to that timestamp. IDs are consecutive numbers starting from zero.

getEpochPrice#

Defined in IFtso (Docs, Source).

function getEpochPrice(
    uint256 _epochId
) external view returns (
    uint256);

Returns agreed asset price in the specified epoch.

Parameters Type Description
_epochId uint256 ID of the epoch. Only the last 200 epochs can be queried. Out-of-bounds queries revert.
Returns Type Description
[0] uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.

getEpochPriceForVoter#

Defined in IFtso (Docs, Source).

function getEpochPriceForVoter(
    uint256 _epochId,
    address _voter
) external view returns (
    uint256);

Returns asset price submitted by a voter in the specified epoch.

Parameters Type Description
_epochId uint256 ID of the epoch being queried. Only the last 200 epochs can be queried. Out-of-bounds queries revert.
_voter address Address of the voter being queried.
Returns Type Description
[0] uint256 Price in USD multiplied by 10^ASSET_PRICE_USD_DECIMALS.

getPriceEpochConfiguration#

Defined in IFtso (Docs, Source).

function getPriceEpochConfiguration(
) external view returns (
    uint256 _firstEpochStartTs,
    uint256 _submitPeriodSeconds,
    uint256 _revealPeriodSeconds);

Returns current epoch's configuration.

Returns Type Description
_firstEpochStartTs uint256 First epoch start timestamp in seconds from UNIX epoch.
_submitPeriodSeconds uint256 Submit period in seconds.
_revealPeriodSeconds uint256 Reveal period in seconds.

getPriceEpochData#

Defined in IFtso (Docs, Source).

function getPriceEpochData(
) external view returns (
    uint256 _epochId,
    uint256 _epochSubmitEndTime,
    uint256 _epochRevealEndTime,
    uint256 _votePowerBlock,
    bool _fallbackMode);

Returns current epoch data. Intervals are open on the right: End times are not included.

Returns Type Description
_epochId uint256 Current epoch ID.
_epochSubmitEndTime uint256 End time of the price submission window in seconds from UNIX epoch.
_epochRevealEndTime uint256 End time of the price reveal window in seconds from UNIX epoch.
_votePowerBlock uint256 Vote power block for the current epoch.
_fallbackMode bool Whether the current epoch is in fallback mode. Only votes from trusted addresses are used in this mode.

getRandom#

Defined in IFtso (Docs, Source).

function getRandom(
    uint256 _epochId
) external view returns (
    uint256);

Returns the random number used in a specific past epoch, obtained from the random numbers provided by all data providers along with their data submissions.

Parameters Type Description
_epochId uint256 ID of the queried epoch. Current epoch cannot be queried, and the previous epoch is constantly updated as data providers reveal their prices and random numbers. Only the last 50 epochs can be queried and there is no bounds checking for this parameter. Out-of-bounds queries return undefined values.
Returns Type Description
[0] uint256 The random number used in that epoch.

getVoteWeightingParameters#

Defined in IIFtso (Docs, Source).

function getVoteWeightingParameters(
) external view returns (
    contract IIVPToken[] _assets,
    uint256[] _assetMultipliers,
    uint256 _totalVotePowerNat,
    uint256 _totalVotePowerAsset,
    uint256 _assetWeightRatio,
    uint256 _votePowerBlock);

Returns parameters necessary for replicating vote weighting (used in VoterWhitelister).

Returns Type Description
_assets contract IIVPToken[] The list of assets that are accounted in vote.
_assetMultipliers uint256[] Weight multiplier of each asset in (multiasset) FTSO.
_totalVotePowerNat uint256 Total native token vote power at block.
_totalVotePowerAsset uint256 Total combined asset vote power at block.
_assetWeightRatio uint256 Ratio of combined asset vote power vs. native token vp (in BIPS).
_votePowerBlock uint256 Vote power block for the epoch.

initializeCurrentEpochStateForReveal#

Defined in IIFtso (Docs, Source).

function initializeCurrentEpochStateForReveal(
    uint256 _circulatingSupplyNat,
    bool _fallbackMode
) external;

Initializes current epoch instance for reveal.

Parameters Type Description
_circulatingSupplyNat uint256 Epoch native token circulating supply.
_fallbackMode bool Whether the current epoch is in fallback mode.

revealPriceSubmitter#

Defined in IFtsoGenesis (Docs, Source).

function revealPriceSubmitter(
    address _voter,
    uint256 _epochId,
    uint256 _price,
    uint256 _voterWNatVP
) external;

Reveals the price submitted by a voter on a specific epoch. The hash of _price and _random must be equal to the submitted hash

Parameters Type Description
_voter address Voter address.
_epochId uint256 ID of the epoch in which the price hash was submitted.
_price uint256 Submitted price.
_voterWNatVP uint256 Voter's vote power in WNat units.

setAsset#

Defined in IIFtso (Docs, Source).

function setAsset(
    contract IIVPToken _asset
) external;

Sets asset for FTSO to operate as single-asset oracle.

Parameters Type Description
_asset contract IIVPToken Address of the IIVPToken contract that will be the asset tracked by this FTSO.

setAssetFtsos#

Defined in IIFtso (Docs, Source).

function setAssetFtsos(
    contract IIFtso[] _assetFtsos
) external;

Sets an array of FTSOs for FTSO to operate as multi-asset oracle. FTSOs implicitly determine the FTSO assets.

Parameters Type Description
_assetFtsos contract IIFtso[] Array of FTSOs.

setVotePowerBlock#

Defined in IIFtso (Docs, Source).

function setVotePowerBlock(
    uint256 _blockNumber
) external;

Sets the current vote power block. Current vote power block will update per reward epoch. The FTSO doesn't have notion of reward epochs.

Parameters Type Description
_blockNumber uint256 Vote power block.

symbol#

Defined in IFtso (Docs, Source).

function symbol(
) external view returns (
    string);

Returns the FTSO symbol.

updateInitialPrice#

Defined in IIFtso (Docs, Source).

function updateInitialPrice(
    uint256 _initialPriceUSD,
    uint256 _initialPriceTimestamp
) external;

Updates initial asset price when the contract is not active yet.

wNat#

Defined in IIFtso (Docs, Source).

function wNat(
) external view returns (
    contract IIVPToken);

Address of the WNat contract.

Returns Type Description
[0] contract IIVPToken Address of the WNat contract.

wNatVotePowerCached#

Defined in IFtsoGenesis (Docs, Source).

function wNatVotePowerCached(
    address _voter,
    uint256 _epochId
) external returns (
    uint256);

Get and cache the vote power of a voter on a specific epoch, in WNat units.

Parameters Type Description
_voter address Voter address.
_epochId uint256 ID of the epoch in which the price hash was submitted.
Returns Type Description
[0] uint256 Voter's vote power in WNat units.