`Ftso`#

An instance of this contract is created for each tracked asset, and typically accessed through the FtsoRegistry. Data providers do not access the Ftso instances directly either, and use the PriceSubmitter contract instead.

Functions#

`activateFtso`#

Defined in Ftso (Docs, Source).

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

Initializes FTSO immutable settings and activates the contract.

Can only be called by the ftsoManager.

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 Ftso (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.

Can only be called by the ftsoManager. Should never revert if called from ftsoManager.

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.

`constructor`#

Defined in Ftso (Docs, Source).

constructor(
    string _symbol,
    uint256 _decimals,
    contract IPriceSubmitter _priceSubmitter,
    contract IIVPToken _wNat,
    address _ftsoManager,
    uint256 _firstEpochStartTs,
    uint256 _submitPeriodSeconds,
    uint256 _revealPeriodSeconds,
    uint128 _initialPriceUSD,
    uint256 _priceDeviationThresholdBIPS,
    uint256 _cyclicBufferSize
) public;

`deactivateFtso`#

Defined in Ftso (Docs, Source).

function deactivateFtso(
) external;

Deactivates the contract.

Can only be called by the ftsoManager.

`epochsConfiguration`#

Defined in Ftso (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 Ftso (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.

Can only be called by the ftsoManager.

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

`finalizePriceEpoch`#

Defined in Ftso (Docs, Source).

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

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.

Can only be called by the ftsoManager, and only at the correct time.

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.
`_natWeightsSum`	`uint256`

`forceFinalizePriceEpoch`#

Defined in Ftso (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.

Can only be called by the ftsoManager.

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 Ftso (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 Ftso (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 Ftso (Docs, Source).

function getCurrentEpochId(
) public view returns (
    uint256);

Returns the current epoch ID.

It never reverts.

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

`getCurrentPrice`#

Defined in Ftso (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 Ftso (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 Ftso (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 Ftso (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 Ftso (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 Ftso (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.

It never reverts.

`getEpochId`#

Defined in Ftso (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.

It never reverts.

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 Ftso (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 Ftso (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 Ftso (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 Ftso (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 Ftso (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 Ftso (Docs, Source).

function initializeCurrentEpochStateForReveal(
    uint256 _circulatingSupplyNat,
    bool _fallbackMode
) external;

Initializes current epoch instance for reveal.

Can only be called by the ftsoManager.

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

`revealPriceSubmitter`#

Defined in Ftso (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

Emits a PriceRevealed event. Can only be called by the priceSubmitter.

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 Ftso (Docs, Source).

function setAsset(
    contract IIVPToken _asset
) external;

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

Can only be called by the ftsoManager.

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

`setAssetFtsos`#

Defined in Ftso (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.

Can only be called by the ftsoManager.

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

`setVotePowerBlock`#

Defined in Ftso (Docs, Source).

function setVotePowerBlock(
    uint256 _votePowerBlock
) 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.

Can only be called by the ftsoManager.

Parameters	Type	Description
`_votePowerBlock`	`uint256`

`symbol`#

Defined in IFtso (Docs, Source).

function symbol(
) external view returns (
    string);

Returns the FTSO symbol.

`updateInitialPrice`#

Defined in Ftso (Docs, Source).

function updateInitialPrice(
    uint256 _initialPriceUSD,
    uint256 _initialPriceTimestamp
) external;

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

Can only be called by the ftsoManager.

`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 Ftso (Docs, Source).

function wNatVotePowerCached(
    address _owner,
    uint256 _epochId
) public returns (
    uint256);

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

Parameters	Type	Description
`_owner`	`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.

Modifiers#

`onlyFtsoManager`#

Defined in Ftso (Docs, Source).

modifier onlyFtsoManager()

Only the ftsoManager can call this method.

`onlyPriceSubmitter`#

Defined in Ftso (Docs, Source).

modifier onlyPriceSubmitter()

Only the priceSubmitter can call this method.

`whenActive`#

Defined in Ftso (Docs, Source).

modifier whenActive()

This method can only be called when the FTSO is active.

Structures#

`RewardData`#

Defined in Ftso (Docs, Source).

struct RewardData {
  uint256[] weightIQR;
  uint256[] weightElasticBand;
  uint256 weightsIQRSum;
  uint256 weightsElasticBandSum;
  uint256 numberOfVotes;
  uint256 elasticBandRewardBIPS;
}

Variables#

`ASSET_PRICE_USD_DECIMALS`#

Defined in Ftso (Docs, Source).

    uint256 ASSET_PRICE_USD_DECIMALS

Number of decimal places in an asset's USD price. Actual USD price is the integer value divided by 10^ASSET_PRICE_USD_DECIMALS

`active`#

Defined in Ftso (Docs, Source).

    bool active

Activation status of this FTSO.

`assetFtsos`#

Defined in Ftso (Docs, Source).

    contract IIFtso[] assetFtsos

Array of addresses of other Ftso contracts tracked by this multi-asset FTSO.

`assets`#

Defined in Ftso (Docs, Source).

    contract IIVPToken[] assets

Array of addresses of the tracked assets.

`ftsoManager`#

Defined in Ftso (Docs, Source).

    address ftsoManager

Address of the FtsoManager contract.

`priceDeviationThresholdBIPS`#

Defined in Ftso (Docs, Source).

    uint256 priceDeviationThresholdBIPS

Threshold for price deviation between consecutive epochs.

`priceEpochCyclicBufferSize`#

Defined in Ftso (Docs, Source).

    uint256 priceEpochCyclicBufferSize

Amount of stored prices for past epochs, set at construction time.

`priceSubmitter`#

Defined in Ftso (Docs, Source).

    contract IPriceSubmitter priceSubmitter

Address of the PriceSubmitter contract.

`symbol`#

Defined in Ftso (Docs, Source).

    string symbol

Asset symbol that identifies this FTSO.

`wNat`#

Defined in Ftso (Docs, Source).

    contract IIVPToken wNat

Address of the wrapped native token (WNat) contract.

Ftso#

Functions#

activateFtso#

active#

configureEpochs#

constructor#

deactivateFtso#

epochsConfiguration#

fallbackFinalizePriceEpoch#

finalizePriceEpoch#

forceFinalizePriceEpoch#

ftsoManager#

getAsset#

getAssetFtsos#

getCurrentEpochId#

getCurrentPrice#

getCurrentPriceDetails#

getCurrentPriceFromTrustedProviders#

getCurrentPriceWithDecimals#

getCurrentPriceWithDecimalsFromTrustedProviders#

getCurrentRandom#

getEpochId#

getEpochPrice#

getEpochPriceForVoter#

getPriceEpochConfiguration#

getPriceEpochData#

getRandom#

getVoteWeightingParameters#

initializeCurrentEpochStateForReveal#

revealPriceSubmitter#

setAsset#

setAssetFtsos#

setVotePowerBlock#

symbol#

updateInitialPrice#

wNat#

wNatVotePowerCached#

Modifiers#

onlyFtsoManager#

onlyPriceSubmitter#

whenActive#

Structures#

RewardData#

Variables#

ASSET_PRICE_USD_DECIMALS#

active#

assetFtsos#

assets#

ftsoManager#

priceDeviationThresholdBIPS#

priceEpochCyclicBufferSize#

priceSubmitter#

symbol#

wNat#

`Ftso`#

`activateFtso`#

`active`#

`configureEpochs`#

`constructor`#

`deactivateFtso`#

`epochsConfiguration`#

`fallbackFinalizePriceEpoch`#

`finalizePriceEpoch`#

`forceFinalizePriceEpoch`#

`ftsoManager`#

`getAsset`#

`getAssetFtsos`#

`getCurrentEpochId`#

`getCurrentPrice`#

`getCurrentPriceDetails`#

`getCurrentPriceFromTrustedProviders`#

`getCurrentPriceWithDecimals`#

`getCurrentPriceWithDecimalsFromTrustedProviders`#

`getCurrentRandom`#

`getEpochId`#

`getEpochPrice`#

`getEpochPriceForVoter`#

`getPriceEpochConfiguration`#

`getPriceEpochData`#

`getRandom`#

`getVoteWeightingParameters`#

`initializeCurrentEpochStateForReveal`#

`revealPriceSubmitter`#

`setAsset`#

`setAssetFtsos`#

`setVotePowerBlock`#

`symbol`#

`updateInitialPrice`#

`wNat`#

`wNatVotePowerCached`#

`onlyFtsoManager`#

`onlyPriceSubmitter`#

`whenActive`#

`RewardData`#

`ASSET_PRICE_USD_DECIMALS`#

`active`#

`assetFtsos`#

`assets`#

`ftsoManager`#

`priceDeviationThresholdBIPS`#

`priceEpochCyclicBufferSize`#

`priceSubmitter`#

`symbol`#

`wNat`#