// SPDX-License-Identifier: AGPL-3.0-or-later
pragma solidity ^0.8.13;

import {ISwapAdapterTypes} from "src/interfaces/ISwapAdapterTypes.sol";

/// @title ISwapAdapter
/// @dev Implement this interface to support Propeller routing through your
/// pools. Before implementing the interface we need to introduce some function
/// for a given pool. The main one, the swap(x) function, implements a sell
/// order of a specified token.
/// The gas function simply
/// returns the estimated gas cost given a specified amount x. Last but not
/// least, the price function is the derivative of the swap function. It
/// represents the best possible price a user can get from a pool after swapping
/// x of the specified token. During calls to swap and getLimits, the caller can
/// be assumed to have the required sell or buy token balance as well as
/// unlimited approvals to this contract.
interface ISwapAdapterV2 is ISwapAdapterTypes {
    /// @notice Calculates pool prices for specified amounts (optional).
    /// @dev The returned prices should include all dex fees. In case the fee is
    /// dynamic on the amount traded, the returned price is expected to include
    /// the minimum fee.
    /// Note that the returned price should be the marginal price which is
    /// distinct from the executed price `swap(amount_in) / amount_in`! The
    /// marginal price is defined as the price to trade an arbitrarily small
    /// (almost zero) amount after the trade of (amount). E.g. the marginal
    /// price of a uniswap v2 pool at amount=0 is `reserve0/reserve1`.
    /// Ideally this method should be implemented, although it is optional as
    /// the price function can be numerically derived from the swap function.
    /// In case it is not available, it should be flagged via capabilities and
    /// calling it should revert using the `NotImplemented` error. The method
    /// needs to be implemented as view as this is usually more efficient and
    /// can be run in parallel.
    /// @param poolId The ID of the trading pool.
    /// @param sellToken The token being sold.
    /// @param buyToken The token being bought.
    /// @param specifiedAmounts Amounts to calculate marginal prices at.
    /// @param data Any additional data required, that does not fit the
    /// interface.
    /// @return prices array of prices as fractions corresponding to the
    /// provided amounts.
    function price(
        bytes memory poolId,
        address sellToken,
        address buyToken,
        uint256[] memory specifiedAmounts,
        bytes memory data
    ) external returns (Fraction[] memory prices);

    /**
     * @notice Simulates swapping tokens on a given pool.
     * @dev This function should be state modifying, meaning it should actually
     * execute the swap and change the state of the EVM accordingly. Please
     * include a gas usage estimate for each amount. This can be achieved e.g. by
     * using the `gasleft()` function. The return type `Trade` has an attribute
     * called price which should contain the value of `price(specifiedAmount)`.
     * As this is optional, defined via `Capability.PriceFunction`, it is valid
     * to return a Fraction(0, 0) value for this price. In that case the price
     * will be estimated numerically.
     * @param poolId The ID of the trading pool.
     * @param sellToken The token being sold.
     * @param buyToken The token being bought.
     * @param side The side of the trade (Sell or Buy).
     * @param specifiedAmount The amount to be traded.
     * @param data Any additional data required, that does not fit the interface
     * @return trade Trade struct representing the executed trade.
     */
    function swap(
        bytes memory poolId,
        address sellToken,
        address buyToken,
        OrderSide side,
        uint256 specifiedAmount,
        bytes memory data
    ) external returns (Trade memory trade);

    /// @notice Retrieves the limits for each token.
    /// @dev Retrieve the maximum limits of a token that can be traded. The
    /// limit is reached when the change in the received amounts is zero or
    /// close to zero or when the swap fails because of the pools restrictions.
    /// Overestimate if in doubt rather than underestimate. The
    /// swap function should not error with `LimitExceeded` if called with
    /// amounts below the limit.
    /// @param poolId The ID of the trading pool.
    /// @param sellToken The token being sold.
    /// @param buyToken The token being bought.
    /// @param data Any additional data required, that does not fit the
    /// interface
    /// @return limits An array of size two indicating the limit amount for the
    /// sell
    ///     token (maximum the pool is willing to buy in sell token) as well as
    /// the limit
    ///     amount of the buy token (maximum the pool is willing to sell in buy
    /// token).
    function getLimits(
        bytes memory poolId,
        address sellToken,
        address buyToken,
        bytes memory data
    ) external returns (uint256[] memory limits);

    /// @notice Retrieves the capabilities of the selected pool.
    /// @param poolId The ID of the trading pool.
    /// @return capabilities An array of Capability.
    function getCapabilities(
        bytes memory poolId,
        address sellToken,
        address buyToken
    ) external returns (Capability[] memory capabilities);

    /// @notice Retrieves the tokens in the selected pool.
    /// @dev Mainly used for testing as this is redundant with the required
    /// substreams implementation.
    /// @param poolId The ID of the trading pool.
    /// @return tokens An array of address contracts.
    function getTokens(bytes memory poolId)
        external
        returns (address[] memory tokens);

    /// @notice Retrieves a range of pool IDs.
    /// @dev Mainly used for testing. It is alright to not return all available
    /// pools here. Nevertheless, this is useful to test against the substreams
    /// implementation. If implemented, it saves time writing custom tests.
    /// @param offset The starting index from which to retrieve pool IDs.
    /// @param limit The maximum number of pool IDs to retrieve.
    /// @return ids An array of pool IDs.
    function getPoolIds(uint256 offset, uint256 limit)
        external
        returns (bytes32[] memory ids);
}
