Making a Swap with POE

This guide explains how to integrate with OraclePool to execute token swaps. The pool uses a callback pattern similar to Uniswap V3 - you call swap(), receive tokens optimistically, then must pay via a callback.

Getting a Quote

Before executing a swap, you can preview the expected output using getQuote():

function getQuote(bool swapXtoY, uint256 amountIn) 
    external view 
    returns (uint256 amountOut, uint256 actualAmountIn, uint256 feeIn);

Parameters:

• swapXtoY - Direction of the swap. true = sell tokenX for tokenY, false = sell tokenY for tokenX

• amountIn - The amount of input token you want to swap

Returns:

• amountOut - Amount of output token you will receive

• actualAmountIn - Actual input amount that will be consumed (may be less than amountIn if it would drain reserves)

• feeIn - Fee amount deducted from the input

Example:

// Check how much tokenY we'd get for 1000 tokenX
(uint256 amountOut, uint256 actualAmountIn, uint256 feeIn) = pool.getQuote(true, 1000e18);

Reading Pool Info

To understand what tokens are involved:

address tokenX = pool.getTokenX();
address tokenY = pool.getTokenY();
(uint256 reserveX, uint256 reserveY) = pool.getReserves();

Executing a Swap

The swap function uses an optimistic transfer pattern with a callback:

function swap(
    address recipient,
    bool swapXtoY,
    uint256 amountIn,
    bytes calldata data
) external returns (int256 deltaX, int256 deltaY);

Parameters:

• recipient - Address that receives the output tokens

• swapXtoY - Direction: true = tokenX → tokenY, false = tokenY → tokenX

• amountIn - Amount of input token to swap

• data - Arbitrary data passed through to the callback

Returns:

• deltaX - Change in tokenX from pool's perspective (positive = pool received, negative = pool sent)

• deltaY - Change in tokenY from pool's perspective

Swap Flow

1

Call swap()

Your contract calls pool.swap(recipient, swapXtoY, amountIn, data).

2

Pool transfers output

Pool calculates amountOut and transfers tokenOut to recipient.

3

Pool calls back

Pool calls swapCallback(deltaX, deltaY, data) on msg.sender (your contract).

4

Your callback pays

Your callback must transfer tokenIn to the pool.

5

Callback returns selector

Your callback must return 0xfa483e72 (the function selector).

6

Pool verifies payment

Pool verifies it received enough tokens.

7

swap() returns

swap() returns with the final deltas.

Implementing the Callback

Your contract must implement the ISwapCallback interface:

interface ISwapCallback {
    function swapCallback(int256 deltaX, int256 deltaY, bytes calldata data) 
        external 
        returns (bytes4);
}

The callback must:

1

Transfer the required input tokens to the pool (msg.sender in the callback).

2

Return the selector 0xfa483e72 (which is ISwapCallback.swapCallback.selector).

Important: The callback is called with deltaX and deltaY from the pool's perspective:

• Positive delta = pool expects to receive that token

• Negative delta = pool has sent that token

Solidity Example: Router Contract

Here's a complete example of a router contract that can swap through OraclePool:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

interface IOraclePool {
    function getTokenX() external view returns (address);
    function getTokenY() external view returns (address);
    function getQuote(bool swapXtoY, uint256 amountIn) 
        external view returns (uint256 amountOut, uint256 actualAmountIn, uint256 feeIn);
    function swap(address recipient, bool swapXtoY, uint256 amountIn, bytes calldata data)
        external returns (int256 deltaX, int256 deltaY);
}

interface ISwapCallback {
    function swapCallback(int256 deltaX, int256 deltaY, bytes calldata data) 
        external returns (bytes4);
}

contract OraclePoolRouter is ISwapCallback {
    using SafeERC20 for IERC20;

    // Track expected callback to prevent unauthorized calls
    address private _expectedPool;

    /// @notice Swap exact input tokens for output tokens
    /// @param pool The OraclePool to swap through
    /// @param swapXtoY Direction: true = tokenX -> tokenY
    /// @param amountIn Amount of input token to swap
    /// @param minAmountOut Minimum output amount (slippage protection)
    /// @param recipient Address to receive output tokens
    /// @return amountOut Actual amount of output tokens received
    function swapExactInput(
        address pool,
        bool swapXtoY,
        uint256 amountIn,
        uint256 minAmountOut,
        address recipient
    ) external returns (uint256 amountOut) {
        // Get the input token
        address tokenIn = swapXtoY 
            ? IOraclePool(pool).getTokenX() 
            : IOraclePool(pool).getTokenY();

        // Transfer input tokens from user to this contract
        IERC20(tokenIn).safeTransferFrom(msg.sender, address(this), amountIn);

        // Set expected pool for callback verification
        _expectedPool = pool;

        // Execute the swap - pool will call our swapCallback
        (int256 deltaX, int256 deltaY) = IOraclePool(pool).swap(
            recipient,
            swapXtoY,
            amountIn,
            abi.encode(tokenIn) // Pass tokenIn address in callback data
        );

        // Clear expected pool
        _expectedPool = address(0);

        // Calculate actual output (negative delta = pool sent tokens)
        amountOut = uint256(swapXtoY ? -deltaY : -deltaX);

        // Slippage check
        require(amountOut >= minAmountOut, "Insufficient output");
    }

    /// @notice Callback called by the pool during swap
    /// @dev Must transfer input tokens to the pool and return correct selector
    function swapCallback(
        int256 deltaX,
        int256 deltaY,
        bytes calldata data
    ) external override returns (bytes4) {
        // Verify caller is the expected pool
        require(msg.sender == _expectedPool, "Unauthorized callback");

        // Decode the token we need to pay
        address tokenIn = abi.decode(data, (address));

        // Determine amount to pay (positive delta = pool expects payment)
        uint256 amountToPay = deltaX > 0 ? uint256(deltaX) : uint256(deltaY);

        // Transfer tokens to the pool
        IERC20(tokenIn).safeTransfer(msg.sender, amountToPay);

        // Return the required selector
        return ISwapCallback.swapCallback.selector; // 0xfa483e72
    }
}

Usage Example

// User wants to swap 100 tokenX for tokenY with 1% slippage tolerance
OraclePoolRouter router = OraclePoolRouter(routerAddress);
IOraclePool pool = IOraclePool(poolAddress);

// First, get a quote
(uint256 expectedOut, , ) = pool.getQuote(true, 100e18);
uint256 minOut = expectedOut * 99 / 100; // 1% slippage

// Approve router to spend tokens
IERC20(pool.getTokenX()).approve(address(router), 100e18);

// Execute swap
uint256 received = router.swapExactInput(
    address(pool),
    true,           // swapXtoY
    100e18,         // amountIn
    minOut,         // minAmountOut
    msg.sender      // recipient
);

TypeScript Example: Reading Quotes

import { ethers } from 'ethers';

const ORACLE_POOL_ABI = [
    "function getTokenX() view returns (address)",
    "function getTokenY() view returns (address)",
    "function getReserves() view returns (uint256 reserveX, uint256 reserveY)",
    "function getQuote(bool swapXtoY, uint256 amountIn) view returns (uint256 amountOut, uint256 actualAmountIn, uint256 feeIn)"
];

async function getSwapQuote(
    provider: ethers.Provider,
    poolAddress: string,
    swapXtoY: boolean,
    amountIn: bigint
) {
    const pool = new ethers.Contract(poolAddress, ORACLE_POOL_ABI, provider);
    
    // Get pool info
    const [tokenX, tokenY, reserves] = await Promise.all([
        pool.getTokenX(),
        pool.getTokenY(),
        pool.getReserves()
    ]);
    
    console.log(`Pool: ${tokenX} / ${tokenY}`);
    console.log(`Reserves: ${reserves.reserveX} / ${reserves.reserveY}`);
    
    // Get quote
    const [amountOut, actualAmountIn, feeIn] = await pool.getQuote(swapXtoY, amountIn);
    
    console.log(`Input: ${actualAmountIn}`);
    console.log(`Output: ${amountOut}`);
    console.log(`Fee: ${feeIn}`);
    
    // Calculate effective price
    const price = Number(amountOut) / Number(actualAmountIn - feeIn);
    console.log(`Effective price: ${price}`);
    
    return { amountOut, actualAmountIn, feeIn };
}

// Example usage
const provider = new ethers.JsonRpcProvider("https://rpc.example.com");
await getSwapQuote(
    provider,
    "0x...", // pool address
    true,    // swap tokenX to tokenY
    ethers.parseEther("100") // 100 tokens
);

Error Handling

Error	Cause
InvalidCallback	Callback didn't return correct selector 0xfa483e72
ZeroTokenReceived	Callback didn't transfer any tokens to the pool
InsufficientTokenReceived	Callback transferred less than required
OraclePool__OracleNotSet	Pool's oracle is not configured
OracleData__Expired	Oracle data has expired, operator needs to update

Security Considerations

1. Callback Verification: Always verify that the callback caller is the expected pool to prevent malicious contracts from draining your tokens.

2. Slippage Protection: Always use minAmountOut checks to protect against price movement between quote and execution.

3. Reentrancy: The callback pattern can be vulnerable to reentrancy. Use reentrancy guards if your callback does anything complex.

4. Token Approvals: Be careful with token approvals. Only approve what's needed for the specific swap.