tempo_precompiles/stablecoin_dex/

orderbook.rs

//! Orderbook and tick level management for the stablecoin DEX.

use crate::{
    error::Result,
    stablecoin_dex::{IStablecoinDEX, TICK_SPACING},
    storage::{Handler, Mapping},
};
use alloy::primitives::{Address, B256, U256, keccak256};
use tempo_contracts::precompiles::StablecoinDEXError;
use tempo_precompiles_macros::Storable;

/// Minimum allowed tick value (corresponds to `MIN_PRICE`).
pub const MIN_TICK: i16 = -2000;
/// Maximum allowed tick value (corresponds to `MAX_PRICE`).
pub const MAX_TICK: i16 = 2000;
/// Scaling factor for tick-to-price conversion. A tick of 0 maps to `PRICE_SCALE` (peg).
pub const PRICE_SCALE: u32 = 100_000;

/// Rounding direction for price conversions.
///
/// Rounding should always favor the protocol to prevent insolvency:
/// - When users deposit funds (escrow) → round UP (user pays more)
/// - When users receive funds (settlement/refunds) → round DOWN (user receives less)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RoundingDirection {
    /// Round down (floor division) - favors protocol when user receives funds
    Down,
    /// Round up (ceiling division) - favors protocol when user deposits funds
    Up,
}

/// Convert base token amount to quote token amount at a given tick.
///
/// Formula: quote_amount = (base_amount * price) / PRICE_SCALE
///
/// Uses U256 for intermediate multiplication to prevent overflow.
///
/// # Arguments
/// * `base_amount` - Amount of base tokens
/// * `tick` - Price tick
/// * `rounding` - Rounding direction
///
/// # Returns
/// Quote token amount, or None if result exceeds u128
pub fn base_to_quote(base_amount: u128, tick: i16, rounding: RoundingDirection) -> Option<u128> {
    let price = U256::from(tick_to_price(tick));
    let base = U256::from(base_amount);
    let scale = U256::from(PRICE_SCALE);

    let numerator = base * price;

    let result = match rounding {
        RoundingDirection::Down => numerator / scale,
        RoundingDirection::Up => numerator.div_ceil(scale),
    };

    result.try_into().ok()
}

/// Convert quote token amount to base token amount at a given tick.
///
/// Formula: base_amount = (quote_amount * PRICE_SCALE) / price
///
/// Uses U256 for intermediate multiplication to prevent overflow.
///
/// # Arguments
/// * `quote_amount` - Amount of quote tokens
/// * `tick` - Price tick
/// * `rounding` - Rounding direction
///
/// # Returns
/// Base token amount, or None if result exceeds u128
pub fn quote_to_base(quote_amount: u128, tick: i16, rounding: RoundingDirection) -> Option<u128> {
    let price = U256::from(tick_to_price(tick));
    let quote = U256::from(quote_amount);
    let scale = U256::from(PRICE_SCALE);

    let numerator = quote * scale;

    let result = match rounding {
        RoundingDirection::Down => numerator / price,
        RoundingDirection::Up => numerator.div_ceil(price),
    };

    result.try_into().ok()
}

/// Lowest representable scaled price (`PRICE_SCALE + MIN_TICK`).
pub(crate) const MIN_PRICE: u32 = 98_000;
/// Highest representable scaled price (`PRICE_SCALE + MAX_TICK`).
pub(crate) const MAX_PRICE: u32 = 102_000;

/// Represents a price level in the orderbook with a doubly-linked list of orders
/// Orders are maintained in FIFO order at each tick level
#[derive(Debug, Storable, Default, Clone, Copy, PartialEq, Eq)]
pub struct TickLevel {
    /// Order ID of the first order at this tick (0 if empty)
    pub head: u128,
    /// Order ID of the last order at this tick (0 if empty)
    pub tail: u128,
    /// Total liquidity available at this tick level
    pub total_liquidity: u128,
}

impl TickLevel {
    /// Creates a new empty tick level
    pub fn new() -> Self {
        Self {
            head: 0,
            tail: 0,
            total_liquidity: 0,
        }
    }

    /// Creates a tick level with specific values
    pub fn with_values(head: u128, tail: u128, total_liquidity: u128) -> Self {
        Self {
            head,
            tail,
            total_liquidity,
        }
    }

    /// Returns true if this tick level has no orders
    pub fn is_empty(&self) -> bool {
        self.head == 0 && self.tail == 0
    }

    /// Returns true if this tick level has orders
    pub fn has_liquidity(&self) -> bool {
        !self.is_empty()
    }
}

impl From<TickLevel> for IStablecoinDEX::PriceLevel {
    fn from(value: TickLevel) -> Self {
        Self {
            head: value.head,
            tail: value.tail,
            totalLiquidity: value.total_liquidity,
        }
    }
}

/// Orderbook for token pair with price-time priority
/// Uses tick-based pricing with bitmaps for price discovery
#[derive(Storable, Default)]
pub struct Orderbook {
    /// Base token address
    pub base: Address,
    /// Quote token address
    pub quote: Address,
    /// Bid orders by tick
    #[allow(dead_code)]
    bids: Mapping<i16, TickLevel>,
    /// Ask orders by tick
    #[allow(dead_code)]
    asks: Mapping<i16, TickLevel>,
    /// Best bid tick for highest bid price
    pub best_bid_tick: i16,
    /// Best ask tick for lowest ask price
    pub best_ask_tick: i16,
    #[allow(dead_code)]
    /// Mapping of tick index to bid bitmap for price discovery
    bid_bitmap: Mapping<i16, U256>,
    /// Mapping of tick index to ask bitmap for price discovery
    #[allow(dead_code)]
    ask_bitmap: Mapping<i16, U256>,
}

impl Orderbook {
    /// Creates a new orderbook for a token pair
    pub fn new(base: Address, quote: Address) -> Self {
        Self {
            base,
            quote,
            best_bid_tick: i16::MIN,
            best_ask_tick: i16::MAX,
            ..Default::default()
        }
    }

    /// Returns true if this orderbook is initialized
    pub fn is_initialized(&self) -> bool {
        self.base != Address::ZERO
    }

    /// Returns true if the base and quote tokens match the provided base and quote token options.
    pub fn matches_tokens(
        &self,
        base_token: Option<Address>,
        quote_token: Option<Address>,
    ) -> bool {
        // Check base token filter
        if let Some(base) = base_token
            && base != self.base
        {
            return false;
        }

        // Check quote token filter
        if let Some(quote) = quote_token
            && quote != self.quote
        {
            return false;
        }

        true
    }
}

impl OrderbookHandler {
    /// Returns a reference to the tick level handler for the given tick and side.
    pub fn tick_level_handler(&self, tick: i16, is_bid: bool) -> &TickLevelHandler {
        if is_bid {
            &self.bids[tick]
        } else {
            &self.asks[tick]
        }
    }

    /// Returns a mutable reference to the tick level handler for the given tick and side.
    pub fn tick_level_handler_mut(&mut self, tick: i16, is_bid: bool) -> &mut TickLevelHandler {
        if is_bid {
            &mut self.bids[tick]
        } else {
            &mut self.asks[tick]
        }
    }

    fn calc_tick_word_idx(&self, tick: i16) -> Result<i16> {
        if !(MIN_TICK..=MAX_TICK).contains(&tick) {
            return Err(StablecoinDEXError::invalid_tick().into());
        }

        Ok(tick >> 8)
    }

    /// Sets the bitmap bit for `tick` to mark it as active on the given side.
    ///
    /// # Errors
    /// - `InvalidTick` — tick is outside `[MIN_TICK, MAX_TICK]`
    pub fn set_tick_bit(&mut self, tick: i16, is_bid: bool) -> Result<()> {
        let word_index = self.calc_tick_word_idx(tick)?;
        let bitmap = if is_bid {
            &mut self.bid_bitmap[word_index]
        } else {
            &mut self.ask_bitmap[word_index]
        };

        // Read current bitmap word
        let current_word = bitmap.read()?;

        // Use bitwise AND to get lower 8 bits correctly for both positive and negative ticks
        let bit_index = (tick & 0xFF) as usize;
        let mask = U256::from(1u8) << bit_index;

        // Set the bit
        bitmap.write(current_word | mask)
    }

    /// Clears the bitmap bit for `tick` to mark it as inactive on the given side.
    ///
    /// # Errors
    /// - `InvalidTick` — tick is outside `[MIN_TICK, MAX_TICK]`
    pub fn delete_tick_bit(&mut self, tick: i16, is_bid: bool) -> Result<()> {
        let word_index = self.calc_tick_word_idx(tick)?;
        let bitmap = if is_bid {
            &mut self.bid_bitmap[word_index]
        } else {
            &mut self.ask_bitmap[word_index]
        };

        // Read current bitmap word
        let current_word = bitmap.read()?;

        // Use bitwise AND to get lower 8 bits correctly for both positive and negative ticks
        let bit_index = (tick & 0xFF) as usize;
        let mask = !(U256::from(1u8) << bit_index);

        // Set the bit
        bitmap.write(current_word & mask)
    }

    /// Returns `true` if the given `tick` has active orders on the specified side.
    ///
    /// # Errors
    /// - `InvalidTick` — tick is outside `[MIN_TICK, MAX_TICK]`
    pub fn is_tick_initialized(&self, tick: i16, is_bid: bool) -> Result<bool> {
        let word_index = self.calc_tick_word_idx(tick)?;
        let bitmap = if is_bid {
            &self.bid_bitmap[word_index]
        } else {
            &self.ask_bitmap[word_index]
        };

        // Read current bitmap word
        let word = bitmap.read()?;

        // Use bitwise AND to get lower 8 bits correctly for both positive and negative ticks
        let bit_index = (tick & 0xFF) as usize;
        let mask = U256::from(1u8) << bit_index;

        Ok((word & mask) != U256::ZERO)
    }

    /// Finds the next initialized tick with liquidity. Searches downward for bids, upward for asks.
    pub fn next_initialized_tick(&self, tick: i16, is_bid: bool) -> Result<(i16, bool)> {
        if is_bid {
            self.next_initialized_bid_tick(tick)
        } else {
            self.next_initialized_ask_tick(tick)
        }
    }

    /// Find next initialized ask tick higher than current tick.
    ///
    /// Uses efficient bitmap word traversal: reads entire 256-bit words and uses
    /// bit manipulation to find set bits, minimizing storage reads.
    fn next_initialized_ask_tick(&self, tick: i16) -> Result<(i16, bool)> {
        // Guard against overflow when tick is at or above MAX_TICK
        if tick >= MAX_TICK {
            return Ok((MAX_TICK, false));
        }

        let mut next_tick = tick + 1;
        let max_word_index = MAX_TICK >> 8;

        loop {
            let word_index = next_tick >> 8;
            if word_index > max_word_index {
                return Ok((next_tick, false));
            }

            let bit_index = (next_tick & 0xFF) as usize;

            let word = self.ask_bitmap[word_index].read()?;

            // Mask off bits below bit_index to only consider ticks >= next_tick
            let mask = if bit_index == 0 {
                U256::MAX
            } else {
                U256::MAX << bit_index
            };
            let masked_word = word & mask;

            if masked_word != U256::ZERO {
                // Find the lowest set bit position using trailing_zeros
                let lowest_bit = masked_word.trailing_zeros();
                let found_tick = (word_index << 8) | (lowest_bit as i16);
                if found_tick <= MAX_TICK {
                    return Ok((found_tick, true));
                }
                return Ok((found_tick, false));
            }

            // No set bits in this word, move to next word
            let next_word_index = word_index + 1;
            if next_word_index > max_word_index {
                return Ok((next_word_index << 8, false));
            }
            next_tick = next_word_index << 8; // First tick of next word
        }
    }

    /// Find next initialized bid tick lower than current tick.
    ///
    /// Uses efficient bitmap word traversal: reads entire 256-bit words and uses
    /// bit manipulation to find set bits, minimizing storage reads.
    fn next_initialized_bid_tick(&self, tick: i16) -> Result<(i16, bool)> {
        // Guard against underflow when tick is at or below MIN_TICK
        if tick <= MIN_TICK {
            return Ok((MIN_TICK, false));
        }

        let mut next_tick = tick - 1;
        let min_word_index = MIN_TICK >> 8;

        loop {
            let word_index = next_tick >> 8;
            if word_index < min_word_index {
                return Ok((next_tick, false));
            }

            let bit_index = (next_tick & 0xFF) as usize;

            let word = self.bid_bitmap[word_index].read()?;

            // Mask off bits above bit_index to only consider ticks <= next_tick
            let mask = if bit_index == 255 {
                U256::MAX
            } else {
                U256::MAX >> (255 - bit_index)
            };
            let masked_word = word & mask;

            if masked_word != U256::ZERO {
                // Find the highest set bit position using leading_zeros
                // U256 is 256 bits, so highest bit index = 255 - leading_zeros
                let leading = masked_word.leading_zeros();
                let highest_bit = 255 - leading;
                let found_tick = (word_index << 8) | (highest_bit as i16);
                if found_tick >= MIN_TICK {
                    return Ok((found_tick, true));
                }
                return Ok((found_tick, false));
            }

            // No set bits in this word, move to previous word
            let prev_word_index = word_index - 1;
            if prev_word_index < min_word_index {
                return Ok(((prev_word_index << 8) | 0xFF, false));
            }
            next_tick = (prev_word_index << 8) | 0xFF; // Last tick of previous word
        }
    }
}

impl From<Orderbook> for IStablecoinDEX::Orderbook {
    fn from(value: Orderbook) -> Self {
        Self {
            base: value.base,
            quote: value.quote,
            bestBidTick: value.best_bid_tick,
            bestAskTick: value.best_ask_tick,
        }
    }
}

/// Compute deterministic book key from ordered (base, quote) token pair
pub fn compute_book_key(base: Address, quote: Address) -> B256 {
    // Compute keccak256(abi.encodePacked(base, quote))
    let mut buf = [0u8; 40];
    buf[..20].copy_from_slice(base.as_slice());
    buf[20..].copy_from_slice(quote.as_slice());
    keccak256(buf)
}

/// Convert relative tick to scaled price
pub fn tick_to_price(tick: i16) -> u32 {
    (PRICE_SCALE as i32 + tick as i32) as u32
}

/// Converts a scaled price back to a relative tick.
///
/// # Errors
/// - `TickOutOfBounds` — price is outside `[MIN_PRICE, MAX_PRICE]`
pub fn price_to_tick(price: u32) -> Result<i16> {
    if !(MIN_PRICE..=MAX_PRICE).contains(&price) {
        let invalid_tick = (price as i32 - PRICE_SCALE as i32) as i16;
        return Err(StablecoinDEXError::tick_out_of_bounds(invalid_tick).into());
    }
    Ok((price as i32 - PRICE_SCALE as i32) as i16)
}

/// Validates that a tick is aligned to [`TICK_SPACING`].
///
/// # Errors
/// - `InvalidTick` — tick is not a multiple of [`TICK_SPACING`]
pub fn validate_tick_spacing(tick: i16) -> Result<()> {
    if tick % TICK_SPACING != 0 {
        return Err(StablecoinDEXError::invalid_tick().into());
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::TempoPrecompileError;
    use rand_08::Rng;

    use alloy::primitives::address;

    #[test]
    fn test_tick_level_creation() {
        let level = TickLevel::new();
        assert_eq!(level.head, 0);
        assert_eq!(level.tail, 0);
        assert_eq!(level.total_liquidity, 0);
        assert!(level.is_empty());
        assert!(!level.has_liquidity());
    }

    #[test]
    fn test_orderbook_creation() {
        let base = address!("0x1111111111111111111111111111111111111111");
        let quote = address!("0x2222222222222222222222222222222222222222");
        let book = Orderbook::new(base, quote);

        assert_eq!(book.base, base);
        assert_eq!(book.quote, quote);
        assert_eq!(book.best_bid_tick, i16::MIN);
        assert_eq!(book.best_ask_tick, i16::MAX);
        assert!(book.is_initialized());
    }

    #[test]
    fn test_tick_price_conversion() -> eyre::Result<()> {
        // Test at peg price (tick 0)
        assert_eq!(tick_to_price(0), PRICE_SCALE);
        assert_eq!(price_to_tick(PRICE_SCALE)?, 0);

        // Test above peg
        assert_eq!(tick_to_price(100), PRICE_SCALE + 100);
        assert_eq!(price_to_tick(PRICE_SCALE + 100)?, 100);

        // Test below peg
        assert_eq!(tick_to_price(-100), PRICE_SCALE - 100);
        assert_eq!(price_to_tick(PRICE_SCALE - 100)?, -100);

        Ok(())
    }

    #[test]
    fn test_price_to_tick_below_min() {
        // Price below MIN_PRICE should return an error
        let result = price_to_tick(MIN_PRICE - 1);
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            TempoPrecompileError::StablecoinDEX(StablecoinDEXError::TickOutOfBounds(_))
        ));
    }

    #[test]
    fn test_price_to_tick_above_max() {
        // Price above MAX_PRICE should return an error
        let result = price_to_tick(MAX_PRICE + 1);
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            TempoPrecompileError::StablecoinDEX(StablecoinDEXError::TickOutOfBounds(_))
        ));
    }

    #[test]
    fn test_price_to_tick_at_min_boundary() {
        let result = price_to_tick(MIN_PRICE);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), MIN_TICK);
        assert_eq!(MIN_PRICE, (PRICE_SCALE as i32 + MIN_TICK as i32) as u32);
    }

    #[test]
    fn test_price_to_tick_at_max_boundary() {
        let result = price_to_tick(MAX_PRICE);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), MAX_TICK);
        assert_eq!(MAX_PRICE, (PRICE_SCALE as i32 + MAX_TICK as i32) as u32);
    }

    #[test]
    fn test_tick_bounds() {
        assert_eq!(MIN_TICK, -2000);
        assert_eq!(MAX_TICK, 2000);

        // Test boundary values
        assert_eq!(tick_to_price(MIN_TICK), PRICE_SCALE - 2000);
        assert_eq!(tick_to_price(MAX_TICK), PRICE_SCALE + 2000);
    }

    #[test]
    fn test_validate_tick_spacing() {
        let mut rng = rand_08::thread_rng();

        assert!(validate_tick_spacing(0).is_ok());
        assert!(validate_tick_spacing(10).is_ok());
        assert!(validate_tick_spacing(-10).is_ok());
        assert!(validate_tick_spacing(100).is_ok());
        assert!(validate_tick_spacing(MIN_TICK).is_ok());
        assert!(validate_tick_spacing(MAX_TICK).is_ok());

        for _ in 0..100 {
            let tick = rng.gen_range(MIN_TICK..=MAX_TICK) * TICK_SPACING;
            assert!(validate_tick_spacing(tick).is_ok());
        }

        for _ in 0..100 {
            let offset = rng.gen_range(1..TICK_SPACING);
            let base = rng.gen_range(MIN_TICK..=MAX_TICK) * TICK_SPACING;
            let tick = base + offset;
            assert!(validate_tick_spacing(tick).is_err());
        }
    }

    #[test]
    fn test_compute_book_key() {
        let base = address!("0x1111111111111111111111111111111111111111");
        let quote = address!("0x2222222222222222222222222222222222222222");

        let key_bq = compute_book_key(base, quote);
        let key_qb = compute_book_key(quote, base);

        assert_ne!(key_bq, key_qb);

        let mut buf = [0u8; 40];
        buf[..20].copy_from_slice(base.as_slice());
        buf[20..].copy_from_slice(quote.as_slice());
        let expected_hash = keccak256(buf);

        assert_eq!(key_bq, expected_hash,);
    }

    mod bitmap_tests {
        use super::*;
        use crate::{
            stablecoin_dex::StablecoinDEX,
            storage::{StorageCtx, hashmap::HashMapStorageProvider},
        };
        const BOOK_KEY: B256 = B256::ZERO;

        #[test]
        fn test_tick_lifecycle() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test full lifecycle (set, check, clear, check) for positive and negative ticks
                // Include boundary cases, word boundaries, and various representative values
                let test_ticks = [
                    MIN_TICK, -1000, -500, -257, -256, -100, -1, 0, 1, 100, 255, 256, 500, 1000,
                    MAX_TICK,
                ];

                for &tick in &test_ticks {
                    // Initially not set
                    assert!(
                        !book_handler.is_tick_initialized(tick, true)?,
                        "Tick {tick} should not be initialized initially"
                    );

                    // Set the bit
                    book_handler.set_tick_bit(tick, true)?;

                    assert!(
                        book_handler.is_tick_initialized(tick, true)?,
                        "Tick {tick} should be initialized after set"
                    );

                    // Clear the bit
                    book_handler.delete_tick_bit(tick, true)?;

                    assert!(
                        !book_handler.is_tick_initialized(tick, true)?,
                        "Tick {tick} should not be initialized after clear"
                    );
                }

                Ok(())
            })
        }

        #[test]
        fn test_boundary_ticks() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test MIN_TICK
                book_handler.set_tick_bit(MIN_TICK, true)?;

                assert!(
                    book_handler.is_tick_initialized(MIN_TICK, true)?,
                    "MIN_TICK should be settable"
                );

                // Test MAX_TICK (use different storage for ask side)
                book_handler.set_tick_bit(MAX_TICK, false)?;

                assert!(
                    book_handler.is_tick_initialized(MAX_TICK, false)?,
                    "MAX_TICK should be settable"
                );

                // Clear MIN_TICK
                book_handler.delete_tick_bit(MIN_TICK, true)?;

                assert!(
                    !book_handler.is_tick_initialized(MIN_TICK, true)?,
                    "MIN_TICK should be clearable"
                );
                Ok(())
            })
        }

        #[test]
        fn test_bid_and_ask_separate() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                let tick = 100;

                // Set as bid
                book_handler.set_tick_bit(tick, true)?;

                assert!(
                    book_handler.is_tick_initialized(tick, true)?,
                    "Tick should be initialized for bids"
                );
                assert!(
                    !book_handler.is_tick_initialized(tick, false)?,
                    "Tick should not be initialized for asks"
                );

                // Set as ask
                book_handler.set_tick_bit(tick, false)?;

                assert!(
                    book_handler.is_tick_initialized(tick, true)?,
                    "Tick should still be initialized for bids"
                );
                assert!(
                    book_handler.is_tick_initialized(tick, false)?,
                    "Tick should now be initialized for asks"
                );
                Ok(())
            })
        }

        #[test]
        fn test_ticks_across_word_boundary() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Ticks that span word boundary at 256
                book_handler.set_tick_bit(255, true)?; // word_index = 0, bit_index = 255
                book_handler.set_tick_bit(256, true)?; // word_index = 1, bit_index = 0

                assert!(book_handler.is_tick_initialized(255, true)?);
                assert!(book_handler.is_tick_initialized(256, true)?);
                Ok(())
            })
        }

        #[test]
        fn test_ticks_different_words() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test ticks in different words (both positive and negative)

                // Negative ticks in different words
                book_handler.set_tick_bit(-1, true)?; // word_index = -1, bit_index = 255
                book_handler.set_tick_bit(-100, true)?; // word_index = -1, bit_index = 156
                book_handler.set_tick_bit(-256, true)?; // word_index = -1, bit_index = 0
                book_handler.set_tick_bit(-257, true)?; // word_index = -2, bit_index = 255

                // Positive ticks in different words
                book_handler.set_tick_bit(1, true)?; // word_index = 0, bit_index = 1
                book_handler.set_tick_bit(100, true)?; // word_index = 0, bit_index = 100
                book_handler.set_tick_bit(256, true)?; // word_index = 1, bit_index = 0
                book_handler.set_tick_bit(512, true)?; // word_index = 2, bit_index = 0

                // Verify negative ticks
                assert!(book_handler.is_tick_initialized(-1, true)?);
                assert!(book_handler.is_tick_initialized(-100, true)?);
                assert!(book_handler.is_tick_initialized(-256, true)?);
                assert!(book_handler.is_tick_initialized(-257, true)?);

                // Verify positive ticks
                assert!(book_handler.is_tick_initialized(1, true)?);
                assert!(book_handler.is_tick_initialized(100, true)?);
                assert!(book_handler.is_tick_initialized(256, true)?);
                assert!(book_handler.is_tick_initialized(512, true)?);

                // Verify unset ticks
                assert!(
                    !book_handler.is_tick_initialized(-50, true)?,
                    "Unset negative tick should not be initialized"
                );
                assert!(
                    !book_handler.is_tick_initialized(50, true)?,
                    "Unset positive tick should not be initialized"
                );
                Ok(())
            })
        }

        #[test]
        fn test_set_tick_bit_out_of_bounds() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test tick above MAX_TICK
                let result = book_handler.set_tick_bit(MAX_TICK + 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));

                // Test tick below MIN_TICK
                let result = book_handler.set_tick_bit(MIN_TICK - 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));
                Ok(())
            })
        }

        #[test]
        fn test_clear_tick_bit_out_of_bounds() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test tick above MAX_TICK
                let result = book_handler.delete_tick_bit(MAX_TICK + 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));

                // Test tick below MIN_TICK
                let result = book_handler.delete_tick_bit(MIN_TICK - 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));
                Ok(())
            })
        }

        #[test]
        fn test_is_tick_initialized_out_of_bounds() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let exchange = StablecoinDEX::new();
                let book_handler = &exchange.books[BOOK_KEY];

                // Test tick above MAX_TICK
                let result = book_handler.is_tick_initialized(MAX_TICK + 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));

                // Test tick below MIN_TICK
                let result = book_handler.is_tick_initialized(MIN_TICK - 1, true);
                assert!(result.is_err());
                assert!(matches!(
                    result.unwrap_err(),
                    TempoPrecompileError::StablecoinDEX(StablecoinDEXError::InvalidTick(_))
                ));
                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_ask_tick_same_word() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Set ticks 10 and 50 (both in word 0)
                book_handler.set_tick_bit(10, false)?;
                book_handler.set_tick_bit(50, false)?;

                // From tick 0, should find tick 10
                let (next, found) = book_handler.next_initialized_tick(0, false)?;
                assert!(found);
                assert_eq!(next, 10);

                // From tick 10, should find tick 50
                let (next, found) = book_handler.next_initialized_tick(10, false)?;
                assert!(found);
                assert_eq!(next, 50);

                // From tick 50, should find nothing in bounds
                let (next, found) = book_handler.next_initialized_tick(50, false)?;
                assert!(!found);
                assert!(next > MAX_TICK);

                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_ask_tick_cross_word() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Set ticks in different words: 100 (word 0), 300 (word 1), 600 (word 2)
                book_handler.set_tick_bit(100, false)?;
                book_handler.set_tick_bit(300, false)?;
                book_handler.set_tick_bit(600, false)?;

                // From tick 0, should find tick 100 (same word)
                let (next, found) = book_handler.next_initialized_tick(0, false)?;
                assert!(found);
                assert_eq!(next, 100);

                // From tick 100, should find tick 300 (cross word boundary)
                let (next, found) = book_handler.next_initialized_tick(100, false)?;
                assert!(found);
                assert_eq!(next, 300);

                // From tick 300, should find tick 600 (cross word boundary)
                let (next, found) = book_handler.next_initialized_tick(300, false)?;
                assert!(found);
                assert_eq!(next, 600);

                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_bid_tick_same_word() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Set ticks 10 and 50 (both in word 0) for bids
                book_handler.set_tick_bit(10, true)?;
                book_handler.set_tick_bit(50, true)?;

                // From tick 100, should find tick 50
                let (next, found) = book_handler.next_initialized_tick(100, true)?;
                assert!(found);
                assert_eq!(next, 50);

                // From tick 50, should find tick 10
                let (next, found) = book_handler.next_initialized_tick(50, true)?;
                assert!(found);
                assert_eq!(next, 10);

                // From tick 10, should find nothing in bounds
                let (next, found) = book_handler.next_initialized_tick(10, true)?;
                assert!(!found);
                assert!(next < MIN_TICK);

                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_bid_tick_cross_word() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Set ticks in different words for bids: 600 (word 2), 300 (word 1), 100 (word 0)
                book_handler.set_tick_bit(600, true)?;
                book_handler.set_tick_bit(300, true)?;
                book_handler.set_tick_bit(100, true)?;

                // From tick 700, should find tick 600 (same word)
                let (next, found) = book_handler.next_initialized_tick(700, true)?;
                assert!(found);
                assert_eq!(next, 600);

                // From tick 600, should find tick 300 (cross word boundary)
                let (next, found) = book_handler.next_initialized_tick(600, true)?;
                assert!(found);
                assert_eq!(next, 300);

                // From tick 300, should find tick 100 (cross word boundary)
                let (next, found) = book_handler.next_initialized_tick(300, true)?;
                assert!(found);
                assert_eq!(next, 100);

                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_tick_negative_ticks() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Set negative ticks for asks
                book_handler.set_tick_bit(-500, false)?;
                book_handler.set_tick_bit(-100, false)?;
                book_handler.set_tick_bit(50, false)?;

                // From -600, should find -500
                let (next, found) = book_handler.next_initialized_tick(-600, false)?;
                assert!(found);
                assert_eq!(next, -500);

                // From -500, should find -100
                let (next, found) = book_handler.next_initialized_tick(-500, false)?;
                assert!(found);
                assert_eq!(next, -100);

                // From -100, should find 50
                let (next, found) = book_handler.next_initialized_tick(-100, false)?;
                assert!(found);
                assert_eq!(next, 50);

                // Set negative ticks for bids
                book_handler.set_tick_bit(-100, true)?;
                book_handler.set_tick_bit(-500, true)?;

                // From 0, should find -100
                let (next, found) = book_handler.next_initialized_tick(0, true)?;
                assert!(found);
                assert_eq!(next, -100);

                // From -100, should find -500
                let (next, found) = book_handler.next_initialized_tick(-100, true)?;
                assert!(found);
                assert_eq!(next, -500);

                Ok(())
            })
        }

        #[test]
        fn test_next_initialized_tick_at_word_boundary() -> eyre::Result<()> {
            let mut storage = HashMapStorageProvider::new(1);
            StorageCtx::enter(&mut storage, || {
                let mut exchange = StablecoinDEX::new();
                exchange.initialize()?;
                let book_handler = &mut exchange.books[BOOK_KEY];

                // Test exact word boundaries (256, 512, -256, -512)
                book_handler.set_tick_bit(255, false)?; // Last bit of word 0
                book_handler.set_tick_bit(256, false)?; // First bit of word 1

                // From 254, should find 255
                let (next, found) = book_handler.next_initialized_tick(254, false)?;
                assert!(found);
                assert_eq!(next, 255);

                // From 255, should find 256 (cross word)
                let (next, found) = book_handler.next_initialized_tick(255, false)?;
                assert!(found);
                assert_eq!(next, 256);

                // Test bid direction at word boundary
                book_handler.set_tick_bit(256, true)?;
                book_handler.set_tick_bit(255, true)?;

                // From 257, should find 256
                let (next, found) = book_handler.next_initialized_tick(257, true)?;
                assert!(found);
                assert_eq!(next, 256);

                // From 256, should find 255 (cross word going down)
                let (next, found) = book_handler.next_initialized_tick(256, true)?;
                assert!(found);
                assert_eq!(next, 255);

                Ok(())
            })
        }
    }

    mod rounding_tests {
        use super::*;

        #[test]
        fn test_base_to_quote_rounds_down_correctly() {
            let base_amount = 1_000_003u128;
            let tick = 0i16;

            let quote_down = base_to_quote(base_amount, tick, RoundingDirection::Down).unwrap();
            let quote_up = base_to_quote(base_amount, tick, RoundingDirection::Up).unwrap();

            assert_eq!(quote_down, 1_000_003);
            assert_eq!(quote_up, 1_000_003);
        }

        #[test]
        fn test_base_to_quote_rounds_up_when_remainder_exists() {
            let base_amount = 33u128;
            let tick = 100i16;

            let price = tick_to_price(tick) as u128;
            let numerator = base_amount * price;
            let has_remainder = !numerator.is_multiple_of(PRICE_SCALE as u128);

            let quote_down = base_to_quote(base_amount, tick, RoundingDirection::Down).unwrap();
            let quote_up = base_to_quote(base_amount, tick, RoundingDirection::Up).unwrap();

            if has_remainder {
                assert_eq!(
                    quote_up,
                    quote_down + 1,
                    "Round up should be 1 more than round down when there's a remainder"
                );
            } else {
                assert_eq!(
                    quote_up, quote_down,
                    "Round up and down should be equal when there's no remainder"
                );
            }
        }

        #[test]
        fn test_quote_to_base_rounds_down_correctly() {
            let quote_amount = 1_000_003u128;
            let tick = 0i16;

            let base_down = quote_to_base(quote_amount, tick, RoundingDirection::Down).unwrap();
            let base_up = quote_to_base(quote_amount, tick, RoundingDirection::Up).unwrap();

            assert_eq!(base_down, 1_000_003);
            assert_eq!(base_up, 1_000_003);
        }

        #[test]
        fn test_quote_to_base_rounds_up_when_remainder_exists() {
            let quote_amount = 33u128;
            let tick = 100i16;

            let price = tick_to_price(tick) as u128;
            let numerator = quote_amount * PRICE_SCALE as u128;
            let has_remainder = !numerator.is_multiple_of(price);

            let base_down = quote_to_base(quote_amount, tick, RoundingDirection::Down).unwrap();
            let base_up = quote_to_base(quote_amount, tick, RoundingDirection::Up).unwrap();

            if has_remainder {
                assert_eq!(
                    base_up,
                    base_down + 1,
                    "Round up should be 1 more than round down when there's a remainder"
                );
            } else {
                assert_eq!(
                    base_up, base_down,
                    "Round up and down should be equal when there's no remainder"
                );
            }
        }

        #[test]
        fn test_rounding_favors_protocol_for_bid_escrow() {
            let base_amount = 10_000_001u128;
            let tick = 100i16;

            let escrow_floor = base_to_quote(base_amount, tick, RoundingDirection::Down).unwrap();
            let escrow_ceil = base_to_quote(base_amount, tick, RoundingDirection::Up).unwrap();

            assert!(
                escrow_ceil >= escrow_floor,
                "Ceiling should never be less than floor"
            );
        }

        #[test]
        fn test_rounding_favors_protocol_for_settlement() {
            let base_amount = 10_000_001u128;
            let tick = 100i16;

            let payout_floor = base_to_quote(base_amount, tick, RoundingDirection::Down).unwrap();
            let payout_ceil = base_to_quote(base_amount, tick, RoundingDirection::Up).unwrap();

            assert!(
                payout_floor <= payout_ceil,
                "Floor should never be more than ceiling"
            );
        }
    }

    mod u256_upcast_tests {
        use super::*;

        #[test]
        fn test_base_to_quote_large_amount_no_overflow() {
            let large_base_amount: u128 = u128::MAX / 100_000;
            let result = base_to_quote(large_base_amount, MAX_TICK, RoundingDirection::Down);

            assert!(
                result.is_some(),
                "base_to_quote should handle large amounts without overflow using U256"
            );

            let expected = large_base_amount
                .checked_mul(102)
                .and_then(|v| v.checked_div(100));
            assert_eq!(result, expected);
        }

        #[test]
        fn test_quote_to_base_large_amount_no_overflow() {
            let large_quote_amount: u128 = (u128::MAX / PRICE_SCALE as u128) + 1;

            assert!(
                large_quote_amount
                    .checked_mul(PRICE_SCALE as u128)
                    .is_none(),
                "Test setup: this value should overflow u128 multiplication"
            );

            let result = quote_to_base(large_quote_amount, MAX_TICK, RoundingDirection::Down);

            assert!(
                result.is_some(),
                "quote_to_base should handle large amounts without overflow using U256"
            );
        }
    }
}