docs: fill↔swap linkage by swap_index for integrators (#316) #804

Merged

PlasticDigits merged 1 commit from cursor/gitlab-issue-workflow-b329 into main

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

PlasticDigits commented

2026-06-05 12:41:51 +00:00

(Migrated from gitlab.com)

Summary

Documentation follow-up for #316.

Indexer fix already merged (f1caac4). This MR adds integrator-facing fill↔swap linkage docs.

Acceptance checklist

Criterion	Verification	Result
Multi-swap same-pair fill linkage	`cargo test --test limit_fill_swap_linkage`	PASS
Single-swap txs (`swap_index` 0)	`cargo test parse_limit_order_fills_assigns_swap_index --lib`	PASS
Integration test coverage	`limit_fill_swap_linkage.rs`	PASS
Integrator doc	`integrators-hybrid-volume.md` § Fill ↔ swap linkage	PASS

Note

Low Risk
Documentation and test-command references only; no runtime or API behavior changes in this diff.

Overview
Documents how integrators should join limit_order_fills to swap_events after the #316 indexer behavior: swap_event_id is resolved by per-pair swap_index (parser walk ordinal), not by picking the earliest swap row (MIN(id) / ORDER BY id).

Adds a Fill ↔ swap linkage section in integrators-hybrid-volume.md with scenario tables (single swap with many fills, multiple swaps on the same pair in one tx, pool-only) and join guidance so per-fill leg attrs attach to the correct parent swap. Updates the agent skill with the same rule and expands the recommended cargo test list to include limit_fill_swap_linkage and parse_limit_order_fills_assigns_swap_index.

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

## Summary Documentation follow-up for [#316](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/316). Indexer fix already merged (`f1caac4`). This MR adds integrator-facing fill↔swap linkage docs. ## Acceptance checklist | Criterion | Verification | Result | |-----------|--------------|--------| | Multi-swap same-pair fill linkage | `cargo test --test limit_fill_swap_linkage` | PASS | | Single-swap txs (`swap_index` 0) | `cargo test parse_limit_order_fills_assigns_swap_index --lib` | PASS | | Integration test coverage | `limit_fill_swap_linkage.rs` | PASS | | Integrator doc | `integrators-hybrid-volume.md` § Fill ↔ swap linkage | PASS |  --- > [!NOTE] > **Low Risk** > Documentation and test-command references only; no runtime or API behavior changes in this diff. > > **Overview** > Documents how integrators should join **`limit_order_fills`** to **`swap_events`** after the #316 indexer behavior: **`swap_event_id`** is resolved by per-pair **`swap_index`** (parser walk ordinal), not by picking the earliest swap row (`MIN(id)` / `ORDER BY id`). > > Adds a **Fill ↔ swap linkage** section in `integrators-hybrid-volume.md` with scenario tables (single swap with many fills, multiple swaps on the same pair in one tx, pool-only) and join guidance so per-fill leg attrs attach to the correct parent swap. Updates the agent skill with the same rule and expands the recommended **`cargo test`** list to include **`limit_fill_swap_linkage`** and **`parse_limit_order_fills_assigns_swap_index`**. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit a121e8a7fd0ea97a86c448749d020ab8f819b00f. 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:41:58 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 12:41:59 +00:00

(Migrated from gitlab.com)

mentioned in issue #316

ghost1 commented

2026-06-05 12:42:03 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 12:42:44 +00:00

(Migrated from gitlab.com)

Security review

Commit reviewed: a121e8a7fd0ea97a86c448749d020ab8f819b00f
Scope: Documentation-only diff — docs/integrators-hybrid-volume.md (Fill ↔ swap linkage section, test reference) and skills/AGENTS_INTEGRATOR_HYBRID_VOLUME.md (skill playbook + test commands).

Outcome: FINDINGS: 0 medium+

Security review: no medium+ findings on this diff.

Analysis

Area	Result
Injection (SQL/command/template)	N/A — no executable code changed
Authn / authz	N/A — no API, indexer, or contract logic touched
Secret leakage / sensitive logging	None — docs describe public schema/join semantics only
SSRF / XSS / CSRF / path traversal	N/A — static markdown/skill files, not served as user-controlled HTML
Deserialization / dependency / supply chain	No dependency or lockfile changes
On-chain / dapp exploit surface	N/A — documents existing indexer behavior (#316); no wasm or frontend changes

Added content is integrator guidance for joining limit_order_fills.swap_event_id via per-pair swap_index. No attacker-controlled input paths or permission boundaries are introduced.

Inline threads: none (no findings to anchor).

## Security review **Commit reviewed:** `a121e8a7fd0ea97a86c448749d020ab8f819b00f` **Scope:** Documentation-only diff — `docs/integrators-hybrid-volume.md` (Fill ↔ swap linkage section, test reference) and `skills/AGENTS_INTEGRATOR_HYBRID_VOLUME.md` (skill playbook + test commands). **Outcome:** `FINDINGS: 0` medium+ Security review: **no medium+ findings** on this diff. ### Analysis | Area | Result | |------|--------| | Injection (SQL/command/template) | N/A — no executable code changed | | Authn / authz | N/A — no API, indexer, or contract logic touched | | Secret leakage / sensitive logging | None — docs describe public schema/join semantics only | | SSRF / XSS / CSRF / path traversal | N/A — static markdown/skill files, not served as user-controlled HTML | | Deserialization / dependency / supply chain | No dependency or lockfile changes | | On-chain / dapp exploit surface | N/A — documents existing indexer behavior (#316); no wasm or frontend changes | Added content is integrator guidance for joining `limit_order_fills.swap_event_id` via per-pair `swap_index`. No attacker-controlled input paths or permission boundaries are introduced. **Inline threads:** none (no findings to anchor).