feat(minibf): implement /pools/retired endpoint

[michalrus]

Resolves #1097.

Implementation

List the pools that already retired. The scan reuses the pools/extended iteration over PoolState. It keeps the pools whose live snapshot has is_retired set, and reports retiring_epoch as the epoch.

Testing

The test that covers this endpoint is defined in:

• https://github.com/blockfrost/blockfrost-tests/blob/38af1d3ee6ecbb17f67b2c3aee9738cf7cb287f1/src/fixtures/preview/pools/retired.ts.

Further work

• The endpoint sorts by retirement epoch.
• For pools that retire in the same epoch, it breaks the tie by register_slot.
• Blockfrost breaks the tie by the retirement announcement transaction, which our ledger model does not store.

The two orders differ for one pair of pools in epoch 185, so two Preview fixtures of blockfrost-tests still fail.

A separate issue will track the fix (add retiring_slot to PoolState). That fix changes the CBOR encoding of the PoolState entity, so it will require a resync:

• minibf: pools retired/retiring order differs from Blockfrost for pools with the same epoch #1135

Summary by CodeRabbit

• New Features

  • Added an endpoint for retrieving retired pools.
  • Results can be filtered, sorted by retirement details, and paginated.
  • Invalid pagination parameters and service errors now return appropriate responses.

• Tests

  • Added coverage for empty results, retired-pool filtering, ordering, pagination, invalid parameters, and internal errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4939e292-6ac8-41b6-82ef-af65e5ca99fe

📥 Commits

Reviewing files that changed from the base of the PR and between 81f7ba7 and a2eb0e8.

📒 Files selected for processing (2)

• crates/minibf/src/lib.rs
• crates/minibf/src/routes/pools.rs

Included review availability: Your plan includes up to 2 reviews per rolling hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The minibf service adds GET /pools/retired. It filters and orders retired pools, supports pagination, maps results to Blockfrost response data, and adds endpoint tests.

Changes

Retired pools endpoint

Layer / File(s)	Summary
Retired-pool selection rules crates/minibf/src/routes/pools.rs	Filters retired pools, applies deterministic sorting, supports order direction, and paginates results.
Endpoint wiring and response mapping crates/minibf/src/lib.rs, crates/minibf/src/routes/pools.rs	Registers GET /pools/retired. The handler loads pool states, selects retired pools, and returns pool identifiers with retirement epochs.
Endpoint validation coverage crates/minibf/src/routes/pools.rs	Tests filtering, ordering, pagination, empty results, invalid parameters, and state-store failures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to a2eb0

This is a localized endpoint addition with no actionable merge-blocking risk remaining; merge after the normal build, lint, and test checks pass.

Suggested reviewers: scarmuega, vladimirvolek, slowbackspace

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant all_retired
  participant Facade
  participant select_retired_pools
  Client->>all_retired: GET /pools/retired with pagination
  all_retired->>Facade: Load pool states
  Facade-->>all_retired: Return pool states or an error
  all_retired->>select_retired_pools: Filter and paginate pool states
  select_retired_pools-->>all_retired: Return ordered retired pools
  all_retired-->>Client: Return JSON results or an internal error

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the /pools/retired endpoint, filter retired pools, and add coverage required by [#1097].
Out of Scope Changes check	✅ Passed	The route, retired-pool selection, pagination, ordering, and tests are directly related to [#1097].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: implementing the /pools/retired endpoint in minibf.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/minibf-pools-retired

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR adds Blockfrost-compatible support in the dolos-minibf service for listing already-retired stake pools via a new /pools/retired route, reusing the existing pool-entity scan/pagination patterns in routes::pools.

Changes:

• Implemented /pools/retired handler that filters pools by PoolState.snapshot.live().is_retired, orders results, and applies pagination.
• Added selection/unit tests and endpoint-level tests for the new retired-pools behavior.
• Registered the new route in the minibf router.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
crates/minibf/src/routes/pools.rs	Adds retired-pool selection logic, the /pools/retired route handler, and associated tests.
crates/minibf/src/lib.rs	Wires the new /pools/retired endpoint into the HTTP router.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.