add MockExchange for offline development and testing

[mooncitydev]

closes #19

what this does

adds MockExchange — a fully offline, zero-network exchange implementation built on top of @faker-js/faker. it lets developers write and test application code against pmxt without real API keys or an internet connection, which is especially useful in CI/CD pipelines and during rapid prototyping.

how it works

MockExchange extends PredictionMarketExchange and overrides every relevant method with local in-memory implementations. faker is seeded deterministically from each market/outcome id, so the same call always returns the same data across runs — you can write stable assertions against it.

features

• fetchMarkets / fetchEvents — generates realistic binary and multi-outcome markets grouped into events, with prices, volumes, slugs, tags, and categories
• fetchOrderBook — produces a realistic CLOB-style bid/ask ladder centred around the mid price
• fetchOHLCV — generates candlestick data for any resolution (1m through 1d) and any date range
• fetchTrades — returns a list of fake historical trades for an outcome
• fetchBalance — returns a configurable starting USDC balance
• createOrder — records the order in-memory, updates balance and positions, simulates a configurable latency (default 100ms), always fills
• full order lifecycle: cancelOrder, fetchOrder, fetchOpenOrders, fetchClosedOrders, fetchAllOrders, fetchMyTrades
• fetchPositions — returns live position state derived from all trades placed so far
• buildOrder / submitOrder — supported
• reset() — clears all orders, positions and trades between test cases

usage

import pmxt from 'pmxtjs';

const exchange = new pmxt.Mock({ marketCount: 20, balance: 5000 });

const markets = await exchange.fetchMarkets();
const order = await exchange.createOrder({
  marketId: markets[0].marketId,
  outcomeId: markets[0].yes!.outcomeId,
  side: 'buy',
  type: 'limit',
  price: 0.55,
  amount: 10,
});
console.log(order.status); // 'filled'

const [balance] = await exchange.fetchBalance();
console.log(balance.available); // 4994.5

exchange.reset(); // clean state for next test

made by mooncitydev

[realfishsam]

Thanks for this — the concept is solid and it covers the issue requirements well. A few things to address before this is ready to merge:

@faker-js/faker as a production dependency

This is the main concern. faker is ~3.5MB and it would ship to every pmxt-core consumer even if they never use MockExchange. A few options:

1. Drop faker entirely — a simple seeded PRNG with the existing templates would produce the same deterministic output at zero dependency cost.
2. Use a dynamic import() so it's only loaded when MockExchange is actually instantiated.
3. Move MockExchange to a separate optional package.

Option 1 is probably the cleanest here since the data generation doesn't need faker's full feature set.

No tests

610 lines of order lifecycle, balance accounting, and position tracking need test coverage. The position math (entry price averaging, PnL) and balance deductions are especially important to verify.

Orders always fill immediately

createOrder always sets status to filled, which means cancelOrder can never actually work (it rejects anything that isn't open or pending), and fetchOpenOrders always returns empty. Consider adding a way to simulate partial fills or pending orders so consumers can test those flows too.

Mutation

Position tracking and cancelOrder mutate stored objects in place (existing.size = ..., order.status = 'cancelled'). We use immutable patterns in this codebase — create new objects instead of modifying existing ones.

Minor

• _outcomePrice on InternalOrder is set but never read.
• Market-type orders get a random price from faker rather than using the order book mid-price.

The foundation here is good — deterministic seeding, proper BaseExchange contract, reset() for test isolation, configurable options. Worth iterating on rather than starting over.