version

Documentation

Overview

Package version implements Oasis protocol and runtime versioning.

For a more detailed explanation of Oasis Core's versioning, see: https://docs.oasis.io/core/versioning.

Index

• Constants
• Variables
• func ConvertGoModulesVersion(goModVersion string) string
• type ProtocolVersions
  • func (pv *ProtocolVersions) Compatible(other ProtocolVersions) bool
  • func (pv ProtocolVersions) PrettyPrint(_ context.Context, prefix string, w io.Writer)
  • func (pv ProtocolVersions) PrettyType() (interface{}, error)
  • func (pv ProtocolVersions) String() string
  • func (pv *ProtocolVersions) ValidateBasic() error
• type Version
  • func FromString(s string) (Version, error)
  • func FromU64(v uint64) Version
  • func MustFromString(s string) Version
  • func (v Version) MaskNonMajor() Version
  • func (v Version) String() string
  • func (v Version) ToU64() uint64
  • func (v Version) ValidateBasic() error

Constants

const VersionUndefined = "undefined"

VersionUndefined represents an undefined version.

Variables

var (
	// SoftwareVersion represents the Oasis Core's version and should be set
	// by the linker.
	SoftwareVersion = "0.0-unset"

	// GitBranch is the name of the git branch of Oasis Core.
	//
	// This is mostly used for reporting and metrics.
	GitBranch = ""

	// ConsensusProtocol versions all data structures and processing used by
	// the epochtime, beacon, registry, roothash, etc. modules that are
	// backend by consensus.
	//
	// NOTE: Consensus protocol version compatibility is currently not directly
	// checked in Oasis Core.
	// It is converted to CometBFTAppVersion whose compatibility is checked
	// via CometBFT's version checks.
	ConsensusProtocol = Version{Major: 7, Minor: 0, Patch: 0}

	// RuntimeHostProtocol versions the protocol between the Oasis node(s) and
	// the runtime.
	//
	// NOTE: This version must be synced with runtime/src/common/version.rs.
	RuntimeHostProtocol = Version{Major: 5, Minor: 1, Patch: 0}

	// RuntimeCommitteeProtocol versions the P2P protocol used by the runtime
	// committee members.
	RuntimeCommitteeProtocol = Version{Major: 5, Minor: 0, Patch: 0}

	// CometBFTAppVersion is CometBFT ABCI application's version computed by
	// masking non-major consensus protocol version segments to 0 to be
	// compatible with CometBFT's version checks.
	//
	// NOTE: CometBFT's version checks compare the whole version uint64
	// directly. For example:
	// https://github.com/cometbft/cometbft/blob/v0.37.1/state/validation.go#L21-L22
	CometBFTAppVersion = ConsensusProtocol.MaskNonMajor().ToU64()

	// Toolchain is the version of the Go compiler/standard library.
	Toolchain = MustFromString(strings.TrimPrefix(runtime.Version(), "go"))
)

var Versions = ProtocolVersions{
	ConsensusProtocol,
	RuntimeHostProtocol,
	RuntimeCommitteeProtocol,
}

Versions are current protocol versions.

Functions

func ConvertGoModulesVersion

func ConvertGoModulesVersion(goModVersion string) string

ConvertGoModulesVersion converts a Go modules compatible version to Oasis Core's canonical version.

Types

type ProtocolVersions

type ProtocolVersions struct {
	ConsensusProtocol        Version `json:"consensus_protocol"`
	RuntimeHostProtocol      Version `json:"runtime_host_protocol"`
	RuntimeCommitteeProtocol Version `json:"runtime_committee_protocol"`
}

ProtocolVersions are the protocol versions.

func (*ProtocolVersions) Compatible

func (pv *ProtocolVersions) Compatible(other ProtocolVersions) bool

Compatible returns if the two protocol versions are compatible.

func (ProtocolVersions) PrettyPrint

func (pv ProtocolVersions) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of ProtocolVersions to the given writer.

func (ProtocolVersions) PrettyType

func (pv ProtocolVersions) PrettyType() (interface{}, error)

PrettyType returns a representation of ProtocolVersions that can be used for pretty printing.

func (ProtocolVersions) String

func (pv ProtocolVersions) String() string

String returns the protocol versions as a string.

func (*ProtocolVersions) ValidateBasic

func (pv *ProtocolVersions) ValidateBasic() error

ValidateBasic does basic validation checks of the protocol versions.

type Version

type Version struct {
	Major uint16 `json:"major,omitempty"`
	Minor uint16 `json:"minor,omitempty"`
	Patch uint16 `json:"patch,omitempty"`
}

Version is a protocol version.

func FromString

func FromString(s string) (Version, error)

FromString parses version in semver format. e.g. "1.0.0" major.minor.patch components are considered where major is mandatory. Any component following patch is ignored.

func FromU64

func FromU64(v uint64) Version

FromU64 returns the version from platform-dependent uint64.

func MustFromString

func MustFromString(s string) Version

MustFromString parses version in semver format and panics, if there is an error.

func (Version) MaskNonMajor

func (v Version) MaskNonMajor() Version

MaskNonMajor masks all non-major version segments to 0 and returns a new protocol version.

This is useful for comparing protocol versions for backward-incompatible changes.

func (Version) String

func (v Version) String() string

String returns the protocol version as a string.

func (Version) ToU64

func (v Version) ToU64() uint64

ToU64 returns the version as platform-dependent uint64.

func (Version) ValidateBasic

func (v Version) ValidateBasic() error

ValidateBasic does basic validation of a protocol version.