Some cleanup and complexity annotations.

Author: aniketd

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query.hs

@@ -1,5 +1,12 @@
 {-# OPTIONS_GHC -Wno-deprecations #-}
 
+-- | Ledger state queries consolidated from @ouroboros-consensus@, @cardano-api@,
+-- @cardano-cli@, and @cardano-db-sync@.
+--
+-- Each query function includes @Source:@ comments pointing to the original
+-- call sites in these downstream packages. These are intended to guide
+-- downstream propagation of these queries. Once a downstream call site has been
+-- successfully migrated, the corresponding comment may be removed.
 module Cardano.Ledger.Api.State.Query (
   -- * @GetChainAccountState@
   module Cardano.Ledger.Api.State.Query.Epoch,

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Debug.hs

@@ -19,6 +19,8 @@ import Cardano.Ledger.Shelley.PParams (ProposedPPUpdates, emptyPPPUpdates)
 --
 -- __Warning:__ This returns internal, era-parameterized state that is not
 -- covered by CBOR stability guarantees. Use only for debugging and tooling.
+--
+-- /O(1)/
 queryDebugEpochState :: NewEpochState era -> EpochState era
 queryDebugEpochState = nesEs
 
@@ -28,12 +30,16 @@ queryDebugEpochState = nesEs
 --
 -- __Warning:__ This returns internal, era-parameterized state that is not
 -- covered by CBOR stability guarantees. Use only for debugging and tooling.
+--
+-- /O(1)/
 queryDebugNewEpochState :: NewEpochState era -> NewEpochState era
 queryDebugNewEpochState = id
 
 -- | Query proposed protocol parameter updates.
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:420
 --   answerPureBlockQuery case for GetProposedPParamsUpdates
+--
+-- /O(1)/
 queryProposedPParamsUpdates :: NewEpochState era -> ProposedPPUpdates era
 queryProposedPParamsUpdates _ = emptyPPPUpdates
 {-# DEPRECATED

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Epoch.hs

@@ -11,6 +11,8 @@ import Lens.Micro ((^.))
 -- | Query the current epoch number.
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:413
 --   answerPureBlockQuery case for GetEpochNo
+--
+-- /O(1)/
 queryEpochNo :: NewEpochState era -> EpochNo
 queryEpochNo = nesEL
 
@@ -19,6 +21,8 @@ queryEpochNo = nesEL
 --   answerPureBlockQuery case for GetAccountState
 -- Also: cardano-api:cardano-api/src/Cardano/Api/Query/Internal/Expr.hs:484
 --   queryAccountState cardano-api wrapper (CLI via Convenience.hs:171)
+--
+-- /O(1)/
 queryChainAccountState ::
   NewEpochState era ->
   ChainAccountState

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Governance.hs

@@ -382,6 +382,8 @@ instance DecCBOR QueryResultDRepStates where
 --   queryGovState cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1617
 --   CLI invocation
+--
+-- /O(1)/
 queryGovState :: NewEpochState era -> GovState era
 queryGovState nes = nes ^. nesEpochStateL . epochStateGovStateL
 
@@ -392,12 +394,16 @@ queryGovState nes = nes ^. nesEpochStateL . epochStateGovStateL
 --   queryConstitution cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1589
 --   CLI invocation
+--
+-- /O(1)/
 queryConstitution :: ConwayEraGov era => NewEpochState era -> QueryResultConstitution
 queryConstitution nes = toQueryResultConstitution $ queryGovState nes ^. constitutionGovStateL
 
 -- | Query the constitution hash.
 --
 -- Convenience extraction — no corresponding standalone query in @ouroboros-consensus@.
+--
+-- /O(1)/
 queryConstitutionHash ::
   ConwayEraGov era =>
   NewEpochState era ->
@@ -414,6 +420,8 @@ queryConstitutionHash nes =
 --   CLI invocation
 --
 -- Empty 'Set' returns all proposals.
+--
+-- /O(g)/ where (g) is the proposals considered for ratification, Seq.filter.
 queryProposals ::
   ConwayEraGov era =>
   NewEpochState era ->
@@ -438,19 +446,28 @@ queryProposals nes gids
 --   queryRatifyState cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1645
 --   CLI invocation
+--
+-- /O(P)/ where (P) is the DRep pulser completion cost, finishedPulserState.
 queryRatifyState :: ConwayEraGov era => NewEpochState era -> RatifyState era
 queryRatifyState = snd . finishedPulserState
 
 -- | Query committee members. Whenever the system is in No Confidence mode this query will
 -- return no committee members.
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:471
 --   answerPureBlockQuery case for GetCommitteeMembersState
--- Also: cardano-api:cardano-api/src/Cardano/Api/Query/Internal/Expr.hs:452
+-- Also: cardano-api:cardano-api/src/Cardano/Api/Query/Internal/Expr.hs:454
 --   queryCommitteeMembersState cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1887
 --   CLI invocation
 --
 -- Empty 'Set' returns all matches (i.e. no filtering).
+--
+-- @
+--   O(P + m)
+-- @
+-- where,
+--   (P) is the DRep pulser completion cost, finishedPulserState
+--   (m) is the committee members (current + next + state), Map.union and Map.mapWithKey
 queryCommitteeMembersState ::
   forall era.
   (ConwayEraGov era, ConwayEraCertState era) =>
@@ -546,6 +563,8 @@ queryCommitteeMembersState coldCredsFilter hotCredsFilter statusFilter nes =
       }
 
 -- | Get the committee members that will be in effect at the next epoch boundary.
+--
+-- /O(P)/ where (P) is the DRep pulser completion cost, finishedPulserState.
 getNextEpochCommitteeMembers ::
   ConwayEraGov era =>
   NewEpochState era ->
@@ -564,6 +583,13 @@ getNextEpochCommitteeMembers nes =
 --   CLI invocation
 --
 -- Empty 'Set' returns all DReps.
+--
+-- @
+--   O(d + k)
+-- @
+-- where,
+--   (d) is the total registered DReps, Map.restrictKeys and Map.map
+--   (k) is the requested DRep credential set, Map.restrictKeys
 queryDRepState ::
   ConwayEraCertState era =>
   NewEpochState era ->
@@ -590,6 +616,15 @@ queryDRepState nes creds =
 --   queryDRepDelegations cardano-api wrapper (not publicly exported)
 --
 -- Empty 'Set' returns all DReps.
+--
+-- @
+--   O(d + k)  when all requested DReps are DRepCredentials
+--   O(c)      when AlwaysAbstain or AlwaysNoConfidence are requested
+-- @
+-- where,
+--   (d) is the registered DReps, Map.restrictKeys
+--   (k) is the requested DRep set, Map.restrictKeys
+--   (c) is the total staking credentials, Map.foldlWithKey' (full accounts scan)
 queryDRepDelegations ::
   forall era.
   ConwayEraCertState era =>
@@ -637,6 +672,14 @@ queryDRepDelegations nes dreps =
 --   CLI invocation
 --
 -- Empty 'Set' returns all DReps.
+--
+-- @
+--   O(P + d + k)
+-- @
+-- where,
+--   (P) is the DRep pulser completion cost, finishedPulserState
+--   (d) is the total DReps in the distribution, Map.map
+--   (k) is the requested DRep set, Map.restrictKeys
 queryDRepStakeDistr ::
   ConwayEraGov era =>
   NewEpochState era ->
@@ -656,6 +699,15 @@ queryDRepStakeDistr nes creds
 --   No consensus BlockQuery constructor exists yet (GetRegisteredDRepStakeDistr was planned but not added).
 --
 -- Empty 'Set' returns all registered DReps.
+--
+-- @
+--   O(d + k + d * c_avg * log(c))
+-- @
+-- where,
+--   (d) is the registered DReps, Map.restrictKeys and Map.foldlWithKey'
+--   (k) is the requested DRep credential set, Map.restrictKeys
+--   (c_avg) is the average delegators per DRep, foldMap over drepDelegs
+--   (c) is the total staking credentials, Map.lookup in instantStake per delegator
 queryRegisteredDRepStakeDistr ::
   (ConwayEraGov era, ConwayEraCertState era) =>
   NewEpochState era ->
@@ -683,13 +735,20 @@ queryRegisteredDRepStakeDistr nes creds =
 -- | Query the DRep delegatee for each given staking credential.
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:457
 --   answerPureBlockQuery case for GetDRepStakeDistr (partial — delegatees extracted separately)
--- Also: cardano-api:cardano-api/src/Cardano/Api/Query/Internal/Expr.hs:459
+-- Also: cardano-api:cardano-api/src/Cardano/Api/Query/Internal/Expr.hs:469
 --   queryStakeVoteDelegatees cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1042
 --   CLI invocation
 --
 -- Returns the DRep each credential has delegated to. Credentials with no
 -- DRep delegation are omitted from the result. Empty 'Set' returns all.
+--
+-- @
+--   O(c + k)
+-- @
+-- where,
+--   (c) is the total staking credentials, Map.restrictKeys
+--   (k) is the requested credential set, Map.restrictKeys
 queryDRepDelegatees ::
   (EraCertState era, ConwayEraAccounts era) =>
   NewEpochState era ->
@@ -704,6 +763,8 @@ queryDRepDelegatees nes creds =
 
 -- | Force the DRep pulser to completion and return the resulting snapshot and
 -- ratify state. Shared across governance query sub-modules.
+--
+-- /O(P)/ where (P) is the remaining DRep pulser work, amortised across the epoch.
 finishedPulserState ::
   ConwayEraGov era =>
   NewEpochState era ->

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/PParams.hs

@@ -18,6 +18,8 @@ import Lens.Micro ((^.))
 -- see if we are aware of any upcoming changes.
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/Query.hs:418
 --   answerPureBlockQuery case for GetCurrentPParams
+--
+-- /O(1)/
 queryCurrentPParams :: EraGov era => NewEpochState era -> PParams era
 queryCurrentPParams nes = nes ^. nesEpochStateL . epochStateGovStateL . curPParamsGovStateL
 
@@ -30,6 +32,8 @@ queryCurrentPParams nes = nes ^. nesEpochStateL . epochStateGovStateL . curPPara
 --   queryFuturePParams cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:1673
 --   CLI invocation
+--
+-- /O(1)/
 queryFuturePParams :: EraGov era => NewEpochState era -> Maybe (PParams era)
 queryFuturePParams nes =
   case nes ^. nesEpochStateL . epochStateGovStateL . futurePParamsGovStateL of

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Pool.hs

@@ -5,7 +5,6 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE StandaloneDeriving #-}
 {-# LANGUAGE TypeApplications #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
 
 module Cardano.Ledger.Api.State.Query.Pool (
   -- * Stable query result types
@@ -166,6 +165,13 @@ mkQueryPoolStateResult = toQueryResultPoolState
 --   CLI invocation
 --
 -- Empty 'Set' returns all pools.
+--
+-- @
+--   O(p + k)
+-- @
+-- where,
+--   (p) is the total registered stake pools, Map.restrictKeys and Map.mapWithKey
+--   (k) is the requested pool key set, Map.restrictKeys
 queryPoolState ::
   EraCertState era =>
   NewEpochState era ->
@@ -185,6 +191,13 @@ queryPoolState nes poolKeys network =
 --   queryStakePoolParameters cardano-api wrapper
 --
 -- Empty 'Set' returns all pools.
+--
+-- @
+--   O(p + k)
+-- @
+-- where,
+--   (p) is the total registered stake pools, Map.restrictKeys and Map.mapWithKey
+--   (k) is the requested pool key set, Map.restrictKeys
 queryStakePoolParams ::
   EraCertState era =>
   Network ->
@@ -218,6 +231,13 @@ queryPoolParameters = queryStakePoolParams
 --   queryStakePoolDefaultVote cardano-api wrapper
 -- Also: cardano-cli:cardano-cli/src/Cardano/CLI/EraBased/Query/Run.hs:2003
 --   CLI invocation
+--
+-- @
+--   O(log(p) + log(c))
+-- @
+-- where,
+--   (p) is the registered stake pools, Map.lookup
+--   (c) is the staking credentials, Map.lookup for reward account
 queryStakePoolDefaultVote ::
   (EraCertState era, ConwayEraAccounts era) =>
   NewEpochState era ->
@@ -237,6 +257,14 @@ queryStakePoolDefaultVote nes poolId =
 --   CLI invocation
 --
 -- Empty 'Set' returns all pools.
+--
+-- @
+--   O(P + p + k)
+-- @
+-- where,
+--   (P) is the DRep pulser completion cost, finishedPulserState
+--   (p) is the total pools in the distribution, Map.map
+--   (k) is the requested pool set, Map.restrictKeys
 querySPOStakeDistr ::
   ConwayEraGov era =>
   NewEpochState era ->
@@ -255,6 +283,8 @@ querySPOStakeDistr nes keys
 --   queryStakePools cardano-api wrapper (CLI via Convenience.hs:148)
 --
 -- Returns the key hashes of every pool in the current PState.
+--
+-- /O(p)/ where (p) is the registered stake pools, Map.keysSet.
 queryStakePools ::
   EraCertState era =>
   NewEpochState era ->
@@ -276,6 +306,13 @@ queryStakePools nes =
 -- memoized @nesPd@ (the __set__ snapshot computed at the last epoch boundary).
 --
 -- Needs @maxLovelaceSupply@ from genesis config.
+--
+-- @
+--   O(c + p)
+-- @
+-- where,
+--   (c) is the staking credentials, queryCurrentSnapshot
+--   (p) is the registered stake pools, calculatePoolDistr and Map.map
 queryStakePoolDistrByTotalSupply ::
   (EraStake era, EraCertState era) =>
   -- | maxLovelaceSupply from genesis config
@@ -325,6 +362,13 @@ queryStakePoolDistrByTotalSupply maxLovelaceSupply nes =
 -- This approach is more efficient: the expensive @calculatePoolDistr@
 -- computation happens once at the epoch boundary (ADR-7), and the query
 -- performs only an O(n+m) @Map.restrictKeys@.
+--
+-- @
+--   O(p + k)
+-- @
+-- where,
+--   (p) is the total pools in the memoized distribution, Map.restrictKeys
+--   (k) is the requested pool set, Map.restrictKeys
 queryStakePoolDistrFromSnapshot ::
   NewEpochState era ->
   Set (KeyHash StakePool) ->
@@ -346,6 +390,12 @@ queryStakePoolDistrFromSnapshot nes poolIds
 --
 -- Source: ouroboros-consensus:ouroboros-consensus-cardano/src/shelley/Ouroboros/Consensus/Shelley/Ledger/PeerSelection.hs:32
 --   getPeers (LedgerSupportsPeerSelection instance)
+--
+-- @
+--   O(p * log(p))
+-- @
+-- where,
+--   (p) is the pools in the distribution, Map.mapMaybeWithKey with Map.lookup per pool
 queryStakePoolRelays ::
   EraCertState era =>
   NewEpochState era ->

libs/cardano-ledger-api/src/Cardano/Ledger/Api/State/Query/Reward.hs

@@ -121,6 +121,14 @@ instance DecCBOR QueryResultRewardInfoPools where
 --
 -- This uses a fresh snapshot derived from the current ledger state, not the
 -- stored mark\/set\/go snapshots.
+--
+-- @
+--   O(c + k * p)
+-- @
+-- where,
+--   (c) is the staking credentials, queryCurrentSnapshot
+--   (k) is the input credential\/coin set, iterate over
+--   (p) is the registered stake pools, VMap.mapWithKey per credential
 queryNonMyopicMemberRewards ::
   (EraGov era, EraStake era, EraCertState era) =>
   -- | maxLovelaceSupply from genesis config
@@ -172,6 +180,13 @@ queryNonMyopicMemberRewards maxLovelaceSupply ss = Map.fromSet nmmRewards
 --
 -- Uses a fresh snapshot from 'queryCurrentSnapshot' rather than the stored
 -- epoch-boundary snapshots, so the data reflects the most recent ledger state.
+--
+-- @
+--   O(c + p)
+-- @
+-- where,
+--   (c) is the staking credentials, queryCurrentSnapshot
+--   (p) is the registered stake pools, VMap.mapWithKey
 queryRewardInfoPools ::
   (EraGov era, EraStake era, EraCertState era) =>
   -- | maxLovelaceSupply from genesis config
@@ -220,6 +235,13 @@ queryRewardInfoPools maxLovelaceSupply nes =
 -- This function requires the full 'Globals' because it internally runs
 -- 'createRUpd' in a 'Reader' monad that needs access to 'epochInfo',
 -- 'activeSlotCoeff', 'securityParameter', and 'maxLovelaceSupply'.
+--
+-- @
+--   O(c * log(p))
+-- @
+-- where,
+--   (c) is the staking credentials, createRUpd reward computation
+--   (p) is the registered stake pools, reward calculation per credential
 queryRewardProvenance ::
   (EraGov era, EraCertState era) =>
   Globals ->