Lux Docs

Overview

Lux VM (github.com/luxfi/vm) defines the core interfaces and RPC infrastructure for Lux blockchain virtual machines. Any chain VM must satisfy the interfaces in this package. It provides dual-transport RPC (ZAP zero-copy and gRPC), VM lifecycle management, capability extensions, and the plugin system for running VMs as subprocesses.

Quick reference

Item	Value
Module	`github.com/luxfi/vm`
Go	1.26.1
Default Transport	ZAP (zero-copy binary protocol)
Alt Transport	gRPC (via `-tags=grpc` build tag)
License	BSD-3-Clause

Core Interfaces

VM (vm.go)

// VM defines the minimal interface for a virtual machine.
type VM interface {
    Initialize(ctx context.Context, init Init) error
    Shutdown(ctx context.Context) error
    ParseBlock(ctx context.Context, b []byte) (Block, error)
    GetBlock(ctx context.Context, id ids.ID) (Block, error)
    SetPreference(ctx context.Context, id ids.ID) error
    LastAccepted(ctx context.Context) (ids.ID, error)
}

Block (vm.go)

type Block interface {
    ID() ids.ID
    Parent() ids.ID
    Bytes() []byte
    Height() uint64
    Timestamp() int64
    Verify(context.Context) error
    Accept(context.Context) error
    Reject(context.Context) error
}

Factory (factory.go)

type Factory interface {
    New(log.Logger) (interface{}, error)
}

Optional Capabilities (capabilities.go)

Interface	Purpose
`BlockBuilder`	`BuildBlock(ctx) (Block, error)`
`HandlerProvider`	`CreateHandlers(ctx) (map[string]http.Handler, error)`
`EventSource`	`WaitForEvent(ctx) (any, error)`
`ConnectionAware`	`Connected/Disconnected` peer tracking
`HealthCheck`	`Health(ctx) (any, error)`

State Lifecycle (state.go)

Unknown -> Starting -> Syncing -> Bootstrapping -> Ready
                                                    |
                                               Degraded
                                                    |
                                              Stopping -> Stopped

States: Unknown, Starting, Syncing, Bootstrapping, Ready, Degraded, Stopping, Stopped

Feature Extensions (fx.go)

type Fx struct {
    ID ids.ID
    Fx any
}

type FxLifecycle interface {
    Initialize(vm any) error
    Bootstrapping() error
    Bootstrapped() error
}

Architecture

github.com/luxfi/vm
├── vm.go               # VM, Block, Init, Message interfaces
├── factory.go          # Factory interface
├── capabilities.go     # BlockBuilder, HandlerProvider, EventSource, etc.
├── state.go            # VM lifecycle states
├── fx.go               # Feature extension types
├── message.go          # MessageType aliases (PendingTxs, StateSyncDone)
├── chain/              # ChainVM interfaces and state management
│   ├── interfaces.go   # Extended chain VM interfaces
│   ├── block.go        # Block implementation
│   ├── state.go        # Chain state management
│   ├── status.go       # Block status tracking
│   ├── errors.go       # Chain errors
│   ├── blockmock/      # Mock blocks for testing
│   └── blocktest/      # Block test utilities
├── chains/             # Multi-chain management
├── rpc/                # VM <-> Node communication layer
│   ├── factory_zap.go  # ZAP-based plugin factory (default)
│   ├── factory_grpc.go # gRPC-based plugin factory (-tags=grpc)
│   ├── vm.go           # VM server/client shared types
│   ├── vm_server.go    # gRPC VM server
│   ├── vm_server_zap.go # ZAP VM server
│   ├── vm_client.go    # gRPC VM client
│   ├── vm_client_zap.go # ZAP VM client
│   ├── capabilities.go # RPC capability negotiation
│   ├── context.go      # RPC context
│   ├── errors.go       # Error types
│   ├── notifier.go     # Event notification
│   ├── warp_adapter.go # Warp message adapter
│   ├── metrics_adapter.go # Prometheus metrics
│   ├── sender/         # p2p.Sender (ZAP + gRPC)
│   ├── runtime/        # VM subprocess runtime
│   ├── chain/          # Chain RPC
│   ├── dag/            # DAG RPC
│   ├── ghttp/          # gRPC HTTP handlers
│   ├── grpcutils/      # gRPC utilities
│   ├── gruntime/       # gRPC runtime
│   ├── gvalidators/    # gRPC validators
│   ├── messenger/      # Message passing
│   └── commonmock/     # Shared mocks
├── api/                # HTTP API definitions
├── components/         # Shared components
├── consensus/          # Consensus integration
├── connectproto/       # Connect protocol definitions
├── internal/           # Internal packages (rpcdb)
├── manager/            # VM factory and management
├── nets/               # Network configuration
├── proto/              # Protobuf definitions
├── registry/           # VM registry
├── secp256k1fx/        # secp256k1 feature extension
├── tests/              # Integration tests
├── types/              # Shared types
├── utils/              # Utility functions
├── vms/                # Built-in VM implementations
└── wallet/             # Wallet integration

Transport Selection (Build Tags)

The package supports two transports for VM-Node communication:

Transport	Build	Usage
ZAP (default)	`go build ./...`	Production -- zero-copy binary protocol
gRPC	`go build -tags=grpc ./...`	Testing/compatibility

ZAP Wire Protocol

Handshake:
  VM -> Node:  [4B length][4B protocol version][vm addr string]
  Node -> VM:  [1B ACK (0x01)]

Messages:
  [4B length][1B message type][payload...]

Message types: MsgInitialize, MsgShutdown, MsgSetState,
  MsgBuildBlock, MsgParseBlock, MsgGetBlock,
  MsgBlockVerify, MsgBlockAccept, MsgBlockReject,
  MsgVersion, MsgHealth, etc.

Sender Package

// ZAP transport (always available)
s := sender.ZAP(zapConn)

// gRPC transport (requires -tags=grpc)
s := sender.GRPC(senderpb.NewSenderClient(grpcConn))

Key Dependencies

github.com/luxfi/consensus@v1.22.67  — Quasar consensus engine
github.com/luxfi/crypto@v1.17.40     — BLS, secp256k1
github.com/luxfi/database@v1.17.40   — Storage layer
github.com/luxfi/node@v1.22.87       — Node integration
github.com/luxfi/warp@v1.18.5        — Cross-chain messaging
github.com/luxfi/p2p@v1.18.9         — P2P networking
github.com/luxfi/lattice/v7@v7.0.0   — Post-quantum lattice crypto
github.com/luxfi/geth@v1.16.73       — EVM types (luxfi fork)
connectrpc.com/connect@v1.19.1       — Connect RPC
google.golang.org/grpc@v1.78.0       — gRPC (optional transport)

Testing

# Default transport (ZAP)
go test -v ./...

# With gRPC transport
go test -tags=grpc -v ./...

# Verify build separation
go list -deps ./rpc | grep grpc        # Should be empty (ZAP build)
go list -tags=grpc -deps ./rpc | grep grpc  # Shows ~62 deps (gRPC build)

lux/lux-node.md -- Node that hosts VMs
lux/lux-session.md -- SessionVM implements this VM interface
lux/lux-consensus.md -- Consensus engine that drives VMs
lux/lux-evm.md -- EVM implementation as a VM
lux/lux-precompile.md -- Custom EVM precompiles

Lux VM - Virtual Machine Types and Interfaces