api

Documentation

Overview

Package api defines the interface exporting the upgrade infrastructure's functionality.

Index

• Constants
• type Descriptor
• type HandlerName
• type PendingUpgrade
• type UpgradeStage

Constants

const (
	// ModuleName is the upgrade module name.
	ModuleName = "upgrade"

	// LogEventIncompatibleBinary is a log event value that signals the currently running version
	// of the binary is incompatible with the upgrade.
	LogEventIncompatibleBinary = "upgrade/incompatible-binary"
	// LogEventStartupUpgrade is a log event value that signals the startup upgrade handler was
	// called.
	LogEventStartupUpgrade = "upgrade/startup-upgrade"
	// LogEventConsensusUpgrade is a log event value that signals the consensus upgrade handler was
	// called.
	LogEventConsensusUpgrade = "upgrade/consensus-upgrade"
)

const (
	// UpgradeStageStartup is the startup upgrade stage, executed at the beginning of node startup.
	UpgradeStageStartup UpgradeStage = 1

	// UpgradeStageConsensus is the upgrade stage carried out during consensus events.
	UpgradeStageConsensus UpgradeStage = 2

	// InvalidUpgradeHeight means the upgrade epoch hasn't been reached yet.
	InvalidUpgradeHeight = int64(0)

	// LatestDescriptorVersion is the latest upgrade descriptor version that should be used for
	// descriptors.
	LatestDescriptorVersion = 1

	// MinDescriptorVersion is the minimum descriptor version that is allowed.
	MinDescriptorVersion = 1
	// MaxDescriptorVersion is the maximum descriptor version that is allowed.
	MaxDescriptorVersion = LatestDescriptorVersion

	// LatestPendingUpgradeVersion is the latest pending upgrade struct version.
	LatestPendingUpgradeVersion = 1

	// MinUpgradeHandlerLength is the minimum length of upgrade handler's name.
	MinUpgradeHandlerLength = 3
	// MaxUpgradeHandlerLength is the maximum length of upgrade handler's name.
	MaxUpgradeHandlerLength = 32

	// MinUpgradeEpoch is the minimum upgrade epoch.
	MinUpgradeEpoch = beacon.EpochTime(1)
	// MaxUpgradeEpoch is the maximum upgrade epoch.
	MaxUpgradeEpoch = beacon.EpochInvalid - 1
)

Types

type Descriptor

type Descriptor struct {
	cbor.Versioned

	// Handler is the name of the upgrade handler.
	Handler HandlerName `json:"handler"`
	// Target is upgrade's target version.
	Target version.ProtocolVersions `json:"target"`
	// Epoch is the epoch at which the upgrade should happen.
	Epoch beacon.EpochTime `json:"epoch"`
}

Descriptor describes an upgrade.

type HandlerName

type HandlerName string

HandlerName is the name of the upgrade descriptor handler.

type PendingUpgrade

type PendingUpgrade struct {
	cbor.Versioned

	// Descriptor is the upgrade descriptor describing the upgrade.
	Descriptor *Descriptor `json:"descriptor"`

	// UpgradeHeight is the height at which the upgrade epoch was reached
	// (or InvalidUpgradeHeight if it hasn't been reached yet).
	UpgradeHeight int64 `json:"upgrade_height"`

	// LastCompletedStage is the last upgrade stage that was successfully completed.
	LastCompletedStage UpgradeStage `json:"last_completed_stage"`
}

PendingUpgrade describes a currently pending upgrade and includes the submitted upgrade descriptor.

type UpgradeStage

type UpgradeStage uint64

UpgradeStage is used in the upgrade descriptor to store completed stages.