luxfi/vm

mirror of https://github.com/luxfi/vm.git synced 2026-10-30 15:13:40 +00:00

Files

T

History

zeekay 6f067da160 codec rip: switch api/* and components/index to luxfi/utils

api/* — all seven service/handler files swap codec/jsonrpc for
luxfi/utils/json (Uint32, Uint64, NewCodec, RawMessage). api carries
no codec.Manager use; the api types only quote integers for the
JSON-RPC boundary.

components/index/index.go — codec/wrappers -> luxfi/utils/wrappers.
Used only for wrappers.LongLen byte-slice sizing.

rpc/runtime/subprocess/linux_stopper.go — drop wrappers.Errs in
favor of errors.Join (stdlib since Go 1.20) for the SIGTERM + Wait
fan-in. One fewer dependency on a doomed module.

vm no longer directly imports any codec/* subpackage. codec is still
pulled in indirectly through chains/atomic (Wave 2E, hand-rolled
binary marshal already in but go.sum still pins codec) and through
the proto/p test fixtures.

2026-06-06 02:57:04 -07:00

subprocess

codec rip: switch api/* and components/index to luxfi/utils

2026-06-06 02:57:04 -07:00

manager.go

fix: resolve proto import paths and test compilation issues

2026-01-11 20:58:38 -08:00

README.md

docs: gRPC tag retired -> ZAP-only build per LP-200

2026-06-03 13:00:04 -07:00

runtime.go

rpc: rip LUX_ prefix from rpcchainvm handshake env vars

2026-05-15 09:53:30 -07:00

README.md

Virtual Machine Runtime Engine (VMRE)

The VMRE handles the lifecycle, compatibility and logging IO of a managed VM process.

How it works

The runtime.Initializer interface could be implemented to manage local or remote VM processes. This implementation is consumed by a ZAP-native server (LP-186) which serves the Runtime service. The server interacts with the underlying process and allows for the VM binary to communicate with Lux Node. (Historical gRPC fallback was retired in v1.26.31.)

Subprocess VM management

The subprocess is currently the only supported Runtime implementation. It works by starting the VM's as a subprocess of Lux Node by os.Exec.

Workflow

VMRegistry calls the RPC Chain VM Factory.
Factory Starts an instance of a VMRE server that consumes a runtime.Initializer interface implementation.
The address of this server is passed as a ENV variable VM_RUNTIME_ENGINE_ADDR via os.Exec which starts the VM binary.
The VM uses the address of the VMRE server to create a client.
Client sends a Initialize RPC informing the server of the Protocol Version and future Address of the RPC Chain VM server allowing it to perform a validation Handshake.
After the Handshake is complete the RPC Chain VM server is started which serves the ChainVM implementation.
The connection details for the RPC Chain VM server are now used to create an RPC Chain VM client.
ChainManager uses this VM client to bootstrap the chain powered by Linear consensus.
To shutdown the VM runtime.Stop() sends a SIGTERM signal to the VM process.

Debugging

Process Not Found

When runtime is Bootstrapped handshake success is observed during the Initialize RPC. Process not found means that the runtime Client in the VM binary could not communicate with the runtime Server on Lux Node. This could be the result of networking issues or other error in Serve().

failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: timeout"}

Protocol Version Mismatch

To ensure RPC compatibility the protocol version of Lux Node must match the subnet VM. To correct this error update the subnet VM's dependencies to the latest version Lux Node.

failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: protocol version mismatch node: 19 vm: 18"}