←Back to ProjectsPROJECT // SAMEX

SAMEX

Cryptocurrency Spot Matching Engine & Distributed Trading Infrastructure

Overview

An event-driven spot cryptocurrency trading platform and order matching engine built with Turborepo, Bun, Apache Kafka, Redis, and Rust. Features an in-memory Central Limit Order Book (CLOB), exact integer accounting in cents, and real-time price streaming with <50ms end-to-end latency.

Streaming Latency
< 50 ms E2E
User Capacity
100,000+ Users
Kafka Throughput
10,000+ msg/s
Redis Cache Speed
100,000+ ops/s
Headless Backend Architecture • No Graphical UIEvent-Driven Services
Execution Core
In-Memory Rust CLOB with FIFO Price-Time Priority
Data Ingestion
Bun Poller • Apache Kafka • Express API
State & Persistence
Atomic Redis OTP • PostgreSQL via Prisma
Technologies:
BunRustApache KafkaRedisTypeScriptNext.js 14Express.jsPostgreSQLPrisma ORMZodWebSockets

THE PROBLEM

Building reliable cryptocurrency trading backends and matching systems requires addressing several core concurrency, state, and accounting challenges:

1. Database Contention During High Order Volume:

Executing order matching directly inside relational database transactions causes lock contention, connection pool exhaustion, and latency spikes under load.

2. Floating-Point Rounding Drift:

Using standard IEEE-754 floating-point numbers for fractional asset balances introduces precision drift. Over millions of fills, tiny rounding discrepancies accumulate into ledger imbalances.

3. Opposite Position Handling in Spot Margin Trades:

In spot margin trading, if a user holding an open short position places a buy order, an engine must close the short first rather than mistakenly opening an opposing long position, which would create double-exposure risk and incorrect PnL.

4. Execution Timing & Stale Market Data:

Matching orders or evaluating liquidations against stale prices can cause inaccurate fills. Real-time mark prices and verified entry/closing prices must be maintained continuously.

5. Authentication Replays & Race Conditions:

OTP verification endpoints must prevent replay attacks and race conditions on concurrent verification requests.

6. Broadcasting Market Data at Scale:

Synchronously serving order book updates to thousands of web clients can saturate server I/O and degrade response times.

THE SOLUTION

SAMEX is a microservices-based trading system organized as a Turborepo monorepo. It decouples trade ingestion, order matching, market data streaming, and persistence across services connected via Apache Kafka and Redis.

Core Architecture Highlights:

•In-Memory Rust Matching Engine: A Central Limit Order Book (CLOB) using BTreeMap and FIFO ring buffers for sub-microsecond price-time priority matching with exact integer accounting in cents ($100,000.00 = 10,000,000 cents).
•Low-Latency Price Streaming: A Bun-powered WebSocket poller ingesting Backpack Exchange bookTicker feeds and publishing to Kafka, delivering updates to 1,000+ clients with <50ms end-to-end latency.
•Asynchronous Request-Response: Kafka topics handle user verification, balance checks, and trade persistence without blocking HTTP gateways.
•Atomic State Caching: Redis-backed OTP verification with atomic match-and-delete to prevent replay attacks, paired with fast session caching.
•Spot Margin & Position Closing: Settles open opposite positions before opening new exposure, with verified PnL accounting.

HIGH-LEVEL SYSTEM ARCHITECTURE

+-------------------------------------------------------------------------------------------------+
|                                    SAMEX SYSTEM ARCHITECTURE                                    |
+-------------------------------------------------------------------------------------------------+

    ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
    │      Next.js Web Trading App      │               │     External Exchange (Backpack)  │
    │  - Real-Time Trading Terminal     │               │  - Real-time bookTicker stream    │
    │  - Live Order Book & Charting     │               └─────────────────┬─────────────────┘
    └─────────────────┬─────────────────┘                                 │
                      │ (HTTP & WebSocket)                                │ (WebSocket)
                      ▼                                                   ▼
    ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
    │       API Server (Express/TS)     │               │        Poller Microservice        │
    │  - WebSocket Broadcaster (Port 8080)              │  - Bun Runtime + WS Client        │
    │  - Auth & Trade Endpoints (3001)  │               │  - Zod Ticker Schema Validation   │
    │  - Redis Session & Price Cache    │               │  - Publishes to `price-updates`   │
    └─────────────────┬─────────────────┘               └─────────────────┬─────────────────┘
                      │ (Produce Requests)                                │ (Produce Tickers)
                      ▼                                                   ▼
    ┌───────────────────────────────────────────────────────────────────────────────────────┐
    │                             APACHE KAFKA MESSAGE BROKER                               │
    │  Topics: user-requests | user-responses | price-updates | trade-requests | responses  │
    └─────────────────┬───────────────────────────────────────────────────┬─────────────────┘
                      │ (Consume Trades)                                  │ (Consume User/DB)
                      ▼                                                   ▼
    ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
    │      Rust Matching Engine         │               │     DB Processor (Bun + KafkaJS)  │
    │  - Central Limit Order Book (CLOB)│               │  - Async User Auth & Creation     │
    │  - Spot Margin & Position Logic   │               │  - Balance & Holdings Management  │
    │  - Realized PnL & Liquidation     │               │  - Prisma ORM + PostgreSQL        │
    │  - Integer Arithmetic (Cents)     │               │  - Completely Stateless & Scalable│
    └───────────────────────────────────┘               └───────────────────────────────────┘

SYSTEM ARCHITECTURE & DEEP DIVE

1. In-Memory Rust Matching Engine (apps/engine)

•Central Limit Order Book (CLOB) Data Structures (src/modules/order_matching.rs):

Implemented in Rust using BTreeMap<Price, VecDeque<Order>> for bid and ask order ladders. Provides O(1) order insertion at existing price levels and O(log N) price tree traversal. Orders matching price criteria are executed strictly in FIFO sequence from ring buffers.

•Integer Accounting (Cents):

All asset prices, margin requirements, account balances, and order quantities are computed in integer cents ($68,452.18 = 6845218 cents, $100,000 = 10000000 cents). This eliminates floating-point epsilon inaccuracies and financial drift.

•Spot Margin & Opposite Position Resolution (src/modules/execution.rs & pnl.rs):

- Position Invariant: Enforces that a user cannot hold both long and short positions simultaneously for the same asset. - Opposite Position Closure: When a user with an open short executes a buy order, the engine automatically detects the existing short position, matches against it, unlocks margin, and logs realized PnL based on entry_price and close_price in the Trade struct: Realized PnL (Short) = (Entry Price - Close Price) * Quantity Realized PnL (Long) = (Close Price - Entry Price) * Quantity - Only opens a new position if no opposite position exists or if residual quantity remains after complete closure.

•Deferred Trade Execution (src/modules/processor.rs):

When a trade request is consumed from Kafka, the engine stages the order and emits a balance inquiry to the DB processor. Matching only executes after the DB processor verifies adequate balance, preventing overdrafts.

•Real-Time Liquidation Engine (src/modules/liquidations.rs):

Continuously evaluates open position margins against incoming price ticks from the price-updates topic. If maintenance margin drops below threshold, liquidation triggers to protect exchange solvency.

2. Market Data Streaming (apps/poller & apps/api-server)

•Persistent WebSocket Ingestion (apps/poller/src/index.ts):

The Poller microservice (powered by Bun) maintains a resilient WebSocket connection to Backpack Exchange (wss://ws.backpack.exchange/), subscribing to real-time bookTicker feeds for SOL_USDC, BTC_USDC, ETH_USDC, DOGE_USDC, and BNB_USDC. Features automatic reconnection and rate limit backoff.

•Zod Schema Validation (packages/schemas):

Incoming payloads are validated before being published to the price-updates Kafka topic.

•WebSocket Broadcasting (apps/api-server/src/index.ts):

The API server consumes ticker updates from Kafka and broadcasts differentials to over 1,000 active WebSocket clients on port 8080.

•In-Memory Price Snapshots:

Concurrently updates latest prices in Redis with short TTLs for microsecond HTTP queries via GET /api/v1/prices.

3. Asynchronous Database Processor (apps/db-processor)

•Decoupled Kafka Consumer:

Built with Bun, KafkaJS, and Prisma ORM. Listens to user-requests (existence checks, user creation, credential validation, balance queries) and produces answers to user-responses.

•Complete Database Isolation:

Database operations execute asynchronously out-of-band, separated from HTTP gateways and matching engines.

•Horizontal Scalability:

Stateless architecture allows running multiple consumer replicas across Kafka consumer groups.

4. Security, Authentication & Session Handling

•Atomic Redis OTP Verification:

OTPs are hashed and stored in Redis with a 5-minute TTL. Verification executes as an atomic Redis transaction where matching and deletion occur in the same operation to prevent replay exploits.

•Credential Management:

Salted bcrypt password hashing with 12 salt rounds, and JWT session tokens delivered via httpOnly cookies.

TESTING, VERIFICATION & BENCHMARKS

8-Payload Test Suite (plans/payload_testing.md):

Sequence of Verified Test Payloads:
1. User A places Buy Limit @ 11,000,000 (margin: 5000000, qty: 1.0) -> Added to book (Status: Open)
2. User B places Sell Market (margin: 5000000, qty: 1.0)           -> Matched @ 110k; User B opens SHORT
3. User B places Buy Limit @ 10,900,000 (margin: 5000000, qty: 1.0) -> Matched; closes User B SHORT (+100,000 PnL)
4. User A places Sell Market (margin: 5000000, qty: 1.0)           -> Matched @ 109k; closes User A LONG (-100,000 PnL)
5. User A places Buy Limit @ 12,000,000 (margin: 5000000, qty: 1.0) -> Added to book (Status: Open)
6. User B places Sell Market (margin: 5000000, qty: 1.0)           -> Matched @ 120k; User B opens SHORT
7. User B places Buy Limit @ 12,100,000 (margin: 5000000, qty: 1.0) -> Matched; closes User B SHORT (-100,000 PnL)
8. User A places Sell Market (margin: 5000000, qty: 1.0)           -> Matched @ 121k; closes User A LONG (+100,000 PnL)

Verified Test Outcomes:

•User A: Completed two cycles (110k->109k, 120k->121k). Realized -$1,000 loss on cycle 1, +$1,000 profit on cycle 2. Margin unlocked, net balance 500,000 USD, 10 BTC.
•User B: Completed two cycles (110k->109k, 120k->121k). Realized +$1,000 profit on cycle 1, -$1,000 loss on cycle 2. Margin unlocked, net balance 500,000 USD, 10 BTC.
•Zero open positions remaining; zero orphaned contracts; margin released correctly.

Spot Margin Profit/Loss Test Flow:

•Initial: User A and User B both start with 500,000 USD balance.
•Step 1: User A Buy 1 BTC @ 100,000 USD limit (10,000,000 cents); User B Sell 1 BTC @ 100,000 USD market.
•Step 2: User A Sell 1 BTC @ 101,000 USD limit (10,100,000 cents); User B Buy 1 BTC @ 101,000 USD market.
•Outcome: User A final balance = $501,000 USD (+$1,000 profit). User B final balance = $499,000 USD (-$1,000 loss). All margin unlocked.

Performance & Latency Benchmarks:

Operation / SubsystemMeasured LatencyThroughput / CapacityImplementation Notes
Market Data Streaming (E2E)< 50 ms1,000+ WS clientsBackpack WS -> Poller -> Kafka -> API -> Web Client
User Signin (Auth)~200 msHigh-throughputKafka round-trip + bcrypt hashing (12 rounds)
Verify OTP & Account Create~270 msHigh-throughputKafka request-response + atomic Redis + PostgreSQL
Session & Profile (/me)< 10 ms100,000+ ops/secRedis in-memory cache lookup
Kafka Message Broker< 5 ms per hop10,000+ msg/secDual-partition broker cluster with KafkaJS
Redis In-Memory Operations< 1 ms100,000+ ops/secSession tokens, OTP with TTL, price cache
User Signup Flow~3.5 sScalableSMTP email dispatch bottleneck (Gmail)
PROJECT // SAMEX[ Back to Projects ↑ ]