实现虚拟机

要在 HyMatrix 网络中部署并运行自己的虚拟机（VM），开发者需要实现 HyMatrix 定义的标准化接口。这确保了所有 VM 都能被网络节点一致调用、日志化并支持可重放验证。

HyMatrix 的虚拟机被设计成永续进程的抽象模型，能够在网络中被 Spawn，接收调用消息，处理交易，并在任何时间重放或恢复，保证结果的可验证性。

接口和数据结构定义

hymx/vmm/schema/schema.go

Docker VM 实现示例

vmdocker

这些示例和定义可以帮助你快速了解如何实现一个符合 HyMatrix 标准的虚拟机。

VmSpawnFunc

首先，你需要实现一个工厂函数，用于实例化虚拟机：

type VmSpawnFunc func(Env) (Vm, error)

这个函数接收一个 Env 环境参数，并返回一个符合 HyMatrix 接口定义的 VM 实例，保证所有虚拟机都能被节点统一管理和调度。

Vm 接口

每个虚拟机必须实现以下接口：

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

Apply

这是虚拟机的核心执行方法。当节点收到一条针对该 VM 的调用消息时，就会调用 Apply。

from：调用者的标识，可以是用户的钱包地址，也可以是其他虚拟机的 ID。HyMatrix 支持跨 VM 之间的消息调度。
meta：包含交易的所有上下文信息和调用参数。

Apply 返回一个 Result 对象，包含执行的输出、生成的新消息、状态更新等。

Checkpoint

用于生成虚拟机当前状态的快照。

节点在重启、迁移、或执行日志重放时，会使用快照来减少计算开销。Checkpoint 必须返回一个可序列化的字符串，能在以后通过 Restore 方法恢复同样的状态。

如果虚拟机没有持久化状态，需要在此方法里返回错误，明确声明没有可用快照。

Restore

从 Checkpoint 的快照数据中恢复 VM 状态。

SCP 模型要求节点能从历史日志完整重放 VM 的执行过程。Restore 需要确保可以从快照恢复到一致状态，从而继续后续日志的执行。

HyMatrix 基于 SCP 模型，要求任何节点都可以重放所有历史日志以验证计算过程。

Checkpoint：生成虚拟机的快照，用于减少重放时的计算量，加速恢复。

Restore：从快照中恢复到一致的状态，继续执行后续日志。

如果你的 VM 没有持久化状态，需要在这两个方法里返回错误，以避免误用。

Close

在节点需要卸载虚拟机、释放内存或做资源清理时调用。

Meta 参数

Apply 的第二个参数 meta 是这次交易调用的完整上下文信息：

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：交易来源的消息 ID，对应 Arweave ANS-104 标准的 BundleItem ID。
Pid：当前调用的 VM 实例 ID，是 HyMatrix 中每个虚拟机实例的唯一标识。
AccId：本次调用的签名者，可以是用户钱包地址，也可以是节点的运营钱包。如果消息来自另一个 VM，AccId 为该 VM 所在节点的运营钱包。注意，AccId 不等于 Apply 中的 from，from 为消息发送者，AccId 可能不是消息的发送者。
Action：调用的函数名称，用于路由到虚拟机内的具体逻辑。
FromProcess：消息来源 VM 的 Pid，如果消息来自另一个 VM，这里记录来源。
PushedFor：消息的首次发送者。例如用户发起的原始消息，在后续多个 VM 之间产生连锁调用时，这个字段始终指向用户地址。
Sequence：来源 VM 生成的 outbox 序列号，用于保证跨 VM 消息顺序。
Nonce：HyMatrix 为本次调用生成的序列号，每个 VM 的调用消息从 0 开始严格自增，系统保证不会有间隔或重复 Nonce。
Timestamp：HyMatrix 为消息生成的时间戳。
Params：本次调用的参数键值对，是虚拟机逻辑处理的核心输入。
Data：符合 ANS-104 格式的大数据字段，用于传递二进制或较大文本数据。
Recovery 字段：用于系统内部的重放控制，开发者无需处理。

Result 返回值

Apply 的返回类型是：

type Result struct {
	Messages     []*ResMessage
	Spawns       []*ResSpawn
	Assignmengts []interface{}
	Output       interface{}
	Data         string
	Cache        map[string]string
	Error        error
}

Messages：VM 生成并发送给其他 VM 的消息。
Spawns：在本次调用中产生的新子虚拟机。
Output / Data：本次调用的输出结果。
Cache：可供用户查询的最新状态。
Error：错误信息。

接口和数据结构定义​

Docker VM 实现示例​

VmSpawnFunc​

Vm 接口​

Apply​

Checkpoint​

Restore​

Close​

Meta 参数​

Result 返回值​