signal

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-010.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

• func Threshold(_ uint64) math.LegacyDec
• func VersionFromBytes(version []byte) uint64
• func VersionToBytes(version uint64) []byte
• type AppModule
  • func NewAppModule(k Keeper) AppModule
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) DefaultGenesis(_ codec.JSONCodec) json.RawMessage
  • func (AppModule) GetQueryCmd() *cobra.Command
  • func (AppModule) GetTxCmd() *cobra.Command
  • func (AppModule) IsAppModule()
  • func (AppModule) IsOnePerModuleType()
  • func (AppModule) Name() string
  • func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)
  • func (AppModule) RegisterInterfaces(reg cdctypes.InterfaceRegistry)
  • func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
  • func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error
  • func (am AppModule) ValidateGenesis(_ codec.JSONCodec, _ client.TxEncodingConfig, _ json.RawMessage) error
• type Keeper
  • func NewKeeper(binaryCodec codec.BinaryCodec, storeKey storetypes.StoreKey, ...) Keeper
  • func (k Keeper) DeleteValidatorVersion(ctx sdk.Context, valAddress sdk.ValAddress)
  • func (k Keeper) GetUpgrade(ctx context.Context, _ *types.QueryGetUpgradeRequest) (*types.QueryGetUpgradeResponse, error)
  • func (k Keeper) GetVotingPowerThreshold(ctx sdk.Context) (math.Int, error)
  • func (k *Keeper) IsUpgradePending(ctx sdk.Context) bool
  • func (k *Keeper) ResetTally(ctx sdk.Context)
  • func (k Keeper) SetValidatorVersion(ctx sdk.Context, valAddress sdk.ValAddress, version uint64)
  • func (k *Keeper) ShouldUpgrade(ctx sdk.Context) (isQuorumVersion bool, upgrade types.Upgrade)
  • func (k Keeper) SignalVersion(ctx context.Context, req *types.MsgSignalVersion) (*types.MsgSignalVersionResponse, error)
  • func (k Keeper) TallyVotingPower(ctx sdk.Context, threshold int64) (bool, uint64, error)
  • func (k *Keeper) TryUpgrade(ctx context.Context, _ *types.MsgTryUpgrade) (*types.MsgTryUpgradeResponse, error)
  • func (k Keeper) VersionTally(ctx context.Context, req *types.QueryVersionTallyRequest) (*types.QueryVersionTallyResponse, error)
• type StakingKeeper

Functions

func Threshold

func Threshold(_ uint64) math.LegacyDec

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 {
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the blobstream module.

func NewAppModule

func NewAppModule(k Keeper) AppModule

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion returns the consensus version of this module.

func (AppModule) DefaultGenesis

func (am AppModule) DefaultGenesis(_ codec.JSONCodec) json.RawMessage

DefaultGenesis returns the blob module's default genesis state.

func (AppModule) GetQueryCmd

func (AppModule) GetQueryCmd() *cobra.Command

GetQueryCmd returns the CLI query commands for this module. TODO(@julienrbrt): Use AutoCLI

func (AppModule) GetTxCmd

func (AppModule) GetTxCmd() *cobra.Command

GetTxCmd returns the CLI transaction commands for this module.

func (AppModule) IsAppModule

func (AppModule) IsAppModule()

func (AppModule) IsOnePerModuleType

func (AppModule) IsOnePerModuleType()

func (AppModule) Name

func (AppModule) Name() string

Name returns the ModuleName

func (AppModule) RegisterGRPCGatewayRoutes

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

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the upgrade module.

func (AppModule) RegisterInterfaces

func (AppModule) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers interfaces and implementations of the blob module.

func (AppModule) RegisterLegacyAminoCodec

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

RegisterLegacyAminoCodec registers the blob module's types on the LegacyAmino codec.

func (AppModule) RegisterServices

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

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

func (AppModule) ValidateGenesis

func (am AppModule) 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) (math.Int, error)

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, upgrade types.Upgrade)

ShouldUpgrade returns whether the signalling mechanism has concluded that the network is ready to upgrade and the upgrade. It returns false and an empty upgrade 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, error)

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 context.Context, addr sdk.ValAddress) (int64, error)
	GetLastTotalPower(ctx context.Context) (math.Int, error)
	GetValidator(ctx context.Context, addr sdk.ValAddress) (validator stakingtypes.Validator, err error)
}