Execution classes

Cardano decentralised exchanges split into two kinds, and the difference decides what the product can promise before a user signs. Zerochord names the two kinds, carries the name through the quote, and lets the interface say different things about each.

The type lives in @cardano-swap/venues:

export type ExecutionClass = "kernel" | "commitment";

Each venue declares its class in its adapter, the configuration declares the same class for the same venue, and building the venue registry refuses to continue when the two disagree. A silent disagreement would be a wrong promise to a user, not a wrong log line.

Kernel

The user's own transaction spends the pool UTxOs directly.

• Hops chain atomically inside one transaction.
• The user signs once, and there is no third party between the quote and the fill.
• The whole route settles or the transaction does not make it onto the chain.

Dano Finance's concentrated liquidity pool is a Kernel venue. Its swap transaction reads the protocol config and the pool script as reference inputs, runs the pool script once as a zero withdrawal from its own reward account carrying the swap redeemer, and spends and repays each pool UTxO. One signature, one submission, no order UTxO and no batcher.

The withdraw-zero pattern is what makes several pools fit inside one execution unit budget: the script runs once for the whole transaction rather than once per pool.

Commitment

Execution is permissioned. The user signs one transaction that creates an order UTxO carrying a binding minimum, and a whitelisted batcher fills it afterwards.

• The rate is bound by the minimum in the order datum.
• The timing is guaranteed by nobody.
• Every Commitment route has a cancel path, so the user can take the funds back.

Minswap V2, Minswap Stableswap, SundaeSwap V3 and SundaeSwap Stableswaps are Commitment venues.

Minswap V2 has a SwapMultiRouting order step that chains up to three pools under one end to end minimum_receive. That single bound is why the multi-hop form is worth building: the intermediate legs cannot slip away from the user, because only the final amount is checked.

How a route's atomicity is decided

The engine reduces the per hop classes to one RouteAtomicity on the route:

export type RouteAtomicity = "atomic" | "single-order" | "needs-settlement";

Per branch:

Then across branches, a route is only as strong as its weakest one:

• Any branch that needs settlement makes the whole route needs-settlement.
• Several branches of mixed atomicity make the route needs-settlement.
• Several branches where any is single-order make the route needs-settlement.
• Otherwise the route is atomic when any branch is atomic, and single-order otherwise.

What the interface says about each

The wording lives in exactly one place, apps/web/src/lib/settlement.ts, keyed on the atomicity. No screen can call a Commitment route immediate, because no screen writes its own wording.

The engine also attaches a plain language warning to the quote for the two non-atomic forms, so the reason travels with the data and not only with the screen.

Choosing a class deliberately

A quote request can restrict routing to one or more classes:

engine.quote(pools, {
  assetIn,
  assetOut,
  amountIn,
  executionClasses: ["kernel"],
});

Passing ["kernel"] asks for a route the user's own transaction settles in full or not at all. On the command line that is cardano-swap swap --atomic. It is a product choice rather than a debugging switch: a slightly worse price with a clean guarantee is often the better trade.

The baseline is deliberately not restricted the same way. See The saving claim.

Related