Architecture

NeutronX is built on CometBFT and the Cosmos SDK. CometBFT handles consensus and block order; Cosmos SDK modules hold the trading logic. The key feature: the order book and the oracle are built into block production itself.

Stack

Block lifecycle

1. Prices. In the previous block every validator signs a vote extension with prices from its oracle sidecar.
2. Building. The proposer aggregates the prices (stake-weighted median) and matches orders from the mempool. It places the result as the first transaction of the block: prices, validator signatures, trades and evidence of wrong prices.
3. Verification. Every validator re-checks the first transaction: signatures, the median and the trades. Any mismatch rejects the block.
4. Start of execution. The new prices are applied, then the trades are settled: margin, fees, positions. Trades are therefore settled before the transactions that created them run.
5. User transactions. They run in order. An order picks up its already settled fills; the remainder rests on the book or is cancelled according to its time-in-force.
6. End of block. Protocol processes run in a fixed order, see below.

End of block

1. Orders of transactions that failed after matching are recorded: their fills stand.
2. Short-term and good-til-block orders and agent keys expire.
3. Funding prices are recorded: mark from the book, index from the oracle.
4. Liquidations.
5. Delisted markets are settled; markets with a frozen price are auto-paused, and pairs without votes get the circuit breaker.
6. Route deposits from IBC and vault quotes.
7. Chase orders are repriced, promo vouchers expire, old records are pruned.
8. Conditional orders, then TWAP and POV.
9. Funding for markets whose interval has come.
10. The in-memory book is rebuilt, orders without margin and post-only orders that would take liquidity are removed, invariants are checked. If an invariant breaks, trading stops.

The order matters. For example, liquidations run before conditional orders: if a liquidation and a stop-loss both trigger in the same block, the liquidation goes first.

The first transaction of a block

The proposer builds it, not a user. It carries the prices, the signed vote extensions, the evidence and the trades. It has no signatures and cannot be sent from outside: every validator checks its content.

The authority field holds the address of the governance module. This is a formal protobuf requirement, not a transaction from governance. Explorers should show it as a consensus batch confirmed by the validators.

Determinism

Every validator must reach a bit-for-bit identical state. Calculations therefore use fixed-point numbers only, data is iterated in sorted order, time comes only from the block header and never from the node's clock, and a block's prices are fixed by the votes of the previous block.