papers/lux-lightspeed-dex/sections/02-architecture.tex

\section{Architecture}
\label{sec:architecture}

The system is four orthogonal components, each with a single responsibility. This
section gives the responsibility of each, the data flow between them, and the
public/private build boundary that keeps the open network independent of the
proprietary engine.

\subsection{One home per concern}

\begin{table}[H]
\centering
\renewcommand{\arraystretch}{1.3}
\begin{tabular}{p{3.0cm} p{3.2cm} p{6.2cm}}
\toprule
\textbf{Component} & \textbf{Holds} & \textbf{Responsibility} \\
\midrule
\textbf{D-Chain}\newline (engine) &
Order books, DEX state, fills, execution root &
The matching engine \emph{is} a chain: own consensus, \texttt{zapdb} persistence,
execution-root commitment. The only place orders match or DEX state lives. \\
\textbf{Atomic proxy}\newline (\texttt{chains/dexvm}) &
Nothing (stateless) &
Relays orders to the D-Chain over ZAP; moves value in/out atomically via
shared-memory import/export. Pure transport plus atomicity. \\
\textbf{Client wrapper}\newline (\texttt{luxfi/dex}) &
Nothing authoritative &
Go client SDK and ZAP gateway. Submits orders as chain transactions; reads are
chain-state queries. No matching logic. \\
\textbf{EVM facade}\newline (precompile \texttt{0x9999}) &
Nothing (inert default) &
Uniswap-V4-\texttt{PoolManager}-style CLOB surface for Solidity. An adapter into the
unified D-Chain, inert unless a venue configures an endpoint. \\
\bottomrule
\end{tabular}
\caption{The decomplected DEX: one home per concern. Matching and state are
isolated to the D-Chain; every other component is stateless or inert by default.}
\label{tab:homes}
\end{table}

\subsection{The D-Chain: matching is a chain, not a contract}

The central design decision is that matching has its own consensus. There is no
in-memory matching authority and no DEX-as-smart-contract. The D-Chain is a full
chain: write frames (\texttt{clob\_place}, \texttt{clob\_cancel}, \texttt{clob\_submit})
enter a mempool, a proposer drains them in sequence order into a block,
\texttt{Block.Verify} runs the matcher against a versioned overlay, and
\texttt{Block.Accept} commits the overlay to \texttt{zapdb}. The persisted state is
authoritative across restart; the in-memory book is a rebuildable accelerator folded
from the persisted log.

State is keyed in the \texttt{zapdb} namespace by order and trade rows, with a
materialized book snapshot for price-time priority. The state root reuses the audited
XVM execution-root construction: an RFC-6962 Merkle fold over the parent root, book
root, trade log root, and height. Because the order rows and trade log fully
reconstruct the book, a node recovers exact state by replaying the persisted log---no
external dependency, no in-memory authority to lose.

\subsection{The atomic proxy: transport, not matching}

The proxy on the public Lux network does what cross-chain asset movement already does
between the X- and C-Chains: it moves value atomically and relays calls. It deliberately
holds no order book and no DEX state---the matching code that once lived here has been
removed, leaving only an import/export path and a ZAP relay. Value enters and leaves the
DEX through atomic shared-memory operations applied at block acceptance, so a transfer
either completes on both sides or neither. The proxy is the cross-chain settlement rail;
it is not the latency-critical matching path.

\subsection{Order flow}

\begin{algorithm}[H]
\caption{Order lifecycle across the four components}
\begin{algorithmic}[1]
\STATE \textbf{Submit.} A trader (or a Solidity contract via \texttt{0x9999}) sends an
order through the \texttt{luxfi/dex} wrapper to the atomic proxy.
\STATE \textbf{Relay.} The proxy frames the order in the frozen ZAP wire format and
relays it to the D-Chain. Inbound value is recorded for atomic import.
\STATE \textbf{Build.} The D-Chain proposer drains pending orders in sequence order and
relays once at block build, obtaining fills from the matcher.
\STATE \textbf{Verify.} Every validator re-runs the matcher in \texttt{Block.Verify}
against a versioned overlay and checks the proposer's carried fills and state root.
\STATE \textbf{Accept.} The overlay commits to \texttt{zapdb}; the proxy applies the
atomic import/export at acceptance, settling value all-or-nothing.
\STATE \textbf{Read.} Fills and book state are read back as chain-state queries through
the wrapper.
\end{algorithmic}
\end{algorithm}

The latency-critical leg (submit$\to$match) is co-located inside the D-Chain venue; the
proxy's relay carries cross-chain settlement, which runs at block cadence rather than per
order. Section~\ref{sec:gpu-matching} quantifies the matching leg; Section~\ref{sec:settlement}
quantifies settlement.

\subsection{Public/private build boundary}

\begin{figure}[H]
\centering
\begin{verbatim}
  PUBLIC OSS luxd                         PRIVATE venue build
  (pure Go, no private deps)              (links C++/GPU engine)
  +---------------------------+           +---------------------------+
  | P-Chain   C-Chain  X-Chain|           |  D-Chain (matching engine)|
  | other sovereign L1s       |           |  zapdb + execution root   |
  | precompile 0x9999 = INERT |  ZAP/sm   |  luxcpp + gpu-kernels      |
  +-------------+-------------+ <-------> +-------------+-------------+
                |  atomic proxy (chains/dexvm, build-tag gated)     |
                +---------------------------------------------------+
\end{verbatim}
\caption{The public/private seam. \texttt{luxd} validates P/C/X and other L1s and
excludes the D-Chain (build-tag gated, zero private dependencies). The precompile ships
in the public EVM but is inert unless a venue sets a D-Chain endpoint. Only the private
venue build links the C++/GPU matching engine.}
\label{fig:build-boundary}
\end{figure}

The D-Chain is excluded from the public node by a build tag: the public build links a
no-op, and only a build with the \texttt{dchain} tag links the proxy and the venue VM.
The precompile is present in the public EVM but defaults to an inert backend that refuses
until a venue configures an endpoint. Consequently the open-source node never imports the
proprietary engine, and the proprietary engine is reachable only by an explicitly
configured venue. The D-Chain is a single-operator venue today---still a full consensus
chain with on-chain persisted state, not an in-memory authority, but operated by one
party rather than decentralized to many external validators.