api

package
v0.1.22 Latest Latest
Warning

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

 Go to latest Published: Nov 14, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

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

This section is empty.

Functions

This section is empty.

Types

type AnyNodeRuntimeAdmissionPolicy 

type AnyNodeRuntimeAdmissionPolicy struct{}

AnyNodeRuntimeAdmissionPolicy allows any node to register.

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 

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.

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.

type DeregisterEntity 

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.

type EntityWhitelistConfig 

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

EntityWhitelistConfig is a per-entity whitelist configuration.

type EntityWhitelistRoleAdmissionPolicy 

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

EntityWhitelistRoleAdmissionPolicy is a per-role entity whitelist policy.

type EntityWhitelistRoleConfig 

type EntityWhitelistRoleConfig struct {
	MaxNodes uint16 `json:"max_nodes,omitempty"`
}

EntityWhitelistRoleConfig is a per-entity whitelist configuration for a given role.

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

	RuntimeStartedEvent   *RuntimeStartedEvent   `json:"runtime_started,omitempty"`
	RuntimeSuspendedEvent *RuntimeSuspendedEvent `json:"runtime_suspended,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"`

	// MaxMissedProposalsPercent is the maximum percentage of proposed rounds in an epoch that
	// can fail for a node to be considered live. Nodes not satisfying this may be penalized.
	// Zero means that all proposed rounds can fail.
	MaxMissedProposalsPercent uint8 `json:"max_missed_proposals_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.

type Fault 

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.

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.

type GetRuntimeQuery 

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 

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

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

type MinPoolSizeConstraint 

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 NodeListEpochEvent 

type NodeListEpochEvent struct{}

NodeListEpochEvent is the per epoch node list event.

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.

type NodeUnfrozenEvent 

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

NodeUnfrozenEvent signifies when node becomes unfrozen.

type PerRoleAdmissionPolicy 

type PerRoleAdmissionPolicy struct {
	EntityWhitelist *EntityWhitelistRoleAdmissionPolicy `json:"entity_whitelist,omitempty"`
}

PerRoleAdmissionPolicy is a per-role admission policy.

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 (Runtime) String 

func (r Runtime) String() string

String returns a string representation of itself.

type RuntimeAdmissionPolicy 

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

	// PerRole is a per-role admission policy that must be satisfied in addition to the global
	// admission policy for a specific role.
	PerRole map[node.RolesMask]PerRoleAdmissionPolicy `json:"per_role,omitempty"`
}

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

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.

type RuntimeGovernanceModel 

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 

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

func (RuntimeGovernanceModel) String 

func (gm RuntimeGovernanceModel) String() string

String returns a string representation of a runtime governance model.

func (*RuntimeGovernanceModel) UnmarshalText 

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

func (k RuntimeKind) String() string

String returns a string representation of a runtime kind.

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.

type RuntimeStartedEvent 

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

RuntimeStartedEvent signifies a runtime started event.

Emitted when a new runtime is started or a previously suspended runtime is resumed.

type RuntimeSuspendedEvent 

type RuntimeSuspendedEvent struct {
	RuntimeID common.Namespace `json:"runtime_id"`
}

RuntimeSuspendedEvent signifies a runtime was suspended.

type SchedulingConstraints 

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.

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

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

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

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

	// ProposerTimeout denotes how long to wait before accepting proposal from
	// the next backup scheduler.
	ProposerTimeout time.Duration `json:"propose_batch_timeout,omitempty"`
}

TxnSchedulerParameters are parameters for the runtime transaction scheduler.

type UnfreezeNode 

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

UnfreezeNode is a request to unfreeze a frozen node.

type ValidatorSetConstraint 

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

	// BundleChecksum is the SHA256 hash of the runtime bundle (optional).
	BundleChecksum []byte `json:"bundle_checksum,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.