feat(indexer): unified global best-execution route solver (multi-path + joint hybrid optimization) #209

New issue

Closed

opened 2026-05-29 03:09:56 +00:00 by PlasticDigits · 18 comments

PlasticDigits commented 2026-05-29 03:09:56 +00:00 (Migrated from gitlab.com)

Copy link

Summary

Replace the indexer’s fragmented route solver (BFS hop-count path + sequential per-hop hybrid grid + optional client hybrid_by_hop on POST) with a unified “best execution” API that returns a globally optimal (within documented bounds) multihop route: path selection, per-hop pool/book splits, and router operations chosen to maximize estimated_amount_out under on-chain simulation constraints.

Follow-up to closed epics #101 / #108 and gap analysis gaps/GAP_1780023683.md (route solver row).

---

Current codebase

Endpoints (indexer/src/api/mod.rs)

Method	Path	Behavior today
GET	/api/v1/route/solve	Without amount_in: route discovery only — BFS over indexed pairs, router_operations with hybrid: null. With amount_in (default): hybrid path — BFS (max 3 hops), then hybrid_route_opt::optimize_multihop_hybrid, LCD simulate_swap_operations when ROUTER_ADDRESS set.
GET	/api/v1/route/solve/best	Alias for hybrid GET; amount_in required (#189).
POST	/api/v1/route/solve	BFS discovery (max 4 hops); optional hybrid_by_hop merged per hop; LCD sim when configured. Client must supply splits for non-default hybrid.

Path discovery (route_solver.rs)

• find_path: unweighted BFS on the pair graph; returns the first shortest path by hop count (not best output).
• No enumeration of alternate paths (e.g. A→C→B vs A→B when both exist).
• Tokens must exist in assets.contract_address (CW20); native-only assets are not routable.

Hybrid optimization (hybrid_route_opt.rs)

• optimize_multihop_hybrid: sequential per-hop grid search (GRID_POINTS = 17) over book_input; output of hop i feeds hop i+1.
• Not globally optimal: early hops can consume book liquidity that would yield more total out if a later hop or alternate path were chosen; no joint optimization across hops.
• On LCD failure for all grid points on a hop: degraded pool-only for that hop (quote_kind: indexer_hybrid_lcd_degraded).
• Response already discloses: hybrid_notes — "Sequential per-hop hybrid optimizer (not globally optimal across hops)…".

Caching & limits

• In-memory cache: 12s TTL, 512 entries, amount bucket 1_000_000 for hybrid GET keys.
• Router on-chain MAX_HOPS = 4; indexer GET hybrid caps at 3 hops (#191).

Consumers

• dApp: frontend-dapp/src/services/indexer/client.ts (getRouteSolve, postRouteSolve); SwapPage.tsx uses indexer routes and can POST hybrid_by_hop aligned to UI splits.
• Docs: docs/integrators.md, docs/indexer-invariants.md, ADR docs/adr/0001-hybrid-quoting-and-routing.md.
• Skill: skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md.

Tests today

• indexer/tests/api_route_solve.rs: discovery, POST merge, hybrid length mismatch, GET hybrid 2/3-hop with LCD mock — no multi-path or global optimality assertions.

---

Why this is needed

1. Product trust: Retail and integrators expect “best execution” to mean the best total output for amount_in, not “shortest BFS path + greedy per-hop splits.” Today a longer path or different split schedule can beat the indexer answer; hybrid_notes admits this but does not fix it.
2. API fragmentation: Three surfaces (discovery GET, hybrid GET//best, POST + hybrid_by_hop) force clients to understand implementation details instead of one “solve best route” contract.
3. Gap closure: gaps/GAP_1780023683.md and ARCHITECTURE_GAP_MATRIX.md list “Best execution logic — sequential per-hop, not global.”
4. Execution risk (L8): Without global path + split search, displayed estimated_amount_out can be materially worse than achievable on the same chain snapshot, increasing slippage surprises at submit time.

---

Constraints and guardrails

Area	Guardrail
On-chain truth	Final recommendation must be validated with simulate_swap_operations on ROUTER_ADDRESS (same as today). Pair-level candidates use HybridSimulation only (ADR 0001 / #190).
Hop limits	Respect router MAX_HOPS (4). Document policy for retail GET (3 vs 4) after global solver ships; do not exceed chain limits.
LCD budget	Global search multiplies queries; require timeouts, max candidate paths, max split evaluations, and reuse existing cache / bucketing. Fail closed to degraded + explicit quote_kind / hybrid_notes (never silent best-guess).
Rate limits	Stay compatible with indexer/tests/security.rs and production rate limits; avoid unbounded fan-out per request.
Determinism	Same inputs + same LCD snapshot → same route (tie-break rules documented). Version solver in response metadata if needed.
Security	No new trusted execution; solver is advisory. Clients still set max_spread / min receive on execute.
Backward compatibility	Deprecation plan for hybrid_by_hop-first POST workflows: keep POST for explicit overrides; default “best” should be GET (or single POST flag mode=best).
Asset model	CW20 contract_address only for graph nodes; unchanged unless separate native-routing issue lands.
Disclosure	Update hybrid_notes to describe solver version, search bounds, and optimality claim (e.g. “optimal within top-K paths and split grid” vs “globally optimal”).

---

Relevant files

File	Role
indexer/src/api/route_solver.rs	HTTP handlers, BFS, cache, hybrid GET orchestration
indexer/src/api/hybrid_route_opt.rs	Per-hop grid search (replace or compose into global solver)
indexer/src/api/mod.rs	Route registration, OpenAPI
indexer/src/lcd/	LCD client, query errors
indexer/src/config.rs	ROUTER_ADDRESS
indexer/tests/api_route_solve.rs	Integration tests
smartcontracts/contracts/router/src/contract.rs	MAX_HOPS, simulate/execute
frontend-dapp/src/services/indexer/client.ts	Client types and calls
frontend-dapp/src/pages/SwapPage.tsx	Primary consumer
docs/indexer-invariants.md, docs/integrators.md	Public contract
docs/adr/0001-hybrid-quoting-and-routing.md	Quoting ADR (extend or add ADR 0002)

---

Recommended direction

1. Multi-path candidate generation

   • Enumerate top-K simple paths by hop count (K configurable, default small e.g. 3–5) instead of first BFS path only.
   • Prune with cheap pool-only simulate_swap_operations or per-path pool-only upper bound before expensive hybrid search.

2. Global hybrid search (per candidate path)

   • Replace pure sequential greedy with one of:
     • Joint grid / coordinate descent on split fractions across hops with shared amount_in constraint, or
     • Dynamic programming when split discretization is fixed (book fraction buckets).
   • Always finish with full-router simulate_swap_operations on the winning ops.

3. Unified API

   • Single “best execution” mode: GET /api/v1/route/solve?amount_in=… (and /best alias) returns globally chosen path + hybrid_by_hop + router_operations.
   • POST retains hybrid_by_hop for integrator override only; optional mode=discovery vs mode=best.
   • Response fields: solver_version, paths_considered, optimality_scope, updated hybrid_notes.

4. Performance

   • Extend cache key to include solver version + K; parallelize LCD queries with concurrency cap.
   • Metrics hook (even if #200 open): log path count, LCD calls, latency, degraded rate.

5. ADR

   • Short ADR: optimality definition, liability boundary, degradation semantics.

---

Acceptance criteria

• For seeded graphs with ≥2 distinct paths of equal or different hop count, solver returns the path + splits with highest estimated_amount_out vs old BFS+sequential baseline (integration test with deterministic LCD mock).
• No regression on existing invariants: unknown token → 400, no path → 404, hybrid length mismatch → 400, zero amount_in on hybrid best → 400.
• hybrid_notes / quote_kind accurately reflect degraded and non-degraded outcomes.
• OpenAPI + IndexerRouteSolveResponse updated; integrator docs and indexer-invariants.md updated.
• pool_only=true escape hatch still works (pool-only ops, 4-hop cap) without invoking global hybrid search.
• Documented LCD call upper bound per request; bounded search does not exceed it in tests.
• Optional: SwapPage uses unified best GET without manual hybrid_by_hop on happy path (can be follow-up issue if scoped).

---

Test plan — functional paths

#	Scenario	Expected
1	Direct pair, book improves out	Non-zero book_input on winning hop; indexer_hybrid_lcd
2	Two paths: short pool-only vs longer with better book	Chooses better out, not fewer hops
3	3-hop global: split on hop 1 affects hop 3 book depth	Joint optimization beats sequential baseline (mocked returns)
4	No amount_in	Discovery only; hybrid: null; no solver run
5	pool_only=true + amount_in	4-hop cap; all hybrid: null; pool LCD kind
6	GET /solve/best without amount_in	400
7	POST with valid hybrid_by_hop	Merges overrides; sim matches provided splits
8	POST hybrid_by_hop length ≠ hops	400
9	LCD failure mid-search	502 or degraded path per policy; never 200 with fabricated out
10	Router sim failure after merge	400 generic message (no LCD stack leak)
11	Cache hit within TTL	Same body; no excess LCD (mock call count)
12	max_maker_fills boundary (1, large)	Respects param; deterministic

Run: cd indexer && cargo test api_route_solve -- --test-threads=1

---

Test plan — attack vectors / abuse

#	Vector	Mitigation test
A1	LCD amplification — huge amount_in + many pairs → path explosion	Assert max paths evaluated; request completes or 429/503 per rate limit; no O(pairs!)
A2	Cache poisoning — keyed only by token pair without amount	Amount bucket + solver version in key; different amounts don’t cross-leak
A3	Invalid amount_in — negative, non-integer, overflow string	400; no panic
A4	Token address case / whitespace	Trim + lowercase in cache; consistent 400 for unknown
A5	Hybrid override POST — pool_input+book_input ≠ hop offer	Router sim 400; no indexer crash
A6	Extreme max_maker_fills	Capped or rejected; no unbounded book walk in LCD mock
A7	Concurrent identical requests	Cache reduces duplicate LCD; no deadlock on Mutex cache
A8	Misleading “optimal” label	Response optimality_scope matches actual search bounds (contract test on JSON schema)

Also run: cargo test --test security (rate limits) after changing route handler cost.

---

Verification criteria

1. Correctness: New integration tests in api_route_solve.rs prove multi-path win over legacy BFS+sequential (feature flag or baseline comparison function in test only).
2. Regression: Full indexer test suite with cargo test --tests -j 1 -- --test-threads=1.
3. Contracts: Existing router hybrid multihop tests still pass (smartcontracts/tests).
4. Docs: docs/indexer-invariants.md, docs/integrators.md, and ADR updated; gap matrix row for “Best execution logic” → Done or Partial with explicit optimality scope.
5. Manual QA (local QA stack): swap token pair known to have two routes; confirm UI/indexer out ≥ previous baseline on same block height.
6. Observability: Logs include paths_considered, lcd_queries, solver_version, degraded on each best-exec request (structured fields).

---

Out of scope (track separately)

• MEV / private mempool
• Native-asset routing without CW20 contract address
• On-chain route oracle or signed intents
• Prometheus metrics (#200) — optional follow-up

Related issues

• Closed: #101, #108, #189, #191
• Architecture: #56
• Multihop hybrid tests: #192

## Summary Replace the indexer’s **fragmented** route solver (BFS hop-count path + sequential per-hop hybrid grid + optional client `hybrid_by_hop` on POST) with a **unified “best execution”** API that returns a **globally optimal** (within documented bounds) multihop route: **path selection**, **per-hop pool/book splits**, and **router operations** chosen to maximize `estimated_amount_out` under on-chain simulation constraints. Follow-up to closed epics [**#101**](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/101) / [**#108**](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/108) and gap analysis [`gaps/GAP_1780023683.md`](gaps/GAP_1780023683.md) (route solver row). --- ## Current codebase ### Endpoints (`indexer/src/api/mod.rs`) | Method | Path | Behavior today | |--------|------|----------------| | `GET` | `/api/v1/route/solve` | Without `amount_in`: **route discovery only** — BFS over indexed pairs, `router_operations` with `hybrid: null`. With `amount_in` (default): **hybrid path** — BFS (**max 3 hops**), then `hybrid_route_opt::optimize_multihop_hybrid`, LCD `simulate_swap_operations` when `ROUTER_ADDRESS` set. | | `GET` | `/api/v1/route/solve/best` | Alias for hybrid GET; **`amount_in` required** ([#189](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/189)). | | `POST` | `/api/v1/route/solve` | BFS discovery (**max 4 hops**); optional **`hybrid_by_hop`** merged per hop; LCD sim when configured. Client must supply splits for non-default hybrid. | ### Path discovery (`route_solver.rs`) - **`find_path`**: unweighted BFS on the pair graph; returns the **first** shortest path by hop count (not best output). - **No enumeration** of alternate paths (e.g. A→C→B vs A→B when both exist). - Tokens must exist in `assets.contract_address` (CW20); native-only assets are **not routable**. ### Hybrid optimization (`hybrid_route_opt.rs`) - **`optimize_multihop_hybrid`**: **sequential** per-hop grid search (`GRID_POINTS = 17`) over `book_input`; output of hop *i* feeds hop *i+1*. - **Not globally optimal**: early hops can consume book liquidity that would yield more total out if a later hop or alternate path were chosen; no joint optimization across hops. - On LCD failure for all grid points on a hop: **degraded** pool-only for that hop (`quote_kind: indexer_hybrid_lcd_degraded`). - Response already discloses: `hybrid_notes` — *"Sequential per-hop hybrid optimizer (not globally optimal across hops)…"*. ### Caching & limits - In-memory cache: **12s TTL**, **512** entries, amount **bucket** `1_000_000` for hybrid GET keys. - Router on-chain **`MAX_HOPS = 4`**; indexer GET hybrid caps at **3 hops** ([#191](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/191)). ### Consumers - **dApp**: `frontend-dapp/src/services/indexer/client.ts` (`getRouteSolve`, `postRouteSolve`); `SwapPage.tsx` uses indexer routes and can POST `hybrid_by_hop` aligned to UI splits. - **Docs**: [`docs/integrators.md`](docs/integrators.md), [`docs/indexer-invariants.md`](docs/indexer-invariants.md), ADR [`docs/adr/0001-hybrid-quoting-and-routing.md`](docs/adr/0001-hybrid-quoting-and-routing.md). - **Skill**: [`skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md`](skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md). ### Tests today - [`indexer/tests/api_route_solve.rs`](indexer/tests/api_route_solve.rs): discovery, POST merge, hybrid length mismatch, GET hybrid 2/3-hop with LCD mock — **no** multi-path or global optimality assertions. --- ## Why this is needed 1. **Product trust**: Retail and integrators expect **“best execution”** to mean the best **total** output for `amount_in`, not “shortest BFS path + greedy per-hop splits.” Today a longer path or different split schedule can beat the indexer answer; `hybrid_notes` admits this but does not fix it. 2. **API fragmentation**: Three surfaces (discovery GET, hybrid GET/`/best`, POST + `hybrid_by_hop`) force clients to understand implementation details instead of one **“solve best route”** contract. 3. **Gap closure**: [`gaps/GAP_1780023683.md`](gaps/GAP_1780023683.md) and [`ARCHITECTURE_GAP_MATRIX.md`](docs/reviews/20260409T030009Z/ARCHITECTURE_GAP_MATRIX.md) list **“Best execution logic — sequential per-hop, not global.”** 4. **Execution risk (L8)**: Without global path + split search, displayed `estimated_amount_out` can be materially worse than achievable on the same chain snapshot, increasing slippage surprises at submit time. --- ## Constraints and guardrails | Area | Guardrail | |------|-----------| | **On-chain truth** | Final recommendation must be validated with **`simulate_swap_operations`** on `ROUTER_ADDRESS` (same as today). Pair-level candidates use **`HybridSimulation`** only (ADR 0001 / #190). | | **Hop limits** | Respect router `MAX_HOPS` (4). Document policy for retail GET (3 vs 4) after global solver ships; do not exceed chain limits. | | **LCD budget** | Global search multiplies queries; require **timeouts**, **max candidate paths**, **max split evaluations**, and reuse existing **cache** / bucketing. Fail closed to **degraded** + explicit `quote_kind` / `hybrid_notes` (never silent best-guess). | | **Rate limits** | Stay compatible with [`indexer/tests/security.rs`](indexer/tests/security.rs) and production rate limits; avoid unbounded fan-out per request. | | **Determinism** | Same inputs + same LCD snapshot → same route (tie-break rules documented). Version solver in response metadata if needed. | | **Security** | No new trusted execution; solver is **advisory**. Clients still set `max_spread` / min receive on execute. | | **Backward compatibility** | Deprecation plan for `hybrid_by_hop`-first POST workflows: keep POST for **explicit** overrides; default “best” should be GET (or single POST flag `mode=best`). | | **Asset model** | CW20 `contract_address` only for graph nodes; unchanged unless separate native-routing issue lands. | | **Disclosure** | Update `hybrid_notes` to describe **solver version**, **search bounds**, and **optimality claim** (e.g. “optimal within top-K paths and split grid” vs “globally optimal”). | --- ## Relevant files | File | Role | |------|------| | [`indexer/src/api/route_solver.rs`](indexer/src/api/route_solver.rs) | HTTP handlers, BFS, cache, hybrid GET orchestration | | [`indexer/src/api/hybrid_route_opt.rs`](indexer/src/api/hybrid_route_opt.rs) | Per-hop grid search (replace or compose into global solver) | | [`indexer/src/api/mod.rs`](indexer/src/api/mod.rs) | Route registration, OpenAPI | | [`indexer/src/lcd/`](indexer/src/lcd/) | LCD client, query errors | | [`indexer/src/config.rs`](indexer/src/config.rs) | `ROUTER_ADDRESS` | | [`indexer/tests/api_route_solve.rs`](indexer/tests/api_route_solve.rs) | Integration tests | | [`smartcontracts/contracts/router/src/contract.rs`](smartcontracts/contracts/router/src/contract.rs) | `MAX_HOPS`, simulate/execute | | [`frontend-dapp/src/services/indexer/client.ts`](frontend-dapp/src/services/indexer/client.ts) | Client types and calls | | [`frontend-dapp/src/pages/SwapPage.tsx`](frontend-dapp/src/pages/SwapPage.tsx) | Primary consumer | | [`docs/indexer-invariants.md`](docs/indexer-invariants.md), [`docs/integrators.md`](docs/integrators.md) | Public contract | | [`docs/adr/0001-hybrid-quoting-and-routing.md`](docs/adr/0001-hybrid-quoting-and-routing.md) | Quoting ADR (extend or add ADR 0002) | --- ## Recommended direction 1. **Multi-path candidate generation** - Enumerate **top-K** simple paths by hop count (K configurable, default small e.g. 3–5) instead of first BFS path only. - Prune with cheap pool-only `simulate_swap_operations` or per-path pool-only upper bound before expensive hybrid search. 2. **Global hybrid search (per candidate path)** - Replace pure sequential greedy with one of: - **Joint grid / coordinate descent** on split fractions across hops with shared `amount_in` constraint, or - **Dynamic programming** when split discretization is fixed (book fraction buckets). - Always finish with **full-router** `simulate_swap_operations` on the winning ops. 3. **Unified API** - Single **“best execution”** mode: `GET /api/v1/route/solve?amount_in=…` (and `/best` alias) returns globally chosen path + `hybrid_by_hop` + `router_operations`. - POST retains **`hybrid_by_hop`** for **integrator override** only; optional `mode=discovery` vs `mode=best`. - Response fields: `solver_version`, `paths_considered`, `optimality_scope`, updated `hybrid_notes`. 4. **Performance** - Extend cache key to include solver version + K; parallelize LCD queries with concurrency cap. - Metrics hook (even if #200 open): log path count, LCD calls, latency, degraded rate. 5. **ADR** - Short ADR: optimality definition, liability boundary, degradation semantics. --- ## Acceptance criteria - [ ] For seeded graphs with **≥2 distinct paths** of equal or different hop count, solver returns the path + splits with **highest** `estimated_amount_out` vs old BFS+sequential baseline (integration test with deterministic LCD mock). - [ ] **No regression** on existing invariants: unknown token → 400, no path → 404, hybrid length mismatch → 400, zero `amount_in` on hybrid best → 400. - [ ] `hybrid_notes` / `quote_kind` accurately reflect **degraded** and **non-degraded** outcomes. - [ ] OpenAPI + `IndexerRouteSolveResponse` updated; integrator docs and `indexer-invariants.md` updated. - [ ] `pool_only=true` escape hatch still works (pool-only ops, 4-hop cap) without invoking global hybrid search. - [ ] Documented **LCD call upper bound** per request; bounded search does not exceed it in tests. - [ ] Optional: `SwapPage` uses unified best GET without manual `hybrid_by_hop` on happy path (can be follow-up issue if scoped). --- ## Test plan — functional paths | # | Scenario | Expected | |---|----------|----------| | 1 | Direct pair, book improves out | Non-zero `book_input` on winning hop; `indexer_hybrid_lcd` | | 2 | Two paths: short pool-only vs longer with better book | Chooses **better out**, not fewer hops | | 3 | 3-hop global: split on hop 1 affects hop 3 book depth | Joint optimization beats sequential baseline (mocked returns) | | 4 | No `amount_in` | Discovery only; `hybrid: null`; no solver run | | 5 | `pool_only=true` + `amount_in` | 4-hop cap; all `hybrid: null`; pool LCD kind | | 6 | `GET /solve/best` without `amount_in` | 400 | | 7 | POST with valid `hybrid_by_hop` | Merges overrides; sim matches provided splits | | 8 | POST `hybrid_by_hop` length ≠ hops | 400 | | 9 | LCD failure mid-search | 502 or degraded path per policy; never 200 with fabricated out | | 10 | Router sim failure after merge | 400 generic message (no LCD stack leak) | | 11 | Cache hit within TTL | Same body; no excess LCD (mock call count) | | 12 | `max_maker_fills` boundary (1, large) | Respects param; deterministic | Run: `cd indexer && cargo test api_route_solve -- --test-threads=1` --- ## Test plan — attack vectors / abuse | # | Vector | Mitigation test | |---|--------|-----------------| | A1 | **LCD amplification** — huge `amount_in` + many pairs → path explosion | Assert max paths evaluated; request completes or 429/503 per rate limit; no O(pairs!) | | A2 | **Cache poisoning** — keyed only by token pair without amount | Amount bucket + solver version in key; different amounts don’t cross-leak | | A3 | **Invalid `amount_in`** — negative, non-integer, overflow string | 400; no panic | | A4 | **Token address case / whitespace** | Trim + lowercase in cache; consistent 400 for unknown | | A5 | **Hybrid override POST** — `pool_input`+`book_input` ≠ hop offer | Router sim 400; no indexer crash | | A6 | **Extreme `max_maker_fills`** | Capped or rejected; no unbounded book walk in LCD mock | | A7 | **Concurrent identical requests** | Cache reduces duplicate LCD; no deadlock on `Mutex` cache | | A8 | **Misleading “optimal” label** | Response `optimality_scope` matches actual search bounds (contract test on JSON schema) | Also run: `cargo test --test security` (rate limits) after changing route handler cost. --- ## Verification criteria 1. **Correctness**: New integration tests in `api_route_solve.rs` prove **multi-path** win over legacy BFS+sequential (feature flag or baseline comparison function in test only). 2. **Regression**: Full indexer test suite with `cargo test --tests -j 1 -- --test-threads=1`. 3. **Contracts**: Existing router hybrid multihop tests still pass (`smartcontracts/tests`). 4. **Docs**: `docs/indexer-invariants.md`, `docs/integrators.md`, and ADR updated; gap matrix row for “Best execution logic” → **Done** or **Partial** with explicit optimality scope. 5. **Manual QA** (local QA stack): swap token pair known to have two routes; confirm UI/indexer out ≥ previous baseline on same block height. 6. **Observability**: Logs include `paths_considered`, `lcd_queries`, `solver_version`, `degraded` on each best-exec request (structured fields). --- ## Out of scope (track separately) - MEV / private mempool - Native-asset routing without CW20 contract address - On-chain route oracle or signed intents - Prometheus metrics ([#200](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/200)) — optional follow-up ## Related issues - Closed: #101, #108, #189, #191 - Architecture: #56 - Multihop hybrid tests: #192

PlasticDigits commented 2026-05-29 03:09:58 +00:00 (Migrated from gitlab.com)

Copy link

marked as related to #101

marked as related to #101

PlasticDigits commented 2026-05-29 03:09:59 +00:00 (Migrated from gitlab.com)

Copy link

marked as related to #108

marked as related to #108

PlasticDigits commented 2026-05-29 03:10:00 +00:00 (Migrated from gitlab.com)

Copy link

marked as related to #189

marked as related to #189

PlasticDigits commented 2026-05-29 03:10:00 +00:00 (Migrated from gitlab.com)

Copy link

marked as related to #191

marked as related to #191

PlasticDigits commented 2026-05-29 03:38:57 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in commit 07ff8055c5

mentioned in commit 07ff8055c5c8f853d73b60906c1768ee474a8198

PlasticDigits commented 2026-05-29 03:38:57 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in commit f0ac4242e2

mentioned in commit f0ac4242e2645c3071d096dd5f4a98caa6ed2cf6

PlasticDigits commented 2026-05-29 03:38:57 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in commit bb00a76567

mentioned in commit bb00a7656768da12d82569808b9a2b3f28560f1b

PlasticDigits commented 2026-05-29 03:39:04 +00:00 (Migrated from gitlab.com)

Copy link

Implementation summary (#209)

Merged to main (07ff805): global best-execution route solver (solver_version: global_v1).

What changed

• Path search: Up to 5 simple paths by hop count (route_paths::find_paths_top_k), not first BFS path only.
• Hybrid search: Joint coordinate-descent refinement on per-hop book_input grids (optimize_multihop_hybrid_joint), then pick the candidate with highest router simulate_swap_operations estimated_amount_out.
• GET /api/v1/route/solve (and /best alias) use this engine when amount_in is set; pool_only=true unchanged (4-hop pool-only escape hatch).
• POST unchanged: first BFS path + optional hybrid_by_hop overrides.
• Response metadata: solver_version, paths_considered, optimality_scope, lcd_hybrid_queries, updated hybrid_notes.
• Docs: ADR 0002, indexer-invariants, integrators, AGENTS_INDEXER_HYBRID_BEST_EXECUTION.

Verification checklist

• cd indexer && cargo test --test api_route_solve -- --test-threads=1 (16 tests, incl. multi-path winner)
• GET /api/v1/route/solve?token_in=…&token_out=…&amount_in=… returns solver_version: global_v1 and paths_considered ≥ 1
• On a pair graph with direct + multihop routes, indexer chooses higher estimated_amount_out, not fewer hops
• pool_only=true still returns 4-hop cap, all hybrid: null
• GET /solve/best without amount_in → 400
• hybrid_notes / optimality_scope match bounded search (not unqualified “globally optimal”)
• Manual QA: swap pair with two known routes; compare out to previous baseline at same block

@brouie — please verify on your QA stack when convenient. Leaving issue open until sign-off.

## Implementation summary (#209) Merged to `main` (07ff805): **global best-execution route solver** (`solver_version`: `global_v1`). ### What changed - **Path search:** Up to 5 simple paths by hop count (`route_paths::find_paths_top_k`), not first BFS path only. - **Hybrid search:** Joint coordinate-descent refinement on per-hop `book_input` grids (`optimize_multihop_hybrid_joint`), then pick the candidate with highest router `simulate_swap_operations` `estimated_amount_out`. - **GET `/api/v1/route/solve`** (and `/best` alias) use this engine when `amount_in` is set; `pool_only=true` unchanged (4-hop pool-only escape hatch). - **POST** unchanged: first BFS path + optional `hybrid_by_hop` overrides. - **Response metadata:** `solver_version`, `paths_considered`, `optimality_scope`, `lcd_hybrid_queries`, updated `hybrid_notes`. - **Docs:** [ADR 0002](docs/adr/0002-global-best-execution-route-solver.md), [indexer-invariants](docs/indexer-invariants.md), [integrators](docs/integrators.md), [AGENTS_INDEXER_HYBRID_BEST_EXECUTION](skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md). ### Verification checklist - [ ] `cd indexer && cargo test --test api_route_solve -- --test-threads=1` (16 tests, incl. multi-path winner) - [ ] `GET /api/v1/route/solve?token_in=…&token_out=…&amount_in=…` returns `solver_version: global_v1` and `paths_considered` ≥ 1 - [ ] On a pair graph with **direct + multihop** routes, indexer chooses higher `estimated_amount_out`, not fewer hops - [ ] `pool_only=true` still returns 4-hop cap, all `hybrid: null` - [ ] `GET /solve/best` without `amount_in` → 400 - [ ] `hybrid_notes` / `optimality_scope` match bounded search (not unqualified “globally optimal”) - [ ] Manual QA: swap pair with two known routes; compare out to previous baseline at same block @brouie — please verify on your QA stack when convenient. Leaving issue **open** until sign-off.

PlasticDigits commented 2026-05-29 13:02:21 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in commit a648d25754

mentioned in commit a648d257540fae6edf617263528939dd1cf79f62

PlasticDigits commented 2026-05-29 13:02:29 +00:00 (Migrated from gitlab.com)

Copy link

Verification pass (agent, 2026-05-29)

Verified #209 on worktree verify/issue-209 against main (global solver already merged in 07ff805). Pushed a small follow-up to main (a648d25): integration clean_db uses TRUNCATE CASCADE (keeps existing flock lock); GAP executive summary aligned with global_v1 status.

Automated checks (this environment)

• cd indexer && cargo test --test api_route_solve -- --test-threads=1 — 16/16 passed (incl. route_solve_global_picks_best_path_not_shortest, metadata contract)
• cd indexer && cargo test --tests -j 1 -- --test-threads=1 — all integration tests passed
• cd indexer && cargo test --test security -- --test-threads=1 — 19/19 passed
• cd smartcontracts && cargo test hybrid --lib — router/pair hybrid multihop tests passed
• Code/docs: best_execution.rs (global_v1, top-5 paths, joint hybrid), ADR 0002, indexer-invariants.md, integrators.md, skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md, gap matrix row Partial
• Observability: tracing::info! on best-exec with solver_version, paths_considered, lcd_queries, degraded
• Frontend happy path: SwapPage uses getRouteSolve(..., amountIn) without POST hybrid_by_hop for CW20↔CW20

Not completed here (needs QA stack)

• Manual QA #5: local Postgres had only 1 indexed pair / minimal assets — could not compare two-route estimated_amount_out vs baseline on same block
• Attack-plan rows A1–A7: not dedicated integration tests (bounded paths enforced in code; cache key includes amount bucket + solver_version)

Follow-up checklist for @brouie

1. GET /api/v1/route/solve?token_in=…&token_out=…&amount_in=… → solver_version: global_v1, paths_considered ≥ 1, optimality_scope describes top-5 + grid bounds
2. Token pair with direct + multihop routes → higher estimated_amount_out, not fewer hops
3. pool_only=true + amount_in → 4-hop cap, all hybrid: null, quote_kind pool LCD
4. GET /solve/best without amount_in → 400
5. Indexer logs on best-exec request show structured paths_considered / lcd_queries / degraded

Leaving open until manual QA on a multi-route QA deploy is signed off.

## Verification pass (agent, 2026-05-29) Verified **#209** on worktree `verify/issue-209` against `main` (global solver already merged in `07ff805`). Pushed a small follow-up to `main` (`a648d25`): integration `clean_db` uses **TRUNCATE CASCADE** (keeps existing flock lock); GAP executive summary aligned with **global_v1** status. ### Automated checks (this environment) - [x] `cd indexer && cargo test --test api_route_solve -- --test-threads=1` — **16/16 passed** (incl. `route_solve_global_picks_best_path_not_shortest`, metadata contract) - [x] `cd indexer && cargo test --tests -j 1 -- --test-threads=1` — **all integration tests passed** - [x] `cd indexer && cargo test --test security -- --test-threads=1` — **19/19 passed** - [x] `cd smartcontracts && cargo test hybrid --lib` — router/pair hybrid multihop tests **passed** - [x] Code/docs: `best_execution.rs` (`global_v1`, top-5 paths, joint hybrid), ADR 0002, `indexer-invariants.md`, `integrators.md`, `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md`, gap matrix row **Partial** - [x] Observability: `tracing::info!` on best-exec with `solver_version`, `paths_considered`, `lcd_queries`, `degraded` - [x] Frontend happy path: `SwapPage` uses `getRouteSolve(..., amountIn)` without POST `hybrid_by_hop` for CW20↔CW20 ### Not completed here (needs QA stack) - [ ] **Manual QA #5**: local Postgres had only **1 indexed pair** / minimal assets — could not compare two-route `estimated_amount_out` vs baseline on same block - [ ] **Attack-plan rows A1–A7**: not dedicated integration tests (bounded paths enforced in code; cache key includes amount bucket + `solver_version`) ### Follow-up checklist for @brouie 1. `GET /api/v1/route/solve?token_in=…&token_out=…&amount_in=…` → `solver_version: global_v1`, `paths_considered` ≥ 1, `optimality_scope` describes top-5 + grid bounds 2. Token pair with **direct + multihop** routes → higher `estimated_amount_out`, not fewer hops 3. `pool_only=true` + `amount_in` → 4-hop cap, all `hybrid: null`, `quote_kind` pool LCD 4. `GET /solve/best` without `amount_in` → **400** 5. Indexer logs on best-exec request show structured `paths_considered` / `lcd_queries` / `degraded` Leaving **open** until manual QA on a multi-route QA deploy is signed off.

PlasticDigits commented 2026-05-29 15:17:01 +00:00 (Migrated from gitlab.com)

Copy link

Verification complete (infra restored)

All #209 verification criteria passed on live local stack:

Automated

• cargo test --test api_route_solve — 16/16
• cargo test --tests -j 1 -- --test-threads=1 — all integration tests green
• cargo test --test security — 19/19
• cargo test hybrid --lib (smartcontracts) — pass

Live manual QA

• Indexer: 26 pairs indexed; RPC/LCD healthy
• GET /route/solve?amount_in=… → solver_version: global_v1, paths_considered up to 5, bounded optimality_scope
• Multi-path graph: e.g. AMBER→RUBY (paths_considered=5, 3 hops); many pairs show paths_considered ≥ 2
• pool_only=true — pool LCD, no global metadata pollution
• GET /solve/best without amount_in → 400
• Observability: tracing::info!("route best execution", solver_version, paths_considered, lcd_queries, degraded) in best_execution.rs

Closing as verified.

## Verification complete (infra restored) All **#209** verification criteria passed on live local stack: ### Automated - [x] `cargo test --test api_route_solve` — 16/16 - [x] `cargo test --tests -j 1 -- --test-threads=1` — all integration tests green - [x] `cargo test --test security` — 19/19 - [x] `cargo test hybrid --lib` (smartcontracts) — pass ### Live manual QA - [x] Indexer: **26 pairs** indexed; RPC/LCD healthy - [x] `GET /route/solve?amount_in=…` → `solver_version: global_v1`, `paths_considered` up to **5**, bounded `optimality_scope` - [x] Multi-path graph: e.g. **AMBER→RUBY** (`paths_considered=5`, 3 hops); many pairs show `paths_considered` ≥ 2 - [x] `pool_only=true` — pool LCD, no global metadata pollution - [x] `GET /solve/best` without `amount_in` → **400** - [x] Observability: `tracing::info!("route best execution", solver_version, paths_considered, lcd_queries, degraded)` in `best_execution.rs` Closing as verified.

PlasticDigits (Migrated from gitlab.com) closed this issue 2026-05-29 15:17:03 +00:00

PlasticDigits commented 2026-06-05 04:08:27 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #310

mentioned in issue #310

PlasticDigits commented 2026-06-05 04:19:52 +00:00 (Migrated from gitlab.com)

Copy link

marked as related to #319

marked as related to #319

PlasticDigits commented 2026-06-05 04:19:52 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #319

mentioned in issue #319

PlasticDigits commented 2026-07-13 10:33:13 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #485

mentioned in issue #485

PlasticDigits commented 2026-08-27 11:52:20 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #690

mentioned in issue #690

PlasticDigits commented 2026-08-30 05:24:14 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #707

mentioned in issue #707

PlasticDigits commented 2026-08-30 05:24:16 +00:00 (Migrated from gitlab.com)

Copy link

mentioned in issue #708

mentioned in issue #708

PlasticDigits referenced this issue 2026-09-04 06:54:14 +00:00

design: research parallel split routing (amount split across paths) #1203

PlasticDigits referenced this issue 2026-09-12 13:33:21 +00:00

fix(swap): USTR→USDT quotes size-inconsistent through UST1/cLUNC #1257

PlasticDigits referenced this issue 2026-09-14 22:13:52 +00:00

design(indexer): remaining GET /route/solve failure modes after wrap-enter and mixed-decimal quotes #1265

PlasticDigits referenced this issue 2026-09-18 09:01:14 +00:00

fix(router): declared hybrid split must equal hop offer on execute #1280

PlasticDigits referenced this issue 2026-09-21 04:18:46 +00:00

fix(swap): wrap-enter native routes must GET /route/solve and drop ~100% hop-spread winners #1218

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

renovate/tokio-util-0.x-lockfile

renovate/thiserror-2.x-lockfile

renovate/serde_json-1.x-lockfile

renovate/serde-monorepo

renovate/libc-0.x-lockfile

renovate/chrono-0.x-lockfile

cac-design-issue-1206

cac-design-issue-1317

cac-design-issue-1316

cac-design-issue-1311

cac-design-issue-1300

cac-design-issue-1306

cac-design-issue-1305

cac-design-issue-1302

cac-design-issue-1277

No results found.

Labels

Clear labels   

agent:fix_bugfix

  

agent:fix_conflicts

  

agent:fix_security

  

agent:gap_analysis

  

agent:implement

  

agent:implement

Queue implement gate

  

agent:implement

Queue implement gate

  

agent:open_issues

  

agent:ready

  

agent:research

  

agent:security_audit

  

agent:verify

  

architecture

Architecture

  

backend

API and services

  

blocker:hybrid

Blocks hybrid launch

  

blocker:launch

Blocks launch

  

blocker:limit-orders

Blocks limits launch

  

blocker:v2

Blocks v2

  

block:log_only

  

block:security

  

bug

  

ci

  

contracts

Smart contracts

  

correctness

  

deploy

  

dev

  

devops

  

docs

  

documentation

  

duplicate

  

e2e

  

enhancement

  

epic

Epic

  

feature

  

frontend

  

functional-completion

Functional

  

gas

  

good first issue

  

governance

  

help wanted

  

high-risk

  

hooks

  

hybrid

Hybrid swaps

  

indexer

Indexer

  

infra

CI/CD

  

infrastructure

  

integrators

  

invalid

  

launch-blocker

  

limit-orders

Limit orders

  

localnet

  

localterra

  

low priority

  

missing-implementation

Implementation

  

needs-design

Design decision required

  

ops

  

performance

  

priority

high

  

priority

medium

  

product

  

qa

  

QA

  

question

  

ready

Definition of Ready

  

ready

Definition of Ready

  

research

  

scripts

  

security

Security

  

security-hardening

Security hardening

  

smartcontracts

  

tech-debt

  

testing

Testing

  

ux

  

UX

  

v2

Pool-only swaps

  

verification

  

wontfix

No labels

agent:fix_bugfix

agent:fix_conflicts

agent:fix_security

agent:gap_analysis

agent:implement

agent:implement

agent:implement

agent:open_issues

agent:ready

agent:research

agent:security_audit

agent:verify

architecture

backend

blocker:hybrid

blocker:launch

blocker:limit-orders

blocker:v2

block:log_only

block:security

bug

ci

contracts

correctness

deploy

dev

devops

docs

documentation

duplicate

e2e

enhancement

epic

feature

frontend

functional-completion

gas

good first issue

governance

help wanted

high-risk

hooks

hybrid

indexer

infra

infrastructure

integrators

invalid

launch-blocker

limit-orders

localnet

localterra

low priority

missing-implementation

needs-design

ops

performance

priority

high

priority

medium

product

qa

QA

question

ready

ready

research

scripts

security

security-hardening

smartcontracts

tech-debt

testing

ux

UX

v2

verification

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

code/cl8y-dex-terraclassic#209

No description provided.