From 97661429e0d7c008d07f0e9a138a2ab95bca6de5 Mon Sep 17 00:00:00 2001 From: Likhita Polavarapu <78951027+likhita-809@users.noreply.github.com> Date: Tue, 5 Sep 2023 03:54:19 +0530 Subject: [PATCH] docs: Add k/v docs in structs using collections (#17609) --- x/auth/keeper/keeper.go | 3 +- x/distribution/keeper/keeper.go | 27 +++++++++++------- x/evidence/keeper/keeper.go | 3 +- x/feegrant/keeper/keeper.go | 12 ++++---- x/gov/keeper/keeper.go | 24 ++++++++++------ x/slashing/keeper/keeper.go | 13 +++++---- x/staking/keeper/keeper.go | 50 ++++++++++++++++++++++----------- 7 files changed, 84 insertions(+), 48 deletions(-) diff --git a/x/auth/keeper/keeper.go b/x/auth/keeper/keeper.go index 393ed99907d3..ccf842406af9 100644 --- a/x/auth/keeper/keeper.go +++ b/x/auth/keeper/keeper.go @@ -101,7 +101,8 @@ type AccountKeeper struct { Schema collections.Schema Params collections.Item[types.Params] AccountNumber collections.Sequence - Accounts *collections.IndexedMap[sdk.AccAddress, sdk.AccountI, AccountsIndexes] + // Accounts key: AccAddr | value: AccountI | index: AccountsIndex + Accounts *collections.IndexedMap[sdk.AccAddress, sdk.AccountI, AccountsIndexes] } var _ AccountKeeperI = &AccountKeeper{} diff --git a/x/distribution/keeper/keeper.go b/x/distribution/keeper/keeper.go index 9ef16d820ef9..9748b280487f 100644 --- a/x/distribution/keeper/keeper.go +++ b/x/distribution/keeper/keeper.go @@ -29,17 +29,24 @@ type Keeper struct { // should be the x/gov module account. authority string - Schema collections.Schema - Params collections.Item[types.Params] - FeePool collections.Item[types.FeePool] - DelegatorsWithdrawAddress collections.Map[sdk.AccAddress, sdk.AccAddress] - ValidatorCurrentRewards collections.Map[sdk.ValAddress, types.ValidatorCurrentRewards] - DelegatorStartingInfo collections.Map[collections.Pair[sdk.ValAddress, sdk.AccAddress], types.DelegatorStartingInfo] + Schema collections.Schema + Params collections.Item[types.Params] + FeePool collections.Item[types.FeePool] + // DelegatorsWithdrawAddress key: delAddr | value: withdrawAddr + DelegatorsWithdrawAddress collections.Map[sdk.AccAddress, sdk.AccAddress] + // ValidatorCurrentRewards key: valAddr | value: ValidatorCurrentRewards + ValidatorCurrentRewards collections.Map[sdk.ValAddress, types.ValidatorCurrentRewards] + // DelegatorStartingInfo key: valAddr+delAccAddr | value: DelegatorStartingInfo + DelegatorStartingInfo collections.Map[collections.Pair[sdk.ValAddress, sdk.AccAddress], types.DelegatorStartingInfo] + // ValidatorsAccumulatedCommission key: valAddr | value: ValidatorAccumulatedCommission ValidatorsAccumulatedCommission collections.Map[sdk.ValAddress, types.ValidatorAccumulatedCommission] - ValidatorOutstandingRewards collections.Map[sdk.ValAddress, types.ValidatorOutstandingRewards] - ValidatorHistoricalRewards collections.Map[collections.Pair[sdk.ValAddress, uint64], types.ValidatorHistoricalRewards] - PreviousProposer collections.Item[sdk.ConsAddress] - ValidatorSlashEvents collections.Map[collections.Triple[sdk.ValAddress, uint64, uint64], types.ValidatorSlashEvent] // key is valAddr, height, period + // ValidatorOutstandingRewards key: valAddr | value: ValidatorOustandingRewards + ValidatorOutstandingRewards collections.Map[sdk.ValAddress, types.ValidatorOutstandingRewards] + // ValidatorHistoricalRewards key: valAddr+period | value: ValidatorHistoricalRewards + ValidatorHistoricalRewards collections.Map[collections.Pair[sdk.ValAddress, uint64], types.ValidatorHistoricalRewards] + PreviousProposer collections.Item[sdk.ConsAddress] + // ValidatorSlashEvents key: valAddr+height+period | value: ValidatorSlashEvent + ValidatorSlashEvents collections.Map[collections.Triple[sdk.ValAddress, uint64, uint64], types.ValidatorSlashEvent] feeCollectorName string // name of the FeeCollector ModuleAccount } diff --git a/x/evidence/keeper/keeper.go b/x/evidence/keeper/keeper.go index 399ca5db0d2e..74f4d6f393f7 100644 --- a/x/evidence/keeper/keeper.go +++ b/x/evidence/keeper/keeper.go @@ -32,7 +32,8 @@ type Keeper struct { cometInfo comet.BlockInfoService - Schema collections.Schema + Schema collections.Schema + // Evidences key: evidence hash bytes | value: Evidence Evidences collections.Map[[]byte, exported.Evidence] } diff --git a/x/feegrant/keeper/keeper.go b/x/feegrant/keeper/keeper.go index e7322dff5627..94f486383f26 100644 --- a/x/feegrant/keeper/keeper.go +++ b/x/feegrant/keeper/keeper.go @@ -22,11 +22,13 @@ import ( // Keeper manages state of all fee grants, as well as calculating approval. // It must have a codec with all available allowances registered. type Keeper struct { - cdc codec.BinaryCodec - storeService store.KVStoreService - authKeeper feegrant.AccountKeeper - Schema collections.Schema - FeeAllowance collections.Map[collections.Pair[sdk.AccAddress, sdk.AccAddress], feegrant.Grant] + cdc codec.BinaryCodec + storeService store.KVStoreService + authKeeper feegrant.AccountKeeper + Schema collections.Schema + // FeeAllowance key: grantee+granter | value: Grant + FeeAllowance collections.Map[collections.Pair[sdk.AccAddress, sdk.AccAddress], feegrant.Grant] + // FeeAllowanceQueue key: expiration time+grantee+granter | value: bool FeeAllowanceQueue collections.Map[collections.Triple[time.Time, sdk.AccAddress, sdk.AccAddress], bool] } diff --git a/x/gov/keeper/keeper.go b/x/gov/keeper/keeper.go index 9b2cab294276..4081d46d9612 100644 --- a/x/gov/keeper/keeper.go +++ b/x/gov/keeper/keeper.go @@ -47,16 +47,22 @@ type Keeper struct { // should be the x/gov module account. authority string - Schema collections.Schema - Constitution collections.Item[string] - Params collections.Item[v1.Params] - Deposits collections.Map[collections.Pair[uint64, sdk.AccAddress], v1.Deposit] - Votes collections.Map[collections.Pair[uint64, sdk.AccAddress], v1.Vote] - ProposalID collections.Sequence - Proposals collections.Map[uint64, v1.Proposal] - ActiveProposalsQueue collections.Map[collections.Pair[time.Time, uint64], uint64] // TODO(tip): this should be simplified and go into an index. + Schema collections.Schema + Constitution collections.Item[string] + Params collections.Item[v1.Params] + // Deposits key: proposalID+depositorAddr | value: Deposit + Deposits collections.Map[collections.Pair[uint64, sdk.AccAddress], v1.Deposit] + // Votes key: proposalID+voterAddr | value: Vote + Votes collections.Map[collections.Pair[uint64, sdk.AccAddress], v1.Vote] + ProposalID collections.Sequence + // Proposals key:proposalID | value: Proposal + Proposals collections.Map[uint64, v1.Proposal] + // ActiveProposalsQueue key: votingEndTime+proposalID | value: proposalID + ActiveProposalsQueue collections.Map[collections.Pair[time.Time, uint64], uint64] // TODO(tip): this should be simplified and go into an index. + // InactiveProposalsQueue key: depositEndTime+proposalID | value: proposalID InactiveProposalsQueue collections.Map[collections.Pair[time.Time, uint64], uint64] // TODO(tip): this should be simplified and go into an index. - VotingPeriodProposals collections.Map[uint64, []byte] // TODO(tip): this could be a keyset or index. + // VotingPeriodProposals key: proposalID | value: proposalStatus (votingPeriod or not) + VotingPeriodProposals collections.Map[uint64, []byte] // TODO(tip): this could be a keyset or index. } // GetAuthority returns the x/gov module's authority. diff --git a/x/slashing/keeper/keeper.go b/x/slashing/keeper/keeper.go index f0d33a896711..e0fbac167576 100644 --- a/x/slashing/keeper/keeper.go +++ b/x/slashing/keeper/keeper.go @@ -25,11 +25,14 @@ type Keeper struct { // the address capable of executing a MsgUpdateParams message. Typically, this // should be the x/gov module account. - authority string - Schema collections.Schema - Params collections.Item[types.Params] - ValidatorSigningInfo collections.Map[sdk.ConsAddress, types.ValidatorSigningInfo] - AddrPubkeyRelation collections.Map[[]byte, cryptotypes.PubKey] + authority string + Schema collections.Schema + Params collections.Item[types.Params] + // ValidatorSigningInfo key: ConsAddr | value: ValidatorSigningInfo + ValidatorSigningInfo collections.Map[sdk.ConsAddress, types.ValidatorSigningInfo] + // AddrPubkeyRelation key: address | value: PubKey + AddrPubkeyRelation collections.Map[[]byte, cryptotypes.PubKey] + // ValidatorMissedBlockBitmap key: ConsAddr | value: byte key for a validator's missed block bitmap chunk ValidatorMissedBlockBitmap collections.Map[collections.Pair[[]byte, uint64], []byte] } diff --git a/x/staking/keeper/keeper.go b/x/staking/keeper/keeper.go index 2221feab94c8..255dafcb1bf6 100644 --- a/x/staking/keeper/keeper.go +++ b/x/staking/keeper/keeper.go @@ -36,24 +36,40 @@ type Keeper struct { validatorAddressCodec addresscodec.Codec consensusAddressCodec addresscodec.Codec - Schema collections.Schema - HistoricalInfo collections.Map[uint64, types.HistoricalInfo] - LastTotalPower collections.Item[math.Int] - ValidatorUpdates collections.Item[types.ValidatorUpdates] - DelegationsByValidator collections.Map[collections.Pair[sdk.ValAddress, sdk.AccAddress], []byte] - UnbondingID collections.Sequence - ValidatorByConsensusAddress collections.Map[sdk.ConsAddress, sdk.ValAddress] - UnbondingType collections.Map[uint64, uint64] - Redelegations collections.Map[collections.Triple[[]byte, []byte, []byte], types.Redelegation] - Delegations collections.Map[collections.Pair[sdk.AccAddress, sdk.ValAddress], types.Delegation] - UnbondingIndex collections.Map[uint64, []byte] - UnbondingQueue collections.Map[time.Time, types.DVPairs] - Validators collections.Map[[]byte, types.Validator] - UnbondingDelegations collections.Map[collections.Pair[[]byte, []byte], types.UnbondingDelegation] - RedelegationsByValDst collections.Map[collections.Triple[[]byte, []byte, []byte], []byte] - RedelegationsByValSrc collections.Map[collections.Triple[[]byte, []byte, []byte], []byte] + Schema collections.Schema + // HistoricalInfo key: Height | value: HistoricalInfo + HistoricalInfo collections.Map[uint64, types.HistoricalInfo] + // LastTotalPower value: LastTotalPower + LastTotalPower collections.Item[math.Int] + // ValidatorUpdates value: ValidatorUpdates + ValidatorUpdates collections.Item[types.ValidatorUpdates] + // DelegationsByValidator key: valAddr+delAddr | value: none used (index key for delegations by validator index) + DelegationsByValidator collections.Map[collections.Pair[sdk.ValAddress, sdk.AccAddress], []byte] + UnbondingID collections.Sequence + // ValidatorByConsensusAddress key: consAddr | value: valAddr + ValidatorByConsensusAddress collections.Map[sdk.ConsAddress, sdk.ValAddress] + // UnbondingType key: unbondingID | value: index of UnbondingType + UnbondingType collections.Map[uint64, uint64] + // Redelegations key: AccAddr+SrcValAddr+DstValAddr | value: Redelegation + Redelegations collections.Map[collections.Triple[[]byte, []byte, []byte], types.Redelegation] + // Delegations key: AccAddr+valAddr | value: Delegation + Delegations collections.Map[collections.Pair[sdk.AccAddress, sdk.ValAddress], types.Delegation] + // UnbondingIndex key:UnbondingID | value: ubdKey (ubdKey = [UnbondingDelegationKey(Prefix)+len(delAddr)+delAddr+len(valAddr)+valAddr]) + UnbondingIndex collections.Map[uint64, []byte] + // UnbondingQueue key: Timestamp | value: DVPairs [delAddr+valAddr] + UnbondingQueue collections.Map[time.Time, types.DVPairs] + // Validators key: valAddr | value: Validator + Validators collections.Map[[]byte, types.Validator] + // UnbondingDelegations key: delAddr+valAddr | value: UnbondingDelegation + UnbondingDelegations collections.Map[collections.Pair[[]byte, []byte], types.UnbondingDelegation] + // RedelegationsByValDst key: DstValAddr+DelAccAddr+SrcValAddr | value: none used (index key for Redelegations stored by DstVal index) + RedelegationsByValDst collections.Map[collections.Triple[[]byte, []byte, []byte], []byte] + // RedelegationsByValSrc key: SrcValAddr+DelAccAddr+DstValAddr | value: none used (index key for Redelegations stored by SrcVal index) + RedelegationsByValSrc collections.Map[collections.Triple[[]byte, []byte, []byte], []byte] + // UnbondingDelegationByValIndex key: valAddr+delAddr | value: none used (index key for UnbondingDelegations stored by validator index) UnbondingDelegationByValIndex collections.Map[collections.Pair[[]byte, []byte], []byte] - LastValidatorPower collections.Map[[]byte, gogotypes.Int64Value] + // LastValidatorPower key: valAddr | value: power(gogotypes.Int64Value()) + LastValidatorPower collections.Map[[]byte, gogotypes.Int64Value] } // NewKeeper creates a new staking Keeper instance