EuNEx Developers Guide

1. Overview

EuNEx (Euronext Exchange Simulator) is a C++20 actor-based matching engine that mirrors the Euronext Optiq production architecture. It implements the full order lifecycle: entry, validation, matching, market data dissemination, trade clearing, and FIX protocol connectivity.

2. Architecture

High-Level System Diagram

3. Optiq Naming Alignment

EuNEx components mirror Euronext Optiq production terminology:

OEG Order Entry Gateway — ME Matching Engine — MDG Market Data Gateway — KFK Kafka Bus

4. Actor Topology

Core Affinity Layout

5. Data Flow

Order Lifecycle (New Limit Order)

6. Core Components

6.1 SimplxShim — Actor Framework

The actor engine emulates the Tredzone Simplx framework API:

6.2 Types

Price_t       = int64_t     // Fixed-point, PRICE_SCALE = 100'000'000
Quantity_t    = uint64_t
OrderId_t     = uint64_t    // Exchange-assigned order ID
ClOrdId_t     = uint64_t    // Client order ID
SymbolIndex_t = uint32_t    // Instrument identifier
SessionId_t   = uint16_t    // Client session identifier
MemberId_t    = uint16_t    // Clearing member identifier

6.3 Price Conversion

Price_t px = toFixedPrice(150.25);  // → 15'025'000'000
double  d  = toDouble(px);          // → 150.25

7. Event System

Events flow between actors via Event::Pipe. Each event struct inherits tredzone::Actor::Event:

Usage Pattern

// In MECoreActor constructor:
oePipe_ = Event::Pipe(*this, oeGatewayId);
mdPipe_ = Event::Pipe(*this, marketDataId);

// Pushing an event (lock-free):
oePipe_.push<ExecReportEvent>(report, sessionId);
mdPipe_.push<TradeEvent>(trade);

8. Order Book & Matching

Order Types & TIF

9. Recovery & IACA

RecoveryProxy

Master/Mirror gating for high availability. cause() always executes (both sides). effect() only on Master. recoveryEffect() only on Mirror during failover replay.

IACA Fragment Chains

Fragments form a tree. Completion check: sum(nextCount) == total_fragments - 1. On completion, the handler fires and generates IA SBE messages.

10. Kafka Bus

The Kafka Bus (src/persistence/KafkaBus.hpp) mirrors the Optiq KFK that connects ME to downstream consumers: MDG, PTB, Clearing, IDS, SATURN.

Topics

Compile-Time Toggle

cmake .. -DEUNEX_USE_KAFKA=ON    # requires librdkafka-dev
cmake .. -DEUNEX_USE_KAFKA=OFF   # no-op stub (default)

Runtime

export EUNEX_KAFKA_BROKERS=kafka:9092
./eunex_me

Docker Deployment

docker/docker-compose.yml runs Kafka in KRaft mode (no ZooKeeper) using apache/kafka:3.9.0, creates all topics via kafka-init, then starts the engine.

cd docker
docker compose up --build

11. FIX Protocol Gateway

TCP server on port 9001 with per-client receive threads. Parses FIX 4.4 messages and routes to the actor engine via Event::Pipe.

Symbol Mapping

12. Clearing House

Receives TradeEvent from MECoreActor. Maps sessions to 10 clearing members. Tracks capital, holdings per symbol, P&L, and trade counts.

On each trade: Buy side reduces capital, updates weighted average cost. Sell side adds proceeds, realizes P&L. getLeaderboard() returns members sorted by capital (thread-safe, mutex-protected).

13. AI Trading Members

10 automated trading members with 3 rotating strategies:

Data sources: BookUpdateEvent (BBO), TradeEvent (price history), ExecReportEvent (fill confirmations).

Output: NewOrderEvent → OEGActor via Event::Pipe, ~3s intervals via Actor::Callback.

14. Project Structure

EuNEx/
├── CMakeLists.txt                    Build configuration
├── README.md                         Project overview
├── src/
│   ├── main.cpp                      Entry point, actor wiring
│   ├── common/
│   │   ├── Types.hpp                 Core types (Price_t, Order, Trade)
│   │   ├── Book.hpp / Book.cpp       Price-time priority matching
│   ├── engine/
│   │   └── SimplxShim.hpp            Actor framework (Simplx API)
│   ├── actors/
│   │   ├── Events.hpp                Inter-actor event definitions
│   │   ├── OEGActor.hpp/cpp          Order Entry Gateway
│   │   ├── MECoreActor.hpp/cpp       Matching Engine core (per symbol)
│   │   ├── MDGActor.hpp/cpp          Market Data Gateway
│   │   ├── FIXAcceptorActor.hpp/cpp  FIX 4.4 TCP protocol gateway
│   │   ├── ClearingHouseActor.hpp/cpp Trade clearing & positions
│   │   └── AITraderActor.hpp/cpp     Automated trading members
│   ├── net/SocketCompat.hpp          Cross-platform sockets
│   ├── persistence/
│   │   ├── KafkaBus.hpp              Multi-topic Kafka publisher
│   │   ├── PersistenceStore.hpp      Store interface
│   │   └── KafkaStore.hpp            Kafka adapter (optional)
│   ├── recovery/RecoveryProxy.hpp    Master/Mirror recovery
│   └── iaca/
│       ├── Fragment.hpp              IACA fragment definitions
│       └── IacaAggregator.hpp/cpp    Fragment chain assembly
├── tests/                            7 test suites
├── examples/                         ping_pong, simple_match
├── dashboard/                        Flask web UI (:8090)
├── clearing_house/                   Flask clearing UI (:8091)
├── fix_gateway/                      Python FIX gateway (alt)
└── docker/
    ├── Dockerfile                    Multi-stage build
    ├── docker-compose.yml            Kafka + engine + nginx
    └── nginx.conf                    Reverse proxy config

15. Build & Test

Prerequisites

• C++20 compiler: MSVC 19.30+, GCC 12+, Clang 15+
• CMake: 3.16+
• Optional: librdkafka (for Kafka persistence)

Build Commands

# Configure
cmake -B build -DEUNEX_BUILD_TESTS=ON

# Build
cmake --build build --config Release

# Run tests (7 suites)
cd build && ctest -C Release

# Run engine
./build/Release/eunex_me

CMake Options

Test Suites

16. Configuration

Seed Orders

AAPL:   Sell 155.00/100, 154.00/200  |  Buy 153.00/150, 152.00/100
MSFT:   Sell 325.00/100, 324.00/150  |  Buy 323.00/200, 322.00/100
GOOGL:  Sell 142.00/100, 141.00/200  |  Buy 140.00/150, 139.00/100
EURO50: Sell 5050.00/50, 5040.00/80  |  Buy 5030.00/60, 5020.00/40

17. Extending EuNEx

Adding a New Symbol

1. Define a new SymbolIndex_t constant in main.cpp
2. Create a MECoreActor passing OEG, MDG, CH actor IDs
3. Register: oeGateway->mapSymbol(newSym, bookActor->getActorId())
4. Add to AITraderActor's symbol list
5. Add seed orders if desired

Adding a New Actor

1. Create src/actors/MyActor.hpp inheriting tredzone::Actor
2. Register event handlers: registerEventHandler<EventT>(*this)
3. Create Event::Pipe members for destination actors
4. Add .cpp to EUNEX_CORE_SOURCES in CMakeLists.txt
5. Wire into topology in main.cpp

Adding a New Event Type

1. Define struct in Events.hpp inheriting tredzone::Actor::Event
2. Add onEvent(const MyEvent&) to receiving actors
3. Register: registerEventHandler<MyEvent>(*this)
4. Push: pipe.push<MyEvent>(args...)

Adding a New Trading Strategy

1. Add enum value to Strategy in AITraderActor.hpp
2. Implement strategyMyStrategy() method
3. Add case to submitOrder() switch
4. Assign to members in initMembers()