epochs

package
v2.0.0-rc.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

epochs

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 signalled upon such events.

Contents

Concepts

The purpose of epochs module is to provide generalized epoch interface to other modules so that they can easily implement epochs without keeping own code for epochs.

State

Epochs module keeps EpochInfo objects and modify the information as epochs info changes. Epochs are initialized as part of genesis initialization, and modified on begin blockers or end blockers.

Epoch information type
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;
}

EpochInfo keeps identifier, start_time,duration, current_epoch, current_epoch_start_time, epoch_counting_started, current_epoch_start_height.

  1. identifier keeps epoch identification string.
  2. start_time keeps epoch counting start time, if block time passes start_time, epoch_counting_started is set.
  3. duration keeps target epoch duration.
  4. current_epoch keeps current active epoch number.
  5. current_epoch_start_time keeps the start time of current epoch.
  6. epoch_number is counted only when epoch_counting_started flag is set.
  7. current_epoch_start_height keeps the start block height of current epoch.

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.

// 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
  // 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

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. Governance can change epoch from week to day as their need.

Queries

Epochs module is providing below queries to check the module's state.

service Query {
  // EpochInfos provide running epochInfos
  rpc EpochInfos(QueryEpochInfosRequest) returns (QueryEpochInfosResponse) {}
  // CurrentEpoch provide current epoch of specified identifier
  rpc CurrentEpoch(QueryCurrentEpochRequest) returns (QueryCurrentEpochResponse) {}
}

Future Improvements

Lack point using this module

In current design each epoch should be at least 2 blocks as start block should be different from endblock. Because of this, each epoch time will be max(blocks_time x 2, epoch_duration). If epoch_duration is set to 1s, and block_time is 5s, actual epoch time should be 10s. We definitely recommend configure epoch_duration as more than 2x block_time, to use this module correctly. If you enforce to set it to 1s, it's same as 10s - could make module logic invalid.

TODO for postlaunch: We should see if we can architect things such that the receiver doesn't have to do this filtering, and the epochs module would pre-filter for them.

Block-time drifts problem

This implementation has block time drift based on block time. For instance, we have an epoch of 100 units that ends at t=100, if we have a block at t=97 and a block at t=104 and t=110, this epoch ends at t=104. And new epoch start at t=110. There are time drifts here, for around 1-2 blocks time. It will slow down epochs.

It's going to slow down epoch by 10-20s per week when epoch duration is 1 week. This should be resolved after launch.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeginBlocker 

func BeginBlocker(ctx sdk.Context, k keeper.Keeper)

BeginBlocker of epochs module.

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis 

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState) (err error)

InitGenesis sets epoch info from genesis

Types

type AppModule 

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

AppModule implements the AppModule interface for the capability module.

func NewAppModule 

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

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(ctx sdk.Context, _ abci.RequestBeginBlock)

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

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) EndBlock 

func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability 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 sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(simState module.SimulationState) []simtypes.WeightedProposalMsg

ProposalContents doesn't return any content functions for governance proposals.

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder 

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

RegisterStoreDecoder registers a decoder for supply module's types.

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

type AppModuleBasic 

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

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic 

func NewAppModuleBasic(cdc codec.Codec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types.

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
rest
integration
action
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.