M3 #26: Rust SDK: Core types and shared definitions

[joaquinbejar]

Summary

Implements the core types for the Rust SDK that mirror the on-chain types and provide a foundation for client-side operations. These types are shared across HTTP and WebSocket clients.

Changes

New Crate: sdk/

File	Description
Cargo.toml	SDK crate dependencies
src/lib.rs	Crate root with exports
src/error.rs	SdkError for SDK operations
src/types/mod.rs	Types module exports
src/types/primitives.rs	Price, Quantity, Side
src/types/order.rs	OrderType, TimeInForce, OrderStatus, Order
src/types/market.rs	Market with conversion utilities
src/types/book.rs	BookLevel, OrderBook, BookChange
src/types/trade.rs	Trade type
src/types/balance.rs	Balance type

Core Value Types

• Price: Newtype wrapper for u64 with checked/saturating arithmetic
• Quantity: Newtype wrapper for u64 with min/max operations
• Side: Bid/Ask enum with opposite() method

Order Types

• OrderType: Limit, PostOnly, ImmediateOrCancel, FillOrKill
• TimeInForce: GTC, IOC, FOK, PostOnly
• OrderStatus: Open, PartiallyFilled, Filled, Cancelled, Expired
• SelfTradeBehavior: CancelTaker, CancelMaker, DecrementTake, Allow
• PlaceOrderParams: Builder pattern for order parameters
• Order: Full order details with fill tracking

Entity Types

• Market: Addresses, tick/lot sizes, decimals, fees
  • Conversion utilities: price_to_ticks, ticks_to_price, etc.
  • Fee calculation: calculate_taker_fee, calculate_maker_fee
• BookLevel: Price, quantity, order count
• OrderBook: Bids/asks with spread/midpoint calculations
• OrderBookUpdate: Snapshot and Delta variants for streaming
• Trade: Executed trade with buyer/seller helpers
• Balance: Free/locked balances with totals

Features

• Full serde support with camelCase for JSON compatibility
• Display implementations for human-readable output
• TryFrom for enum conversions
• rust_decimal for precise price calculations
• Copy trait for small value types (Price, Quantity, Side)

Technical Decisions

• Newtype pattern: Price and Quantity use newtype wrappers for type safety
• Checked arithmetic: All arithmetic operations have checked variants
• String addresses: Addresses stored as base58 strings for JSON compatibility
• rust_decimal: Used for precise decimal calculations in Market conversions
• serde camelCase: JSON field names use camelCase for JavaScript compatibility

Testing

• 89 unit tests for all types
• Price/Quantity arithmetic tests
• Enum conversion tests (TryFrom)
• Serde serialization/deserialization tests
• Market conversion tests
• OrderBook operations tests
• Doc test for example usage

Checklist

• Code follows .internalDoc/09-rust-guidelines.md
• Documentation added for all public items
• No warnings from cargo clippy
• cargo fmt passes
• All tests pass

Closes #26