api

package
v0.20.9 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2020 License: Apache-2.0 Imports: 30 Imported by: 22

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 epochtime.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 = 1
)
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

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

	// RegisterGenesisRuntimeSignatureContext is the context used for
	// runtime registation in the genesis document.
	//
	// Note: This is identical to non-gensis registrations to support
	// migrating existing registrations into a new genesis document.
	RegisterGenesisRuntimeSignatureContext = RegisterRuntimeSignatureContext

	// 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 forbiden 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", SignedRuntime{})

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

View Source 
var (
	// ErrUnsupportedRuntimeKind is the error returned when the parsed runtime
	// kind is malformed or unknown.
	ErrUnsupportedRuntimeKind = errors.New("runtime: unsupported runtime kind")
)

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, sigRt *SignedRuntime) *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) 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 VerifyRegisterRuntimeStorageArgs 

func VerifyRegisterRuntimeStorageArgs(rt *Runtime, logger *logging.Logger) error

VerifyRegisterRuntimeStorageArgs verifies the runtime's storage parameters

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 if available.
	//
	// 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"`

	// DebugAllowEntitySignedNodeRegistration is true iff node registration
	// signed by entity signing keys should be allowed.
	DebugAllowEntitySignedNodeRegistration bool `json:"debug_allow_entity_signed_node_registration,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"`
}

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 EntityWhitelistRuntimeAdmissionPolicy 

type EntityWhitelistRuntimeAdmissionPolicy struct {
	Entities map[signature.PublicKey]bool `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 uint64 `json:"group_size"`

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

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

	// RoundTimeout is the round timeout of the nodes in the group.
	RoundTimeout time.Duration `json:"round_timeout"`
}

ExecutorParameters are parameters for the executor committee.

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 []*SignedRuntime `json:"runtimes,omitempty"`
	// SuspendedRuntimes is the list of suspended runtimes.
	SuspendedRuntimes []*SignedRuntime `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(
	baseEpoch epochtime.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 MergeParameters 

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

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

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

	// RoundTimeout is the round timeout of the nodes in the group.
	RoundTimeout time.Duration `json:"round_timeout"`
}

MergeParameters are parameters for the merge committee.

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)

	// 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 epochtime.EpochTime,
) (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 epochtime.EpochTime `json:"freeze_end_time"`
}

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

	// Merge stores parameters of the merge committee.
	Merge MergeParameters `json:"merge,omitempty"`

	// TxnScheduler stores parameters of the transactions scheduler 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"`

	// Staking stores the runtime's staking-related parameters.
	Staking RuntimeStakingParameters `json:"staking,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,
	isGenesis bool,
	isSanityCheck bool,
	epoch epochtime.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 VerifyRegisterRuntimeArgs 

func VerifyRegisterRuntimeArgs(
	params *ConsensusParameters,
	logger *logging.Logger,
	sigRt *SignedRuntime,
	isGenesis bool,
	isSanityCheck bool,
) (*Runtime, error)

VerifyRegisterRuntimeArgs verifies arguments for RegisterRuntime.

func (*Runtime) IsCompute 

func (r *Runtime) IsCompute() bool

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

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 {
	// RegistryDescriptor waits for the runtime to be registered and then returns its registry
	// descriptor.
	RegistryDescriptor(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 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

	// TxnSchedulerAlgorithmBatching is the name of the batching algorithm.
	TxnSchedulerAlgorithmBatching = "batching"
)

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 []*SignedRuntime,
	suspendedRuntimes []*SignedRuntime,
	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"`
}

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 SignedRuntime 

type SignedRuntime struct {
	signature.Signed
}

SignedRuntime is a signed blob containing a CBOR-serialized Runtime.

func SignRuntime 

func SignRuntime(signer signature.Signer, context signature.Context, runtime *Runtime) (*SignedRuntime, error)

SignRuntime serializes the Runtime and signs the result.

func (*SignedRuntime) Open 

func (s *SignedRuntime) Open(context signature.Context, runtime *Runtime) error

Open first verifies the blob signature and then unmarshals the blob.

func (SignedRuntime) PrettyPrint 

func (s SignedRuntime) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

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

func (SignedRuntime) PrettyType 

func (s SignedRuntime) PrettyType() (interface{}, error)

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

type StorageParameters 

type StorageParameters struct {
	// GroupSize is the size of the storage group.
	GroupSize uint64 `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 uint64 `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"`

	// MaxMergeRoots is the maximum number of merge roots.
	MaxMergeRoots uint64 `json:"max_merge_roots"`

	// MaxApplyOps configures the maximum number of merge operations in a batch.
	MaxMergeOps uint64 `json:"max_merge_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.

type TxnSchedulerParameters 

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

	// Algorithm is the transaction scheduling algorithm.
	Algorithm string `json:"algorithm"`

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

	// MaxBatchSize denotes, if using the "batching" algorithm, what is the max
	// size of a batch.
	MaxBatchSize uint64 `json:"max_batch_size"`

	// MaxBatchSizeBytes denotes, if using the "batching" algorithm, what is the
	// max size of a batch in bytes.
	MaxBatchSizeBytes uint64 `json:"max_batch_size_bytes"`
}

TxnSchedulerParameters are parameters for the transaction scheduler committee.

type UnfreezeNode 

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

UnfreezeNode is a request to unfreeze a frozen node.

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.

type VersionInfoIntelSGX 

type VersionInfoIntelSGX struct {
	// Enclaves is the allowed MRENCLAVE/MRSIGNER pairs.
	Enclaves []sgx.EnclaveIdentity `json:"enclaves"`
}

VersionInfoIntelSGX is the SGX TEE 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.