feat(minibf): add the constitutional committee vote endpoints

[michalrus]

Resolves #1108.

Resolves #1110.

Merge this after:

• feat(minibf): add /governance/dreps/{drep_id}/votes #1368

Implementation

• Add /governance/committee/votes and /governance/committee/{cc_id}/votes. Both routes scan the committee vote histories in ProposalState. The scan keeps a bounded frontier of complete slot groups. It reads each block from the archive for the transaction hash, the vote anchor, the block height, and the intra-block order.

• /governance/committee/{cc_id}/votes accepts a hot or cold CIP-129 credential. On-chain votes store the hot credential only. For a cold credential, Dolos finds the authorized hot credentials in committee_auths and committee_auth_archive.

• Keep removed committee authorizations for API queries:

  • The Conway ledger EPOCH rule removes authorization histories of cold credentials that leave the committee.
  • Add GovState::committee_auth_archive at CBOR field index 8. The archive stores the authorization histories that the garbage collection removes. It is not ledger-effective state.
  • In CommitteeGc::apply, append each removed history to committee_auth_archive. CommitteeGc::undo truncates the appended entries.
  • Add GovState::committee_hot_credentials. It yields all hot credentials from active authorizations and the archive.
  • Read the archive in /governance/committee/{cc_id}/votes.

• ⚠️ [resync / replay] Stores synchronized with earlier versions ran the old garbage collection. That garbage collection erased past authorization histories. As a result, an existing store has an empty archive. To recover the erased histories and query past members by cold credential, you must replay or resync the store.

Testing

The synthetic test chain now carries a vote anchor.

Raise the gov snapshot schema revision from 1 to 2 and pin a revision-2 golden. The revision-1 golden stays for decode coverage.

The blockfrost-tests suite tests these endpoints in these files:

• https://github.com/blockfrost/blockfrost-tests/blob/0f3f3ea268983a6cf2e6f7fd24c5082fc3a91e0e/src/fixtures/preprod/governance/committee/votes.ts
• https://github.com/blockfrost/blockfrost-tests/blob/0f3f3ea268983a6cf2e6f7fd24c5082fc3a91e0e/src/fixtures/preview/governance/committee/votes.ts
• https://github.com/blockfrost/blockfrost-tests/blob/0f3f3ea268983a6cf2e6f7fd24c5082fc3a91e0e/src/fixtures/preprod/governance/committee/cc-id-votes.ts
• https://github.com/blockfrost/blockfrost-tests/blob/0f3f3ea268983a6cf2e6f7fd24c5082fc3a91e0e/src/fixtures/preview/governance/committee/cc-id-votes.ts

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: Advanced

Run ID: 1c34502f-490e-4c1c-bfa1-4fbcf31d574c

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Removing authorization GC can incorrectly reactivate a stale hot credential when a former cold credential rejoins the committee.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Preserve authorization GC semantics when re-adding committee members · New

What changed in this PR

Adds Blockfrost-compatible constitutional committee vote endpoints and preserves authorization history for cold-credential lookups.

Changes:

• Adds global and member-specific committee vote routes with pagination.
• Resolves archived transaction, anchor, ordering, and block metadata.
• Extends synthetic fixtures and tests with vote anchors and authorization history.

File	Description
docs/​content/​apis/​minibf.mdx	Documents the new endpoints.
crates/​testing/​src/​synthetic.rs	Adds vote-anchor fixture support.
crates/​minibf/​src/​routes/​governance/​mod.rs	Implements handlers, lookup logic, pagination, and tests.
crates/​minibf/​src/​lib.rs	Registers the routes.
crates/​minibf/​src/​error.rs	Adds invalid committee-ID handling.
crates/​cardano/​src/​ewrap/​loading.rs	Stops committee authorization garbage collection.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

Retained authorizations can incorrectly reactivate an old hot credential when a former cold credential rejoins the committee.

Review effort: Balanced
Findings: 1

Open (1)

• Preserve authorization GC semantics when re-adding committee members

[Copilot]

Copilot review overview

🟡 Changes recommended

The bounded-frontier pagination and scan-budget branches need focused coverage before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Add tests for bounded-frontier truncation and scan budget errors · New

Resolved since last review (1)

• Preserve authorization GC semantics when re-adding committee members

[Copilot]

Copilot review overview

🟡 Changes recommended

Rolling back legacy committee-GC WAL entries can panic, and the snapshot profile documentation is stale.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Handle legacy CommitteeGc undo without archive panic · New

Resolved since last review (1)

• Add tests for bounded-frontier truncation and scan budget errors

Previously missed (1)

In code that hasn't changed since last review

Update profile docs for gov revision 2

crates/​snapshot/​src/​namespaces.rs:77

Bumping gov to revision 2 makes the profile documentation inaccurate: crates/snapshot/PROFILE.md:152 still states that thirteen of fourteen live revisions are 1 and that epochs is the only/first bump. Update that compatibility-contract description to say that both epochs and gov are at revision 2.

[Copilot]

Copilot review overview

🟢 Approval recommended

The endpoint behavior, historical authorization model, rollback invariants, bounded scans, schema migration, and edge cases are comprehensively implemented and tested.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Handle legacy CommitteeGc undo without archive panic

[slowbackspace]

Reviewed against blockfrost-backend-ryo (committee_votes.sql, committee_cc_id_votes.sql, validateCommitteeCredentialId) and the pinned blockfrost-tests fixtures. On f66b3b6e in an isolated worktree: clippy is clean for the files this PR touches, the 83 minibf governance tests, the 15 cardano committee tests and every snapshot suite pass.

What checks out: the listing order matches ryo's voting_procedure.id (tx order, then voter map order). Pallas orders ConstitutionalCommitteeScript before ConstitutionalCommitteeKey, which is the ledger's Credential order that db-sync inserts in, so the several-members-in-one-tx case matches. The cold-to-hot union over every recorded authorization matches ryo's committee_registration join. The 400 text is identical, unknown ids return 200 [], and the governance_type names match ryo's snake_case mapping. The gov revision bump follows the schema-rev process (rev 1 golden kept, rev 2 pinned). Uppercase bech32 ids are fine: CheckedHrpstring::hrp() is guaranteed lowercase.

Legend: 🔴 high = fix before merge (correctness, perf) · 🟡 medium = design or parity risk · 🟢 low = cleanup, tests, nits

[slowbackspace]

Severity: 🔴 high

For /governance/committee/votes this counter charges every committee vote in chain history against max_scan_items, whatever the page. Once the chain holds more than 3000 committee votes (the default), the endpoint returns 400 for ?count=1&page=1 and for every other request, permanently. Mainnet has 7 members voting on ~160 actions so far; preview and preprod test committees vote far more often. The only remedy is to raise max_scan_items, which also loosens the page cap on every other endpoint.

The counter does not protect anything the walk does not already pay. read_page for /governance/proposals decodes the same namespace without a budget. The frontier bounds memory to group_limit groups, and archive reads are bounded by group_limit <= to() <= max_scan_items. Rows inside one slot are bounded by the block size.

Suggest dropping the row budget and the two tests that pin it (rejects_history_over_scan_budget, counts_rows_inside_one_slot), and keeping the group_limit == budget guard as the loop terminator. Same point as #1368 (comment), but here the trigger is certain.

[slowbackspace]

Severity: 🟡 medium

Because unresolved rows are dropped before the page offset is counted, this loop settles every group from the frontier edge up to the page. The frontier holds to() groups, so ?count=100&page=30 decodes up to 3000 blocks per request on a full-archive node. If rows counted toward the offset before settling, only the groups that overlap [from, to) would need a block read (at most count + 1), and pruned nodes would return short pages instead of shifted ones.

Same trade-off as #1368 (comment); whichever way #1368 lands, the two endpoints should agree, and the choice deserves a sentence in the PR description.

[slowbackspace]

Severity: 🟡 medium

This is the inverse of bech32_committee_hot / bech32_committee_cold in crates/minibf/src/mapping.rs, but no test round-trips the pair. The route tests parse only a hot script id and a cold key id. The hot key URL in bad_request fails on page=0 before the parser runs, and no test parses a cold script id. A regression in the 0x2 branch for cc_hot or the 0x3 branch for cc_cold would pass the suite.

Please add a unit test that encodes all four (role, kind) combinations with the encoders and asserts the parse returns the same role and credential, plus a 28-byte and a 30-byte payload and a low nibble of 0x0/0x1 as rejections. Moving the parser next to bech32_committee would also let both sides share the HRP constants and the nibble values instead of repeating the literals here.

[slowbackspace]

Severity: 🟢 low

This test never truncates. group_limit = to().min(budget).max(1), and to() is count * page = 4 = budget, so the first frontier holds all four vote slots and the loop exits on the first pass. The comment says the first frontier holds count groups, which is not what the code does.

With a full archive the growth path is unreachable: to() groups always yield at least to() rows, so the page is full and the loop breaks. Growth only happens through pruning, which grows_past_a_pruned_group and returns_a_short_page_at_the_group_budget already cover. Either fix the comment and keep this as a plain paging check, or drop it.

[slowbackspace]

Severity: 🟢 low

settle_committee_casts and resolve_committee_vote_page repeat the block-matching and page-skipping logic of settle_casts and page_resolved_votes from the DRep path: decode the block, build a casts map with a VecDeque per target, pop_front in history order, sort by (tx position, index), drop rows without a cast, reverse for desc, skip from. The committee version is a superset (voter set, anchor, block height). Once #1368 settles, generalizing the DRep helpers over a voter filter and a row type would leave one copy to fix.

[slowbackspace]

Severity: 🟢 low

Every row is built here, with a clone of voter and vote, before push decides whether the frontier accepts it. On the aggregate endpoint most rows fall outside the frontier. A would_accept(slot) check on the frontier before building the row avoids the work. Separately, each retry of the loop in committee_vote_page rescans the whole namespace and re-decodes the blocks that the previous pass already settled; carrying settled groups across retries would make the pruned-node path cheaper.