Import an Avalanche L1

Context​

In previous instances, Avalanche L1s might have been manually created through transaction issuance to node APIs, whether it was done using a local node or public API nodes. However, the current focus is on integrating Avalanche-CLI.

To achieve this integration, this guide demonstrates the process of importing an Avalanche L1 to the Avalanche-CLI to enable better management of the Avalanche L1's configuration. This how-to uses the WAGMI Avalanche L1 deployed on Fuji Testnet as the example Avalanche L1.

Requirements​

For the import to work properly, you need:

• The Avalanche L1's genesis file, stored on disk

• The Avalanche L1's SubnetID

Import the Avalanche L1​

For these use cases, Avalanche-CLI now supports the import public command.

Start the import by issuing

avalanche blockchain import public

The tool prompts for the network from which to import. The invariant assumption here is that the network is a public network, either the Fuji testnet or Mainnet. In other words, importing from a local network isn't supported.

Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to import from:
  ▸ Fuji
    Mainnet

As stated earlier, this is from Fuji, so select it. As a next step, Avalanche-CLI asks for the path of the genesis file on disk:

✗ Provide the path to the genesis file: /tmp/subnet_evm.genesis.json

The wizard checks if the file at the provided path exists, refer to the checkmark at the beginning of the line:

✔ Provide the path to the genesis file: /tmp/subnetevm_genesis.json

Subsequently, the wizard asks if nodes have already been deployed for this Avalanche L1.

Use the arrow keys to navigate: ↓ ↑ → ←
? Have nodes already been deployed to this subnet?:
    Yes
  ▸ No

Nodes are Already Validating This Avalanche L1​

If nodes already have been deployed, the wizard attempts to query such a node for detailed data like the VM version. This allows the tool to skip querying GitHub (or wherever the VM's repository is hosted) for the VM's version, but rather we'll get the exact version which is actually running on the node.

For this to work, a node API URL is requested from the user, which is used for the query. This requires that the node's API IP and port are accessible from the machine running Avalanche-CLI, or the node is obviously not reachable, and thus the query times out and fails, and the tool exits. The node should also be validating the given Avalanche L1 for the import to be meaningful, otherwise, the import fails with missing information.

If the query succeeded, the wizard jumps to prompt for the Avalanche L1 ID (SubnetID).

Please provide an API URL of such a node so we can query its VM version (e.g. http://111.22.33.44:5555): http://154.42.240.119:9650
What is the ID of the subnet?: 28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY

The rest of the wizard is identical to the next section, except that there is no prompt for the VM version anymore.

Nodes Aren't Yet Validating this Avalanche L1, the Nodes API URL are Unknown, or Inaccessible (Firewalls)​

If you don't have a node's API URL at hand, or it's not reachable from the machine running Avalanche-CLI, or maybe no nodes have even been deployed yet because only the CreateSubnet transaction has been issued, for example, you can query the public APIs.

You can't know for sure what Avalanche L1 VM versions the validators are running though, therefore the tool has to prompt later. So, select No when the tool asks for deployed nodes:

Thus, at this point the wizard requests the Avalanche L1's ID, without which it can't know what to import. Remember the ID is different on different networks.

From the Testnet Avalanche L1 Explorer you can see that WAGMI's Avalanche L1 ID (SubnetID) is 28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY:

✔ What is the ID of the subnet?: 28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY

Notice the checkmark at line start, it signals that there is ID format validation.

If you hit enter now, the tool queries the public APIs for the given network, and if successful, it prints some information about the Avalanche L1, and proceeds to ask about the Avalanche L1's type:

Getting information from the Fuji network...
Retrieved information. BlockchainID: 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt, Name: WAGMI, VMID: srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
Use the arrow keys to navigate: ↓ ↑ → ←
? What's this VM's type?:
  ▸ Subnet-EVM
    Custom

Avalanche-CLI needs to know the VM type, to hit its repository and select what VM versions are available. This works automatically for Ava Labs VMs (like Subnet-EVM).

Custom VMs aren't supported yet at this point, but are next on the agenda.

As the import is for WAGMI, and you know that it's a Subnet-EVM type, select that.

The tool then queries the (GitHub) repository for available releases, and prompts the user to pick the version she wants to use:

✔ Subnet-EVM
Use the arrow keys to navigate: ↓ ↑ → ←
? Pick the version for this VM:
  ▸ v0.4.5
    v0.4.5-rc.1
    v0.4.4
    v0.4.4-rc.0
↓   v0.4.3

There is only so much the tool can help here, the Avalanche L1 manager/administrator should know what they want to use Avalanche-CLI for, how, and why they're importing the Avalanche L1.

It's crucial to understand that the correct versions are only known to the user. The latest might be usually fine, but the tool can't make assumptions about it easily. This is why it's indispensable that the wizard prompts the user, and the tool requires her to choose.

If you selected to query an actual Avalanche L1 validator, not the public APIs, in the preceding step. In such a scenario, the tool skips this picking.

✔ v0.4.5
Subnet WAGMI imported successfully

The choice finalizes the wizard, which hopefully signals that the import succeeded. If something went wrong, the error messages provide cause information. This means you can now use Avalanche-CLI to handle the imported Avalanche L1 in the accustomed way. For example, you could deploy the WAGMI Avalanche L1 locally.

For a complete description of options, flags, and the command, visit the command reference.