Skip to main content

Implementing a Virtual Machine

To deploy and run your own virtual machine (VM) on the HyMatrix network, developers must implement the standardized interface defined by HyMatrix. This ensures that all VMs can be invoked consistently by nodes, support logging, and enable replayable verification.

HyMatrix defines VMs as persistent process abstractions that can be spawned, receive invocation messages, process transactions, and be replayed or restored at any time to ensure verifiability.

Interface & Schema Definition​

Docker VM Implementation Example​

These examples help you quickly understand how to implement a VM that meets HyMatrix standards.

VmSpawnFunc​

First, you need to implement a factory function to instantiate the virtual machine:

type VmSpawnFunc func(Env) (Vm, error)

This function receives an Env parameter and returns a VM instance that conforms to HyMatrix’s interface, enabling the system to manage and schedule it uniformly.

Vm Interface​

Each VM must implement the following interface:

type Vm interface {
	Apply(from string, meta Meta) (res Result)
	Checkpoint() (data string, err error)
	Restore(data string) error
	Close() error
}

Apply​

The core execution method. When a node receives a message directed to this VM, it invokes Apply.

  • from: The sender of the call. This may be a user wallet address or another VM ID. HyMatrix supports cross-VM message calls.
  • meta: Contains all context and parameters for the transaction.

Apply returns a Result containing the output, any generated messages, state updates, and more.

Checkpoint​

Generates a snapshot of the VM’s current state.

Nodes use this to reduce overhead when restarting, migrating, or replaying logs. The snapshot must be a serializable string that can be restored later.

If your VM doesn’t maintain persistent state, return an error here to indicate no snapshot is available.

Restore​

Restores the VM state from a previously saved snapshot.

Since HyMatrix uses SCP (Storage-based Consensus Paradigm), nodes must be able to fully replay execution history. Restore ensures the VM can resume from a consistent state for accurate replay.

HyMatrix requires all nodes to be able to replay historical logs for verification.

  • Checkpoint: Generates a snapshot to reduce replay cost.
  • Restore: Restores from snapshot to resume execution.

If your VM has no persistent state, return an error in both methods to prevent misuse.

Close​

Called when the node needs to unload the VM and free up resources.

Meta Parameter​

The second parameter to Apply, meta, carries full context of the transaction call:

type Meta struct {
	ItemId string `json:"Item-Id"`
	Pid    string `json:"Pid"`
	AccId  string `json:"Acc-Id"`
	Action      string `json:"Action"`
	FromProcess string `json:"From-Process"`
	PushedFor   string `json:"Pushed-For"`
	Sequence    int64  `json:"Sequence"`
	Nonce       int64  `json:"Nonce"`
	Timestamp   int64  `json:"Timestamp"`
	Params      map[string]string `json:"Params"`
	Data        string            `json:"Data"`
	RecoveryDryRun   bool  `json:"-"`
	RecoveryMaxNonce int64 `json:"-"`
}
  • ItemId: The source message ID, following the Arweave ANS-104 BundleItem ID.
  • Pid: VM instance ID, uniquely identifying the VM.
  • AccId: The signer of this transaction (e.g., user wallet or node operator wallet). Note: AccId is not always equal to from, which is the actual sender.
  • Action: Function name being invoked.
  • FromProcess: Source VM ID if this message came from another VM.
  • PushedFor: The original sender (usually a user) — preserved across chained VM calls.
  • Sequence: Outbox sequence number from source VM, used to maintain message order.
  • Nonce: Sequentially increasing counter for calls to a VM, starting from 0 with no gaps or duplicates.
  • Timestamp: Message timestamp generated by HyMatrix.
  • Params: Key-value input parameters — the main input to your VM logic.
  • Data: Optional large data payload following ANS-104 format.
  • Recovery Fields: For internal replay logic; developers can ignore.

Result Return Type​

The Apply method must return a result of type:

type Result struct {
	Messages     []*ResMessage
	Spawns       []*ResSpawn
	Assignmengts []interface{}
	Output       interface{}
	Data         string
	Cache        map[string]string
	Error        error
}
  • Messages: Messages sent by the VM to other VMs.
  • Spawns: New VM instances spawned during this call.
  • Output / Data: Execution results.
  • Cache: Key-value pairs for queryable state.
  • Error: Any error that occurred during execution.