feat(minibf): add /scripts/{script_hash}/redeemers endpoint

[slowbackspace]

Closes #1077.

What

• New endpoint: GET /scripts/{script_hash}/redeemers with count/page/order pagination and the Blockfrost 404/empty-page semantics.
• Candidate blocks come from a new index-time script_redeemers dimension, streamed through blocks_by_script_redeemers_stream in dolos-cardano. The endpoint scans that dimension alone — see the dimension section below for why query-time derivation cannot work.
• Redeemer-to-script matching lives in a shared redeemer_script_hash function. It now covers spend, mint, cert, and reward. As a side effect, /txs/{tx_hash}/redeemers now fills script_hash for cert and reward redeemers (it returned an empty string before).
• Phase-2-failed txs are skipped: db-sync stores no redeemers for them, so Blockfrost lists none. A failed tx also consumes only its collateral, so its spend redeemers point at inputs the resolver never prepared.
• Docs: one row added to the MiniBF endpoint table.

Verification

• Unit tests resolve every purpose against a hand-built Conway tx, including the vote/propose None cases and key-credential negatives.
• Route tests follow the standard matrix: happy path, pagination 400s, 404s, faulty-store 500.
• Official blockfrost-tests suite against a synced preview node: the strict golden fixture for this endpoint (112 rows, exact db-sync fees) passes, plus all pagination-error fixtures and the txs/:tx/redeemers regression tests.
• New upstream fixtures covering cert and reward purposes on both endpoints (test: cover cert and reward redeemer purposes on all networks blockfrost/blockfrost-tests#105) pass against this branch and against live Blockfrost on preview.
• Descending order equals reversed ascending order over the script's full history.

The script_redeemers dimension

Deriving candidates at query time cannot be complete: an execution through a reference script carries no script bytes, and governance redeemers (vote, propose) leave no side effect that any dimension tags. So the endpoint is backed by an index-time dimension, following the precedent of #974 (ACCOUNT_WITHDRAWALS) and #976 (POOL_CERTS):

• index_block resolves each redeemer to its script — a shared matcher in pallas_extras, covering all six purposes including vote (the voter's credential) and propose (the proposal's policy script) — and tags the executed script under script_redeemers.
• The endpoint scans that dimension alone. The tag is block-level, so the handler still matches each redeemer to pick rows.
• Tags are a superset by design: phase-2-failed txs and governance purposes are tagged. The Blockfrost rules (no redeemers for failed txs; no vote/propose in the schema) stay query-time filters, so output matches deployed Blockfrost exactly.
• Storage cost measured on preview: ~1.7 entries per block at current traffic, ≈16 B payload each — single-digit percent of the index store, nothing on archive or state.
• The stele goldens re-pin deliberately: the canonical indexes layer carries one record per dimension, so its diffId and the inscription digest change.

Operational note (release-note material): a store synced before this change serves only post-upgrade history on /scripts/{script_hash}/redeemers. Full history needs a store synced from scratch, or a snapshot cut from one — the same transition model as #974/#976.

Known limits / follow-ups

• Vote and propose rows are still not emitted: the Blockfrost OpenAPI schema cannot represent them yet (feat: add vote and propose redeemer purposes blockfrost/openapi#464). Once the schema releases and the crate regenerates, emitting them is a query-side change — the tags already exist on stores synced with this dimension.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ffe2f3a2-124f-4bfc-bbc6-6b13b7df2df9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}