Document iteration function code structure we intend to use

[colin-axner]

Summary

Document the format we intend to have for our keeper iteration functions which allows for optmization and reuse outside of the keeper.

The format decided on was implemented for IterateClientStates in this pr. See the top comment:

After discussion with @chatton, we decided every key/value set in our stores should have a corresponding Iterate function. That is IterateClientStates, IterateConsensusStates, etc. These should take in a prefix to determine the starting point of the iteration (allows to limit unnecessary iterations) and a callback which can accrue the desired values and exit iteration early based on optimizations. This PR renames IterateClients to IterateClientStates and adds the prefix necessary for optimized iteration

The idea is that for every key path we store, there should be an associated iteration function. This function should take in a prefix and a callback. It should begin iteration at the top level of the store. It should parse any necessary information from the key and value and then perform a callback (given a provided function by the caller). This will allow for optimized iteration in a generic enough format that the caller can perform specific iteration (such as iterating over a client type) without adding an additional function into the keeper

Each function should look similar to:

func (k Keeper) Iterate<KeyName>(ctx sdk.Context, prefix []byte, cb func(key Key, value Value) bool) {
	store := ctx.KVStore(k.storeKey)
	iterator := sdk.KVStorePrefixIterator(store, PrefixedStoreKey(prefix))

	defer iterator.Close()
	for ; iterator.Valid(); iterator.Next() {
		path := string(iterator.Key())
		if !strings.Contains(path, <KeyName>) {
			// skip non non matching keys
			continue
		}

		key := host.MustParseKeyh(path)
		value := k.MustUnmarshalValue(iterator.Value())

		if cb(key, value) {
			break
		}
	}
}

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged/assigned

[colin-axner]

Going to close as stale. Issue hasn't arisen since we ran into this