Epochs
Abstract
This document specifies the internal x/epochs
module of the HAQQ Network.
Often, when working with the Cosmos SDK, we would like to run certain pieces of code every so often.
The purpose of the epochs
module is to allow other modules to maintain that they would like to be signaled
once in a time period. So, another module can specify it wants to execute certain code once a week,
starting at UTC-time = x. epochs
creates a generalized epoch interface to other modules so they can be more
easily signaled upon such events.
Contents
Module Architecture
If you're not familiar with the overall module structure from the SDK modules, please check this document as prerequisite reading.
epochs/
├── client
│ └── cli
│ └── query.go # CLI query commands for the module
├── keeper
│ ├── abci.go # ABCI BeginBlock and EndBlock logic
│ ├── epoch_infos.go # Store state functions of the module
│ ├── grpc_query.go # gRPC state query handlers
│ ├── hooks.go # Hook functions of the module
│ └── keeper.go # Store keeper that handles the business logic of the module and has access to a specific subtree of the state tree.
├── types
│ ├── codec.go # Type registration for encoding
│ ├── epoch_info.go # Utility functions for the EpochInfo struct
│ ├── events.go # Events exposed to the CometBFT PubSub/Websocket
│ ├── genesis.go # Genesis state for the module
│ ├── identifier.go # The pre-defined IDs and utility functions for epochs
│ ├── interfaces.go # The interfaces describing the components of the required modules
│ └── keys.go # Store keys and utility functions
├── genesis.go # ABCI InitGenesis and ExportGenesis functionality
└── module.go # Module setup for the module manager
Concept
The epochs
module defines on-chain timers that execute at fixed time intervals. Other HAQQ modules can then register
logic to be executed at the timer ticks. We refer to the period in between two timer ticks as an "epoch".
Every timer has a unique identifier, and every epoch will have a start time and an end time,
where end time = start time + timer interval
.
State
State Objects
The x/epochs
module keeps the following objects in state
:
State Object | Description | Key | Value | Store |
---|---|---|---|---|
EpochInfo | Epoch info bytecode | []byte{identifier} | []byte{epochInfo} | KV |
EpochInfo
An EpochInfo
defines several variables:
identifier
keeps an epoch identification stringstart_time
keeps the start time for epoch counting: if block height passesstart_time
, thenepoch_counting_started
is setduration
keeps the target epoch durationcurrent_epoch
keeps the current active epoch numbercurrent_epoch_start_time
keeps the start time of the current epochepoch_counting_started
is a flag set withstart_time
, at which pointepoch_number
will be countedcurrent_epoch_start_height
keeps the start block height of the current epoch
message EpochInfo {
string identifier = 1;
google.protobuf.Timestamp start_time = 2 [
(gogoproto.stdtime) = true,
(gogoproto.nullable) = false,
(gogoproto.moretags) = "yaml:\"start_time\""
];
google.protobuf.Duration duration = 3 [
(gogoproto.nullable) = false,
(gogoproto.stdduration) = true,
(gogoproto.jsontag) = "duration,omitempty",
(gogoproto.moretags) = "yaml:\"duration\""
];
int64 current_epoch = 4;
google.protobuf.Timestamp current_epoch_start_time = 5 [
(gogoproto.stdtime) = true,
(gogoproto.nullable) = false,
(gogoproto.moretags) = "yaml:\"current_epoch_start_time\""
];
bool epoch_counting_started = 6;
reserved 7;
int64 current_epoch_start_height = 8;
}
The epochs
module keeps these EpochInfo
objects in state, which are initialized at genesis and are modified
on begin blockers or end blockers.
Genesis State
The x/epochs
module's GenesisState
defines the state necessary for initializing the chain from a previously
exported height. It contains a slice containing all the EpochInfo
objects kept in state:
// Genesis State defines the epoch module's genesis state
type GenesisState struct {
// list of EpochInfo structs corresponding to all epochs
Epochs []EpochInfo `protobuf:"bytes,1,rep,name=epochs,proto3" json:"epochs"`
}
Events
The x/epochs
module emits the following events:
BeginBlocker
Type | Attribute Key | Attribute Value |
---|---|---|
epoch_start | "epoch_number" | {epoch_number} |
epoch_start | "start_time" | {start_time} |
EndBlocker
Type | Attribute Key | Attribute Value |
---|---|---|
epoch_end | "epoch_number" | {epoch_number} |
Keepers
The x/epochs
module only exposes one keeper, the epochs keeper, which can be used to manage epochs.
Epochs Keeper
Presently only one fully-permissioned epochs keeper is exposed, which has the ability to both read and write
the EpochInfo
for all epochs, and to iterate over all stored epochs.
// Keeper of epoch nodule maintains collections of epochs and hooks.
type Keeper struct {
cdc codec.Codec
storeKey storetypes.StoreKey
hooks types.EpochHooks
}
// Keeper is the interface for epoch module keeper
type Keeper interface {
// GetEpochInfo returns epoch info by identifier
GetEpochInfo(ctx sdk.Context, identifier string) (types.EpochInfo, bool)
// SetEpochInfo set epoch info
SetEpochInfo(ctx sdk.Context, epoch types.EpochInfo)
// DeleteEpochInfo delete epoch info
DeleteEpochInfo(ctx sdk.Context, identifier string)
// IterateEpochInfo iterate through epochs
IterateEpochInfo(ctx sdk.Context, fn func(index int64, epochInfo types.EpochInfo) (stop bool))
// Get all epoch infos
AllEpochInfos(ctx sdk.Context) []types.EpochInfo
}
Hooks
The x/epochs
module implements hooks so that other modules can use epochs to allow facets of
the Cosmos SDK to run on specific schedules.
Hooks Implementation
// combine multiple epoch hooks, all hook functions are run in array sequence
type MultiEpochHooks []types.EpochHooks
// AfterEpochEnd is called when epoch is going to be ended, epochNumber is the
// number of epoch that is ending
func (mh MultiEpochHooks) AfterEpochEnd(ctx sdk.Context, epochIdentifier string, epochNumber int64) {...}
// BeforeEpochStart is called when epoch is going to be started, epochNumber is
// the number of epoch that is starting
func (mh MultiEpochHooks) BeforeEpochStart(ctx sdk.Context, epochIdentifier string, epochNumber int64) {...}
// AfterEpochEnd executes the indicated hook after epochs ends
func (k Keeper) AfterEpochEnd(ctx sdk.Context, identifier string, epochNumber int64) {...}
// BeforeEpochStart executes the indicated hook before the epochs
func (k Keeper) BeforeEpochStart(ctx sdk.Context, identifier string, epochNumber int64) {...}
Receiving Hooks
When other modules (outside of x/epochs
) receive hooks, they need to filter the value epochIdentifier
,
and only do executions for a specific epochIdentifier
.
The filtered values from epochIdentifier
could be stored in the Params
of other modules, so they can be modified
by governance.
Governance can change epoch periods from week
to day
as needed.
Queries
The x/epochs
module provides the following queries to check the module's state.
service Query {
// EpochInfos provide running epochInfos
rpc EpochInfos(QueryEpochsInfoRequest) returns (QueryEpochsInfoResponse) {}
// CurrentEpoch provide current epoch of specified identifier
rpc CurrentEpoch(QueryCurrentEpochRequest) returns (QueryCurrentEpochResponse) {}
}
Future Improvements
Correct Usage
In the current design, each epoch should be at least two blocks, as the start block should be different from the end block.
Because of this, the time allocated to each epoch will be max(block_time x 2, epoch_duration)
.
For example: if the epoch_duration
is set to 1s
, and block_time
is 5s
, actual epoch time should be 10s
.
It is recommended to configure epoch_duration
to be more than two times the block_time
, to use this module correctly.
If there is a mismatch between the epoch_duration
and the actual epoch time, as in the example above, then module
logic could become invalid.
Block-Time Drifts
This implementation of the x/epochs
module has block-time drifts based on the value of block_time
.
For example: if we have an epoch of 100 units that ends at t=100
, and we have a block at t=97
and a block
at t=104
and t=110
, this epoch ends at t=104
, and the new epoch will start at t=110
.
There are time drifts here, varying about 1-2 blocks time, which will slow down epochs.