Consolidate ledger-state queries by aniketd · Pull Request #5690 · IntersectMBO/cardano-ledger

aniketd · 2026-03-30T16:20:53Z

Description

Reorganise Ledger.Api.State.Query into domain-specific sub-modules, and re-export everything.

Consolidate ledger state queries from consensus, api, and cli.
Add stable QueryResult* types to decouple downstream from ledger-internal representation.
Wherever it made sense: filter ~ empty set -> return all.
Contains breaking changes, some tests.
CBOR codecs are preserved.

Checklist

Copilot

Pull request overview

This PR restructures Cardano.Ledger.Api.State.Query into domain-focused submodules, consolidating ledger-state query helpers previously scattered across downstream packages, and introduces stable QueryResult* types to reduce coupling to ledger-internal representations.

Changes:

Split Cardano.Ledger.Api.State.Query into 9 submodules (Governance/Pool/Snapshot/StakeDelegation/Reward/UTxO/PParams/Epoch/Debug) and re-export them from Query.
Add/rename stable QueryResult* result types (with deprecated aliases/shims) and update tests/arbitrary instances accordingly.
Deprecate overlapping wallet API functions in Cardano.Ledger.Shelley.API.Wallet, bump cardano-ledger-api to 1.14.0.0, and update changelogs.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
libs/cardano-ledger-api/testlib/Test/Cardano/Ledger/Api/Arbitrary.hs	Adds `Arbitrary` instances for new `QueryResult*` types and imports wallet reward types.
libs/cardano-ledger-api/test/Test/Cardano/Ledger/Api/State/QuerySpec.hs	Updates roundtrip tests to new types and adds extraction-function property tests.
libs/cardano-ledger-api/test/Test/Cardano/Ledger/Api/State/Imp/QuerySpec.hs	Updates Imp tests to use `QueryResult*` governance query results.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/UTxO.hs	New UTxO query helpers (full/by-address/by-txin).
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/StakeDelegation.hs	New stake delegation queries + stable result type for delegs/rewards.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Snapshot.hs	New stake snapshot query + stable snapshot result types and deprecated aliases.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Reward.hs	New reward-related queries + stable result type for reward-info pools.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/PParams.hs	New protocol parameter query helpers.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Pool.hs	New pool queries + stable pool-state result type and deprecated aliases.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Governance.hs	New governance queries + stable constitution/committee/drep result types and conversions.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Epoch.hs	New epoch/account-state query helpers.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Debug.hs	New debug query helpers + deprecated PParams updates query.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/CommitteeMembersState.hs	Removes now-redundant standalone committee-members-state module.
libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query.hs	Becomes a thin re-export module for the new submodules.
libs/cardano-ledger-api/CHANGELOG.md	Documents the breaking reorg and new query/result types.
libs/cardano-ledger-api/cardano-ledger-api.cabal	Bumps version, registers new modules, adds dependencies.
eras/shelley/impl/src/Cardano/Ledger/Shelley/API/Wallet.hs	Adds deprecations pointing to new query modules; exports `currentSnapshot`; adds `Ord` for reward types.
eras/shelley/impl/CHANGELOG.md	Notes wallet API deprecations in favor of consolidated queries.
.claude/skills/update-changelogs/SKILL.md	Clarifies changelog process rule: top entry is unreleased; don’t add a new section.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

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

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add haddock to mark usage sites across downstream dependencies.

Add usage-site sources in haddock.

Add stable types prefixed QueryResult*. Add CBOR round-trip tests.

Add stable QueryResult* types for some of them.

Add stable QueryResult* types for Snapshot and Snapshots. Also simpify querySnapshots to remove the Maybe Set parameter to just a Set, where an emtpy Set means return ALL pools.

Move queryStakePoolDelegsAndRewards into Query.StakeDelegation submodule. Add QueryResultDelegsAndRewards stable type replacing the tuple. Now, passing an emtpy set means the consumer is asking for all credentials.

Rename QueryPoolStateResult to QueryResultPoolState, and queryPoolParameters to queryStakePoolParams. Simplify queryPoolState to return all pool states when given an empty set. Query is now a thin-wrapper re-exporting sub-modules.

These queries are from consensus, cardano-api, cardano-cli, and Shelley.API.Wallet.

Some debug/deprecated queries.

New sub-module for reward-related queries (non-myopic member rewards, per-pool reward info, reward provenance). Adds Ord instances to RewardInfoPool and RewardParams in Wallet.hs to support the QueryResultRewardInfoPools stable type.

Api.State.Query sub-modules are the place for all ledger-state queries.

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

f-f · 2026-04-07T11:22:05Z

+import Cardano.Ledger.Shelley.PParams (ProposedPPUpdates, emptyPPPUpdates)
+
+-- | Query the full 'EpochState' for debugging.
+-- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:424


These comments are guaranteed to get out of date very soon. I wonder if it would make sense to just name the module (e.g. Ouroboros.Consensus.Shelley.Ledger.Query)

Are they pointing at current usage or future usage?

I thought that it will be quite difficult for the release engineer to figure out where to use the new queries added here, as some of them are completely new, whose bodies are currently in-line in certain downstream modules. Furthermore, some queries may have been changed or in a way, optimised, and therefore will not match syntactic searches to find those places. I have made this comment in the re-exporter "mother module" Query, as such.

I know this is weird, and unconventional, and a form of ephemeral communication between team-members by leaving messages in haddock, instead of using slack or issue comments here. But because it lives alongside the actual queries and the integration process is expected to delete them, I thought it is the safest and most clear - in-band, same-channel - form of communication that would be hard to get wrong or miss.

Let me know what you think. 🙂

I think migrations for breaking changes of this kind are best documented in a migration guide, rather than in the source. The source is by definition a formal spec and represents current intent, but guidance for how the downstream code needs to change is (IMHO) probably best given in a more informal guidance document "look, this functionality you were using is no more, so this is how you achieve circa the same" (e.g. this is how we do migration documents for PureScript, which is what I am thinking about here).

If you'd rather keep this guidance in the source (so it's in-band, which I also understand) then it should be spelled out in the deprecation notices, so that these warnings are notified to the user in the right places in their source.

lehins · 2026-04-03T14:32:04Z

+import Cardano.Ledger.Slot (EpochNo)
+
+-- | Query the current epoch number.
+-- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:413


Links to mutable source code make no sense, since they will get outdated very quickly.
If you want to add links to the source, add them in PR review as a comment, since that is the actual audience

Yes I know this is totally weird, so I answered @f-f 's comment also 🙂 . I may be completely off the optimal solution to this. Let me know what you think. #5690 (comment)

Should I add a table or something to this PR that the release engineer can then track for the work? Or would it be better to open another tracking issue with all the references?

lehins · 2026-04-07T08:15:54Z

+## 1.14.0.0

-*
+* Refactor pool related queries into `Query.Pool` and re-export from `Query`.


This change is not visible to the outside world, as such it should not be even mentioned in the changelog

@oldname

Since the query consolidation breaks downstream anyway (new types, renamed functions, changed return types), keeping deprecated aliases adds noise without value. Remove every deprecation across the Query sub-modules and Shelley.API.Wallet for a completely fresh API. Query sub-modules: - Remove type aliases: CommitteeMemberState, CommitteeMembersState, QueryPoolStateResult, StakeSnapshot, StakeSnapshots - Remove function aliases: mkQueryPoolStateResult, queryPoolParameters - Remove queryProposedPParamsUpdates (always returned empty) - Un-deprecate queryRewardProvenance (serves a distinct purpose) - Remove {-# OPTIONS_GHC -Wno-deprecations #-} from Query.hs and Governance.hs Shelley.API.Wallet: - Remove 11 query functions: getUTxO, getFilteredUTxO, getUTxOSubset, getPools, getStakePools, poolsByTotalStakeFraction, getTotalStake, getNonMyopicMemberRewards, currentSnapshot, getRewardInfoPools, getRewardProvenance - Clean up unused imports and language extensions Add "Replaces @oldname@" haddock annotations to all 10 replacement query functions to guide downstream migration. Update both CHANGELOGs with explicit per-function replacement mappings.

aniketd force-pushed the aniketd/lsq branch 5 times, most recently from c9d1cb9 to 38aa10e Compare March 31, 2026 15:32

aniketd changed the title ~~wip~~ Consolidate ledger-state queries Mar 31, 2026

aniketd marked this pull request as ready for review March 31, 2026 15:35

aniketd requested a review from a team as a code owner March 31, 2026 15:35

aniketd requested review from Lucsanszky, f-f, lehins, neilmayhew and teodanciu March 31, 2026 15:35

aniketd force-pushed the aniketd/lsq branch from 38aa10e to 35023f3 Compare March 31, 2026 15:39

aniketd requested a review from Copilot March 31, 2026 19:54

Copilot started reviewing on behalf of aniketd March 31, 2026 19:55 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Comment thread libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Snapshot.hs Outdated

Comment thread libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/StakeDelegation.hs Outdated

Comment thread libs/cardano-ledger-api/CHANGELOG.md Outdated

aniketd force-pushed the aniketd/lsq branch from 35023f3 to 2618891 Compare April 1, 2026 09:30

aniketd requested review from Jimbo4350 and Copilot April 1, 2026 09:31

Copilot started reviewing on behalf of aniketd April 1, 2026 09:32 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

aniketd force-pushed the aniketd/lsq branch from 2618891 to 2372b76 Compare April 6, 2026 14:19

aniketd added 7 commits April 6, 2026 19:50

Refactor pool queries into Query.Pool.

2bfff7f

Add haddock to mark usage sites across downstream dependencies.

Refactor chainStateAccount query into Query.Epoch.

bd27798

Add usage-site sources in haddock.

mv Query.CommitteeMembersState to Query.Governance.

3b0137e

Add stable types prefixed QueryResult*. Add CBOR round-trip tests.

mv all governance queries to Query.Governance.

f87567f

Add stable QueryResult* types for some of them.

Refactor snapshot queries into Query.Snapshot.

7106bd8

Add stable QueryResult* types for Snapshot and Snapshots. Also simpify querySnapshots to remove the Maybe Set parameter to just a Set, where an emtpy Set means return ALL pools.

Refactor stake delegation to Query.StakeDelegation.

f7fb5c0

Move queryStakePoolDelegsAndRewards into Query.StakeDelegation submodule. Add QueryResultDelegsAndRewards stable type replacing the tuple. Now, passing an emtpy set means the consumer is asking for all credentials.

Refactor pool queries into Query.Pool.

3cd8df7

Rename QueryPoolStateResult to QueryResultPoolState, and queryPoolParameters to queryStakePoolParams. Simplify queryPoolState to return all pool states when given an empty set. Query is now a thin-wrapper re-exporting sub-modules.

aniketd added 6 commits April 6, 2026 19:51

Add cardano-{cli,api} queries to API.State.Query.

3ead077

These queries are from consensus, cardano-api, cardano-cli, and Shelley.API.Wallet.

Add new pool queries from consensus and cardano-api

d099e60

Add Query.{UTxO,Debug} sub-modules.

9775380

Some debug/deprecated queries.

Add Query.Reward.

53efdb4

New sub-module for reward-related queries (non-myopic member rewards, per-pool reward info, reward provenance). Adds Ord instances to RewardInfoPool and RewardParams in Wallet.hs to support the QueryResultRewardInfoPools stable type.

Deprecate wallet query functions.

6c969ef

Api.State.Query sub-modules are the place for all ledger-state queries.

Some cleanup and complexity annotations.

30687e1

aniketd force-pushed the aniketd/lsq branch from 2372b76 to 30687e1 Compare April 6, 2026 14:23

aniketd requested a review from Copilot April 6, 2026 14:23

Copilot started reviewing on behalf of aniketd April 6, 2026 14:24 View session

Copilot AI reviewed Apr 6, 2026

View reviewed changes

f-f reviewed Apr 7, 2026

View reviewed changes

Small typos and fixes

1008ac9

lehins reviewed Apr 7, 2026

View reviewed changes

aniketd marked this pull request as draft April 10, 2026 11:46

This was referenced Apr 10, 2026

Add serialisation tests for query result types #5723

Draft

Move some of the queries to sub-modules, add more tests #5730

Draft

Consolidate ledger state queries - part 3 #5734

Draft

Consolidate ledger state queries - part 4 #5746

Draft

Conversation

aniketd commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

f-f Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

aniketd Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

f-f Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lehins Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

aniketd Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

aniketd Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

lehins Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aniketd commented Mar 30, 2026 •

edited

Loading

f-f Apr 8, 2026 •

edited

Loading