node

package
v1.36.31 Latest Latest
Warning

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

Go to latest
Published: Jul 27, 2026 License: BSD-3-Clause Imports: 90 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

View Source
var CoreVMs = map[ids.ID]CoreVM{
	constants.PlatformVMID: {Name: "platformvm (P-Chain)", RegisteredInNodeGo: true},
	constants.XVMID:        {Name: "xvm (X-Chain)", RegisteredInNodeGo: true},
	constants.QuantumVMID:  {Name: "quantumvm (Q-Chain)", Factory: &quantumvm.Factory{Config: quantumvmconfig.DefaultConfig()}},
	constants.ZKVMID:       {Name: "zkvm (Z-Chain)", Factory: &zkvm.Factory{}},
}

CoreVMs is the authoritative set of in-process VMs. Q and Z carry their concrete factory (registerCoreVMs installs them); P and X are registered in node.go with runtime dependencies (RegisteredInNodeGo=true, Factory nil).

This map is the single source for "what is core". The anti-shadow guards iterate its keys; tests assert all four are present and that none also appears in OptionalVMs.

View Source
var OptionalVMs = map[ids.ID]PluginSpec{
	constants.DexVMID:      {Name: "dexvm", RequiredNFT: &NFTRequirement{Collection: "dex-operator", GroupID: 0}},
	constants.BridgeVMID:   {Name: "bridgevm", RequiredNFT: &NFTRequirement{Collection: "bridge-operator", GroupID: 0}},
	constants.EVMID:        {Name: "evm"},
	constants.AIVMID:       {Name: "aivm"},
	constants.GraphVMID:    {Name: "graphvm"},
	constants.IdentityVMID: {Name: "identityvm"},
	constants.KeyVMID:      {Name: "keyvm"},
	constants.OracleVMID:   {Name: "oraclevm"},
	constants.RelayVMID:    {Name: "relayvm"},
	constants.MPCVMID:      {Name: "mpcvm"},

	constants.FHEVMID: {Name: "fhevm"},
}

OptionalVMs is the authoritative set of plugin-only VMs and their activation gates. It is the single source for both (a) which VMs MUST NOT be linked in-process, and (b) which chains require an operator NFT to activate.

D (dexvm) and B (bridgevm) are NFT-gated: a node may only track/validate them if its staking X-address holds the corresponding operator NFT. The concrete collection AssetID is per-network and supplied via Config.NFTAuthorizationAssets; minting the real collections is a follow-up, so until a network configures an asset the chain stays ungated (preserving today's opt-in-flag behavior) while the gate itself remains fail-closed.

C (evm) and the remaining app VMs are plugin-loaded but ungated today.

Declaring a VM here is a statement of intent, not a guarantee that a binary exists: the registry scan simply finds nothing and the chain cannot start. fhevm (F-Chain) is exactly that case today — see its entry below.

Functions

func NewBLSSignerWrapper added in v1.16.16

func NewBLSSignerWrapper(key *bls.SecretKey) bls.Signer

func NewResourceManagerWrapper added in v1.16.16

func NewResourceManagerWrapper(manager resource.Manager) tracker.ResourceManager

NewResourceManagerWrapper creates a new resource manager wrapper

func NewRouterAdapter added in v1.16.16

func NewRouterAdapter(r Router) router.Router

NewRouterAdapter creates a new router adapter

Types

type BLSSignerWrapper added in v1.16.16

type BLSSignerWrapper struct {
	// contains filtered or unexported fields
}

BLSSignerWrapper wraps a SecretKey to implement the Signer interface with error returns

func (*BLSSignerWrapper) PublicKey added in v1.16.16

func (s *BLSSignerWrapper) PublicKey() *bls.PublicKey

func (*BLSSignerWrapper) Sign added in v1.16.16

func (s *BLSSignerWrapper) Sign(msg []byte) (*bls.Signature, error)

func (*BLSSignerWrapper) SignProofOfPossession added in v1.16.16

func (s *BLSSignerWrapper) SignProofOfPossession(msg []byte) (*bls.Signature, error)

type CoreVM added in v1.30.16

type CoreVM struct {
	Name               string
	Factory            vms.Factory
	RegisteredInNodeGo bool
}

CoreVM describes a VM that runs in-process (linked into luxd), never loaded from PluginDir and never NFT-gated.

Factory is the concrete in-process factory for VMs whose construction needs no node runtime state (Q, Z) — registerCoreVMs installs these. It is nil for P and X, whose factories must be built with live node dependencies (chainManager, validators, security profile, classical-compat registry) and are therefore registered explicitly in node.go; RegisteredInNodeGo records that ownership so the nil Factory is self-documenting, not a footgun.

type HealthConfig added in v1.16.16

type HealthConfig struct {
	Enabled                       bool          `json:"enabled"`
	PollingInterval               time.Duration `json:"pollingInterval"`
	MaxOutstandingRequestDuration time.Duration `json:"maxOutstandingRequestDuration"`
	MaxTimeSinceMsgReceived       time.Duration `json:"maxTimeSinceMsgReceived"`
	MaxTimeSinceMsgSent           time.Duration `json:"maxTimeSinceMsgSent"`
	MaxPortionSentQueueBytesFull  float64       `json:"maxPortionSentQueueBytesFull"`
	MaxPortionSendQueueFull       float64       `json:"maxPortionSendQueueFull"`
	MaxSendFailRate               float64       `json:"maxSendFailRate"`
	MinConnectedPeers             int           `json:"minConnectedPeers"`
	ReadTimeout                   time.Duration `json:"readTimeout"`
	WriteTimeout                  time.Duration `json:"writeTimeout"`
}

HealthConfig for router health monitoring

type NFTRequirement added in v1.30.16

type NFTRequirement struct {
	// Collection is the human label of the operator NFT collection (e.g.
	// "dex-operator", "bridge-operator"). It exists for logging/clarity and to
	// key the per-network asset lookup conceptually; the authoritative join key
	// is the VMID (see chainAuthorizationsFor).
	Collection string
	// GroupID is the nftfx group within the collection that authorizes
	// activation; 0 means any group in the collection.
	GroupID uint32
}

NFTRequirement is the per-network-independent POLICY half of a VM's activation gate: which X-Chain nftfx collection a validator's staking address must hold, and which group within it (0 = any group). The per-network VALUE half — the concrete collection AssetID — is supplied separately from network config (Config.NFTAuthorizationAssets) and joined with this policy in chainAuthorizationsFor. Splitting policy (here) from per-network value (config) keeps one declaration of "which VMs need an operator NFT" while the asset IDs vary per network/genesis.

type Node

type Node struct {
	Log          log.Logger
	VMFactoryLog log.Logger
	LogFactory   log.Factory

	// This node's unique ID used when communicating with other nodes
	// (in consensus, for example)
	ID ids.NodeID

	StakingTLSSigner crypto.Signer
	StakingTLSCert   *staking.Certificate

	// Storage for this node
	DB database.Database

	// dispatcher for events as they happen in consensus
	BlockAcceptorGroup  nodeconsensus.AcceptorGroup
	TxAcceptorGroup     nodeconsensus.AcceptorGroup
	VertexAcceptorGroup nodeconsensus.AcceptorGroup

	// Net runs the networking stack
	Net network.Network

	// Handles HTTP API calls
	APIServer server.Server

	// This node's configuration
	Config *node.Config

	// Metrics Registerer
	MetricsGatherer        metric.MultiGatherer
	MeterDBMetricsGatherer metric.MultiGatherer

	VMAliaser ids.Aliaser
	VMManager vms.Manager

	// VM endpoint registry
	VMRegistry registry.VMRegistry
	// contains filtered or unexported fields
}

Node is an instance of a Lux node.

func New added in v0.1.1

func New(
	config *node.Config,
	logFactory log.Factory,
	logger log.Logger,
) (*Node, error)

New returns an instance of Node

func (*Node) Dispatch

func (n *Node) Dispatch() error

Dispatch starts the node's servers. Returns when the node exits.

func (*Node) ExitCode added in v0.1.1

func (n *Node) ExitCode() int

func (*Node) SecurityProfile added in v1.26.11

func (n *Node) SecurityProfile() *consensusconfig.ChainSecurityProfile

SecurityProfile returns the chain-wide ChainSecurityProfile this node is operating under, or nil when the genesis carries no pin. The returned pointer is the post-Validate+ComputeHash result already stamped with ProfileHash; callers MUST NOT mutate it.

Downstream consumers (signer factory, peer handshake gate, mempool admittance, validator registry, bridge oracle co-signer) take this as a dependency at construction time. The single load happens at node bootstrap (initSecurityProfile); there is no per-request re-resolution.

Closes red-team finding F102 at the consumer API boundary.

func (*Node) Shutdown

func (n *Node) Shutdown(exitCode int)

Shutdown this node May be called multiple times All calls to shutdownOnce.Do block until the first call returns

type PluginSpec added in v1.30.16

type PluginSpec struct {
	// Name is the chain VM's package/plugin name (e.g. "dexvm"). For the nine
	// luxfi/chains VMs the plugin main is github.com/luxfi/chains/<Name>/cmd/
	// plugin and the built artifact is placed at <plugin-dir>/<VMID-CB58> by the
	// Dockerfile Chain VM Plugin Stage. The C-Chain EVM ("evm") is also
	// plugin-loaded but its plugin main lives in the EVM repo, not chains.
	Name string
	// RequiredNFT, when non-nil, gates this VM's activation on X-Chain operator
	// NFT ownership (see NFTRequirement). Nil means the VM is plugin-loaded but
	// ungated (any node that tracks the chain may activate it).
	RequiredNFT *NFTRequirement
}

PluginSpec describes a VM that is loaded ONLY from PluginDir (never linked in-process), optionally gated on an X-Chain operator NFT.

type Router added in v1.16.16

type Router interface {
	Initialize(
		nodeID ids.NodeID,
		logger log.Logger,
		timeoutManager timer.AdaptiveTimeoutManager,
		gossipFrequency uint64,
		harshQuittersTime uint64,
		harshQuittersSlashingFraction uint64,
		appGossipValidatorSize uint64,
		appGossipNonValidatorSize uint64,
		gossipAcceptedFrontierSize uint64,
		appSendQueueSize uint64,
		peerNotConnectedF uint64,
		connectedPeers ...ids.NodeID,
	) error

	RegisterRequest(
		ctx context.Context,
		nodeID ids.NodeID,
		chainID ids.ID,
		requestID uint32,
		op message.Op,
		failedMsg message.InboundMessage,
		engineType p2p.EngineType,
	)

	HandleInbound(ctx context.Context, msg message.InboundMessage)
	Shutdown(ctx context.Context)
	AddChain(ctx context.Context, chainID ids.ID, handler handler.Handler)
	Connected(nodeID ids.NodeID, nodeVersion *version.Application, netID ids.ID)
	Disconnected(nodeID ids.NodeID)
	Benched(chainID ids.ID, nodeID ids.NodeID)
	Unbenched(chainID ids.ID, nodeID ids.NodeID)
	HealthCheck(ctx context.Context) (interface{}, error)
	Deprecated() // Required for router.Router compatibility
}

Router handles message routing between chains

func NewRouter added in v1.22.59

func NewRouter(logger log.Logger, timeoutManager timer.AdaptiveTimeoutManager) Router

NewRouter creates a new chain router

func NewSimpleRouter added in v1.16.16

func NewSimpleRouter(logger log.Logger, timeoutManager timer.AdaptiveTimeoutManager) Router

NewSimpleRouter is deprecated - use NewRouter instead

func Trace added in v1.16.16

func Trace(router Router, name string, tracer trace.Tracer) Router

Trace wraps a router with tracing capabilities

type Targeter added in v1.16.16

type Targeter = tracker.Targeter

Type aliases

type ValidatorManager added in v1.22.22

type ValidatorManager struct {
	Router
	// contains filtered or unexported fields
}

ValidatorManager wraps the consensus router and handles: - Validator connection tracking - Beacon connection management for bootstrap - Sybil protection weight management

func NewValidatorManager added in v1.22.22

func NewValidatorManager(cfg ValidatorManagerConfig) *ValidatorManager

NewValidatorManager creates a new validator manager

func (*ValidatorManager) AddChain added in v1.22.22

func (v *ValidatorManager) AddChain(ctx context.Context, chainID ids.ID, h handler.Handler)

func (*ValidatorManager) Benched added in v1.22.22

func (v *ValidatorManager) Benched(chainID ids.ID, nodeID ids.NodeID)

func (*ValidatorManager) Connected added in v1.22.22

func (v *ValidatorManager) Connected(nodeID ids.NodeID, nodeVersion *version.Application, netID ids.ID)

func (*ValidatorManager) Deprecated added in v1.22.22

func (v *ValidatorManager) Deprecated()

Router interface methods - forward to underlying router

func (*ValidatorManager) Disconnected added in v1.22.22

func (v *ValidatorManager) Disconnected(nodeID ids.NodeID)

func (*ValidatorManager) HandleInbound added in v1.22.22

func (v *ValidatorManager) HandleInbound(ctx context.Context, msg message.InboundMessage)

func (*ValidatorManager) HealthCheck added in v1.22.22

func (v *ValidatorManager) HealthCheck(ctx context.Context) (interface{}, error)

func (*ValidatorManager) Initialize added in v1.22.22

func (v *ValidatorManager) Initialize(
	nodeID ids.NodeID,
	logger log.Logger,
	timeoutManager timer.AdaptiveTimeoutManager,
	gossipFrequency uint64,
	harshQuittersTime uint64,
	harshQuittersSlashingFraction uint64,
	appGossipValidatorSize uint64,
	appGossipNonValidatorSize uint64,
	gossipAcceptedFrontierSize uint64,
	appSendQueueSize uint64,
	peerNotConnectedF uint64,
	connectedPeers ...ids.NodeID,
) error

func (*ValidatorManager) RegisterRequest added in v1.22.22

func (v *ValidatorManager) RegisterRequest(
	ctx context.Context,
	nodeID ids.NodeID,
	chainID ids.ID,
	requestID uint32,
	op message.Op,
	failedMsg message.InboundMessage,
	engineType p2p.EngineType,
)

func (*ValidatorManager) Shutdown added in v1.22.22

func (v *ValidatorManager) Shutdown(ctx context.Context)

func (*ValidatorManager) Unbenched added in v1.22.22

func (v *ValidatorManager) Unbenched(chainID ids.ID, nodeID ids.NodeID)

type ValidatorManagerConfig added in v1.22.22

type ValidatorManagerConfig struct {
	Router                  Router
	Log                     log.Logger
	Validators              validators.Manager
	Beacons                 validators.Manager
	TrackedNetworks         []ids.ID
	SybilProtectionDisabled bool
	SybilProtectionWeight   uint64
	RequiredBeaconConns     int64
	OnSufficientlyConnected chan struct{}
}

ValidatorManagerConfig configures the validator manager

Directories

Path Synopsis
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL