# Order Matching Engine

Welcome to the **Order Matching Engine** project. This repository contains a Python-based order matching engine that simulates trades on a mock centralized exchange. It includes:
- A **Matching Engine** to match buy and sell orders.
- A **WebSocket** server to broadcast real-time trades via Redis Pub/Sub.
- Sample code to **simulate** random orders.

---

## Table of Contents

- [Overview](#overview)
- [Project Structure](#project-structure)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
  - [Running the WebSocket Server](#running-the-websocket-server)
  - [Simulating Orders](#simulating-orders)
  - [Observing Trades](#observing-trades)
- [How It Works](#how-it-works)
  - [Matching Logic](#matching-logic)
  - [Order Types](#order-types)
  - [WebSocket Broadcast](#websocket-broadcast)
- [Contributing](#contributing)
- [License](#license)
- [Future Versions: Final Recommendations & Notes](#future-versions-final-recommendations--notes)

---

## Overview

This engine demonstrates how to build and operate a **limit order book** for a digital asset exchange. Features include:

- **Multiple trading pairs** (one order book per pair).
- **Limit and market orders** (with optional stop-limit/stop-market placeholders).
- **Redis Pub/Sub** integration for broadcasting trades in real time.
- **WebSocket** server to push updates to connected clients.
- A simple **simulation** script that generates random buy/sell orders.

---

## Project Structure

```
.
├── config/
│   └── config.py             # Environment configuration (Redis, WebSocket ports, etc.)
├── core/
│   ├── matching_engine.py    # Orchestrates order books, matching logic, trade publishing
│   ├── order_book.py         # Defines the OrderBook, Order objects, partial fills, stops
│   ├── websockets_server.py  # Async WebSocket server for real-time trade updates
│   └── utils.py              # Logging decorators, utility functions
├── logs/
│   └── app.log               # Rotating logs output (ignored by .gitignore)
├── main.py                   # Entry point to run the MatchingEngine & WebSocket server
├── requirements.txt          # Dependencies
├── .gitignore
├── README.md                 # This README
└── myvenv/                   # Local virtual environment (ignored by .gitignore)
```

---

## Requirements

- **Python 3.8+** (recommended)
- **Redis** 5 or above
- Python libraries listed in `requirements.txt`:
  - `websockets==11.0`
  - `redis==5.0.0`
  - `pytest==7.0.0`
  - `uvloop==0.17.0`
  - `loguru==0.6.0`

---

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/your-username/order_matching_engine.git
   cd order_matching_engine
   ```

2. Create and activate a virtual environment:
   ```bash
   python -m venv myvenv
   source myvenv/bin/activate  # On Windows: myvenv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Ensure Redis is running locally on the host and port specified in `config/config.py` (default `localhost:6379`).

---

## Usage

### Running the WebSocket Server

1. Start Redis (if not already running):
   ```bash
   redis-server
   ```

2. In another terminal, start the matching engine and WebSocket server:
   ```bash
   python main.py
   ```

   Example logs:
   ```
   WebSocket server started and running...
   Simulating live order matching...
   ```

---

### Simulating Orders

- The `main.py` script automatically starts a simulation thread that generates random buy/sell orders.
- Orders will appear in the logs (`logs/app.log`) with details like price, quantity, and side.

---

### Observing Trades

#### Redis Pub/Sub:

1. Open a new terminal and run:
   ```bash
   redis-cli
   SUBSCRIBE trades_BTC/USD
   ```
2. You’ll see JSON messages whenever a trade occurs (when prices cross).

#### WebSocket:

1. Use a WebSocket client like `wscat`:
   ```bash
   npm install -g wscat
   wscat -c ws://localhost:8765
   ```
2. You’ll see real-time messages for executed trades.

---

## How It Works

### Matching Logic

- **OrderBook**: Maintains two heaps:
  - Bids (buy orders) stored as negative prices for a max-heap effect.
  - Asks (sell orders) stored as normal (min-heap).
- **MatchingEngine**: Continuously checks if the best bid can match with the best ask.
  - Price crossing: A trade occurs if:
    - `best_bid.price >= best_ask.price` (limit vs limit), or
    - Either is a market order (which matches immediately if the other side exists).
  - Partial fills: If an order isn’t fully filled, its remainder is pushed back into the heap.

### Order Types

- **Limit**: Must match at a specific price or better.
- **Market**: Executes immediately at the best available price(s).
- **Stop-limit / Stop-market**: Triggered only once the market reaches a certain price threshold.

### WebSocket Broadcast

After every matched trade, the engine publishes trade data to Redis:

```json
{
  "trading_pair": "BTC/USD",
  "trades": [
    {
      "buy_order_id": 123,
      "sell_order_id": 456,
      "price": 50000,
      "quantity": 2
    }
  ]
}
```

The WebSocket server subscribes to the `trades_BTC/USD` channel and relays these messages to all connected WebSocket clients.

---

## Contributing

We welcome improvements such as:
- More advanced order types (e.g., GTC, FOK, IOC).
- Enhanced data structures (e.g., skip lists, RB-trees for better performance).
- Scaling solutions (distributed matching, partitioned order books).
- Improved test coverage with `pytest`.

---

## License

This project is released under the MIT License. Feel free to adapt and use it for your own projects.

---

## Future Versions: 

### Performance Optimization
- Migrate to a lower-level language or specialized data structures for ultra-low latency.
- Consider asynchronous or distributed architectures to handle large volumes of orders in parallel.

### Stop Orders
- Enrich the logic to trigger stops on the best bid/ask rather than last traded price, or integrate with a real price feed.

### Order Persistence
- Implement a robust database layer (SQL/NoSQL) for historical records, compliance, and auditing.

### Risk and Balance Management
- Introduce user balances, margin checks, and risk limits before matching an order.

### Advanced Orders
- Support time-in-force policies: Good-Til-Canceled (GTC), Immediate-Or-Cancel (IOC), Fill-Or-Kill (FOK).
- Add features like iceberg orders or trailing stop orders.

### Microservices & Scalability
- Separate the matching engine from the API and the data store to allow horizontal scaling.
- Use a high-speed message bus (e.g., NATS, Kafka, or ZeroMQ) for real-time order streaming.

This roadmap is designed for building a production-grade order matching system that can scale with higher throughput and more sophisticated features.