docs: verify and document GitLab #273 hybrid no-belief slippage floor #801

2026-06-05T12:31:06Z

PlasticDigits commented

2026-06-05 12:31:06 +00:00

(Migrated from gitlab.com)

Summary

GitLab #273 — hybrid book-leg slippage in the no-belief max_spread path.

The security fix is already on main (commits 58092d1 #273 book shortfall, 6cf3d7a #307 material pool leg, e1ae059 frontend preflight). This MR only syncs integrator/UX docs and the agent skill test list with the merged implementation.

Acceptance criteria

Criterion	Verification	Result
No-belief hybrid with book leg filling materially worse than pool reference is rejected	`cargo test hybrid_no_belief_book_far_below_pool_rejected`; `dex-common` `no_belief_rejects_book_far_below_pool_net_rate`	PASS (on `main`)
No-belief metric reflects book-leg degradation	`max_spread.rs` `book_shortfall` term; unit tests above	PASS (on `main`)
Router hybrid hops bounded per-hop without `minimum_receive`	Router `validate_declared_hybrid_pool_leg_for_no_belief`; pair `assert_max_spread` per hop	PASS (on `main`)

Verification (third parties)

cd smartcontracts && cargo test -p dex-common max_spread
cd smartcontracts && cargo test -p cl8y-dex-tests hybrid_no_belief
make test-contracts
cd frontend-dapp && npm test -- src/utils/swapMaxSpread.test.ts

Doc changes (this MR)

docs/integrators.md — slippage section matches L9 / #273 / #307
docs/swap-max-spread-ux.md — on-chain + preflight invariants
skills/AGENTS_MAX_SPREAD_HYBRID.md — integration test names

Follow-up (out of scope)

Pure-book hybrid (declared_pool_input = 0) still requires belief_price or router minimum_receive — tracked separately (directions 2 & 3 in issue discussion).

Note

Low Risk
Markdown-only; no runtime, contract, or frontend behavior changes.

Overview
Documentation-only PR that brings integrator, swap UX, and agent playbooks in line with on-chain behavior already on main (no contract or frontend code in this diff).

docs/integrators.md and docs/swap-max-spread-ux.md now describe the no-belief_price hybrid check as (spread_cmp + book_shortfall) / total_gross_out instead of pool-only spread_cmp / total_gross_out, including book_shortfall vs the pool’s realized net rate (#273). They also document the material declared pool leg gate when both hybrid legs are present: declared_pool_input ≥ 10% of offer (min 1 unit) and pool_net_return > 0, with early reject on pair/router (#307), and note that pure-book (declared_pool_input = 0) and belief_price paths skip the #307 floor.

docs/swap-max-spread-ux.md adds cross-links to AGENTS_MAX_SPREAD_HYBRID.md, #273, and #307. skills/AGENTS_MAX_SPREAD_HYBRID.md lists the integration tests hybrid_no_belief_book_far_below_pool_rejected and hybrid_no_belief_dust_pool_leg_rejected as regression anchors for those rules.

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

## Summary GitLab [#273](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/273) — hybrid book-leg slippage in the no-belief `max_spread` path. The **security fix is already on `main`** (commits `58092d1` #273 book shortfall, `6cf3d7a` #307 material pool leg, `e1ae059` frontend preflight). This MR only syncs integrator/UX docs and the agent skill test list with the merged implementation. ## Acceptance criteria | Criterion | Verification | Result | |-----------|--------------|--------| | No-belief hybrid with book leg filling materially worse than pool reference is rejected | `cargo test hybrid_no_belief_book_far_below_pool_rejected`; `dex-common` `no_belief_rejects_book_far_below_pool_net_rate` | **PASS** (on `main`) | | No-belief metric reflects book-leg degradation | `max_spread.rs` `book_shortfall` term; unit tests above | **PASS** (on `main`) | | Router hybrid hops bounded per-hop without `minimum_receive` | Router `validate_declared_hybrid_pool_leg_for_no_belief`; pair `assert_max_spread` per hop | **PASS** (on `main`) | ## Verification (third parties) ```bash cd smartcontracts && cargo test -p dex-common max_spread cd smartcontracts && cargo test -p cl8y-dex-tests hybrid_no_belief make test-contracts cd frontend-dapp && npm test -- src/utils/swapMaxSpread.test.ts ``` ## Doc changes (this MR) - `docs/integrators.md` — slippage section matches L9 / #273 / #307 - `docs/swap-max-spread-ux.md` — on-chain + preflight invariants - `skills/AGENTS_MAX_SPREAD_HYBRID.md` — integration test names ## Follow-up (out of scope) Pure-book hybrid (`declared_pool_input = 0`) still requires `belief_price` or router `minimum_receive` — tracked separately (directions 2 & 3 in issue discussion).  --- > [!NOTE] > **Low Risk** > Markdown-only; no runtime, contract, or frontend behavior changes. > > **Overview** > Documentation-only PR that brings integrator, swap UX, and agent playbooks in line with **on-chain behavior already on main** (no contract or frontend code in this diff). > > **`docs/integrators.md`** and **`docs/swap-max-spread-ux.md`** now describe the no-`belief_price` hybrid check as **`(spread_cmp + book_shortfall) / total_gross_out`** instead of pool-only **`spread_cmp / total_gross_out`**, including **`book_shortfall`** vs the pool’s realized net rate ([#273](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/273)). They also document the **material declared pool leg** gate when both hybrid legs are present: **`declared_pool_input ≥ 10%` of offer** (min 1 unit) and **`pool_net_return > 0`**, with early reject on pair/router ([#307](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/307)), and note that **pure-book** (`declared_pool_input = 0`) and **`belief_price`** paths skip the #307 floor. > > **`docs/swap-max-spread-ux.md`** adds cross-links to **`AGENTS_MAX_SPREAD_HYBRID.md`**, #273, and #307. **`skills/AGENTS_MAX_SPREAD_HYBRID.md`** lists the integration tests **`hybrid_no_belief_book_far_below_pool_rejected`** and **`hybrid_no_belief_dust_pool_leg_rejected`** as regression anchors for those rules. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 845ea37c1980db451537e47aece1ead056d0aceb. 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 12:31:13 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 12:31:16 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 12:31:16 +00:00

(Migrated from gitlab.com)

mentioned in issue #273

ghost1 commented

2026-06-05 12:31:19 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 12:31:57 +00:00

(Migrated from gitlab.com)

Security review

Commit reviewed: 845ea37c1980db451537e47aece1ead056d0aceb

Scope: Added/modified lines in this MR only — docs/integrators.md, docs/swap-max-spread-ux.md, skills/AGENTS_MAX_SPREAD_HYBRID.md (markdown documentation sync for GitLab #273 / #307 hybrid no-belief slippage floor).

Method: Diff review for injection, authn/authz, secret leakage, SSRF/XSS, unsafe deserialization, and supply-chain changes. Cross-checked documented invariants against canonical implementation on main (dex_common::max_spread, pair/router early validation, frontend swapMaxSpread.ts preflight).

Outcome: FINDINGS: 0 medium+

This MR introduces no executable code, dependencies, or configuration. Changes describe existing on-chain and frontend slippage controls (book-leg shortfall numerator #273, material declared pool leg gate #307, pure-book / belief_price exceptions) that are already merged on main. No attacker-controlled input paths, permission boundaries, or credential exposure in the diff.

Inline threads: none (no medium+ findings to anchor).

Automated security review (Cursor Cloud Agent).

## Security review **Commit reviewed:** `845ea37c1980db451537e47aece1ead056d0aceb` **Scope:** Added/modified lines in this MR only — `docs/integrators.md`, `docs/swap-max-spread-ux.md`, `skills/AGENTS_MAX_SPREAD_HYBRID.md` (markdown documentation sync for GitLab #273 / #307 hybrid no-belief slippage floor). **Method:** Diff review for injection, authn/authz, secret leakage, SSRF/XSS, unsafe deserialization, and supply-chain changes. Cross-checked documented invariants against canonical implementation on `main` (`dex_common::max_spread`, pair/router early validation, frontend `swapMaxSpread.ts` preflight). **Outcome:** `FINDINGS: 0` medium+ This MR introduces no executable code, dependencies, or configuration. Changes describe existing on-chain and frontend slippage controls (book-leg shortfall numerator #273, material declared pool leg gate #307, pure-book / `belief_price` exceptions) that are already merged on `main`. No attacker-controlled input paths, permission boundaries, or credential exposure in the diff. **Inline threads:** none (no medium+ findings to anchor). --- *Automated security review (Cursor Cloud Agent).*

PlasticDigits commented

2026-06-05 12:33:36 +00:00

(Migrated from gitlab.com)

mentioned in commit b9121d8392

mentioned in commit b9121d839230a62ecb449988372067d5b9a61bd5