Set up validator node
This section will take your through all the steps to configure your node as a validator and join an existing network.
All the following commands will use an optional --home flag. This flag allows you to specify a custom home for the configuration, state, and cache of your Vega node. The flag is not mandatory and a default path will be chosen if not specified.
It's recommended that you use different folders for your Vega and Tendermint homes. Keep track of which home you're referring to as you progress.
The XDG Base Directory standard is use to create the path, see: XDG Base Directory spec.
You can list all the path used by your Vega installation by using the following command:
vega paths list
Generate the configurations
Start by generating a Vega validator node configuration.
You will be asked for a passphrase for your node wallet.
(If writing automation, you may want to use --nodewallet-passphrase-file, which allows you to specify a file containing the passphrase.)
Make sure to save this passphrase as it allows you to unlock the node wallet. This command should output the path of the main configuration file. Feel free to open and change settings if needed. (Below you'll find more info on mandatory settings):
vega init --home="path/to/home/root" validator
Then generate the Tendermint node configuration. For convenience, the Vega toolchain also embeds Tendermint. You can run all Tendermint subcommands using this Vega command:
vega tm
Generate the configuration and Tendermint keys using the following command:
vega tm --home="path/to/tendermint/home/root" init validator
Back up and securely store your Tendermint node and validator keys.
Set up the node wallet
Each validator node requires two cryptographic wallets to operate properly:
- Ethereum wallet: Used to sign transactions going through the ERC20 bridge
- Vega wallet: Used to sign transaction sent by validators in the Vega network
The public key of the Tendermint node also needs to be saved in the node wallet.
All this information needs to be checked in properly before starting the node. When the network starts or a node is added to the validator set, this information will be checked against the transaction used to register the node on the network. Any incorrect set-up will stop the node from joining the network.
For the following node wallet command, you will be prompted to input your node wallet passphrase (that you created when you initialised Vega). If you cannot run these command interactively you can specify a file containing the passphrase using the following flag: --passphrase-file=.
Tendermint validator public key
To save the Tendermint validator public key in your node wallet, use the following command:
vega nodewallet import --chain=tendermint --home=path/to/home --tendermint-pubkey="YOUR_TENDERMINT_PUBKEY"
If you are using the keys generated by Tendermint, you can find the public key at the following path: path/to/tendermint/config/priv_validator_key.json.
If your Tendermint node is set up to use tmkms, then refer to the documentation to get your public key.
If you are not using tmkms (e.g: the default software keys generated by tendermint, run the following command instead:
vega nodewallet import --chain=tendermint --home=path/to/home --tendermint-home=path/to/tendermint
This will read the Tendermint keys from the configuration path, and set up your node wallet properly.
Ethereum wallet
Vega supports two types of Ethereum wallet: you can either register a wallet available from a clef instance or import a keystore file (e.g: create with geth account).
Using clef
To set up your clef instance please refer to the clef documentation.
Set the address of your clef instance in the Vega configuration (path/to/home/config/node/config.toml):
[NodeWallet]
Level = "Info"
[NodeWallet.ETH]
Level = "Info"
Address = ""
ClefAddress = "http://your.clef.instance.network:3334"
Alternatively you can run the following command and specify the flag: --eth.clef-address="http://your.clef.instance.network:3334"
Then run the following command:
vega nodewallet import --chain=ethereum --home=path/to/home --clef-account-address="0xYOUR_WALLET_ADDRESS"
Using a keystore account file
You can either import an existing keystore or create a new one. (Learn how to create a keystore using geth)
Import an existing keystore using the following command:
vega nodewallet import --chain=ethereum --home="path/to/home" --wallet-passphrase-file="file/containing/account/passphrase" --wallet-path="path/to/wallet"
Or use the following command to create a new keystore and save it in the node wallet:
vega nodewallet generate --chain=ethereum --home="path/to/home" --wallet-passphrase-file="file/containing/account/passphrase"
Vega wallet
We recommend you use an isolated key. Read the guide on how to isolate Vega wallet keys.
Give the node access to the key using the following command:
vega nodewallet import --chain=vega --home="path/to/vega-home" --wallet-passphrase-file="file/containing/account/passphrase" --wallet-path="path/to/wallet"
Alternatively you can create a new Vega wallet and save it in the node wallet:
vega nodewallet generate --chain=vega --home="path/to/home" --wallet-passphrase-file="file/containing/account/passphrase"
Save your wallet mnemonic somewhere secure, as it is the only way to restore your wallet.
You can verify the information saved in your node wallet using the following command:
vega nodewallet --home="path/to/home/" show
Update config files
Modify Vega config.toml
Each Vega validator node needs to be connected to an Ethereum archive node (not a full node). The core software connects to the eth_getLogs endpoint, which is only available on archive nodes. This allows the Vega node to verify that an event happened on Ethereum (e.g: a deposit or a withdrawal).
Modify the following config in path/to/home/config/node/config.toml:
[NodeWallet]
Level = "Info"
[NodeWallet.ETH]
Level = "Info"
Address = "http://ADD_YOUR_ETH_ARCHIVE_NODE_RPC_ENDOINT.here/rpc"
ClefAddress = ""
Modify tendermint config.toml
Vega being a decentralised network, you will need an entry point to join it. This is done by connecting to one or more nodes in the network when you start your node.
This step needs to be done manually. You will first need to reach out to another node operator in the network, such as through the validator Discord channel, to get their node ID and the address of their node.
Use that node information to inform the persistent peers. The persistent peers field is a list of Node IDs and addresses of nodes separated by a @ character.
Update the tendermint config located at YOUR_TENDERMINT_HOME/config/config.toml and set the persistent_peers field under the [p2p] section.
Here's an example:
[p2p]
persistent_peers = "55b8ac477ddd6c0c9bae411dfa6ebfb46e7b4022@veganodeoperator.com:26656,2d1bbf1229bd7f8e57e89c61346ab6928d61881b@127.0.0.1:26656"
Under Mempool Configuration Option, ensure that broadcast = true.
Then, review the remaining config and modify as required for your setup. For example you may want to update the moniker field.
Update Tendermint genesis
To start successfully, tendermint needs the genesis file from the network you will be trying to join. This file need to be located in YOUR_TENDERMINT_HOME/config/genesis.json. Download the genesis file and use it to replace the genesis in your config.
You can find genesis files in the networks repository for the mainnet network.
To join mainnet you will need the following genesis file.
Start your node
Start the node and synchronise with the network by replaying the full chain history to get up-to-date. It may take several hours, or up to a few days, (depending on chain size and your node's infrastructure) to catch up.
To replay all history from genesis, set a genesis file when starting the node with the following commands:
vega node --home="path/to/vega-home" --nodewallet-passphrase-file="YOUR_PASSPHRASE_FILE_PATH"
vega tm start --home="path/to/tendermint-home"
To verify that your node is connected and verifying blocks, you can query https://YOUR_NODE_DOMAIN/statistics endpoint.
While your node is catching up, you can associate the tokens you need for self-stake to your node's Vega public key. Then after your node is synchronised and you have tokens available, announce the node to the network and then the community.
Associate tokens to your Vega key
Before you announce your node, you will need to have 👀3000 tokens Vega associated to your Vega key, in order to self-stake (below).
The tokens that you want to use for self-staking must be available on an Ethereum wallet, and then associated to the same Vega public key you used to set up the node.
You can do this by importing the Vega Wallet you created for your node wallet, onto your local computer using the Vega Wallet recovery phrase.
Once you have tokens, connect your Ethereum wallet and your Vega Wallet, and associate the tokens to your Vega public key using the governance dApp ↗. Below, you'll self-nominate (self-stake) to your node.
The association will need to be confirmed by both the Ethereum and Vega blockchains, and may take some time.
Announce node on-chain
Use your Ethereum key to announce your node to the network, once your VEGA tokens are available in your Vega wallet.
You'll need to know the current epoch ↗, and have the following data to hand: the URL for your validator website, and URL for the avatar that will show up on the governance dApp next to your node name.
vega announce_node --home="YOUR_VEGA_HOME_PATH" --passphrase-file="YOUR_PASSPHRASE_FILE_PATH" --info-url="YOUR_VALIDATOR_URL" --avatar-url="YOUR_AVATAR_URL" --country="UK" --name="YOUR_NODE_NAME" --from-epoch="CURRENT_EPOCH"
Nominate your node
To move on to self-staking, wait until you see your node on the validator list as a pending validator. Query the API at https://api.vega.xyz/epochs or check the governance dApp.
Then, associate your tokens and nominate your node using the governance dApp ↗ or by interacting directly with the smart contract.
Your pending validator node will need to see Ethereum bridge events on the network and send heartbeats before moving on to the next step.
Submit signature bundle
In the epoch after you announced your node, and once your pending validator has seen Ethereum bridge events and sent heartbeats, your node will be added to a signature bundle built by the network: proof from the network that your node can be added to the multisigControl signers.
You'll need your node ID, which you can find on the latest epoch's validator list.
Ensure that you have set up your data node and chosen web UI port.
Open your data node's gRPC web UI using your node domain to get the signature bundle:
- Service name:
datanode.api.v2.TradingDataService - Method name:
erc20multisigsigneraddedbundle
Use the data from the bundle with the MultiSigControl smart contract. It must be executed from the node's Ethereum wallet.
Once the signature bundle is accepted, your node will be able to emit signatures to control withdrawals from the bridge.
You need to add your node as a signer by the end of the epoch that the signature is emitted in.
Announce node off-chain
Create a validator profile on the forum ↗ describing the experience you have, security practices and policies, how you will ensure maximum uptime, how you'll meet suitable performance standards, your communication channels for questions and the role you intend to take in Vega's governance.
Share your profile with the community, for example in the Validators Discord channel ↗, to attract staker delegation.