feat(minibf): add /epochs/{number}/blocks/{pool_id} endpoint

[slowbackspace]

Closes #1102. Closes #1234.

Summary

Adds GET /epochs/{number}/blocks/{pool_id}: the hashes of the blocks a pool minted in an epoch. Standard count / page / order pagination.

Semantics (pinned against live Blockfrost)

Input	Response
Pool id, bech32 or hex (shared decode_pool_id)	200
Malformed pool id	400
Unknown pool	404
Epoch that doesn't exist yet	404
Known pool, no blocks in the epoch (or pool younger than the epoch)	200 []

Implementation

A bounded epoch-range scan, as sketched in the issue — no new index.

• Scan: archive().get_range over the epoch's slots. Match each block's issuer vkey hash against the pool. Runs in spawn_blocking. Stops when the page fills. desc is the exact mirror of asc.
• Header-only decode: the handler needs the issuer and the block hash. Both live in the header — the block hash is the hash of the header bytes. decode_block_header steps over the [era_tag, [header, txs, ...]] wrapper and never parses transactions. ~10x on the worst epochs.
• Unknown-pool 404: a pool is known when it registered (PoolState entity) or when the scan finds a block it minted. A pool must register before it can mint, so the entity check covers every real pool.
• Byron: no issuer in the header, never matches.

Bug found on the way (#1234)

• get_range treats its upper bound as exclusive. This endpoint and the pre-existing /epochs/{number}/blocks both dropped a block minted on the epoch's final slot.
• Proof: preview epoch 16 ends with a block (Koios confirms). Live Blockfrost lists 1279 blocks for its pool; we listed 1278.
• Both handlers fixed in one commit. The epoch-16 listing now matches live Blockfrost exactly.

Performance (measured, 346 GB mainnet archive)

Full scans are the common case: 404s, empty pages, and any count the pool's blocks don't fill all read the whole epoch (~21k blocks).

Query	Full decode	Header-only (this PR)
Alonzo congestion epochs 320–335 (worst offenders)	2.1–2.3 s	0.28–0.33 s cold / ~0.20 s warm
Recent Conway epoch 640	0.7 s	0.16 s cold / 0.13 s warm
Minting pool, count=1 (early exit)	< 1 ms	< 1 ms

Cold now beats warm by ~40%: flatfile I/O is the remaining floor, not CPU.

Testing

• 9 inline endpoint tests: happy path, pagination, desc = reversed asc, empty page, 400, both 404s, archive fault 500, final-slot regression.
• 4 unit tests for decode_block_header: equals the full decode on a Conway block, decodes the Shelley header shape, None for Byron, error on malformed bytes.
• Official blockfrost-tests: 12/12 preview (epoch 469), 12/12 mainnet (epoch 211).
• dolos-minibf suite green (329 tests). Workspace clippy clean with -D warnings. Nightly fmt clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added an endpoint to retrieve blocks produced by a specific pool during an epoch.
  • Supports pagination and ascending or descending result ordering.
  • Includes validation for epoch and pool availability.

• Bug Fixes

  • Improved epoch boundary handling to include blocks from the final slot.
  • Added clearer handling for malformed or unavailable block data.

• Documentation

  • Documented the new pool-filtered epoch blocks endpoint.

[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: f0dbe56e-7b0d-4a4e-8f2c-6364511d3724

📥 Commits

Reviewing files that changed from the base of the PR and between d9a847d and 7fa4b35.

📒 Files selected for processing (4)

• crates/minibf/src/lib.rs
• crates/minibf/src/routes/epochs/mod.rs
• crates/minibf/src/test_support.rs
• docs/content/apis/minibf.mdx

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

---

📝 Walkthrough

Walkthrough

Adds GET /epochs/{epoch}/blocks/{pool_id} to MiniBF. The handler validates inputs, scans epoch blocks, decodes headers, filters by pool issuer hash, and supports pagination and ordering. Epoch range handling now includes blocks on the final slot.

Changes

Pool-filtered epoch blocks

Layer / File(s)	Summary
Epoch range and header decoding crates/minibf/src/routes/epochs/mod.rs	The epoch scan uses the next epoch start as an exclusive bound. Header-only decoding supports issuer filtering, skips unsupported boundary blocks, and reports malformed data.
Pool-filtered endpoint flow crates/minibf/src/lib.rs, crates/minibf/src/routes/epochs/mod.rs	The new route validates the epoch and pool, filters matching blocks, applies pagination and ordering, and maps failures to responses.
Endpoint validation and support crates/minibf/src/routes/epochs/mod.rs, crates/minibf/src/test_support.rs, docs/content/apis/minibf.mdx	Tests cover filtering, pagination, ordering, boundary inclusion, decoding, and errors. Test support exposes epoch starts, and the endpoint is documented.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟡 Moderate · up to 7fa4b

The change adds a pool-filtered epoch block endpoint and adjusts final-slot handling; without supplied successful lint, build, and test results, regressions in routing or scan behavior are not yet cleared, so merge should wait for those checks.

Possibly related PRs

• txpipe/dolos#731: The endpoint extends the existing epoch block scanning implementation.
• txpipe/dolos#1152: Both changes add epoch-scoped MiniBF routes with router wiring, tests, and documentation.

Suggested labels: enhancement, area:minibf

Suggested reviewers: scarmuega, gonzalezzfelipe

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the new pool-filtered epoch blocks endpoint.
Linked Issues check	✅ Passed	The changes implement the endpoint and fix final-slot omission required by issues [#1102] and [#1234].
Out of Scope Changes check	✅ Passed	The implementation, tests, helper, and documentation directly support the linked endpoint and epoch-range fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 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-epoch-pool-blocks

---

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

Adds the Blockfrost-compatible endpoint for listing blocks minted by a pool during an epoch.

Changes:

• Implements issuer-based block filtering with pagination.
• Registers and documents the endpoint.
• Adds endpoint and error-path tests.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/content/apis/minibf.mdx	Documents endpoint support.
crates/minibf/src/routes/epochs/mod.rs	Implements handler and tests.
crates/minibf/src/lib.rs	Registers the route.

---

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

[Copilot]

Pull request overview

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