@flarenetwork/ftso-adapters

Flare FTSO Oracle Adapter Libraries

Solidity library contracts that adapt Flare's FTSO data to popular oracle interfaces such as Chainlink, Pyth, and API3. These libraries let dApps migrate to Flare's native FTSO oracle with minimal code changes.

Key Concept: Stateless Library + Stateful Consumer

• Your Contract (Consumer): Stores configuration (e.g., ftsoFeedId) and holds cached price data in storage.
• The Library: Provides pure/internal logic you call to refresh and read price data stored within your contract.
• Refreshing: Expose a refresh() function on your contract and call it periodically (via a keeper or cron) to keep on-chain prices fresh.

Example: Chainlink-Style Adapter

This example shows how to build a contract that uses a FtsoChainlinkAdapterLibrary to expose a Chainlink-compatible latestRoundData interface. The pattern is identical for API3 and Pyth adapters.

1) Library: FtsoChainlinkAdapterLibrary.sol

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

library FtsoChainlinkAdapterLibrary {
    struct Round {
        int256 answer;
        uint256 startedAt;
        uint256 updatedAt;
        uint80 answeredInRound;
        uint80 roundId;
    }

    // Fetches price from FTSO and updates the cached Round in the consuming contract
    function refresh(Round storage _latestState /*, other args */) internal {
        // Fetch price from FTSO, transform, and store in _latestState
    }

    // Reads and validates the cached price
    function latestRoundData(
        Round storage _latestState /*, other args */
    )
        internal
        view
        returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)
    {
        // Validate _latestState and return Chainlink-like round data
    }
}

2) Consumer Contract: MyPriceConsumer.sol

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

import { FtsoChainlinkAdapterLibrary } from "./FtsoChainlinkAdapterLibrary.sol";

contract MyPriceConsumer {
    // --- Adapter configuration and cached state ---
    bytes21 public immutable ftsoFeedId;
    uint8 public immutable chainlinkDecimals;
    uint256 public immutable maxAgeSeconds;

    FtsoChainlinkAdapterLibrary.Round private _latestPriceData;

    constructor(bytes21 _ftsoFeedId, uint8 _decimals, uint256 _maxAge) {
        ftsoFeedId = _ftsoFeedId;
        chainlinkDecimals = _decimals;
        maxAgeSeconds = _maxAge;
    }

    // Keeper-triggered method to refresh cache via the library
    function refresh() external {
        FtsoChainlinkAdapterLibrary.refresh(_latestPriceData /*, ftsoFeedId, chainlinkDecimals */);
    }

    // Chainlink-compatible read method backed by cached data
    function latestRoundData()
        public
        view
        returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)
    {
        return FtsoChainlinkAdapterLibrary.latestRoundData(_latestPriceData /*, maxAgeSeconds */);
    }

    // Example business logic using the adapter output
    function executeTrade() external {
        (, int256 price, , , ) = latestRoundData();
        require(price > 0, "Price is not available");
        // ... your logic here ...
    }
}

Notes

• The libraries are stateless; your contract owns the storage and simply calls library functions to refresh and read values.
• Configure a keeper/off-chain process to call your refresh() periodically to keep data fresh.
• For more examples of adapters with off-chain scripts, see the hardhat starter here.