code/cl8y-dex-terraclassic

Fork 0

API: server hybrid best execution + Terraport-shaped events for Vyntrex + consolidated CMC/CG reporting #189

New issue

Closed

opened 2026-05-26 07:58:37 +00:00 by PlasticDigits · 13 comments

PlasticDigits commented

2026-05-26 07:58:37 +00:00

(Migrated from gitlab.com)

Problem statement

Vyntrex integration needs server-driven hybrid best execution (not only manual Pattern C / opt-in hybrid_optimize) and on-chain/indexer events that match Terraport-compatible shapes for volume, price, and related swap fields on hybrid settlements. CoinGecko / CoinMarketCap endpoints must report hybrid and v2 (pool-only) activity in one consolidated view so external listings do not under-count book legs.

Evidence / context

Product gap: ISSUE_BACKLOG.md — DEX-P0-EPIC / #108; GET /api/v1/route/solve still defaults pool-only unless hybrid_optimize=true (indexer/src/api/route_solver.rs).
Terraport reference for integrator event shapes: docs/terraport.md.
Listing APIs: docs/CG_CMC_COMPLIANCE.md; indexer CMC/CG routes under indexer/src/api/.
Hybrid swap attributes today: book_return_amount, limit_book_offer_consumed, pool_return_amount on swap_events (docs/limit-orders.md).

Proposed solution

Indexer API: Expose a first-class hybrid best-execution solve path (default or dedicated endpoint) that returns execution-aligned splits and router ops (build on hybrid_route_opt / HybridSimulation + LCD sim where configured).
Events / ingestion: Ensure wasm/indexer persistence and any export/webhook fields needed for Vyntrex include hybrid legs with Terraport-equivalent volume/price semantics (document mapping table CL8Y → Terraport).
CMC/CG: Extend ticker/summary/trades endpoints so hybrid + pool-only v2 volumes and last prices are consolidated (no double-count; book vs pool attribution documented).

Acceptance criteria

ADR or docs/integrators.md section defines hybrid best-execution API contract, hop limits, and Terraport field mapping for Vyntrex.
Indexer serves server-chosen hybrid splits for the default retail path (or documented successor endpoint).
Hybrid swaps emit/store fields sufficient for Vyntrex volume/price reconciliation; fixture tests with sample tx JSON.
CMC/CG endpoints include hybrid activity in consolidated pair/market stats; compliance doc updated with examples.
No regression for pool-only integrators (explicit opt-out or versioned response documented).

Dependencies

Related: product epic #56, #108; route defaults tracked separately.

Priority

P0 (integration + listings)

## Problem statement Vyntrex integration needs **server-driven hybrid best execution** (not only manual Pattern C / opt-in `hybrid_optimize`) and **on-chain/indexer events** that match **Terraport-compatible** shapes for volume, price, and related swap fields on **hybrid** settlements. CoinGecko / CoinMarketCap endpoints must report **hybrid and v2 (pool-only) activity in one consolidated view** so external listings do not under-count book legs. ## Evidence / context - Product gap: [ISSUE_BACKLOG.md — DEX-P0-EPIC / #108](docs/reviews/20260409T030009Z/ISSUE_BACKLOG.md); `GET /api/v1/route/solve` still defaults pool-only unless `hybrid_optimize=true` ([`indexer/src/api/route_solver.rs`](indexer/src/api/route_solver.rs)). - Terraport reference for integrator event shapes: [`docs/terraport.md`](docs/terraport.md). - Listing APIs: [`docs/CG_CMC_COMPLIANCE.md`](docs/CG_CMC_COMPLIANCE.md); indexer CMC/CG routes under `indexer/src/api/`. - Hybrid swap attributes today: `book_return_amount`, `limit_book_offer_consumed`, `pool_return_amount` on `swap_events` ([`docs/limit-orders.md`](docs/limit-orders.md)). ## Proposed solution 1. **Indexer API:** Expose a first-class **hybrid best-execution** solve path (default or dedicated endpoint) that returns execution-aligned splits and router ops (build on `hybrid_route_opt` / `HybridSimulation` + LCD sim where configured). 2. **Events / ingestion:** Ensure wasm/indexer persistence and any **export/webhook fields** needed for Vyntrex include hybrid legs with **Terraport-equivalent** volume/price semantics (document mapping table CL8Y → Terraport). 3. **CMC/CG:** Extend ticker/summary/trades endpoints so **hybrid + pool-only v2** volumes and last prices are **consolidated** (no double-count; book vs pool attribution documented). ## Acceptance criteria - [ ] ADR or `docs/integrators.md` section defines hybrid best-execution API contract, hop limits, and Terraport field mapping for Vyntrex. - [ ] Indexer serves server-chosen hybrid splits for the default retail path (or documented successor endpoint). - [ ] Hybrid swaps emit/store fields sufficient for Vyntrex volume/price reconciliation; fixture tests with sample tx JSON. - [ ] CMC/CG endpoints include hybrid activity in consolidated pair/market stats; compliance doc updated with examples. - [ ] No regression for pool-only integrators (explicit opt-out or versioned response documented). ## Dependencies - Related: product epic **#56**, **#108**; route defaults tracked separately. ## Priority **P0** (integration + listings)

PlasticDigits commented

2026-05-26 09:34:19 +00:00

(Migrated from gitlab.com)

mentioned in commit 216ef38822

mentioned in commit 216ef388227493eb97e91aded907198fec5b64b9

PlasticDigits commented

2026-05-26 09:34:26 +00:00

(Migrated from gitlab.com)

Implementation summary (merged to `main` @ `216ef38`)

Implemented GitLab #189 — server-driven hybrid best execution, Terraport-shaped event documentation, and consolidated CG/CMC reporting.

Changes

Best-execution route API
- New GET /api/v1/route/solve/best — retail / Vyntrex path; requires amount_in, always runs per-hop hybrid optimization (max 3 hops), same engine as hybrid_optimize=true.
- Refactored shared execute_hybrid_route_solve in route_solver.rs.
- Documented pool_only=true opt-out on legacy GET /route/solve for pool-only integrators.
Terraport / Vyntrex event mapping
- Added mapping table in docs/integrators.md and CL8Y hybrid extension section in docs/terraport.md.
- Updated ADR 0001 and docs/indexer-invariants.md.
Consolidated CG/CMC reporting
- New consolidated_stats module + get_24h_hybrid_breakdown SQL.
- /cg/tickers and /cmc/summary include cl8y_extensions (hybrid vs pool-only trade counts + leg volumes).
- Trade feeds add optional pool_leg_volume / book_leg_volume on hybrid swaps.
- Documented in docs/CG_CMC_COMPLIANCE.md.
Agent skill
- skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md for third-party integrators.
Tests
- api_route_solve.rs: /best endpoint, degraded LCD fallback.
- api_consolidated_reporting.rs: CG/CMC extension fields.
- Existing swap_events_hybrid_columns.rs covers fixture tx → DB round-trip.

Verification checklist

GET /api/v1/route/solve/best?token_in=…&token_out=…&amount_in=… returns quote_kind of indexer_hybrid_lcd (or indexer_hybrid_lcd_degraded when LCD hybrid sim unavailable) with non-null hybrid on hops when book liquidity exists
Legacy GET /api/v1/route/solve without hybrid_optimize still returns pool-only hybrid: null ops (no regression)
Hybrid swap txs index pool_return_amount, book_return_amount, limit_book_offer_consumed on swap_events (see /api/v1/pairs/{addr}/trades)
/cg/tickers entries include cl8y_extensions.consolidated: true and correct hybrid trade counts when hybrid swaps exist in last 24h
/cmc/summary includes matching cl8y_extensions
/cg/historical_trades and /cmc/trades/{pair} expose pool_leg_volume / book_leg_volume on hybrid trades only
Standard volume fields remain consolidated totals (no double-count with limit_order_fills)
Docs cross-links: integrators.md, terraport.md, CG_CMC_COMPLIANCE.md, indexer-invariants.md, ADR 0001, skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md

Tests

cd indexer && cargo test route_solve consolidated hybrid_swap -- --test-threads=1

@brouie — please verify the above checklist against staging/production indexer when convenient. Leaving issue open until signed off.

/cc @brouie

## Implementation summary (merged to `main` @ 216ef38) Implemented GitLab #189 — server-driven hybrid best execution, Terraport-shaped event documentation, and consolidated CG/CMC reporting. ### Changes 1. **Best-execution route API** - New `GET /api/v1/route/solve/best` — retail / Vyntrex path; requires `amount_in`, always runs per-hop hybrid optimization (max 3 hops), same engine as `hybrid_optimize=true`. - Refactored shared `execute_hybrid_route_solve` in `route_solver.rs`. - Documented `pool_only=true` opt-out on legacy `GET /route/solve` for pool-only integrators. 2. **Terraport / Vyntrex event mapping** - Added mapping table in `docs/integrators.md` and CL8Y hybrid extension section in `docs/terraport.md`. - Updated ADR 0001 and `docs/indexer-invariants.md`. 3. **Consolidated CG/CMC reporting** - New `consolidated_stats` module + `get_24h_hybrid_breakdown` SQL. - `/cg/tickers` and `/cmc/summary` include `cl8y_extensions` (hybrid vs pool-only trade counts + leg volumes). - Trade feeds add optional `pool_leg_volume` / `book_leg_volume` on hybrid swaps. - Documented in `docs/CG_CMC_COMPLIANCE.md`. 4. **Agent skill** - `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md` for third-party integrators. 5. **Tests** - `api_route_solve.rs`: `/best` endpoint, degraded LCD fallback. - `api_consolidated_reporting.rs`: CG/CMC extension fields. - Existing `swap_events_hybrid_columns.rs` covers fixture tx → DB round-trip. ### Verification checklist - [ ] `GET /api/v1/route/solve/best?token_in=…&token_out=…&amount_in=…` returns `quote_kind` of `indexer_hybrid_lcd` (or `indexer_hybrid_lcd_degraded` when LCD hybrid sim unavailable) with non-null `hybrid` on hops when book liquidity exists - [ ] Legacy `GET /api/v1/route/solve` without `hybrid_optimize` still returns pool-only `hybrid: null` ops (no regression) - [ ] Hybrid swap txs index `pool_return_amount`, `book_return_amount`, `limit_book_offer_consumed` on `swap_events` (see `/api/v1/pairs/{addr}/trades`) - [ ] `/cg/tickers` entries include `cl8y_extensions.consolidated: true` and correct hybrid trade counts when hybrid swaps exist in last 24h - [ ] `/cmc/summary` includes matching `cl8y_extensions` - [ ] `/cg/historical_trades` and `/cmc/trades/{pair}` expose `pool_leg_volume` / `book_leg_volume` on hybrid trades only - [ ] Standard volume fields remain consolidated totals (no double-count with `limit_order_fills`) - [ ] Docs cross-links: `integrators.md`, `terraport.md`, `CG_CMC_COMPLIANCE.md`, `indexer-invariants.md`, ADR 0001, `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md` ### Tests ```bash cd indexer && cargo test route_solve consolidated hybrid_swap -- --test-threads=1 ``` @brouie — please verify the above checklist against staging/production indexer when convenient. Leaving issue open until signed off. /cc @brouie

PlasticDigits commented

2026-05-26 09:36:59 +00:00

(Migrated from gitlab.com)

mentioned in issue #190

PlasticDigits commented

2026-05-27 06:34:23 +00:00

(Migrated from gitlab.com)

mentioned in commit 0e5f020551

mentioned in commit 0e5f020551e769b17a58d71f0e2c5e3bf12431f9

PlasticDigits commented

2026-05-27 06:35:28 +00:00

(Migrated from gitlab.com)

Verification complete

Verified GitLab #189 against local stack (LocalTerra, host Postgres :5432, indexer :3001, bot swarm 30/30). All acceptance criteria and checklist items pass.

Checklist

GET /api/v1/route/solve/best returns quote_kind: indexer_hybrid_lcd with non-null hybrid when book liquidity exists (EMBER→CORAL, amount_in=1e6)
Legacy pool-only opt-out: GET /route/solve?pool_only=true&amount_in=… returns hybrid: null (indexer_pool_lcd)
Hybrid swap columns indexed: DB swap_event id 461 has pool_return_amount, book_return_amount, limit_book_offer_consumed; /pairs/{addr}/trades exposes leg columns
/cg/tickers and /cmc/summary include cl8y_extensions.consolidated: true with hybrid/pool-only 24h counts
/cg/historical_trades and /cmc/trades/{pair} expose pool_leg_volume / book_leg_volume
Standard volume fields remain consolidated totals (no double-count)
Docs cross-links present (integrators.md, terraport.md, CG_CMC_COMPLIANCE.md, indexer-invariants.md, ADR 0001, skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md)

Bug fix (merged @ `0e5f020`)

route_solve_hybrid_optimize_degraded_falls_back_to_pool_only was failing: when all HybridSimulation grid queries returned HTTP 500, LCD endpoint cooldown blocked the pool simulation fallback, causing /best to 502. Fixed by:

Falling back directly to pool simulation when hybrid grid fails (hybrid_route_opt.rs)
Not cooling down LCD endpoints on contract-level 4xx/500 responses (lcd/mod.rs)

Tests

cargo test --test api_route_solve -- --test-threads=1  # 14 passed
cargo test --test api_consolidated_reporting -- --test-threads=1  # 3 passed
cargo test --test swap_events_hybrid_columns -- --test-threads=1  # 1 passed

Cursor browser MCP was not available in this environment; verification was API + test driven (backend-only scope).

## Verification complete Verified GitLab #189 against local stack (LocalTerra, host Postgres :5432, indexer :3001, bot swarm 30/30). All acceptance criteria and checklist items pass. ### Checklist - [x] `GET /api/v1/route/solve/best` returns `quote_kind: indexer_hybrid_lcd` with non-null `hybrid` when book liquidity exists (EMBER→CORAL, amount_in=1e6) - [x] Legacy pool-only opt-out: `GET /route/solve?pool_only=true&amount_in=…` returns `hybrid: null` (`indexer_pool_lcd`) - [x] Hybrid swap columns indexed: DB swap_event id 461 has `pool_return_amount`, `book_return_amount`, `limit_book_offer_consumed`; `/pairs/{addr}/trades` exposes leg columns - [x] `/cg/tickers` and `/cmc/summary` include `cl8y_extensions.consolidated: true` with hybrid/pool-only 24h counts - [x] `/cg/historical_trades` and `/cmc/trades/{pair}` expose `pool_leg_volume` / `book_leg_volume` - [x] Standard volume fields remain consolidated totals (no double-count) - [x] Docs cross-links present (`integrators.md`, `terraport.md`, `CG_CMC_COMPLIANCE.md`, `indexer-invariants.md`, ADR 0001, `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md`) ### Bug fix (merged @ 0e5f020) `route_solve_hybrid_optimize_degraded_falls_back_to_pool_only` was failing: when all `HybridSimulation` grid queries returned HTTP 500, LCD endpoint cooldown blocked the pool `simulation` fallback, causing `/best` to 502. Fixed by: 1. Falling back directly to pool `simulation` when hybrid grid fails (`hybrid_route_opt.rs`) 2. Not cooling down LCD endpoints on contract-level 4xx/500 responses (`lcd/mod.rs`) ### Tests ``` cargo test --test api_route_solve -- --test-threads=1 # 14 passed cargo test --test api_consolidated_reporting -- --test-threads=1 # 3 passed cargo test --test swap_events_hybrid_columns -- --test-threads=1 # 1 passed ``` Cursor browser MCP was not available in this environment; verification was API + test driven (backend-only scope).

PlasticDigits (Migrated from gitlab.com) closed this issue

2026-05-27 06:35:29 +00:00

PlasticDigits commented

2026-05-29 03:09:57 +00:00

(Migrated from gitlab.com)

mentioned in issue #209