Consolidate ledger state queries.

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.

This commit adds breaking changes, tests.

Author: aniketd

eras/shelley/impl/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 1.19.0.0
 
+* Deprecate functions in `Cardano.Ledger.Shelley.API.Wallet` in favour of
+  consolidated queries in `Cardano.Ledger.Api.State.Query`:
+  - `poolsByTotalStakeFraction` → `queryStakePoolDistrByTotalSupply`
+  - `getNonMyopicMemberRewards` → `queryNonMyopicMemberRewards`
+  - `getRewardInfoPools` → `queryRewardInfoPools`
+  - `getRewardProvenance` → `queryRewardProvenance`
 * Add `Shelley.API.Forecast` and `Shelley.Forecast`:
   - Add `EraForecast` and `ShelleyEraForecast` typeclasses to deprecate `GetLedgerView` from `cardano-ledger-tpraos`.
   - Add `currentForecast` and `futureForecast` functions to deprecate `currentLedgerView` and `futureLedgerView`.

eras/shelley/impl/src/Cardano/Ledger/Shelley/API/Wallet.hs

@@ -37,6 +37,9 @@ module Cardano.Ledger.Shelley.API.Wallet (
   totalAdaES,
   totalAdaPotsES,
   getStakePools,
+
+  -- * Snapshots
+  currentSnapshot,
 ) where
 
 import Cardano.Ledger.Address (compactAddr)
@@ -200,6 +203,10 @@ poolsByTotalStakeFraction globals nes =
       IndividualPoolStake
     toTotalStakeFrac (IndividualPoolStake s c vrf) =
       IndividualPoolStake (s * stakeRatio) c vrf
+{-# DEPRECATED
+  poolsByTotalStakeFraction
+  "Use queryStakePoolDistrByTotalSupply from Cardano.Ledger.Api.State.Query.Pool instead"
+  #-}
 
 -- | Calculate the current total stake.
 getTotalStake :: Globals -> NewEpochState era -> Coin
@@ -252,6 +259,10 @@ getNonMyopicMemberRewards globals ss = Map.fromSet nmmRewards
       getTopRankedPools rPot totalStakeCoin pp $
         Map.intersectionWith (,) (VMap.toMap (VMap.map percentile' ls)) $
           VMap.toMap stakePoolsSnapShot
+{-# DEPRECATED
+  getNonMyopicMemberRewards
+  "Use queryNonMyopicMemberRewards from Cardano.Ledger.Api.State.Query.Reward instead"
+  #-}
 
 -- | Create a current snapshot of the ledger state.
 --
@@ -284,7 +295,7 @@ data RewardInfoPool = RewardInfoPool
   -- Can be larger than @1.0@ for pool that gets lucky.
   -- (If some pools get unlucky, some pools must get lucky.)
   }
-  deriving (Eq, Show, Generic)
+  deriving (Eq, Ord, Show, Generic)
 
 instance NoThunks RewardInfoPool
 
@@ -305,7 +316,7 @@ data RewardParams = RewardParams
   , totalStake :: Coin
   -- ^ Maximum lovelace supply minus treasury
   }
-  deriving (Eq, Show, Generic)
+  deriving (Eq, Ord, Show, Generic)
 
 instance NoThunks RewardParams
 
@@ -359,17 +370,14 @@ getRewardInfoPools globals nes =
         , performanceEstimate =
             unPerformanceEstimate $ percentile' $ histLookup poolId
         }
+{-# DEPRECATED getRewardInfoPools "Use queryRewardInfoPools from Cardano.Ledger.Api.State.Query.Reward instead" #-}
 
 -- | Calculate stake pool rewards from the snapshot labeled `go`.
 -- Also includes information on how the rewards were calculated
 -- ('RewardProvenance').
 --
 -- For a calculation of rewards based on the current stake distribution,
 -- see 'getRewardInfoPools'.
---
--- TODO: Deprecate 'getRewardProvenance', because wallets are more
--- likely to use 'getRewardInfoPools' for up-to-date information
--- on stake pool rewards.
 getRewardProvenance ::
   forall era.
   (EraGov era, EraCertState era) =>
@@ -391,6 +399,7 @@ getRewardProvenance globals newEpochState =
     slotsPerEpoch = epochInfoSize (epochInfoPure globals) epochNo
     asc = activeSlotCoeff globals
     secparam = securityParameter globals
+{-# DEPRECATED getRewardProvenance "Use queryRewardProvenance from Cardano.Ledger.Api.State.Query.Reward instead" #-}
 
 --------------------------------------------------------------------------------
 -- Transaction helpers

libs/cardano-ledger-api/CHANGELOG.md

@@ -1,8 +1,44 @@
 # Version history for `cardano-ledger-api`
 
-## 1.13.0.1
-
-*
+## 1.14.0.0
+
+* Reorganize `Cardano.Ledger.Api.State.Query` into 9 sub-modules with stable
+  query result types and deprecation shims for downstream migration:
+  - `Query.Governance` — governance, constitution, committee, and DRep queries
+  - `Query.Pool` — stake pool queries and stake distribution
+  - `Query.Snapshot` — mark/set/go stake snapshots
+  - `Query.StakeDelegation` — stake pool delegations and reward accounts
+  - `Query.Reward` — reward provenance and non-myopic member rewards
+  - `Query.UTxO` — UTxO queries by address, TxIn, or whole
+  - `Query.PParams` — protocol parameter queries
+  - `Query.Epoch` — epoch number and chain account state
+  - `Query.Debug` — debug and deprecated queries
+* Add new stable query result types:
+  - `QueryResultConstitution` (replaces `Constitution era` in `queryConstitution`)
+  - `QueryResultCommitteeMemberState`, `QueryResultCommitteeMembersState`
+    (replace `CommitteeMemberState`, `CommitteeMembersState` — deprecated aliases provided)
+  - `QueryResultDRepState`, `QueryResultDRepStates`
+    (replaces `Map (Credential DRepRole) DRepState` in `queryDRepState`)
+  - `QueryResultDelegsAndRewards`
+    (replaces `(Map, Map)` tuple in `queryStakePoolDelegsAndRewards`)
+  - `QueryResultRewardInfoPools`
+  - Rename `StakeSnapshot` → `QueryResultStakeSnapshot` (deprecated alias provided)
+  - Rename `StakeSnapshots` → `QueryResultStakeSnapshots` (deprecated alias provided)
+  - Rename `QueryPoolStateResult` → `QueryResultPoolState` (deprecated alias provided)
+* Add 22 newly consolidated query functions (from ouroboros-consensus, cardano-api, cardano-cli):
+  - `queryEpochNo`
+  - `queryNonMyopicMemberRewards`, `queryRewardInfoPools`, `queryRewardProvenance`
+  - `queryStakePools`, `queryStakePoolDistrByTotalSupply`, `queryStakePoolDistrFromSnapshot`
+  - `queryStakeDelegDeposits`, `queryDRepDelegatees`, `queryStakeVoteDelegatees`
+  - `queryUTxOByAddress`, `queryUTxOByTxIn`, `queryUTxOFull`
+  - `queryDebugEpochState`, `queryDebugNewEpochState`, `queryProposedPParamsUpdates`
+  - `queryStakePoolParams` (renamed from `queryPoolParameters` — deprecated alias provided)
+  - `toQueryResultConstitution`, `toQueryResultPoolState`, `toQueryResultDRepState`
+* Deprecate functions in `Cardano.Ledger.Shelley.API.Wallet` pointing to new query module locations:
+  - `poolsByTotalStakeFraction` → `queryStakePoolDistrByTotalSupply`
+  - `getNonMyopicMemberRewards` → `queryNonMyopicMemberRewards`
+  - `getRewardInfoPools` → `queryRewardInfoPools`
+  - `getRewardProvenance` → `queryRewardProvenance`
 
 ## 1.13.0.0
 

libs/cardano-ledger-api/cardano-ledger-api.cabal

@@ -1,6 +1,6 @@
 cabal-version: 3.0
 name: cardano-ledger-api
-version: 1.13.0.1
+version: 1.14.0.0
 license: Apache-2.0
 maintainer: operations@iohk.io
 author: IOHK
@@ -42,7 +42,15 @@ library
   hs-source-dirs: src
   other-modules:
     Cardano.Ledger.Api.Scripts.ExUnits
-    Cardano.Ledger.Api.State.Query.CommitteeMembersState
+    Cardano.Ledger.Api.State.Query.Debug
+    Cardano.Ledger.Api.State.Query.Epoch
+    Cardano.Ledger.Api.State.Query.Governance
+    Cardano.Ledger.Api.State.Query.PParams
+    Cardano.Ledger.Api.State.Query.Pool
+    Cardano.Ledger.Api.State.Query.Reward
+    Cardano.Ledger.Api.State.Query.Snapshot
+    Cardano.Ledger.Api.State.Query.StakeDelegation
+    Cardano.Ledger.Api.State.Query.UTxO
 
   default-language: Haskell2010
   ghc-options:
@@ -78,6 +86,7 @@ library
     data-default,
     deepseq,
     microlens,
+    nothunks,
     transformers,
     vector-map >=1.2,
 
@@ -106,6 +115,7 @@ library testlib
     cardano-ledger-binary:{cardano-ledger-binary, testlib},
     cardano-ledger-core:{cardano-ledger-core, testlib},
     cardano-ledger-dijkstra:testlib,
+    cardano-ledger-shelley,
     data-default,
     generic-random,
     prettyprinter,