docs: verify #289 expired head-clog mitigations #795

Merged

PlasticDigits merged 1 commit from cursor/gitlab-issue-verification-18b8 into main

2026-06-05 11:04:14 +00:00

PlasticDigits commented

2026-06-05 11:03:23 +00:00

(Migrated from gitlab.com)

Summary

Verification QA for https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/289 — documents accepted mitigations for low-severity hybrid expired head-clog griefing (no matcher change).

Takers: same-side book_start_hint past expired prefix (L17, #272)
Keepers: resumable CleanLimitBook with MAX_CLEAN_SCAN_STEPS + resume_cursor (#274)
Future-only: optional per-order placement fee; park-cap re-benchmark on wasm redeploy

Verification checklist

Acceptance item	Result	Command / output
Head clog cannot block takers in small # of swaps (operational)	PASS	`cargo test -p cl8y-dex-tests hybrid_same_side_book_start_hint_still_matches`; `hybrid_walk_three_expired_bids_all_parked_then_fills_live_bid`
Head-only taker degrades (expected)	documented	`cargo test -p cl8y-dex-tests hybrid_walk_scan_steps_cap_bounds_expired_prefix_and_spills_to_pool`
Bounded clean traversal	PASS	`cargo test -p cl8y-dex-tests clean_limit_book_scan_cap_resume_reaches_tail`
Scan cap unit tests	PASS	`cargo test -p cl8y-dex-pair match_bids_scan_steps_cap`

Docs/guardrails only — issue stays open until MR merges.

Related: #272, #274, #309

Note

Low Risk
Markdown and agent playbook updates only; no smart contract, frontend, or indexer code changes.

Overview
Documentation-only QA for GitLab #289: records accepted mitigations for low-severity expired head-clog on hybrid book walks (no matcher/wasm change in this PR).

docs/contracts-security-audit.md: L5 now notes head-only walks can exhaust MAX_SCAN_STEPS on deep expired prefixes and points to L17 + L15 (#274). L17 adds integrator guidance: same-side book_start_hint past the expired prefix. L15 expands CleanLimitBook docs with optional max_steps, resume_cursor, and the clean_limit_book_scan_cap_resume_reaches_tail test reference.

docs/limit-orders.md: CleanLimitBook / permissionless clean sections document max_steps, scan_capped, resume_cursor, and resubmit flow (#274). New Head-clog griefing under Expiry describes the attack, taker/keeper mitigations, and future-only ideas (placement fee, park-cap re-benchmark #309).

Agent skills: AGENTS_BOOK_MATCH_HINT_SECURITY.md adds an #289 section (hint past clog; dApp/indexer may still emit null hints). AGENTS_TERRACLASSIC_GAS.md rule 16 cross-links #289 with L17 and CleanLimitBook resume.

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

## Summary Verification QA for https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/289 — documents accepted mitigations for low-severity hybrid **expired head-clog** griefing (no matcher change). - **Takers:** same-side `book_start_hint` past expired prefix (**L17**, #272) - **Keepers:** resumable `CleanLimitBook` with `MAX_CLEAN_SCAN_STEPS` + `resume_cursor` (#274) - **Future-only:** optional per-order placement fee; park-cap re-benchmark on wasm redeploy ## Verification checklist | Acceptance item | Result | Command / output | |-----------------|--------|------------------| | Head clog cannot block takers in small # of swaps (operational) | PASS | `cargo test -p cl8y-dex-tests hybrid_same_side_book_start_hint_still_matches`; `hybrid_walk_three_expired_bids_all_parked_then_fills_live_bid` | | Head-only taker degrades (expected) | documented | `cargo test -p cl8y-dex-tests hybrid_walk_scan_steps_cap_bounds_expired_prefix_and_spills_to_pool` | | Bounded clean traversal | PASS | `cargo test -p cl8y-dex-tests clean_limit_book_scan_cap_resume_reaches_tail` | | Scan cap unit tests | PASS | `cargo test -p cl8y-dex-pair match_bids_scan_steps_cap` | Docs/guardrails only — issue stays open until MR merges. Related: #272, #274, #309  --- > [!NOTE] > **Low Risk** > Markdown and agent playbook updates only; no smart contract, frontend, or indexer code changes. > > **Overview** > **Documentation-only** QA for GitLab **#289**: records **accepted mitigations** for low-severity **expired head-clog** on hybrid book walks (no matcher/wasm change in this PR). > > **`docs/contracts-security-audit.md`:** **L5** now notes head-only walks can exhaust **`MAX_SCAN_STEPS`** on deep expired prefixes and points to **L17** + **L15** (#274). **L17** adds integrator guidance: same-side **`book_start_hint`** past the expired prefix. **L15** expands **`CleanLimitBook`** docs with optional **`max_steps`**, **`resume_cursor`**, and the **`clean_limit_book_scan_cap_resume_reaches_tail`** test reference. > > **`docs/limit-orders.md`:** **`CleanLimitBook`** / permissionless clean sections document **`max_steps`**, **`scan_capped`**, **`resume_cursor`**, and resubmit flow (#274). New **Head-clog griefing** under **Expiry** describes the attack, taker/keeper mitigations, and future-only ideas (placement fee, park-cap re-benchmark #309). > > **Agent skills:** **`AGENTS_BOOK_MATCH_HINT_SECURITY.md`** adds an **#289** section (hint past clog; dApp/indexer may still emit null hints). **`AGENTS_TERRACLASSIC_GAS.md`** rule **16** cross-links **#289** with **L17** and **`CleanLimitBook`** resume. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 4c4c26846bff977763c2d66c787473c6627bbfc5. 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 11:03:30 +00:00

(Migrated from gitlab.com)

changed the description

ghost1 commented

2026-06-05 11:03:39 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 11:04:15 +00:00

(Migrated from gitlab.com)

mentioned in commit c179fa92fb

mentioned in commit c179fa92fb7b003c69f1b9567eb094bf45e11373

PlasticDigits (Migrated from gitlab.com) merged commit c179fa92fb into main

2026-06-05 11:04:15 +00:00

PlasticDigits commented

2026-06-05 11:05:13 +00:00

(Migrated from gitlab.com)

Security review (automated)

Commit reviewed: 4c4c26846bff977763c2d66c787473c6627bbfc5 (docs: verify GitLab #289 expired head-clog mitigations)

Scope: Documentation and agent-playbook updates only (docs/contracts-security-audit.md, docs/limit-orders.md, skills/AGENTS_BOOK_MATCH_HINT_SECURITY.md, skills/AGENTS_TERRACLASSIC_GAS.md). No smart contract, indexer, or frontend executable changes in this diff.

Review method: Compared added text to existing on-chain controls (resolve_match_start_hint, MAX_SCAN_STEPS / MAX_CLEAN_SCAN_STEPS, resumable CleanLimitBook attrs). Checked for secret leakage, unsafe integrator guidance, and new attack surface in the patch itself.

Outcome: FINDINGS: 0 (no medium, high, or critical issues introduced or exposed by this diff).

Notes:

The MR records low-severity hybrid expired head-clog griefing (#289) and accepted mitigations already shipped (#272 same-side book_start_hint, #274 bounded/resumable clean). That is operational documentation of pre-existing matcher behavior, not a new vulnerability or authz bypass.
Impact described is degraded book-leg fill / pool spillover or slippage revert for head-only takers — not escrow theft or permission escalation. Cross-side hint drain remains covered by invariant L17 (unchanged logic; docs cross-link only).
No inline review threads (nothing to anchor at medium+ severity).

Cursor Cloud Agent security review — webhook open

## Security review (automated) **Commit reviewed:** `4c4c26846bff977763c2d66c787473c6627bbfc5` ([docs: verify GitLab #289 expired head-clog mitigations](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/commit/4c4c26846bff977763c2d66c787473c6627bbfc5)) **Scope:** Documentation and agent-playbook updates only (`docs/contracts-security-audit.md`, `docs/limit-orders.md`, `skills/AGENTS_BOOK_MATCH_HINT_SECURITY.md`, `skills/AGENTS_TERRACLASSIC_GAS.md`). No smart contract, indexer, or frontend executable changes in this diff. **Review method:** Compared added text to existing on-chain controls (`resolve_match_start_hint`, `MAX_SCAN_STEPS` / `MAX_CLEAN_SCAN_STEPS`, resumable `CleanLimitBook` attrs). Checked for secret leakage, unsafe integrator guidance, and new attack surface in the patch itself. **Outcome:** `FINDINGS: 0` (no medium, high, or critical issues introduced or exposed by this diff). **Notes:** - The MR records **low-severity** hybrid **expired head-clog** griefing ([#289](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/289)) and **accepted mitigations** already shipped ([#272](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/272) same-side `book_start_hint`, [#274](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/274) bounded/resumable clean). That is operational documentation of pre-existing matcher behavior, not a new vulnerability or authz bypass. - Impact described is degraded book-leg fill / pool spillover or slippage revert for head-only takers — not escrow theft or permission escalation. Cross-side hint drain remains covered by invariant **L17** (unchanged logic; docs cross-link only). - No inline review threads (nothing to anchor at medium+ severity). --- *Cursor Cloud Agent security review — webhook `open`*