signal

package
v3.0.1 Latest Latest
Warning

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

 Go to latest Published: Nov 22, 2024 License: Apache-2.0 Imports: 17 Imported by: 0

README

x/signal

The signal module acts as a coordinating mechanism for the application on when it should transition from one app version to another. The application itself handles multiple versioned modules as well as migrations, however it requires some protocol for knowing which height to perform this upgrade as it is critical that all nodes upgrade at the same point.

Note: this module won't be used for upgrading from app version v1 to v2 but will be used for upgrading from v2 to v3 and onwards.

Concepts

  • Total voting power: The sum of voting power for all validators.
  • Voting power threshold: The amount of voting power that needs to signal for a particular version for an upgrade to take place. This is a percentage of the total voting power (usually 5/6).

State

This module persists a map in state from validator address to version that they are signalling for.

State Transitions

The map from validator address to version is updated when a validator signals for a version (SignalVersion) and after an upgrade takes place (ResetTally).

Messages

See types/msgs.go for the message types.

Client

CLI
celestia-appd query signal tally
celestia-appd tx signal signal
celestia-appd tx signal try-upgrade
gRPC
celestia.signal.v1.Query/VersionTally

grpcurl -plaintext localhost:9090 celestia.signal.v1.Query/VersionTally

Appendix

  1. https://github.com/celestiaorg/celestia-app/blob/main/docs/architecture/adr-018-network-upgrades.md
  2. https://github.com/celestiaorg/CIPs/blob/main/cips/cip-10.md
  3. https://github.com/cosmos/cosmos-sdk/blob/v0.46.15/x/upgrade/README.md
  4. https://github.com/cosmos/cosmos-sdk/blob/v0.46.15/x/gov/README.md

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Threshold 

func Threshold(_ uint64) sdk.Dec

Threshold is the fraction of voting power that is required to signal for a version change. It is set to 5/6 as the middle point between 2/3 and 3/3 providing 1/6 fault tolerance to halting the network during an upgrade period. It can be modified through a hard fork change that modified the app version

func VersionFromBytes 

func VersionFromBytes(version []byte) uint64

func VersionToBytes 

func VersionToBytes(version uint64) []byte

Types

type AppModule 

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

AppModule implements the sdk.AppModule interface

func NewAppModule 

func NewAppModule(keeper Keeper) AppModule

NewAppModule creates a new AppModule object

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion returns the consensus version of this module.

func (AppModule) ExportGenesis 

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

ExportGenesis is always empty, as InitGenesis does nothing either.

func (AppModule) InitGenesis 

func (AppModule) InitGenesis(_ sdk.Context, _ codec.JSONCodec, _ json.RawMessage) []abci.ValidatorUpdate

InitGenesis does nothing because there is no sense in serializing future upgrades.

func (AppModule) LegacyQuerierHandler 

func (AppModule) LegacyQuerierHandler(_ *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns nil because there are no legacy queriers.

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the query routing key used for ABCI queries.

func (AppModule) RegisterInvariants 

func (AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants does nothing because there are no invariants to enforce.

func (AppModule) RegisterServices 

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

RegisterServices registers module services.

func (AppModule) Route 

func (AppModule) Route() sdk.Route

Route returns an empty route for this module.

type AppModuleBasic 

type AppModuleBasic struct{}

AppModuleBasic implements the sdk.AppModuleBasic interface

func (AppModuleBasic) DefaultGenesis 

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

DefaultGenesis returns an empty object.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the CLI query commands for this module.

func (AppModuleBasic) GetTxCmd 

func (AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the CLI transaction commands for this module.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the ModuleName

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

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

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the upgrade module.

func (AppModuleBasic) RegisterInterfaces 

func (AppModuleBasic) RegisterInterfaces(registry codectypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types on the InterfaceRegistry.

func (AppModuleBasic) RegisterLegacyAminoCodec 

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

RegisterLegacyAminoCodec registers the upgrade types on the LegacyAmino codec

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(_ codec.JSONCodec, _ client.TxEncodingConfig, _ json.RawMessage) error

ValidateGenesis is always successful, as we ignore the value.

type Keeper 

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

func NewKeeper 

func NewKeeper(
	binaryCodec codec.BinaryCodec,
	storeKey storetypes.StoreKey,
	stakingKeeper StakingKeeper,
) Keeper

NewKeeper returns a signal keeper.

func (Keeper) DeleteValidatorVersion 

func (k Keeper) DeleteValidatorVersion(ctx sdk.Context, valAddress sdk.ValAddress)

DeleteValidatorVersion deletes a signalled version for a validator.

func (Keeper) GetUpgrade 

func (k Keeper) GetUpgrade(ctx context.Context, _ *types.QueryGetUpgradeRequest) (*types.QueryGetUpgradeResponse, error)

GetUpgrade returns the current upgrade information.

func (Keeper) GetVotingPowerThreshold 

func (k Keeper) GetVotingPowerThreshold(ctx sdk.Context) sdkmath.Int

GetVotingPowerThreshold returns the voting power threshold required to upgrade to a new version.

func (*Keeper) IsUpgradePending 

func (k *Keeper) IsUpgradePending(ctx sdk.Context) bool

IsUpgradePending returns true if an app version has reached quorum and the chain should upgrade to the app version at the upgrade height. While the keeper has an upgrade pending the SignalVersion and TryUpgrade messages will be rejected.

func (*Keeper) ResetTally 

func (k *Keeper) ResetTally(ctx sdk.Context)

ResetTally resets the tally after a version change. It iterates over the store and deletes all versions. It also resets the quorumVersion and upgradeHeight to 0.

func (Keeper) SetValidatorVersion 

func (k Keeper) SetValidatorVersion(ctx sdk.Context, valAddress sdk.ValAddress, version uint64)

SetValidatorVersion saves a signalled version for a validator.

func (*Keeper) ShouldUpgrade 

func (k *Keeper) ShouldUpgrade(ctx sdk.Context) (isQuorumVersion bool, version uint64)

ShouldUpgrade returns whether the signalling mechanism has concluded that the network is ready to upgrade and the version to upgrade to. It returns false and 0 if no version has reached quorum.

func (Keeper) SignalVersion 

func (k Keeper) SignalVersion(ctx context.Context, req *types.MsgSignalVersion) (*types.MsgSignalVersionResponse, error)

SignalVersion is a method required by the MsgServer interface.

func (Keeper) TallyVotingPower 

func (k Keeper) TallyVotingPower(ctx sdk.Context, threshold int64) (bool, uint64)

TallyVotingPower tallies the voting power for each version and returns true and the version if any version has reached the quorum in voting power. Returns false and 0 otherwise.

func (*Keeper) TryUpgrade 

func (k *Keeper) TryUpgrade(ctx context.Context, _ *types.MsgTryUpgrade) (*types.MsgTryUpgradeResponse, error)

TryUpgrade is a method required by the MsgServer interface. It tallies the voting power that has voted on each version. If one version has reached a quorum, an upgrade is persisted to the store. The upgrade is used by the application later when it is time to upgrade to that version.

func (Keeper) VersionTally 

func (k Keeper) VersionTally(ctx context.Context, req *types.QueryVersionTallyRequest) (*types.QueryVersionTallyResponse, error)

VersionTally enables a client to query for the tally of voting power has signalled for a particular version.

type StakingKeeper 

type StakingKeeper interface {
	GetLastValidatorPower(ctx sdk.Context, addr sdk.ValAddress) int64
	GetLastTotalPower(ctx sdk.Context) math.Int
	GetValidator(ctx sdk.Context, addr sdk.ValAddress) (validator stakingtypes.Validator, found bool)
}

Source Files

View all Source files

Directories

Path Synopsis
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.