FtsoV2Interface

Primary interface for interacting with FTSOv2. This is a long-term support (LTS) interface, designed to ensure continuity even as underlying contracts evolve or protocols migrate to new versions.

Sourced from FtsoV2Interface.sol on GitHub.

Functions

getFeedById

Returns stored data of a feed. A fee (calculated by the FeeCalculator contract) may need to be paid.

function getFeedById(
    bytes21 _feedId
) external payable returns (
    uint256 _value,
    int8 _decimals,
    uint64 _timestamp
);

Parameters

• _feedId: The id of the feed.

Returns

• _value: The value for the requested feed.
• _decimals: The decimal places for the requested feed.
• _timestamp: The timestamp of the last update.

Sample contract usage

FTSOV2FeedById.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
/* THIS IS A TEST IMPORT, in production use: import {FtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/FtsoV2Interface.sol"; */
import {TestFtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/TestFtsoV2Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */
contract FtsoV2FeedConsumerById {
    TestFtsoV2Interface internal ftsoV2;
    // Example Feed ID for FLR/USD
    bytes21 public feedId =
        bytes21(0x01464c522f55534400000000000000000000000000); // FLR/USD

    /**
     * Get the current value of a specific feed by its ID.
     * @return _feedValue The latest price value of the feed.
     * @return _decimals The decimal precision of the feed value.
     * @return _timestamp The timestamp of the last feed update.
     */
    function getFtsoV2FeedValueById()
        external
        payable
        returns (uint256 _feedValue, int8 _decimals, uint64 _timestamp)
    {
        /* THIS IS A TEST METHOD, in production use: ftsoV2 = ContractRegistry.getFtsoV2(); */
        ftsoV2 = ContractRegistry.getTestFtsoV2();
        /* Retrieves the latest value, decimals, and timestamp for the specified feed ID. */
        return ftsoV2.getFeedById(feedId);
    }
}

Open sample in Remix

getFeedByIdInWei

Returns value in wei and timestamp of a feed. A fee (calculated by the FeeCalculator contract) may need to be paid.

function getFeedByIdInWei(
    bytes21 _feedId
) external payable returns (
    uint256 _value,
    uint64 _timestamp
);

Parameters

• _feedId: The id of the feed.

Returns

• _value: The value for the requested feed in wei (i.e. with 18 decimal places).
• _timestamp: The timestamp of the last update.

Sample contract usage

FTSOV2FeedByIdWei.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
/* THIS IS A TEST IMPORT, in production use: import {FtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/FtsoV2Interface.sol"; */
import {TestFtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/TestFtsoV2Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */
contract FtsoV2FeedTracker {
    TestFtsoV2Interface internal ftsoV2;
    bytes21 public feedId =
        bytes21(0x01464c522f55534400000000000000000000000000); // FLR/USD

    // Event to track feed retrieval
    event FeedFetched(bytes21 feedId, uint256 valueInWei, uint64 timestamp);

    /**
     * Get the current value of a specific feed by its index, in wei.
     * @return _feedValue The latest price value of the feed in wei.
     * @return _timestamp The timestamp of the last update for the feed.
     */
    function getFeedValueByIdWei()
        external
        payable
        returns (uint256 _feedValue, uint64 _timestamp)
    {
        /* THIS IS A TEST METHOD, in production use: ftsoV2 = ContractRegistry.getFtsoV2(); */
        ftsoV2 = ContractRegistry.getTestFtsoV2();
        // Retrieve feed value and timestamp from the FtsoV2 contract
        (_feedValue, _timestamp) = ftsoV2.getFeedByIdInWei(feedId);

        // Emit an event to log the feed retrieval
        emit FeedFetched(feedId, _feedValue, _timestamp);
    }
}

Open sample in Remix

getFeedsById

Returns stored data of each feed. A fee (calculated by the FeeCalculator contract) may need to be paid.

function getFeedsById(
    bytes21[] _feedIds
) external payable returns (
    uint256[] _values,
    int8[] _decimals,
    uint64 _timestamp
);

Parameters

• _feedIds: The list of feed ids.

Returns

• _values: The list of values for the requested feeds.
• _decimals: The list of decimal places for the requested feeds.
• _timestamp: The timestamp of the last update.

Sample contract usage

FTSOV2FeedsById.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
/* THIS IS A TEST IMPORT, in production use: import {FtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/FtsoV2Interface.sol"; */
import {TestFtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/TestFtsoV2Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */
contract FtsoV2FeedConsumer {
    TestFtsoV2Interface internal ftsoV2;
    // Feed IDs, see https://dev.flare.network/ftso/feeds for full list
    bytes21[] public feedIds = [
        bytes21(0x01464c522f55534400000000000000000000000000), // FLR/USD
        bytes21(0x014254432f55534400000000000000000000000000), // BTC/USD
        bytes21(0x014554482f55534400000000000000000000000000) // ETH/USD
    ];

    /**
     * Get the current value of the feeds.
     */
    function getFtsoV2CurrentFeedValues()
        external
        returns (
            uint256[] memory _feedValues,
            int8[] memory _decimals,
            uint64 _timestamp
        )
    {
        /* THIS IS A TEST METHOD, in production use: ftsoV2 = ContractRegistry.getFtsoV2(); */
        ftsoV2 = ContractRegistry.getTestFtsoV2();
        /* Your custom feed consumption logic. In this example the values are just returned. */
        return ftsoV2.getFeedsById(feedIds);
    }
}

Open sample in Remix

getFeedsByIdInWei

Returns value of each feed and a timestamp. For some feeds, a fee (calculated by the FeeCalculator contract) may need to be paid.

function getFeedsByIdInWei(
    bytes21[] _feedIds
) external payable returns (
    uint256[] _values,
    uint64 _timestamp
);

Parameters

• _feedIds: Ids of the feeds.

Returns

• _values: The list of values for the requested feeds in wei (i.e. with 18 decimal places).
• _timestamp: The timestamp of the last update.

Sample contract usage

FTSOV2FeedsByIdWei.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
/* THIS IS A TEST IMPORT, in production use: import {FtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/FtsoV2Interface.sol"; */
import {TestFtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/TestFtsoV2Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */
contract FtsoV2FeedConsumer {
    // Feed IDs, see https://dev.flare.network/ftso/feeds for full list
    bytes21[] public feedIds = [
        bytes21(0x01464c522f55534400000000000000000000000000), // FLR/USD
        bytes21(0x014254432f55534400000000000000000000000000), // BTC/USD
        bytes21(0x014554482f55534400000000000000000000000000) // ETH/USD
    ];

    // Event to log feed values retrieval
    event FeedValuesRetrieved(
        bytes21[] indexed feedIds,
        uint256[] values,
        uint64 timestamp
    );

    /**
     * Get the current value of the feeds in wei.
     * A fee may be required for certain feeds, calculated by the FeeCalculator contract.
     * @param _feedIds The IDs of the feeds to retrieve values for.
     * @return _values The list of values for the requested feeds in wei.
     * @return _timestamp The timestamp of the last update.
     */
    function getFeedsByIdInWei(
        bytes21[] calldata _feedIds
    ) external view returns (uint256[] memory _values, uint64 _timestamp) {
        // Ensure that the length of the feed IDs is non-zero
        require(_feedIds.length > 0, "No feed IDs provided");

        /* THIS IS A TEST METHOD, in production use: ftsoV2 = ContractRegistry.getFtsoV2(); */
        TestFtsoV2Interface ftsoV2 = ContractRegistry.getTestFtsoV2();

        // Retrieve the feed values and timestamp from the FTSOv2 contract
        return ftsoV2.getFeedsByIdInWei(_feedIds);
    }
}

Open sample in Remix

verifyFeedData

Checks if the feed data is valid (i.e. is part of the confirmed Merkle tree).

function verifyFeedData(
    struct FtsoV2Interface.FeedDataWithProof _feedData
) external view returns (
    bool
);

Parameters

• _feedData: Structure containing data about the feed (FeedData structure) and Merkle proof.

Returns

• _0: true if the feed data is valid.

Sample contract usage

FTSOV2VerifyProof.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
import {FtsoV2Interface} from "@flarenetwork/flare-periphery-contracts/coston2/FtsoV2Interface.sol";
import {MerkleProof} from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

/**
 * @title FtsoV2FeedVerifier
 * @notice A contract to verify the validity of feed data against a confirmed Merkle tree.
 */
contract FtsoV2FeedVerifier {
    FtsoV2Interface internal ftsoV2;

    /**
     * Constructor initializes the FTSOv2 contract.
     */
    constructor() {
        // THIS IS A TEST METHOD, in production use: ftsoV2 = ContractRegistry.getFtsoV2();
        ftsoV2 = ContractRegistry.getTestFtsoV2();
    }

    /**
     * @notice Verify if the provided feed data is valid based on the Merkle proof.
     * @param _feedData The FeedDataWithProof structure containing feed data and proof.
     * @return isValid Returns true if the feed data is valid, false otherwise.
     */
    function verifyFeedData(
        FtsoV2Interface.FeedDataWithProof calldata _feedData
    ) external view returns (bool isValid) {
        // Pack the relevant feed data fields into a hash
        bytes32 leaf = keccak256(
            abi.encodePacked(
                _feedData.body.votingRoundId,
                _feedData.body.id,
                _feedData.body.value,
                _feedData.body.turnoutBIPS,
                _feedData.body.decimals
            )
        );

        // Verify the Merkle proof against the leaf and root
        isValid = MerkleProof.verify(
            _feedData.proof,
            _feedData.merkleRoot,
            leaf
        );
    }
}

Open sample in Remix

Structures

FeedData

Feed data structure

struct FeedData {
  uint32 votingRoundId;
  bytes21 id;
  int32 value;
  uint16 turnoutBIPS;
  int8 decimals;
}

FeedDataWithProof

Feed data with proof structure

struct FeedDataWithProof {
    bytes32[] proof;
    struct FtsoV2Interface.FeedData body;
}