DEX Order Book Liquidity Depth Sampler

[Kingsman-99]

Description

Before routing a large split payment through the Stellar DEX, the SDK should sample the order book depth to estimate price impact and warn when available liquidity is insufficient to fill the payment without excessive slippage. The current src/pathRouter.ts routes blindly without checking order book depth. A depth sampler should query the Horizon order book and compute fill cost for the target amount.

Technical Context

Add src/orderBookSampler.ts. Uses @stellar/stellar-sdk Server.orderbook() to fetch the order book for a given asset pair. Simulates a market order fill by walking the asks or bids array and computing cumulative fill cost and slippage percentage. Adds OrderBookSample and FillEstimate to src/types.ts. src/pathRouter.ts calls the sampler and emits highSlippageWarning via src/events.ts when slippage exceeds a threshold.

Acceptance Criteria

• OrderBookSampler.sample(baseAsset, counterAsset, side: 'buy' | 'sell', amount): Promise<FillEstimate> returns { estimatedCost, slippagePercent, worstPrice, filledAtLevels }
• Computes slippage as (worstPrice - bestPrice) / bestPrice × 100
• Returns { filledFraction: number < 1 } when the order book cannot fill the full amount at any price
• src/pathRouter.ts calls sample() before selecting a DEX path and emits highSlippageWarning when slippagePercent > slippageTolerancePercent
• Unit tests with mock order book data assert correct fill simulation for: full fill, partial fill, zero liquidity
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---