Skip to main content

Quote Engine

The quote engine converts pay amounts into receive amounts through value flow.

The current TypeScript reference model is quote.ts. This page explains the model in implementation terms.

Reserve asset​

Each quoteable reserve asset has:

interface ReserveAsset {
  tokenAddress: string;
  stableness: number;
  fee: number;
  reserve: number;
  scale: number;
  targetScale: number;
}

Pay path​

quotePay processes pay legs in order. Each pay leg:

  1. computes reserve-relative size r = amount / reserve,
  2. computes target-relative size rt,
  3. chooses the linear branch or dynamic branch,
  4. computes value flow and scale change,
  5. updates token reserve, token scale, and total scale.

The pay result returns:

payQuotes
totalValueFlow
totalValueChange
postTotalScale

Receive path​

quoteReceive starts from the post-pay total scale. It allocates the pay value flow across receive assets.

For each receive allocation, the engine computes a negative receive value flow, solves for the reserve amount, applies fees, then updates reserve, scale, and total scale.

Receive allocation order matters for exact implementation output because each leg updates state.

Target-relative trade size​

The quote engine computes:

tokenWeight = scale / totalScale
targetWeight = targetScale / totalTargetScale
rt = ((targetWeight - tokenWeight) / (1 - targetWeight)) / tokenWeight

rt is the reserve-relative trade size that reaches target.

Branch selection​

The dynamic branch is used when the trade moves beyond the target-restoring direction:

(r > 0 && r > rt) || (r < 0 && r < rt)

The linear branch is used for target-restoring movement.

Dynamic branch​

For n = 0:

sigma = r / (1 + r)
kappa = 1

For n > 0:

kappa = abs((r - rt) / (1 + rt))^n
sigma = r / (1 + kappa * r)

Then:

valueFlow = scale * sigma
valueChange = (1 - kappa) * valueFlow

Linear branch​

The linear branch uses:

valueFlow = amount * scale / reserve
valueChange = valueFlow

This branch supports movement toward target.

Value-flow conservation​

The multiswap quote conserves unnormalized value flow across pay and receive legs.

sum pay valueFlow + sum receive valueFlow = 0

Receive fees are split after gross receive quotes.

Practical quote properties​

  • High stableness creates a broad low-impact region near target.
  • The smaller relevant receive scale often constrains pairwise depth.
  • Multi-receive allocation increases basket depth.
  • quote.ts uses a pay-then-receive path, so implementation numbers can be more conservative than a pure rt = 0 algebraic benchmark.