Tracking Liquidity

This guide explains how to monitor liquidity in OraclePool, including the difference between reserves and balances, and how to track changes via events.

Reserves vs Balances

OraclePool has two important concepts:

Reserves (getReserves)

function getReserves() external view returns (uint256 reserveX, uint256 reserveY);

Reserves are the tokens allocated for trading. These directly affect:

• Price calculations

• Available liquidity for swaps

• Execution price (via the CLCP formula)

Reserves change when:

• Swaps occur (tokens flow in/out)

• Allocation is adjusted via allocate()

Balances (getBalances)

function getBalances() external view returns (uint256 amountX, uint256 amountY);

Balances are the total tokens held by the pool (including reserves + any unallocated tokens).

Balances can be higher than reserves if:

• Tokens were deposited but not yet allocated

• There are extra tokens from fees or other sources

Reading Current State

// Get allocated reserves (used for trading)
(uint256 reserveX, uint256 reserveY) = pool.getReserves();

// Get total balances (all tokens held)
(uint256 balanceX, uint256 balanceY) = pool.getBalances();

// Unallocated = balances - reserves
uint256 unallocatedX = balanceX - reserveX;
uint256 unallocatedY = balanceY - reserveY;

Events

Swap Event

Emitted on every swap. Reserves change as tokens flow in/out.

event Swap(
    address indexed sender,
    address indexed recipient,
    bool indexed swapXtoY,
    uint256 amountIn,
    uint256 amountOut,
    uint256 feeIn
);

Parameters:

• sender - Address that initiated the swap

• recipient - Address that received the output tokens

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

• amountIn - Actual amount of input token consumed (includes fee)

• amountOut - Amount of output token sent to recipient

• feeIn - Fee deducted from input

Reserve changes from Swap:

• If swapXtoY = true: reserveX increases by (amountIn - feeIn), reserveY decreases by amountOut

• If swapXtoY = false: reserveY increases by (amountIn - feeIn), reserveX decreases by amountOut

Allocated Event

Emitted when reserves are reallocated by the allocator role.

event Allocated(
    address indexed allocator,
    uint256 reserveX,
    uint256 reserveY
);

Parameters:

• allocator - Address that called allocate()

• reserveX - New reserve amount for tokenX

• reserveY - New reserve amount for tokenY

This event gives you the absolute new reserve values, not deltas.

TypeScript Example: Tracking Liquidity

liquidity-tracker.ts

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 getBalances() view returns (uint256 amountX, uint256 amountY)",
    "event Swap(address indexed sender, address indexed recipient, bool indexed swapXtoY, uint256 amountIn, uint256 amountOut, uint256 feeIn)",
    "event Allocated(address indexed allocator, uint256 reserveX, uint256 reserveY)"
];

interface LiquidityState {
    reserveX: bigint;
    reserveY: bigint;
    balanceX: bigint;
    balanceY: bigint;
}

class LiquidityTracker {
    private pool: ethers.Contract;
    private state: LiquidityState;

    constructor(provider: ethers.Provider, poolAddress: string) {
        this.pool = new ethers.Contract(poolAddress, ORACLE_POOL_ABI, provider);
        this.state = { reserveX: 0n, reserveY: 0n, balanceX: 0n, balanceY: 0n };
    }

    async initialize(): Promise<LiquidityState> {
        const [reserves, balances] = await Promise.all([
            this.pool.getReserves(),
            this.pool.getBalances()
        ]);

        this.state = {
            reserveX: reserves.reserveX,
            reserveY: reserves.reserveY,
            balanceX: balances.amountX,
            balanceY: balances.amountY
        };

        return this.state;
    }

    getState(): LiquidityState {
        return { ...this.state };
    }
}

// Usage
async function main() {
    const provider = new ethers.JsonRpcProvider("https://rpc3.monad.xyz");
    
    const tracker = new LiquidityTracker(provider, "0x...poolAddress");
    const initialState = await tracker.initialize();
    
    console.log('Initial state:');
    console.log(`  Reserves: ${initialState.reserveX} / ${initialState.reserveY}`);
    console.log(`  Balances: ${initialState.balanceX} / ${initialState.balanceY}`);
}

Python Example

get_liquidity_state.py

from web3 import Web3
from typing import Dict, Any

def get_liquidity_state(w3: Web3, pool_address: str) -> Dict[str, Any]:
    """
    Get current liquidity state from the pool.
    """
    
    pool_abi = [
        {"name": "getReserves", "type": "function", "inputs": [], 
         "outputs": [{"name": "reserveX", "type": "uint256"}, {"name": "reserveY", "type": "uint256"}],
         "stateMutability": "view"},
        {"name": "getBalances", "type": "function", "inputs": [], 
         "outputs": [{"name": "amountX", "type": "uint256"}, {"name": "amountY", "type": "uint256"}],
         "stateMutability": "view"},
        {"name": "getTokenX", "type": "function", "inputs": [], 
         "outputs": [{"name": "", "type": "address"}],
         "stateMutability": "view"},
        {"name": "getTokenY", "type": "function", "inputs": [], 
         "outputs": [{"name": "", "type": "address"}],
         "stateMutability": "view"},
    ]
    
    pool = w3.eth.contract(address=w3.to_checksum_address(pool_address), abi=pool_abi)
    
    # Get current state
    reserve_x, reserve_y = pool.functions.getReserves().call()
    balance_x, balance_y = pool.functions.getBalances().call()
    token_x = pool.functions.getTokenX().call()
    token_y = pool.functions.getTokenY().call()
    
    return {
        'token_x': token_x,
        'token_y': token_y,
        'reserves': {'x': reserve_x, 'y': reserve_y},
        'balances': {'x': balance_x, 'y': balance_y},
        'unallocated': {'x': balance_x - reserve_x, 'y': balance_y - reserve_y}
    }

# Usage
if __name__ == "__main__":
    w3 = Web3(Web3.HTTPProvider("https://rpc3.monad.xyz"))
    
    result = get_liquidity_state(w3, "0x...poolAddress")
    
    print(f"Token X: {result['token_x']}")
    print(f"Token Y: {result['token_y']}")
    print(f"Reserves: X={result['reserves']['x']}, Y={result['reserves']['y']}")
    print(f"Balances: X={result['balances']['x']}, Y={result['balances']['y']}")
    print(f"Unallocated: X={result['unallocated']['x']}, Y={result['unallocated']['y']}")

Understanding Reserve Changes

From Swaps

When a swap occurs with swapXtoY = true (selling tokenX for tokenY):

New reserveX = Old reserveX + (amountIn - feeIn)
New reserveY = Old reserveY - amountOut

When swapXtoY = false (selling tokenY for tokenX):

New reserveY = Old reserveY + (amountIn - feeIn)
New reserveX = Old reserveX - amountOut

Note: The fee is not added to reserves. It's sent to the fee rewarder, if it's set.

From Allocation

The allocate() function sets reserves as a percentage of balances:

function allocate(uint256 allocateXBps, uint256 allocateYBps) external;

Where allocateXBps and allocateYBps are in basis points (10000 = 100%).

For example, allocate(8000, 8000) allocates 80% of each token balance to reserves.

Key Points

• Reserves affect price — Only allocated reserves participate in the CLCP pricing formula

• Balances include everything — Reserves + unallocated tokens

• Fees don't go to reserves — They're sent to the fee rewarder

• Allocated event is absolute — It gives new reserve values, not deltas

• Swap event gives deltas — Calculate new reserves from amountIn, amountOut, and feeIn