Order book sorting documentation mismatch: bids/asks ordering is reversed

[tarasenk]

Description

The documentation on BookUpdate claims bids are sorted "descending" and asks "ascending", but the actual WebSocket data arrives with the opposite sorting.

Current Behavior (per docs)

/// Current bid levels (price descending)
pub bids: Vec<OrderBookLevel>,
/// Current ask levels (price ascending)
pub asks: Vec<OrderBookLevel>,

Actual Behavior

Bids: Price ascending (lowest → highest)
Asks: Price descending (highest → lowest)

Reproduction

use futures::StreamExt;
use polymarket_client_sdk::clob::ws::Client;
use polymarket_client_sdk::types::U256;
use std::str::FromStr;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::default();
    let asset_ids = vec![
        U256::from_str("77893140510362582253172593084218413010407941075415081594586195705930819989216")?,
    ];
    
    let stream = client.subscribe_orderbook(asset_ids)?;
    let mut stream = Box::pin(stream);

    while let Some(Ok(book)) = stream.next().await {
        println!("bids len: {} | asks len: {}", book.bids.len(), book.asks.len());
        
        if let (Some(first), Some(last)) = (book.bids.first(), book.bids.last()) {
            println!("bids.first(): {} | bids.last(): {}", first.price, last.price);
        }
        
        if let (Some(first), Some(last)) = (book.asks.first(), book.asks.last()) {
            println!("asks.first(): {} | asks.last(): {}", first.price, last.price);
        }
        
        let bids_asc = book.bids.windows(2).all(|w| w[0].price <= w[1].price);
        let asks_desc = book.asks.windows(2).all(|w| w[0].price >= w[1].price);
        println!("bids ascending: {} | asks descending: {}", bids_asc, asks_desc);
    }
    Ok(())
}

Output

bids len: 13 | asks len: 86
bids.first(): 0.01 | bids.last(): 0.13
asks.first(): 0.99 | asks.last(): 0.14
bids ascending: true | asks descending: true

Impact

Users relying on bids.first() for best bid or asks.first() for best ask will get the worst prices instead.

Suggested Fix

Update documentation to match actual behavior:

/// Current bid levels (price ascending)
pub bids: Vec<OrderBookLevel>,
/// Current ask levels (price descending)
pub asks: Vec<OrderBookLevel>,