Skip to main content

Spawn and Use Virtual Machines

After completing Mount, Build, and Module upload, you can officially bring your virtual machine online on the HyMatrix network and interact with it using the official SDK. This guide is divided into two parts: how to spawn a virtual machine instance, and how to use the HyMatrix SDK to send messages—such as token transfers or node staking.

Spawning a VM​

In HyMatrix, starting a virtual machine is called Spawn. A user or developer simply sends a Process type transaction, specifying the Module ID (the VM template previously uploaded to Arweave) and the Scheduler (the target node for execution).

With the official Golang SDK, spawning a VM is very straightforward. Here's a minimal Go example:

package main

import (
	"fmt"

	"github.com/hymatrix/hymx/sdk"
	goarSchema "github.com/permadao/goar/schema"
)

func main() {
	// Initialize the SDK client
	s := sdk.New("http://127.0.0.1:8080", "../test_keyfile.json")

	// Call the Spawn method
	res, err := s.Spawn(
		"LSjhdzBjyWuyUPe-g6PUzt8t1PUlw2FZ9SM3_hCh2Is", // Module ID
		"0x972AeD684D6f817e1b58AF70933dF1b4a75bfA51",  // Scheduler (Node AccId)
		[]goarSchema.Tag{},
	)
	fmt.Printf("res: %#v, err: %v\n", res, err)
}

Key parameters:

  • Module ID: The item.Id obtained after uploading the Module to Arweave. Uniquely identifies your VM template.
  • Scheduler: The AccId of the node you want to schedule the VM on (can be your own node or another).
  • Tags: Optional metadata.

After calling this, a Process transaction is created on-chain, and the node will load and instantiate the VM according to the Module ID. All logs are verifiable and replayable.

Using the HyMatrix SDK​

The official Golang SDK supports more than just spawning—it also allows calling any deployed VM. This includes token transfers (e.g. tAX) or on-chain operations like node registration and staking.

Below are two common examples:

1️⃣ tAX Token Transfer​

package main

import (
	"math/big"

	"github.com/hymatrix/hymx/sdk"
	"github.com/permadao/goar/schema"
)

func transfer(from *sdk.SDK, token, to string, amt *big.Int) error {
	_, err := from.SendMessageAndWait(token, "",
		[]schema.Tag{
			{Name: "Action", Value: "Transfer"},
			{Name: "Recipient", Value: to},
			{Name: "Quantity", Value: amt.String()},
		},
	)
	return err
}

Explanation:

  • token is the VM address for the tAX token.
  • to is the recipient’s address.
  • amt is the amount to transfer.

This will create a standard, verifiable transaction on-chain.

2️⃣ Node Staking​

func stake(from *sdk.SDK, amt *big.Int) {
	info, _ := from.Client.Info()
	from.SendMessage(info.Hm, "",
		[]schema.Tag{
			{Name: "Action", Value: "Stake"},
			{Name: "Quantity", Value: amt.String()},

			{Name: "Registry", Value: info.Registry},
			{Name: "Acc-Id", Value: from.GetAddress()},
			{Name: "Name", Value: "stakeNode"},
			{Name: "Desc", Value: "This is stake node"},
			{Name: "URL", Value: "http://127.0.0.1:8081"},
		},
	)
}

This shows how to call HyMatrix’s registration/staking interface, writing your node info on-chain and locking tokens to participate in computation and earn rewards.

With these standardized call patterns, developers can easily build dApp frontends or backend services that interact with any virtual machine on HyMatrix—for spawning, transferring, staking, or calling custom logic in a decentralized and verifiable way.