Skip to main content

Routing Model

Aqueducta routes from a fixed in-memory snapshot of Movement liquidity.

That matters because quote determinism does not come from guessing. It comes from holding the routing input stable.

Snapshot First​

Each live refresh produces a snapshot_id.

That snapshot contains:

  • discovered pools
  • pool snapshots and reserves
  • token metadata
  • Yuzu CLMM tick data

Quote requests are evaluated against the current hot snapshot, not against fresh live discovery on the request path.

Aqueducta generates route candidates from the pool graph and then runs quote math over those candidates.

Current behavior:

  • no split routing
  • no partial execution
  • ranked single-route alternatives only

Routing Modes​

fast​

Use this for:

  • wallet previews
  • route preview UIs
  • user-facing “get me the best route now” flows

Characteristics:

  • smaller search budget
  • tighter hop budget
  • prefers precomputed candidate sets when available

balanced​

Use this for:

  • alternative route displays
  • app-side quote comparison
  • normal ranked-route requests

Characteristics:

  • larger search budget than fast
  • returns broader alternatives

best_price​

Use this for:

  • slower power-user flows
  • integrations that explicitly want the widest search budget

Characteristics:

  • largest candidate search budget
  • can be slower than fast or balanced

Hot Pair Candidate Cache​

Aqueducta now keeps an in-memory route-candidate cache keyed by:

  • snapshot_id
  • token_in
  • token_out
  • routing_mode
  • hop policy

What is cached:

  • route skeletons only

What is not cached:

  • output amounts
  • slippage-adjusted values
  • execution payloads
  • diagnostics

That design keeps cache behavior deterministic while still removing repeated graph-search work for popular pairs.

Why Determinism Matters​

Deterministic ordering lets an integration:

  • compare responses safely
  • cache responses by snapshot_id
  • replay quote requests in tests
  • detect real regressions instead of random ordering noise

If a route changes, it should change for a real reason:

  • the snapshot changed
  • the request changed
  • the routing mode changed