Skip to content

development.mdx

Latest commit

 

History

History
88 lines (69 loc) · 3.33 KB

development.mdx

File metadata and controls

88 lines (69 loc) · 3.33 KB
Raw
title Order lifecycle
description How an order moves through markets-service, execution-service, execution-contracts, and risk-core

System overview

Numo's orderbook is split across four layers:

Public REST API for market discovery, orderbook reads, trades, order entry, and cancellation. Backend executor that validates crossed-order payloads and submits `verifyAndMatch(...)`. Onchain matching and action-verification contracts used by the trusted backend executor. Margin engine, subaccounts, cash asset accounting, manager hooks, settlement, and liquidation.

End-to-end flow

Clients call `GET /v1/markets` on `markets-service` to discover enabled instruments and retrieve the canonical `asset_address` and `sub_id`. Clients poll `GET /v1/book` and `GET /v1/trades` on `markets-service` for top-of-book state, recent prints, and 24h stats. Clients submit signed order payloads to `POST /v1/orders`. The service validates that order metadata matches the embedded action payload before persisting the order. The matcher loop in `markets-service` scans for crossed orders, computes fill amounts, and builds an executor payload for the market. `execution-service` validates the payload, ABI-encodes `TradeModule.OrderData`, simulates `Matching.verifyAndMatch(...)`, and broadcasts the transaction through `execution-contracts`. `risk-core` validates account state through manager and asset hooks, updates margin state, and handles cash settlement, funding, and liquidation behavior.

USDC/cNGN market

The USDC/cNGN market exposed by the backend is:

  • market: USDCcNGN-SPOT
  • contract_type: spot
  • settlement_type: spot
  • display_name: USDC/cNGN Spot

The settlement note in the matcher registry is:

Spot-style orderbook market on Base. Trades exchange WRAPPED_CNGN against internal USDC cash using the existing single quote-asset rail.

What each repo is responsible for

markets-service

  • stores active orders and trade fills
  • exposes GET /v1/markets, GET /v1/book, GET /v1/trades
  • accepts POST /v1/orders and POST /v1/orders/cancel
  • resolves market metadata from exact (asset_address, sub_id)

execution-service

  • accepts POST /execute
  • requires actions.length === signatures.length
  • requires actions[0].subaccount_id === order_data.taker_account
  • requires every action.module === module_address

execution-contracts

  • verifies signed actions
  • owns the trusted Matching execution path
  • executes matched transfers against the core account system

risk-core

  • stores balances in SubAccounts
  • lets managers validate final account state
  • lets assets track transfer semantics and settlement inputs
  • provides CashAsset and PerpAsset primitives used by managers during settlement