epic: indexer best execution for default swap; manual hybrid only in advanced trading UX #108

New issue

Closed

opened 2026-04-22 03:24:30 +00:00 by PlasticDigits · 12 comments

PlasticDigits commented

2026-04-22 03:24:30 +00:00

(Migrated from gitlab.com)

Summary

Product gate: the indexer (and/or solver service) must provide automated best execution for end users on the default / simple swap experience: optimal or near-optimal split between AMM pool legs and on-chain limit book legs (per hop, up to the 3-hop policy) with clear disclosure of assumptions and risks.

Manual control of hybrid parameters (pool_input / book_input / max_maker_fills / book_start_hint) is relegated to the advanced trading UI only — not the primary swap flow.

Rationale

Today, retail users must opt in to hybrid and manually specify book leg size on direct routes (SwapPage); multihop is pool-only in the UI. That is a pro workflow, not default retail.
ARCHITECTURE_GAP_MATRIX already flags “Best execution logic — not implemented server-side”; this issue closes that gap in the product sense: off-chain policy + on-chain verification via existing router simulate / pair queries.

Requirements (high level)

Server (indexer or dedicated service)

Deterministic, versioned API for “quote + recommended operations” including hybrid_by_hop suggestions and slippage-safe bounds. Must define behavior when LCD or book query fails: fallback to pool-only with explicit degraded flag to the client.
Caching, rate limits, and anti-amplification for LCD (pair orderbook is N queries for depth).
Versioning (Accept header or /v2/) if breaking; coordinate with dApp.
Observability: metrics for simulation failures, book depth, and latency.

Frontend

Simple swap: one primary action “Swap” with no manual book split; show “Advanced” link to the pro trading view for manual hybrid, pro order entry, and deeper book.
Trust UX: show “Quote source: indexer vX” vs chain vs fallback; link to docs on execution risk (L8, etc.).

Non-goals (in this issue)

MEV protection or private RPC — track separately.
CEX-only order types (margin, futures) — out of scope.

Acceptance criteria

GET (or versioned) public best-exec response documented in OpenAPI and typescript types in frontend-dapp.
Default swap page uses the API; no bookInputHuman required for happy path.
Advanced page retains or expands manual HybridSwapParams editing; E2E differentiates the two.
Stakeholder ADR (short) under docs/adr/ for solver ownership and liability boundaries.

References

indexer/src/api/route_solver.rs — SolveRoutePostBody / hybrid_by_hop
frontend-dapp/src/pages/SwapPage.tsx — current manual hybrid
docs/reviews/20260409T030009Z/ISSUE_BACKLOG.md — DEX-P0-EPIC best execution

Labels suggested

epic, indexer, frontend, hybrid, product, launch-blocker, architecture

Relationship

Blocks closing the “real gaps” gate issue until the simple vs advanced UX split and indexer API are shipped.
Depends on the hybrid multihop + GET route issue for technical alignment (may merge or split if PM prefers one epic).

## Summary **Product gate:** the **indexer (and/or solver service)** must provide **automated best execution** for **end users** on the **default / simple** swap experience: optimal or near-optimal **split between AMM pool legs and on-chain limit book legs** (per hop, up to the **3-hop** policy) with clear disclosure of **assumptions and risks**. **Manual control** of hybrid parameters (`pool_input` / `book_input` / `max_maker_fills` / `book_start_hint`) is **relegated to the advanced trading UI** only — not the primary swap flow. ## Rationale - Today, **retail** users must **opt in** to hybrid and **manually** specify book leg size on **direct** routes (`SwapPage`); **multihop** is **pool-only** in the UI. That is a **pro** workflow, not **default retail**. - `ARCHITECTURE_GAP_MATRIX` already flags **“Best execution logic — not implemented server-side”**; this issue **closes that gap** in the product sense: **off-chain** policy + **on-chain** verification via existing **router simulate** / pair queries. ## Requirements (high level) ### Server (indexer or dedicated service) - **Deterministic, versioned** API for **“quote + recommended operations”** including **`hybrid_by_hop` suggestions** and **slippage-safe** bounds. Must define behavior when **LCD** or **book query** fails: fallback to **pool-only** with explicit **degraded** flag to the client. - **Caching, rate limits**, and **anti-amplification** for LCD (pair orderbook is **N** queries for depth). - **Versioning** (`Accept` header or `/v2/`) if breaking; coordinate with dApp. - **Observability**: metrics for simulation failures, book depth, and latency. ### Frontend - **Simple swap**: one primary action “Swap” with **no** manual book split; show **“Advanced”** link to the **pro** trading view for **manual** hybrid, **pro** order entry, and **deeper** book. - **Trust UX**: show **“Quote source: indexer vX”** vs **chain** vs **fallback**; link to **docs** on execution risk (L8, etc.). ## Non-goals (in this issue) - **MEV** protection or private RPC — track separately. - **CEX-only** order types (margin, futures) — out of scope. ## Acceptance criteria - [ ] `GET` (or versioned) **public** best-exec response documented in OpenAPI and **typescript** types in `frontend-dapp`. - [ ] **Default** swap page uses the API; **no** `bookInputHuman` required for happy path. - [ ] **Advanced** page retains or expands **manual** `HybridSwapParams` editing; **E2E** differentiates the two. - [ ] Stakeholder **ADR** (short) under `docs/adr/` for **solver ownership** and **liability** boundaries. ## References - `indexer/src/api/route_solver.rs` — `SolveRoutePostBody` / `hybrid_by_hop` - `frontend-dapp/src/pages/SwapPage.tsx` — current manual hybrid - `docs/reviews/20260409T030009Z/ISSUE_BACKLOG.md` — DEX-P0-EPIC best execution ## Labels suggested `epic`, `indexer`, `frontend`, `hybrid`, `product`, `launch-blocker`, `architecture` ## Relationship - **Blocks** closing the **“real gaps” gate** issue until the **simple** vs **advanced** UX split and **indexer** API are shipped. - **Depends on** the **hybrid multihop + GET route** issue for technical alignment (may merge or split if PM prefers one epic).

PlasticDigits commented

2026-04-22 03:24:51 +00:00

(Migrated from gitlab.com)

mentioned in issue #107