How Kadia DEX works

Draft

Kadia DEX is in development, not audited and not on mainnet. A test version runs on Ergo testnet (the testnet record). The market contracts are frozen at revision r12 for testing, but details can still change before mainnet.

Source: kadia-dex docs/guide/how-it-works.md at commit 4b2bbee (4b2bbeeff4c2df397d4090a1214542923338941c). The DEX design specification, docs/specs/2026-09-23-dex-design.md, is the authority; section numbers below point into it.

The pieces

Piece	What it is
Market box	One box per trading pair. It holds the pool’s reserves (ERG and a token, or two tokens), the market’s fixed parameters and its per-block state. Each market has exactly one, identified by an NFT.
Order box	A box you create to trade. It holds what you’re selling, your minimum acceptable payout, an expiry height and where to send the proceeds. There are swap orders and orders that add or remove liquidity (the contract’s LP-deposit and LP-redeem orders).
Settlement transaction	A transaction that spends the market box and a batch of orders together, pays every order and creates the market’s next state. Anyone can build one.
Settler	Software that builds settlements. Anyone can run one; Kadia runs a reference settler with no special rights.
Keeper	Software that refunds expired orders and keeps idle markets fresh. Also open to anyone.
Governance box	One box per network, named in every r12 market. Its key holders can pause swaps and new liquidity, wind a market down, or upgrade it after notice. They can never stop removing liquidity, cancelling or refunding. See Assumptions and risks.
Registry / indexer	Off-chain software that checks every market’s history from genesis and serves market lists, quotes and order status. Anyone can re-run it.

A swap, step by step

1. You create an order. Your wallet sends your tokens (or ERG) into a swap order box. It records the pair, your minimum payout (minOut), the highest fee you’ll accept, an expiry height and an ERG execution-fee cap. Nothing has traded yet, and you can cancel at any time with your own key.
2. A settler picks it up. Each block, settlers look at open orders and the pool, and build a settlement that includes some of them.
3. One price for the whole batch. The settlement sets the pool’s new reserves, and those define the batch’s reference price P′. Every order in the batch is entitled to at least P′ minus the order fee f, and at least its own minOut (§5.2).
4. Each order checks its own payout. Your order’s contract looks at the output in its own position in the transaction. That output must carry your order’s id, go to your payout address and contain at least what you’re owed. Otherwise the whole transaction is invalid (§6.2).
5. The pool checks it was paid fairly. The market contract checks that the pool’s net trade in this block paid at least the fair price plus the pool fee φ, and that the price stayed within the market’s band δ around the block’s opening price (§5.1, §5.4).
6. If nobody fills your order by its expiry, anyone can refund it. The whole balance goes back to your payout address, minus at most your execution-fee cap. The refund doesn’t depend on the market existing.

Orders fill whole or not at all. There are no partial fills in v1.

Why batches

• Everyone in a batch gets the same price. Reordering orders inside a batch doesn’t change anyone’s entitlement, so front-running and sandwiching within a transaction don’t work. A settler can still chain several settlements in one block and back-run your price impact (N3). Your minOut is what limits that.
• Orders can match each other. Opposite orders in a batch can fill against each other, and only the net flow touches the pool.
• The pool is priced per block, not per transaction. Splitting a trade across several transactions in one block gains nothing against liquidity providers (§5.1).

Liquidity providers

• Adding liquidity adds both assets in the pool’s current ratio and mints LP tokens to you. Removing liquidity (a redeem order in the contract) returns LP tokens for your share of both reserves. Both are proportional, with rounding in the pool’s favour (§5.6).
• LP actions run first in each block, before any swap (§5.4). After a block’s first swap, LP orders wait for the next block.
• An exit always exists. A finite number of removal steps returns your share without needing anyone to trade (S7). Inclusion isn’t guaranteed: someone paying for a swap every block can delay LP actions (N9).
• What LPs earn comes from the pool fee φ, and from the rule that makes traders pay the post-trade price rather than the average price. That reduces what LPs lose to arbitrage within a block compared with a standard constant-product pool. LPs still carry the full between-block arbitrage risk (N3).

Per-block state

Each market box records the block’s opening price, its reference state, the current height, and whether a swap has happened yet this block.

• A new block: the state resets from the current reserves.
• Within a block: every state must stay within ±δ of the opening price.
• Across blocks: the price can move by up to the band each block, and that compounds (S6).

What runs off-chain, and why that’s safe

Settlers, keepers, the registry and the apps have no on-chain privileges. They only build transactions that the contracts accept or reject. If Kadia’s own services stop:

• your open orders can still be cancelled with your key, or refunded by anyone after expiry;
• liquidity providers can still exit;
• anyone can run a settler and keep trading.

See Know your assumptions for what is and isn’t guaranteed, and Fees for who pays what.