Create a Subnet with a Custom Virtual Machine
This tutorial walks through the process of creating a Subnet with a custom virtual machine and deploying it locally. Although the tutorial uses a fork of Subnet-EVM as an example, you can extend its lessons to support any custom VM binary.
Fork Subnet-EVM
Instead of building a custom VM from scratch, this tutorial starts with forking Subnet-EVM.
Clone Subnet-EVM
First off, clone the Subnet-EVM repository into a directory of your choosing.
git clone https://github.com/ava-labs/subnet-evm.git
The repository cloning method used is HTTPS, but SSH can be used too:
git clone [email protected]:ava-labs/subnet-evm.git
You can find more about SSH and how to use it here.
Modify and Build Subnet-EVM
To prove you're running your custom binary and not the stock Subnet-EVM included with Avalanche-CLI, you need to modify the Subnet-EVM binary by making a minor change.
Navigate to the directory you cloned Subnet-EVM into and generate a new commit:
git commit -a --allow-empty -m "custom vm commit"
Take note of the new commit hash:
git rev-parse HEAD
c0fe6506a40da466285f37dd0d3c044f494cce32
In this case, c0fe6506a40da466285f37dd0d3c044f494cce32
.
Now build your custom binary by running
./scripts/build.sh custom_vm.bin
This command builds the binary and saves it at ./custom_vm.bin
.
Create a Custom Genesis
To start a VM, you need to provide a genesis file. Here is a basic Subnet-EVM genesis that's compatible with your custom VM.
{
"config": {
"byzantiumBlock": 0,
"chainId": 12345,
"constantinopleBlock": 0,
"eip150Block": 0,
"eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
"eip155Block": 0,
"eip158Block": 0,
"feeConfig": {
"gasLimit": 15000000,
"targetBlockRate": 2,
"minBaseFee": 25000000000,
"targetGas": 15000000,
"baseFeeChangeDenominator": 36,
"minBlockGasCost": 0,
"maxBlockGasCost": 1000000,
"blockGasCostStep": 200000
},
"homesteadBlock": 0,
"istanbulBlock": 0,
"muirGlacierBlock": 0,
"petersburgBlock": 0,
"subnetEVMTimestamp": 0
},
"nonce": "0x0",
"timestamp": "0x0",
"extraData": "0x",
"gasLimit": "0xe4e1c0",
"difficulty": "0x0",
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"coinbase": "0x0000000000000000000000000000000000000000",
"alloc": {
"8db97c7cece249c2b98bdc0226cc4c2a57bf52fc": {
"balance": "0xd3c21bcecceda1000000"
}
},
"airdropHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"airdropAmount": null,
"number": "0x0",
"gasUsed": "0x0",
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"baseFeePerGas": null
}
Open a text editor and copy the preceding text into a file called custom_genesis.json
.
Create the Subnet Configuration
Now that you have your binary, it's time to create the Subnet configuration. This tutorial uses
myCustomSubnet
as it Subnet name. Invoke the Subnet Creation Wizard with this command:
avalanche subnet create myCustomSubnet
Choose Your VM
Select Custom
for your VM.
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
Subnet-EVM
▸ Custom
Enter the Path to Your Genesis
Enter the path to the genesis file you created in this step.
✔ Enter path to custom genesis: ./custom_genesis.json
Enter the Path to Your VM Binary
Next, enter the path to your VM binary. This should be the path to the custom_evm.bin
you
created previously.
✔ Enter path to vm binary: ./custom_vm.bin
Wrapping Up
If all worked successfully, the command prints Successfully created Subnet configuration
.
Now it's time to deploy it.
Deploy the Subnet Locally
To deploy your Subnet, run
avalanche subnet deploy myCustomSubnet
Make sure to substitute the name of your Subnet if you used a different one than myCustomSubnet
.
Next, select Local Network
.
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
▸ Local Network
Fuji
Mainnet
This command boots a five node Avalanche network on your machine. It needs to download the latest versions of AvalancheGo and Subnet-EVM. The command may take a couple minutes to run.
If all works as expected, the command output should look something like this:
> avalanche subnet deploy myCustomSubnet
✔ Local Network
Deploying [myCustomSubnet] to Local Network
Backend controller started, pid: 26110, output at: /home/fm/.avalanche-cli/runs/server_20230816_131014/avalanche-cli-backend.log
Installing avalanchego-v1.10.8...
avalanchego-v1.10.8 installation successful
Node log path: /home/fm/.avalanche-cli/runs/network_20230816_131608/node<i>/logs
Starting network...
VMs ready.
Blockchain has been deployed. Wait until network acknowledges...
Network ready to use. Local network node endpoints:
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| NODE | VM | URL | ALIAS URL |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| node1 | myCustomSubnet | http://127.0.0.1:9650/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc | http://127.0.0.1:9650/ext/bc/myCustomSubnet/rpc |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| node2 | myCustomSubnet | http://127.0.0.1:9652/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc | http://127.0.0.1:9652/ext/bc/myCustomSubnet/rpc |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| node3 | myCustomSubnet | http://127.0.0.1:9654/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc | http://127.0.0.1:9654/ext/bc/myCustomSubnet/rpc |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| node4 | myCustomSubnet | http://127.0.0.1:9656/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc | http://127.0.0.1:9656/ext/bc/myCustomSubnet/rpc |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
| node5 | myCustomSubnet | http://127.0.0.1:9658/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc | http://127.0.0.1:9658/ext/bc/myCustomSubnet/rpc |
+-------+----------------+------------------------------------------------------------------------------------+-------------------------------------------------+
Browser Extension connection details (any node URL from above works):
RPC URL: http://127.0.0.1:9650/ext/bc/z9a7L6XmFYskbaHuuLFCxThByKg4xqsYYbaqT5ke6xVutDQTp/rpc
You can use the RPC URL
to connect to and interact with your Subnet.
Interact with Your Subnet
Check the Version
You can verify that your Subnet has deployed correctly by querying the local node to see what
Subnets it's running. You need to use the
getNodeVersion
endpoint. Try running this
curl command:
curl --location --request POST 'http://127.0.0.1:9650/ext/info' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc":"2.0",
"id" :1,
"method" :"info.getNodeVersion",
"params" :{
}
}'
The command returns a list of all the VMs your local node is currently running along with their versions.
{
"jsonrpc": "2.0",
"result": {
"version": "avalanche/1.10.8",
"databaseVersion": "v1.4.5",
"rpcProtocolVersion": "27",
"gitCommit": "e70a17d9d988b5067f3ef5c4a057f15ae1271ac4",
"vmVersions": {
"avm": "v1.10.8",
"evm": "v0.12.5",
"platform": "v1.10.8",
"qDMnZ895HKpRXA2wEvujJew8nNFEkvcrH5frCR9T1Suk1sREe": "v0.5.4@c0fe6506a40da466285f37dd0d3c044f494cce32"
}
},
"id": 1
}
Your results may be slightly different, but you can see that in addition to the X-Chain's
avm
, the C-Chain's evm
, and the P-Chain's platform
VM, the node is running the custom VM with
commit c0fe6506a40da466285f37dd0d3c044f494cce32
.
Check a Balance
If you used the default genesis, your custom VM has a prefunded address. You can verify its balance
with a curl command. Make sure to substitute the command's URL with the RPC URL
from your
deployment output.
curl --location --request POST 'http://127.0.0.1:9650/ext/bc/myCustomSubnet/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": [
"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc",
"latest"
],
"id": 1
}'
The command should return
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xd3c21bcecceda1000000"
}
The balance is hex encoded, so this means the address has a balance of 1 million tokens.
Note, this command doesn't work on all custom VMs, only VMs that implement the EVM's
eth_getBalance
interface.
Next Steps
You've now unlocked the ability to deploy custom VMs. Go build something cool!