epochs

README

---

sidebar_position: 1

x/epochs

Abstract

Often in the SDK, we would like to run certain code every-so often. The purpose of epochs module is to allow other modules to set that they would like to be signaled once every period. So another module can specify it wants to execute code once a week, starting at UTC-time = x. epochs creates a generalized epoch interface to other modules so that they can easily be signaled upon such events.

Contents

1. Concept
2. State
3. Events
4. Keeper
5. Hooks
6. Queries

Concepts

The epochs module defines on-chain timers that execute at fixed time intervals. Other SDK 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. Every epoch will have a start time, and an end time, where end time = start time + timer interval. On mainnet, we only utilize one identifier, with a time interval of one day.

The timer will tick at the first block whose block time is greater than the timer end time, and set the start as the prior timer end time. (Notably, it's not set to the block time!) This means that if the chain has been down for a while, you will get one timer tick per block, until the timer has caught up.

State

The Epochs module keeps a single EpochInfo per identifier. This contains the current state of the timer with the corresponding identifier. Its fields are modified at every timer tick. EpochInfos are initialized as part of genesis initialization or upgrade logic, and are only modified on begin blockers.

Events

The 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

Keeper functions

Epochs keeper module provides utility functions to manage epochs.

Hooks

  // the first block whose timestamp is after the duration is counted as the end of the epoch
  AfterEpochEnd(ctx sdk.Context, epochIdentifier string, epochNumber int64)
  // new epoch is next block of epoch end block
  BeforeEpochStart(ctx sdk.Context, epochIdentifier string, epochNumber int64)

How modules receive hooks

On hook receiver function of other modules, they need to filter epochIdentifier and only do executions for only specific epochIdentifier. Filtering epochIdentifier could be in Params of other modules so that they can be modified by governance.

This is the standard dev UX of this:

func (k MyModuleKeeper) AfterEpochEnd(ctx sdk.Context, epochIdentifier string, epochNumber int64) {
    params := k.GetParams(ctx)
    if epochIdentifier == params.DistrEpochIdentifier {
    // my logic
  }
}

Panic isolation

If a given epoch hook panics, its state update is reverted, but we keep proceeding through the remaining hooks. This allows more advanced epoch logic to be used, without concern over state machine halting, or halting subsequent modules.

This does mean that if there is behavior you expect from a prior epoch hook, and that epoch hook reverted, your hook may also have an issue. So do keep in mind "what if a prior hook didn't get executed" in the safety checks you consider for a new epoch hook.

Queries

The 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) {}
}

Epoch Infos

Query the currently running epochInfos

<appd> query epochs epoch-infos

:::details Example

An example output:

epochs:
- current_epoch: "183"
  current_epoch_start_height: "2438409"
  current_epoch_start_time: "2021-12-18T17:16:09.898160996Z"
  duration: 86400s
  epoch_counting_started: true
  identifier: day
  start_time: "2021-06-18T17:00:00Z"
- current_epoch: "26"
  current_epoch_start_height: "2424854"
  current_epoch_start_time: "2021-12-17T17:02:07.229632445Z"
  duration: 604800s
  epoch_counting_started: true
  identifier: week
  start_time: "2021-06-18T17:00:00Z"

:::

Current Epoch

Query the current epoch by the specified identifier

<appd> query epochs current-epoch [identifier]

:::details Example

Query the current day epoch:

<appd> query epochs current-epoch day

Which in this example outputs:

current_epoch: "183"

:::

Documentation

Index

• Constants
• func InvokeSetHooks(keeper *keeper.Keeper, hooks map[string]types.EpochHooksWrapper) error
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper *keeper.Keeper) AppModule
  • func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
  • func (am AppModule) BeginBlock(ctx context.Context) error
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) DefaultGenesis() json.RawMessage
  • func (am AppModule) ExportGenesis(ctx context.Context) (json.RawMessage, error)
  • func (AppModule) GenerateGenesisState(simState *module.SimulationState)
  • func (am AppModule) InitGenesis(ctx context.Context, bz json.RawMessage) error
  • func (am AppModule) IsAppModule()
  • func (am AppModule) IsOnePerModuleType()
  • func (am AppModule) ModuleCodec() (schema.ModuleCodec, error)
  • func (AppModule) Name() string
  • func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
  • func (AppModule) RegisterLegacyAminoCodec(registrar registry.AminoRegistrar)
  • func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error
  • func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)
  • func (am AppModule) ValidateGenesis(bz json.RawMessage) error
• type ModuleInputs
• type ModuleOutputs
  • func ProvideModule(in ModuleInputs) ModuleOutputs

Constants

const ConsensusVersion = 1

Functions

func InvokeSetHooks

func InvokeSetHooks(keeper *keeper.Keeper, hooks map[string]types.EpochHooksWrapper) error

Types

type AppModule

type AppModule struct {
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the epochs module.

func NewAppModule

func NewAppModule(cdc codec.Codec, keeper *keeper.Keeper) AppModule

NewAppModule creates a new AppModule object.

func (AppModule) AutoCLIOptions

func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions

AutoCLIOptions implements the autocli.HasAutoCLIConfig interface.

func (AppModule) BeginBlock

func (am AppModule) BeginBlock(ctx context.Context) error

BeginBlock executes all ABCI BeginBlock logic respective to the epochs module.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements HasConsensusVersion

func (AppModule) DefaultGenesis

func (am AppModule) DefaultGenesis() json.RawMessage

DefaultGenesis returns the epochs module's default genesis state.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx context.Context) (json.RawMessage, error)

ExportGenesis returns the epochs module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the epochs module.

func (AppModule) InitGenesis

func (am AppModule) InitGenesis(ctx context.Context, bz json.RawMessage) error

InitGenesis performs the epochs module's genesis initialization

func (AppModule) IsAppModule

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) ModuleCodec

func (am AppModule) ModuleCodec() (schema.ModuleCodec, error)

ModuleCodec implements schema.HasModuleCodec. It allows the indexer to decode the module's KVPairUpdate.

func (AppModule) Name

func (AppModule) Name() string

Name returns the epochs module's name. Deprecated: kept for legacy reasons.

func (AppModule) RegisterGRPCGatewayRoutes

func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the epochs module.

func (AppModule) RegisterLegacyAminoCodec

func (AppModule) RegisterLegacyAminoCodec(registrar registry.AminoRegistrar)

RegisterLegacyAminoCodec registers the epochs module's types for the given codec.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error

RegisterServices registers module services.

func (AppModule) RegisterStoreDecoder

func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder for epochs module's types

func (AppModule) ValidateGenesis

func (am AppModule) ValidateGenesis(bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the epochs module.

type ModuleInputs

type ModuleInputs struct {
	depinject.In

	Config      *modulev1.Module
	Cdc         codec.Codec
	Environment appmodule.Environment
}

type ModuleOutputs

type ModuleOutputs struct {
	depinject.Out

	EpochKeeper *keeper.Keeper
	Module      appmodule.AppModule
}

func ProvideModule

func ProvideModule(in ModuleInputs) ModuleOutputs