Skip to content

feat: add per-pool slippage, utilization, and execution risk to /simulate response#50

Open
0xcentur1on wants to merge 14 commits intomasterfrom
feat/per-pool-slippage
Open

feat: add per-pool slippage, utilization, and execution risk to /simulate response#50
0xcentur1on wants to merge 14 commits intomasterfrom
feat/per-pool-slippage

Conversation

@0xcentur1on
Copy link
Copy Markdown

@0xcentur1on 0xcentur1on commented Mar 9, 2026

Summary

Enriches each pool entry in the /simulate response with three new fields that give callers a complete, server-side view of execution risk before sending a transaction on-chain:

  • slippage_bps — per-ladder-step price impact in basis points (positive = cost to trader)
  • pool_utilization_bps — fraction of the pool's reported max_in consumed by the largest requested amount (10 000 = 100 %)
  • execution_risk — composite risk score and qualitative label (low / medium / high / very_high / unknown) derived from slippage, utilization, curve convexity, and ladder completeness

A new pool_type field (blue_chip | stablecoin | volatile, defaults to volatile) on the request lets callers pass pool-class context so the service can apply pool-type-aware weights when computing the risk score.

Changed files

File What changed
src/models/messages.rs Added PoolType enum, pool_type on AmountOutRequest; added slippage_bps, pool_utilization_bps, execution_risk on AmountOutResponse; added ExecutionRisk struct and RiskLevel enum; added SkippedPrecheck pool outcome kind
src/services/quotes.rs Implemented compute_slippage_bps, compute_pool_utilization_bps, and compute_execution_risk (pool-type-aware weights); extended PoolQuoteResult with spot_price and max_in; wires all three new fields into response construction
src/handlers/quote.rs Updated SkippedPrecheck arm
src/sim_analysis/mod.rs Code cleanup
docs/slippage.md New — explains the per-step slippage calculation strategy
docs/pool-execution-risk.md New — documents the risk score formula, weights, and risk-level thresholds
docs/tycho-simulation-library.md New — reference notes on the Tycho simulation library API used here
scripts/start_server.sh Optimises binary selection for local dev environments
.gitignore Added Cargo temp file patterns

Risk score formula

risk_score = w1 × slippage_last_bps
           + w2 × utilization_bps
           + w3 × convexity_ratio   (slippage_last / slippage_first)
           + w4 × partial_ladder × 10_000

Weights differ by pool type (blue-chip pools apply tighter slippage tolerance; stablecoin pools penalise utilization more heavily). Block-lag staleness is excluded from the server-side score — callers should add that penalty using block_number vs. the current chain head.

Risk level Score range Interpretation
low < 200 Deep pool; minimal sensitivity to concurrent activity
medium 200 – 499 Moderate sensitivity; suitable for most orders
high 500 – 999 Pool state sensitive to competing routing
very_high ≥ 1 000 Prefer splitting across multiple pools
unknown Insufficient signal (all slippage null and no utilization)

Test plan

  • cargo test passes (216 tests: 182 unit + 32 integration + 2 main)
  • slippage_bps, pool_utilization_bps, and execution_risk appear in /simulate pool responses
  • execution_risk is omitted from the response when insufficient signal is available
  • Backward-compatible: pool_type defaults to volatile; new fields skip serialisation when absent

Closes #45

0xcentur1on and others added 2 commits March 6, 2026 11:48
…esponse

Each AmountOutResponse now includes:
- slippage_bps: per-ladder-step slippage in basis points, computed from the
  pool's spot_price() (marginal rate) vs the actual amount_out/amount_in ratio.
- pool_utilization_bps: fraction of the pool's get_limits() max_in consumed by
  the largest requested amount, in basis points (10_000 = 100%).

Inside simulate_pool() one spot_price() call is made per pool after the ladder
completes. spot_price and max_in are threaded through PoolQuoteResult and the
computation is done in get_amounts_out() before building AmountOutResponse.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@0xcentur1on 0xcentur1on requested a review from 0xdecr1pto March 9, 2026 11:35
Compute a composite execution-risk score for each pool returned by
/simulate, derived from slippage (price sensitivity), pool utilization
(capacity pressure), bonding curve convexity, and partial-ladder
detection. The score and a qualitative label (low/medium/high/very_high/
unknown) are surfaced as execution_risk on each AmountOutResponse.

Block-lag staleness is intentionally excluded from the server-side score;
clients add that penalty using block_number vs. the current chain head.

Adds 14 new unit tests covering score thresholds, the partial-ladder
penalty, convexity amplification, division-by-zero guards, and
serialization of the new types.
- Add pool_type: PoolType::Volatile to all AmountOutRequest initializers in
  sim_analysis/mod.rs (encode-hop-1, encode-hop-2, simulate_request)
- Add pool_type: PoolType::Volatile to the make_amount_out_request test
  helper in services/quotes.rs
- Import PoolType in sim_analysis/mod.rs and at the top level of quotes.rs
- Fix compute_execution_risk: remove incomplete match pool_type block left
  from partial feature work, lift weight constants back to function scope,
  and pass Some(self.request.pool_type) at the production call site
- Add None as the 4th argument to all compute_execution_risk test call sites
- All 182 unit tests pass
- Differentiate risk score weights by PoolType:
  - Stablecoin: higher utilization weight (0.55) to reflect peg sensitivity
  - BlueChip: balanced utilization weight (0.45) for deep-liquidity pools
  - Volatile (default): original weights unchanged (slippage 0.35, utilization 0.35)
- Rename _pool_type to pool_type now that the parameter is fully consumed
- Fix missing pool_type field in integration test AmountOutRequest fixture
- Minor formatting cleanup in quotes.rs import block and requested_max_in chain
@0xcentur1on 0xcentur1on changed the title feat: add per-pool per-amount slippage and utilization to /simulate response feat: add per-pool slippage, utilization, and execution risk to /simulate response Mar 25, 2026
@0xcentur1on 0xcentur1on self-assigned this Mar 25, 2026
- stablecoin: w1 0.25→0.10, w2 0.55→0.70 (utilization is dominant signal)
- blue_chip:  w1 0.25→0.35, w2 0.45→0.55 (both signals meaningful)
- volatile:   w1 0.35→0.45 (slippage is primary risk indicator)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add per pool/amount slippage calculation

1 participant