The saving claim

Zerochord claims a saving against the direct route on every swap. The claim is only worth something if somebody else can check it, so the baseline is defined narrowly and recorded on the quote.

The definition

The baseline is the best executable output for the same input size, at the same chain state, on a single venue using a single pool.

Every part of that sentence is load bearing.

Same input size. Not a normalised unit, not a smaller probe. The same number the user is about to swap.

Same chain state. The engine refuses a pool set read at more than one block hash, so the route and the baseline are computed against one block. Comparing a route at one block against a baseline at another would make the claim meaningless.

A single venue using a single pool. Not the best two pool combination, not the best route with one hop removed. The obvious trade.

What the quote records

interface Baseline {
  exists: boolean;
  venueId: string | null;
  poolOutRef: string | null;
  amountOut: bigint | null;
  /** Why there is no baseline, when there is not one. */
  reason: string | null;
}

Alongside it the quote carries:

• savingAbsolute: amountOut minus the baseline output. Zero when there is no baseline.
• savingBps: the same saving in basis points of the baseline.
• routingBeatsDirect: false when the baseline is at least as good as the route, and false when no baseline exists.

savingBps uses floor division rather than truncation toward zero. A route very slightly worse than the baseline would otherwise report a saving of exactly zero basis points while savingAbsolute was negative. Flooring makes a loss read as a loss.

When no saving is claimed

Two cases, and each names itself.

No single pool holds both assets. The baseline reason reads:

no single pool holds both assets, so there is no direct route to compare against

A direct pool exists but none can fill this size. The baseline reason reads:

a direct pool exists but none of them can fill this size

In both cases exists is false, savingAbsolute is zero, and the quote adds a warning in words as well. The words matter: an interface reading only the zero could report that the comparison ran and found no saving, which is a different claim.

The baseline ignores the caller's execution class filter

This is the subtle part, and it is deliberate.

A caller that asks for Kernel routes only, as cardano-swap swap --atomic does, is compared against the best direct pool, not against the best Kernel direct pool.

The reason: if the better direct pool is a Commitment one, restricting the baseline would inflate the saving by the caller's own restriction. A single pool order is executable at either class, so both belong in the comparison.

A pool whose fee can move after the quote is still excluded from both sides, because the product will not route through one at all.

When routing loses

routingBeatsDirect being false is a normal outcome, not a failure. On a pair with a deep direct pool it is the expected one.

The engine attaches this warning:

routing does not beat the direct pool for this pair and size; the direct pool is the better trade

The interface then names the baseline venue and offers to requote restricted to that one pool. The command line prints beats direct no.

Suppressing that outcome would make every published saving figure dishonest, which is the one failure the whole comparison exists to avoid.

Checking the claim afterwards

cardano-swap audit reconstructs every swap from public chain data alone and recomputes the comparison, including how many swaps did not beat the direct route. Where the baseline cannot be recovered from the transaction itself, it says so rather than substituting a present day pool state for a past one.

See Reproducing the saving claim.

Related