api

package
v0.2101.1 Latest Latest
Warning

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

 Go to latest Published: Apr 23, 2021 License: Apache-2.0 Imports: 29 Imported by: 24

Documentation

Overview

Package api implements the runtime and entity registry APIs.

Index

Constants

View Source 
const (
	// GasOpRegisterEntity is the gas operation identifier for entity registration.
	GasOpRegisterEntity transaction.Op = "register_entity"
	// GasOpDeregisterEntity is the gas operation identifier for entity deregistration.
	GasOpDeregisterEntity transaction.Op = "deregister_entity"
	// GasOpRegisterNode is the gas operation identifier for entity registration.
	GasOpRegisterNode transaction.Op = "register_node"
	// GasOpUnfreezeNode is the gas operation identifier for unfreezing nodes.
	GasOpUnfreezeNode transaction.Op = "unfreeze_node"
	// GasOpRegisterRuntime is the gas operation identifier for runtime registration.
	GasOpRegisterRuntime transaction.Op = "register_runtime"
	// GasOpRuntimeEpochMaintenance is the gas operation identifier for per-epoch
	// runtime maintenance costs.
	GasOpRuntimeEpochMaintenance transaction.Op = "runtime_epoch_maintenance"
	// GasOpUpdateKeyManager is the gas operation identifier for key manager
	// policy updates costs.
	GasOpUpdateKeyManager transaction.Op = "update_keymanager"
)
View Source 
const (
	// StakeClaimRegisterEntity is the stake claim identifier used for registering an entity.
	StakeClaimRegisterEntity = "registry.RegisterEntity"
	// StakeClaimRegisterNode is the stake claim template used for registering nodes.
	StakeClaimRegisterNode = "registry.RegisterNode.%s"
	// StakeClaimRegisterRuntime is the stake claim template used for registering runtimes.
	StakeClaimRegisterRuntime = "registry.RegisterRuntime.%s"
)
View Source 
const FreezeForever beacon.EpochTime = 0xffffffffffffffff

FreezeForever is an epoch that can be used to freeze a node for all (practical) time.

View Source 
const (
	// LatestRuntimeDescriptorVersion is the latest entity descriptor version that should be used
	// for all new descriptors. Using earlier versions may be rejected.
	LatestRuntimeDescriptorVersion = 2
)
View Source 
const ModuleName = "registry"

ModuleName is a unique module name for the registry module.

Variables

View Source 
var (
	// RegisterEntitySignatureContext is the context used for entity
	// registration.
	RegisterEntitySignatureContext = signature.NewContext("oasis-core/registry: register entity")

	// RegisterGenesisEntitySignatureContext is the context used for
	// entity registration in the genesis document.
	//
	// Note: This is identical to non-gensis registrations to support
	// migrating existing registrations into a new genesis document.
	RegisterGenesisEntitySignatureContext = RegisterEntitySignatureContext

	// RegisterNodeSignatureContext is the context used for node
	// registration.
	RegisterNodeSignatureContext = signature.NewContext("oasis-core/registry: register node")

	// RegisterGenesisNodeSignatureContext is the context used for
	// node registration in the genesis document.
	//
	// Note: This is identical to non-gensis registrations to support
	// migrating existing registrations into a new genesis document.
	RegisterGenesisNodeSignatureContext = RegisterNodeSignatureContext

	// ErrInvalidArgument is the error returned on malformed argument(s).
	ErrInvalidArgument = errors.New(ModuleName, 1, "registry: invalid argument")

	// ErrInvalidSignature is the error returned on an invalid signature.
	ErrInvalidSignature = errors.New(ModuleName, 2, "registry: invalid signature")

	// ErrBadEntityForNode is the error returned when a node registration
	// with an unknown entity is attempted.
	ErrBadEntityForNode = errors.New(ModuleName, 3, "registry: unknown entity in node registration")

	// ErrBadEntityForRuntime is the error returned when a runtime
	// attempts to register with an unknown entity.
	ErrBadEntityForRuntime = errors.New(ModuleName, 4, "registry: unknown entity in runtime registration")

	// ErrNoEnclaveForRuntime is the error returned when a TEE runtime
	// registers with no enclave IDs.
	ErrNoEnclaveForRuntime = errors.New(ModuleName, 5, "registry: no enclaves for TEE runtime registration")

	// ErrBadEnclaveIdentity is the error returned when a node tries to
	// register runtimes with wrong Enclave IDs.
	ErrBadEnclaveIdentity = errors.New(ModuleName, 6, "registry: bad enclave id")

	// ErrBadCapabilitiesTEEHardware is the error returned when a node tries to
	// register a runtime with bad Capabilities.TEE.Hardware.
	ErrBadCapabilitiesTEEHardware = errors.New(ModuleName, 7, "registry: bad capabilities.TEE.Hardware")

	// ErrTEEHardwareMismatch is the error returned when a node tries to
	// register a runtime and Capabilities.TEE.Hardware mismatches the one in
	// the registry.
	ErrTEEHardwareMismatch = errors.New(ModuleName, 8, "registry: runtime TEE.Hardware mismatches the one in registry")

	// ErrNoSuchEntity is the error returned when an entity does not exist.
	ErrNoSuchEntity = errors.New(ModuleName, 9, "registry: no such entity")

	// ErrNoSuchNode is the error returned when an node does not exist.
	ErrNoSuchNode = errors.New(ModuleName, 10, "registry: no such node")

	// ErrNoSuchRuntime is the error returned when an runtime does not exist.
	ErrNoSuchRuntime = errors.New(ModuleName, 11, "registry: no such runtime")

	// ErrIncorrectTxSigner is the error returned when the signer of the transaction
	// is not the correct one.
	ErrIncorrectTxSigner = errors.New(ModuleName, 12, "registry: incorrect tx signer")

	// ErrNodeExpired is the error returned when a node is expired.
	ErrNodeExpired = errors.New(ModuleName, 13, "registry: node expired")

	// ErrNodeCannotBeUnfrozen is the error returned when a node cannot yet be
	// unfrozen due to the freeze period not being over yet.
	ErrNodeCannotBeUnfrozen = errors.New(ModuleName, 14, "registry: node cannot be unfrozen yet")

	// ErrEntityHasNodes is the error returned when an entity cannot be deregistered
	// as it still has nodes.
	ErrEntityHasNodes = errors.New(ModuleName, 15, "registry: entity still has nodes")

	// ErrForbidden is the error returned when an operation is forbidden by
	// policy.
	ErrForbidden = errors.New(ModuleName, 16, "registry: forbidden by policy")

	// ErrNodeUpdateNotAllowed is the error returned when trying to update an existing node with
	// disallowed changes.
	ErrNodeUpdateNotAllowed = errors.New(ModuleName, 17, "registry: node update not allowed")

	// ErrRuntimeUpdateNotAllowed is the error returned when trying to update an existing runtime.
	ErrRuntimeUpdateNotAllowed = errors.New(ModuleName, 18, "registry: runtime update not allowed")

	// ErrEntityHasRuntimes is the error returned when an entity cannot be deregistered as it still
	// has runtimes.
	ErrEntityHasRuntimes = errors.New(ModuleName, 19, "registry: entity still has runtimes")

	// MethodRegisterEntity is the method name for entity registrations.
	MethodRegisterEntity = transaction.NewMethodName(ModuleName, "RegisterEntity", entity.SignedEntity{})
	// MethodDeregisterEntity is the method name for entity deregistrations.
	MethodDeregisterEntity = transaction.NewMethodName(ModuleName, "DeregisterEntity", nil)
	// MethodRegisterNode is the method name for node registrations.
	MethodRegisterNode = transaction.NewMethodName(ModuleName, "RegisterNode", node.MultiSignedNode{})
	// MethodUnfreezeNode is the method name for unfreezing nodes.
	MethodUnfreezeNode = transaction.NewMethodName(ModuleName, "UnfreezeNode", UnfreezeNode{})
	// MethodRegisterRuntime is the method name for registering runtimes.
	MethodRegisterRuntime = transaction.NewMethodName(ModuleName, "RegisterRuntime", Runtime{})

	// Methods is the list of all methods supported by the registry backend.
	Methods = []transaction.MethodName{
		MethodRegisterEntity,
		MethodDeregisterEntity,
		MethodRegisterNode,
		MethodUnfreezeNode,
		MethodRegisterRuntime,
	}

	// RuntimesRequiredRoles are the Node roles that require runtimes.
	RuntimesRequiredRoles = node.RoleComputeWorker |
		node.RoleStorageWorker |
		node.RoleKeyManager

	// ComputeRuntimeAllowedRoles are the Node roles that allow compute runtimes.
	ComputeRuntimeAllowedRoles = node.RoleComputeWorker |
		node.RoleStorageWorker

	// KeyManagerRuntimeAllowedRoles are the Node roles that allow key manager runtimes.
	KeyManagerRuntimeAllowedRoles = node.RoleKeyManager

	// ConsensusAddressRequiredRoles are the Node roles that require Consensus Address.
	ConsensusAddressRequiredRoles = node.RoleValidator

	// TLSAddressRequiredRoles are the Node roles that require TLS Address.
	TLSAddressRequiredRoles = node.RoleComputeWorker |
		node.RoleStorageWorker |
		node.RoleKeyManager |
		node.RoleConsensusRPC

	// P2PAddressRequiredRoles are the Node roles that require P2P Address.
	P2PAddressRequiredRoles = node.RoleComputeWorker
)
View Source 
var (
	// ErrUnsupportedRuntimeKind is the error returned when the parsed runtime
	// kind is malformed or unknown.
	ErrUnsupportedRuntimeKind = errors.New("runtime: unsupported runtime kind")

	// ErrUnsupportedRuntimeGovernanceModel is the error returned when the
	// parsed runtime governance model is malformed or unknown.
	ErrUnsupportedRuntimeGovernanceModel = errors.New("runtime: unsupported governance model")
)
View Source 
var DefaultGasCosts = transaction.Costs{
	GasOpRegisterEntity:          1000,
	GasOpDeregisterEntity:        1000,
	GasOpRegisterNode:            1000,
	GasOpUnfreezeNode:            1000,
	GasOpRegisterRuntime:         1000,
	GasOpRuntimeEpochMaintenance: 1000,
	GasOpUpdateKeyManager:        1000,
}

DefaultGasCosts are the "default" gas costs for operations.

Functions

func NewDeregisterEntityTx 

func NewDeregisterEntityTx(nonce uint64, fee *transaction.Fee) *transaction.Transaction

NewDeregisterEntityTx creates a new deregister entity transaction.

func NewRegisterEntityTx 

func NewRegisterEntityTx(nonce uint64, fee *transaction.Fee, sigEnt *entity.SignedEntity) *transaction.Transaction

NewRegisterEntityTx creates a new register entity transaction.

func NewRegisterNodeTx 

func NewRegisterNodeTx(nonce uint64, fee *transaction.Fee, sigNode *node.MultiSignedNode) *transaction.Transaction

NewRegisterNodeTx creates a new register node transaction.

func NewRegisterRuntimeTx 

func NewRegisterRuntimeTx(nonce uint64, fee *transaction.Fee, rt *Runtime) *transaction.Transaction

NewRegisterRuntimeTx creates a new register runtime transaction.

func NewUnfreezeNodeTx 

func NewUnfreezeNodeTx(nonce uint64, fee *transaction.Fee, unfreeze *UnfreezeNode) *transaction.Transaction

NewUnfreezeNodeTx creates a new unfreeze node transaction.

func RegisterService 

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new registry backend service with the given gRPC server.

func SanityCheckEntities 

func SanityCheckEntities(logger *logging.Logger, entities []*entity.SignedEntity) (map[signature.PublicKey]*entity.Entity, error)

SanityCheckEntities examines the entities table. Returns lookup of entity ID to the entity record for use in other checks.

func SanityCheckStake 

func SanityCheckStake(
	entities []*entity.Entity,
	accounts map[staking.Address]*staking.Account,
	nodes []*node.Node,
	runtimes []*Runtime,
	stakeThresholds map[staking.ThresholdKind]quantity.Quantity,
	isGenesis bool,
) error

SanityCheckStake ensures entities' stake accumulator claims are consistent with general state and entities have enough stake for themselves and all their registered nodes and runtimes.

func SortNodeList 

func SortNodeList(nodes []*node.Node)

SortNodeList sorts the given node list to ensure a canonical order.

func StakeClaimForNode 

func StakeClaimForNode(id signature.PublicKey) staking.StakeClaim

StakeClaimForNode generates a new stake claim identifier for a specific node registration.

func StakeClaimForRuntime 

func StakeClaimForRuntime(id common.Namespace) staking.StakeClaim

StakeClaimForRuntime generates a new stake claim for a specific runtime registration.

func StakeThresholdsForNode 

func StakeThresholdsForNode(n *node.Node, rts []*Runtime) (thresholds []staking.StakeThreshold)

StakeThresholdsForNode returns the staking thresholds for the given node.

The passed list of runtimes must be runtime descriptors for all runtimes that the node is registered for in the same order as they appear in the node descriptor (for example as returned by the VerifyRegisterNodeArgs function).

func StakeThresholdsForRuntime 

func StakeThresholdsForRuntime(rt *Runtime) (thresholds []staking.StakeThreshold)

StakeThresholdsForRuntime returns the staking thresholds for the given runtime.

func VerifyAddress 

func VerifyAddress(addr node.Address, allowUnroutable bool) error

VerifyAddress verifies a node address.

func VerifyNodeRuntimeEnclaveIDs 

func VerifyNodeRuntimeEnclaveIDs(logger *logging.Logger, rt *node.Runtime, regRt *Runtime, ts time.Time) error

VerifyNodeRuntimeEnclaveIDs verifies TEE-specific attributes of the node's runtime.

func VerifyNodeUpdate 

func VerifyNodeUpdate(logger *logging.Logger, currentNode, newNode *node.Node, epoch beacon.EpochTime) error

VerifyNodeUpdate verifies changes while updating the node.

func VerifyRegisterComputeRuntimeArgs 

func VerifyRegisterComputeRuntimeArgs(ctx context.Context, logger *logging.Logger, rt *Runtime, runtimeLookup RuntimeLookup) error

VerifyRegisterComputeRuntimeArgs verifies compute runtime-specific arguments for RegisterRuntime.

func VerifyRegisterEntityArgs 

func VerifyRegisterEntityArgs(logger *logging.Logger, sigEnt *entity.SignedEntity, isGenesis, isSanityCheck bool) (*entity.Entity, error)

VerifyRegisterEntityArgs verifies arguments for RegisterEntity.

func VerifyRuntime added in v0.2100.0 

func VerifyRuntime(
	params *ConsensusParameters,
	logger *logging.Logger,
	rt *Runtime,
	isGenesis bool,
	isSanityCheck bool,
) error

VerifyRuntime verifies the given runtime.

func VerifyRuntimeUpdate 

func VerifyRuntimeUpdate(logger *logging.Logger, currentRt, newRt *Runtime) error

VerifyRuntimeUpdate verifies changes while updating the runtime.

Types

type AnyNodeRuntimeAdmissionPolicy 

type AnyNodeRuntimeAdmissionPolicy struct{}

AnyNodeRuntimeAdmissionPolicy allows any node to register.

type Backend 

type Backend interface {
	// GetEntity gets an entity by ID.
	GetEntity(context.Context, *IDQuery) (*entity.Entity, error)

	// GetEntities gets a list of all registered entities.
	GetEntities(context.Context, int64) ([]*entity.Entity, error)

	// WatchEntities returns a channel that produces a stream of
	// EntityEvent on entity registration changes.
	WatchEntities(context.Context) (<-chan *EntityEvent, pubsub.ClosableSubscription, error)

	// GetNode gets a node by ID.
	GetNode(context.Context, *IDQuery) (*node.Node, error)

	// GetNodeStatus returns a node's status.
	GetNodeStatus(context.Context, *IDQuery) (*NodeStatus, error)

	// GetNodes gets a list of all registered nodes.
	GetNodes(context.Context, int64) ([]*node.Node, error)

	// GetNodeByConsensusAddress looks up a node by its consensus address at the
	// specified block height. The nature and format of the consensus address depends
	// on the specific consensus backend implementation used.
	GetNodeByConsensusAddress(context.Context, *ConsensusAddressQuery) (*node.Node, error)

	// WatchNodes returns a channel that produces a stream of
	// NodeEvent on node registration changes.
	WatchNodes(context.Context) (<-chan *NodeEvent, pubsub.ClosableSubscription, error)

	// WatchNodeList returns a channel that produces a stream of NodeList.
	// Upon subscription, the node list for the current epoch will be sent
	// immediately.
	//
	// Each node list will be sorted by node ID in lexicographically ascending
	// order.
	WatchNodeList(context.Context) (<-chan *NodeList, pubsub.ClosableSubscription, error)

	// GetRuntime gets a runtime by ID.
	GetRuntime(context.Context, *NamespaceQuery) (*Runtime, error)

	// GetRuntimes returns the registered Runtimes at the specified
	// block height.
	GetRuntimes(context.Context, *GetRuntimesQuery) ([]*Runtime, error)

	// WatchRuntimes returns a stream of Runtime.  Upon subscription,
	// all runtimes will be sent immediately.
	WatchRuntimes(context.Context) (<-chan *Runtime, pubsub.ClosableSubscription, error)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(context.Context, int64) (*Genesis, error)

	// GetEvents returns the events at specified block height.
	GetEvents(ctx context.Context, height int64) ([]*Event, error)

	// Cleanup cleans up the registry backend.
	Cleanup()
}

Backend is a registry implementation.

func NewRegistryClient 

func NewRegistryClient(c *grpc.ClientConn) Backend

NewRegistryClient creates a new gRPC registry client service.

type ConsensusAddressQuery 

type ConsensusAddressQuery struct {
	Height  int64  `json:"height"`
	Address []byte `json:"address"`
}

ConsensusAddressQuery is a registry query by consensus address. The nature and format of the consensus address depends on the specific consensus backend implementation used.

type ConsensusParameters 

type ConsensusParameters struct {
	// DebugAllowUnroutableAddresses is true iff node registration should
	// allow unroutable addreses.
	DebugAllowUnroutableAddresses bool `json:"debug_allow_unroutable_addresses,omitempty"`

	// DebugAllowTestRuntimes is true iff test runtimes should be allowed to
	// be registered.
	DebugAllowTestRuntimes bool `json:"debug_allow_test_runtimes,omitempty"`

	// DebugBypassStake is true iff the registry should bypass all of the staking
	// related checks and operations.
	DebugBypassStake bool `json:"debug_bypass_stake,omitempty"`

	// DisableRuntimeRegistration is true iff runtime registration should be
	// disabled outside of the genesis block.
	DisableRuntimeRegistration bool `json:"disable_runtime_registration,omitempty"`

	// DisableRuntimeRegistration is true iff key manager runtime registration should be
	// disabled outside of the genesis block.
	DisableKeyManagerRuntimeRegistration bool `json:"disable_km_runtime_registration,omitempty"`

	// GasCosts are the registry transaction gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`

	// MaxNodeExpiration is the maximum number of epochs relative to the epoch
	// at registration time that a single node registration is valid for.
	MaxNodeExpiration uint64 `json:"max_node_expiration,omitempty"`

	// EnableRuntimeGovernanceModels is a set of enabled runtime governance models.
	EnableRuntimeGovernanceModels map[RuntimeGovernanceModel]bool `json:"enable_runtime_governance_models,omitempty"`
}

ConsensusParameters are the registry consensus parameters.

type EntityEvent 

type EntityEvent struct {
	Entity         *entity.Entity `json:"entity"`
	IsRegistration bool           `json:"is_registration"`
}

EntityEvent is the event that is returned via WatchEntities to signify entity registration changes and updates.

type EntityWhitelistConfig added in v0.2100.0 

type EntityWhitelistConfig struct {
	// MaxNodes is the maximum number of nodes that an entity can register under
	// the given runtime for a specific role. If the map is empty or absent, the
	// number of nodes is unlimited. If the map is present and non-empty, the
	// the number of nodes is restricted to the specified maximum (where zero
	// means no nodes allowed), any missing roles imply zero nodes.
	MaxNodes map[node.RolesMask]uint16 `json:"max_nodes,omitempty"`
}

type EntityWhitelistRuntimeAdmissionPolicy 

type EntityWhitelistRuntimeAdmissionPolicy struct {
	Entities map[signature.PublicKey]EntityWhitelistConfig `json:"entities"`
}

EntityWhitelistRuntimeAdmissionPolicy allows only whitelisted entities' nodes to register.

type Event 

type Event struct {
	Height int64     `json:"height,omitempty"`
	TxHash hash.Hash `json:"tx_hash,omitempty"`

	RuntimeEvent      *RuntimeEvent      `json:"runtime,omitempty"`
	EntityEvent       *EntityEvent       `json:"entity,omitempty"`
	NodeEvent         *NodeEvent         `json:"node,omitempty"`
	NodeUnfrozenEvent *NodeUnfrozenEvent `json:"node_unfrozen,omitempty"`
}

Event is a registry event returned via GetEvents.

type ExecutorParameters 

type ExecutorParameters struct {
	// GroupSize is the size of the committee.
	GroupSize uint16 `json:"group_size"`

	// GroupBackupSize is the size of the discrepancy resolution group.
	GroupBackupSize uint16 `json:"group_backup_size"`

	// AllowedStragglers is the number of allowed stragglers.
	AllowedStragglers uint16 `json:"allowed_stragglers"`

	// RoundTimeout is the round timeout in consensus blocks.
	RoundTimeout int64 `json:"round_timeout"`

	// MaxMessages is the maximum number of messages that can be emitted by the runtime in a
	// single round.
	MaxMessages uint32 `json:"max_messages"`
}

ExecutorParameters are parameters for the executor committee.

func (*ExecutorParameters) ValidateBasic added in v0.2010.0 

func (e *ExecutorParameters) ValidateBasic() error

ValidateBasic performs basic executor parameter validity checks.

type Genesis 

type Genesis struct {
	// Parameters are the registry consensus parameters.
	Parameters ConsensusParameters `json:"params"`

	// Entities is the initial list of entities.
	Entities []*entity.SignedEntity `json:"entities,omitempty"`

	// Runtimes is the initial list of runtimes.
	Runtimes []*Runtime `json:"runtimes,omitempty"`
	// SuspendedRuntimes is the list of suspended runtimes.
	SuspendedRuntimes []*Runtime `json:"suspended_runtimes,omitempty"`

	// Nodes is the initial list of nodes.
	Nodes []*node.MultiSignedNode `json:"nodes,omitempty"`

	// NodeStatuses is a set of node statuses.
	NodeStatuses map[signature.PublicKey]*NodeStatus `json:"node_statuses,omitempty"`
}

Genesis is the registry genesis state.

func (*Genesis) SanityCheck 

func (g *Genesis) SanityCheck(
	now time.Time,
	baseEpoch beacon.EpochTime,
	stakeLedger map[staking.Address]*staking.Account,
	stakeThresholds map[staking.ThresholdKind]quantity.Quantity,
	publicKeyBlacklist map[signature.PublicKey]bool,
) error

SanityCheck does basic sanity checking on the genesis state.

type GetRuntimesQuery 

type GetRuntimesQuery struct {
	Height           int64 `json:"height"`
	IncludeSuspended bool  `json:"include_suspended"`
}

GetRuntimesQuery is a registry get runtimes query.

type IDQuery 

type IDQuery struct {
	Height int64               `json:"height"`
	ID     signature.PublicKey `json:"id"`
}

IDQuery is a registry query by ID.

type MaxNodesConstraint added in v0.2100.0 

type MaxNodesConstraint struct {
	Limit uint16 `json:"limit"`
}

MaxNodesConstraint specifies that only the given number of nodes may be eligible per entity.

type MinPoolSizeConstraint added in v0.2100.0 

type MinPoolSizeConstraint struct {
	Limit uint16 `json:"limit"`
}

MinPoolSizeConstraint is the minimum required candidate pool size constraint.

type NamespaceQuery 

type NamespaceQuery struct {
	Height int64            `json:"height"`
	ID     common.Namespace `json:"id"`
}

NamespaceQuery is a registry query by namespace (Runtime ID).

type NodeEvent 

type NodeEvent struct {
	Node           *node.Node `json:"node"`
	IsRegistration bool       `json:"is_registration"`
}

NodeEvent is the event that is returned via WatchNodes to signify node registration changes and updates.

type NodeList 

type NodeList struct {
	Nodes []*node.Node `json:"nodes"`
}

NodeList is a per-epoch immutable node list.

type NodeLookup 

type NodeLookup interface {
	// NodeBySubKey looks up a specific node by its consensus, P2P or TLS key.
	NodeBySubKey(ctx context.Context, key signature.PublicKey) (*node.Node, error)

	// NodeByBeaconPoint looks up a specific node by its beacon point.
	NodeByBeaconPoint(ctx context.Context, point pvss.Point) (*node.Node, error)

	// Returns a list of all nodes.
	Nodes(ctx context.Context) ([]*node.Node, error)
}

NodeLookup interface implements various ways for the verification functions to look-up nodes in the registry's state.

func SanityCheckNodes 

func SanityCheckNodes(
	logger *logging.Logger,
	params *ConsensusParameters,
	nodes []*node.MultiSignedNode,
	seenEntities map[signature.PublicKey]*entity.Entity,
	runtimesLookup RuntimeLookup,
	isGenesis bool,
	epoch beacon.EpochTime,
	now time.Time,
) (NodeLookup, error)

SanityCheckNodes examines the nodes table. Pass lookups of entities and runtimes from SanityCheckEntities and SanityCheckRuntimes for cross referencing purposes.

type NodeStatus 

type NodeStatus struct {
	// ExpirationProcessed is a flag specifying whether the node expiration
	// has already been processed.
	//
	// If you want to check whether a node has expired, check the node
	// descriptor directly instead of this flag.
	ExpirationProcessed bool `json:"expiration_processed"`
	// FreezeEndTime is the epoch when a frozen node can become unfrozen.
	//
	// After the specified epoch passes, this flag needs to be explicitly
	// cleared (set to zero) in order for the node to become unfrozen.
	FreezeEndTime beacon.EpochTime `json:"freeze_end_time"`
	// ElectionEligibleAfter specifies the epoch after which a node is
	// eligible to be included in non-validator committee elections.
	//
	// Note: A value of 0 is treated unconditionally as "ineligible".
	ElectionEligibleAfter beacon.EpochTime `json:"election_eligible_after"`
}

NodeStatus is live status of a node.

func (NodeStatus) IsFrozen 

func (ns NodeStatus) IsFrozen() bool

IsFrozen returns true if the node is currently frozen (prevented from being considered in scheduling decisions).

func (*NodeStatus) Unfreeze 

func (ns *NodeStatus) Unfreeze()

Unfreeze makes the node unfrozen.

type NodeUnfrozenEvent 

type NodeUnfrozenEvent struct {
	NodeID signature.PublicKey `json:"node_id"`
}

NodeUnfrozenEvent signifies when node becomes unfrozen.

type Runtime 

type Runtime struct {
	cbor.Versioned

	// ID is a globally unique long term identifier of the runtime.
	ID common.Namespace `json:"id"`

	// EntityID is the public key identifying the Entity controlling
	// the runtime.
	EntityID signature.PublicKey `json:"entity_id"`

	// Genesis is the runtime genesis information.
	Genesis RuntimeGenesis `json:"genesis"`

	// Kind is the type of runtime.
	Kind RuntimeKind `json:"kind"`

	// TEEHardware specifies the runtime's TEE hardware requirements.
	TEEHardware node.TEEHardware `json:"tee_hardware"`

	// Version is the runtime version information.
	Version VersionInfo `json:"versions"`

	// KeyManager is the key manager runtime ID for this runtime.
	KeyManager *common.Namespace `json:"key_manager,omitempty"`

	// Executor stores parameters of the executor committee.
	Executor ExecutorParameters `json:"executor,omitempty"`

	// TxnScheduler stores transaction scheduling parameters of the executor
	// committee.
	TxnScheduler TxnSchedulerParameters `json:"txn_scheduler,omitempty"`

	// Storage stores parameters of the storage committee.
	Storage StorageParameters `json:"storage,omitempty"`

	// AdmissionPolicy sets which nodes are allowed to register for this runtime.
	// This policy applies to all roles.
	AdmissionPolicy RuntimeAdmissionPolicy `json:"admission_policy"`

	// Constraints are the node scheduling constraints.
	Constraints map[scheduler.CommitteeKind]map[scheduler.Role]SchedulingConstraints `json:"constraints,omitempty"`

	// Staking stores the runtime's staking-related parameters.
	Staking RuntimeStakingParameters `json:"staking,omitempty"`

	// GovernanceModel specifies the runtime governance model.
	GovernanceModel RuntimeGovernanceModel `json:"governance_model"`
}

Runtime represents a runtime.

func VerifyRegisterNodeArgs 

func VerifyRegisterNodeArgs(
	ctx context.Context,
	params *ConsensusParameters,
	logger *logging.Logger,
	sigNode *node.MultiSignedNode,
	entity *entity.Entity,
	now time.Time,
	isGenesis bool,
	isSanityCheck bool,
	epoch beacon.EpochTime,
	runtimeLookup RuntimeLookup,
	nodeLookup NodeLookup,
) (*node.Node, []*Runtime, error)

VerifyRegisterNodeArgs verifies arguments for RegisterNode.

Returns the node descriptor and a list of runtime descriptors the node is registering for.

func (*Runtime) IsCompute 

func (r *Runtime) IsCompute() bool

IsCompute returns true iff the runtime is a generic compute runtime.

func (*Runtime) StakingAddress added in v0.2100.0 

func (r *Runtime) StakingAddress() *staking.Address

StakingAddress returns the correct staking address for the runtime based on its governance model or nil if there is no staking address under the given governance model.

func (Runtime) String 

func (r Runtime) String() string

String returns a string representation of itself.

func (*Runtime) ValidateBasic 

func (r *Runtime) ValidateBasic(strictVersion bool) error

ValidateBasic performs basic descriptor validity checks.

type RuntimeAdmissionPolicy 

type RuntimeAdmissionPolicy struct {
	AnyNode         *AnyNodeRuntimeAdmissionPolicy         `json:"any_node,omitempty"`
	EntityWhitelist *EntityWhitelistRuntimeAdmissionPolicy `json:"entity_whitelist,omitempty"`
}

RuntimeAdmissionPolicy is a specification of which nodes are allowed to register for a runtime.

type RuntimeDescriptorProvider 

type RuntimeDescriptorProvider interface {
	// ActiveDescriptor waits for the runtime to be initialized and then returns its active
	// descriptor.
	ActiveDescriptor(ctx context.Context) (*Runtime, error)
}

RuntimeDescriptorProvider is an interface that provides access to runtime descriptors.

type RuntimeEvent 

type RuntimeEvent struct {
	Runtime *Runtime `json:"runtime"`
}

RuntimeEvent signifies new runtime registration.

type RuntimeGenesis 

type RuntimeGenesis struct {
	// StateRoot is the state root that should be used at genesis time. If
	// the runtime should start with empty state, this must be set to the
	// empty hash.
	StateRoot hash.Hash `json:"state_root"`

	// State is the state identified by the StateRoot. It may be empty iff
	// all StorageReceipts are valid or StateRoot is an empty hash or if used
	// in network genesis (e.g. during consensus chain init).
	State storage.WriteLog `json:"state"`

	// StorageReceipts are the storage receipts for the state root. The list
	// may be empty or a signature in the list invalid iff the State is non-
	// empty or StateRoot is an empty hash or if used in network genesis
	// (e.g. during consensus chain init).
	StorageReceipts []signature.Signature `json:"storage_receipts"`

	// Round is the runtime round in the genesis.
	Round uint64 `json:"round"`
}

RuntimeGenesis is the runtime genesis information that is used to initialize runtime state in the first block.

func (*RuntimeGenesis) Equal 

func (rtg *RuntimeGenesis) Equal(cmp *RuntimeGenesis) bool

Equal compares vs another RuntimeGenesis for equality.

func (*RuntimeGenesis) SanityCheck 

func (rtg *RuntimeGenesis) SanityCheck(isGenesis bool) error

SanityCheck does basic sanity checking of RuntimeGenesis. isGenesis is true, if it is called during consensus chain init.

type RuntimeGovernanceModel added in v0.2100.0 

type RuntimeGovernanceModel uint8

RuntimeGovernanceModel specifies the runtime governance model. 

const (
	GovernanceInvalid   RuntimeGovernanceModel = 0
	GovernanceEntity    RuntimeGovernanceModel = 1
	GovernanceRuntime   RuntimeGovernanceModel = 2
	GovernanceConsensus RuntimeGovernanceModel = 3

	GovernanceMax = GovernanceConsensus
)

func (RuntimeGovernanceModel) MarshalText added in v0.2100.0 

func (gm RuntimeGovernanceModel) MarshalText() ([]byte, error)

func (RuntimeGovernanceModel) String added in v0.2100.0 

func (gm RuntimeGovernanceModel) String() string

String returns a string representation of a runtime governance model.

func (*RuntimeGovernanceModel) UnmarshalText added in v0.2100.0 

func (gm *RuntimeGovernanceModel) UnmarshalText(text []byte) error

type RuntimeKind 

type RuntimeKind uint32

RuntimeKind represents the runtime functionality. 

const (
	// KindInvalid is an invalid runtime and should never be explicitly set.
	KindInvalid RuntimeKind = 0

	// KindCompute is a generic compute runtime.
	KindCompute RuntimeKind = 1

	// KindKeyManager is a key manager runtime.
	KindKeyManager RuntimeKind = 2

	// TxnSchedulerSimple is the name of the simple batching algorithm.
	TxnSchedulerSimple = "simple"
)

func (*RuntimeKind) FromString 

func (k *RuntimeKind) FromString(str string) error

FromString deserializes a string into a RuntimeKind.

func (RuntimeKind) String 

func (k RuntimeKind) String() string

String returns a string representation of a runtime kind.

type RuntimeLookup 

type RuntimeLookup interface {
	// Runtime looks up a runtime by its identifier and returns it.
	//
	// This excludes any suspended runtimes, use SuspendedRuntime to query suspended runtimes only.
	Runtime(ctx context.Context, id common.Namespace) (*Runtime, error)

	// SuspendedRuntime looks up a suspended runtime by its identifier and
	// returns it.
	SuspendedRuntime(ctx context.Context, id common.Namespace) (*Runtime, error)

	// AnyRuntime looks up either an active or suspended runtime by its identifier and returns it.
	AnyRuntime(ctx context.Context, id common.Namespace) (*Runtime, error)

	// AllRuntimes returns a list of all runtimes (including suspended ones).
	AllRuntimes(ctx context.Context) ([]*Runtime, error)
}

RuntimeLookup interface implements various ways for the verification functions to look-up runtimes in the registry's state.

func SanityCheckRuntimes 

func SanityCheckRuntimes(
	logger *logging.Logger,
	params *ConsensusParameters,
	runtimes []*Runtime,
	suspendedRuntimes []*Runtime,
	isGenesis bool,
) (RuntimeLookup, error)

SanityCheckRuntimes examines the runtimes table.

type RuntimeStakingParameters 

type RuntimeStakingParameters struct {
	// Thresholds are the minimum stake thresholds for a runtime. These per-runtime thresholds are
	// in addition to the global thresholds. May be left unspecified.
	//
	// In case a node is registered for multiple runtimes, it will need to satisfy the maximum
	// threshold of all the runtimes.
	Thresholds map[staking.ThresholdKind]quantity.Quantity `json:"thresholds,omitempty"`

	// Slashing are the per-runtime misbehavior slashing parameters.
	Slashing map[staking.SlashReason]staking.Slash `json:"slashing,omitempty"`

	// RewardSlashEquvocationRuntimePercent is the percentage of the reward obtained when slashing
	// for equivocation that is transferred to the runtime's account.
	RewardSlashEquvocationRuntimePercent uint8 `json:"reward_equivocation,omitempty"`

	// RewardSlashBadResultsRuntimePercent is the percentage of the reward obtained when slashing
	// for incorrect results that is transferred to the runtime's account.
	RewardSlashBadResultsRuntimePercent uint8 `json:"reward_bad_results,omitempty"`
}

RuntimeStakingParameters are the stake-related parameters for a runtime.

func (*RuntimeStakingParameters) ValidateBasic 

func (s *RuntimeStakingParameters) ValidateBasic(runtimeKind RuntimeKind) error

ValidateBasic performs basic descriptor validity checks.

type SchedulingConstraints added in v0.2100.0 

type SchedulingConstraints struct {
	ValidatorSet *ValidatorSetConstraint `json:"validator_set,omitempty"`
	MaxNodes     *MaxNodesConstraint     `json:"max_nodes,omitempty"`
	MinPoolSize  *MinPoolSizeConstraint  `json:"min_pool_size,omitempty"`
}

SchedulingConstraints are the node scheduling constraints.

Multiple fields may be set in which case the ALL the constraints must be satisfied.

type StorageParameters 

type StorageParameters struct {
	// GroupSize is the size of the storage group.
	GroupSize uint16 `json:"group_size"`

	// MinWriteReplication is the number of nodes to which any writes must be replicated before
	// being assumed to be committed. It must be less than or equal to the GroupSize.
	MinWriteReplication uint16 `json:"min_write_replication"`

	// MaxApplyWriteLogEntries is the maximum number of write log entries when performing an Apply
	// operation.
	MaxApplyWriteLogEntries uint64 `json:"max_apply_write_log_entries"`

	// MaxApplyOps is the maximum number of apply operations in a batch.
	MaxApplyOps uint64 `json:"max_apply_ops"`

	// CheckpointInterval is the expected runtime state checkpoint interval (in rounds).
	CheckpointInterval uint64 `json:"checkpoint_interval"`

	// CheckpointNumKept is the expected minimum number of checkpoints to keep.
	CheckpointNumKept uint64 `json:"checkpoint_num_kept"`

	// CheckpointChunkSize is the chunk size parameter for checkpoint creation.
	CheckpointChunkSize uint64 `json:"checkpoint_chunk_size"`
}

StorageParameters are parameters for the storage committee.

func (*StorageParameters) ValidateBasic added in v0.2010.0 

func (s *StorageParameters) ValidateBasic() error

ValidateBasic performs basic storage parameter validity checks.

type TxnSchedulerParameters 

type TxnSchedulerParameters struct {
	// Algorithm is the transaction scheduling algorithm.
	Algorithm string `json:"algorithm"`

	// BatchFlushTimeout denotes, if using the "simple" algorithm, how long to
	// wait for a scheduled batch.
	BatchFlushTimeout time.Duration `json:"batch_flush_timeout"`

	// MaxBatchSize denotes what is the max size of a scheduled batch.
	MaxBatchSize uint64 `json:"max_batch_size"`

	// MaxBatchSizeBytes denote what is the max size of a scheduled batch in bytes.
	MaxBatchSizeBytes uint64 `json:"max_batch_size_bytes"`

	// ProposerTimeout denotes the timeout (in consensus blocks) for scheduler
	// to propose a batch.
	ProposerTimeout int64 `json:"propose_batch_timeout"`
}

TxnSchedulerParameters are parameters for the runtime transaction scheduler.

func (*TxnSchedulerParameters) ValidateBasic added in v0.2010.0 

func (t *TxnSchedulerParameters) ValidateBasic() error

ValidateBasic performs basic transaction scheduler parameter validity checks.

type UnfreezeNode 

type UnfreezeNode struct {
	NodeID signature.PublicKey `json:"node_id"`
}

UnfreezeNode is a request to unfreeze a frozen node.

type ValidatorSetConstraint added in v0.2100.0 

type ValidatorSetConstraint struct {
}

ValidatorSetConstraint specifies that the entity must have a node that is part of the validator set. No other options can currently be specified.

type VersionInfo 

type VersionInfo struct {
	// Version of the runtime.
	Version version.Version `json:"version"`

	// TEE is the enclave version information, in an enclave provider specific
	// format if any.
	TEE []byte `json:"tee,omitempty"`
}

VersionInfo is the per-runtime version information.

Source Files

View all Source files

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.