Skip to content

perf(backend): make analytics pagination stable and bounded for large vault histories #69

Description

@arisu6804

Problem

Offset pagination over growing transaction histories becomes slow and can produce duplicates or gaps while new records arrive.

Objective

Deliver a production-quality improvement to analytics history queries and API pagination that creates measurable value for correctness, security, reliability, performance, or maintainability.

Implementation scope

  • Replace unbounded offsets with a documented cursor or stable snapshot strategy.
  • Enforce maximum page size and apply indexed filters for vault, actor, and time range.
  • Return deterministic ordering and cursor metadata that survives normal inserts.

Acceptance criteria

  • Repeated pages contain no duplicates or gaps under concurrent inserts.
  • Requests above the limit are rejected or capped explicitly.
  • Query plans and a representative benchmark demonstrate bounded behavior.

Required validation

  • Pagination contract tests, concurrent-insert integration tests, and a large-fixture performance check.
  • Existing tests and CI remain passing.
  • Add regression coverage for the original failure mode.
  • Do not weaken, delete, or skip unrelated tests to obtain a green build.

PR quality bar

  • Keep the PR focused on this issue and explain design tradeoffs.
  • Include test evidence, compatibility impact, and migration or rollout notes where relevant.
  • Avoid typo-only, documentation-only, cosmetic-only, or unrelated refactor submissions.

Out of scope

  • Broad rewrites not required by the acceptance criteria.
  • Changes to unrelated services, contracts, or user flows.

Metadata

Metadata

Assignees

No one assigned

    Labels

    GRANTFOX OSSOpen-source issue tracked by GrantFoxMAYBE REWARDEDThis issue may carry a rewardThird CampaignThird Campaign contributionenhancementNew feature or requestpriority:mediumMedium implementation priority

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions