Merge pull request #436 from sadeeq6400/swap-matching

Feat: Implement Swap Matching Engine

Author: DevMuhdishaq

src/app.module.ts

@@ -113,6 +113,7 @@ import { WalletLedger } from './wallet/entities/wallet-ledger.entity';
 import { LedgerEntry } from './wallet/entities/ledger-entry.entity';
 import { WithdrawalRequest } from './wallet/entities/withdrawal-request.entity';
 import { FiatPaymentIntent } from './wallet/entities/fiat-payment-intent.entity';
+import { TradingModule } from './trading/trading.module';
 
 @Module({
   imports: [
@@ -267,6 +268,7 @@ import { FiatPaymentIntent } from './wallet/entities/fiat-payment-intent.entity'
     EscrowSettlementModule,
     // ── Wallet & Payments Integration ──
     WalletModule,
+    TradingModule,
 
     // ── Error Handling ──
     ErrorModule,

src/trading/controllers/trading.controller.spec.ts

@@ -0,0 +1,50 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { TradingController } from './trading.controller';
+import { TradingService } from '../services/trading.service';
+import { CreateOrderDto } from '../dto/create-order.dto';
+import { OrderSide, OrderType, OrderStatus } from '../enums/order.enum';
+import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
+
+describe('TradingController', () => {
+  let controller: TradingController;
+  let service: TradingService;
+
+  beforeEach(async () => {
+    const mockTradingService = {
+      createOrder: jest.fn().mockImplementation((userId, dto) =>
+        Promise.resolve({
+          id: 'order-123',
+          userId,
+          ...dto,
+          status: OrderStatus.OPEN,
+        }),
+      ),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [TradingController],
+      providers: [{ provide: TradingService, useValue: mockTradingService }],
+    })
+      .overrideGuard(JwtAuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get<TradingController>(TradingController);
+    service = module.get<TradingService>(TradingService);
+  });
+
+  it('should create order for authenticated user', async () => {
+    const req = { user: { userId: 'user-456' } };
+    const dto: CreateOrderDto = {
+      assetPair: 'SOL/USDC',
+      side: OrderSide.BUY,
+      type: OrderType.LIMIT,
+      price: 150,
+      quantity: 5,
+    };
+
+    const result = await controller.createOrder(req, dto);
+    expect(result).toBeDefined();
+    expect(service.createOrder).toHaveBeenCalledWith('user-456', dto);
+  });
+});

src/trading/controllers/trading.controller.ts

@@ -0,0 +1,16 @@
+import { Controller, Post, Body, UseGuards, Req } from '@nestjs/common';
+import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
+import { TradingService } from '../services/trading.service';
+import { CreateOrderDto } from '../dto/create-order.dto';
+
+@Controller('trading')
+export class TradingController {
+  constructor(private readonly tradingService: TradingService) {}
+
+  @Post('orders')
+  @UseGuards(JwtAuthGuard)
+  createOrder(@Req() req, @Body() createOrderDto: CreateOrderDto) {
+    const userId = req.user?.userId || req.user?.id || req.user?.sub;
+    return this.tradingService.createOrder(userId, createOrderDto);
+  }
+}

src/trading/dto/create-order.dto.ts

@@ -0,0 +1,24 @@
+import { IsEnum, IsNotEmpty, IsNumber, IsString } from 'class-validator';
+import { OrderType, OrderSide } from '../enums/order.enum';
+
+export class CreateOrderDto {
+  @IsNotEmpty()
+  @IsString()
+  assetPair: string;
+
+  @IsNotEmpty()
+  @IsEnum(OrderSide)
+  side: OrderSide;
+
+  @IsNotEmpty()
+  @IsEnum(OrderType)
+  type: OrderType;
+
+  @IsNotEmpty()
+  @IsNumber()
+  price: number;
+
+  @IsNotEmpty()
+  @IsNumber()
+  quantity: number;
+}

src/trading/entities/order.entity.ts

@@ -0,0 +1,44 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { OrderType, OrderSide, OrderStatus } from '../enums/order.enum';
+
+@Entity('orders')
+export class Order {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  userId: string;
+
+  @Column()
+  assetPair: string;
+
+  @Column({ type: 'enum', enum: OrderSide })
+  side: OrderSide;
+
+  @Column({ type: 'enum', enum: OrderType })
+  type: OrderType;
+
+  @Column({ type: 'decimal', precision: 18, scale: 8 })
+  price: number;
+
+  @Column({ type: 'decimal', precision: 18, scale: 8 })
+  quantity: number;
+
+  @Column({ type: 'decimal', precision: 18, scale: 8, default: 0 })
+  filledQuantity: number;
+
+  @Column({ type: 'enum', enum: OrderStatus, default: OrderStatus.OPEN })
+  status: OrderStatus;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}

src/trading/entities/trade.entity.ts

@@ -0,0 +1,30 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+} from 'typeorm';
+
+@Entity('trades')
+export class Trade {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  assetPair: string;
+
+  @Column()
+  takerOrderId: string;
+
+  @Column()
+  makerOrderId: string;
+
+  @Column({ type: 'decimal', precision: 18, scale: 8 })
+  price: number;
+
+  @Column({ type: 'decimal', precision: 18, scale: 8 })
+  quantity: number;
+
+  @CreateDateColumn()
+  timestamp: Date;
+}

src/trading/enums/order.enum.ts

@@ -0,0 +1,16 @@
+export enum OrderType {
+  LIMIT = 'LIMIT',
+  MARKET = 'MARKET',
+}
+
+export enum OrderSide {
+  BUY = 'BUY',
+  SELL = 'SELL',
+}
+
+export enum OrderStatus {
+  OPEN = 'OPEN',
+  PARTIALLY_FILLED = 'PARTIALLY_FILLED',
+  FILLED = 'FILLED',
+  CANCELLED = 'CANCELLED',
+}

src/trading/services/matching-engine.service.spec.ts

@@ -0,0 +1,54 @@
+import { MatchingEngine } from './matching-engine.service';
+import { Order } from '../entities/order.entity';
+import { OrderSide, OrderStatus, OrderType } from '../enums/order.enum';
+
+describe('MatchingEngine', () => {
+  let matchingEngine: MatchingEngine;
+
+  beforeEach(() => {
+    matchingEngine = new MatchingEngine();
+  });
+
+  it('should match buy and sell orders when prices overlap', () => {
+    const buyOrder = new Order();
+    buyOrder.id = 'buy-1';
+    buyOrder.userId = 'user-1';
+    buyOrder.assetPair = 'ETH/USDT';
+    buyOrder.side = OrderSide.BUY;
+    buyOrder.type = OrderType.LIMIT;
+    buyOrder.price = 2000;
+    buyOrder.quantity = 2;
+    buyOrder.filledQuantity = 0;
+    buyOrder.status = OrderStatus.OPEN;
+    buyOrder.createdAt = new Date('2026-01-01T00:00:00Z');
+
+    const sellOrder = new Order();
+    sellOrder.id = 'sell-1';
+    sellOrder.userId = 'user-2';
+    sellOrder.assetPair = 'ETH/USDT';
+    sellOrder.side = OrderSide.SELL;
+    sellOrder.type = OrderType.LIMIT;
+    sellOrder.price = 1900;
+    sellOrder.quantity = 1;
+    sellOrder.filledQuantity = 0;
+    sellOrder.status = OrderStatus.OPEN;
+    sellOrder.createdAt = new Date('2026-01-01T00:00:01Z');
+
+    // Add buy order first (no match yet)
+    const trades1 = matchingEngine.addOrder(buyOrder);
+    expect(trades1.length).toBe(0);
+
+    // Add sell order (should match)
+    const trades2 = matchingEngine.addOrder(sellOrder);
+    expect(trades2.length).toBe(1);
+    expect(trades2[0].assetPair).toBe('ETH/USDT');
+    expect(trades2[0].quantity).toBe(1);
+    expect(trades2[0].price).toBe(1900);
+    expect(trades2[0].takerOrderId).toBe('buy-1');
+    expect(trades2[0].makerOrderId).toBe('sell-1');
+
+    expect(sellOrder.status).toBe(OrderStatus.FILLED);
+    expect(buyOrder.status).toBe(OrderStatus.PARTIALLY_FILLED);
+    expect(buyOrder.filledQuantity).toBe(1);
+  });
+});

src/trading/services/matching-engine.service.ts

@@ -0,0 +1,72 @@
+import { Injectable } from '@nestjs/common';
+import { Order } from '../entities/order.entity';
+import { OrderBook } from './order-book.service';
+import { Trade } from '../entities/trade.entity';
+import { OrderStatus, OrderSide } from '../enums/order.enum';
+
+@Injectable()
+export class MatchingEngine {
+  private readonly orderBooks: Map<string, OrderBook> = new Map();
+
+  addOrder(order: Order): Trade[] {
+    const orderBook = this.getOrderBook(order.assetPair);
+    orderBook.addOrder(order);
+    return this.matchOrders(order.assetPair);
+  }
+
+  private getOrderBook(assetPair: string): OrderBook {
+    let book = this.orderBooks.get(assetPair);
+    if (!book) {
+      book = new OrderBook();
+      this.orderBooks.set(assetPair, book);
+    }
+    return book;
+  }
+
+  private matchOrders(assetPair: string): Trade[] {
+    const trades: Trade[] = [];
+    const orderBook = this.getOrderBook(assetPair);
+    const bids = orderBook.getBids();
+    const asks = orderBook.getAsks();
+
+    while (
+      bids.length > 0 &&
+      asks.length > 0 &&
+      bids[0].price >= asks[0].price
+    ) {
+      const bestBid = bids[0];
+      const bestAsk = asks[0];
+      const tradeQuantity = Math.min(
+        bestBid.quantity - bestBid.filledQuantity,
+        bestAsk.quantity - bestAsk.filledQuantity,
+      );
+
+      const trade = new Trade();
+      trade.assetPair = assetPair;
+      trade.price = bestAsk.price;
+      trade.quantity = tradeQuantity;
+      trade.takerOrderId = bestBid.id;
+      trade.makerOrderId = bestAsk.id;
+      trade.timestamp = new Date();
+      trades.push(trade);
+
+      bestBid.filledQuantity += tradeQuantity;
+      bestAsk.filledQuantity += tradeQuantity;
+
+      if (bestBid.filledQuantity === bestBid.quantity) {
+        bestBid.status = OrderStatus.FILLED;
+        bids.shift();
+      } else {
+        bestBid.status = OrderStatus.PARTIALLY_FILLED;
+      }
+
+      if (bestAsk.filledQuantity === bestAsk.quantity) {
+        bestAsk.status = OrderStatus.FILLED;
+        asks.shift();
+      } else {
+        bestAsk.status = OrderStatus.PARTIALLY_FILLED;
+      }
+    }
+    return trades;
+  }
+}

src/trading/services/order-book.service.spec.ts

@@ -0,0 +1,55 @@
+import { OrderBook } from './order-book.service';
+import { Order } from '../entities/order.entity';
+import { OrderSide, OrderType, OrderStatus } from '../enums/order.enum';
+
+describe('OrderBook', () => {
+  let orderBook: OrderBook;
+
+  beforeEach(() => {
+    orderBook = new OrderBook();
+  });
+
+  it('should sort buy orders with highest price first (bids)', () => {
+    const order1 = new Order();
+    order1.id = '1';
+    order1.side = OrderSide.BUY;
+    order1.price = 100;
+    order1.createdAt = new Date('2026-01-01T00:00:00Z');
+
+    const order2 = new Order();
+    order2.id = '2';
+    order2.side = OrderSide.BUY;
+    order2.price = 150;
+    order2.createdAt = new Date('2026-01-01T00:00:01Z');
+
+    orderBook.addOrder(order1);
+    orderBook.addOrder(order2);
+
+    const bids = orderBook.getBids();
+    expect(bids.length).toBe(2);
+    expect(bids[0].price).toBe(150);
+    expect(bids[1].price).toBe(100);
+  });
+
+  it('should sort sell orders with lowest price first (asks)', () => {
+    const order1 = new Order();
+    order1.id = '1';
+    order1.side = OrderSide.SELL;
+    order1.price = 200;
+    order1.createdAt = new Date('2026-01-01T00:00:00Z');
+
+    const order2 = new Order();
+    order2.id = '2';
+    order2.side = OrderSide.SELL;
+    order2.price = 180;
+    order2.createdAt = new Date('2026-01-01T00:00:01Z');
+
+    orderBook.addOrder(order1);
+    orderBook.addOrder(order2);
+
+    const asks = orderBook.getAsks();
+    expect(asks.length).toBe(2);
+    expect(asks[0].price).toBe(180);
+    expect(asks[1].price).toBe(200);
+  });
+});