The Quote object

Quote is what QuoteEngine.quote() returns and what every builder takes. Everything an interface must display is a field here, because a number computed in the interface is a number nobody can audit afterwards.

Every amount is a bigint in base units. Nothing is converted to a JavaScript number: 2^53 is smaller than the base unit supply of several of these assets.

Identity and amounts

minimumOut is derived from amountOut by a slippage deduction with a ceiling, so the on-chain bound is never looser than the quote implies.

The rate

rateScaled / rateScale is output base units per input base unit, scaled so it stays exact and integral. RATE_SCALE is 10^18.

displayed = rateScaled / rateScale * 10^(decimalsIn - decimalsOut)

Both front ends use the same formula, so they cannot disagree.

Fees

interface QuoteFees {
  lpFeeIn: bigint;
  protocolFeeIn: bigint;
  venueExecutionLovelace: bigint;
  venueExecutionFeeIsWorstCase: boolean;
  depositLovelace: bigint;
}

venueExecutionFeeIsWorstCase is the one figure on a quote that can overstate the cost. A venue that scoops orders in a batch spreads its fee across the batch, so an order scooped alone pays all of it. Showing that number bare reads as a promise of precision the venue never made.

The aggregate rule: a sum containing one upper bound is itself only an upper bound, so the total is a worst case as soon as any single leg's is. The reduction never turns an uncertain leg into a certain total.

Price impact

priceImpactPips: bigint is the shortfall against the marginal price, in hundredths of a basis point. Ten to the sixth is one percent.

The reference is the route's own marginal price, read as a closed form off the exact reduction. See Routing.

The route

interface Route {
  branches: readonly RouteBranch[];
  amountIn: bigint;
  amountOut: bigint;
  atomicity: RouteAtomicity;
  executionClasses: readonly ExecutionClass[];
  venueIds: readonly string[];
}

Each branch is one path from the input asset to the output asset with its allocation:

interface RouteBranch {
  hops: readonly RouteHop[];
  amountIn: bigint;
  amountOut: bigint;
}

Each hop is one pool spend or order:

atomicity is "atomic", "single-order" or "needs-settlement". See Execution classes.

The baseline and the saving

interface Baseline {
  exists: boolean;
  venueId: string | null;
  poolOutRef: string | null;
  amountOut: bigint | null;
  reason: string | null;
}

See The saving claim.

Chain state and warnings

Warnings come from three places: the risk notes on every pool the route touches, the atomicity of the route, and the baseline outcome. They travel with the data rather than only with the screen, so a second consumer of the quote reaches the same conclusions.

Errors

NoRouteError extends QuoteError.

The request

interface QuoteRequest {
  assetIn: AssetRef;
  assetOut: AssetRef;
  amountIn: bigint;
  slippageBps?: number;
  allowNonAtomic?: boolean;
  executionClasses?: readonly ExecutionClass[];
}

slippageBps falls back to routing.defaultSlippageBps.

allowNonAtomic is off by default, so routes that would settle leg by leg are not enumerated.

executionClasses restricts routing to the given classes. It does not restrict the baseline.

Related