Review: max_spread / belief_price semantics for hybrid total return #81

New issue

Closed

opened 2026-04-09 03:24:16 +00:00 by PlasticDigits · 6 comments

PlasticDigits commented

2026-04-09 03:24:16 +00:00

(Migrated from gitlab.com)

Type

security-hardening + product needs-design

Evidence

SECURITY_REVIEW.md SC-08; pair/src/contract.rs spread assertion uses pool leg inputs

Dependencies

Product sign-off; may follow #64

Acceptance criteria

Documented expected behavior; tests if code changes

Epic

#60

## Type **security-hardening** + product **needs-design** ## Evidence - `SECURITY_REVIEW.md` SC-08; `pair/src/contract.rs` spread assertion uses pool leg inputs ## Dependencies - Product sign-off; may follow #64 ## Acceptance criteria - [ ] Documented expected behavior; tests if code changes ## Epic #60

PlasticDigits commented

2026-04-09 03:24:17 +00:00

(Migrated from gitlab.com)

marked this issue as related to #60

PlasticDigits commented

2026-04-09 03:24:17 +00:00

(Migrated from gitlab.com)

marked this issue as related to #56

PlasticDigits commented

2026-04-13 11:35:32 +00:00

(Migrated from gitlab.com)

@brouie Please verify: hybrid slippage behavior is documented in docs/integrators.md and SC-08 in SECURITY_REVIEW.md matches assert_max_spread (no-belief: pool spread vs pool_gross+book_net; belief: actual_return includes pool commission). Regression tests in cl8y-dex-pair max_spread_tests. Run: cargo test -p cl8y-dex-pair

Brouie commented

2026-04-20 06:46:54 +00:00

(Migrated from gitlab.com)

@PlasticDigits Verified on current main. Acceptance criteria:

Documented expected behavior; tests if code changes.

Docs: docs/integrators.md line 30 section 'Slippage: max_spread and belief_price (hybrid)' clearly describes both paths:

Without belief_price: ratio numerator is pool leg constant-product spread (capped by pool gross), denominator is pool_net + pool_commission + book_return_net (book leg scales denominator even though spread numerator is pool-only)
With belief_price: expected output is offer_amount / belief_price, actual is book_return_net + pool_net_to_receiver + pool_commission (pool commission counts on actual side)

Tests: ran cargo test -p cl8y-dex-pair max_spread -- 5 passed, 0 failed:

max_spread_belief_counts_pool_commission_in_actual_return
max_spread_no_belief_denominator_includes_book_net
max_spread_half_rejects_at_full_slippage_metric
max_spread_one_allows_capped_ratio_when_raw_spread_exceeds_gross
spot_linear_spread_matches_floor_ideal_minus_gross

Test names directly mirror the docs semantics (belief path counts pool commission in actual, no-belief denominator includes book net, etc). SC-08 behavior locked in with regression coverage. Closing.

@PlasticDigits Verified on current main. Acceptance criteria: - [x] Documented expected behavior; tests if code changes. **Docs:** docs/integrators.md line 30 section 'Slippage: max_spread and belief_price (hybrid)' clearly describes both paths: - Without belief_price: ratio numerator is pool leg constant-product spread (capped by pool gross), denominator is pool_net + pool_commission + book_return_net (book leg scales denominator even though spread numerator is pool-only) - With belief_price: expected output is offer_amount / belief_price, actual is book_return_net + pool_net_to_receiver + pool_commission (pool commission counts on actual side) **Tests:** ran cargo test -p cl8y-dex-pair max_spread -- **5 passed, 0 failed**: - max_spread_belief_counts_pool_commission_in_actual_return - max_spread_no_belief_denominator_includes_book_net - max_spread_half_rejects_at_full_slippage_metric - max_spread_one_allows_capped_ratio_when_raw_spread_exceeds_gross - spot_linear_spread_matches_floor_ideal_minus_gross Test names directly mirror the docs semantics (belief path counts pool commission in actual, no-belief denominator includes book net, etc). SC-08 behavior locked in with regression coverage. Closing.

Brouie (Migrated from gitlab.com) closed this issue

2026-04-20 06:46:58 +00:00

Brouie commented

2026-04-20 07:26:43 +00:00

(Migrated from gitlab.com)

mentioned in issue #100