Indexer hybrid route optimizer: pass book_start_hint for first live-side order (#332) #816

2026-06-05T14:00:55Z

PlasticDigits commented

2026-06-05 14:00:55 +00:00

(Migrated from gitlab.com)

Summary

Implements GitLab #332 (follow-up to #289).

The global_v2 hybrid route optimizer now resolves the first live resting order on the taker's match side from a fresh Postgres mirror and forwards that order_id as book_start_hint through:

Mirror grid simulate_hybrid_from_mirror (book walk starts at hinted order when valid same-side)
LCD HybridSimulation queries during optimization (when mirror fresh)
Returned HybridHopJson / router_operations when book_input > 0

Stale or missing mirror → hint omitted (null); LCD fallback grid never emits hints. Pool-only hops → null. Wrong-side corrupt mirror rows are skipped.

Acceptance checklist

Criterion	Verification	Result
`optimize_hop_hybrid` sets `book_start_hint` to first live-side order id when book leg > 0 and mirror fresh	`cargo test --test api_route_solve_db_hybrid route_solve_db_hybrid_book_start_hint_paths` (live head + expired-head scenarios)	PASS
`HybridSimulation` queries use same hint as output ops	Code: `hybrid_sim_query` + `optimize_one_hop` share resolved hint; integration test asserts router op hint matches	PASS
Stale/missing mirror → `book_start_hint: null`	Same integration test stale-mirror scenario + `first_live_book_start_hint` unit tests	PASS
`api_route_solve` tests updated	New `route_solve_db_hybrid_book_start_hint_paths`; existing `api_route_solve` suite green	PASS
Docs note hint behavior in route-solver glossary	`docs/route-solver.md` glossary + skills updated	PASS
`cargo test --test api_route_solve` green	`cd indexer && cargo test --test api_route_solve --test api_route_solve_db_hybrid -- --test-threads=1`	PASS
Manual LocalTerra `POST /route/solve` non-null hint	Requires full LocalTerra stack; covered by DB mirror integration test	SKIP

Verification for third parties

cd indexer && cargo test --lib db_orderbook_sim
cd indexer && cargo test --test api_route_solve --test api_route_solve_db_hybrid -- --test-threads=1

docs/route-solver.md — book_start_hint glossary entry
skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md
skills/AGENTS_BOOK_MATCH_HINT_SECURITY.md

Note

Medium Risk
Touches hybrid quoting and execute-facing router ops; hint logic is side-validated but wrong mirror data or hint/execute drift could still affect fills until on-chain L17 runs.

Overview
global_v2 (Postgres mirror hybrid optimizer) now sets book_start_hint on hops with book_input > 0 when the mirror is fresh: the first live resting order on the taker’s match side (bid when offering token0, ask when offering token1). Stale/missing mirrors, LCD-only global_v1, and pool-only legs keep null.

Mirror HybridSimulation and the 17-point grid / coordinate-descent path thread the same hint into book walks (validated same-side slice, wrong-side rows skipped). Optimized router_operations include the hint for execute-time parity with on-chain L17; stale-mirror LCD fallback still omits hints.

Docs and agent skills updated; integration test route_solve_db_hybrid_book_start_hint_paths covers live head, expired-head skip, and stale mirror.

^{Reviewed by Cursor Bugbot for commit 63640f1c74. Bugbot is set up for automated code reviews on this repo. Configure here.}

## Summary Implements GitLab [#332](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/332) (follow-up to [#289](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/289)). The `global_v2` hybrid route optimizer now resolves the first **live** resting order on the taker's match side from a fresh Postgres mirror and forwards that `order_id` as `book_start_hint` through: - Mirror grid `simulate_hybrid_from_mirror` (book walk starts at hinted order when valid same-side) - LCD `HybridSimulation` queries during optimization (when mirror fresh) - Returned `HybridHopJson` / `router_operations` when `book_input > 0` Stale or missing mirror → hint omitted (`null`); LCD fallback grid never emits hints. Pool-only hops → `null`. Wrong-side corrupt mirror rows are skipped. ## Acceptance checklist | Criterion | Verification | Result | |-----------|--------------|--------| | `optimize_hop_hybrid` sets `book_start_hint` to first live-side order id when book leg > 0 and mirror fresh | `cargo test --test api_route_solve_db_hybrid route_solve_db_hybrid_book_start_hint_paths` (live head + expired-head scenarios) | PASS | | `HybridSimulation` queries use same hint as output ops | Code: `hybrid_sim_query` + `optimize_one_hop` share resolved hint; integration test asserts router op hint matches | PASS | | Stale/missing mirror → `book_start_hint: null` | Same integration test stale-mirror scenario + `first_live_book_start_hint` unit tests | PASS | | `api_route_solve` tests updated | New `route_solve_db_hybrid_book_start_hint_paths`; existing `api_route_solve` suite green | PASS | | Docs note hint behavior in route-solver glossary | `docs/route-solver.md` glossary + skills updated | PASS | | `cargo test --test api_route_solve` green | `cd indexer && cargo test --test api_route_solve --test api_route_solve_db_hybrid -- --test-threads=1` | PASS | | Manual LocalTerra `POST /route/solve` non-null hint | Requires full LocalTerra stack; covered by DB mirror integration test | SKIP | ## Verification for third parties ```bash cd indexer && cargo test --lib db_orderbook_sim cd indexer && cargo test --test api_route_solve --test api_route_solve_db_hybrid -- --test-threads=1 ``` ## Related docs - `docs/route-solver.md` — `book_start_hint` glossary entry - `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md` - `skills/AGENTS_BOOK_MATCH_HINT_SECURITY.md`  --- > [!NOTE] > **Medium Risk** > Touches hybrid quoting and execute-facing router ops; hint logic is side-validated but wrong mirror data or hint/execute drift could still affect fills until on-chain L17 runs. > > **Overview** > **`global_v2`** (Postgres mirror hybrid optimizer) now sets **`book_start_hint`** on hops with **`book_input > 0`** when the mirror is fresh: the first **live** resting order on the taker’s match side (bid when offering token0, ask when offering token1). Stale/missing mirrors, LCD-only **`global_v1`**, and pool-only legs keep **`null`**. > > Mirror **`HybridSimulation`** and the 17-point grid / coordinate-descent path thread the same hint into book walks (validated same-side slice, wrong-side rows skipped). Optimized **`router_operations`** include the hint for execute-time parity with on-chain **L17**; stale-mirror LCD fallback still omits hints. > > Docs and agent skills updated; integration test **`route_solve_db_hybrid_book_start_hint_paths`** covers live head, expired-head skip, and stale mirror. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 63640f1c746b9adbaacf4a299eeef69f345b2c91. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

ghost1 commented

2026-06-05 14:01:04 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 14:01:07 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 14:01:07 +00:00

(Migrated from gitlab.com)

mentioned in issue #332

ghost1 commented

2026-06-05 14:01:10 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 14:03:46 +00:00

(Migrated from gitlab.com)

Security review (automated)

Commit reviewed: 63640f1c746b9adbaacf4a299eeef69f345b2c91

Scope: MR !816 — indexer global_v2 hybrid route optimizer: book_start_hint resolution from fresh Postgres mirror, mirror book-walk slicing, LCD HybridSimulation hint forwarding (fresh mirror only), docs/skills/tests.

Outcome: FINDINGS: 0 (no medium, high, or critical issues on this diff)

Inline threads: none (no findings to anchor)

Summary

Reviewed added/modified logic in indexer/src/api/db_orderbook_sim.rs, indexer/src/api/hybrid_route_opt.rs, and related tests/docs. Traced attacker-controlled inputs on GET|POST /api/v1/route/solve to sinks.

Controls observed (adequate for this change):

Area	Assessment
Input source	`book_start_hint` is derived from indexer-owned mirror rows (`resting_limit_orders` / `HopMirror`), not from route-solve query/body parameters. Clients can still supply hints via existing `POST hybrid_by_hop` (unchanged by this MR).
Side safety (L17 parity)	`first_live_book_start_hint` and `book_orders_from_hint` require `order.side == expected_side` on the correct bid/ask list; wrong-side mirror rows are skipped. Matches on-chain `resolve_match_start_hint` / `order_on_match_side` (#272).
Stale / degraded paths	Hints omitted when `MirrorFreshness != Fresh`; LCD fallback grid explicitly passes `None` for hints.
Execute-time authority	Returned `router_operations` hints are advisory; contract L17 remains authoritative — invalid/wrong-side/stale hints fall back to head without cross-side escrow debit (existing contract tests).
Injection / SSRF / auth	Hint is a `u64` order id in JSON LCD queries; no new user-controlled strings, endpoints, or LCD budget expansion beyond existing hybrid grid.
Secrets / logging	No new sensitive logging.

Not reported (out of scope / below bar): governance trust in mirror freshness, quote-vs-execute drift from indexing lag (mitigated by staleness gates + on-chain validation), and pre-existing POST hybrid_by_hop client-supplied hints.

Security review: no medium+ findings on this diff.

## Security review (automated) **Commit reviewed:** `63640f1c746b9adbaacf4a299eeef69f345b2c91` **Scope:** MR !816 — indexer `global_v2` hybrid route optimizer: `book_start_hint` resolution from fresh Postgres mirror, mirror book-walk slicing, LCD `HybridSimulation` hint forwarding (fresh mirror only), docs/skills/tests. **Outcome:** `FINDINGS: 0` (no medium, high, or critical issues on this diff) **Inline threads:** none (no findings to anchor) --- ### Summary Reviewed added/modified logic in `indexer/src/api/db_orderbook_sim.rs`, `indexer/src/api/hybrid_route_opt.rs`, and related tests/docs. Traced attacker-controlled inputs on `GET|POST /api/v1/route/solve` to sinks. **Controls observed (adequate for this change):** | Area | Assessment | |------|------------| | **Input source** | `book_start_hint` is derived from indexer-owned mirror rows (`resting_limit_orders` / `HopMirror`), not from route-solve query/body parameters. Clients can still supply hints via existing `POST hybrid_by_hop` (unchanged by this MR). | | **Side safety (L17 parity)** | `first_live_book_start_hint` and `book_orders_from_hint` require `order.side == expected_side` on the correct bid/ask list; wrong-side mirror rows are skipped. Matches on-chain `resolve_match_start_hint` / `order_on_match_side` ([#272](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/272)). | | **Stale / degraded paths** | Hints omitted when `MirrorFreshness != Fresh`; LCD fallback grid explicitly passes `None` for hints. | | **Execute-time authority** | Returned `router_operations` hints are advisory; contract L17 remains authoritative — invalid/wrong-side/stale hints fall back to head without cross-side escrow debit (existing contract tests). | | **Injection / SSRF / auth** | Hint is a `u64` order id in JSON LCD queries; no new user-controlled strings, endpoints, or LCD budget expansion beyond existing hybrid grid. | | **Secrets / logging** | No new sensitive logging. | **Not reported (out of scope / below bar):** governance trust in mirror freshness, quote-vs-execute drift from indexing lag (mitigated by staleness gates + on-chain validation), and pre-existing POST `hybrid_by_hop` client-supplied hints. Security review: **no medium+ findings** on this diff.

PlasticDigits commented

2026-06-05 14:26:53 +00:00

(Migrated from gitlab.com)

mentioned in commit 8edf0509e5

mentioned in commit 8edf0509e5534e1ca7851ad6467e2fec9741fca5