Skip to content

development.mdx

Latest commit

 

History

History
88 lines (69 loc) · 3.4 KB

development.mdx

File metadata and controls

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

System overview

Numo's futures 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.

Deliverable cNGN future

The physically delivered FX future exposed by the backend is:

  • market: USDCcNGN-APR30-2026
  • contract_type: deliverable_fx_future
  • settlement_type: physical_delivery
  • display_name: USDC/cNGN APR-30-2026 Future

The settlement note in the matcher registry is:

Physically delivered on Base. Long pays cNGN and receives fixed USDC notional; short pays fixed USDC notional and receives cNGN.

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