Feat introduce route optimizer for swaps and lp 36

[omolobamoyinoluwa-max]

his implementation introduces an intelligent route optimizer for Stellar AgentKit that addresses the critical problem of inefficient trades by providing multi-DEX routing with best price discovery. The route optimizer queries liquidity pools from both Horizon and Soroban AMMs, compares rates across multiple sources, and selects optimal paths using four different strategies (best-route, direct, minimal-hops, and split) to maximize output while minimizing slippage and transaction costs. With features like multi-hop routing, real-time pool data caching, price impact calculation, and confidence scoring, this enhancement transforms Stellar AgentKit from a basic execution SDK into a sophisticated routing platform that enables professional-grade trading applications with optimal pricing, reduced slippage, and comprehensive route analytics, all while maintaining backward compatibility and a simple, intuitive API surface.

Closes #36

---

Summary by cubic

Introduces an intelligent route optimizer for swaps and LP with multi-DEX, multi-hop best-price execution, plus built-in transaction analytics. Adds agent.swapOptimized without breaking the existing swap API, improves pricing, reduces slippage, and hardens reliability. Addresses #36.

• New Features

  • Route optimizer: multi-DEX (Horizon + Soroban AMMs), multi-hop, strategies (best-route, direct, minimal-hops, split), price impact + confidence scoring, and pool caching; exposed via AgentClient.swapOptimized with docs (docs/route-optimizer.md) and examples; supports both input-amount and destAmount flows.
  • Transaction analytics: automatic tracking for swaps/bridges/LP with persistent storage at ~/.stellartools/metrics-{network}.json; agent.metrics.summary() for volume, success rate, slippage, and execution time; filtering/export; tests.

• Bug Fixes

  • Restored backward compatibility by keeping swap unchanged and adding swapOptimized.
  • Routing engine: fixed BFS pruning, implemented real swap execution, completed split strategy, improved Soroban pool discovery, and refreshed confidence scoring based on current price impact.
  • Transactions: preserved FeeBumpTransaction envelopes and fixed memo override conditions.
  • Bridge: added ALLOW_MAINNET_BRIDGE runtime guard and stronger runtime env validation with clear errors.
  • Metrics: validated numeric fields to prevent NaN, fixed constructor instantiation order, and overridden homedir during tests to isolate files; improved persistence/timing stability.
  • Resolved TypeScript issues with stricter types, guards, and reliable IDE/CI behavior.

^{Written for commit 6f15a38. Summary will update on new commits.}

[cubic-dev-ai]

19 issues found across 17 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:117">
P2: README documents conflicting swap APIs: it presents route optimization on `agent.swap()` but later defines route-aware swaps as `agent.dex.*` and `agent.swap()` as legacy.</violation>
</file>

<file name="tools/bridge.ts">

<violation number="1" location="tools/bridge.ts:110">
P1: Removed `ALLOW_MAINNET_BRIDGE` runtime guard allows mainnet bridge execution without explicit environment opt-in.</violation>
</file>

<file name="tests/unit/metrics.test.ts">

<violation number="1" location="tests/unit/metrics.test.ts:216">
P2: MetricsCollector is instantiated before the test redirects storage to the fixture, so this test can touch the user's real metrics file.</violation>
</file>

<file name="PR_DESCRIPTION.md">

<violation number="1" location="PR_DESCRIPTION.md:173">
P2: PR description mixes a separate metrics/analytics feature writeup into a route-optimizer PR, creating incorrect and misleading scope documentation.</violation>
</file>

<file name="docs/route-optimizer.md">

<violation number="1" location="docs/route-optimizer.md:19">
P2: `split` strategy documentation is internally inconsistent (future enhancement vs currently supported usage), which can mislead integrators.</violation>

<violation number="2" location="docs/route-optimizer.md:143">
P2: Documentation uses an internal deep import path for `RouteOptimizer`, which is not a stable/public package entrypoint and can break consumer module resolution.</violation>
</file>

<file name="lib/metrics.ts">

<violation number="1" location="lib/metrics.ts:192">
P2: Unvalidated `parseFloat` results can introduce `NaN` into summary averages, causing poisoned analytics output.</violation>
</file>

<file name="CONTRIBUTION_DETAILS.md">

<violation number="1" location="CONTRIBUTION_DETAILS.md:4">
P2: Contribution details document content does not match this PR’s route-optimizer scope, suggesting stale/incorrect metadata was committed.</violation>
</file>

<file name="utils/buildTransaction.ts">

<violation number="1" location="utils/buildTransaction.ts:132">
P1: `buildTransactionFromXDR` strips fee-bump envelopes by returning `innerTransaction`, which can alter externally provided fee-bumped XDR before signing/submission.</violation>

<violation number="2" location="utils/buildTransaction.ts:141">
P2: Memo override condition is incorrect: checking `!baseTransaction.memo` prevents applying `config.memo` because empty memos are represented as truthy `Memo.none()` objects.</violation>
</file>

<file name="agent.ts">

<violation number="1" location="agent.ts:169">
P2: Bridge metrics status is always recorded as success even when bridge result is still pending.</violation>

<violation number="2" location="agent.ts:208">
P1: `swap` was repurposed to a different parameter contract, creating a backward-incompatible public API break for existing consumers.</violation>

<violation number="3" location="agent.ts:333">
P2: LP deposit metrics use `Number(...)` on string token amounts, which can lose precision and record inaccurate volume.</violation>
</file>

<file name="lib/routeOptimizer.ts">

<violation number="1" location="lib/routeOptimizer.ts:119">
P2: `split` routing strategy is exposed but not implemented; it ignores `splitCount` and falls back to single-route selection.</violation>

<violation number="2" location="lib/routeOptimizer.ts:211">
P2: Soroban pool discovery is stubbed out, so enabling `rpcUrl` does not actually include Soroban liquidity in route optimization.</violation>

<violation number="3" location="lib/routeOptimizer.ts:315">
P2: Multi-hop BFS incorrectly prunes valid alternative routes by marking assets globally as visited instead of tracking full traversal state.</violation>

<violation number="4" location="lib/routeOptimizer.ts:398">
P1: Swap execution path returns mocked success data instead of executing a real transaction.</violation>

<violation number="5" location="lib/routeOptimizer.ts:417">
P2: Confidence scoring uses stale `route.priceImpact` instead of the newly computed price impact, causing misleading route reliability scores.</violation>

<violation number="6" location="lib/routeOptimizer.ts:520">
P2: `destAmount` is part of `OptimizedSwapParams` but is never used in route computation; the optimizer always derives input from `sendAmount`, causing dest-amount-only requests to miscompute routes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}