api

package
v0.2202.13 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2024 License: Apache-2.0 Imports: 27 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"
	// GasOpProveFreshness is the gas operation identifier for freshness proofs.
	GasOpProveFreshness transaction.Op = "prove_freshness"
)
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 = 3
)
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", DeregisterEntity{})
	// 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{})
	// MethodProveFreshness is the method name for freshness proofs.
	MethodProveFreshness = transaction.NewMethodName(ModuleName, "ProveFreshness", Runtime{})

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

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

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

	// 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.RoleConsensusRPC

	// P2PAddressRequiredRoles are the Node roles that require P2P Address.
	P2PAddressRequiredRoles = node.RoleComputeWorker |
		node.RoleKeyManager |
		node.RoleStorageRPC
)
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,
	GasOpProveFreshness:          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 NewProveFreshnessTx added in v0.2202.0 

func NewProveFreshnessTx(nonce uint64, fee *transaction.Fee, blob [32]byte) *transaction.Transaction

NewProveFreshnessTx creates a new prove freshness 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,
	allRuntimes []*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 unique runtime descriptors for all runtimes that the node is registered for.

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,
	nodeID signature.PublicKey,
	rt *node.Runtime,
	regRt *Runtime,
	teeCfg *node.TEEFeatures,
	ts time.Time,
	height uint64,
) error

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

func VerifyNodeUpdate 

func VerifyNodeUpdate(
	ctx context.Context,
	logger *logging.Logger,
	currentNode, newNode *node.Node,
	runtimeLookup RuntimeLookup,
	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,
	now beacon.EpochTime,
) error

VerifyRuntime verifies the given runtime.

func VerifyRuntimeNew added in v0.2200.0 

func VerifyRuntimeNew(logger *logging.Logger, rt *Runtime, now beacon.EpochTime, params *ConsensusParameters, isGenesis bool) error

VerifyRuntimeNew verifies a new runtime.

func VerifyRuntimeUpdate 

func VerifyRuntimeUpdate(
	logger *logging.Logger,
	currentRt, newRt *Runtime,
	now beacon.EpochTime,
	params *ConsensusParameters,
) 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, *GetRuntimeQuery) (*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)

	// ConsensusParameters returns the registry consensus parameters.
	ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, 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 ConsensusParameterChanges added in v0.2202.0 

type ConsensusParameterChanges struct {
	// DisableRuntimeRegistration is the new disable runtime registration flag.
	DisableRuntimeRegistration *bool `json:"disable_runtime_registration,omitempty"`

	// DisableKeyManagerRuntimeRegistration the new disable key manager runtime registration flag.
	DisableKeyManagerRuntimeRegistration *bool `json:"disable_km_runtime_registration,omitempty"`

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

	// MaxNodeExpiration is the maximum node expiration.
	MaxNodeExpiration *uint64 `json:"max_node_expiration,omitempty"`

	// EnableRuntimeGovernanceModels are the new enabled runtime governance models.
	EnableRuntimeGovernanceModels map[RuntimeGovernanceModel]bool `json:"enable_runtime_governance_models,omitempty"`

	// TEEFeatures are the new TEE features.
	TEEFeatures **node.TEEFeatures `json:"tee_features,omitempty"`

	// MaxRuntimeDeployments is the new maximum number of runtime deployments.
	MaxRuntimeDeployments *uint8 `json:"max_runtime_deployments,omitempty"`
}

ConsensusParameterChanges are allowed registry consensus parameter changes.

func (*ConsensusParameterChanges) Apply added in v0.2202.0 

func (c *ConsensusParameterChanges) Apply(params *ConsensusParameters) error

Apply applies changes to the given consensus parameters.

func (*ConsensusParameterChanges) SanityCheck added in v0.2202.0 

func (c *ConsensusParameterChanges) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameter changes.

type ConsensusParameters 

type ConsensusParameters struct {
	// DebugAllowUnroutableAddresses is true iff node registration should
	// allow unroutable addresses.
	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"`

	// DebugDeployImmediately is true iff runtime registrations should
	// allow immediate deployment.
	DebugDeployImmediately bool `json:"debug_deploy_immediately,omitempty"`

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

	// DisableKeyManagerRuntimeRegistration 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"`

	// TEEFeatures contains the configuration of supported TEE features.
	TEEFeatures *node.TEEFeatures `json:"tee_features,omitempty"`

	// MaxRuntimeDeployments is the maximum number of runtime deployments.
	MaxRuntimeDeployments uint8 `json:"max_runtime_deployments,omitempty"`
}

ConsensusParameters are the registry consensus parameters.

func (*ConsensusParameters) SanityCheck added in v0.2202.0 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameters.

type DeregisterEntity added in v0.2102.8 

type DeregisterEntity struct{}

DeregisterEntity is a request to deregister an entity.

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.

func (*EntityEvent) EventKind added in v0.2200.0 

func (e *EntityEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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"`

	// MinLiveRoundsPercent is the minimum percentage of rounds in an epoch that a node must
	// participate in positively in order to be considered live. Nodes not satisfying this may be
	// penalized.
	MinLiveRoundsPercent uint8 `json:"min_live_rounds_percent,omitempty"`

	// MinLiveRoundsForEvaluation is the minimum number of live rounds in an epoch for the liveness
	// calculations to be considered for evaluation.
	MinLiveRoundsForEvaluation uint64 `json:"min_live_rounds_eval,omitempty"`

	// MaxLivenessFailures is the maximum number of liveness failures that are tolerated before
	// suspending and/or slashing the node. Zero means unlimited.
	MaxLivenessFailures uint8 `json:"max_liveness_fails,omitempty"`
}

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 Fault added in v0.2200.0 

type Fault struct {
	// Failures is the number of times a node has been declared faulty.
	Failures uint8 `json:"failures,omitempty"`
	// SuspendedUntil specifies the epoch number until the node is not eligible for being scheduled
	// into the committee for which it is deemed faulty.
	SuspendedUntil beacon.EpochTime `json:"suspended_until,omitempty"`
}

Fault is used to track the state of nodes that are experiencing liveness failures.

func (*Fault) IsSuspended added in v0.2200.0 

func (f *Fault) IsSuspended(epoch beacon.EpochTime) bool

IsSuspended checks whether the node is suspended in the given epoch.

func (*Fault) RecordFailure added in v0.2200.0 

func (f *Fault) RecordFailure(epoch beacon.EpochTime)

RecordFailure records a liveness failure in the epoch preceding the specified epoch.

func (*Fault) RecordSuccess added in v0.2200.0 

func (f *Fault) RecordSuccess(epoch beacon.EpochTime)

RecordSuccess records success in the epoch preceding the specified epoch.

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,
	height uint64,
	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 GetRuntimeQuery added in v0.2202.0 

type GetRuntimeQuery struct {
	Height           int64            `json:"height"`
	ID               common.Namespace `json:"id"`
	IncludeSuspended bool             `json:"include_suspended,omitempty"`
}

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

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.

func (*NodeEvent) EventKind added in v0.2200.0 

func (e *NodeEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type NodeList 

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

NodeList is a per-epoch immutable node list.

type NodeListEpochEvent added in v0.2200.0 

type NodeListEpochEvent struct{}

NodeListEpochEvent is the per epoch node list event.

func (*NodeListEpochEvent) DecodeValue added in v0.2200.0 

func (e *NodeListEpochEvent) DecodeValue(value string) error

DecodeValue decodes the attribute event value.

func (*NodeListEpochEvent) EventKind added in v0.2200.0 

func (e *NodeListEpochEvent) EventKind() string

EventKind returns a string representation of this event's kind.

func (*NodeListEpochEvent) EventValue added in v0.2200.0 

func (e *NodeListEpochEvent) EventValue() string

EventValue returns a string representation of this event's kind.

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)

	// 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,
	height uint64,
) (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"`
	// Faults is a set of fault records for nodes that are experiencing
	// liveness failures when participating in specific committees.
	Faults map[common.Namespace]*Fault `json:"faults,omitempty"`
}

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) IsSuspended added in v0.2200.0 

func (ns *NodeStatus) IsSuspended(runtimeID common.Namespace, epoch beacon.EpochTime) bool

IsSuspended checks whether the node is suspended in the given epoch.

func (*NodeStatus) RecordFailure added in v0.2200.0 

func (ns *NodeStatus) RecordFailure(runtimeID common.Namespace, epoch beacon.EpochTime)

RecordFailure records a liveness failure in the epoch preceding the specified epoch.

func (*NodeStatus) RecordSuccess added in v0.2200.0 

func (ns *NodeStatus) RecordSuccess(runtimeID common.Namespace, epoch beacon.EpochTime)

RecordSuccess records success in the epoch preceding the specified epoch.

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.

func (*NodeUnfrozenEvent) EventKind added in v0.2200.0 

func (e *NodeUnfrozenEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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"`

	// 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"`

	// Deployments specifies the runtime deployments (versions).
	Deployments []*VersionInfo `json:"deployments,omitempty"`
}

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,
	height uint64,
	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) ActiveDeployment added in v0.2200.0 

func (r *Runtime) ActiveDeployment(now beacon.EpochTime) *VersionInfo

ActiveDeployment returns the currently active deployment for the specified epoch if it exists.

func (*Runtime) DeploymentForVersion added in v0.2202.0 

func (r *Runtime) DeploymentForVersion(v version.Version) *VersionInfo

DeploymentForVersion returns the deployment corresponding to the passed version if it exists.

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.

func (*Runtime) ValidateDeployments added in v0.2200.0 

func (r *Runtime) ValidateDeployments(now beacon.EpochTime, params *ConsensusParameters) error

ValidateDeployments validates a runtime descriptor's Deployments field at the specified epoch.

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.

func (*RuntimeEvent) EventKind added in v0.2200.0 

func (e *RuntimeEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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"`

	// 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
)

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)

	// Runtimes returns active runtimes (not including suspended ones).
	Runtimes(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,
	now beacon.EpochTime,
) (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"`

	// MinInMessageFee specifies the minimum fee that the incoming message must include for the
	// message to be queued.
	MinInMessageFee quantity.Quantity `json:"min_in_message_fee,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 {
	// 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 {
	// 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"`

	// MaxInMessages specifies the maximum size of the incoming message queue.
	MaxInMessages uint32 `json:"max_in_messages,omitempty"`

	// 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"`

	// ValidFrom stores the epoch at which, this version is valid.
	ValidFrom beacon.EpochTime `json:"valid_from"`

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

func (*VersionInfo) Equal added in v0.2200.0 

func (vi *VersionInfo) Equal(cmp *VersionInfo) bool

Equal compares vs another VersionInfo for equality.

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.