Skip to main content

Deploy a Permissioned Subnet on Mainnet

warning

Deploying a Subnet to Mainnet has many risks. Doing so safely requires a laser focus on security. This tutorial does its best to point out common pitfalls, but there may be other risks not discussed here.

This tutorial is an educational resource and provides no guarantees that following it results in a secure deployment. Additionally, this tutorial takes some shortcuts that aid the understanding of the deployment process at the expense of security. The text highlights these shortcuts and they shouldn't be used for a production deployment.

After managing a successful Subnet deployment on the Fuji Testnet, you're ready to deploy your Subnet on Mainnet. If you haven't done so, first Deploy a Subnet on Testnet.

This tutorial shows how to do the following on Mainnet.

  • Create a Subnet.
  • Deploy a virtual machine based on Subnet-EVM.
  • Join a node to the newly created Subnet.
  • Add a node as a validator to the Subnet.
note

All IDs in this article are for illustration purposes only. They are guaranteed to be different in your own run-through of this tutorial.

Prerequisites​

warning

Although only one validator is strictly required to run a Subnet, running with less than five validators is extremely dangerous and guarantees network downtime. Plan to support at least five validators in your production network.

Getting Your Mainnet NodeIDs​

You need to collect the NodeIDs for each of your validators. This tutorial uses these NodeIDs in several commands.

To get the NodeID of a Mainnet node, call the info.getNodeID endpoint. For example:

curl -X POST --data '{
"jsonrpc":"2.0",
"id" :1,
"method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info

The response should look something like:

{
"jsonrpc": "2.0",
"result": {
"nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD"
},
"id": 1
}

In the sample response, NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD is the NodeID. Note that the NodeID- prefix is part of the NodeID.

Setting up Your Ledger​

In the interest of security, all Avalanche-CLI Mainnet operations require the use of a connected Ledger device. You must unlock your Ledger and run the Avalanche App. See How to Use Ledger for help getting set up.

Avalanche-CLI supports the Ledger Nano X, Nano S, and Nano S Plus.

Ledger devices support TX signing for any address inside a sequence automatically generated by the device.

By default, Avalanche-CLI uses the first address of the derivation, and that address needs funds to issue the TXs to create the Subnet and add validators.

To get the first Mainnet address of your Ledger device, first make sure it is connected, unblocked, and running the Avalanche app. Then execute the key list command:

avalanche key list --ledger 0 --mainnet
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| KIND | NAME | CHAIN | ADDRESS | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j | 11 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+

The command prints the P-Chain address for Mainnet, P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j, and its balance. You should fund this address with at least 2.5 AVAX to cover TX fees. the TX fee for creating your Subnet costs 2 AVAX. Adding validators costs 0.001 AVAX each. For more details, see Fees

note

You can use the key list command to get any Ledger address in the derivation sequence by changing the index parameter from 0 to the one desired, or to a list of them (for example: 2, or 0,4,7). Also, you can ask for addresses on Fuji with the --fuji parameter, and local networks with the --local parameter.

Funding the Ledger​

A new Ledger device has no funds on the addresses it controls. You'll need to send funds to it by exporting them from C-Chain to the P-Chain using Core web connected to Core extension.

You can load the Ledger's C-Chain address in Core extension, or load in a different private key to Core extension, and then connect to Core web .

You can move test funds from the C-Chain to the P-Chain by clicking Stake on Core web , then Cross-Chain Transfer (find more details on this tutorial).

Deploy the Subnet​

With your Ledger unlocked and running the Avalanche app, run

avalanche subnet deploy testsubnet

This is going to start a new prompt series.

Use the arrow keys to navigate: ↓ ↑ β†’ ←
? Choose a network to deploy on:
Local Network
Fuji
β–Έ Mainnet

This tutorial is about deploying to Mainnet, so navigate with the arrow keys to Mainnet and hit enter.

βœ” Mainnet
Deploying [testsubnet] to Mainnet

After that, CLI shows the Mainnet Ledger address used to fund the deployment:

Ledger address: P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j

The deployment requires running a createSubnet transaction and a createBlockchain transaction, and so this first Ledger address must have the funds to issue both operations.

This tutorial creates a permissioned Subnet. As such, you must specify which P-Chain addresses can control the Subnet. These addresses are known as Control Keys. The CLI can automatically set your Ledger's address as the sole control key or the user may specify a custom list.

warning

In production Subnets, you should always use multiple control keys running in a multisig configuration. This tutorial uses a single control key for illustrative purposes only.

For instructions on controlling your Subnet with a multisig, see the Multisig Deployment Tutorial.

Configure which addresses may make changes to the subnet.
These addresses are known as your control keys. You are going to also
set how many control keys are required to make a subnet change (the threshold).
Use the arrow keys to navigate: ↓ ↑ β†’ ←
? How would you like to set your control keys?:
β–Έ Use ledger address
Custom list

For this tutorial, opt to use the first Ledger address, so enter at Use ledger address. Only this address is going to be able to add or remove validators, or create blockchains on the Subnet.

Your Subnet's control keys: [P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j]
Your subnet auth keys for chain creation: [P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j]

Next, the CLI generates a TX for creating the SubnetID and asks the user to sign it by using the Ledger.

*** Please sign subnet creation hash on the ledger device ***

This activates a Please review window on the Ledger. Navigate to the Ledger's APPROVE window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

If the Ledger doesn't have enough funds, the user may see an error message:

*** Please sign subnet creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000000 more units of asset "U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK"

If successful, the CLI next asks you to sign a chain creation TX.

Subnet has been created with ID: 2UUCLbdGqawRDND7kHjwq3zXXMPdiycG2bkyuRzYMnuTSDr6db. Now creating blockchain...
*** Please sign blockchain creation hash on the ledger device ***

This activates a Please review window on the Ledger. Navigate to the Ledger's APPROVE window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

After that, CLI creates the blockchain within the Subnet, and a summary window for the deployment appears:

+--------------------+------------------------------------------------------------------------------------+
| DEPLOYMENT RESULTS | |
+--------------------+------------------------------------------------------------------------------------+
| Chain Name | testsubnet |
+--------------------+------------------------------------------------------------------------------------+
| Subnet ID | 2UUCLbdGqawRDND7kHjwq3zXXMPdiycG2bkyuRzYMnuTSDr6db |
+--------------------+------------------------------------------------------------------------------------+
| VM ID | rW1esjm6gy4BtGvxKMpHB2M28MJGFNsqHRY9AmnchdcgeB3ii |
+--------------------+------------------------------------------------------------------------------------+
| Blockchain ID | wNoEemzDEr54Zy3iNn66yjUxXmZS9LKsZYSUciL89274mHsjG |
+--------------------+------------------------------------------------------------------------------------+
| RPC URL | http://127.0.0.1:9650/ext/bc/wNoEemzDEr54Zy3iNn66yjUxXmZS9LKsZYSUciL89274mHsjG/rpc |
+--------------------+------------------------------------------------------------------------------------+
| P-Chain TXID | wNoEemzDEr54Zy3iNn66yjUxXmZS9LKsZYSUciL89274mHsjG |
+--------------------+------------------------------------------------------------------------------------+

Well done. You have just created your own Subnet running on Mainnet. Now it's time to add your validators.

Request to Join a Subnet as a Validator​

The new Subnet created in the previous steps doesn't have any dedicated validators yet. To request permission to validate a Subnet, the following steps are required:

info

Adding a validator on a Subnet requires that the node is already a validator on the primary network, which means that your node has fully bootstrapped.

See here on how to become a validator.

First, request permission to validate by running the join command along with the Subnet name:

avalanche subnet join testsubnet

Note: Running join does not guarantee that your node is a validator of the Subnet! The owner of the Subnet must approve your node to be a validator afterwards by calling addValidator as described in the next section.

Select Mainnet​

When you join command, you are first prompted with the network selection. Choose Mainnet:

Use the arrow keys to navigate: ↓ ↑ β†’ ←
? Choose a network to validate on (this command only supports public networks):
Fuji
β–Έ Mainnet

Setup Node Automatically​

There are now two choices possible: automatic and Manual configuration. As mentioned earlier, "Automatic" attempts to edit your config file and sets up your plugin directory, while "Manual" just prints the required config to the screen. If you are running the CLI on the same box as your validator, you should run the commands in automated mode. If you don't want to run Avalanche-CLI on the same box as your validator, use the manual commands.

Select automatic.

Set Config File​

βœ” Automatic
βœ” Path to your existing config file (or where it's going to be generated): config.json

Provide a path to a config file. If this command runs on the box where your validator is running, then you could point this to the actually used config file, for example /etc/avalanchego/config.json - just make sure the tool has write access to the file. Or you could just copy the file later. In any case, the tool is going to either try to edit the existing file specified by the given path, or create a new file. Again, set write permissions.

Set Plugin Directory​

Next, provide the plugin directory. Each VM runs its own binary, called a plugin. Therefore, you need to copy your VM's plugin binary into AvalancheGo's plugin directory. This directory depends on your AvalancheGo install location.

βœ” Path to your avalanchego plugin dir (likely avalanchego/build/plugins): /home/user/go/src/github.com/ava-labs/avalanchego/build/plugins

The tool doesn't know where exactly it's located so it requires the full path. With the path given, it's going to copy the VM binary to the provided location:

βœ” Path to your avalanchego plugin dir (likely avalanchego/build/plugins): /home/user/go/src/github.com/ava-labs/avalanchego/build/pluginsβ–ˆ
VM binary written to /home/user/go/src/github.com/ava-labs/avalanchego/build/plugins/tGBrMADESojmu5Et9CpbGCrmVf9fiAJtZM5ZJ3YVDj5JTu2qw
This is going to edit your existing config file. This edit is nondestructive,
but it's always good to have a backup.
Use the arrow keys to navigate: ↓ ↑ β†’ ←
? Proceed?:
β–Έ Yes
No

Hitting Yes writes the necessary file:

βœ” Yes
The config file has been edited. To use it, make sure to start the node with the '--config-file'
option, e.g.

./build/avalanchego --config-file config.json

(using your binary location). The node has to be restarted for the changes to take effect.

Restart the Node​

It's required to restart the node.

Setup Node Manually​

By choosing "Manual" instead, the tool prints instructions. The user is going to have to follow these instructions and apply them to the node. Note that the IDs for the VM and Subnet are different for each Subnet deployment and you shouldn't copy them from this tutorial.

βœ” Manual

To setup your node, you must do two things:

1. Add your VM binary to your node's plugin directory
2. Update your node config to start validating the subnet

To add the VM to your plugin directory, copy or scp from /tmp/tGBrMADESojmu5Et9CpbGCrmVf9fiAJtZM5ZJ3YVDj5JTu2qw

If you installed avalanchego manually, your plugin directory is likely
avalanchego/build/plugins.

If you start your node from the command line WITHOUT a config file (e.g. via command
line or systemd script), add the following flag to your node's startup command:

--track-subnets=2b175hLJhGdj3CzgXENso9CmwMgejaCQXhMFzBsm8hXbH2MF7H
(if the node already has a track-subnets config, append the new value by
comma-separating it).

For example:
./build/avalanchego --network-id=Mainnet --track-subnets=2b175hLJhGdj3CzgXENso9CmwMgejaCQXhMFzBsm8hXbH2MF7H

If you start the node via a JSON config file, add this to your config file:
track-subnets: 2b175hLJhGdj3CzgXENso9CmwMgejaCQXhMFzBsm8hXbH2MF7H

TIP: Try this command with the --avalanchego-config flag pointing to your config file,
this tool is going to try to update the file automatically (make sure it can write to it).

After you update your config, you are going to need to restart your node for the changes to
take effect.

Add a Validator​

warning

If the join command isn't successfully completed before addValidator is completed, the Subnet could experience degraded performance or even halt.

Now that the node has joined the Subnet, a Subnet control key holder must call addValidator to grant the node permission to be a validator in your Subnet.

To whitelist a node as a recognized validator on the Subnet, run:

avalanche subnet addValidator testsubnet

You need to repeat this process for every validator you add to the network.

You can run the addValidator transactions from the same box that deployed the Subnet.

Submit addValidator TX to Mainnet​

First choose Mainnet as the network to add the Subnet validator to.

Use the arrow keys to navigate: ↓ ↑ β†’ ←
? Choose a network to add validator to.:
Fuji
β–Έ Mainnet

Because this operation issues a new transaction, the CLI needs the control keys to sign the operation. Because this tutorial only uses one control key in the Subnet, the process looks slightly different if you use multiple controls keys. The address needs to pay a TX fee of 0.001 AVAX.

Your subnet auth keys for add validator tx creation: [P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j]

Set NodeID​

Now enter the NodeID of the validator.

Next, we need the NodeID of the validator you want to whitelist.

Check https://docs.avax.network/apis/avalanchego/apis/info#infogetnodeid for instructions about how
to query the NodeID from your node
(Edit host IP address and port to match your deployment, if needed).
βœ” What is the NodeID of the validator you'd like to whitelist?: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lgβ–ˆ

Note, this ID is intentionally modified to prevent replication.

Set Stake Weight​

Select 30 as the stake weight. You can learn more about the stake weight parameter in addSubnetValidator under the weight section.

warning

The stake weight of all your validators should sum to at least 100.

Use the arrow keys to navigate: ↓ ↑ β†’ ←
? What stake weight would you like to assign to the validator?:
Default (20)
β–Έ Custom
βœ” What stake weight would you like to assign to the validator?: 30

Set Validation Start Time​

Next, specify when the validator is going to start validating. The time must be in the future. You can use the custom option to enter a specific date in YYYY-MM-DD HH:MM:SS format. Follow the default this time:

Use the arrow keys to navigate: ↓ ↑ β†’ ←
? Start time:
β–Έ Start in one minute
Custom

Set Validation Duration​

Finally, specify how long it's going to be validating:

βœ” Start in one minute
Use the arrow keys to navigate: ↓ ↑ β†’ ←
? How long should your validator validate for?:
β–Έ Until primary network validator expires
Custom

If you choose Custom here, you need to enter a duration, which is a time span expressed in hours. For example, say 200 days = 24 \* 200 = 4800h

βœ” How long should this validator be validating? Enter a duration, e.g. 8760h: 4800h

The CLI shows the user an actual date:

? Your validator is going to finish staking by 2023-06-10 13:07:58:
β–Έ Yes
No

Confirm if correct.

Issue the TX​

At this point the prompt series is complete and the CLI attempts the transaction:

NodeID: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
Network: Mainnet
Start time: 2022-11-22 13:07:58
End time: 2023-06-10 13:07:58
Weight: 30
Inputs complete, issuing transaction to add the provided validator information...

The CLI shows the Ledger address:

Ledger address: P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j

At this point, if the Ledger address isn't the control key for the Subnet, the user receives an error:

Error: wallet doesn't contain subnet auth keys
exit status 1

If the Ledger doesn't have enough funds, the following error message appears:

*** Please sign subnet creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000 more units of asset "U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK"

Otherwise, both the CLI and the Ledger request to sign the TX:

*** Please sign add validator hash on the ledger device ***

This activates a Please review window on the Ledger. Navigate to the Ledger's APPROVE window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

This might take a couple of seconds. After, it prints:

Transaction successful, transaction ID: r3tJ4Wr2CWA8AaticmFrKdKgAs5AhW2wwWTaQHRBZKwJhsXzb

This means the node is now a validator on the given Subnet on Mainnet! However, your work isn't complete. You must finish the Request to Join a Subnet as a Validator section otherwise your Subnet risks downtime.

You can get the P-Chain TX id information on Avalanche Explorer

Subnet Export​

Because you need to setup multiple validators on multiple different machines, you need to export your Subnet's configuration and import it on each validator.

avalanche subnet export testsubnet
βœ” Enter file path to write export data to: /tmp/testsubnet-export.dat

The file is in text format and you shouldn't change it. You can use it to import the configuration on a different machine.

Subnet Import​

To import a VM configuration, move the file you exported in the previous section to your desired machine and issue the import command with the path to the file.

avalanche subnet import /tmp/testsubnet-export.dat
Subnet imported successfully

After this the whole Subnet configuration should be available on the target machine:

avalanche subnet list
+---------------+---------------+----------+-----------+----------+
| SUBNET | CHAIN | CHAIN ID | TYPE | DEPLOYED |
+---------------+---------------+----------+-----------+----------+
| testsubnet | testsubnet | 3333 | SubnetEVM | No |
+---------------+---------------+----------+-----------+----------+

Going Live​

Once all of your validators have joined the network, you are ready to issue transactions to your Subnet.

For the safety of your validators, you should setup dedicated API nodes to process transactions, but for test purposes, you can issue transactions directly to one of your validator's RPC interface.

Was this page helpful?