EVM Subchains

Introduction

Velas EVM Subchains is a solution that allows using Velas as infrastructure for your custom EVM compatible chain. Each EVM Subchain is isolated, have full Ethereum JSON-RPC API (same as in Velas EVM Chain), but uses custom token as its "main" token.

For custom chain end-users, fees are paid with their "main" token, but in Velas processing cost is payed with Native VLX token, so administrator of the chain responsible for paying fees with VLX for custom chain end-users.

Velas provides a way for administrator to create subchain, manage fee, and export subchain state if needed. The administrator is also responsible to host an EVM Bridge - a thin proxy that maps Ethereum calls to real api calls, and route them to the nodes.

Prerequisite

In order to be abble to deploy new subchain one should have velas CLI and subchain-manager tool installed. These tools are available in our release packages or can be built manualy.

Download from release

Grab latest release from Velas Releases for your platform and put it in appropriate path. For more info check Velas CLI Documentation

Building from source

Binary for some platforms are not available in Velas Releases, but still supported by Velas.

If you couldn't find binary for your platform on release page, you can follow instructions to build it from source code.

1. Clone repository

   git clone https://github.com/velas/velas-chain
   cd velas-chain

2. Select branch or tag that support Velas Subchains (needed for alpha testers)

   git switch zeta

3. Install required dependencies

   For Debian based Distros:

   sudo apt-get update
   sudo apt-get install libssl-dev libudev-dev pkg-config zlib1g-dev llvm clang make cmake protobuf-compiler

   For Fedora:

   sudo dnf install openssl-devel systemd-devel pkg-config zlib-devel llvm clang cmake make protobuf-devel protobuf-compiler perl-core

   For MacOS:

   sudo brew install openssl pkg-config zlib llvm clang cmake make protobuf protobuf-compiler perl-core

4. Install Rust

   curl https://sh.rustup.rs -sSf | sh
   source $HOME/.cargo/env
   rustup component add rustfmt
   cargo --version

5. Build packages

   cargo build --release -p solana-cli -p subchain-manager -p evm-bridge -p velas-keygen
   

   The output files can be found at ./target/release

   ./target/release/velas --version
   ./target/release/evm-bridge --version
   # Since subchain manager is TUI you can't request it's version but you can check that it exist.
   ls -la ./target/release/subchain-manager

In the next chapters we will use subchain-manager and velas cli executables directly without providing a path. For manual builds you need to put binaries somewhere in your $PATH. Or prepend all commands with ./target/release/ (without space). Or you can update $PATH environment variable to also search for binnaries in your ./target/release folder, by executing command:

export PATH=$PATH:$(pwd)/target/release

Generating key and get VLX to deploy (for testing purposes)

The guide assumes that one have native VLX account with enough tokens to deploy EVM Subchain. Currenty, the cost of EVM Subchain deployment is 1,000,000 VLX

If not, and one uses devnet for testing. One should generate keys and request an airdrop

velas-keygen new
velas -u devnet airdrop 1000200

Setting Up Subchain

First, you need to generate a config.

Run subchain-manager in TUI mode

subchain-manager
#TODO: export config from geth init 

And it will guide you through the process.

An example of the process could look like this:

❯ subchain-manager

> This program helps to create and manage subchains. It allows create config for new subchain, that can be later used to deploy subchain, and other infrastrucutre (like bridges and explorers). Generate a new config
> Choose a name for the chain: My New super chain
> Pick a name for the token: MNSC
> Select a Chain ID (should be unique, and start with 0x56): 0x5623
> Hardfork version: Istanbul hardfork (currently only available).
> Store config in file: my-config.toml
> Minting address: 0x1a64…14f1
> Balance: 12312300000
? One more minting address (esc to skip): <canceled>
> Select a token symbol: $
> Provide RPC URL for future tooling: foo.bar.baz

At the end one get config (in case of example my-config.toml), that can be used to deploy custom chain.

The next step is to deploy subchain.

The config can be deployed using same subchain-manager TUI mode, or for better scripting, in CLI mode.

./target/release/subchain-manager create-and-deploy --config-file my-config.toml --velas-rpc https://api.devnet.velas.com

checkout clusters to get list of available Velas clusters and their JSON-RPC addresses.

At this point custom EVM Subchain is successfully deployed, but in order to be able to process EVM transactions, you should fund Native VLX Account of newly created EVM Subchain with VLX tokens to cover subchain transaction fees.

1. find Native Velas Account which handles EVM Subchain State

   subchain-manager get-subchain-address --config-file my-config.toml
   EVM subchain state is stored in: FTBiU6qAupE7SqmFEXW8tX3tdhNLxnRwnX9LamCJGLPw

2. transfer some Native VLX tokens to that account

   velas -u devnet transfer FTBiU6qAupE7SqmFEXW8tX3tdhNLxnRwnX9LamCJGLPw 100

Starting EVM Bridge

The final step is to start thin proxy that would provide eth_* JSON-RPC API for EVM Subchain end user.

evm-bridge /home/$USER/.config/velas/id.json http://api.devnet.velas.com 127.0.0.1:8545 <CHAIN_ID> --subchain --no-simulate --borsh-encoding

Don't forget to replace <CHAIN_ID> with chain id of your EVM Subchain.

EVM Bridge can easily scale horizontally, but it contains local mempool, so make sure that your load balancer is able to track users and route requests to correct evm-bridge instance.