docs: Add k/v docs in structs using collections (cosmos#17609)

notional-labs · Sep 4, 2023 · 9766142 · 9766142
1 parent eb85311
commit 9766142
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 48 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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